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 
48 MONGOCRYPT_EXPORT
49 const char *
50 mongocrypt_version (uint32_t *len);
51 
52 
75 typedef struct _mongocrypt_binary_t mongocrypt_binary_t;
76 
77 
85 MONGOCRYPT_EXPORT
88 
89 
99 MONGOCRYPT_EXPORT
101 mongocrypt_binary_new_from_data (uint8_t *data, uint32_t len);
102 
103 
111 MONGOCRYPT_EXPORT
112 uint8_t *
114 
115 
123 MONGOCRYPT_EXPORT
124 uint32_t
126 
127 
135 MONGOCRYPT_EXPORT
136 void
138 
139 
148 typedef struct _mongocrypt_status_t mongocrypt_status_t;
149 
153 typedef 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 
170 MONGOCRYPT_EXPORT
173 
174 
191 MONGOCRYPT_EXPORT
192 void
195  uint32_t code,
196  const char *message,
197  int32_t message_len);
198 
199 
207 MONGOCRYPT_EXPORT
210 
211 
219 MONGOCRYPT_EXPORT
220 uint32_t
222 
223 
233 MONGOCRYPT_EXPORT
234 const char *
236 
237 
246 MONGOCRYPT_EXPORT
247 bool
249 
250 
256 MONGOCRYPT_EXPORT
257 void
259 
263 typedef 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 
299 typedef struct _mongocrypt_t mongocrypt_t;
300 
301 
311 MONGOCRYPT_EXPORT
312 mongocrypt_t *
314 
315 
328 MONGOCRYPT_EXPORT
329 bool
331  mongocrypt_log_fn_t log_fn,
332  void *log_ctx);
333 
334 
356 MONGOCRYPT_EXPORT
357 bool
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 
379 MONGOCRYPT_EXPORT
380 bool
382  mongocrypt_binary_t *key);
383 
395 MONGOCRYPT_EXPORT
396 bool
398  mongocrypt_binary_t *kms_providers);
399 
412 MONGOCRYPT_EXPORT
413 bool
415  mongocrypt_binary_t *schema_map);
416 
429 MONGOCRYPT_EXPORT
430 bool
432  mongocrypt_binary_t *efc_map);
433 
434 
463 MONGOCRYPT_EXPORT
464 void
466  const char *path);
467 
468 
492 MONGOCRYPT_EXPORT
493 void
495  const char *path);
496 
497 
512 MONGOCRYPT_EXPORT
513 void
515 
516 
530 MONGOCRYPT_EXPORT
531 bool
533 
534 
544 MONGOCRYPT_EXPORT
545 bool
547 
548 
554 MONGOCRYPT_EXPORT
555 void
557 
576 MONGOCRYPT_EXPORT
577 const char *
579  uint32_t *len);
580 
581 
601 MONGOCRYPT_EXPORT
602 uint64_t
604 
605 
609 typedef struct _mongocrypt_ctx_t mongocrypt_ctx_t;
610 
611 
621 MONGOCRYPT_EXPORT
624 
625 
637 MONGOCRYPT_EXPORT
638 bool
640 
641 
656 MONGOCRYPT_EXPORT
657 bool
659  mongocrypt_binary_t *key_id);
660 
683 MONGOCRYPT_EXPORT
684 bool
686  mongocrypt_binary_t *key_alt_name);
687 
703 MONGOCRYPT_EXPORT
704 bool
706  mongocrypt_binary_t *key_material);
707 
728 MONGOCRYPT_EXPORT
729 bool
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 
763 MONGOCRYPT_EXPORT
764 bool
766  const char *region,
767  int32_t region_len,
768  const char *cmk,
769  int32_t cmk_len);
770 
771 
789 MONGOCRYPT_EXPORT
790 bool
792  const char *endpoint,
793  int32_t endpoint_len);
794 
805 MONGOCRYPT_EXPORT
806 bool
808 
860 MONGOCRYPT_EXPORT
861 bool
863  mongocrypt_binary_t *bin);
864 
865 
880 MONGOCRYPT_EXPORT
881 bool
883 
898 MONGOCRYPT_EXPORT
899 bool
901  const char *db,
902  int32_t db_len,
903  mongocrypt_binary_t *cmd);
904 
936 MONGOCRYPT_EXPORT
937 bool
939  mongocrypt_binary_t *msg);
940 
941 
955 MONGOCRYPT_EXPORT
956 bool
958 
959 
973 MONGOCRYPT_EXPORT
974 bool
976  mongocrypt_binary_t *msg);
977 
978 
991 MONGOCRYPT_EXPORT
992 bool
994  mongocrypt_binary_t *filter);
995 
996 
1003 typedef 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 
1021 MONGOCRYPT_EXPORT
1024 
1025 
1046 MONGOCRYPT_EXPORT
1047 bool
1049 
1050 
1073 MONGOCRYPT_EXPORT
1074 bool
1076 
1077 
1085 MONGOCRYPT_EXPORT
1086 bool
1088 
1089 
1093 typedef struct _mongocrypt_kms_ctx_t mongocrypt_kms_ctx_t;
1094 
1095 
1109 MONGOCRYPT_EXPORT
1112 
1113 
1127 MONGOCRYPT_EXPORT
1128 bool
1130  mongocrypt_binary_t *msg);
1131 
1132 
1147 MONGOCRYPT_EXPORT
1148 bool
1150 
1151 
1158 MONGOCRYPT_EXPORT
1159 uint32_t
1161 
1162 
1175 MONGOCRYPT_EXPORT
1176 bool
1178 
1179 
1188 MONGOCRYPT_EXPORT
1189 bool
1191  mongocrypt_status_t *status);
1192 
1208 MONGOCRYPT_EXPORT
1209 const char *
1211 
1212 
1221 MONGOCRYPT_EXPORT
1222 bool
1224 
1225 
1240 MONGOCRYPT_EXPORT
1241 bool
1243  mongocrypt_ctx_t *ctx, mongocrypt_binary_t *kms_providers_definition);
1244 
1281 MONGOCRYPT_EXPORT
1282 bool
1284 
1285 
1291 MONGOCRYPT_EXPORT
1292 void
1294 
1312 typedef bool (*mongocrypt_crypto_fn) (void *ctx,
1313  mongocrypt_binary_t *key,
1314  mongocrypt_binary_t *iv,
1315  mongocrypt_binary_t *in,
1316  mongocrypt_binary_t *out,
1317  uint32_t *bytes_written,
1318  mongocrypt_status_t *status);
1319 
1337 typedef bool (*mongocrypt_hmac_fn) (void *ctx,
1338  mongocrypt_binary_t *key,
1339  mongocrypt_binary_t *in,
1340  mongocrypt_binary_t *out,
1341  mongocrypt_status_t *status);
1342 
1343 
1357 typedef bool (*mongocrypt_hash_fn) (void *ctx,
1358  mongocrypt_binary_t *in,
1359  mongocrypt_binary_t *out,
1360  mongocrypt_status_t *status);
1361 
1375 typedef bool (*mongocrypt_random_fn) (void *ctx,
1376  mongocrypt_binary_t *out,
1377  uint32_t count,
1378  mongocrypt_status_t *status);
1379 
1380 MONGOCRYPT_EXPORT
1381 bool
1382 mongocrypt_setopt_crypto_hooks (mongocrypt_t *crypt,
1383  mongocrypt_crypto_fn aes_256_cbc_encrypt,
1384  mongocrypt_crypto_fn aes_256_cbc_decrypt,
1385  mongocrypt_random_fn random,
1386  mongocrypt_hmac_fn hmac_sha_512,
1387  mongocrypt_hmac_fn hmac_sha_256,
1388  mongocrypt_hash_fn sha_256,
1389  void *ctx);
1390 
1406 MONGOCRYPT_EXPORT
1407 bool
1409  mongocrypt_crypto_fn aes_256_ctr_encrypt,
1410  mongocrypt_crypto_fn aes_256_ctr_decrypt,
1411  void *ctx);
1412 
1428 MONGOCRYPT_EXPORT
1429 bool
1431  mongocrypt_crypto_fn aes_256_ecb_encrypt,
1432  void *ctx);
1433 
1451 MONGOCRYPT_EXPORT
1452 bool
1454  mongocrypt_t *crypt,
1455  mongocrypt_hmac_fn sign_rsaes_pkcs1_v1_5,
1456  void *sign_ctx);
1457 
1467 MONGOCRYPT_EXPORT
1468 void
1470 
1481 MONGOCRYPT_EXPORT
1482 bool
1484  int64_t contention_factor);
1485 
1501 MONGOCRYPT_EXPORT
1502 bool
1504  mongocrypt_binary_t *key_id);
1505 
1506 
1517 MONGOCRYPT_EXPORT
1518 bool
1520  const char *query_type,
1521  int len);
1522 
1524 #define MONGOCRYPT_QUERY_TYPE_EQUALITY_STR "equality"
1525 
1526 #endif /* MONGOCRYPT_H */
MONGOCRYPT_EXPORT const char * mongocrypt_version(uint32_t *len)
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 const char * mongocrypt_status_message(mongocrypt_status_t *status, uint32_t *len)
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 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 bool mongocrypt_ctx_setopt_index_key_id(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *key_id)
MONGOCRYPT_EXPORT mongocrypt_t * mongocrypt_new(void)
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)
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:1312
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 mongocrypt_kms_ctx_t * mongocrypt_ctx_next_kms_ctx(mongocrypt_ctx_t *ctx)
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 const char * mongocrypt_kms_ctx_get_kms_provider(mongocrypt_kms_ctx_t *kms, uint32_t *len)
MONGOCRYPT_EXPORT mongocrypt_status_t * mongocrypt_status_new(void)
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 mongocrypt_ctx_t * mongocrypt_ctx_new(mongocrypt_t *crypt)
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)
MONGOCRYPT_EXPORT const char * mongocrypt_crypt_shared_lib_version_string(const mongocrypt_t *crypt, uint32_t *len)
bool(* mongocrypt_hash_fn)(void *ctx, mongocrypt_binary_t *in, mongocrypt_binary_t *out, mongocrypt_status_t *status)
Definition: mongocrypt.h:1357
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:1375
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 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 uint8_t * mongocrypt_binary_data(const mongocrypt_binary_t *binary)
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 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)
MONGOCRYPT_EXPORT mongocrypt_binary_t * mongocrypt_binary_new_from_data(uint8_t *data, uint32_t 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 bool mongocrypt_ctx_explicit_encrypt_init(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *msg)
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(void)
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:1337
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)