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 
48 MONGOCRYPT_EXPORT
49 const char *mongocrypt_version(uint32_t *len);
50 
73 typedef struct _mongocrypt_binary_t mongocrypt_binary_t;
74 
82 MONGOCRYPT_EXPORT
84 
94 MONGOCRYPT_EXPORT
96 
104 MONGOCRYPT_EXPORT
106 
114 MONGOCRYPT_EXPORT
116 
124 MONGOCRYPT_EXPORT
126 
135 typedef struct _mongocrypt_status_t mongocrypt_status_t;
136 
140 typedef enum {
141  MONGOCRYPT_STATUS_OK = 0,
142  MONGOCRYPT_STATUS_ERROR_CLIENT = 1,
143  MONGOCRYPT_STATUS_ERROR_KMS = 2,
144  MONGOCRYPT_STATUS_ERROR_CRYPT_SHARED = 3,
146 
156 MONGOCRYPT_EXPORT
158 
175 MONGOCRYPT_EXPORT
178  uint32_t code,
179  const char *message,
180  int32_t message_len);
181 
189 MONGOCRYPT_EXPORT
191 
199 MONGOCRYPT_EXPORT
201 
211 MONGOCRYPT_EXPORT
212 const char *mongocrypt_status_message(mongocrypt_status_t *status, uint32_t *len);
213 
222 MONGOCRYPT_EXPORT
224 
230 MONGOCRYPT_EXPORT
232 
236 typedef enum {
237  MONGOCRYPT_LOG_LEVEL_FATAL = 0,
238  MONGOCRYPT_LOG_LEVEL_ERROR = 1,
239  MONGOCRYPT_LOG_LEVEL_WARNING = 2,
240  MONGOCRYPT_LOG_LEVEL_INFO = 3,
241  MONGOCRYPT_LOG_LEVEL_TRACE = 4
243 
253 typedef void (*mongocrypt_log_fn_t)(mongocrypt_log_level_t level, const char *message, uint32_t message_len, void *ctx);
254 
267 typedef struct _mongocrypt_t mongocrypt_t;
268 
278 MONGOCRYPT_EXPORT
280 
293 MONGOCRYPT_EXPORT
295 
317 MONGOCRYPT_EXPORT
319  const char *aws_access_key_id,
320  int32_t aws_access_key_id_len,
321  const char *aws_secret_access_key,
322  int32_t aws_secret_access_key_len);
323 
338 MONGOCRYPT_EXPORT
340 
352 MONGOCRYPT_EXPORT
354 
367 MONGOCRYPT_EXPORT
369 
382 MONGOCRYPT_EXPORT
384 
413 MONGOCRYPT_EXPORT
415 
439 MONGOCRYPT_EXPORT
441 
456 MONGOCRYPT_EXPORT
458 
472 MONGOCRYPT_EXPORT
474 
484 MONGOCRYPT_EXPORT
486 
492 MONGOCRYPT_EXPORT
494 
513 MONGOCRYPT_EXPORT
514 const char *mongocrypt_crypt_shared_lib_version_string(const mongocrypt_t *crypt, uint32_t *len);
515 
535 MONGOCRYPT_EXPORT
537 
541 typedef struct _mongocrypt_ctx_t mongocrypt_ctx_t;
542 
552 MONGOCRYPT_EXPORT
554 
566 MONGOCRYPT_EXPORT
568 
583 MONGOCRYPT_EXPORT
585 
608 MONGOCRYPT_EXPORT
610 
626 MONGOCRYPT_EXPORT
628 
649 MONGOCRYPT_EXPORT
650 bool mongocrypt_ctx_setopt_algorithm(mongocrypt_ctx_t *ctx, const char *algorithm, int len);
651 
653 #define MONGOCRYPT_ALGORITHM_DETERMINISTIC_STR "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"
655 #define MONGOCRYPT_ALGORITHM_RANDOM_STR "AEAD_AES_256_CBC_HMAC_SHA_512-Random"
657 #define MONGOCRYPT_ALGORITHM_INDEXED_STR "Indexed"
659 #define MONGOCRYPT_ALGORITHM_UNINDEXED_STR "Unindexed"
663 #define MONGOCRYPT_ALGORITHM_RANGEPREVIEW_STR "RangePreview"
664 
683 MONGOCRYPT_EXPORT
685  const char *region,
686  int32_t region_len,
687  const char *cmk,
688  int32_t cmk_len);
689 
707 MONGOCRYPT_EXPORT
708 bool mongocrypt_ctx_setopt_masterkey_aws_endpoint(mongocrypt_ctx_t *ctx, const char *endpoint, int32_t endpoint_len);
709 
720 MONGOCRYPT_EXPORT
722 
774 MONGOCRYPT_EXPORT
776 
791 MONGOCRYPT_EXPORT
793 
808 MONGOCRYPT_EXPORT
809 bool mongocrypt_ctx_encrypt_init(mongocrypt_ctx_t *ctx, const char *db, int32_t db_len, mongocrypt_binary_t *cmd);
810 
846 MONGOCRYPT_EXPORT
848 
893 MONGOCRYPT_EXPORT
895 
909 MONGOCRYPT_EXPORT
911 
925 MONGOCRYPT_EXPORT
927 
940 MONGOCRYPT_EXPORT
942 
949 typedef enum {
950  MONGOCRYPT_CTX_ERROR = 0,
951  MONGOCRYPT_CTX_NEED_MONGO_COLLINFO = 1, /* run on main MongoClient */
952  MONGOCRYPT_CTX_NEED_MONGO_MARKINGS = 2, /* run on mongocryptd. */
953  MONGOCRYPT_CTX_NEED_MONGO_KEYS = 3, /* run on key vault */
954  MONGOCRYPT_CTX_NEED_KMS = 4,
955  MONGOCRYPT_CTX_NEED_KMS_CREDENTIALS = 7, /* fetch/renew KMS credentials */
956  MONGOCRYPT_CTX_READY = 5, /* ready for encryption/decryption */
957  MONGOCRYPT_CTX_DONE = 6,
959 
966 MONGOCRYPT_EXPORT
968 
989 MONGOCRYPT_EXPORT
991 
1014 MONGOCRYPT_EXPORT
1016 
1024 MONGOCRYPT_EXPORT
1026 
1030 typedef struct _mongocrypt_kms_ctx_t mongocrypt_kms_ctx_t;
1031 
1045 MONGOCRYPT_EXPORT
1047 
1061 MONGOCRYPT_EXPORT
1063 
1078 MONGOCRYPT_EXPORT
1079 bool mongocrypt_kms_ctx_endpoint(mongocrypt_kms_ctx_t *kms, const char **endpoint);
1080 
1087 MONGOCRYPT_EXPORT
1089 
1102 MONGOCRYPT_EXPORT
1104 
1113 MONGOCRYPT_EXPORT
1115 
1131 MONGOCRYPT_EXPORT
1133 
1142 MONGOCRYPT_EXPORT
1144 
1159 MONGOCRYPT_EXPORT
1161 
1198 MONGOCRYPT_EXPORT
1200 
1206 MONGOCRYPT_EXPORT
1208 
1226 typedef bool (*mongocrypt_crypto_fn)(void *ctx,
1227  mongocrypt_binary_t *key,
1228  mongocrypt_binary_t *iv,
1229  mongocrypt_binary_t *in,
1230  mongocrypt_binary_t *out,
1231  uint32_t *bytes_written,
1232  mongocrypt_status_t *status);
1233 
1251 typedef bool (*mongocrypt_hmac_fn)(void *ctx,
1252  mongocrypt_binary_t *key,
1253  mongocrypt_binary_t *in,
1254  mongocrypt_binary_t *out,
1255  mongocrypt_status_t *status);
1256 
1270 typedef bool (*mongocrypt_hash_fn)(void *ctx,
1271  mongocrypt_binary_t *in,
1272  mongocrypt_binary_t *out,
1273  mongocrypt_status_t *status);
1274 
1288 typedef bool (*mongocrypt_random_fn)(void *ctx, mongocrypt_binary_t *out, uint32_t count, mongocrypt_status_t *status);
1289 
1290 MONGOCRYPT_EXPORT
1291 bool mongocrypt_setopt_crypto_hooks(mongocrypt_t *crypt,
1292  mongocrypt_crypto_fn aes_256_cbc_encrypt,
1293  mongocrypt_crypto_fn aes_256_cbc_decrypt,
1294  mongocrypt_random_fn random,
1295  mongocrypt_hmac_fn hmac_sha_512,
1296  mongocrypt_hmac_fn hmac_sha_256,
1297  mongocrypt_hash_fn sha_256,
1298  void *ctx);
1299 
1315 MONGOCRYPT_EXPORT
1317  mongocrypt_crypto_fn aes_256_ctr_encrypt,
1318  mongocrypt_crypto_fn aes_256_ctr_decrypt,
1319  void *ctx);
1320 
1336 MONGOCRYPT_EXPORT
1337 bool mongocrypt_setopt_aes_256_ecb(mongocrypt_t *crypt, mongocrypt_crypto_fn aes_256_ecb_encrypt, void *ctx);
1338 
1356 MONGOCRYPT_EXPORT
1358  mongocrypt_hmac_fn sign_rsaes_pkcs1_v1_5,
1359  void *sign_ctx);
1360 
1370 MONGOCRYPT_EXPORT
1372 
1383 MONGOCRYPT_EXPORT
1384 bool mongocrypt_ctx_setopt_contention_factor(mongocrypt_ctx_t *ctx, int64_t contention_factor);
1385 
1401 MONGOCRYPT_EXPORT
1403 
1414 MONGOCRYPT_EXPORT
1415 bool mongocrypt_ctx_setopt_query_type(mongocrypt_ctx_t *ctx, const char *query_type, int len);
1416 
1436 MONGOCRYPT_EXPORT
1438 
1440 #define MONGOCRYPT_QUERY_TYPE_EQUALITY_STR "equality"
1441 // NOTE: The RangePreview algorithm is experimental only. It is not intended for
1442 // public use.
1443 #define MONGOCRYPT_QUERY_TYPE_RANGEPREVIEW_STR "rangePreview"
1444 
1445 #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:1030
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_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 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:1226
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:140
mongocrypt_log_level_t
Definition: mongocrypt.h:236
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:541
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:73
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:1270
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:1288
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:949
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:267
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:253
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_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:1251
struct _mongocrypt_status_t mongocrypt_status_t
Definition: mongocrypt.h:135
MONGOCRYPT_EXPORT bool mongocrypt_ctx_mongo_op(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *op_bson)