libmongocrypt
|
#include "mongocrypt-export.h"
#include "mongocrypt-compat.h"
#include "mongocrypt-config.h"
Go to the source code of this file.
Macros | |
#define | MONGOCRYPT_VERSION "1.0.1" |
Typedefs | |
typedef struct _mongocrypt_binary_t | mongocrypt_binary_t |
typedef struct _mongocrypt_status_t | mongocrypt_status_t |
typedef void(* | mongocrypt_log_fn_t) (mongocrypt_log_level_t level, const char *message, uint32_t message_len, void *ctx) |
typedef struct _mongocrypt_t | mongocrypt_t |
typedef struct _mongocrypt_ctx_t | mongocrypt_ctx_t |
typedef struct _mongocrypt_kms_ctx_t | mongocrypt_kms_ctx_t |
typedef bool(* | mongocrypt_crypto_fn) (void *ctx, mongocrypt_binary_t *key, mongocrypt_binary_t *iv, mongocrypt_binary_t *in, mongocrypt_binary_t *out, uint32_t *bytes_written, mongocrypt_status_t *status) |
typedef bool(* | mongocrypt_hmac_fn) (void *ctx, mongocrypt_binary_t *key, mongocrypt_binary_t *in, mongocrypt_binary_t *out, mongocrypt_status_t *status) |
typedef bool(* | mongocrypt_hash_fn) (void *ctx, mongocrypt_binary_t *in, mongocrypt_binary_t *out, mongocrypt_status_t *status) |
typedef bool(* | mongocrypt_random_fn) (void *ctx, mongocrypt_binary_t *out, uint32_t count, mongocrypt_status_t *status) |
Enumerations | |
enum | mongocrypt_status_type_t { MONGOCRYPT_STATUS_OK = 0, MONGOCRYPT_STATUS_ERROR_CLIENT = 1, MONGOCRYPT_STATUS_ERROR_KMS = 2 } |
enum | mongocrypt_log_level_t { MONGOCRYPT_LOG_LEVEL_FATAL = 0, MONGOCRYPT_LOG_LEVEL_ERROR = 1, MONGOCRYPT_LOG_LEVEL_WARNING = 2, MONGOCRYPT_LOG_LEVEL_INFO = 3, MONGOCRYPT_LOG_LEVEL_TRACE = 4 } |
enum | mongocrypt_ctx_state_t { MONGOCRYPT_CTX_ERROR = 0, MONGOCRYPT_CTX_NEED_MONGO_COLLINFO = 1, MONGOCRYPT_CTX_NEED_MONGO_MARKINGS = 2, MONGOCRYPT_CTX_NEED_MONGO_KEYS = 3, MONGOCRYPT_CTX_NEED_KMS = 4, MONGOCRYPT_CTX_READY = 5, MONGOCRYPT_CTX_DONE = 6 } |
The top-level handle to libmongocrypt.
#define MONGOCRYPT_VERSION "1.0.1" |
The version string describing libmongocrypt. Has the form x.y.z-
+<date>+git<sha>.
typedef struct _mongocrypt_binary_t mongocrypt_binary_t |
A non-owning view of a byte buffer.
When constructing a mongocrypt_binary_t it is the responsibility of the caller to maintain the lifetime of the viewed data. However, all public functions that take a mongocrypt_binary_t as an argument will make a copy of the viewed data. For example, the following is valid:
Functions with a mongocrypt_binary_t* out guarantee the lifetime of the viewed data to live as long as the parent object. For example, mongocrypt_ctx_mongo_op guarantees that the viewed data of mongocrypt_binary_t is valid until the parent ctx is destroyed with mongocrypt_ctx_destroy.
typedef bool(* mongocrypt_crypto_fn) (void *ctx, mongocrypt_binary_t *key, mongocrypt_binary_t *iv, mongocrypt_binary_t *in, mongocrypt_binary_t *out, uint32_t *bytes_written, mongocrypt_status_t *status) |
An crypto AES-256-CBC encrypt or decrypt function.
Note, in
is already padded. Encrypt with padding disabled.
[in] | ctx | An optional context object that may have been set when hooks were enabled. |
[in] | key | An encryption key (32 bytes for AES_256). |
[in] | iv | An initialization vector (16 bytes for AES_256); |
[in] | in | The input. |
[out] | out | A preallocated byte array for the output. See mongocrypt_binary_data. |
[out] | bytes_written | Set this to the number of bytes written to out . |
[out] | status | An optional status to pass error messages. See mongocrypt_status_set. |
status
with a message indiciating the error using mongocrypt_status_ste. typedef struct _mongocrypt_ctx_t mongocrypt_ctx_t |
Manages the state machine for encryption or decryption.
typedef bool(* mongocrypt_hash_fn) (void *ctx, mongocrypt_binary_t *in, mongocrypt_binary_t *out, mongocrypt_status_t *status) |
A crypto hash (SHA-256) function.
[in] | ctx | An optional context object that may have been set when hooks were enabled. |
[in] | in | The input. |
[out] | out | A preallocated byte array for the output. See mongocrypt_binary_data. |
[out] | status | An optional status to pass error messages. See mongocrypt_status_set. |
status
with a message indiciating the error using mongocrypt_status_ste. typedef bool(* mongocrypt_hmac_fn) (void *ctx, mongocrypt_binary_t *key, mongocrypt_binary_t *in, mongocrypt_binary_t *out, mongocrypt_status_t *status) |
A crypto HMAC SHA-512 or SHA-256 function.
[in] | ctx | An optional context object that may have been set when hooks were enabled. |
[in] | key | An encryption key (32 bytes for HMAC_SHA512). |
[in] | in | The input. |
[out] | out | A preallocated byte array for the output. See mongocrypt_binary_data. |
[out] | status | An optional status to pass error messages. See mongocrypt_status_set. |
status
with a message indiciating the error using mongocrypt_status_ste. typedef struct _mongocrypt_kms_ctx_t mongocrypt_kms_ctx_t |
Manages a single KMS HTTP request/response.
typedef void(* mongocrypt_log_fn_t) (mongocrypt_log_level_t level, const char *message, uint32_t message_len, void *ctx) |
A log callback function. Set a custom log callback with mongocrypt_setopt_log_handler.
[in] | message | A NULL terminated message. |
[in] | message_len | The length of message. |
[in] | ctx | A context provided by the caller of mongocrypt_setopt_log_handler. |
typedef bool(* mongocrypt_random_fn) (void *ctx, mongocrypt_binary_t *out, uint32_t count, mongocrypt_status_t *status) |
A crypto secure random function.
[in] | ctx | An optional context object that may have been set when hooks were enabled. |
[out] | out | A preallocated byte array for the output. See mongocrypt_binary_data. |
[in] | count | The number of random bytes requested. |
[out] | status | An optional status to pass error messages. See mongocrypt_status_set. |
status
with a message indiciating the error using mongocrypt_status_ste. typedef struct _mongocrypt_status_t mongocrypt_status_t |
Indicates success or contains error information.
Functions like mongocrypt_ctx_encrypt_init follow a pattern to expose a status. A boolean is returned. True indicates success, and false indicates failure. On failure a status on the handle is set, and is accessible with a corresponding (handle)_status function. E.g. mongocrypt_ctx_status.
typedef struct _mongocrypt_t mongocrypt_t |
The top-level handle to libmongocrypt.
Create a mongocrypt_t handle to perform operations within libmongocrypt: encryption, decryption, registering log callbacks, etc.
Functions on a mongocrypt_t are thread safe, though functions on derived handles (e.g. mongocrypt_ctx_t) are not and must be owned by a single thread. See each handle's documentation for thread-safety considerations.
Multiple mongocrypt_t handles may be created.
Indicates the state of the mongocrypt_ctx_t. Each state requires different handling. See the integration guide for information on what to do for each state.
Indicates the type of log message.
Indicates the type of error.
MONGOCRYPT_EXPORT uint8_t* mongocrypt_binary_data | ( | const mongocrypt_binary_t * | binary | ) |
Get a pointer to the viewed data.
[in] | binary | The mongocrypt_binary_t. |
MONGOCRYPT_EXPORT void mongocrypt_binary_destroy | ( | mongocrypt_binary_t * | binary | ) |
Free the mongocrypt_binary_t.
This does not free the viewed data.
[in] | binary | The mongocrypt_binary_t destroy. |
MONGOCRYPT_EXPORT uint32_t mongocrypt_binary_len | ( | const mongocrypt_binary_t * | binary | ) |
Get the length of the viewed data.
[in] | binary | The mongocrypt_binary_t. |
MONGOCRYPT_EXPORT mongocrypt_binary_t* mongocrypt_binary_new | ( | void | ) |
Create a new non-owning view of a buffer (data + length).
Use this to create a mongocrypt_binary_t used for output parameters.
MONGOCRYPT_EXPORT mongocrypt_binary_t* mongocrypt_binary_new_from_data | ( | uint8_t * | data, |
uint32_t | len | ||
) |
Create a new non-owning view of a buffer (data + length).
[in] | data | A pointer to an array of bytes. This data is not copied. data must outlive the binary object. |
[in] | len | The length of the data byte array. |
MONGOCRYPT_EXPORT bool mongocrypt_ctx_datakey_init | ( | mongocrypt_ctx_t * | ctx | ) |
Initialize a context to create a data key.
Associated options:
[in] | ctx | The mongocrypt_ctx_t object. |
MONGOCRYPT_EXPORT bool mongocrypt_ctx_decrypt_init | ( | mongocrypt_ctx_t * | ctx, |
mongocrypt_binary_t * | doc | ||
) |
Initialize a context for decryption.
This method expects the passed-in BSON to be of the form: { "v" : BSON value to encrypt }
[in] | ctx | The mongocrypt_ctx_t object. |
[in] | doc | The document to be decrypted. The viewed data is copied. It is valid to destroy doc with mongocrypt_binary_destroy immediately after. |
MONGOCRYPT_EXPORT void mongocrypt_ctx_destroy | ( | mongocrypt_ctx_t * | ctx | ) |
Destroy and free all memory associated with a mongocrypt_ctx_t.
[in] | ctx | A mongocrypt_ctx_t. |
MONGOCRYPT_EXPORT bool mongocrypt_ctx_encrypt_init | ( | mongocrypt_ctx_t * | ctx, |
const char * | db, | ||
int32_t | db_len, | ||
mongocrypt_binary_t * | cmd | ||
) |
Initialize a context for encryption.
[in] | ctx | The mongocrypt_ctx_t object. |
[in] | db | The database name. |
[in] | db_len | The byte length of db . Pass -1 to determine the string length with strlen (must be NULL terminated). |
[in] | cmd | The BSON command to be encrypted. The viewed data is copied. It is valid to destroy cmd with mongocrypt_binary_destroy immediately after. |
MONGOCRYPT_EXPORT bool mongocrypt_ctx_explicit_decrypt_init | ( | mongocrypt_ctx_t * | ctx, |
mongocrypt_binary_t * | msg | ||
) |
Explicit helper method to decrypt a single BSON object.
[in] | ctx | A mongocrypt_ctx_t. |
[in] | msg | A mongocrypt_binary_t the encrypted BSON. The viewed data is copied. It is valid to destroy msg with mongocrypt_binary_destroy immediately after. |
MONGOCRYPT_EXPORT bool mongocrypt_ctx_explicit_encrypt_init | ( | mongocrypt_ctx_t * | ctx, |
mongocrypt_binary_t * | msg | ||
) |
Explicit helper method to encrypt a single BSON object. Contexts created for explicit encryption will not go through mongocryptd.
To specify a key_id, algorithm, or iv to use, please use the corresponding mongocrypt_setopt methods before calling this.
This method expects the passed-in BSON to be of the form: { "v" : BSON value to encrypt }
Associated options:
[in] | ctx | A mongocrypt_ctx_t. |
[in] | msg | A mongocrypt_binary_t the plaintext BSON value. The viewed data is copied. It is valid to destroy msg with mongocrypt_binary_destroy immediately after. |
MONGOCRYPT_EXPORT bool mongocrypt_ctx_finalize | ( | mongocrypt_ctx_t * | ctx, |
mongocrypt_binary_t * | out | ||
) |
Perform the final encryption or decryption.
[in] | ctx | A mongocrypt_ctx_t. |
[out] | out | The final BSON. The data viewed by out is guaranteed to be valid until ctx is destroyed with mongocrypt_ctx_destroy. The meaning of this BSON depends on the type of ctx . |
If ctx
was initialized with mongocrypt_ctx_encrypt_init, then this BSON is the (possibly) encrypted command to send to the server.
If ctx
was initialized with mongocrypt_ctx_decrypt_init, then this BSON is the decrypted result to return to the user.
If ctx
was initialized with mongocrypt_ctx_explicit_encrypt_init, then this BSON has the form { "v": (BSON binary) } where the BSON binary is the resulting encrypted value.
If ctx
was initialized with mongocrypt_ctx_explicit_decrypt_init, then this BSON has the form { "v": (BSON value) } where the BSON value is the resulting decrypted value.
If ctx
was initialized with mongocrypt_ctx_datakey_init, then this BSON is the document containing the new data key to be inserted into the key vault collection.
MONGOCRYPT_EXPORT bool mongocrypt_ctx_kms_done | ( | mongocrypt_ctx_t * | ctx | ) |
Call when done handling all KMS contexts.
[in] | ctx | The mongocrypt_ctx_t object. |
MONGOCRYPT_EXPORT bool mongocrypt_ctx_mongo_done | ( | mongocrypt_ctx_t * | ctx | ) |
Call when done feeding the reply (or replies) back to the context.
[in] | ctx | The mongocrypt_ctx_t object. |
MONGOCRYPT_EXPORT bool mongocrypt_ctx_mongo_feed | ( | mongocrypt_ctx_t * | ctx, |
mongocrypt_binary_t * | reply | ||
) |
Feed a BSON reply or result when mongocrypt_ctx_t is in MONGOCRYPT_CTX_NEED_MONGO_* states. This may be called multiple times depending on the operation.
reply is a BSON document result being fed back for this operation.
[in] | ctx | The mongocrypt_ctx_t object. |
[in] | reply | A BSON document for the MongoDB operation. The viewed data is copied. It is valid to destroy reply with mongocrypt_binary_destroy immediately after. |
MONGOCRYPT_EXPORT bool mongocrypt_ctx_mongo_op | ( | mongocrypt_ctx_t * | ctx, |
mongocrypt_binary_t * | op_bson | ||
) |
Get BSON necessary to run the mongo operation when mongocrypt_ctx_t is in MONGOCRYPT_CTX_NEED_MONGO_* states.
op_bson
is a BSON document to be used for the operation.
The lifetime of op_bson
is tied to the lifetime of ctx
. It is valid until mongocrypt_ctx_destroy is called.
[in] | ctx | The mongocrypt_ctx_t object. |
[out] | op_bson | A BSON document for the MongoDB operation. The data viewed by op_bson is guaranteed to be valid until ctx is destroyed with mongocrypt_ctx_destroy. |
MONGOCRYPT_EXPORT mongocrypt_ctx_t* mongocrypt_ctx_new | ( | mongocrypt_t * | crypt | ) |
Create a new uninitialized mongocrypt_ctx_t.
Initialize the context with functions like mongocrypt_ctx_encrypt_init. When done, destroy it with mongocrypt_ctx_destroy.
[in] | crypt | The mongocrypt_t object. |
MONGOCRYPT_EXPORT mongocrypt_kms_ctx_t* mongocrypt_ctx_next_kms_ctx | ( | mongocrypt_ctx_t * | ctx | ) |
Get the next KMS handle.
Multiple KMS handles may be retrieved at once. Drivers may do this to fan out multiple concurrent KMS HTTP requests. Feeding multiple KMS requests is thread-safe.
If KMS handles are being handled synchronously, the driver can reuse the same TLS socket to send HTTP requests and receive responses.
[in] | ctx | A mongocrypt_ctx_t. |
MONGOCRYPT_EXPORT bool mongocrypt_ctx_setopt_algorithm | ( | mongocrypt_ctx_t * | ctx, |
const char * | algorithm, | ||
int | len | ||
) |
Set the algorithm used for encryption to either deterministic or random encryption. This value should only be set when using explicit encryption.
If -1 is passed in for "len", then "algorithm" is assumed to be a null-terminated string.
Valid values for algorithm are: "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic" "AEAD_AES_256_CBC_HMAC_SHA_512-Random"
[in] | ctx | The mongocrypt_ctx_t object. |
[in] | algorithm | A string specifying the algorithm to use for encryption. |
[in] | len | The length of the algorithm string. |
ctx
has not been initialized. MONGOCRYPT_EXPORT bool mongocrypt_ctx_setopt_key_alt_name | ( | mongocrypt_ctx_t * | ctx, |
mongocrypt_binary_t * | key_alt_name | ||
) |
Set the keyAltName to use for explicit encryption or data key creation.
Pass the binary encoding a BSON document like the following:
{ "keyAltName" : (BSON UTF8 value) }
For explicit encryption, it is an error to set both the keyAltName and the key id.
For creating data keys, call this function repeatedly to set multiple keyAltNames.
[in] | ctx | The mongocrypt_ctx_t object. |
[in] | key_alt_name | The name to use. The viewed data is copied. It is valid to destroy key_alt_name with mongocrypt_binary_destroy immediately after. |
ctx
has not been initialized. MONGOCRYPT_EXPORT bool mongocrypt_ctx_setopt_key_id | ( | mongocrypt_ctx_t * | ctx, |
mongocrypt_binary_t * | key_id | ||
) |
Set the key id to use for explicit encryption.
It is an error to set both this and the key alt name.
[in] | ctx | The mongocrypt_ctx_t object. |
[in] | key_id | The binary corresponding to the _id (a UUID) of the data key to use from the key vault collection. Note, the UUID must be encoded with RFC-4122 byte order. The viewed data is copied. It is valid to destroy key_id with mongocrypt_binary_destroy immediately after. |
ctx
has not been initialized. MONGOCRYPT_EXPORT bool mongocrypt_ctx_setopt_masterkey_aws | ( | mongocrypt_ctx_t * | ctx, |
const char * | region, | ||
int32_t | region_len, | ||
const char * | cmk, | ||
int32_t | cmk_len | ||
) |
Identify the AWS KMS master key to use for creating a data key.
[in] | ctx | The mongocrypt_ctx_t object. |
[in] | region | The AWS region. |
[in] | region_len | The string length of region . Pass -1 to determine the string length with strlen (must be NULL terminated). |
[in] | cmk | The Amazon Resource Name (ARN) of the customer master key (CMK). |
[in] | cmk_len | The string length of cmk_len . Pass -1 to determine the string length with strlen (must be NULL terminated). |
ctx
has not been initialized. MONGOCRYPT_EXPORT bool mongocrypt_ctx_setopt_masterkey_aws_endpoint | ( | mongocrypt_ctx_t * | ctx, |
const char * | endpoint, | ||
int32_t | endpoint_len | ||
) |
Identify a custom AWS endpoint when creating a data key. This is used internally to construct the correct HTTP request (with the Host header set to this endpoint). This endpoint is persisted in the new data key, and will be returned via mongocrypt_kms_ctx_endpoint.
[in] | ctx | The mongocrypt_ctx_t object. |
[in] | endpoint | The endpoint. |
[in] | endpoint_len | The string length of endpoint . Pass -1 to determine the string length with strlen (must be NULL terminated). |
MONGOCRYPT_EXPORT bool mongocrypt_ctx_setopt_masterkey_local | ( | mongocrypt_ctx_t * | ctx | ) |
Set the master key to "local" for creating a data key.
[in] | ctx | The mongocrypt_ctx_t object. |
ctx
has not been initialized. MONGOCRYPT_EXPORT mongocrypt_ctx_state_t mongocrypt_ctx_state | ( | mongocrypt_ctx_t * | ctx | ) |
Get the current state of a context.
[in] | ctx | The mongocrypt_ctx_t object. |
MONGOCRYPT_EXPORT bool mongocrypt_ctx_status | ( | mongocrypt_ctx_t * | ctx, |
mongocrypt_status_t * | status | ||
) |
Get the status associated with a mongocrypt_ctx_t object.
[in] | ctx | The mongocrypt_ctx_t object. |
[out] | status | Receives the status. |
MONGOCRYPT_EXPORT void mongocrypt_destroy | ( | mongocrypt_t * | crypt | ) |
Destroy the mongocrypt_t object.
[in] | crypt | The mongocrypt_t object to destroy. |
MONGOCRYPT_EXPORT bool mongocrypt_init | ( | mongocrypt_t * | crypt | ) |
Initialize new mongocrypt_t object.
Set options before using mongocrypt_setopt_kms_provider_local, mongocrypt_setopt_kms_provider_aws, or mongocrypt_setopt_log_handler.
[in] | crypt | The mongocrypt_t object. |
MONGOCRYPT_EXPORT uint32_t mongocrypt_kms_ctx_bytes_needed | ( | mongocrypt_kms_ctx_t * | kms | ) |
Indicates how many bytes to feed into mongocrypt_kms_ctx_feed.
[in] | kms | The mongocrypt_kms_ctx_t. |
MONGOCRYPT_EXPORT bool mongocrypt_kms_ctx_endpoint | ( | mongocrypt_kms_ctx_t * | kms, |
const char ** | endpoint | ||
) |
Get the hostname from which to connect over TLS.
The storage for endpoint
is not owned by the caller, but is valid until calling mongocrypt_ctx_kms_done.
[in] | kms | A mongocrypt_kms_ctx_t. |
[out] | endpoint | The output hostname as a NULL terminated string. This may include a port (e.g. "example.com:123"). If it does not, default to port 443. |
MONGOCRYPT_EXPORT bool mongocrypt_kms_ctx_feed | ( | mongocrypt_kms_ctx_t * | kms, |
mongocrypt_binary_t * | bytes | ||
) |
Feed bytes from the HTTP response.
Feeding more bytes than what has been returned in mongocrypt_kms_ctx_bytes_needed is an error.
[in] | kms | The mongocrypt_kms_ctx_t. |
[in] | bytes | The bytes to feed. The viewed data is copied. It is valid to destroy bytes with mongocrypt_binary_destroy immediately after. |
MONGOCRYPT_EXPORT bool mongocrypt_kms_ctx_message | ( | mongocrypt_kms_ctx_t * | kms, |
mongocrypt_binary_t * | msg | ||
) |
Get the HTTP request message for a KMS handle.
The lifetime of msg
is tied to the lifetime of kms
. It is valid until mongocrypt_ctx_kms_done is called.
[in] | kms | A mongocrypt_kms_ctx_t. |
[out] | msg | The HTTP request to send to KMS. The data viewed by msg is guaranteed to be valid until the call of mongocrypt_ctx_kms_done of the parent mongocrypt_ctx_t. |
MONGOCRYPT_EXPORT bool mongocrypt_kms_ctx_status | ( | mongocrypt_kms_ctx_t * | kms, |
mongocrypt_status_t * | status | ||
) |
Get the status associated with a mongocrypt_kms_ctx_t object.
[in] | kms | The mongocrypt_kms_ctx_t object. |
[out] | status | Receives the status. |
MONGOCRYPT_EXPORT mongocrypt_t* mongocrypt_new | ( | void | ) |
Allocate a new mongocrypt_t object.
Set options using mongocrypt_setopt_* functions, then initialize with mongocrypt_init. When done with the mongocrypt_t, free with mongocrypt_destroy.
MONGOCRYPT_EXPORT bool mongocrypt_setopt_kms_provider_aws | ( | mongocrypt_t * | crypt, |
const char * | aws_access_key_id, | ||
int32_t | aws_access_key_id_len, | ||
const char * | aws_secret_access_key, | ||
int32_t | aws_secret_access_key_len | ||
) |
Configure an AWS KMS provider on the mongocrypt_t object.
[in] | crypt | The mongocrypt_t object. |
[in] | aws_access_key_id | The AWS access key ID used to generate KMS messages. |
[in] | aws_access_key_id_len | The string length (in bytes) of aws_access_key_id . Pass -1 to determine the string length with strlen (must be NULL terminated). |
[in] | aws_secret_access_key | The AWS secret access key used to generate KMS messages. |
[in] | aws_secret_access_key_len | The string length (in bytes) of aws_secret_access_key . Pass -1 to determine the string length with strlen (must be NULL terminated). |
crypt
. MONGOCRYPT_EXPORT bool mongocrypt_setopt_kms_provider_local | ( | mongocrypt_t * | crypt, |
mongocrypt_binary_t * | key | ||
) |
Configure a local KMS provider on the mongocrypt_t object.
[in] | crypt | The mongocrypt_t object. |
[in] | key | A 96 byte master key used to encrypt and decrypt key vault keys. The viewed data is copied. It is valid to destroy key with mongocrypt_binary_destroy immediately after. |
crypt
. MONGOCRYPT_EXPORT bool mongocrypt_setopt_log_handler | ( | mongocrypt_t * | crypt, |
mongocrypt_log_fn_t | log_fn, | ||
void * | log_ctx | ||
) |
Set a handler on the mongocrypt_t object to get called on every log message.
[in] | crypt | The mongocrypt_t object. |
[in] | log_fn | The log callback. |
[in] | log_ctx | A context passed as an argument to the log callback every invokation. |
crypt
. MONGOCRYPT_EXPORT bool mongocrypt_setopt_schema_map | ( | mongocrypt_t * | crypt, |
mongocrypt_binary_t * | schema_map | ||
) |
Set a local schema map for encryption.
[in] | crypt | The mongocrypt_t object. |
[in] | schema_map | A BSON document representing the schema map supplied by the user. The keys are collection namespaces and values are JSON schemas. The viewed data copied. It is valid to destroy schema_map with mongocrypt_binary_destroy immediately after. |
crypt
has not been initialized. MONGOCRYPT_EXPORT bool mongocrypt_status | ( | mongocrypt_t * | crypt, |
mongocrypt_status_t * | status | ||
) |
Get the status associated with a mongocrypt_t object.
[in] | crypt | The mongocrypt_t object. |
[out] | status | Receives the status. |
MONGOCRYPT_EXPORT uint32_t mongocrypt_status_code | ( | mongocrypt_status_t * | status | ) |
Get an error code or 0.
[in] | status | The status object. |
MONGOCRYPT_EXPORT void mongocrypt_status_destroy | ( | mongocrypt_status_t * | status | ) |
Free the memory for a status object.
[in] | status | The status to destroy. |
MONGOCRYPT_EXPORT const char* mongocrypt_status_message | ( | mongocrypt_status_t * | status, |
uint32_t * | len | ||
) |
Get the error message associated with a status or NULL.
[in] | status | The status object. |
[out] | len | An optional length of the returned string (excluding the trailing NULL byte). May be NULL. |
MONGOCRYPT_EXPORT mongocrypt_status_t* mongocrypt_status_new | ( | void | ) |
Create a new status object.
Use a new status object to retrieve the status from a handle by passing this as an out-parameter to functions like mongocrypt_ctx_status. When done, destroy it with mongocrypt_status_destroy.
MONGOCRYPT_EXPORT bool mongocrypt_status_ok | ( | mongocrypt_status_t * | status | ) |
Returns true if the status indicates success.
[in] | status | The status to check. |
MONGOCRYPT_EXPORT void mongocrypt_status_set | ( | mongocrypt_status_t * | status, |
mongocrypt_status_type_t | type, | ||
uint32_t | code, | ||
const char * | message, | ||
int32_t | message_len | ||
) |
Set a status object with message, type, and code.
Use this to set the mongocrypt_status_t given in the crypto hooks.
[in] | type | The status type. |
[in] | code | The status code. |
[in] | message | The message. |
[in] | message_len | Due to historical behavior, pass 1 + the string length of message (which differs from other functions accepting string arguments). Alternatively, if message is NULL terminated this may be -1 to tell mongocrypt to determine the string's length with strlen. |
MONGOCRYPT_EXPORT mongocrypt_status_type_t mongocrypt_status_type | ( | mongocrypt_status_t * | status | ) |
Indicates success or the type of error.
[in] | status | The status object. |
MONGOCRYPT_EXPORT const char* mongocrypt_version | ( | uint32_t * | len | ) |
Returns the version string for libmongocrypt.
[out] | len | An optional length of the returned string. May be NULL. |