libmongocrypt
Loading...
Searching...
No Matches
mongocrypt.h File Reference
#include "mongocrypt-compat.h"
#include "mongocrypt-export.h"
#include "mongocrypt-config.h"

Go to the source code of this file.

Data Structures

struct  _mongocrypt_binary_t
 

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_ALGORITHM_RANGEPREVIEW_DEPRECATED_STR   "RangePreview"
 
#define MONGOCRYPT_ALGORITHM_RANGE_STR   "Range"
 
#define MONGOCRYPT_QUERY_TYPE_EQUALITY_STR   "equality"
 String constants for setopt_query_type.
 
#define MONGOCRYPT_QUERY_TYPE_RANGEPREVIEW_DEPRECATED_STR   "rangePreview"
 
#define MONGOCRYPT_QUERY_TYPE_RANGE_STR   "range"
 
#define MONGOCRYPT_QUERY_TYPE_SUBSTRINGPREVIEW_STR   "substringPreview"
 NOTE: "substringPreview" is experimental and may be removed in a future non-major release.
 
#define MONGOCRYPT_QUERY_TYPE_SUFFIXPREVIEW_STR   "suffixPreview"
 NOTE: "suffixPreview" is experimental and may be removed in a future non-major release.
 
#define MONGOCRYPT_QUERY_TYPE_PREFIXPREVIEW_STR   "prefixPreview"
 NOTE: "prefixPreview" is experimental and may be removed in a future non-major release.
 

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_COLLINFO_WITH_DB = 8 , 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 bool mongocrypt_is_crypto_available (void)
 
MONGOCRYPT_EXPORT mongocrypt_binary_tmongocrypt_binary_new (void)
 
MONGOCRYPT_EXPORT mongocrypt_binary_tmongocrypt_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_tmongocrypt_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_tmongocrypt_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_retry_kms (mongocrypt_t *crypt, bool enable)
 
MONGOCRYPT_EXPORT bool mongocrypt_setopt_enable_multiple_collinfo (mongocrypt_t *crypt)
 
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.
 
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.
 
MONGOCRYPT_EXPORT void mongocrypt_setopt_use_need_kms_credentials_state (mongocrypt_t *crypt)
 Opt-into handling the MONGOCRYPT_CTX_NEED_KMS_CREDENTIALS state.
 
MONGOCRYPT_EXPORT void mongocrypt_setopt_use_need_mongo_collinfo_with_db_state (mongocrypt_t *crypt)
 Opt-into handling the MONGOCRYPT_CTX_NEED_MONGO_COLLINFO_WITH_DB state.
 
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.
 
MONGOCRYPT_EXPORT mongocrypt_ctx_tmongocrypt_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_explicit_encrypt_expression_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.
 
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 const char * mongocrypt_ctx_mongo_db (mongocrypt_ctx_t *ctx)
 
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_tmongocrypt_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 int64_t mongocrypt_kms_ctx_usleep (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_fail (mongocrypt_kms_ctx_t *kms)
 
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.
 
MONGOCRYPT_EXPORT bool mongocrypt_setopt_use_range_v2 (mongocrypt_t *crypt)
 
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)
 
MONGOCRYPT_EXPORT bool mongocrypt_ctx_setopt_algorithm_range (mongocrypt_ctx_t *ctx, mongocrypt_binary_t *opts)
 
MONGOCRYPT_EXPORT bool mongocrypt_setopt_key_expiration (mongocrypt_t *crypt, uint64_t cache_expiration_ms)
 

Detailed Description

The top-level handle to libmongocrypt.

Typedef Documentation

◆ 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:

// The viewed data of bin has been copied. Ok to free the view and the data.
my_free_fn (mydata);
MONGOCRYPT_EXPORT void mongocrypt_binary_destroy(mongocrypt_binary_t *binary)
MONGOCRYPT_EXPORT bool mongocrypt_setopt_kms_provider_local(mongocrypt_t *crypt, mongocrypt_binary_t *key)
MONGOCRYPT_EXPORT mongocrypt_binary_t * mongocrypt_binary_new_from_data(uint8_t *data, uint32_t len)
Definition mongocrypt.h:87

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.

The mongocrypt_binary_t struct definition is public. Consumers may rely on the struct layout.

◆ mongocrypt_crypto_fn

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.

Parameters
[in]ctxAn optional context object that may have been set when hooks were enabled.
[in]keyAn encryption key (32 bytes for AES_256).
[in]ivAn initialization vector (16 bytes for AES_256);
[in]inThe input.
[out]outA preallocated byte array for the output. See mongocrypt_binary_data.
[out]bytes_writtenSet this to the number of bytes written to out.
[out]statusAn optional status to pass error messages. See mongocrypt_status_set.
Returns
A boolean indicating success. If returning false, set status with a message indicating the error using mongocrypt_status_set.

◆ mongocrypt_ctx_t

typedef struct _mongocrypt_ctx_t mongocrypt_ctx_t

Manages the state machine for encryption or decryption.

◆ mongocrypt_hash_fn

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.

Parameters
[in]ctxAn optional context object that may have been set when hooks were enabled.
[in]inThe input.
[out]outA preallocated byte array for the output. See mongocrypt_binary_data.
[out]statusAn optional status to pass error messages. See mongocrypt_status_set.
Returns
A boolean indicating success. If returning false, set status with a message indicating the error using mongocrypt_status_set.

◆ mongocrypt_hmac_fn

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.

Parameters
[in]ctxAn optional context object that may have been set when hooks were enabled.
[in]keyAn encryption key (32 bytes for HMAC_SHA512).
[in]inThe input.
[out]outA preallocated byte array for the output. See mongocrypt_binary_data.
[out]statusAn optional status to pass error messages. See mongocrypt_status_set.
Returns
A boolean indicating success. If returning false, set status with a message indicating the error using mongocrypt_status_set.

◆ mongocrypt_kms_ctx_t

typedef struct _mongocrypt_kms_ctx_t mongocrypt_kms_ctx_t

Manages a single KMS HTTP request/response.

◆ mongocrypt_log_fn_t

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.

Parameters
[in]messageA NULL terminated message.
[in]message_lenThe length of message.
[in]ctxA context provided by the caller of mongocrypt_setopt_log_handler.

◆ mongocrypt_random_fn

typedef bool(* mongocrypt_random_fn) (void *ctx, mongocrypt_binary_t *out, uint32_t count, mongocrypt_status_t *status)

A crypto secure random function.

Parameters
[in]ctxAn optional context object that may have been set when hooks were enabled.
[out]outA preallocated byte array for the output. See mongocrypt_binary_data.
[in]countThe number of random bytes requested.
[out]statusAn optional status to pass error messages. See mongocrypt_status_set.
Returns
A boolean indicating success. If returning false, set status with a message indicating the error using mongocrypt_status_set.

◆ mongocrypt_status_t

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.

◆ mongocrypt_t

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.

Enumeration Type Documentation

◆ mongocrypt_ctx_state_t

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.

◆ mongocrypt_log_level_t

Indicates the type of log message.

◆ mongocrypt_status_type_t

Indicates the type of error.

Function Documentation

◆ mongocrypt_binary_data()

MONGOCRYPT_EXPORT uint8_t * mongocrypt_binary_data ( const mongocrypt_binary_t * binary)

Get a pointer to the viewed data.

Parameters
[in]binaryThe mongocrypt_binary_t.
Returns
A pointer to the viewed data.

◆ mongocrypt_binary_destroy()

MONGOCRYPT_EXPORT void mongocrypt_binary_destroy ( mongocrypt_binary_t * binary)

Free the mongocrypt_binary_t.

This does not free the viewed data.

Parameters
[in]binaryThe mongocrypt_binary_t destroy.

◆ mongocrypt_binary_len()

MONGOCRYPT_EXPORT uint32_t mongocrypt_binary_len ( const mongocrypt_binary_t * binary)

Get the length of the viewed data.

Parameters
[in]binaryThe mongocrypt_binary_t.
Returns
The length of the viewed data.

◆ mongocrypt_binary_new()

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.

Returns
A new mongocrypt_binary_t.

◆ mongocrypt_binary_new_from_data()

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).

Parameters
[in]dataA pointer to an array of bytes. This data is not copied. data must outlive the binary object.
[in]lenThe length of the data byte array.
Returns
A new mongocrypt_binary_t.

◆ mongocrypt_crypt_shared_lib_version()

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.

Parameters
[in]cryptThe mongocrypt_t object after a successful call to mongocrypt_init.
Returns
A 64-bit encoded version number, with the version encoded as four sixteen-bit integers, or zero if no crypt_shared library was loaded.

The version is encoded as four 16-bit numbers, from high to low:

  • Major version
  • Minor version
  • Revision
  • Reserved

For example, version 6.2.1 would be encoded as: 0x0006'0002'0001'0000

◆ mongocrypt_crypt_shared_lib_version_string()

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.

Parameters
[in]cryptThe mongocrypt_t object after a successful call to mongocrypt_init.
[out]lenAn 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.
Returns
A nul-terminated string of the dynamically loaded crypt_shared library.
Note
For a numeric value that can be compared against, use mongocrypt_crypt_shared_lib_version.

◆ mongocrypt_ctx_datakey_init()

MONGOCRYPT_EXPORT bool mongocrypt_ctx_datakey_init ( mongocrypt_ctx_t * ctx)

Initialize a context to create a data key.

Associated options:

Parameters
[in]ctxThe mongocrypt_ctx_t object.
Returns
A boolean indicating success. If false, an error status is set. Retrieve it with mongocrypt_ctx_status
Precondition
A master key option has been set, and an associated KMS provider has been set on the parent mongocrypt_t.

◆ mongocrypt_ctx_decrypt_init()

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 }

Parameters
[in]ctxThe mongocrypt_ctx_t object.
[in]docThe document to be decrypted. The viewed data is copied. It is valid to destroy doc with mongocrypt_binary_destroy immediately after.
Returns
A boolean indicating success. If false, an error status is set. Retrieve it with mongocrypt_ctx_status

◆ mongocrypt_ctx_destroy()

MONGOCRYPT_EXPORT void mongocrypt_ctx_destroy ( mongocrypt_ctx_t * ctx)

Destroy and free all memory associated with a mongocrypt_ctx_t.

Parameters
[in]ctxA mongocrypt_ctx_t.

◆ mongocrypt_ctx_encrypt_init()

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.

Parameters
[in]ctxThe mongocrypt_ctx_t object.
[in]dbThe database name.
[in]db_lenThe byte length of db. Pass -1 to determine the string length with strlen (must be NULL terminated).
[in]cmdThe BSON command to be encrypted. The viewed data is copied. It is valid to destroy cmd with mongocrypt_binary_destroy immediately after.
Returns
A boolean indicating success. If false, an error status is set. Retrieve it with mongocrypt_ctx_status

◆ mongocrypt_ctx_explicit_decrypt_init()

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) }

Parameters
[in]ctxA mongocrypt_ctx_t.
[in]msgA mongocrypt_binary_t the encrypted BSON. The viewed data is copied. It is valid to destroy msg with mongocrypt_binary_destroy immediately after.

◆ mongocrypt_ctx_explicit_encrypt_expression_init()

MONGOCRYPT_EXPORT bool mongocrypt_ctx_explicit_encrypt_expression_init ( mongocrypt_ctx_t * ctx,
mongocrypt_binary_t * msg )

Explicit helper method to encrypt a Match Expression or Aggregate Expression. Contexts created for explicit encryption will not go through mongocryptd. Requires query_type to be "range".

This method expects the passed-in BSON to be of the form: { "v" : FLE2RangeFindDriverSpec }

FLE2RangeFindDriverSpec is a BSON document with one of these forms:

  1. A Match Expression of this form: {$and: [{<field>: {<op>: <value1>, {<field>: {<op>: <value2> }}]}
  2. An Aggregate Expression of this form: {$and: [{<op>: [<fieldpath>, <value1>]}, {<op>: [<fieldpath>, <value2>]}]

<op> may be $lt, $lte, $gt, or $gte.

The value of "v" is expected to be the BSON value passed to a driver ClientEncryption.encryptExpression helper.

Associated options for FLE 1:

Associated options for Queryable Encryption:

An error is returned if FLE 1 and Queryable Encryption incompatible options are set.

Parameters
[in]ctxA mongocrypt_ctx_t.
[in]msgA mongocrypt_binary_t the plaintext BSON value. The viewed data is copied. It is valid to destroy msg with mongocrypt_binary_destroy immediately after.
Returns
A boolean indicating success. If false, an error status is set. Retrieve it with mongocrypt_ctx_status

◆ mongocrypt_ctx_explicit_encrypt_init()

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 }

The value of "v" is expected to be the BSON value passed to a driver ClientEncryption.encrypt helper.

Associated options for FLE 1:

Associated options for Queryable Encryption:

An error is returned if FLE 1 and Queryable Encryption incompatible options are set.

Parameters
[in]ctxA mongocrypt_ctx_t.
[in]msgA mongocrypt_binary_t the plaintext BSON value. The viewed data is copied. It is valid to destroy msg with mongocrypt_binary_destroy immediately after.
Returns
A boolean indicating success. If false, an error status is set. Retrieve it with mongocrypt_ctx_status

◆ mongocrypt_ctx_finalize()

MONGOCRYPT_EXPORT bool mongocrypt_ctx_finalize ( mongocrypt_ctx_t * ctx,
mongocrypt_binary_t * out )

Perform the final encryption or decryption.

Parameters
[in]ctxA mongocrypt_ctx_t.
[out]outThe 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.

Returns
a bool indicating success. If false, an error status is set. Retrieve it with mongocrypt_ctx_status

◆ mongocrypt_ctx_kms_done()

MONGOCRYPT_EXPORT bool mongocrypt_ctx_kms_done ( mongocrypt_ctx_t * ctx)

Call when done handling all KMS contexts.

Parameters
[in]ctxThe mongocrypt_ctx_t object.
Returns
A boolean indicating success. If false, an error status is set. Retrieve it with mongocrypt_ctx_status

◆ mongocrypt_ctx_mongo_db()

MONGOCRYPT_EXPORT const char * mongocrypt_ctx_mongo_db ( mongocrypt_ctx_t * ctx)

Get the database to run the mongo operation.

Only applies when mongocrypt_ctx_t is in the state: MONGOCRYPT_CTX_NEED_MONGO_COLLINFO_WITH_DB.

The lifetime of the returned string is tied to the lifetime of ctx. It is valid until mongocrypt_ctx_destroy is called.

Parameters
[in]ctxThe mongocrypt_ctx_t object.
Returns
A string or NULL. If NULL, an error status is set. Retrieve it with mongocrypt_ctx_status

◆ mongocrypt_ctx_mongo_done()

MONGOCRYPT_EXPORT bool mongocrypt_ctx_mongo_done ( mongocrypt_ctx_t * ctx)

Call when done feeding the reply (or replies) back to the context.

Parameters
[in]ctxThe mongocrypt_ctx_t object.
Returns
A boolean indicating success. If false, an error status is set. Retrieve it with mongocrypt_ctx_status

◆ mongocrypt_ctx_mongo_feed()

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.

  • For MONGOCRYPT_CTX_NEED_MONGO_COLLINFO(_WITH_DB) it is a doc from a listCollections cursor. (Note, if listCollections returned no result, do not call this function.)
  • For MONGOCRYPT_CTX_NEED_MONGO_KEYS it is a doc from a find cursor. (Note, if find returned no results, do not call this function. reply must not be NULL.)
  • For MONGOCRYPT_CTX_NEED_MONGO_MARKINGS it is a reply from mongocryptd.
Parameters
[in]ctxThe mongocrypt_ctx_t object.
[in]replyA BSON document for the MongoDB operation. The viewed data is copied. It is valid to destroy reply with mongocrypt_binary_destroy immediately after.
Returns
A boolean indicating success. If false, an error status is set. Retrieve it with mongocrypt_ctx_status

◆ mongocrypt_ctx_mongo_op()

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.

  • For MONGOCRYPT_CTX_NEED_MONGO_COLLINFO(_WITH_DB) it is a listCollections filter.
  • For MONGOCRYPT_CTX_NEED_MONGO_KEYS it is a find filter.
  • For MONGOCRYPT_CTX_NEED_MONGO_MARKINGS it is a command to send to mongocryptd.

The lifetime of op_bson is tied to the lifetime of ctx. It is valid until mongocrypt_ctx_destroy is called.

Parameters
[in]ctxThe mongocrypt_ctx_t object.
[out]op_bsonA 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.
Returns
A boolean indicating success. If false, an error status is set. Retrieve it with mongocrypt_ctx_status

◆ mongocrypt_ctx_new()

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.

Parameters
[in]cryptThe mongocrypt_t object.
Returns
A new context.

◆ mongocrypt_ctx_next_kms_ctx()

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.

The returned KMS handle does not outlive ctx.

Parameters
[in]ctxA mongocrypt_ctx_t.
Returns
a new mongocrypt_kms_ctx_t or NULL.

◆ mongocrypt_ctx_provide_kms_providers()

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.

Parameters
[in]ctxThe mongocrypt_ctx_t object.
[in]kms_providers_definitionA BSON document mapping the KMS provider names to credentials.
Returns
A boolean indicating success. If false, an error status is set. Retrieve it with mongocrypt_ctx_status.

◆ mongocrypt_ctx_rewrap_many_datakey_init()

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:

Parameters
[in]ctxThe mongocrypt_ctx_t object.
[in]filterThe filter to use for the find command on the key vault collection to retrieve datakeys to rewrap.
Returns
A boolean indicating success. If false, an error status is set. Retrieve it with mongocrypt_ctx_status.

◆ mongocrypt_ctx_setopt_algorithm()

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"

Parameters
[in]ctxThe mongocrypt_ctx_t object.
[in]algorithmA string specifying the algorithm to use for encryption.
[in]lenThe length of the algorithm string.
Precondition
ctx has not been initialized.
Returns
A boolean indicating success. If false, an error status is set. Retrieve it with mongocrypt_ctx_status

◆ mongocrypt_ctx_setopt_algorithm_range()

MONGOCRYPT_EXPORT bool mongocrypt_ctx_setopt_algorithm_range ( mongocrypt_ctx_t * ctx,
mongocrypt_binary_t * opts )

Set options for explicit encryption with the "range" algorithm.

opts is a BSON document of the form: { "min": Optional<BSON value>, "max": Optional<BSON value>, "sparsity": Optional<Int64>, "precision": Optional<Int32>, "trimFactor": Optional<Int32> }

Parameters
[in]ctxThe mongocrypt_ctx_t object.
[in]optsBSON.
Precondition
ctx has not been initialized.
Returns
A boolean indicating success. If false, an error status is set. Retrieve it with mongocrypt_ctx_status

◆ mongocrypt_ctx_setopt_contention_factor()

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.

Parameters
[in]ctxThe mongocrypt_ctx_t object.
[in]contention_factor
Precondition
ctx has not been initialized.
Returns
A boolean indicating success. If false, an error status is set. Retrieve it with mongocrypt_ctx_status.

◆ mongocrypt_ctx_setopt_index_key_id()

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.

Parameters
[in]ctxThe mongocrypt_ctx_t object.
[in]key_idThe 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.
Precondition
ctx has not been initialized.
Returns
A boolean indicating success. If false, an error status is set. Retrieve it with mongocrypt_ctx_status

◆ mongocrypt_ctx_setopt_key_alt_name()

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.

Parameters
[in]ctxThe mongocrypt_ctx_t object.
[in]key_alt_nameThe name to use. The viewed data is copied. It is valid to destroy key_alt_name with mongocrypt_binary_destroy immediately after.
Precondition
ctx has not been initialized.
Returns
A boolean indicating success. If false, an error status is set. Retrieve it with mongocrypt_ctx_status

◆ mongocrypt_ctx_setopt_key_encryption_key()

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.

Parameters
[in]ctxThe mongocrypt_ctx_t object.
[in]binBSON 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> }

Precondition
ctx has not been initialized.
Returns
A boolean indicating success. If false, an error status is set. Retrieve it with mongocrypt_ctx_status.

◆ mongocrypt_ctx_setopt_key_id()

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.

Parameters
[in]ctxThe mongocrypt_ctx_t object.
[in]key_idThe 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.
Precondition
ctx has not been initialized.
Returns
A boolean indicating success. If false, an error status is set. Retrieve it with mongocrypt_ctx_status

◆ mongocrypt_ctx_setopt_key_material()

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) }

Parameters
[in]ctxThe mongocrypt_ctx_t object.
[in]key_materialThe data encryption key to use. The viewed data is copied. It is valid to destroy key_material with mongocrypt_binary_destroy immediately after.
Precondition
ctx has not been initialized.
Returns
A boolean indicating success. If false, an error status is set. Retrieve it with mongocrypt_ctx_status

◆ mongocrypt_ctx_setopt_masterkey_aws()

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

Parameters
[in]ctxThe mongocrypt_ctx_t object.
[in]regionThe AWS region.
[in]region_lenThe string length of region. Pass -1 to determine the string length with strlen (must be NULL terminated).
[in]cmkThe Amazon Resource Name (ARN) of the customer master key (CMK).
[in]cmk_lenThe string length of cmk_len. Pass -1 to determine the string length with strlen (must be NULL terminated).
Precondition
ctx has not been initialized.
Returns
A boolean indicating success. If false, an error status is set. Retrieve it with mongocrypt_ctx_status

◆ mongocrypt_ctx_setopt_masterkey_aws_endpoint()

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

Parameters
[in]ctxThe mongocrypt_ctx_t object.
[in]endpointThe endpoint.
[in]endpoint_lenThe string length of endpoint. Pass -1 to determine the string length with strlen (must be NULL terminated).
Returns
A boolean indicating success. If false, an error status is set. Retrieve it with mongocrypt_ctx_status

◆ mongocrypt_ctx_setopt_masterkey_local()

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

Parameters
[in]ctxThe mongocrypt_ctx_t object.
Precondition
ctx has not been initialized.
Returns
A boolean indicating success. If false, an error status is set. Retrieve it with mongocrypt_ctx_status

◆ mongocrypt_ctx_setopt_query_type()

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.

Parameters
[in]ctxThe mongocrypt_ctx_t object.
[in]query_typeThe query type string
[in]lenThe length of query_type, or -1 for automatic
Precondition
ctx has not been initialized.
Returns
A boolean indicating success. If false, an error status is set. Retrieve it with mongocrypt_ctx_status

◆ mongocrypt_ctx_state()

MONGOCRYPT_EXPORT mongocrypt_ctx_state_t mongocrypt_ctx_state ( mongocrypt_ctx_t * ctx)

Get the current state of a context.

Parameters
[in]ctxThe mongocrypt_ctx_t object.
Returns
A mongocrypt_ctx_state_t.

◆ mongocrypt_ctx_status()

MONGOCRYPT_EXPORT bool mongocrypt_ctx_status ( mongocrypt_ctx_t * ctx,
mongocrypt_status_t * status )

Get the status associated with a mongocrypt_ctx_t object.

Parameters
[in]ctxThe mongocrypt_ctx_t object.
[out]statusReceives the status.
Returns
True if the output is an ok status, false if it is an error status.
See also
mongocrypt_status_ok

◆ mongocrypt_destroy()

MONGOCRYPT_EXPORT void mongocrypt_destroy ( mongocrypt_t * crypt)

Destroy the mongocrypt_t object.

Parameters
[in]cryptThe mongocrypt_t object to destroy.

◆ mongocrypt_init()

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.

Parameters
[in]cryptThe mongocrypt_t object.
Returns
A boolean indicating success. If false, an error status is set. Retrieve it with mongocrypt_ctx_status Failure may occur if previously set options are invalid.

◆ mongocrypt_is_crypto_available()

MONGOCRYPT_EXPORT bool mongocrypt_is_crypto_available ( void )

Returns true if libmongocrypt was built with native crypto support.

If libmongocrypt was not built with native crypto support, setting crypto hooks is required.

Returns
True if libmongocrypt was built with native crypto support.

◆ mongocrypt_kms_ctx_bytes_needed()

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.

Parameters
[in]kmsThe mongocrypt_kms_ctx_t.
Returns
The number of requested bytes.

◆ mongocrypt_kms_ctx_endpoint()

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.

Parameters
[in]kmsA mongocrypt_kms_ctx_t.
[out]endpointThe 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.
Returns
A boolean indicating success. If false, an error status is set. Retrieve it with mongocrypt_kms_ctx_status

◆ mongocrypt_kms_ctx_fail()

MONGOCRYPT_EXPORT bool mongocrypt_kms_ctx_fail ( mongocrypt_kms_ctx_t * kms)

Indicate a network-level failure.

Parameters
[in]kmsThe mongocrypt_kms_ctx_t.
Returns
A boolean indicating whether the failed request may be retried.

◆ mongocrypt_kms_ctx_feed()

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.

Parameters
[in]kmsThe mongocrypt_kms_ctx_t.
[in]bytesThe bytes to feed. The viewed data is copied. It is valid to destroy bytes with mongocrypt_binary_destroy immediately after.
Returns
A boolean indicating success. If false, an error status is set. Retrieve it with mongocrypt_kms_ctx_status

◆ mongocrypt_kms_ctx_get_kms_provider()

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.

Parameters
[in]kmsThe mongocrypt_kms_ctx_t object.
[out]lenReceives 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.
Returns
One of the NULL terminated static strings: "aws", "azure", "gcp", or "kmip".

◆ mongocrypt_kms_ctx_message()

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.

Parameters
[in]kmsA mongocrypt_kms_ctx_t.
[out]msgThe 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.
Returns
A boolean indicating success. If false, an error status is set. Retrieve it with mongocrypt_kms_ctx_status

◆ mongocrypt_kms_ctx_status()

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.

Parameters
[in]kmsThe mongocrypt_kms_ctx_t object.
[out]statusReceives the status.
Returns
A boolean indicating success. If false, an error status is set.

◆ mongocrypt_kms_ctx_usleep()

MONGOCRYPT_EXPORT int64_t mongocrypt_kms_ctx_usleep ( mongocrypt_kms_ctx_t * kms)

Indicates how long to sleep before sending this request.

Parameters
[in]kmsThe mongocrypt_kms_ctx_t.
Returns
How long to sleep in microseconds.

◆ mongocrypt_new()

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.

Returns
A new mongocrypt_t object.

◆ mongocrypt_setopt_aes_256_ctr()

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.

Parameters
[in]cryptThe mongocrypt_t object.
[in]aes_256_ctr_encryptThe crypto callback function for encrypt operation.
[in]aes_256_ctr_decryptThe crypto callback function for decrypt operation.
[in]ctxUnused.
Precondition
mongocrypt_init has not been called on crypt.
Returns
A boolean indicating success. If false, an error status is set. Retrieve it with mongocrypt_status

◆ mongocrypt_setopt_aes_256_ecb()

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.

Parameters
[in]cryptThe mongocrypt_t object.
[in]aes_256_ecb_encryptThe crypto callback function for encrypt operation.
[in]ctxUnused.
Precondition
mongocrypt_init has not been called on crypt.
Returns
A boolean indicating success. If false, an error status is set. Retrieve it with mongocrypt_status

◆ mongocrypt_setopt_append_crypt_shared_lib_search_path()

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.

Parameters
[in]cryptThe mongocrypt_t object to update
[in]pathA 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.
Note
If no crypt_shared dynamic library is found in any of the directories specified by the search paths loaded here, mongocrypt_init() will still succeed and continue to operate without crypt_shared.
The search paths are searched in the order that they are appended. This allows one to provide a precedence in how the library will be discovered. For example, appending known directories before appending "$SYSTEM" will allow one to supersede the system's installed library, but still fall-back to it if the library wasn't found otherwise. If one does not ever append "$SYSTEM", then the system's library-search mechanism will never be consulted.
If an absolute path to the library is specified using mongocrypt_setopt_set_crypt_shared_lib_path_override, then paths appended here will have no effect.

◆ mongocrypt_setopt_bypass_query_analysis()

MONGOCRYPT_EXPORT void mongocrypt_setopt_bypass_query_analysis ( mongocrypt_t * crypt)

Opt-into skipping query analysis.

If opted in:

  • The crypt_shared library will not attempt to be loaded.
  • A mongocrypt_ctx_t will never enter the MONGOCRYPT_CTX_NEED_MARKINGS state.
Parameters
[in]cryptThe mongocrypt_t object to update

◆ mongocrypt_setopt_crypto_hook_sign_rsaes_pkcs1_v1_5()

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

Parameters
[in]cryptThe mongocrypt_t object.
[in]sign_rsaes_pkcs1_v1_5The crypto callback function.
[in]sign_ctxA context passed as an argument to the crypto callback every invocation.
Precondition
mongocrypt_init has not been called on crypt.
Returns
A boolean indicating success. If false, an error status is set. Retrieve it with mongocrypt_status

◆ mongocrypt_setopt_enable_multiple_collinfo()

MONGOCRYPT_EXPORT bool mongocrypt_setopt_enable_multiple_collinfo ( mongocrypt_t * crypt)

Enable support for multiple collection schemas. Required to support $lookup.

Parameters
[in]cryptThe mongocrypt_t object.
Precondition
mongocrypt_init has not been called on crypt.
Returns
A boolean indicating success. If false, an error status is set. Retrieve it with mongocrypt_ctx_status

◆ mongocrypt_setopt_encrypted_field_config_map()

MONGOCRYPT_EXPORT bool mongocrypt_setopt_encrypted_field_config_map ( mongocrypt_t * crypt,
mongocrypt_binary_t * efc_map )

Set a local EncryptedFieldConfigMap for encryption.

Parameters
[in]cryptThe mongocrypt_t object.
[in]efc_mapA 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.
Precondition
crypt has not been initialized.
Returns
A boolean indicating success. If false, an error status is set. Retrieve it with mongocrypt_status

◆ mongocrypt_setopt_key_expiration()

MONGOCRYPT_EXPORT bool mongocrypt_setopt_key_expiration ( mongocrypt_t * crypt,
uint64_t cache_expiration_ms )

Set the expiration time for the data encryption key cache. Defaults to 60 seconds if not set.

Parameters
[in]ctxThe mongocrypt_ctx_t object.
[in]cache_expiration_msThe cache expiration time in milliseconds. If zero, the cache never expires.

◆ mongocrypt_setopt_kms_provider_aws()

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

Parameters
[in]cryptThe mongocrypt_t object.
[in]aws_access_key_idThe AWS access key ID used to generate KMS messages.
[in]aws_access_key_id_lenThe 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_keyThe AWS secret access key used to generate KMS messages.
[in]aws_secret_access_key_lenThe string length (in bytes) of aws_secret_access_key. Pass -1 to determine the string length with strlen (must be NULL terminated).
Precondition
mongocrypt_init has not been called on crypt.
Returns
A boolean indicating success. If false, an error status is set. Retrieve it with mongocrypt_ctx_status

◆ mongocrypt_setopt_kms_provider_local()

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

Parameters
[in]cryptThe mongocrypt_t object.
[in]keyA 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.
Precondition
mongocrypt_init has not been called on crypt.
Returns
A boolean indicating success. If false, an error status is set. Retrieve it with mongocrypt_ctx_status

◆ mongocrypt_setopt_kms_providers()

MONGOCRYPT_EXPORT bool mongocrypt_setopt_kms_providers ( mongocrypt_t * crypt,
mongocrypt_binary_t * kms_providers )

Configure KMS providers with a BSON document.

Parameters
[in]cryptThe mongocrypt_t object.
[in]kms_providersA 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.
Precondition
mongocrypt_init has not been called on crypt.
Returns
A boolean indicating success. If false, an error status is set. Retrieve it with mongocrypt_ctx_status

◆ mongocrypt_setopt_log_handler()

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.

Parameters
[in]cryptThe mongocrypt_t object.
[in]log_fnThe log callback.
[in]log_ctxA context passed as an argument to the log callback every invocation.
Precondition
mongocrypt_init has not been called on crypt.
Returns
A boolean indicating success. If false, an error status is set. Retrieve it with mongocrypt_ctx_status

◆ mongocrypt_setopt_retry_kms()

MONGOCRYPT_EXPORT bool mongocrypt_setopt_retry_kms ( mongocrypt_t * crypt,
bool enable )

Enable or disable KMS retry behavior.

Parameters
[in]cryptThe mongocrypt_t object.
[in]enableA boolean indicating whether to retry operations.
Precondition
mongocrypt_init has not been called on crypt.
Returns
A boolean indicating success. If false, an error status is set. Retrieve it with mongocrypt_ctx_status

◆ mongocrypt_setopt_schema_map()

MONGOCRYPT_EXPORT bool mongocrypt_setopt_schema_map ( mongocrypt_t * crypt,
mongocrypt_binary_t * schema_map )

Set a local schema map for encryption.

Parameters
[in]cryptThe mongocrypt_t object.
[in]schema_mapA 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.
Precondition
crypt has not been initialized.
Returns
A boolean indicating success. If false, an error status is set. Retrieve it with mongocrypt_status

◆ mongocrypt_setopt_set_crypt_shared_lib_path_override()

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.

Parameters
[in]cryptThe mongocrypt_t object to update
[in]pathA 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.
Note
This function will do no IO nor path validation. All validation will occur during the call to mongocrypt_init.
If a crypt_shared library path override is specified here, then no paths given to mongocrypt_setopt_append_crypt_shared_lib_search_path will be consulted when opening the crypt_shared library.
If a path is provided via this API and mongocrypt_init fails to initialize a valid crypt_shared library instance for the path specified, then the initialization of mongocrypt_t will fail with an error.

◆ mongocrypt_setopt_use_need_kms_credentials_state()

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.

Parameters
[in]cryptThe mongocrypt_t object to update

◆ mongocrypt_setopt_use_need_mongo_collinfo_with_db_state()

MONGOCRYPT_EXPORT void mongocrypt_setopt_use_need_mongo_collinfo_with_db_state ( mongocrypt_t * crypt)

Opt-into handling the MONGOCRYPT_CTX_NEED_MONGO_COLLINFO_WITH_DB state.

A context enters the MONGOCRYPT_CTX_NEED_MONGO_COLLINFO_WITH_DB state when processing a bulkWrite command. The target database of the bulkWrite may differ from the command database ("admin").

Parameters
[in]cryptThe mongocrypt_t object to update

◆ mongocrypt_setopt_use_range_v2()

MONGOCRYPT_EXPORT bool mongocrypt_setopt_use_range_v2 ( mongocrypt_t * crypt)

DEPRECATED: Use of mongocrypt_setopt_use_range_v2 is deprecated. Range V2 is always enabled.

Parameters
[in]cryptThe mongocrypt_t object.
Returns
A boolean indicating success. If false, an error status is set. Retrieve it with mongocrypt_status

◆ mongocrypt_status()

MONGOCRYPT_EXPORT bool mongocrypt_status ( mongocrypt_t * crypt,
mongocrypt_status_t * status )

Get the status associated with a mongocrypt_t object.

Parameters
[in]cryptThe mongocrypt_t object.
[out]statusReceives the status.
Returns
A boolean indicating success. If false, an error status is set. Retrieve it with mongocrypt_ctx_status

◆ mongocrypt_status_code()

MONGOCRYPT_EXPORT uint32_t mongocrypt_status_code ( mongocrypt_status_t * status)

Get an error code or 0.

Parameters
[in]statusThe status object.
Returns
An error code.

◆ mongocrypt_status_destroy()

MONGOCRYPT_EXPORT void mongocrypt_status_destroy ( mongocrypt_status_t * status)

Free the memory for a status object.

Parameters
[in]statusThe status to destroy.

◆ mongocrypt_status_message()

MONGOCRYPT_EXPORT const char * mongocrypt_status_message ( mongocrypt_status_t * status,
uint32_t * len )

Get the error message associated with a status or NULL.

Parameters
[in]statusThe status object.
[out]lenAn optional length of the returned string (excluding the trailing NULL byte). May be NULL.
Returns
A NULL terminated error message or NULL.

◆ mongocrypt_status_new()

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.

Returns
A new status object.

◆ mongocrypt_status_ok()

MONGOCRYPT_EXPORT bool mongocrypt_status_ok ( mongocrypt_status_t * status)

Returns true if the status indicates success.

Parameters
[in]statusThe status to check.
Returns
A boolean indicating success. If false, an error status is set. Retrieve it with mongocrypt_ctx_status

◆ mongocrypt_status_set()

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.

Parameters
[in]typeThe status type.
[in]codeThe status code.
[in]messageThe message.
[in]message_lenDue 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_status_type()

MONGOCRYPT_EXPORT mongocrypt_status_type_t mongocrypt_status_type ( mongocrypt_status_t * status)

Indicates success or the type of error.

Parameters
[in]statusThe status object.
Returns
A mongocrypt_status_type_t.

◆ mongocrypt_version()

MONGOCRYPT_EXPORT const char * mongocrypt_version ( uint32_t * len)

Returns the version string for libmongocrypt.

Parameters
[out]lenAn optional length of the returned string. May be NULL.
Returns
a NULL terminated version string for libmongocrypt.