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 #include "mongocrypt-config.h"
29 
35 #define MONGOCRYPT_VERSION "1.4.1"
36 
43 MONGOCRYPT_EXPORT
44 const char *
45 mongocrypt_version (uint32_t *len);
46 
47 
70 typedef struct _mongocrypt_binary_t mongocrypt_binary_t;
71 
72 
80 MONGOCRYPT_EXPORT
83 
84 
94 MONGOCRYPT_EXPORT
96 mongocrypt_binary_new_from_data (uint8_t *data, uint32_t len);
97 
98 
106 MONGOCRYPT_EXPORT
107 uint8_t *
109 
110 
118 MONGOCRYPT_EXPORT
119 uint32_t
121 
122 
130 MONGOCRYPT_EXPORT
131 void
133 
134 
143 typedef struct _mongocrypt_status_t mongocrypt_status_t;
144 
148 typedef enum {
149  MONGOCRYPT_STATUS_OK = 0,
150  MONGOCRYPT_STATUS_ERROR_CLIENT = 1,
151  MONGOCRYPT_STATUS_ERROR_KMS = 2
153 
154 
164 MONGOCRYPT_EXPORT
166 mongocrypt_status_new (void);
167 
168 
185 MONGOCRYPT_EXPORT
186 void
189  uint32_t code,
190  const char *message,
191  int32_t message_len);
192 
193 
201 MONGOCRYPT_EXPORT
204 
205 
213 MONGOCRYPT_EXPORT
214 uint32_t
216 
217 
227 MONGOCRYPT_EXPORT
228 const char *
229 mongocrypt_status_message (mongocrypt_status_t *status, uint32_t *len);
230 
231 
240 MONGOCRYPT_EXPORT
241 bool
243 
244 
250 MONGOCRYPT_EXPORT
251 void
253 
257 typedef enum {
258  MONGOCRYPT_LOG_LEVEL_FATAL = 0,
259  MONGOCRYPT_LOG_LEVEL_ERROR = 1,
260  MONGOCRYPT_LOG_LEVEL_WARNING = 2,
261  MONGOCRYPT_LOG_LEVEL_INFO = 3,
262  MONGOCRYPT_LOG_LEVEL_TRACE = 4
264 
265 
276  const char *message,
277  uint32_t message_len,
278  void *ctx);
279 
280 
293 typedef struct _mongocrypt_t mongocrypt_t;
294 
295 
305 MONGOCRYPT_EXPORT
306 mongocrypt_t *
307 mongocrypt_new (void);
308 
309 
322 MONGOCRYPT_EXPORT
323 bool
325  mongocrypt_log_fn_t log_fn,
326  void *log_ctx);
327 
328 
350 MONGOCRYPT_EXPORT
351 bool
353  const char *aws_access_key_id,
354  int32_t aws_access_key_id_len,
355  const char *aws_secret_access_key,
356  int32_t aws_secret_access_key_len);
357 
358 
373 MONGOCRYPT_EXPORT
374 bool
376  mongocrypt_binary_t *key);
377 
389 MONGOCRYPT_EXPORT
390 bool
392  mongocrypt_binary_t *kms_providers);
393 
406 MONGOCRYPT_EXPORT
407 bool
409  mongocrypt_binary_t *schema_map);
410 
411 
440 MONGOCRYPT_EXPORT
441 void
443  const char *path);
444 
445 
468 MONGOCRYPT_EXPORT
469 void
471  const char *path);
472 
473 
488 MONGOCRYPT_EXPORT
489 void
491 
492 
506 MONGOCRYPT_EXPORT
507 bool
509 
510 
520 MONGOCRYPT_EXPORT
521 bool
523 
524 
530 MONGOCRYPT_EXPORT
531 void
533 
551 MONGOCRYPT_EXPORT
552 const char *
553 mongocrypt_csfle_version_string (const mongocrypt_t *crypt, uint32_t *len);
554 
555 
575 MONGOCRYPT_EXPORT
576 uint64_t
578 
579 
583 typedef struct _mongocrypt_ctx_t mongocrypt_ctx_t;
584 
585 
595 MONGOCRYPT_EXPORT
598 
599 
611 MONGOCRYPT_EXPORT
612 bool
614 
615 
630 MONGOCRYPT_EXPORT
631 bool
633  mongocrypt_binary_t *key_id);
634 
657 MONGOCRYPT_EXPORT
658 bool
660  mongocrypt_binary_t *key_alt_name);
661 
677 MONGOCRYPT_EXPORT
678 bool
680  mongocrypt_binary_t *key_material);
681 
702 MONGOCRYPT_EXPORT
703 bool
705  const char *algorithm,
706  int len);
707 
708 
727 MONGOCRYPT_EXPORT
728 bool
730  const char *region,
731  int32_t region_len,
732  const char *cmk,
733  int32_t cmk_len);
734 
735 
753 MONGOCRYPT_EXPORT
754 bool
756  const char *endpoint,
757  int32_t endpoint_len);
758 
769 MONGOCRYPT_EXPORT
770 bool
772 
823 MONGOCRYPT_EXPORT
824 bool
826  mongocrypt_binary_t *bin);
827 
828 
843 MONGOCRYPT_EXPORT
844 bool
846 
861 MONGOCRYPT_EXPORT
862 bool
864  const char *db,
865  int32_t db_len,
866  mongocrypt_binary_t *cmd);
867 
890 MONGOCRYPT_EXPORT
891 bool
893  mongocrypt_binary_t *msg);
894 
895 
909 MONGOCRYPT_EXPORT
910 bool
912 
913 
923 MONGOCRYPT_EXPORT
924 bool
926  mongocrypt_binary_t *msg);
927 
928 
935 typedef enum {
936  MONGOCRYPT_CTX_ERROR = 0,
937  MONGOCRYPT_CTX_NEED_MONGO_COLLINFO = 1, /* run on main MongoClient */
938  MONGOCRYPT_CTX_NEED_MONGO_MARKINGS = 2, /* run on mongocryptd. */
939  MONGOCRYPT_CTX_NEED_MONGO_KEYS = 3, /* run on key vault */
940  MONGOCRYPT_CTX_NEED_KMS = 4,
941  MONGOCRYPT_CTX_NEED_KMS_CREDENTIALS = 7, /* fetch/renew KMS credentials */
942  MONGOCRYPT_CTX_READY = 5, /* ready for encryption/decryption */
943  MONGOCRYPT_CTX_DONE = 6,
945 
946 
953 MONGOCRYPT_EXPORT
956 
957 
978 MONGOCRYPT_EXPORT
979 bool
981 
982 
1005 MONGOCRYPT_EXPORT
1006 bool
1008 
1009 
1017 MONGOCRYPT_EXPORT
1018 bool
1020 
1021 
1025 typedef struct _mongocrypt_kms_ctx_t mongocrypt_kms_ctx_t;
1026 
1027 
1041 MONGOCRYPT_EXPORT
1044 
1045 
1059 MONGOCRYPT_EXPORT
1060 bool
1062  mongocrypt_binary_t *msg);
1063 
1064 
1079 MONGOCRYPT_EXPORT
1080 bool
1081 mongocrypt_kms_ctx_endpoint (mongocrypt_kms_ctx_t *kms, const char **endpoint);
1082 
1083 
1090 MONGOCRYPT_EXPORT
1091 uint32_t
1093 
1094 
1107 MONGOCRYPT_EXPORT
1108 bool
1110 
1111 
1120 MONGOCRYPT_EXPORT
1121 bool
1123  mongocrypt_status_t *status);
1124 
1140 MONGOCRYPT_EXPORT
1141 const char *
1143 
1144 
1153 MONGOCRYPT_EXPORT
1154 bool
1156 
1157 
1172 MONGOCRYPT_EXPORT
1173 bool
1175  mongocrypt_ctx_t *ctx,
1176  mongocrypt_binary_t *kms_providers_definition);
1177 
1207 MONGOCRYPT_EXPORT
1208 bool
1210 
1211 
1217 MONGOCRYPT_EXPORT
1218 void
1220 
1238 typedef bool (*mongocrypt_crypto_fn) (void *ctx,
1239  mongocrypt_binary_t *key,
1240  mongocrypt_binary_t *iv,
1241  mongocrypt_binary_t *in,
1242  mongocrypt_binary_t *out,
1243  uint32_t *bytes_written,
1244  mongocrypt_status_t *status);
1245 
1263 typedef bool (*mongocrypt_hmac_fn) (void *ctx,
1264  mongocrypt_binary_t *key,
1265  mongocrypt_binary_t *in,
1266  mongocrypt_binary_t *out,
1267  mongocrypt_status_t *status);
1268 
1269 
1283 typedef bool (*mongocrypt_hash_fn) (void *ctx,
1284  mongocrypt_binary_t *in,
1285  mongocrypt_binary_t *out,
1286  mongocrypt_status_t *status);
1287 
1301 typedef bool (*mongocrypt_random_fn) (void *ctx,
1302  mongocrypt_binary_t *out,
1303  uint32_t count,
1304  mongocrypt_status_t *status);
1305 
1306 MONGOCRYPT_EXPORT
1307 bool
1308 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 
1334 MONGOCRYPT_EXPORT
1335 bool
1337  mongocrypt_t *crypt,
1338  mongocrypt_hmac_fn sign_rsaes_pkcs1_v1_5,
1339  void *sign_ctx);
1340 
1341 #endif /* MONGOCRYPT_H */
MONGOCRYPT_EXPORT void mongocrypt_setopt_set_csfle_lib_path_override(mongocrypt_t *crypt, const char *path)
Set a single override path for loading the CSFLE dynamic library.
MONGOCRYPT_EXPORT bool mongocrypt_ctx_setopt_key_encryption_key(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *bin)
MONGOCRYPT_EXPORT bool mongocrypt_setopt_kms_provider_local(mongocrypt_t *crypt, mongocrypt_binary_t *key)
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:1263
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:1238
MONGOCRYPT_EXPORT mongocrypt_ctx_t * mongocrypt_ctx_new(mongocrypt_t *crypt)
MONGOCRYPT_EXPORT mongocrypt_kms_ctx_t * mongocrypt_ctx_next_kms_ctx(mongocrypt_ctx_t *ctx)
struct _mongocrypt_kms_ctx_t mongocrypt_kms_ctx_t
Definition: mongocrypt.h:1025
MONGOCRYPT_EXPORT bool mongocrypt_ctx_setopt_masterkey_aws_endpoint(mongocrypt_ctx_t *ctx, const char *endpoint, int32_t endpoint_len)
MONGOCRYPT_EXPORT bool mongocrypt_kms_ctx_endpoint(mongocrypt_kms_ctx_t *kms, const char **endpoint)
MONGOCRYPT_EXPORT bool mongocrypt_ctx_mongo_op(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *op_bson)
MONGOCRYPT_EXPORT uint32_t mongocrypt_status_code(mongocrypt_status_t *status)
MONGOCRYPT_EXPORT void mongocrypt_status_destroy(mongocrypt_status_t *status)
MONGOCRYPT_EXPORT bool mongocrypt_ctx_explicit_encrypt_init(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *msg)
MONGOCRYPT_EXPORT bool mongocrypt_status(mongocrypt_t *crypt, mongocrypt_status_t *status)
mongocrypt_log_level_t
Definition: mongocrypt.h:257
bool(* mongocrypt_hash_fn)(void *ctx, mongocrypt_binary_t *in, mongocrypt_binary_t *out, mongocrypt_status_t *status)
Definition: mongocrypt.h:1283
MONGOCRYPT_EXPORT mongocrypt_binary_t * mongocrypt_binary_new_from_data(uint8_t *data, uint32_t len)
MONGOCRYPT_EXPORT void mongocrypt_binary_destroy(mongocrypt_binary_t *binary)
MONGOCRYPT_EXPORT bool mongocrypt_setopt_log_handler(mongocrypt_t *crypt, mongocrypt_log_fn_t log_fn, void *log_ctx)
MONGOCRYPT_EXPORT const char * mongocrypt_kms_ctx_get_kms_provider(mongocrypt_kms_ctx_t *kms, uint32_t *len)
mongocrypt_status_type_t
Definition: mongocrypt.h:148
MONGOCRYPT_EXPORT mongocrypt_status_type_t mongocrypt_status_type(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 bool mongocrypt_ctx_setopt_key_material(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *key_material)
MONGOCRYPT_EXPORT const char * mongocrypt_csfle_version_string(const mongocrypt_t *crypt, uint32_t *len)
MONGOCRYPT_EXPORT mongocrypt_binary_t * mongocrypt_binary_new(void)
MONGOCRYPT_EXPORT const char * mongocrypt_status_message(mongocrypt_status_t *status, 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:275
MONGOCRYPT_EXPORT bool mongocrypt_ctx_mongo_done(mongocrypt_ctx_t *ctx)
MONGOCRYPT_EXPORT bool mongocrypt_ctx_provide_kms_providers(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *kms_providers_definition)
MONGOCRYPT_EXPORT bool mongocrypt_kms_ctx_feed(mongocrypt_kms_ctx_t *kms, mongocrypt_binary_t *bytes)
bool(* mongocrypt_random_fn)(void *ctx, mongocrypt_binary_t *out, uint32_t count, mongocrypt_status_t *status)
Definition: mongocrypt.h:1301
MONGOCRYPT_EXPORT bool mongocrypt_ctx_status(mongocrypt_ctx_t *ctx, mongocrypt_status_t *status)
MONGOCRYPT_EXPORT bool mongocrypt_status_ok(mongocrypt_status_t *status)
MONGOCRYPT_EXPORT bool mongocrypt_ctx_explicit_decrypt_init(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *msg)
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_status_t * mongocrypt_status_new(void)
mongocrypt_ctx_state_t
Definition: mongocrypt.h:935
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 void mongocrypt_destroy(mongocrypt_t *crypt)
MONGOCRYPT_EXPORT bool mongocrypt_kms_ctx_message(mongocrypt_kms_ctx_t *kms, mongocrypt_binary_t *msg)
MONGOCRYPT_EXPORT mongocrypt_ctx_state_t mongocrypt_ctx_state(mongocrypt_ctx_t *ctx)
MONGOCRYPT_EXPORT uint32_t mongocrypt_binary_len(const mongocrypt_binary_t *binary)
MONGOCRYPT_EXPORT bool mongocrypt_setopt_schema_map(mongocrypt_t *crypt, mongocrypt_binary_t *schema_map)
MONGOCRYPT_EXPORT bool mongocrypt_ctx_encrypt_init(mongocrypt_ctx_t *ctx, const char *db, int32_t db_len, mongocrypt_binary_t *cmd)
MONGOCRYPT_EXPORT uint32_t mongocrypt_kms_ctx_bytes_needed(mongocrypt_kms_ctx_t *kms)
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 void mongocrypt_setopt_append_csfle_search_path(mongocrypt_t *crypt, const char *path)
Append an additional search directory to the search path for loading the CSFLE dynamic library...
MONGOCRYPT_EXPORT bool mongocrypt_ctx_mongo_feed(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *reply)
MONGOCRYPT_EXPORT bool mongocrypt_ctx_decrypt_init(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *doc)
struct _mongocrypt_ctx_t mongocrypt_ctx_t
Definition: mongocrypt.h:583
MONGOCRYPT_EXPORT bool mongocrypt_ctx_datakey_init(mongocrypt_ctx_t *ctx)
MONGOCRYPT_EXPORT bool mongocrypt_init(mongocrypt_t *crypt)
MONGOCRYPT_EXPORT bool mongocrypt_ctx_finalize(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *out)
MONGOCRYPT_EXPORT bool mongocrypt_ctx_setopt_key_id(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *key_id)
struct _mongocrypt_t mongocrypt_t
Definition: mongocrypt.h:293
struct _mongocrypt_status_t mongocrypt_status_t
Definition: mongocrypt.h:143
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_ctx_setopt_masterkey_local(mongocrypt_ctx_t *ctx)
MONGOCRYPT_EXPORT bool mongocrypt_ctx_kms_done(mongocrypt_ctx_t *ctx)
MONGOCRYPT_EXPORT mongocrypt_t * mongocrypt_new(void)
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 bool mongocrypt_ctx_setopt_algorithm(mongocrypt_ctx_t *ctx, const char *algorithm, int len)
MONGOCRYPT_EXPORT uint64_t mongocrypt_csfle_version(const mongocrypt_t *crypt)
Obtain a 64-bit constant encoding the version of the loaded csfle library, if available.
MONGOCRYPT_EXPORT const char * mongocrypt_version(uint32_t *len)
MONGOCRYPT_EXPORT bool mongocrypt_kms_ctx_status(mongocrypt_kms_ctx_t *kms, mongocrypt_status_t *status)
MONGOCRYPT_EXPORT void mongocrypt_ctx_destroy(mongocrypt_ctx_t *ctx)
MONGOCRYPT_EXPORT bool mongocrypt_setopt_kms_providers(mongocrypt_t *crypt, mongocrypt_binary_t *kms_providers)
MONGOCRYPT_EXPORT uint8_t * mongocrypt_binary_data(const mongocrypt_binary_t *binary)
struct _mongocrypt_binary_t mongocrypt_binary_t
Definition: mongocrypt.h:70