libmongocrypt
|
#include "mongocrypt-export.h"
#include "mongocrypt-compat.h"
#include "mongocrypt-config.h"
Go to the source code of this file.
Macros | |
#define | MONGOCRYPT_ALGORITHM_DETERMINISTIC_STR "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic" |
String constant for setopt_algorithm "Deterministic" encryption. | |
#define | MONGOCRYPT_ALGORITHM_RANDOM_STR "AEAD_AES_256_CBC_HMAC_SHA_512-Random" |
String constant for setopt_algorithm "Random" encryption. | |
#define | MONGOCRYPT_ALGORITHM_INDEXED_STR "Indexed" |
String constant for setopt_algorithm "Indexed" explicit encryption. | |
#define | MONGOCRYPT_ALGORITHM_UNINDEXED_STR "Unindexed" |
String constant for setopt_algorithm "Unindexed" explicit encryption. | |
#define | MONGOCRYPT_QUERY_TYPE_EQUALITY_STR "equality" |
String constant for setopt_query_type_v2, "equality" query type. | |
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 , MONGOCRYPT_STATUS_ERROR_CRYPT_SHARED = 3 } |
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_NEED_KMS_CREDENTIALS = 7 , MONGOCRYPT_CTX_READY = 5 , MONGOCRYPT_CTX_DONE = 6 } |
Functions | |
MONGOCRYPT_EXPORT const char * | mongocrypt_version (uint32_t *len) |
MONGOCRYPT_EXPORT mongocrypt_binary_t * | mongocrypt_binary_new (void) |
MONGOCRYPT_EXPORT mongocrypt_binary_t * | mongocrypt_binary_new_from_data (uint8_t *data, uint32_t len) |
MONGOCRYPT_EXPORT uint8_t * | mongocrypt_binary_data (const mongocrypt_binary_t *binary) |
MONGOCRYPT_EXPORT uint32_t | mongocrypt_binary_len (const mongocrypt_binary_t *binary) |
MONGOCRYPT_EXPORT void | mongocrypt_binary_destroy (mongocrypt_binary_t *binary) |
MONGOCRYPT_EXPORT mongocrypt_status_t * | mongocrypt_status_new (void) |
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) |
MONGOCRYPT_EXPORT mongocrypt_status_type_t | mongocrypt_status_type (mongocrypt_status_t *status) |
MONGOCRYPT_EXPORT uint32_t | mongocrypt_status_code (mongocrypt_status_t *status) |
MONGOCRYPT_EXPORT const char * | mongocrypt_status_message (mongocrypt_status_t *status, uint32_t *len) |
MONGOCRYPT_EXPORT bool | mongocrypt_status_ok (mongocrypt_status_t *status) |
MONGOCRYPT_EXPORT void | mongocrypt_status_destroy (mongocrypt_status_t *status) |
MONGOCRYPT_EXPORT mongocrypt_t * | mongocrypt_new (void) |
MONGOCRYPT_EXPORT bool | mongocrypt_setopt_log_handler (mongocrypt_t *crypt, mongocrypt_log_fn_t log_fn, void *log_ctx) |
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) |
MONGOCRYPT_EXPORT bool | mongocrypt_setopt_kms_provider_local (mongocrypt_t *crypt, mongocrypt_binary_t *key) |
MONGOCRYPT_EXPORT bool | mongocrypt_setopt_kms_providers (mongocrypt_t *crypt, mongocrypt_binary_t *kms_providers) |
MONGOCRYPT_EXPORT bool | mongocrypt_setopt_schema_map (mongocrypt_t *crypt, mongocrypt_binary_t *schema_map) |
MONGOCRYPT_EXPORT bool | mongocrypt_setopt_encrypted_field_config_map (mongocrypt_t *crypt, mongocrypt_binary_t *efc_map) |
MONGOCRYPT_EXPORT void | mongocrypt_setopt_append_crypt_shared_lib_search_path (mongocrypt_t *crypt, const char *path) |
Append an additional search directory to the search path for loading the crypt_shared dynamic library. More... | |
MONGOCRYPT_EXPORT void | mongocrypt_setopt_set_crypt_shared_lib_path_override (mongocrypt_t *crypt, const char *path) |
Set a single override path for loading the crypt_shared dynamic library. More... | |
MONGOCRYPT_EXPORT void | mongocrypt_setopt_use_need_kms_credentials_state (mongocrypt_t *crypt) |
Opt-into handling the MONGOCRYPT_CTX_NEED_KMS_CREDENTIALS state. More... | |
MONGOCRYPT_EXPORT bool | mongocrypt_init (mongocrypt_t *crypt) |
MONGOCRYPT_EXPORT bool | mongocrypt_status (mongocrypt_t *crypt, mongocrypt_status_t *status) |
MONGOCRYPT_EXPORT void | mongocrypt_destroy (mongocrypt_t *crypt) |
MONGOCRYPT_EXPORT const char * | mongocrypt_crypt_shared_lib_version_string (const mongocrypt_t *crypt, uint32_t *len) |
MONGOCRYPT_EXPORT uint64_t | mongocrypt_crypt_shared_lib_version (const mongocrypt_t *crypt) |
Obtain a 64-bit constant encoding the version of the loaded crypt_shared library, if available. More... | |
MONGOCRYPT_EXPORT mongocrypt_ctx_t * | mongocrypt_ctx_new (mongocrypt_t *crypt) |
MONGOCRYPT_EXPORT bool | mongocrypt_ctx_status (mongocrypt_ctx_t *ctx, mongocrypt_status_t *status) |
MONGOCRYPT_EXPORT bool | mongocrypt_ctx_setopt_key_id (mongocrypt_ctx_t *ctx, mongocrypt_binary_t *key_id) |
MONGOCRYPT_EXPORT bool | mongocrypt_ctx_setopt_key_alt_name (mongocrypt_ctx_t *ctx, mongocrypt_binary_t *key_alt_name) |
MONGOCRYPT_EXPORT bool | mongocrypt_ctx_setopt_key_material (mongocrypt_ctx_t *ctx, mongocrypt_binary_t *key_material) |
MONGOCRYPT_EXPORT bool | mongocrypt_ctx_setopt_algorithm (mongocrypt_ctx_t *ctx, const char *algorithm, int len) |
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) |
MONGOCRYPT_EXPORT bool | mongocrypt_ctx_setopt_masterkey_aws_endpoint (mongocrypt_ctx_t *ctx, const char *endpoint, int32_t endpoint_len) |
MONGOCRYPT_EXPORT bool | mongocrypt_ctx_setopt_masterkey_local (mongocrypt_ctx_t *ctx) |
MONGOCRYPT_EXPORT bool | mongocrypt_ctx_setopt_key_encryption_key (mongocrypt_ctx_t *ctx, mongocrypt_binary_t *bin) |
MONGOCRYPT_EXPORT bool | mongocrypt_ctx_datakey_init (mongocrypt_ctx_t *ctx) |
MONGOCRYPT_EXPORT bool | mongocrypt_ctx_encrypt_init (mongocrypt_ctx_t *ctx, const char *db, int32_t db_len, mongocrypt_binary_t *cmd) |
MONGOCRYPT_EXPORT bool | mongocrypt_ctx_explicit_encrypt_init (mongocrypt_ctx_t *ctx, mongocrypt_binary_t *msg) |
MONGOCRYPT_EXPORT bool | mongocrypt_ctx_decrypt_init (mongocrypt_ctx_t *ctx, mongocrypt_binary_t *doc) |
MONGOCRYPT_EXPORT bool | mongocrypt_ctx_explicit_decrypt_init (mongocrypt_ctx_t *ctx, mongocrypt_binary_t *msg) |
MONGOCRYPT_EXPORT bool | mongocrypt_ctx_rewrap_many_datakey_init (mongocrypt_ctx_t *ctx, mongocrypt_binary_t *filter) |
Initialize a context to rewrap datakeys. More... | |
MONGOCRYPT_EXPORT mongocrypt_ctx_state_t | mongocrypt_ctx_state (mongocrypt_ctx_t *ctx) |
MONGOCRYPT_EXPORT bool | mongocrypt_ctx_mongo_op (mongocrypt_ctx_t *ctx, mongocrypt_binary_t *op_bson) |
MONGOCRYPT_EXPORT bool | mongocrypt_ctx_mongo_feed (mongocrypt_ctx_t *ctx, mongocrypt_binary_t *reply) |
MONGOCRYPT_EXPORT bool | mongocrypt_ctx_mongo_done (mongocrypt_ctx_t *ctx) |
MONGOCRYPT_EXPORT mongocrypt_kms_ctx_t * | mongocrypt_ctx_next_kms_ctx (mongocrypt_ctx_t *ctx) |
MONGOCRYPT_EXPORT bool | mongocrypt_kms_ctx_message (mongocrypt_kms_ctx_t *kms, mongocrypt_binary_t *msg) |
MONGOCRYPT_EXPORT bool | mongocrypt_kms_ctx_endpoint (mongocrypt_kms_ctx_t *kms, const char **endpoint) |
MONGOCRYPT_EXPORT uint32_t | mongocrypt_kms_ctx_bytes_needed (mongocrypt_kms_ctx_t *kms) |
MONGOCRYPT_EXPORT bool | mongocrypt_kms_ctx_feed (mongocrypt_kms_ctx_t *kms, mongocrypt_binary_t *bytes) |
MONGOCRYPT_EXPORT bool | mongocrypt_kms_ctx_status (mongocrypt_kms_ctx_t *kms, mongocrypt_status_t *status) |
MONGOCRYPT_EXPORT const char * | mongocrypt_kms_ctx_get_kms_provider (mongocrypt_kms_ctx_t *kms, uint32_t *len) |
MONGOCRYPT_EXPORT bool | mongocrypt_ctx_kms_done (mongocrypt_ctx_t *ctx) |
MONGOCRYPT_EXPORT bool | mongocrypt_ctx_provide_kms_providers (mongocrypt_ctx_t *ctx, mongocrypt_binary_t *kms_providers_definition) |
MONGOCRYPT_EXPORT bool | mongocrypt_ctx_finalize (mongocrypt_ctx_t *ctx, mongocrypt_binary_t *out) |
MONGOCRYPT_EXPORT void | mongocrypt_ctx_destroy (mongocrypt_ctx_t *ctx) |
MONGOCRYPT_EXPORT bool | mongocrypt_setopt_crypto_hooks (mongocrypt_t *crypt, mongocrypt_crypto_fn aes_256_cbc_encrypt, mongocrypt_crypto_fn aes_256_cbc_decrypt, mongocrypt_random_fn random, mongocrypt_hmac_fn hmac_sha_512, mongocrypt_hmac_fn hmac_sha_256, mongocrypt_hash_fn sha_256, void *ctx) |
MONGOCRYPT_EXPORT bool | mongocrypt_setopt_aes_256_ctr (mongocrypt_t *crypt, mongocrypt_crypto_fn aes_256_ctr_encrypt, mongocrypt_crypto_fn aes_256_ctr_decrypt, void *ctx) |
MONGOCRYPT_EXPORT bool | mongocrypt_setopt_aes_256_ecb (mongocrypt_t *crypt, mongocrypt_crypto_fn aes_256_ecb_encrypt, void *ctx) |
MONGOCRYPT_EXPORT bool | mongocrypt_setopt_crypto_hook_sign_rsaes_pkcs1_v1_5 (mongocrypt_t *crypt, mongocrypt_hmac_fn sign_rsaes_pkcs1_v1_5, void *sign_ctx) |
MONGOCRYPT_EXPORT void | mongocrypt_setopt_bypass_query_analysis (mongocrypt_t *crypt) |
Opt-into skipping query analysis. More... | |
MONGOCRYPT_EXPORT bool | mongocrypt_ctx_setopt_contention_factor (mongocrypt_ctx_t *ctx, int64_t contention_factor) |
MONGOCRYPT_EXPORT bool | mongocrypt_ctx_setopt_index_key_id (mongocrypt_ctx_t *ctx, mongocrypt_binary_t *key_id) |
MONGOCRYPT_EXPORT bool | mongocrypt_ctx_setopt_query_type (mongocrypt_ctx_t *ctx, const char *query_type, int len) |
The top-level handle to libmongocrypt.
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_set. 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_set. 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 signature or HMAC function.
Currently used in callbacks for HMAC SHA-512, HMAC SHA-256, and RSA SHA-256 signature.
[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_set. 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_set. 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 uint64_t mongocrypt_crypt_shared_lib_version | ( | const mongocrypt_t * | crypt | ) |
Obtain a 64-bit constant encoding the version of the loaded crypt_shared library, if available.
[in] | crypt | The mongocrypt_t object after a successul call to mongocrypt_init. |
The version is encoded as four 16-bit numbers, from high to low:
For example, version 6.2.1 would be encoded as: 0x0006'0002'0001'0000
MONGOCRYPT_EXPORT const char* mongocrypt_crypt_shared_lib_version_string | ( | const mongocrypt_t * | crypt, |
uint32_t * | len | ||
) |
Obtain a nul-terminated version string of the loaded crypt_shared dynamic library, if available.
If no crypt_shared was successfully loaded, this function returns NULL.
[in] | crypt | The mongocrypt_t object after a successful call to mongocrypt_init. |
[out] | len | An optional output parameter to which the length of the returned string is written. If provided and no crypt_shared library was loaded, zero is written to *len. |
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.
Pass the binary encoding of a BSON document containing the BSON value to encrypt like the following:
{ "v" : (BSON BINARY value of subtype 6) }
[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 for FLE 1:
Associated options for Queryable Encryption:
An error is returned if FLE 1 and Queryable Encryption incompatible options are set.
[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.
If ctx
was initialized with mongocrypt_ctx_rewrap_many_datakey_init, then this BSON has the form: { "v": [{ "_id": ..., "keyMaterial": ..., "masterKey": ... }, ...] } where each BSON document in the array contains the updated fields of a rewrapped datakey to be bulk-updated into the key vault collection. Note: the updateDate field should be updated using the $currentDate operator.
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_provide_kms_providers | ( | mongocrypt_ctx_t * | ctx, |
mongocrypt_binary_t * | kms_providers_definition | ||
) |
Call in response to the MONGOCRYPT_CTX_NEED_KMS_CREDENTIALS state to set per-context KMS provider settings. These follow the same format as mongocrypt_setopt_kms_providers. If no keys are present in the BSON input, the KMS provider settings configured for the mongocrypt_t at initialization are used.
[in] | ctx | The mongocrypt_ctx_t object. |
[in] | kms_providers | A BSON document mapping the KMS provider names to credentials. |
MONGOCRYPT_EXPORT bool mongocrypt_ctx_rewrap_many_datakey_init | ( | mongocrypt_ctx_t * | ctx, |
mongocrypt_binary_t * | filter | ||
) |
Initialize a context to rewrap datakeys.
Associated options:
[in] | ctx | The mongocrypt_ctx_t object. |
[in] | filter | The filter to use for the find command on the key vault collection to retrieve datakeys to rewrap. |
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_contention_factor | ( | mongocrypt_ctx_t * | ctx, |
int64_t | contention_factor | ||
) |
Set the contention factor used for explicit encryption. The contention factor is only used for indexed Queryable Encryption.
[in] | ctx | The mongocrypt_ctx_t object. |
[in] | contention_factor |
ctx
has not been initialized. MONGOCRYPT_EXPORT bool mongocrypt_ctx_setopt_index_key_id | ( | mongocrypt_ctx_t * | ctx, |
mongocrypt_binary_t * | key_id | ||
) |
Set the index key id to use for explicit Queryable Encryption.
If the index key id not set, the key id from mongocrypt_ctx_setopt_key_id is used.
[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_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_encryption_key | ( | mongocrypt_ctx_t * | ctx, |
mongocrypt_binary_t * | bin | ||
) |
Set key encryption key document for creating a data key or for rewrapping datakeys.
[in] | ctx | The mongocrypt_ctx_t object. |
[in] | bin | BSON representing the key encryption key document with an additional "provider" field. The following forms are accepted: |
AWS { provider: "aws", region: <string>, key: <string>, endpoint: <optional string> }
Azure { provider: "azure", keyVaultEndpoint: <string>, keyName: <string>, keyVersion: <optional string> }
GCP { provider: "gcp", projectId: <string>, location: <string>, keyRing: <string>, keyName: <string>, keyVersion: <optional string>, endpoint: <optional string> }
Local { provider: "local" }
KMIP { provider: "kmip", keyId: <optional string> endpoint: <string> }
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_key_material | ( | mongocrypt_ctx_t * | ctx, |
mongocrypt_binary_t * | key_material | ||
) |
Set the keyMaterial to use for encrypting data.
Pass the binary encoding of a BSON document like the following:
{ "keyMaterial" : (BSON BINARY value) }
[in] | ctx | The mongocrypt_ctx_t object. |
[in] | key_material | The data encryption key to use. The viewed data is copied. It is valid to destroy key_material 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.
This has been superseded by the more flexible: mongocrypt_ctx_setopt_key_encryption_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.
This has been superseded by the more flexible: mongocrypt_ctx_setopt_key_encryption_key
[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. This has been superseded by the more flexible: mongocrypt_ctx_setopt_key_encryption_key
[in] | ctx | The mongocrypt_ctx_t object. |
ctx
has not been initialized. MONGOCRYPT_EXPORT bool mongocrypt_ctx_setopt_query_type | ( | mongocrypt_ctx_t * | ctx, |
const char * | query_type, | ||
int | len | ||
) |
Set the query type to use for explicit Queryable Encryption.
[in] | ctx | The mongocrypt_ctx_t object. |
[in] | query_type | The query type string |
[in] | len | The length of query_type, or -1 for automatic |
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 endpoint as a NULL terminated string. The endpoint consists of a hostname and port separated by a colon. E.g. "example.com:123". A port is always present. |
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 const char* mongocrypt_kms_ctx_get_kms_provider | ( | mongocrypt_kms_ctx_t * | kms, |
uint32_t * | len | ||
) |
Get the KMS provider identifier associated with this KMS request.
This is used to conditionally configure TLS connections based on the KMS request. It is useful for KMIP, which authenticates with a client certificate.
[in] | kms | The mongocrypt_kms_ctx_t object. |
[out] | len | Receives the length of the returned string. It may be NULL. If it is not NULL, it is set to the length of the returned string without the NULL terminator. |
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_aes_256_ctr | ( | mongocrypt_t * | crypt, |
mongocrypt_crypto_fn | aes_256_ctr_encrypt, | ||
mongocrypt_crypto_fn | aes_256_ctr_decrypt, | ||
void * | ctx | ||
) |
Set a crypto hook for the AES256-CTR operations.
[in] | crypt | The mongocrypt_t object. |
[in] | aes_256_ctr_encrypt | The crypto callback function for encrypt operation. |
[in] | aes_256_ctr_decrypt | The crypto callback function for decrypt operation. |
[in] | ctx | A context passed as an argument to the crypto callback every invocation. |
crypt
. MONGOCRYPT_EXPORT bool mongocrypt_setopt_aes_256_ecb | ( | mongocrypt_t * | crypt, |
mongocrypt_crypto_fn | aes_256_ecb_encrypt, | ||
void * | ctx | ||
) |
Set an AES256-ECB crypto hook for the AES256-CTR operations. If CTR hook was configured using mongocrypt_setopt_aes_256_ctr, ECB hook will be ignored.
[in] | crypt | The mongocrypt_t object. |
[in] | aes_256_ecb_encrypt | The crypto callback function for encrypt operation. |
[in] | ctx | A context passed as an argument to the crypto callback every invocation. |
crypt
. MONGOCRYPT_EXPORT void mongocrypt_setopt_append_crypt_shared_lib_search_path | ( | mongocrypt_t * | crypt, |
const char * | path | ||
) |
Append an additional search directory to the search path for loading the crypt_shared dynamic library.
[in] | crypt | The mongocrypt_t object to update |
[in] | path | A null-terminated sequence of bytes for the search path. On some filesystems, this may be arbitrary bytes. On other filesystems, this may be required to be a valid UTF-8 code unit sequence. If the leading element of the path is the literal string "$ORIGIN", that substring will be replaced with the directory path containing the executable libmongocrypt module. If the path string is literal "$SYSTEM", then libmongocrypt will defer to the system's library resolution mechanism to find the crypt_shared library. |
MONGOCRYPT_EXPORT void mongocrypt_setopt_bypass_query_analysis | ( | mongocrypt_t * | crypt | ) |
Opt-into skipping query analysis.
If opted in:
[in] | crypt | The mongocrypt_t object to update |
MONGOCRYPT_EXPORT bool mongocrypt_setopt_crypto_hook_sign_rsaes_pkcs1_v1_5 | ( | mongocrypt_t * | crypt, |
mongocrypt_hmac_fn | sign_rsaes_pkcs1_v1_5, | ||
void * | sign_ctx | ||
) |
Set a crypto hook for the RSASSA-PKCS1-v1_5 algorithm with a SHA-256 hash.
See: https://tools.ietf.org/html/rfc3447#section-8.2
Note: this function has the wrong name. It should be: mongocrypt_setopt_crypto_hook_sign_rsassa_pkcs1_v1_5
[in] | crypt | The mongocrypt_t object. |
[in] | sign_rsaes_pkcs1_v1_5 | The crypto callback function. |
[in] | sign_ctx | A context passed as an argument to the crypto callback every invocation. |
crypt
. MONGOCRYPT_EXPORT bool mongocrypt_setopt_encrypted_field_config_map | ( | mongocrypt_t * | crypt, |
mongocrypt_binary_t * | efc_map | ||
) |
Set a local EncryptedFieldConfigMap for encryption.
[in] | crypt | The mongocrypt_t object. |
[in] | efc_map | A BSON document representing the EncryptedFieldConfigMap supplied by the user. The keys are collection namespaces and values are EncryptedFieldConfigMap documents. The viewed data copied. It is valid to destroy efc_map with mongocrypt_binary_destroy immediately after. |
crypt
has not been initialized. 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.
This has been superseded by the more flexible: mongocrypt_setopt_kms_providers
[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.
This has been superseded by the more flexible: mongocrypt_setopt_kms_providers
[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_kms_providers | ( | mongocrypt_t * | crypt, |
mongocrypt_binary_t * | kms_providers | ||
) |
Configure KMS providers with a BSON document.
[in] | crypt | The mongocrypt_t object. |
[in] | kms_providers | A BSON document mapping the KMS provider names to credentials. Set a KMS provider value to an empty document to supply credentials on-demand with mongocrypt_ctx_provide_kms_providers. |
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 invocation. |
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 void mongocrypt_setopt_set_crypt_shared_lib_path_override | ( | mongocrypt_t * | crypt, |
const char * | path | ||
) |
Set a single override path for loading the crypt_shared dynamic library.
[in] | crypt | The mongocrypt_t object to update |
[in] | path | A null-terminated sequence of bytes for a path to the crypt_shared dynamic library. On some filesystems, this may be arbitrary bytes. On other filesystems, this may be required to be a valid UTF-8 code unit sequence. If the leading element of the path is the literal string $ORIGIN , that substring will be replaced with the directory path containing the executable libmongocrypt module. |
MONGOCRYPT_EXPORT void mongocrypt_setopt_use_need_kms_credentials_state | ( | mongocrypt_t * | crypt | ) |
Opt-into handling the MONGOCRYPT_CTX_NEED_KMS_CREDENTIALS state.
If set, before entering the MONGOCRYPT_CTX_NEED_KMS state, contexts may enter the MONGOCRYPT_CTX_NEED_KMS_CREDENTIALS state and then wait for credentials to be supplied through mongocrypt_ctx_provide_kms_providers.
A context will only enter MONGOCRYPT_CTX_NEED_KMS_CREDENTIALS if an empty document was set for a KMS provider in mongocrypt_setopt_kms_providers.
[in] | crypt | The mongocrypt_t object to update |
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. |