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-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
73typedef struct _mongocrypt_binary_t mongocrypt_binary_t;
74
82MONGOCRYPT_EXPORT
84
94MONGOCRYPT_EXPORT
96
104MONGOCRYPT_EXPORT
106
114MONGOCRYPT_EXPORT
116
124MONGOCRYPT_EXPORT
126
135typedef struct _mongocrypt_status_t mongocrypt_status_t;
136
140typedef 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
156MONGOCRYPT_EXPORT
158
175MONGOCRYPT_EXPORT
178 uint32_t code,
179 const char *message,
180 int32_t message_len);
181
189MONGOCRYPT_EXPORT
191
199MONGOCRYPT_EXPORT
201
211MONGOCRYPT_EXPORT
212const char *mongocrypt_status_message(mongocrypt_status_t *status, uint32_t *len);
213
222MONGOCRYPT_EXPORT
224
230MONGOCRYPT_EXPORT
232
236typedef 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
253typedef void (*mongocrypt_log_fn_t)(mongocrypt_log_level_t level, const char *message, uint32_t message_len, void *ctx);
254
267typedef struct _mongocrypt_t mongocrypt_t;
268
278MONGOCRYPT_EXPORT
280
293MONGOCRYPT_EXPORT
295
317MONGOCRYPT_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
338MONGOCRYPT_EXPORT
340
352MONGOCRYPT_EXPORT
354
367MONGOCRYPT_EXPORT
369
382MONGOCRYPT_EXPORT
384
413MONGOCRYPT_EXPORT
415
439MONGOCRYPT_EXPORT
441
456MONGOCRYPT_EXPORT
458
472MONGOCRYPT_EXPORT
474
484MONGOCRYPT_EXPORT
486
492MONGOCRYPT_EXPORT
494
513MONGOCRYPT_EXPORT
514const char *mongocrypt_crypt_shared_lib_version_string(const mongocrypt_t *crypt, uint32_t *len);
515
535MONGOCRYPT_EXPORT
537
541typedef struct _mongocrypt_ctx_t mongocrypt_ctx_t;
542
552MONGOCRYPT_EXPORT
554
566MONGOCRYPT_EXPORT
568
583MONGOCRYPT_EXPORT
585
608MONGOCRYPT_EXPORT
610
626MONGOCRYPT_EXPORT
628
649MONGOCRYPT_EXPORT
650bool 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
683MONGOCRYPT_EXPORT
685 const char *region,
686 int32_t region_len,
687 const char *cmk,
688 int32_t cmk_len);
689
707MONGOCRYPT_EXPORT
708bool mongocrypt_ctx_setopt_masterkey_aws_endpoint(mongocrypt_ctx_t *ctx, const char *endpoint, int32_t endpoint_len);
709
720MONGOCRYPT_EXPORT
722
774MONGOCRYPT_EXPORT
776
791MONGOCRYPT_EXPORT
793
808MONGOCRYPT_EXPORT
809bool mongocrypt_ctx_encrypt_init(mongocrypt_ctx_t *ctx, const char *db, int32_t db_len, mongocrypt_binary_t *cmd);
810
846MONGOCRYPT_EXPORT
848
893MONGOCRYPT_EXPORT
895
909MONGOCRYPT_EXPORT
911
925MONGOCRYPT_EXPORT
927
940MONGOCRYPT_EXPORT
942
949typedef 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
966MONGOCRYPT_EXPORT
968
989MONGOCRYPT_EXPORT
991
1014MONGOCRYPT_EXPORT
1016
1024MONGOCRYPT_EXPORT
1026
1030typedef struct _mongocrypt_kms_ctx_t mongocrypt_kms_ctx_t;
1031
1045MONGOCRYPT_EXPORT
1047
1061MONGOCRYPT_EXPORT
1063
1078MONGOCRYPT_EXPORT
1079bool mongocrypt_kms_ctx_endpoint(mongocrypt_kms_ctx_t *kms, const char **endpoint);
1080
1087MONGOCRYPT_EXPORT
1089
1102MONGOCRYPT_EXPORT
1104
1113MONGOCRYPT_EXPORT
1115
1131MONGOCRYPT_EXPORT
1133
1142MONGOCRYPT_EXPORT
1144
1159MONGOCRYPT_EXPORT
1161
1198MONGOCRYPT_EXPORT
1200
1206MONGOCRYPT_EXPORT
1208
1226typedef bool (*mongocrypt_crypto_fn)(void *ctx,
1231 uint32_t *bytes_written,
1232 mongocrypt_status_t *status);
1233
1251typedef bool (*mongocrypt_hmac_fn)(void *ctx,
1255 mongocrypt_status_t *status);
1256
1270typedef bool (*mongocrypt_hash_fn)(void *ctx,
1273 mongocrypt_status_t *status);
1274
1288typedef bool (*mongocrypt_random_fn)(void *ctx, mongocrypt_binary_t *out, uint32_t count, mongocrypt_status_t *status);
1289
1290MONGOCRYPT_EXPORT
1291bool 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
1315MONGOCRYPT_EXPORT
1317 mongocrypt_crypto_fn aes_256_ctr_encrypt,
1318 mongocrypt_crypto_fn aes_256_ctr_decrypt,
1319 void *ctx);
1320
1336MONGOCRYPT_EXPORT
1337bool mongocrypt_setopt_aes_256_ecb(mongocrypt_t *crypt, mongocrypt_crypto_fn aes_256_ecb_encrypt, void *ctx);
1338
1356MONGOCRYPT_EXPORT
1358 mongocrypt_hmac_fn sign_rsaes_pkcs1_v1_5,
1359 void *sign_ctx);
1360
1370MONGOCRYPT_EXPORT
1372
1383MONGOCRYPT_EXPORT
1384bool mongocrypt_ctx_setopt_contention_factor(mongocrypt_ctx_t *ctx, int64_t contention_factor);
1385
1401MONGOCRYPT_EXPORT
1403
1414MONGOCRYPT_EXPORT
1415bool mongocrypt_ctx_setopt_query_type(mongocrypt_ctx_t *ctx, const char *query_type, int len);
1416
1436MONGOCRYPT_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 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:1030
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: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 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: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 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)
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 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: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 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: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)
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 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: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)
MONGOCRYPT_EXPORT mongocrypt_kms_ctx_t * mongocrypt_ctx_next_kms_ctx(mongocrypt_ctx_t *ctx)