libmongocrypt
Macros | Typedefs | Enumerations | Functions
mongocrypt.h File Reference
#include "mongocrypt-export.h"
#include "mongocrypt-compat.h"
#include "mongocrypt-config.h"

Go to the source code of this file.

Macros

#define MONGOCRYPT_VERSION   "1.0.1"
 

Typedefs

typedef struct _mongocrypt_binary_t mongocrypt_binary_t
 
typedef struct _mongocrypt_status_t mongocrypt_status_t
 
typedef void(* mongocrypt_log_fn_t) (mongocrypt_log_level_t level, const char *message, uint32_t message_len, void *ctx)
 
typedef struct _mongocrypt_t mongocrypt_t
 
typedef struct _mongocrypt_ctx_t mongocrypt_ctx_t
 
typedef struct _mongocrypt_kms_ctx_t mongocrypt_kms_ctx_t
 
typedef bool(* mongocrypt_crypto_fn) (void *ctx, mongocrypt_binary_t *key, mongocrypt_binary_t *iv, mongocrypt_binary_t *in, mongocrypt_binary_t *out, uint32_t *bytes_written, mongocrypt_status_t *status)
 
typedef bool(* mongocrypt_hmac_fn) (void *ctx, mongocrypt_binary_t *key, mongocrypt_binary_t *in, mongocrypt_binary_t *out, mongocrypt_status_t *status)
 
typedef bool(* mongocrypt_hash_fn) (void *ctx, mongocrypt_binary_t *in, mongocrypt_binary_t *out, mongocrypt_status_t *status)
 
typedef bool(* mongocrypt_random_fn) (void *ctx, mongocrypt_binary_t *out, uint32_t count, mongocrypt_status_t *status)
 

Enumerations

enum  mongocrypt_status_type_t { MONGOCRYPT_STATUS_OK = 0, MONGOCRYPT_STATUS_ERROR_CLIENT = 1, MONGOCRYPT_STATUS_ERROR_KMS = 2 }
 
enum  mongocrypt_log_level_t {
  MONGOCRYPT_LOG_LEVEL_FATAL = 0, MONGOCRYPT_LOG_LEVEL_ERROR = 1, MONGOCRYPT_LOG_LEVEL_WARNING = 2, MONGOCRYPT_LOG_LEVEL_INFO = 3,
  MONGOCRYPT_LOG_LEVEL_TRACE = 4
}
 
enum  mongocrypt_ctx_state_t {
  MONGOCRYPT_CTX_ERROR = 0, MONGOCRYPT_CTX_NEED_MONGO_COLLINFO = 1, MONGOCRYPT_CTX_NEED_MONGO_MARKINGS = 2, MONGOCRYPT_CTX_NEED_MONGO_KEYS = 3,
  MONGOCRYPT_CTX_NEED_KMS = 4, MONGOCRYPT_CTX_READY = 5, MONGOCRYPT_CTX_DONE = 6
}
 

Functions

MONGOCRYPT_EXPORT const char * mongocrypt_version (uint32_t *len)
 
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_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_schema_map (mongocrypt_t *crypt, mongocrypt_binary_t *schema_map)
 
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 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_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_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 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_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 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 bool mongocrypt_ctx_kms_done (mongocrypt_ctx_t *ctx)
 
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)
 

Detailed Description

The top-level handle to libmongocrypt.

Macro Definition Documentation

◆ MONGOCRYPT_VERSION

#define MONGOCRYPT_VERSION   "1.0.1"

The version string describing libmongocrypt. Has the form x.y.z-

+<date>+git<sha>.

Typedef Documentation

◆ mongocrypt_binary_t

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:

// The viewed data of bin has been copied. Ok to free the view and the data.
my_free_fn (mydata);

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.

◆ 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 indiciating the error using mongocrypt_status_ste.

◆ 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 indiciating the error using mongocrypt_status_ste.

◆ 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 HMAC SHA-512 or SHA-256 function.

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 indiciating the error using mongocrypt_status_ste.

◆ 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 indiciating the error using mongocrypt_status_ste.

◆ 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_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.

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

Associated options:

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.

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

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

◆ 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_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_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_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.

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.

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.

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_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_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 hostname as a NULL terminated string. This may include a port (e.g. "example.com:123"). If it does not, default to port 443.
Returns
A boolean indicating success. If false, an error status is set. Retrieve it with mongocrypt_kms_ctx_status

◆ 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_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_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_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.

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.

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_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 invokation.
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_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.