libmongocrypt
mongocrypt.h
Go to the documentation of this file.
1/*
2 * Copyright 2019-present MongoDB, Inc.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16#ifndef MONGOCRYPT_H
17#define MONGOCRYPT_H
18
26#include "mongocrypt-compat.h"
27#include "mongocrypt-export.h"
28
29/* clang-format off */
30#ifndef __has_include
31 #include "mongocrypt-config.h"
32#else
33 #if __has_include("mongocrypt-config.h")
34 #include "mongocrypt-config.h"
35 #else
36 #error No "mongocrypt-config.h" header is available. That file must \
37 be generated in order to use libmongocrypt.
38 #endif
39#endif
40/* clang-format on */
41
48MONGOCRYPT_EXPORT
49const char *mongocrypt_version(uint32_t *len);
50
59MONGOCRYPT_EXPORT
61
87typedef struct _mongocrypt_binary_t {
88 void *data;
89 uint32_t len;
91
99MONGOCRYPT_EXPORT
101
111MONGOCRYPT_EXPORT
113
121MONGOCRYPT_EXPORT
123
131MONGOCRYPT_EXPORT
133
141MONGOCRYPT_EXPORT
143
152typedef struct _mongocrypt_status_t mongocrypt_status_t;
153
157typedef enum {
158 MONGOCRYPT_STATUS_OK = 0,
159 MONGOCRYPT_STATUS_ERROR_CLIENT = 1,
160 MONGOCRYPT_STATUS_ERROR_KMS = 2,
161 MONGOCRYPT_STATUS_ERROR_CRYPT_SHARED = 3,
163
173MONGOCRYPT_EXPORT
175
192MONGOCRYPT_EXPORT
195 uint32_t code,
196 const char *message,
197 int32_t message_len);
198
206MONGOCRYPT_EXPORT
208
216MONGOCRYPT_EXPORT
218
228MONGOCRYPT_EXPORT
229const char *mongocrypt_status_message(mongocrypt_status_t *status, uint32_t *len);
230
239MONGOCRYPT_EXPORT
241
247MONGOCRYPT_EXPORT
249
253typedef enum {
254 MONGOCRYPT_LOG_LEVEL_FATAL = 0,
255 MONGOCRYPT_LOG_LEVEL_ERROR = 1,
256 MONGOCRYPT_LOG_LEVEL_WARNING = 2,
257 MONGOCRYPT_LOG_LEVEL_INFO = 3,
258 MONGOCRYPT_LOG_LEVEL_TRACE = 4
260
270typedef void (*mongocrypt_log_fn_t)(mongocrypt_log_level_t level, const char *message, uint32_t message_len, void *ctx);
271
284typedef struct _mongocrypt_t mongocrypt_t;
285
295MONGOCRYPT_EXPORT
297
310MONGOCRYPT_EXPORT
312
334MONGOCRYPT_EXPORT
336 const char *aws_access_key_id,
337 int32_t aws_access_key_id_len,
338 const char *aws_secret_access_key,
339 int32_t aws_secret_access_key_len);
340
355MONGOCRYPT_EXPORT
357
369MONGOCRYPT_EXPORT
371
384MONGOCRYPT_EXPORT
386
399MONGOCRYPT_EXPORT
401
430MONGOCRYPT_EXPORT
432
456MONGOCRYPT_EXPORT
458
473MONGOCRYPT_EXPORT
475
485MONGOCRYPT_EXPORT
487
501MONGOCRYPT_EXPORT
503
513MONGOCRYPT_EXPORT
515
521MONGOCRYPT_EXPORT
523
542MONGOCRYPT_EXPORT
543const char *mongocrypt_crypt_shared_lib_version_string(const mongocrypt_t *crypt, uint32_t *len);
544
564MONGOCRYPT_EXPORT
566
570typedef struct _mongocrypt_ctx_t mongocrypt_ctx_t;
571
581MONGOCRYPT_EXPORT
583
595MONGOCRYPT_EXPORT
597
612MONGOCRYPT_EXPORT
614
637MONGOCRYPT_EXPORT
639
655MONGOCRYPT_EXPORT
657
678MONGOCRYPT_EXPORT
679bool mongocrypt_ctx_setopt_algorithm(mongocrypt_ctx_t *ctx, const char *algorithm, int len);
680
682#define MONGOCRYPT_ALGORITHM_DETERMINISTIC_STR "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"
684#define MONGOCRYPT_ALGORITHM_RANDOM_STR "AEAD_AES_256_CBC_HMAC_SHA_512-Random"
686#define MONGOCRYPT_ALGORITHM_INDEXED_STR "Indexed"
688#define MONGOCRYPT_ALGORITHM_UNINDEXED_STR "Unindexed"
692#define MONGOCRYPT_ALGORITHM_RANGEPREVIEW_DEPRECATED_STR "RangePreview"
693#define MONGOCRYPT_ALGORITHM_RANGE_STR "Range"
694
713MONGOCRYPT_EXPORT
715 const char *region,
716 int32_t region_len,
717 const char *cmk,
718 int32_t cmk_len);
719
737MONGOCRYPT_EXPORT
738bool mongocrypt_ctx_setopt_masterkey_aws_endpoint(mongocrypt_ctx_t *ctx, const char *endpoint, int32_t endpoint_len);
739
750MONGOCRYPT_EXPORT
752
804MONGOCRYPT_EXPORT
806
821MONGOCRYPT_EXPORT
823
838MONGOCRYPT_EXPORT
839bool mongocrypt_ctx_encrypt_init(mongocrypt_ctx_t *ctx, const char *db, int32_t db_len, mongocrypt_binary_t *cmd);
840
876MONGOCRYPT_EXPORT
878
924MONGOCRYPT_EXPORT
926
940MONGOCRYPT_EXPORT
942
956MONGOCRYPT_EXPORT
958
971MONGOCRYPT_EXPORT
973
980typedef enum {
981 MONGOCRYPT_CTX_ERROR = 0,
982 MONGOCRYPT_CTX_NEED_MONGO_COLLINFO = 1, /* run on main MongoClient */
983 MONGOCRYPT_CTX_NEED_MONGO_COLLINFO_WITH_DB = 8, /* run on main MongoClient */
984 MONGOCRYPT_CTX_NEED_MONGO_MARKINGS = 2, /* run on mongocryptd. */
985 MONGOCRYPT_CTX_NEED_MONGO_KEYS = 3, /* run on key vault */
986 MONGOCRYPT_CTX_NEED_KMS = 4,
987 MONGOCRYPT_CTX_NEED_KMS_CREDENTIALS = 7, /* fetch/renew KMS credentials */
988 MONGOCRYPT_CTX_READY = 5, /* ready for encryption/decryption */
989 MONGOCRYPT_CTX_DONE = 6,
991
998MONGOCRYPT_EXPORT
1000
1021MONGOCRYPT_EXPORT
1023
1037MONGOCRYPT_EXPORT
1039
1062MONGOCRYPT_EXPORT
1064
1072MONGOCRYPT_EXPORT
1074
1078typedef struct _mongocrypt_kms_ctx_t mongocrypt_kms_ctx_t;
1079
1093MONGOCRYPT_EXPORT
1095
1109MONGOCRYPT_EXPORT
1111
1126MONGOCRYPT_EXPORT
1127bool mongocrypt_kms_ctx_endpoint(mongocrypt_kms_ctx_t *kms, const char **endpoint);
1128
1135MONGOCRYPT_EXPORT
1137
1150MONGOCRYPT_EXPORT
1152
1161MONGOCRYPT_EXPORT
1163
1179MONGOCRYPT_EXPORT
1181
1190MONGOCRYPT_EXPORT
1192
1207MONGOCRYPT_EXPORT
1209
1246MONGOCRYPT_EXPORT
1248
1254MONGOCRYPT_EXPORT
1256
1274typedef bool (*mongocrypt_crypto_fn)(void *ctx,
1279 uint32_t *bytes_written,
1280 mongocrypt_status_t *status);
1281
1299typedef bool (*mongocrypt_hmac_fn)(void *ctx,
1303 mongocrypt_status_t *status);
1304
1318typedef bool (*mongocrypt_hash_fn)(void *ctx,
1321 mongocrypt_status_t *status);
1322
1336typedef bool (*mongocrypt_random_fn)(void *ctx, mongocrypt_binary_t *out, uint32_t count, mongocrypt_status_t *status);
1337
1338MONGOCRYPT_EXPORT
1339bool mongocrypt_setopt_crypto_hooks(mongocrypt_t *crypt,
1340 mongocrypt_crypto_fn aes_256_cbc_encrypt,
1341 mongocrypt_crypto_fn aes_256_cbc_decrypt,
1342 mongocrypt_random_fn random,
1343 mongocrypt_hmac_fn hmac_sha_512,
1344 mongocrypt_hmac_fn hmac_sha_256,
1345 mongocrypt_hash_fn sha_256,
1346 void *ctx);
1347
1362MONGOCRYPT_EXPORT
1364 mongocrypt_crypto_fn aes_256_ctr_encrypt,
1365 mongocrypt_crypto_fn aes_256_ctr_decrypt,
1366 void *ctx);
1367
1382MONGOCRYPT_EXPORT
1383bool mongocrypt_setopt_aes_256_ecb(mongocrypt_t *crypt, mongocrypt_crypto_fn aes_256_ecb_encrypt, void *ctx);
1384
1402MONGOCRYPT_EXPORT
1404 mongocrypt_hmac_fn sign_rsaes_pkcs1_v1_5,
1405 void *sign_ctx);
1406
1416MONGOCRYPT_EXPORT
1418
1427MONGOCRYPT_EXPORT
1429
1440MONGOCRYPT_EXPORT
1441bool mongocrypt_ctx_setopt_contention_factor(mongocrypt_ctx_t *ctx, int64_t contention_factor);
1442
1458MONGOCRYPT_EXPORT
1460
1471MONGOCRYPT_EXPORT
1472bool mongocrypt_ctx_setopt_query_type(mongocrypt_ctx_t *ctx, const char *query_type, int len);
1473
1492MONGOCRYPT_EXPORT
1494
1496#define MONGOCRYPT_QUERY_TYPE_EQUALITY_STR "equality"
1497// 'rangePreview' is deprecated in favor of range.
1500#define MONGOCRYPT_QUERY_TYPE_RANGEPREVIEW_DEPRECATED_STR "rangePreview"
1501#define MONGOCRYPT_QUERY_TYPE_RANGE_STR "range"
1502
1503#endif /* MONGOCRYPT_H */
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_binary_t * mongocrypt_binary_new(void)
struct _mongocrypt_kms_ctx_t mongocrypt_kms_ctx_t
Definition: mongocrypt.h:1078
MONGOCRYPT_EXPORT uint32_t mongocrypt_binary_len(const mongocrypt_binary_t *binary)
MONGOCRYPT_EXPORT const char * mongocrypt_kms_ctx_get_kms_provider(mongocrypt_kms_ctx_t *kms, uint32_t *len)
MONGOCRYPT_EXPORT bool mongocrypt_status(mongocrypt_t *crypt, mongocrypt_status_t *status)
MONGOCRYPT_EXPORT bool mongocrypt_ctx_setopt_algorithm_range(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *opts)
MONGOCRYPT_EXPORT bool mongocrypt_ctx_setopt_key_id(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *key_id)
MONGOCRYPT_EXPORT const char * mongocrypt_version(uint32_t *len)
MONGOCRYPT_EXPORT bool mongocrypt_ctx_setopt_index_key_id(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *key_id)
MONGOCRYPT_EXPORT bool mongocrypt_ctx_setopt_key_material(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *key_material)
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_ctx_decrypt_init(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *doc)
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 bool mongocrypt_kms_ctx_status(mongocrypt_kms_ctx_t *kms, mongocrypt_status_t *status)
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 const char * mongocrypt_crypt_shared_lib_version_string(const mongocrypt_t *crypt, uint32_t *len)
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)
Definition: mongocrypt.h:1274
MONGOCRYPT_EXPORT mongocrypt_status_type_t mongocrypt_status_type(mongocrypt_status_t *status)
MONGOCRYPT_EXPORT bool mongocrypt_is_crypto_available(void)
MONGOCRYPT_EXPORT void mongocrypt_ctx_destroy(mongocrypt_ctx_t *ctx)
MONGOCRYPT_EXPORT void mongocrypt_binary_destroy(mongocrypt_binary_t *binary)
MONGOCRYPT_EXPORT bool mongocrypt_setopt_encrypted_field_config_map(mongocrypt_t *crypt, mongocrypt_binary_t *efc_map)
mongocrypt_status_type_t
Definition: mongocrypt.h:157
mongocrypt_log_level_t
Definition: mongocrypt.h:253
MONGOCRYPT_EXPORT bool mongocrypt_init(mongocrypt_t *crypt)
MONGOCRYPT_EXPORT bool mongocrypt_ctx_setopt_contention_factor(mongocrypt_ctx_t *ctx, int64_t contention_factor)
MONGOCRYPT_EXPORT bool mongocrypt_ctx_encrypt_init(mongocrypt_ctx_t *ctx, const char *db, int32_t db_len, mongocrypt_binary_t *cmd)
MONGOCRYPT_EXPORT mongocrypt_ctx_t * mongocrypt_ctx_new(mongocrypt_t *crypt)
struct _mongocrypt_ctx_t mongocrypt_ctx_t
Definition: mongocrypt.h:570
MONGOCRYPT_EXPORT bool mongocrypt_setopt_use_range_v2(mongocrypt_t *crypt)
Opt-into use of Queryable Encryption Range V2 protocol.
MONGOCRYPT_EXPORT bool mongocrypt_ctx_setopt_masterkey_local(mongocrypt_ctx_t *ctx)
MONGOCRYPT_EXPORT uint32_t mongocrypt_kms_ctx_bytes_needed(mongocrypt_kms_ctx_t *kms)
MONGOCRYPT_EXPORT bool mongocrypt_setopt_kms_providers(mongocrypt_t *crypt, mongocrypt_binary_t *kms_providers)
MONGOCRYPT_EXPORT bool mongocrypt_setopt_log_handler(mongocrypt_t *crypt, mongocrypt_log_fn_t log_fn, void *log_ctx)
struct _mongocrypt_binary_t mongocrypt_binary_t
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 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 void mongocrypt_destroy(mongocrypt_t *crypt)
MONGOCRYPT_EXPORT uint32_t mongocrypt_status_code(mongocrypt_status_t *status)
MONGOCRYPT_EXPORT bool mongocrypt_ctx_explicit_decrypt_init(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *msg)
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 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 bool mongocrypt_ctx_kms_done(mongocrypt_ctx_t *ctx)
bool(* mongocrypt_hash_fn)(void *ctx, mongocrypt_binary_t *in, mongocrypt_binary_t *out, mongocrypt_status_t *status)
Definition: mongocrypt.h:1318
MONGOCRYPT_EXPORT bool mongocrypt_ctx_setopt_key_encryption_key(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *bin)
bool(* mongocrypt_random_fn)(void *ctx, mongocrypt_binary_t *out, uint32_t count, mongocrypt_status_t *status)
Definition: mongocrypt.h:1336
MONGOCRYPT_EXPORT mongocrypt_ctx_state_t mongocrypt_ctx_state(mongocrypt_ctx_t *ctx)
MONGOCRYPT_EXPORT bool mongocrypt_kms_ctx_message(mongocrypt_kms_ctx_t *kms, mongocrypt_binary_t *msg)
MONGOCRYPT_EXPORT bool mongocrypt_ctx_mongo_feed(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *reply)
MONGOCRYPT_EXPORT bool mongocrypt_ctx_provide_kms_providers(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *kms_providers_definition)
MONGOCRYPT_EXPORT const char * mongocrypt_status_message(mongocrypt_status_t *status, uint32_t *len)
MONGOCRYPT_EXPORT bool mongocrypt_ctx_datakey_init(mongocrypt_ctx_t *ctx)
MONGOCRYPT_EXPORT bool mongocrypt_kms_ctx_feed(mongocrypt_kms_ctx_t *kms, mongocrypt_binary_t *bytes)
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 bool mongocrypt_status_ok(mongocrypt_status_t *status)
mongocrypt_ctx_state_t
Definition: mongocrypt.h:980
MONGOCRYPT_EXPORT bool mongocrypt_ctx_setopt_masterkey_aws_endpoint(mongocrypt_ctx_t *ctx, const char *endpoint, int32_t endpoint_len)
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_kms_ctx_endpoint(mongocrypt_kms_ctx_t *kms, const char **endpoint)
MONGOCRYPT_EXPORT uint8_t * mongocrypt_binary_data(const mongocrypt_binary_t *binary)
MONGOCRYPT_EXPORT bool mongocrypt_ctx_setopt_query_type(mongocrypt_ctx_t *ctx, const char *query_type, int len)
struct _mongocrypt_t mongocrypt_t
Definition: mongocrypt.h:284
MONGOCRYPT_EXPORT bool mongocrypt_ctx_finalize(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *out)
MONGOCRYPT_EXPORT bool mongocrypt_setopt_kms_provider_local(mongocrypt_t *crypt, mongocrypt_binary_t *key)
MONGOCRYPT_EXPORT bool mongocrypt_setopt_aes_256_ecb(mongocrypt_t *crypt, mongocrypt_crypto_fn aes_256_ecb_encrypt, void *ctx)
MONGOCRYPT_EXPORT bool mongocrypt_ctx_setopt_algorithm(mongocrypt_ctx_t *ctx, const char *algorithm, int len)
void(* mongocrypt_log_fn_t)(mongocrypt_log_level_t level, const char *message, uint32_t message_len, void *ctx)
Definition: mongocrypt.h:270
MONGOCRYPT_EXPORT mongocrypt_t * mongocrypt_new(void)
MONGOCRYPT_EXPORT bool mongocrypt_ctx_explicit_encrypt_init(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *msg)
MONGOCRYPT_EXPORT mongocrypt_status_t * mongocrypt_status_new(void)
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 mongocrypt_binary_t * mongocrypt_binary_new_from_data(uint8_t *data, uint32_t len)
MONGOCRYPT_EXPORT bool mongocrypt_ctx_explicit_encrypt_expression_init(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *msg)
MONGOCRYPT_EXPORT bool mongocrypt_setopt_schema_map(mongocrypt_t *crypt, mongocrypt_binary_t *schema_map)
MONGOCRYPT_EXPORT void mongocrypt_setopt_bypass_query_analysis(mongocrypt_t *crypt)
Opt-into skipping query analysis.
MONGOCRYPT_EXPORT bool mongocrypt_ctx_mongo_done(mongocrypt_ctx_t *ctx)
MONGOCRYPT_EXPORT bool mongocrypt_ctx_status(mongocrypt_ctx_t *ctx, mongocrypt_status_t *status)
MONGOCRYPT_EXPORT bool mongocrypt_ctx_setopt_key_alt_name(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *key_alt_name)
MONGOCRYPT_EXPORT void mongocrypt_status_destroy(mongocrypt_status_t *status)
bool(* mongocrypt_hmac_fn)(void *ctx, mongocrypt_binary_t *key, mongocrypt_binary_t *in, mongocrypt_binary_t *out, mongocrypt_status_t *status)
Definition: mongocrypt.h:1299
struct _mongocrypt_status_t mongocrypt_status_t
Definition: mongocrypt.h:152
MONGOCRYPT_EXPORT bool mongocrypt_ctx_mongo_op(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *op_bson)
MONGOCRYPT_EXPORT mongocrypt_kms_ctx_t * mongocrypt_ctx_next_kms_ctx(mongocrypt_ctx_t *ctx)
MONGOCRYPT_EXPORT const char * mongocrypt_ctx_mongo_db(mongocrypt_ctx_t *ctx)
Definition: mongocrypt.h:87