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
59MONGOCRYPT_EXPORT
61
87typedef struct _mongocrypt_binary_t {
88 void *data;
89 uint32_t len;
91
99MONGOCRYPT_EXPORT
101
111MONGOCRYPT_EXPORT
113
121MONGOCRYPT_EXPORT
123
131MONGOCRYPT_EXPORT
133
141MONGOCRYPT_EXPORT
143
152typedef struct _mongocrypt_status_t mongocrypt_status_t;
153
157typedef enum {
158 MONGOCRYPT_STATUS_OK = 0,
159 MONGOCRYPT_STATUS_ERROR_CLIENT = 1,
160 MONGOCRYPT_STATUS_ERROR_KMS = 2,
161 MONGOCRYPT_STATUS_ERROR_CRYPT_SHARED = 3,
163
173MONGOCRYPT_EXPORT
175
192MONGOCRYPT_EXPORT
195 uint32_t code,
196 const char *message,
197 int32_t message_len);
198
206MONGOCRYPT_EXPORT
208
216MONGOCRYPT_EXPORT
218
228MONGOCRYPT_EXPORT
229const char *mongocrypt_status_message(mongocrypt_status_t *status, uint32_t *len);
230
239MONGOCRYPT_EXPORT
241
247MONGOCRYPT_EXPORT
249
253typedef enum {
254 MONGOCRYPT_LOG_LEVEL_FATAL = 0,
255 MONGOCRYPT_LOG_LEVEL_ERROR = 1,
256 MONGOCRYPT_LOG_LEVEL_WARNING = 2,
257 MONGOCRYPT_LOG_LEVEL_INFO = 3,
258 MONGOCRYPT_LOG_LEVEL_TRACE = 4
260
270typedef void (*mongocrypt_log_fn_t)(mongocrypt_log_level_t level, const char *message, uint32_t message_len, void *ctx);
271
284typedef struct _mongocrypt_t mongocrypt_t;
285
295MONGOCRYPT_EXPORT
297
310MONGOCRYPT_EXPORT
312
334MONGOCRYPT_EXPORT
336 const char *aws_access_key_id,
337 int32_t aws_access_key_id_len,
338 const char *aws_secret_access_key,
339 int32_t aws_secret_access_key_len);
340
355MONGOCRYPT_EXPORT
357
369MONGOCRYPT_EXPORT
371
384MONGOCRYPT_EXPORT
386
399MONGOCRYPT_EXPORT
401
430MONGOCRYPT_EXPORT
432
456MONGOCRYPT_EXPORT
458
473MONGOCRYPT_EXPORT
475
489MONGOCRYPT_EXPORT
491
501MONGOCRYPT_EXPORT
503
509MONGOCRYPT_EXPORT
511
530MONGOCRYPT_EXPORT
531const char *mongocrypt_crypt_shared_lib_version_string(const mongocrypt_t *crypt, uint32_t *len);
532
552MONGOCRYPT_EXPORT
554
558typedef struct _mongocrypt_ctx_t mongocrypt_ctx_t;
559
569MONGOCRYPT_EXPORT
571
583MONGOCRYPT_EXPORT
585
600MONGOCRYPT_EXPORT
602
625MONGOCRYPT_EXPORT
627
643MONGOCRYPT_EXPORT
645
666MONGOCRYPT_EXPORT
667bool mongocrypt_ctx_setopt_algorithm(mongocrypt_ctx_t *ctx, const char *algorithm, int len);
668
670#define MONGOCRYPT_ALGORITHM_DETERMINISTIC_STR "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"
672#define MONGOCRYPT_ALGORITHM_RANDOM_STR "AEAD_AES_256_CBC_HMAC_SHA_512-Random"
674#define MONGOCRYPT_ALGORITHM_INDEXED_STR "Indexed"
676#define MONGOCRYPT_ALGORITHM_UNINDEXED_STR "Unindexed"
680#define MONGOCRYPT_ALGORITHM_RANGEPREVIEW_STR "RangePreview"
681
700MONGOCRYPT_EXPORT
702 const char *region,
703 int32_t region_len,
704 const char *cmk,
705 int32_t cmk_len);
706
724MONGOCRYPT_EXPORT
725bool mongocrypt_ctx_setopt_masterkey_aws_endpoint(mongocrypt_ctx_t *ctx, const char *endpoint, int32_t endpoint_len);
726
737MONGOCRYPT_EXPORT
739
791MONGOCRYPT_EXPORT
793
808MONGOCRYPT_EXPORT
810
825MONGOCRYPT_EXPORT
826bool mongocrypt_ctx_encrypt_init(mongocrypt_ctx_t *ctx, const char *db, int32_t db_len, mongocrypt_binary_t *cmd);
827
863MONGOCRYPT_EXPORT
865
910MONGOCRYPT_EXPORT
912
926MONGOCRYPT_EXPORT
928
942MONGOCRYPT_EXPORT
944
957MONGOCRYPT_EXPORT
959
966typedef enum {
967 MONGOCRYPT_CTX_ERROR = 0,
968 MONGOCRYPT_CTX_NEED_MONGO_COLLINFO = 1, /* run on main MongoClient */
969 MONGOCRYPT_CTX_NEED_MONGO_MARKINGS = 2, /* run on mongocryptd. */
970 MONGOCRYPT_CTX_NEED_MONGO_KEYS = 3, /* run on key vault */
971 MONGOCRYPT_CTX_NEED_KMS = 4,
972 MONGOCRYPT_CTX_NEED_KMS_CREDENTIALS = 7, /* fetch/renew KMS credentials */
973 MONGOCRYPT_CTX_READY = 5, /* ready for encryption/decryption */
974 MONGOCRYPT_CTX_DONE = 6,
976
983MONGOCRYPT_EXPORT
985
1006MONGOCRYPT_EXPORT
1008
1031MONGOCRYPT_EXPORT
1033
1041MONGOCRYPT_EXPORT
1043
1047typedef struct _mongocrypt_kms_ctx_t mongocrypt_kms_ctx_t;
1048
1062MONGOCRYPT_EXPORT
1064
1078MONGOCRYPT_EXPORT
1080
1095MONGOCRYPT_EXPORT
1096bool mongocrypt_kms_ctx_endpoint(mongocrypt_kms_ctx_t *kms, const char **endpoint);
1097
1104MONGOCRYPT_EXPORT
1106
1119MONGOCRYPT_EXPORT
1121
1130MONGOCRYPT_EXPORT
1132
1148MONGOCRYPT_EXPORT
1150
1159MONGOCRYPT_EXPORT
1161
1176MONGOCRYPT_EXPORT
1178
1215MONGOCRYPT_EXPORT
1217
1223MONGOCRYPT_EXPORT
1225
1243typedef bool (*mongocrypt_crypto_fn)(void *ctx,
1248 uint32_t *bytes_written,
1249 mongocrypt_status_t *status);
1250
1268typedef bool (*mongocrypt_hmac_fn)(void *ctx,
1272 mongocrypt_status_t *status);
1273
1287typedef bool (*mongocrypt_hash_fn)(void *ctx,
1290 mongocrypt_status_t *status);
1291
1305typedef bool (*mongocrypt_random_fn)(void *ctx, mongocrypt_binary_t *out, uint32_t count, mongocrypt_status_t *status);
1306
1307MONGOCRYPT_EXPORT
1308bool mongocrypt_setopt_crypto_hooks(mongocrypt_t *crypt,
1309 mongocrypt_crypto_fn aes_256_cbc_encrypt,
1310 mongocrypt_crypto_fn aes_256_cbc_decrypt,
1311 mongocrypt_random_fn random,
1312 mongocrypt_hmac_fn hmac_sha_512,
1313 mongocrypt_hmac_fn hmac_sha_256,
1314 mongocrypt_hash_fn sha_256,
1315 void *ctx);
1316
1332MONGOCRYPT_EXPORT
1334 mongocrypt_crypto_fn aes_256_ctr_encrypt,
1335 mongocrypt_crypto_fn aes_256_ctr_decrypt,
1336 void *ctx);
1337
1353MONGOCRYPT_EXPORT
1354bool mongocrypt_setopt_aes_256_ecb(mongocrypt_t *crypt, mongocrypt_crypto_fn aes_256_ecb_encrypt, void *ctx);
1355
1373MONGOCRYPT_EXPORT
1375 mongocrypt_hmac_fn sign_rsaes_pkcs1_v1_5,
1376 void *sign_ctx);
1377
1387MONGOCRYPT_EXPORT
1389
1400MONGOCRYPT_EXPORT
1401bool mongocrypt_ctx_setopt_contention_factor(mongocrypt_ctx_t *ctx, int64_t contention_factor);
1402
1418MONGOCRYPT_EXPORT
1420
1431MONGOCRYPT_EXPORT
1432bool mongocrypt_ctx_setopt_query_type(mongocrypt_ctx_t *ctx, const char *query_type, int len);
1433
1453MONGOCRYPT_EXPORT
1455
1457#define MONGOCRYPT_QUERY_TYPE_EQUALITY_STR "equality"
1458// NOTE: The RangePreview algorithm is experimental only. It is not intended for
1459// public use.
1460#define MONGOCRYPT_QUERY_TYPE_RANGEPREVIEW_STR "rangePreview"
1461
1462#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:1047
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:1243
MONGOCRYPT_EXPORT mongocrypt_status_type_t mongocrypt_status_type(mongocrypt_status_t *status)
MONGOCRYPT_EXPORT bool mongocrypt_is_crypto_available(void)
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:157
mongocrypt_log_level_t
Definition mongocrypt.h:253
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:558
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
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:1287
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:1305
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:966
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:284
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:270
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:1268
struct _mongocrypt_status_t mongocrypt_status_t
Definition mongocrypt.h:152
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)
Definition mongocrypt.h:87