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-export.h"
27#include "mongocrypt-compat.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 *
50mongocrypt_version (uint32_t *len);
51
52
75typedef struct _mongocrypt_binary_t mongocrypt_binary_t;
76
77
85MONGOCRYPT_EXPORT
88
89
99MONGOCRYPT_EXPORT
101mongocrypt_binary_new_from_data (uint8_t *data, uint32_t len);
102
103
111MONGOCRYPT_EXPORT
112uint8_t *
114
115
123MONGOCRYPT_EXPORT
124uint32_t
126
127
135MONGOCRYPT_EXPORT
136void
138
139
148typedef struct _mongocrypt_status_t mongocrypt_status_t;
149
153typedef enum {
154 MONGOCRYPT_STATUS_OK = 0,
155 MONGOCRYPT_STATUS_ERROR_CLIENT = 1,
156 MONGOCRYPT_STATUS_ERROR_KMS = 2,
157 MONGOCRYPT_STATUS_ERROR_CRYPT_SHARED = 3,
159
160
170MONGOCRYPT_EXPORT
173
174
191MONGOCRYPT_EXPORT
192void
195 uint32_t code,
196 const char *message,
197 int32_t message_len);
198
199
207MONGOCRYPT_EXPORT
210
211
219MONGOCRYPT_EXPORT
220uint32_t
222
223
233MONGOCRYPT_EXPORT
234const char *
236
237
246MONGOCRYPT_EXPORT
247bool
249
250
256MONGOCRYPT_EXPORT
257void
259
263typedef enum {
264 MONGOCRYPT_LOG_LEVEL_FATAL = 0,
265 MONGOCRYPT_LOG_LEVEL_ERROR = 1,
266 MONGOCRYPT_LOG_LEVEL_WARNING = 2,
267 MONGOCRYPT_LOG_LEVEL_INFO = 3,
268 MONGOCRYPT_LOG_LEVEL_TRACE = 4
270
271
282 const char *message,
283 uint32_t message_len,
284 void *ctx);
285
286
299typedef struct _mongocrypt_t mongocrypt_t;
300
301
311MONGOCRYPT_EXPORT
314
315
328MONGOCRYPT_EXPORT
329bool
331 mongocrypt_log_fn_t log_fn,
332 void *log_ctx);
333
334
356MONGOCRYPT_EXPORT
357bool
359 const char *aws_access_key_id,
360 int32_t aws_access_key_id_len,
361 const char *aws_secret_access_key,
362 int32_t aws_secret_access_key_len);
363
364
379MONGOCRYPT_EXPORT
380bool
383
395MONGOCRYPT_EXPORT
396bool
398 mongocrypt_binary_t *kms_providers);
399
412MONGOCRYPT_EXPORT
413bool
415 mongocrypt_binary_t *schema_map);
416
429MONGOCRYPT_EXPORT
430bool
432 mongocrypt_binary_t *efc_map);
433
434
463MONGOCRYPT_EXPORT
464void
466 const char *path);
467
468
492MONGOCRYPT_EXPORT
493void
495 const char *path);
496
497
512MONGOCRYPT_EXPORT
513void
515
516
530MONGOCRYPT_EXPORT
531bool
533
534
544MONGOCRYPT_EXPORT
545bool
547
548
554MONGOCRYPT_EXPORT
555void
557
576MONGOCRYPT_EXPORT
577const char *
579 uint32_t *len);
580
581
601MONGOCRYPT_EXPORT
602uint64_t
604
605
609typedef struct _mongocrypt_ctx_t mongocrypt_ctx_t;
610
611
621MONGOCRYPT_EXPORT
624
625
637MONGOCRYPT_EXPORT
638bool
640
641
656MONGOCRYPT_EXPORT
657bool
659 mongocrypt_binary_t *key_id);
660
683MONGOCRYPT_EXPORT
684bool
686 mongocrypt_binary_t *key_alt_name);
687
703MONGOCRYPT_EXPORT
704bool
706 mongocrypt_binary_t *key_material);
707
728MONGOCRYPT_EXPORT
729bool
731 const char *algorithm,
732 int len);
733
735#define MONGOCRYPT_ALGORITHM_DETERMINISTIC_STR \
736 "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"
738#define MONGOCRYPT_ALGORITHM_RANDOM_STR "AEAD_AES_256_CBC_HMAC_SHA_512-Random"
740#define MONGOCRYPT_ALGORITHM_INDEXED_STR "Indexed"
742#define MONGOCRYPT_ALGORITHM_UNINDEXED_STR "Unindexed"
743
744
763MONGOCRYPT_EXPORT
764bool
766 const char *region,
767 int32_t region_len,
768 const char *cmk,
769 int32_t cmk_len);
770
771
789MONGOCRYPT_EXPORT
790bool
792 const char *endpoint,
793 int32_t endpoint_len);
794
805MONGOCRYPT_EXPORT
806bool
808
860MONGOCRYPT_EXPORT
861bool
864
865
880MONGOCRYPT_EXPORT
881bool
883
898MONGOCRYPT_EXPORT
899bool
901 const char *db,
902 int32_t db_len,
904
936MONGOCRYPT_EXPORT
937bool
940
941
955MONGOCRYPT_EXPORT
956bool
958
959
973MONGOCRYPT_EXPORT
974bool
977
978
991MONGOCRYPT_EXPORT
992bool
994 mongocrypt_binary_t *filter);
995
996
1003typedef enum {
1004 MONGOCRYPT_CTX_ERROR = 0,
1005 MONGOCRYPT_CTX_NEED_MONGO_COLLINFO = 1, /* run on main MongoClient */
1006 MONGOCRYPT_CTX_NEED_MONGO_MARKINGS = 2, /* run on mongocryptd. */
1007 MONGOCRYPT_CTX_NEED_MONGO_KEYS = 3, /* run on key vault */
1008 MONGOCRYPT_CTX_NEED_KMS = 4,
1009 MONGOCRYPT_CTX_NEED_KMS_CREDENTIALS = 7, /* fetch/renew KMS credentials */
1010 MONGOCRYPT_CTX_READY = 5, /* ready for encryption/decryption */
1011 MONGOCRYPT_CTX_DONE = 6,
1013
1014
1021MONGOCRYPT_EXPORT
1024
1025
1046MONGOCRYPT_EXPORT
1047bool
1049
1050
1073MONGOCRYPT_EXPORT
1074bool
1076
1077
1085MONGOCRYPT_EXPORT
1086bool
1088
1089
1093typedef struct _mongocrypt_kms_ctx_t mongocrypt_kms_ctx_t;
1094
1095
1109MONGOCRYPT_EXPORT
1112
1113
1127MONGOCRYPT_EXPORT
1128bool
1130 mongocrypt_binary_t *msg);
1131
1132
1147MONGOCRYPT_EXPORT
1148bool
1150
1151
1158MONGOCRYPT_EXPORT
1159uint32_t
1161
1162
1175MONGOCRYPT_EXPORT
1176bool
1178
1179
1188MONGOCRYPT_EXPORT
1189bool
1191 mongocrypt_status_t *status);
1192
1208MONGOCRYPT_EXPORT
1209const char *
1211
1212
1221MONGOCRYPT_EXPORT
1222bool
1224
1225
1240MONGOCRYPT_EXPORT
1241bool
1243 mongocrypt_ctx_t *ctx, mongocrypt_binary_t *kms_providers_definition);
1244
1279MONGOCRYPT_EXPORT
1280bool
1282
1283
1289MONGOCRYPT_EXPORT
1290void
1292
1310typedef bool (*mongocrypt_crypto_fn) (void *ctx,
1315 uint32_t *bytes_written,
1316 mongocrypt_status_t *status);
1317
1335typedef bool (*mongocrypt_hmac_fn) (void *ctx,
1339 mongocrypt_status_t *status);
1340
1341
1355typedef bool (*mongocrypt_hash_fn) (void *ctx,
1358 mongocrypt_status_t *status);
1359
1373typedef bool (*mongocrypt_random_fn) (void *ctx,
1375 uint32_t count,
1376 mongocrypt_status_t *status);
1377
1378MONGOCRYPT_EXPORT
1379bool
1380mongocrypt_setopt_crypto_hooks (mongocrypt_t *crypt,
1381 mongocrypt_crypto_fn aes_256_cbc_encrypt,
1382 mongocrypt_crypto_fn aes_256_cbc_decrypt,
1383 mongocrypt_random_fn random,
1384 mongocrypt_hmac_fn hmac_sha_512,
1385 mongocrypt_hmac_fn hmac_sha_256,
1386 mongocrypt_hash_fn sha_256,
1387 void *ctx);
1388
1404MONGOCRYPT_EXPORT
1405bool
1407 mongocrypt_crypto_fn aes_256_ctr_encrypt,
1408 mongocrypt_crypto_fn aes_256_ctr_decrypt,
1409 void *ctx);
1410
1426MONGOCRYPT_EXPORT
1427bool
1429 mongocrypt_crypto_fn aes_256_ecb_encrypt,
1430 void *ctx);
1431
1449MONGOCRYPT_EXPORT
1450bool
1452 mongocrypt_t *crypt,
1453 mongocrypt_hmac_fn sign_rsaes_pkcs1_v1_5,
1454 void *sign_ctx);
1455
1465MONGOCRYPT_EXPORT
1466void
1468
1479MONGOCRYPT_EXPORT
1480bool
1482 int64_t contention_factor);
1483
1499MONGOCRYPT_EXPORT
1500bool
1502 mongocrypt_binary_t *key_id);
1503
1504
1515MONGOCRYPT_EXPORT
1516bool
1518 const char *query_type,
1519 int len);
1520
1522#define MONGOCRYPT_QUERY_TYPE_EQUALITY_STR "equality"
1523
1524#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:1093
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_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 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:1310
MONGOCRYPT_EXPORT mongocrypt_status_type_t mongocrypt_status_type(mongocrypt_status_t *status)
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:153
mongocrypt_log_level_t
Definition: mongocrypt.h:263
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:609
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
Definition: mongocrypt.h:75
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:1355
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:1373
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:1003
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:299
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:281
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_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:1335
struct _mongocrypt_status_t mongocrypt_status_t
Definition: mongocrypt.h:148
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)