libmongocrypt
Loading...
Searching...
No Matches
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"
746#define MONGOCRYPT_ALGORITHM_RANGEPREVIEW_STR "RangePreview"
747
748
767MONGOCRYPT_EXPORT
768bool
770 const char *region,
771 int32_t region_len,
772 const char *cmk,
773 int32_t cmk_len);
774
775
793MONGOCRYPT_EXPORT
794bool
796 const char *endpoint,
797 int32_t endpoint_len);
798
809MONGOCRYPT_EXPORT
810bool
812
864MONGOCRYPT_EXPORT
865bool
868
869
884MONGOCRYPT_EXPORT
885bool
887
902MONGOCRYPT_EXPORT
903bool
905 const char *db,
906 int32_t db_len,
908
944MONGOCRYPT_EXPORT
945bool
948
993MONGOCRYPT_EXPORT
994bool
997
998
1012MONGOCRYPT_EXPORT
1013bool
1015
1016
1030MONGOCRYPT_EXPORT
1031bool
1033 mongocrypt_binary_t *msg);
1034
1035
1048MONGOCRYPT_EXPORT
1049bool
1051 mongocrypt_binary_t *filter);
1052
1053
1060typedef enum {
1061 MONGOCRYPT_CTX_ERROR = 0,
1062 MONGOCRYPT_CTX_NEED_MONGO_COLLINFO = 1, /* run on main MongoClient */
1063 MONGOCRYPT_CTX_NEED_MONGO_MARKINGS = 2, /* run on mongocryptd. */
1064 MONGOCRYPT_CTX_NEED_MONGO_KEYS = 3, /* run on key vault */
1065 MONGOCRYPT_CTX_NEED_KMS = 4,
1066 MONGOCRYPT_CTX_NEED_KMS_CREDENTIALS = 7, /* fetch/renew KMS credentials */
1067 MONGOCRYPT_CTX_READY = 5, /* ready for encryption/decryption */
1068 MONGOCRYPT_CTX_DONE = 6,
1070
1071
1078MONGOCRYPT_EXPORT
1081
1082
1103MONGOCRYPT_EXPORT
1104bool
1106
1107
1130MONGOCRYPT_EXPORT
1131bool
1133
1134
1142MONGOCRYPT_EXPORT
1143bool
1145
1146
1150typedef struct _mongocrypt_kms_ctx_t mongocrypt_kms_ctx_t;
1151
1152
1166MONGOCRYPT_EXPORT
1169
1170
1184MONGOCRYPT_EXPORT
1185bool
1187 mongocrypt_binary_t *msg);
1188
1189
1204MONGOCRYPT_EXPORT
1205bool
1207
1208
1215MONGOCRYPT_EXPORT
1216uint32_t
1218
1219
1232MONGOCRYPT_EXPORT
1233bool
1235
1236
1245MONGOCRYPT_EXPORT
1246bool
1248 mongocrypt_status_t *status);
1249
1265MONGOCRYPT_EXPORT
1266const char *
1268
1269
1278MONGOCRYPT_EXPORT
1279bool
1281
1282
1297MONGOCRYPT_EXPORT
1298bool
1300 mongocrypt_ctx_t *ctx, mongocrypt_binary_t *kms_providers_definition);
1301
1338MONGOCRYPT_EXPORT
1339bool
1341
1342
1348MONGOCRYPT_EXPORT
1349void
1351
1369typedef bool (*mongocrypt_crypto_fn) (void *ctx,
1374 uint32_t *bytes_written,
1375 mongocrypt_status_t *status);
1376
1394typedef bool (*mongocrypt_hmac_fn) (void *ctx,
1398 mongocrypt_status_t *status);
1399
1400
1414typedef bool (*mongocrypt_hash_fn) (void *ctx,
1417 mongocrypt_status_t *status);
1418
1432typedef bool (*mongocrypt_random_fn) (void *ctx,
1434 uint32_t count,
1435 mongocrypt_status_t *status);
1436
1437MONGOCRYPT_EXPORT
1438bool
1439mongocrypt_setopt_crypto_hooks (mongocrypt_t *crypt,
1440 mongocrypt_crypto_fn aes_256_cbc_encrypt,
1441 mongocrypt_crypto_fn aes_256_cbc_decrypt,
1442 mongocrypt_random_fn random,
1443 mongocrypt_hmac_fn hmac_sha_512,
1444 mongocrypt_hmac_fn hmac_sha_256,
1445 mongocrypt_hash_fn sha_256,
1446 void *ctx);
1447
1463MONGOCRYPT_EXPORT
1464bool
1466 mongocrypt_crypto_fn aes_256_ctr_encrypt,
1467 mongocrypt_crypto_fn aes_256_ctr_decrypt,
1468 void *ctx);
1469
1485MONGOCRYPT_EXPORT
1486bool
1488 mongocrypt_crypto_fn aes_256_ecb_encrypt,
1489 void *ctx);
1490
1508MONGOCRYPT_EXPORT
1509bool
1511 mongocrypt_t *crypt,
1512 mongocrypt_hmac_fn sign_rsaes_pkcs1_v1_5,
1513 void *sign_ctx);
1514
1524MONGOCRYPT_EXPORT
1525void
1527
1538MONGOCRYPT_EXPORT
1539bool
1541 int64_t contention_factor);
1542
1558MONGOCRYPT_EXPORT
1559bool
1561 mongocrypt_binary_t *key_id);
1562
1563
1574MONGOCRYPT_EXPORT
1575bool
1577 const char *query_type,
1578 int len);
1579
1599MONGOCRYPT_EXPORT
1600bool
1602 mongocrypt_binary_t *opts);
1603
1605#define MONGOCRYPT_QUERY_TYPE_EQUALITY_STR "equality"
1606// NOTE: The RangePreview algorithm is experimental only. It is not intended for
1607// public use.
1608#define MONGOCRYPT_QUERY_TYPE_RANGEPREVIEW_STR "rangePreview"
1609
1610#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:1150
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 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:1369
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:1414
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:1432
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:1060
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_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:1394
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)