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.3.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 
388 MONGOCRYPT_EXPORT
389 bool
391  mongocrypt_binary_t *kms_providers);
392 
405 MONGOCRYPT_EXPORT
406 bool
408  mongocrypt_binary_t *schema_map);
409 
410 
439 MONGOCRYPT_EXPORT
440 void
442  const char *path);
443 
444 
467 MONGOCRYPT_EXPORT
468 void
470  const char *path);
471 
472 
486 MONGOCRYPT_EXPORT
487 bool
489 
490 
500 MONGOCRYPT_EXPORT
501 bool
503 
504 
510 MONGOCRYPT_EXPORT
511 void
513 
514 
518 typedef struct _mongocrypt_ctx_t mongocrypt_ctx_t;
519 
520 
530 MONGOCRYPT_EXPORT
533 
534 
546 MONGOCRYPT_EXPORT
547 bool
549 
550 
565 MONGOCRYPT_EXPORT
566 bool
568  mongocrypt_binary_t *key_id);
569 
592 MONGOCRYPT_EXPORT
593 bool
595  mongocrypt_binary_t *key_alt_name);
596 
612 MONGOCRYPT_EXPORT
613 bool
615  mongocrypt_binary_t *key_material);
616 
637 MONGOCRYPT_EXPORT
638 bool
640  const char *algorithm,
641  int len);
642 
643 
662 MONGOCRYPT_EXPORT
663 bool
665  const char *region,
666  int32_t region_len,
667  const char *cmk,
668  int32_t cmk_len);
669 
670 
688 MONGOCRYPT_EXPORT
689 bool
691  const char *endpoint,
692  int32_t endpoint_len);
693 
704 MONGOCRYPT_EXPORT
705 bool
707 
758 MONGOCRYPT_EXPORT
759 bool
761  mongocrypt_binary_t *bin);
762 
763 
778 MONGOCRYPT_EXPORT
779 bool
781 
796 MONGOCRYPT_EXPORT
797 bool
799  const char *db,
800  int32_t db_len,
801  mongocrypt_binary_t *cmd);
802 
825 MONGOCRYPT_EXPORT
826 bool
828  mongocrypt_binary_t *msg);
829 
830 
844 MONGOCRYPT_EXPORT
845 bool
847 
848 
858 MONGOCRYPT_EXPORT
859 bool
861  mongocrypt_binary_t *msg);
862 
863 
870 typedef enum {
871  MONGOCRYPT_CTX_ERROR = 0,
872  MONGOCRYPT_CTX_NEED_MONGO_COLLINFO = 1, /* run on main MongoClient */
873  MONGOCRYPT_CTX_NEED_MONGO_MARKINGS = 2, /* run on mongocryptd. */
874  MONGOCRYPT_CTX_NEED_MONGO_KEYS = 3, /* run on key vault */
875  MONGOCRYPT_CTX_NEED_KMS = 4,
876  MONGOCRYPT_CTX_READY = 5, /* ready for encryption/decryption */
877  MONGOCRYPT_CTX_DONE = 6
879 
880 
887 MONGOCRYPT_EXPORT
890 
891 
912 MONGOCRYPT_EXPORT
913 bool
915 
916 
939 MONGOCRYPT_EXPORT
940 bool
942 
943 
951 MONGOCRYPT_EXPORT
952 bool
954 
955 
959 typedef struct _mongocrypt_kms_ctx_t mongocrypt_kms_ctx_t;
960 
961 
975 MONGOCRYPT_EXPORT
978 
979 
993 MONGOCRYPT_EXPORT
994 bool
996  mongocrypt_binary_t *msg);
997 
998 
1013 MONGOCRYPT_EXPORT
1014 bool
1015 mongocrypt_kms_ctx_endpoint (mongocrypt_kms_ctx_t *kms, const char **endpoint);
1016 
1017 
1024 MONGOCRYPT_EXPORT
1025 uint32_t
1027 
1028 
1041 MONGOCRYPT_EXPORT
1042 bool
1044 
1045 
1054 MONGOCRYPT_EXPORT
1055 bool
1057  mongocrypt_status_t *status);
1058 
1074 MONGOCRYPT_EXPORT
1075 const char *
1077 
1078 
1087 MONGOCRYPT_EXPORT
1088 bool
1090 
1091 
1121 MONGOCRYPT_EXPORT
1122 bool
1124 
1125 
1131 MONGOCRYPT_EXPORT
1132 void
1134 
1152 typedef bool (*mongocrypt_crypto_fn) (void *ctx,
1153  mongocrypt_binary_t *key,
1154  mongocrypt_binary_t *iv,
1155  mongocrypt_binary_t *in,
1156  mongocrypt_binary_t *out,
1157  uint32_t *bytes_written,
1158  mongocrypt_status_t *status);
1159 
1177 typedef bool (*mongocrypt_hmac_fn) (void *ctx,
1178  mongocrypt_binary_t *key,
1179  mongocrypt_binary_t *in,
1180  mongocrypt_binary_t *out,
1181  mongocrypt_status_t *status);
1182 
1183 
1197 typedef bool (*mongocrypt_hash_fn) (void *ctx,
1198  mongocrypt_binary_t *in,
1199  mongocrypt_binary_t *out,
1200  mongocrypt_status_t *status);
1201 
1215 typedef bool (*mongocrypt_random_fn) (void *ctx,
1216  mongocrypt_binary_t *out,
1217  uint32_t count,
1218  mongocrypt_status_t *status);
1219 
1220 MONGOCRYPT_EXPORT
1221 bool
1222 mongocrypt_setopt_crypto_hooks (mongocrypt_t *crypt,
1223  mongocrypt_crypto_fn aes_256_cbc_encrypt,
1224  mongocrypt_crypto_fn aes_256_cbc_decrypt,
1225  mongocrypt_random_fn random,
1226  mongocrypt_hmac_fn hmac_sha_512,
1227  mongocrypt_hmac_fn hmac_sha_256,
1228  mongocrypt_hash_fn sha_256,
1229  void *ctx);
1230 
1248 MONGOCRYPT_EXPORT
1249 bool
1251  mongocrypt_t *crypt,
1252  mongocrypt_hmac_fn sign_rsaes_pkcs1_v1_5,
1253  void *sign_ctx);
1254 
1255 #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:1177
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:1152
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:959
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:1197
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 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_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:1215
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:870
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:518
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 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 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