-
Notifications
You must be signed in to change notification settings - Fork 85
/
mongocrypt.h
1528 lines (1432 loc) · 55.8 KB
/
mongocrypt.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/*
* Copyright 2019-present MongoDB, Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#ifndef MONGOCRYPT_H
#define MONGOCRYPT_H
/** @file mongocrypt.h The top-level handle to libmongocrypt. */
/**
* @mainpage libmongocrypt
* See all public API documentation in: @ref mongocrypt.h
*/
#include "mongocrypt-compat.h"
#include "mongocrypt-export.h"
/* clang-format off */
#ifndef __has_include
#include "mongocrypt-config.h"
#else
#if __has_include("mongocrypt-config.h")
#include "mongocrypt-config.h"
#else
#error No "mongocrypt-config.h" header is available. That file must \
be generated in order to use libmongocrypt.
#endif
#endif
/* clang-format on */
/**
* Returns the version string for libmongocrypt.
*
* @param[out] len An optional length of the returned string. May be NULL.
* @returns a NULL terminated version string for libmongocrypt.
*/
MONGOCRYPT_EXPORT
const char *mongocrypt_version(uint32_t *len);
/**
* Returns true if libmongocrypt was built with native crypto support.
*
* If libmongocrypt was not built with native crypto support, setting crypto
* hooks is required.
*
* @returns True if libmongocrypt was built with native crypto support.
*/
MONGOCRYPT_EXPORT
bool mongocrypt_is_crypto_available(void);
/**
* A non-owning view of a byte buffer.
*
* When constructing a mongocrypt_binary_t it is the responsibility of the
* caller to maintain the lifetime of the viewed data. However, all public
* functions that take a mongocrypt_binary_t as an argument will make a copy of
* the viewed data. For example, the following is valid:
*
* @code{.c}
* mongocrypt_binary_t bin = mongocrypt_binary_new_from_data(mydata, mylen);
* assert (mongocrypt_setopt_kms_provider_local (crypt), bin);
* // The viewed data of bin has been copied. Ok to free the view and the data.
* mongocrypt_binary_destroy (bin);
* my_free_fn (mydata);
* @endcode
*
* Functions with a mongocrypt_binary_t* out guarantee the lifetime of the
* viewed data to live as long as the parent object. For example, @ref
* mongocrypt_ctx_mongo_op guarantees that the viewed data of
* mongocrypt_binary_t is valid until the parent ctx is destroyed with @ref
* mongocrypt_ctx_destroy.
*
* The `mongocrypt_binary_t` struct definition is public.
* Consumers may rely on the struct layout.
*/
typedef struct _mongocrypt_binary_t {
void *data;
uint32_t len;
} mongocrypt_binary_t;
/**
* Create a new non-owning view of a buffer (data + length).
*
* Use this to create a mongocrypt_binary_t used for output parameters.
*
* @returns A new mongocrypt_binary_t.
*/
MONGOCRYPT_EXPORT
mongocrypt_binary_t *mongocrypt_binary_new(void);
/**
* Create a new non-owning view of a buffer (data + length).
*
* @param[in] data A pointer to an array of bytes. This data is not copied. @p
* data must outlive the binary object.
* @param[in] len The length of the @p data byte array.
*
* @returns A new @ref mongocrypt_binary_t.
*/
MONGOCRYPT_EXPORT
mongocrypt_binary_t *mongocrypt_binary_new_from_data(uint8_t *data, uint32_t len);
/**
* Get a pointer to the viewed data.
*
* @param[in] binary The @ref mongocrypt_binary_t.
*
* @returns A pointer to the viewed data.
*/
MONGOCRYPT_EXPORT
uint8_t *mongocrypt_binary_data(const mongocrypt_binary_t *binary);
/**
* Get the length of the viewed data.
*
* @param[in] binary The @ref mongocrypt_binary_t.
*
* @returns The length of the viewed data.
*/
MONGOCRYPT_EXPORT
uint32_t mongocrypt_binary_len(const mongocrypt_binary_t *binary);
/**
* Free the @ref mongocrypt_binary_t.
*
* This does not free the viewed data.
*
* @param[in] binary The mongocrypt_binary_t destroy.
*/
MONGOCRYPT_EXPORT
void mongocrypt_binary_destroy(mongocrypt_binary_t *binary);
/**
* Indicates success or contains error information.
*
* Functions like @ref mongocrypt_ctx_encrypt_init follow a pattern to expose a
* status. A boolean is returned. True indicates success, and false indicates
* failure. On failure a status on the handle is set, and is accessible with a
* corresponding (handle)_status function. E.g. @ref mongocrypt_ctx_status.
*/
typedef struct _mongocrypt_status_t mongocrypt_status_t;
/**
* Indicates the type of error.
*/
typedef enum {
MONGOCRYPT_STATUS_OK = 0,
MONGOCRYPT_STATUS_ERROR_CLIENT = 1,
MONGOCRYPT_STATUS_ERROR_KMS = 2,
MONGOCRYPT_STATUS_ERROR_CRYPT_SHARED = 3,
} mongocrypt_status_type_t;
/**
* Create a new status object.
*
* Use a new status object to retrieve the status from a handle by passing
* this as an out-parameter to functions like @ref mongocrypt_ctx_status.
* When done, destroy it with @ref mongocrypt_status_destroy.
*
* @returns A new status object.
*/
MONGOCRYPT_EXPORT
mongocrypt_status_t *mongocrypt_status_new(void);
/**
* Set a status object with message, type, and code.
*
* Use this to set the @ref mongocrypt_status_t given in the crypto hooks.
*
* @param[in] type The status type.
* @param[in] code The status code.
* @param[in] message The message.
* @param[in] message_len Due to historical behavior, pass 1 + the string length
* of @p message (which differs from other functions accepting string
* arguments).
* Alternatively, if message is NULL terminated this may be -1 to tell
* mongocrypt
* to determine the string's length with strlen.
*
*/
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);
/**
* Indicates success or the type of error.
*
* @param[in] status The status object.
*
* @returns A @ref mongocrypt_status_type_t.
*/
MONGOCRYPT_EXPORT
mongocrypt_status_type_t mongocrypt_status_type(mongocrypt_status_t *status);
/**
* Get an error code or 0.
*
* @param[in] status The status object.
*
* @returns An error code.
*/
MONGOCRYPT_EXPORT
uint32_t mongocrypt_status_code(mongocrypt_status_t *status);
/**
* Get the error message associated with a status or NULL.
*
* @param[in] status The status object.
* @param[out] len An optional length of the returned string (excluding the
* trailing NULL byte). May be NULL.
*
* @returns A NULL terminated error message or NULL.
*/
MONGOCRYPT_EXPORT
const char *mongocrypt_status_message(mongocrypt_status_t *status, uint32_t *len);
/**
* Returns true if the status indicates success.
*
* @param[in] status The status to check.
*
* @returns A boolean indicating success. If false, an error status is set.
* Retrieve it with @ref mongocrypt_ctx_status
*/
MONGOCRYPT_EXPORT
bool mongocrypt_status_ok(mongocrypt_status_t *status);
/**
* Free the memory for a status object.
*
* @param[in] status The status to destroy.
*/
MONGOCRYPT_EXPORT
void mongocrypt_status_destroy(mongocrypt_status_t *status);
/**
* Indicates the type of log message.
*/
typedef enum {
MONGOCRYPT_LOG_LEVEL_FATAL = 0,
MONGOCRYPT_LOG_LEVEL_ERROR = 1,
MONGOCRYPT_LOG_LEVEL_WARNING = 2,
MONGOCRYPT_LOG_LEVEL_INFO = 3,
MONGOCRYPT_LOG_LEVEL_TRACE = 4
} mongocrypt_log_level_t;
/**
* A log callback function. Set a custom log callback with @ref
* mongocrypt_setopt_log_handler.
*
* @param[in] message A NULL terminated message.
* @param[in] message_len The length of message.
* @param[in] ctx A context provided by the caller of @ref
* mongocrypt_setopt_log_handler.
*/
typedef void (*mongocrypt_log_fn_t)(mongocrypt_log_level_t level, const char *message, uint32_t message_len, void *ctx);
/**
* The top-level handle to libmongocrypt.
*
* Create a mongocrypt_t handle to perform operations within libmongocrypt:
* encryption, decryption, registering log callbacks, etc.
*
* Functions on a mongocrypt_t are thread safe, though functions on derived
* handles (e.g. mongocrypt_ctx_t) are not and must be owned by a single
* thread. See each handle's documentation for thread-safety considerations.
*
* Multiple mongocrypt_t handles may be created.
*/
typedef struct _mongocrypt_t mongocrypt_t;
/**
* Allocate a new @ref mongocrypt_t object.
*
* Set options using mongocrypt_setopt_* functions, then initialize with @ref
* mongocrypt_init. When done with the @ref mongocrypt_t, free with @ref
* mongocrypt_destroy.
*
* @returns A new @ref mongocrypt_t object.
*/
MONGOCRYPT_EXPORT
mongocrypt_t *mongocrypt_new(void);
/**
* Set a handler on the @ref mongocrypt_t object to get called on every log
* message.
*
* @param[in] crypt The @ref mongocrypt_t object.
* @param[in] log_fn The log callback.
* @param[in] log_ctx A context passed as an argument to the log callback every
* invocation.
* @pre @ref mongocrypt_init has not been called on @p crypt.
* @returns A boolean indicating success. If false, an error status is set.
* Retrieve it with @ref mongocrypt_ctx_status
*/
MONGOCRYPT_EXPORT
bool mongocrypt_setopt_log_handler(mongocrypt_t *crypt, mongocrypt_log_fn_t log_fn, void *log_ctx);
/**
* Enable or disable KMS retry behavior.
*
* @param[in] crypt The @ref mongocrypt_t object.
* @param[in] enable A boolean indicating whether to retry operations.
* @pre @ref mongocrypt_init has not been called on @p crypt.
* @returns A boolean indicating success. If false, an error status is set.
* Retrieve it with @ref mongocrypt_ctx_status
*/
MONGOCRYPT_EXPORT
bool mongocrypt_setopt_retry_kms(mongocrypt_t *crypt, bool enable);
/**
* Configure an AWS KMS provider on the @ref mongocrypt_t object.
*
* This has been superseded by the more flexible:
* @ref mongocrypt_setopt_kms_providers
*
* @param[in] crypt The @ref mongocrypt_t object.
* @param[in] aws_access_key_id The AWS access key ID used to generate KMS
* messages.
* @param[in] aws_access_key_id_len The string length (in bytes) of @p
* aws_access_key_id. Pass -1 to determine the string length with strlen (must
* be NULL terminated).
* @param[in] aws_secret_access_key The AWS secret access key used to generate
* KMS messages.
* @param[in] aws_secret_access_key_len The string length (in bytes) of @p
* aws_secret_access_key. Pass -1 to determine the string length with strlen
* (must be NULL terminated).
* @pre @ref mongocrypt_init has not been called on @p crypt.
* @returns A boolean indicating success. If false, an error status is set.
* Retrieve it with @ref mongocrypt_ctx_status
*/
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);
/**
* Configure a local KMS provider on the @ref mongocrypt_t object.
*
* This has been superseded by the more flexible:
* @ref mongocrypt_setopt_kms_providers
*
* @param[in] crypt The @ref mongocrypt_t object.
* @param[in] key A 96 byte master key used to encrypt and decrypt key vault
* keys. The viewed data is copied. It is valid to destroy @p key with @ref
* mongocrypt_binary_destroy immediately after.
* @pre @ref mongocrypt_init has not been called on @p crypt.
* @returns A boolean indicating success. If false, an error status is set.
* Retrieve it with @ref mongocrypt_ctx_status
*/
MONGOCRYPT_EXPORT
bool mongocrypt_setopt_kms_provider_local(mongocrypt_t *crypt, mongocrypt_binary_t *key);
/**
* Configure KMS providers with a BSON document.
*
* @param[in] crypt The @ref mongocrypt_t object.
* @param[in] kms_providers A BSON document mapping the KMS provider names
* to credentials. Set a KMS provider value to an empty document to supply
* credentials on-demand with @ref mongocrypt_ctx_provide_kms_providers.
* @pre @ref mongocrypt_init has not been called on @p crypt.
* @returns A boolean indicating success. If false, an error status is set.
* Retrieve it with @ref mongocrypt_ctx_status
*/
MONGOCRYPT_EXPORT
bool mongocrypt_setopt_kms_providers(mongocrypt_t *crypt, mongocrypt_binary_t *kms_providers);
/**
* Set a local schema map for encryption.
*
* @param[in] crypt The @ref mongocrypt_t object.
* @param[in] schema_map A BSON document representing the schema map supplied by
* the user. The keys are collection namespaces and values are JSON schemas. The
* viewed data copied. It is valid to destroy @p schema_map with @ref
* mongocrypt_binary_destroy immediately after.
* @pre @p crypt has not been initialized.
* @returns A boolean indicating success. If false, an error status is set.
* Retrieve it with @ref mongocrypt_status
*/
MONGOCRYPT_EXPORT
bool mongocrypt_setopt_schema_map(mongocrypt_t *crypt, mongocrypt_binary_t *schema_map);
/**
* Set a local EncryptedFieldConfigMap for encryption.
*
* @param[in] crypt The @ref mongocrypt_t object.
* @param[in] efc_map A BSON document representing the EncryptedFieldConfigMap
* supplied by the user. The keys are collection namespaces and values are
* EncryptedFieldConfigMap documents. The viewed data copied. It is valid to
* destroy @p efc_map with @ref mongocrypt_binary_destroy immediately after.
* @pre @p crypt has not been initialized.
* @returns A boolean indicating success. If false, an error status is set.
* Retrieve it with @ref mongocrypt_status
*/
MONGOCRYPT_EXPORT
bool mongocrypt_setopt_encrypted_field_config_map(mongocrypt_t *crypt, mongocrypt_binary_t *efc_map);
/**
* @brief Append an additional search directory to the search path for loading
* the crypt_shared dynamic library.
*
* @param[in] crypt The @ref mongocrypt_t object to update
* @param[in] path A null-terminated sequence of bytes for the search path. On
* some filesystems, this may be arbitrary bytes. On other filesystems, this may
* be required to be a valid UTF-8 code unit sequence. If the leading element of
* the path is the literal string "$ORIGIN", that substring will be replaced
* with the directory path containing the executable libmongocrypt module. If
* the path string is literal "$SYSTEM", then libmongocrypt will defer to the
* system's library resolution mechanism to find the crypt_shared library.
*
* @note If no crypt_shared dynamic library is found in any of the directories
* specified by the search paths loaded here, @ref mongocrypt_init() will still
* succeed and continue to operate without crypt_shared.
*
* @note The search paths are searched in the order that they are appended. This
* allows one to provide a precedence in how the library will be discovered. For
* example, appending known directories before appending "$SYSTEM" will allow
* one to supersede the system's installed library, but still fall-back to it if
* the library wasn't found otherwise. If one does not ever append "$SYSTEM",
* then the system's library-search mechanism will never be consulted.
*
* @note If an absolute path to the library is specified using
* @ref mongocrypt_setopt_set_crypt_shared_lib_path_override, then paths
* appended here will have no effect.
*/
MONGOCRYPT_EXPORT
void mongocrypt_setopt_append_crypt_shared_lib_search_path(mongocrypt_t *crypt, const char *path);
/**
* @brief Set a single override path for loading the crypt_shared dynamic
* library.
*
* @param[in] crypt The @ref mongocrypt_t object to update
* @param[in] path A null-terminated sequence of bytes for a path to the
* crypt_shared dynamic library. On some filesystems, this may be arbitrary
* bytes. On other filesystems, this may be required to be a valid UTF-8 code
* unit sequence. If the leading element of the path is the literal string
* `$ORIGIN`, that substring will be replaced with the directory path containing
* the executable libmongocrypt module.
*
* @note This function will do no IO nor path validation. All validation will
* occur during the call to @ref mongocrypt_init.
*
* @note If a crypt_shared library path override is specified here, then no
* paths given to @ref mongocrypt_setopt_append_crypt_shared_lib_search_path
* will be consulted when opening the crypt_shared library.
*
* @note If a path is provided via this API and @ref mongocrypt_init fails to
* initialize a valid crypt_shared library instance for the path specified, then
* the initialization of mongocrypt_t will fail with an error.
*/
MONGOCRYPT_EXPORT
void mongocrypt_setopt_set_crypt_shared_lib_path_override(mongocrypt_t *crypt, const char *path);
/**
* @brief Opt-into handling the MONGOCRYPT_CTX_NEED_KMS_CREDENTIALS state.
*
* If set, before entering the MONGOCRYPT_CTX_NEED_KMS state,
* contexts may enter the MONGOCRYPT_CTX_NEED_KMS_CREDENTIALS state
* and then wait for credentials to be supplied through
* @ref mongocrypt_ctx_provide_kms_providers.
*
* A context will only enter MONGOCRYPT_CTX_NEED_KMS_CREDENTIALS
* if an empty document was set for a KMS provider in @ref
* mongocrypt_setopt_kms_providers.
*
* @param[in] crypt The @ref mongocrypt_t object to update
*/
MONGOCRYPT_EXPORT
void mongocrypt_setopt_use_need_kms_credentials_state(mongocrypt_t *crypt);
/**
* @brief Opt-into handling the MONGOCRYPT_CTX_NEED_MONGO_COLLINFO_WITH_DB state.
*
* A context enters the MONGOCRYPT_CTX_NEED_MONGO_COLLINFO_WITH_DB state when
* processing a `bulkWrite` command. The target database of the `bulkWrite` may differ from the command database
* ("admin").
*
* @param[in] crypt The @ref mongocrypt_t object to update
*/
MONGOCRYPT_EXPORT
void mongocrypt_setopt_use_need_mongo_collinfo_with_db_state(mongocrypt_t *crypt);
/**
* Initialize new @ref mongocrypt_t object.
*
* Set options before using @ref mongocrypt_setopt_kms_provider_local, @ref
* mongocrypt_setopt_kms_provider_aws, or @ref mongocrypt_setopt_log_handler.
*
* @param[in] crypt The @ref mongocrypt_t object.
*
* @returns A boolean indicating success. If false, an error status is set.
* Retrieve it with @ref mongocrypt_ctx_status Failure may occur if previously
* set
* options are invalid.
*/
MONGOCRYPT_EXPORT
bool mongocrypt_init(mongocrypt_t *crypt);
/**
* Get the status associated with a @ref mongocrypt_t object.
*
* @param[in] crypt The @ref mongocrypt_t object.
* @param[out] status Receives the status.
*
* @returns A boolean indicating success. If false, an error status is set.
* Retrieve it with @ref mongocrypt_ctx_status
*/
MONGOCRYPT_EXPORT
bool mongocrypt_status(mongocrypt_t *crypt, mongocrypt_status_t *status);
/**
* Destroy the @ref mongocrypt_t object.
*
* @param[in] crypt The @ref mongocrypt_t object to destroy.
*/
MONGOCRYPT_EXPORT
void mongocrypt_destroy(mongocrypt_t *crypt);
/**
* Obtain a nul-terminated version string of the loaded crypt_shared dynamic
* library, if available.
*
* If no crypt_shared was successfully loaded, this function returns NULL.
*
* @param[in] crypt The mongocrypt_t object after a successful call to
* mongocrypt_init.
* @param[out] len An optional output parameter to which the length of the
* returned string is written. If provided and no crypt_shared library was
* loaded, zero is written to *len.
*
* @return A nul-terminated string of the dynamically loaded crypt_shared
* library.
*
* @note For a numeric value that can be compared against, use
* @ref mongocrypt_crypt_shared_lib_version.
*/
MONGOCRYPT_EXPORT
const char *mongocrypt_crypt_shared_lib_version_string(const mongocrypt_t *crypt, uint32_t *len);
/**
* @brief Obtain a 64-bit constant encoding the version of the loaded
* crypt_shared library, if available.
*
* @param[in] crypt The mongocrypt_t object after a successful call to
* mongocrypt_init.
*
* @return A 64-bit encoded version number, with the version encoded as four
* sixteen-bit integers, or zero if no crypt_shared library was loaded.
*
* The version is encoded as four 16-bit numbers, from high to low:
*
* - Major version
* - Minor version
* - Revision
* - Reserved
*
* For example, version 6.2.1 would be encoded as: 0x0006'0002'0001'0000
*/
MONGOCRYPT_EXPORT
uint64_t mongocrypt_crypt_shared_lib_version(const mongocrypt_t *crypt);
/**
* Manages the state machine for encryption or decryption.
*/
typedef struct _mongocrypt_ctx_t mongocrypt_ctx_t;
/**
* Create a new uninitialized @ref mongocrypt_ctx_t.
*
* Initialize the context with functions like @ref mongocrypt_ctx_encrypt_init.
* When done, destroy it with @ref mongocrypt_ctx_destroy.
*
* @param[in] crypt The @ref mongocrypt_t object.
* @returns A new context.
*/
MONGOCRYPT_EXPORT
mongocrypt_ctx_t *mongocrypt_ctx_new(mongocrypt_t *crypt);
/**
* Get the status associated with a @ref mongocrypt_ctx_t object.
*
* @param[in] ctx The @ref mongocrypt_ctx_t object.
* @param[out] status Receives the status.
*
* @returns True if the output is an ok status, false if it is an error
* status.
*
* @see mongocrypt_status_ok
*/
MONGOCRYPT_EXPORT
bool mongocrypt_ctx_status(mongocrypt_ctx_t *ctx, mongocrypt_status_t *status);
/**
* Set the key id to use for explicit encryption.
*
* It is an error to set both this and the key alt name.
*
* @param[in] ctx The @ref mongocrypt_ctx_t object.
* @param[in] key_id The binary corresponding to the _id (a UUID) of the data
* key to use from the key vault collection. Note, the UUID must be encoded with
* RFC-4122 byte order. The viewed data is copied. It is valid to destroy
* @p key_id with @ref mongocrypt_binary_destroy immediately after.
* @pre @p ctx has not been initialized.
* @returns A boolean indicating success. If false, an error status is set.
* Retrieve it with @ref mongocrypt_ctx_status
*/
MONGOCRYPT_EXPORT
bool mongocrypt_ctx_setopt_key_id(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *key_id);
/**
* Set the keyAltName to use for explicit encryption or
* data key creation.
*
* Pass the binary encoding a BSON document like the following:
*
* { "keyAltName" : (BSON UTF8 value) }
*
* For explicit encryption, it is an error to set both the keyAltName
* and the key id.
*
* For creating data keys, call this function repeatedly to set
* multiple keyAltNames.
*
* @param[in] ctx The @ref mongocrypt_ctx_t object.
* @param[in] key_alt_name The name to use. The viewed data is copied. It is
* valid to destroy @p key_alt_name with @ref mongocrypt_binary_destroy
* immediately after.
* @pre @p ctx has not been initialized.
* @returns A boolean indicating success. If false, an error status is set.
* Retrieve it with @ref mongocrypt_ctx_status
*/
MONGOCRYPT_EXPORT
bool mongocrypt_ctx_setopt_key_alt_name(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *key_alt_name);
/**
* Set the keyMaterial to use for encrypting data.
*
* Pass the binary encoding of a BSON document like the following:
*
* { "keyMaterial" : (BSON BINARY value) }
*
* @param[in] ctx The @ref mongocrypt_ctx_t object.
* @param[in] key_material The data encryption key to use. The viewed data is
* copied. It is valid to destroy @p key_material with @ref
* mongocrypt_binary_destroy immediately after.
* @pre @p ctx has not been initialized.
* @returns A boolean indicating success. If false, an error status is set.
* Retrieve it with @ref mongocrypt_ctx_status
*/
MONGOCRYPT_EXPORT
bool mongocrypt_ctx_setopt_key_material(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *key_material);
/**
* Set the algorithm used for encryption to either
* deterministic or random encryption. This value
* should only be set when using explicit encryption.
*
* If -1 is passed in for "len", then "algorithm" is
* assumed to be a null-terminated string.
*
* Valid values for algorithm are:
* "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"
* "AEAD_AES_256_CBC_HMAC_SHA_512-Random"
*
* @param[in] ctx The @ref mongocrypt_ctx_t object.
* @param[in] algorithm A string specifying the algorithm to
* use for encryption.
* @param[in] len The length of the algorithm string.
* @pre @p ctx has not been initialized.
* @returns A boolean indicating success. If false, an error status is set.
* Retrieve it with @ref mongocrypt_ctx_status
*/
MONGOCRYPT_EXPORT
bool mongocrypt_ctx_setopt_algorithm(mongocrypt_ctx_t *ctx, const char *algorithm, int len);
/// String constant for setopt_algorithm "Deterministic" encryption
#define MONGOCRYPT_ALGORITHM_DETERMINISTIC_STR "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"
/// String constant for setopt_algorithm "Random" encryption
#define MONGOCRYPT_ALGORITHM_RANDOM_STR "AEAD_AES_256_CBC_HMAC_SHA_512-Random"
/// String constant for setopt_algorithm "Indexed" explicit encryption
#define MONGOCRYPT_ALGORITHM_INDEXED_STR "Indexed"
/// String constant for setopt_algorithm "Unindexed" explicit encryption
#define MONGOCRYPT_ALGORITHM_UNINDEXED_STR "Unindexed"
// DEPRECATED: support "RangePreview" has been removed in favor of "range".
#define MONGOCRYPT_ALGORITHM_RANGEPREVIEW_DEPRECATED_STR "RangePreview"
#define MONGOCRYPT_ALGORITHM_RANGE_STR "Range"
/**
* Identify the AWS KMS master key to use for creating a data key.
*
* This has been superseded by the more flexible:
* @ref mongocrypt_ctx_setopt_key_encryption_key
*
* @param[in] ctx The @ref mongocrypt_ctx_t object.
* @param[in] region The AWS region.
* @param[in] region_len The string length of @p region. Pass -1 to determine
* the string length with strlen (must be NULL terminated).
* @param[in] cmk The Amazon Resource Name (ARN) of the customer master key
* (CMK).
* @param[in] cmk_len The string length of @p cmk_len. Pass -1 to determine the
* string length with strlen (must be NULL terminated).
* @pre @p ctx has not been initialized.
* @returns A boolean indicating success. If false, an error status is set.
* Retrieve it with @ref mongocrypt_ctx_status
*/
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);
/**
* Identify a custom AWS endpoint when creating a data key.
* This is used internally to construct the correct HTTP request
* (with the Host header set to this endpoint). This endpoint
* is persisted in the new data key, and will be returned via
* @ref mongocrypt_kms_ctx_endpoint.
*
* This has been superseded by the more flexible:
* @ref mongocrypt_ctx_setopt_key_encryption_key
*
* @param[in] ctx The @ref mongocrypt_ctx_t object.
* @param[in] endpoint The endpoint.
* @param[in] endpoint_len The string length of @p endpoint. Pass -1 to
* determine the string length with strlen (must be NULL terminated).
* @returns A boolean indicating success. If false, an error status is set.
* Retrieve it with @ref mongocrypt_ctx_status
*/
MONGOCRYPT_EXPORT
bool mongocrypt_ctx_setopt_masterkey_aws_endpoint(mongocrypt_ctx_t *ctx, const char *endpoint, int32_t endpoint_len);
/**
* Set the master key to "local" for creating a data key.
* This has been superseded by the more flexible:
* @ref mongocrypt_ctx_setopt_key_encryption_key
*
* @param[in] ctx The @ref mongocrypt_ctx_t object.
* @pre @p ctx has not been initialized.
* @returns A boolean indicating success. If false, an error status is set.
* Retrieve it with @ref mongocrypt_ctx_status
*/
MONGOCRYPT_EXPORT
bool mongocrypt_ctx_setopt_masterkey_local(mongocrypt_ctx_t *ctx);
/**
* Set key encryption key document for creating a data key or for rewrapping
* datakeys.
*
* @param[in] ctx The @ref mongocrypt_ctx_t object.
* @param[in] bin BSON representing the key encryption key document with
* an additional "provider" field. The following forms are accepted:
*
* AWS
* {
* provider: "aws",
* region: <string>,
* key: <string>,
* endpoint: <optional string>
* }
*
* Azure
* {
* provider: "azure",
* keyVaultEndpoint: <string>,
* keyName: <string>,
* keyVersion: <optional string>
* }
*
* GCP
* {
* provider: "gcp",
* projectId: <string>,
* location: <string>,
* keyRing: <string>,
* keyName: <string>,
* keyVersion: <optional string>,
* endpoint: <optional string>
* }
*
* Local
* {
* provider: "local"
* }
*
* KMIP
* {
* provider: "kmip",
* keyId: <optional string>
* endpoint: <string>
* }
*
* @pre @p ctx has not been initialized.
* @returns A boolean indicating success. If false, an error status is set.
* Retrieve it with @ref mongocrypt_ctx_status.
*/
MONGOCRYPT_EXPORT
bool mongocrypt_ctx_setopt_key_encryption_key(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *bin);
/**
* Initialize a context to create a data key.
*
* Associated options:
* - @ref mongocrypt_ctx_setopt_masterkey_aws
* - @ref mongocrypt_ctx_setopt_masterkey_aws_endpoint
* - @ref mongocrypt_ctx_setopt_masterkey_local
*
* @param[in] ctx The @ref mongocrypt_ctx_t object.
* @returns A boolean indicating success. If false, an error status is set.
* Retrieve it with @ref mongocrypt_ctx_status
* @pre A master key option has been set, and an associated KMS provider
* has been set on the parent @ref mongocrypt_t.
*/
MONGOCRYPT_EXPORT
bool mongocrypt_ctx_datakey_init(mongocrypt_ctx_t *ctx);
/**
* Initialize a context for encryption.
*
* @param[in] ctx The @ref mongocrypt_ctx_t object.
* @param[in] db The database name.
* @param[in] db_len The byte length of @p db. Pass -1 to determine the string
* length with strlen (must
* be NULL terminated).
* @param[in] cmd The BSON command to be encrypted. The viewed data is copied.
* It is valid to destroy @p cmd with @ref mongocrypt_binary_destroy immediately
* after.
* @returns A boolean indicating success. If false, an error status is set.
* Retrieve it with @ref mongocrypt_ctx_status
*/
MONGOCRYPT_EXPORT
bool mongocrypt_ctx_encrypt_init(mongocrypt_ctx_t *ctx, const char *db, int32_t db_len, mongocrypt_binary_t *cmd);
/**
* Explicit helper method to encrypt a single BSON object. Contexts
* created for explicit encryption will not go through mongocryptd.
*
* To specify a key_id, algorithm, or iv to use, please use the
* corresponding mongocrypt_setopt methods before calling this.
*
* This method expects the passed-in BSON to be of the form:
* { "v" : BSON value to encrypt }
*
* The value of "v" is expected to be the BSON value passed to a driver
* ClientEncryption.encrypt helper.
*
* Associated options for FLE 1:
* - @ref mongocrypt_ctx_setopt_key_id
* - @ref mongocrypt_ctx_setopt_key_alt_name
* - @ref mongocrypt_ctx_setopt_algorithm
*
* Associated options for Queryable Encryption:
* - @ref mongocrypt_ctx_setopt_key_id
* - @ref mongocrypt_ctx_setopt_index_key_id
* - @ref mongocrypt_ctx_setopt_contention_factor
* - @ref mongocrypt_ctx_setopt_query_type
* - @ref mongocrypt_ctx_setopt_algorithm_range
*
* An error is returned if FLE 1 and Queryable Encryption incompatible options
* are set.
*
* @param[in] ctx A @ref mongocrypt_ctx_t.
* @param[in] msg A @ref mongocrypt_binary_t the plaintext BSON value. The
* viewed data is copied. It is valid to destroy @p msg with @ref
* mongocrypt_binary_destroy immediately after.
* @returns A boolean indicating success. If false, an error status is set.
* Retrieve it with @ref mongocrypt_ctx_status
*/
MONGOCRYPT_EXPORT
bool mongocrypt_ctx_explicit_encrypt_init(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *msg);
/**
* Explicit helper method to encrypt a Match Expression or Aggregate Expression.
* Contexts created for explicit encryption will not go through mongocryptd.
* Requires query_type to be "range".
*
* This method expects the passed-in BSON to be of the form:
* { "v" : FLE2RangeFindDriverSpec }
*
* FLE2RangeFindDriverSpec is a BSON document with one of these forms:
*
* 1. A Match Expression of this form:
* {$and: [{<field>: {<op>: <value1>, {<field>: {<op>: <value2> }}]}
* 2. An Aggregate Expression of this form:
* {$and: [{<op>: [<fieldpath>, <value1>]}, {<op>: [<fieldpath>, <value2>]}]
*
* <op> may be $lt, $lte, $gt, or $gte.
*
* The value of "v" is expected to be the BSON value passed to a driver
* ClientEncryption.encryptExpression helper.
*
* Associated options for FLE 1:
* - @ref mongocrypt_ctx_setopt_key_id
* - @ref mongocrypt_ctx_setopt_key_alt_name
* - @ref mongocrypt_ctx_setopt_algorithm
*
* Associated options for Queryable Encryption:
* - @ref mongocrypt_ctx_setopt_key_id
* - @ref mongocrypt_ctx_setopt_index_key_id
* - @ref mongocrypt_ctx_setopt_contention_factor
* - @ref mongocrypt_ctx_setopt_query_type
* - @ref mongocrypt_ctx_setopt_algorithm_range
*
* An error is returned if FLE 1 and Queryable Encryption incompatible options
* are set.
*
* @param[in] ctx A @ref mongocrypt_ctx_t.
* @param[in] msg A @ref mongocrypt_binary_t the plaintext BSON value. The
* viewed data is copied. It is valid to destroy @p msg with @ref
* mongocrypt_binary_destroy immediately after.
* @returns A boolean indicating success. If false, an error status is set.
* Retrieve it with @ref mongocrypt_ctx_status
*/
MONGOCRYPT_EXPORT
bool mongocrypt_ctx_explicit_encrypt_expression_init(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *msg);
/**
* Initialize a context for decryption.
*
* This method expects the passed-in BSON to be of the form:
* { "v" : BSON value to encrypt }
*
* @param[in] ctx The @ref mongocrypt_ctx_t object.
* @param[in] doc The document to be decrypted. The viewed data is copied. It is
* valid to destroy @p doc with @ref mongocrypt_binary_destroy immediately
* after.
* @returns A boolean indicating success. If false, an error status is set.
* Retrieve it with @ref mongocrypt_ctx_status
*/
MONGOCRYPT_EXPORT
bool mongocrypt_ctx_decrypt_init(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *doc);
/**
* Explicit helper method to decrypt a single BSON object.
*
* Pass the binary encoding of a BSON document containing the BSON value to
* encrypt like the following:
*
* { "v" : (BSON BINARY value of subtype 6) }
*
* @param[in] ctx A @ref mongocrypt_ctx_t.
* @param[in] msg A @ref mongocrypt_binary_t the encrypted BSON. The viewed data
* is copied. It is valid to destroy @p msg with @ref mongocrypt_binary_destroy
* immediately after.
*/
MONGOCRYPT_EXPORT
bool mongocrypt_ctx_explicit_decrypt_init(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *msg);
/**
* @brief Initialize a context to rewrap datakeys.
*
* Associated options:
* - @ref mongocrypt_ctx_setopt_key_encryption_key
*
* @param[in] ctx The @ref mongocrypt_ctx_t object.
* @param[in] filter The filter to use for the find command on the key vault
* collection to retrieve datakeys to rewrap.
* @return A boolean indicating success. If false, an error status is set.
* Retrieve it with @ref mongocrypt_ctx_status.
*/
MONGOCRYPT_EXPORT
bool mongocrypt_ctx_rewrap_many_datakey_init(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *filter);
/**
* Indicates the state of the @ref mongocrypt_ctx_t. Each state requires
* different handling. See [the integration
* guide](https://github.com/mongodb/libmongocrypt/blob/master/integrating.md#state-machine)
* for information on what to do for each state.
*/
typedef enum {
MONGOCRYPT_CTX_ERROR = 0,
MONGOCRYPT_CTX_NEED_MONGO_COLLINFO = 1, /* run on main MongoClient */
MONGOCRYPT_CTX_NEED_MONGO_COLLINFO_WITH_DB = 8, /* run on main MongoClient */
MONGOCRYPT_CTX_NEED_MONGO_MARKINGS = 2, /* run on mongocryptd. */
MONGOCRYPT_CTX_NEED_MONGO_KEYS = 3, /* run on key vault */
MONGOCRYPT_CTX_NEED_KMS = 4,
MONGOCRYPT_CTX_NEED_KMS_CREDENTIALS = 7, /* fetch/renew KMS credentials */
MONGOCRYPT_CTX_READY = 5, /* ready for encryption/decryption */
MONGOCRYPT_CTX_DONE = 6,
} mongocrypt_ctx_state_t;
/**
* Get the current state of a context.