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.0.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 
347 MONGOCRYPT_EXPORT
348 bool
350  const char *aws_access_key_id,
351  int32_t aws_access_key_id_len,
352  const char *aws_secret_access_key,
353  int32_t aws_secret_access_key_len);
354 
355 
367 MONGOCRYPT_EXPORT
368 bool
370  mongocrypt_binary_t *key);
371 
372 
385 MONGOCRYPT_EXPORT
386 bool
388  mongocrypt_binary_t *schema_map);
389 
390 
404 MONGOCRYPT_EXPORT
405 bool
407 
408 
418 MONGOCRYPT_EXPORT
419 bool
421 
422 
428 MONGOCRYPT_EXPORT
429 void
431 
432 
436 typedef struct _mongocrypt_ctx_t mongocrypt_ctx_t;
437 
438 
448 MONGOCRYPT_EXPORT
451 
452 
464 MONGOCRYPT_EXPORT
465 bool
467 
468 
483 MONGOCRYPT_EXPORT
484 bool
486  mongocrypt_binary_t *key_id);
487 
510 MONGOCRYPT_EXPORT
511 bool
513  mongocrypt_binary_t *key_alt_name);
514 
535 MONGOCRYPT_EXPORT
536 bool
538  const char *algorithm,
539  int len);
540 
541 
557 MONGOCRYPT_EXPORT
558 bool
560  const char *region,
561  int32_t region_len,
562  const char *cmk,
563  int32_t cmk_len);
564 
565 
580 MONGOCRYPT_EXPORT
581 bool
583  const char *endpoint,
584  int32_t endpoint_len);
585 
594 MONGOCRYPT_EXPORT
595 bool
597 
598 
613 MONGOCRYPT_EXPORT
614 bool
616 
631 MONGOCRYPT_EXPORT
632 bool
634  const char *db,
635  int32_t db_len,
636  mongocrypt_binary_t *cmd);
637 
660 MONGOCRYPT_EXPORT
661 bool
663  mongocrypt_binary_t *msg);
664 
665 
679 MONGOCRYPT_EXPORT
680 bool
682 
683 
693 MONGOCRYPT_EXPORT
694 bool
696  mongocrypt_binary_t *msg);
697 
698 
705 typedef enum {
706  MONGOCRYPT_CTX_ERROR = 0,
707  MONGOCRYPT_CTX_NEED_MONGO_COLLINFO = 1, /* run on main MongoClient */
708  MONGOCRYPT_CTX_NEED_MONGO_MARKINGS = 2, /* run on mongocryptd. */
709  MONGOCRYPT_CTX_NEED_MONGO_KEYS = 3, /* run on key vault */
710  MONGOCRYPT_CTX_NEED_KMS = 4,
711  MONGOCRYPT_CTX_READY = 5, /* ready for encryption/decryption */
712  MONGOCRYPT_CTX_DONE = 6
714 
715 
722 MONGOCRYPT_EXPORT
725 
726 
747 MONGOCRYPT_EXPORT
748 bool
750 
751 
774 MONGOCRYPT_EXPORT
775 bool
777 
778 
786 MONGOCRYPT_EXPORT
787 bool
789 
790 
794 typedef struct _mongocrypt_kms_ctx_t mongocrypt_kms_ctx_t;
795 
796 
810 MONGOCRYPT_EXPORT
813 
814 
828 MONGOCRYPT_EXPORT
829 bool
831  mongocrypt_binary_t *msg);
832 
833 
847 MONGOCRYPT_EXPORT
848 bool
849 mongocrypt_kms_ctx_endpoint (mongocrypt_kms_ctx_t *kms, const char **endpoint);
850 
851 
858 MONGOCRYPT_EXPORT
859 uint32_t
861 
862 
875 MONGOCRYPT_EXPORT
876 bool
878 
879 
888 MONGOCRYPT_EXPORT
889 bool
891  mongocrypt_status_t *status);
892 
893 
902 MONGOCRYPT_EXPORT
903 bool
905 
906 
936 MONGOCRYPT_EXPORT
937 bool
939 
940 
946 MONGOCRYPT_EXPORT
947 void
949 
967 typedef bool (*mongocrypt_crypto_fn) (void *ctx,
968  mongocrypt_binary_t *key,
971  mongocrypt_binary_t *out,
972  uint32_t *bytes_written,
973  mongocrypt_status_t *status);
974 
989 typedef bool (*mongocrypt_hmac_fn) (void *ctx,
990  mongocrypt_binary_t *key,
992  mongocrypt_binary_t *out,
993  mongocrypt_status_t *status);
994 
995 
1009 typedef bool (*mongocrypt_hash_fn) (void *ctx,
1010  mongocrypt_binary_t *in,
1011  mongocrypt_binary_t *out,
1012  mongocrypt_status_t *status);
1013 
1027 typedef bool (*mongocrypt_random_fn) (void *ctx,
1028  mongocrypt_binary_t *out,
1029  uint32_t count,
1030  mongocrypt_status_t *status);
1031 
1032 MONGOCRYPT_EXPORT
1033 bool
1034 mongocrypt_setopt_crypto_hooks (mongocrypt_t *crypt,
1035  mongocrypt_crypto_fn aes_256_cbc_encrypt,
1036  mongocrypt_crypto_fn aes_256_cbc_decrypt,
1037  mongocrypt_random_fn random,
1038  mongocrypt_hmac_fn hmac_sha_512,
1039  mongocrypt_hmac_fn hmac_sha_256,
1040  mongocrypt_hash_fn sha_256,
1041  void *ctx);
1042 
1043 
1044 #endif /* MONGOCRYPT_H */
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:989
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:967
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:794
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:1009
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_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 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:1027
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:705
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_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:436
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 uint8_t * mongocrypt_binary_data(const mongocrypt_binary_t *binary)
struct _mongocrypt_binary_t mongocrypt_binary_t
Definition: mongocrypt.h:70