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.2.0"
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
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 *
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 *
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 
424 MONGOCRYPT_EXPORT
425 bool
427 
428 
438 MONGOCRYPT_EXPORT
439 bool
441 
442 
448 MONGOCRYPT_EXPORT
449 void
451 
452 
456 typedef struct _mongocrypt_ctx_t mongocrypt_ctx_t;
457 
458 
468 MONGOCRYPT_EXPORT
471 
472 
484 MONGOCRYPT_EXPORT
485 bool
487 
488 
503 MONGOCRYPT_EXPORT
504 bool
506  mongocrypt_binary_t *key_id);
507 
530 MONGOCRYPT_EXPORT
531 bool
533  mongocrypt_binary_t *key_alt_name);
534 
555 MONGOCRYPT_EXPORT
556 bool
558  const char *algorithm,
559  int len);
560 
561 
580 MONGOCRYPT_EXPORT
581 bool
583  const char *region,
584  int32_t region_len,
585  const char *cmk,
586  int32_t cmk_len);
587 
588 
606 MONGOCRYPT_EXPORT
607 bool
609  const char *endpoint,
610  int32_t endpoint_len);
611 
622 MONGOCRYPT_EXPORT
623 bool
625 
669 MONGOCRYPT_EXPORT
670 bool
672  mongocrypt_binary_t *bin);
673 
674 
689 MONGOCRYPT_EXPORT
690 bool
692 
707 MONGOCRYPT_EXPORT
708 bool
710  const char *db,
711  int32_t db_len,
712  mongocrypt_binary_t *cmd);
713 
736 MONGOCRYPT_EXPORT
737 bool
739  mongocrypt_binary_t *msg);
740 
741 
755 MONGOCRYPT_EXPORT
756 bool
758 
759 
769 MONGOCRYPT_EXPORT
770 bool
772  mongocrypt_binary_t *msg);
773 
774 
781 typedef enum {
782  MONGOCRYPT_CTX_ERROR = 0,
783  MONGOCRYPT_CTX_NEED_MONGO_COLLINFO = 1, /* run on main MongoClient */
784  MONGOCRYPT_CTX_NEED_MONGO_MARKINGS = 2, /* run on mongocryptd. */
785  MONGOCRYPT_CTX_NEED_MONGO_KEYS = 3, /* run on key vault */
786  MONGOCRYPT_CTX_NEED_KMS = 4,
787  MONGOCRYPT_CTX_READY = 5, /* ready for encryption/decryption */
788  MONGOCRYPT_CTX_DONE = 6
790 
791 
798 MONGOCRYPT_EXPORT
801 
802 
823 MONGOCRYPT_EXPORT
824 bool
826 
827 
850 MONGOCRYPT_EXPORT
851 bool
853 
854 
862 MONGOCRYPT_EXPORT
863 bool
865 
866 
870 typedef struct _mongocrypt_kms_ctx_t mongocrypt_kms_ctx_t;
871 
872 
886 MONGOCRYPT_EXPORT
889 
890 
904 MONGOCRYPT_EXPORT
905 bool
907  mongocrypt_binary_t *msg);
908 
909 
923 MONGOCRYPT_EXPORT
924 bool
925 mongocrypt_kms_ctx_endpoint (mongocrypt_kms_ctx_t *kms, const char **endpoint);
926 
927 
934 MONGOCRYPT_EXPORT
935 uint32_t
937 
938 
951 MONGOCRYPT_EXPORT
952 bool
954 
955 
964 MONGOCRYPT_EXPORT
965 bool
967  mongocrypt_status_t *status);
968 
969 
978 MONGOCRYPT_EXPORT
979 bool
981 
982 
1012 MONGOCRYPT_EXPORT
1013 bool
1015 
1016 
1022 MONGOCRYPT_EXPORT
1023 void
1025 
1043 typedef bool (*mongocrypt_crypto_fn) (void *ctx,
1044  mongocrypt_binary_t *key,
1045  mongocrypt_binary_t *iv,
1046  mongocrypt_binary_t *in,
1047  mongocrypt_binary_t *out,
1048  uint32_t *bytes_written,
1049  mongocrypt_status_t *status);
1050 
1068 typedef bool (*mongocrypt_hmac_fn) (void *ctx,
1069  mongocrypt_binary_t *key,
1070  mongocrypt_binary_t *in,
1071  mongocrypt_binary_t *out,
1072  mongocrypt_status_t *status);
1073 
1074 
1088 typedef bool (*mongocrypt_hash_fn) (void *ctx,
1089  mongocrypt_binary_t *in,
1090  mongocrypt_binary_t *out,
1091  mongocrypt_status_t *status);
1092 
1106 typedef bool (*mongocrypt_random_fn) (void *ctx,
1107  mongocrypt_binary_t *out,
1108  uint32_t count,
1109  mongocrypt_status_t *status);
1110 
1111 MONGOCRYPT_EXPORT
1112 bool
1113 mongocrypt_setopt_crypto_hooks (mongocrypt_t *crypt,
1114  mongocrypt_crypto_fn aes_256_cbc_encrypt,
1115  mongocrypt_crypto_fn aes_256_cbc_decrypt,
1116  mongocrypt_random_fn random,
1117  mongocrypt_hmac_fn hmac_sha_512,
1118  mongocrypt_hmac_fn hmac_sha_256,
1119  mongocrypt_hash_fn sha_256,
1120  void *ctx);
1121 
1139 MONGOCRYPT_EXPORT
1140 bool
1142  mongocrypt_t *crypt,
1143  mongocrypt_hmac_fn sign_rsaes_pkcs1_v1_5,
1144  void *sign_ctx);
1145 
1146 #endif /* MONGOCRYPT_H */
mongocrypt_setopt_crypto_hook_sign_rsaes_pkcs1_v1_5
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_setopt_kms_provider_aws
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_ctx_destroy
MONGOCRYPT_EXPORT void mongocrypt_ctx_destroy(mongocrypt_ctx_t *ctx)
mongocrypt_binary_new
MONGOCRYPT_EXPORT mongocrypt_binary_t * mongocrypt_binary_new(void)
mongocrypt_ctx_kms_done
MONGOCRYPT_EXPORT bool mongocrypt_ctx_kms_done(mongocrypt_ctx_t *ctx)
mongocrypt_ctx_setopt_key_encryption_key
MONGOCRYPT_EXPORT bool mongocrypt_ctx_setopt_key_encryption_key(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *bin)
mongocrypt_new
MONGOCRYPT_EXPORT mongocrypt_t * mongocrypt_new(void)
mongocrypt_status_message
MONGOCRYPT_EXPORT const char * mongocrypt_status_message(mongocrypt_status_t *status, uint32_t *len)
mongocrypt_status_new
MONGOCRYPT_EXPORT mongocrypt_status_t * mongocrypt_status_new(void)
mongocrypt_status_code
MONGOCRYPT_EXPORT uint32_t mongocrypt_status_code(mongocrypt_status_t *status)
mongocrypt_kms_ctx_bytes_needed
MONGOCRYPT_EXPORT uint32_t mongocrypt_kms_ctx_bytes_needed(mongocrypt_kms_ctx_t *kms)
mongocrypt_status_t
struct _mongocrypt_status_t mongocrypt_status_t
Definition: mongocrypt.h:143
mongocrypt_ctx_next_kms_ctx
MONGOCRYPT_EXPORT mongocrypt_kms_ctx_t * mongocrypt_ctx_next_kms_ctx(mongocrypt_ctx_t *ctx)
mongocrypt_kms_ctx_endpoint
MONGOCRYPT_EXPORT bool mongocrypt_kms_ctx_endpoint(mongocrypt_kms_ctx_t *kms, const char **endpoint)
mongocrypt_status_type
MONGOCRYPT_EXPORT mongocrypt_status_type_t mongocrypt_status_type(mongocrypt_status_t *status)
mongocrypt_ctx_state_t
mongocrypt_ctx_state_t
Definition: mongocrypt.h:781
mongocrypt_ctx_t
struct _mongocrypt_ctx_t mongocrypt_ctx_t
Definition: mongocrypt.h:456
mongocrypt_status
MONGOCRYPT_EXPORT bool mongocrypt_status(mongocrypt_t *crypt, mongocrypt_status_t *status)
mongocrypt_binary_new_from_data
MONGOCRYPT_EXPORT mongocrypt_binary_t * mongocrypt_binary_new_from_data(uint8_t *data, uint32_t len)
mongocrypt_ctx_setopt_algorithm
MONGOCRYPT_EXPORT bool mongocrypt_ctx_setopt_algorithm(mongocrypt_ctx_t *ctx, const char *algorithm, int len)
mongocrypt_setopt_log_handler
MONGOCRYPT_EXPORT bool mongocrypt_setopt_log_handler(mongocrypt_t *crypt, mongocrypt_log_fn_t log_fn, void *log_ctx)
mongocrypt_ctx_new
MONGOCRYPT_EXPORT mongocrypt_ctx_t * mongocrypt_ctx_new(mongocrypt_t *crypt)
mongocrypt_hmac_fn
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:1068
mongocrypt_t
struct _mongocrypt_t mongocrypt_t
Definition: mongocrypt.h:293
mongocrypt_init
MONGOCRYPT_EXPORT bool mongocrypt_init(mongocrypt_t *crypt)
mongocrypt_binary_data
MONGOCRYPT_EXPORT uint8_t * mongocrypt_binary_data(const mongocrypt_binary_t *binary)
mongocrypt_version
MONGOCRYPT_EXPORT const char * mongocrypt_version(uint32_t *len)
mongocrypt_kms_ctx_status
MONGOCRYPT_EXPORT bool mongocrypt_kms_ctx_status(mongocrypt_kms_ctx_t *kms, mongocrypt_status_t *status)
mongocrypt_ctx_finalize
MONGOCRYPT_EXPORT bool mongocrypt_ctx_finalize(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *out)
mongocrypt_status_set
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_ctx_decrypt_init
MONGOCRYPT_EXPORT bool mongocrypt_ctx_decrypt_init(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *doc)
mongocrypt_kms_ctx_t
struct _mongocrypt_kms_ctx_t mongocrypt_kms_ctx_t
Definition: mongocrypt.h:870
mongocrypt_status_destroy
MONGOCRYPT_EXPORT void mongocrypt_status_destroy(mongocrypt_status_t *status)
mongocrypt_binary_destroy
MONGOCRYPT_EXPORT void mongocrypt_binary_destroy(mongocrypt_binary_t *binary)
mongocrypt_binary_t
struct _mongocrypt_binary_t mongocrypt_binary_t
Definition: mongocrypt.h:70
mongocrypt_ctx_encrypt_init
MONGOCRYPT_EXPORT bool mongocrypt_ctx_encrypt_init(mongocrypt_ctx_t *ctx, const char *db, int32_t db_len, mongocrypt_binary_t *cmd)
mongocrypt_binary_len
MONGOCRYPT_EXPORT uint32_t mongocrypt_binary_len(const mongocrypt_binary_t *binary)
mongocrypt_ctx_setopt_key_alt_name
MONGOCRYPT_EXPORT bool mongocrypt_ctx_setopt_key_alt_name(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *key_alt_name)
mongocrypt_hash_fn
bool(* mongocrypt_hash_fn)(void *ctx, mongocrypt_binary_t *in, mongocrypt_binary_t *out, mongocrypt_status_t *status)
Definition: mongocrypt.h:1088
mongocrypt_ctx_setopt_key_id
MONGOCRYPT_EXPORT bool mongocrypt_ctx_setopt_key_id(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *key_id)
mongocrypt_ctx_setopt_masterkey_aws
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_kms_ctx_feed
MONGOCRYPT_EXPORT bool mongocrypt_kms_ctx_feed(mongocrypt_kms_ctx_t *kms, mongocrypt_binary_t *bytes)
mongocrypt_random_fn
bool(* mongocrypt_random_fn)(void *ctx, mongocrypt_binary_t *out, uint32_t count, mongocrypt_status_t *status)
Definition: mongocrypt.h:1106
mongocrypt_ctx_mongo_op
MONGOCRYPT_EXPORT bool mongocrypt_ctx_mongo_op(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *op_bson)
mongocrypt_destroy
MONGOCRYPT_EXPORT void mongocrypt_destroy(mongocrypt_t *crypt)
mongocrypt_kms_ctx_message
MONGOCRYPT_EXPORT bool mongocrypt_kms_ctx_message(mongocrypt_kms_ctx_t *kms, mongocrypt_binary_t *msg)
mongocrypt_ctx_explicit_encrypt_init
MONGOCRYPT_EXPORT bool mongocrypt_ctx_explicit_encrypt_init(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *msg)
mongocrypt_ctx_mongo_feed
MONGOCRYPT_EXPORT bool mongocrypt_ctx_mongo_feed(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *reply)
mongocrypt_ctx_setopt_masterkey_local
MONGOCRYPT_EXPORT bool mongocrypt_ctx_setopt_masterkey_local(mongocrypt_ctx_t *ctx)
mongocrypt_log_level_t
mongocrypt_log_level_t
Definition: mongocrypt.h:257
mongocrypt_ctx_setopt_masterkey_aws_endpoint
MONGOCRYPT_EXPORT bool mongocrypt_ctx_setopt_masterkey_aws_endpoint(mongocrypt_ctx_t *ctx, const char *endpoint, int32_t endpoint_len)
mongocrypt_log_fn_t
void(* mongocrypt_log_fn_t)(mongocrypt_log_level_t level, const char *message, uint32_t message_len, void *ctx)
Definition: mongocrypt.h:275
mongocrypt_status_type_t
mongocrypt_status_type_t
Definition: mongocrypt.h:148
mongocrypt_setopt_kms_provider_local
MONGOCRYPT_EXPORT bool mongocrypt_setopt_kms_provider_local(mongocrypt_t *crypt, mongocrypt_binary_t *key)
mongocrypt_ctx_state
MONGOCRYPT_EXPORT mongocrypt_ctx_state_t mongocrypt_ctx_state(mongocrypt_ctx_t *ctx)
mongocrypt_ctx_mongo_done
MONGOCRYPT_EXPORT bool mongocrypt_ctx_mongo_done(mongocrypt_ctx_t *ctx)
mongocrypt_status_ok
MONGOCRYPT_EXPORT bool mongocrypt_status_ok(mongocrypt_status_t *status)
mongocrypt_ctx_status
MONGOCRYPT_EXPORT bool mongocrypt_ctx_status(mongocrypt_ctx_t *ctx, mongocrypt_status_t *status)
mongocrypt_ctx_explicit_decrypt_init
MONGOCRYPT_EXPORT bool mongocrypt_ctx_explicit_decrypt_init(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *msg)
mongocrypt_setopt_kms_providers
MONGOCRYPT_EXPORT bool mongocrypt_setopt_kms_providers(mongocrypt_t *crypt, mongocrypt_binary_t *kms_providers)
mongocrypt_ctx_datakey_init
MONGOCRYPT_EXPORT bool mongocrypt_ctx_datakey_init(mongocrypt_ctx_t *ctx)
mongocrypt_crypto_fn
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:1043
mongocrypt_setopt_schema_map
MONGOCRYPT_EXPORT bool mongocrypt_setopt_schema_map(mongocrypt_t *crypt, mongocrypt_binary_t *schema_map)