mongocrypt.h

Go to the documentation of this file.

/*
 * 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
 
#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 */
 
MONGOCRYPT_EXPORT
const char *mongocrypt_version(uint32_t *len);
 
MONGOCRYPT_EXPORT
bool mongocrypt_is_crypto_available(void);
 
typedef struct _mongocrypt_binary_t {
    void *data;
    uint32_t len;
} mongocrypt_binary_t;
 
MONGOCRYPT_EXPORT
mongocrypt_binary_t *mongocrypt_binary_new(void);
 
MONGOCRYPT_EXPORT
mongocrypt_binary_t *mongocrypt_binary_new_from_data(uint8_t *data, uint32_t len);
 
MONGOCRYPT_EXPORT
uint8_t *mongocrypt_binary_data(const mongocrypt_binary_t *binary);
 
MONGOCRYPT_EXPORT
uint32_t mongocrypt_binary_len(const mongocrypt_binary_t *binary);
 
MONGOCRYPT_EXPORT
void mongocrypt_binary_destroy(mongocrypt_binary_t *binary);
 
typedef struct _mongocrypt_status_t mongocrypt_status_t;
 
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;
 
MONGOCRYPT_EXPORT
mongocrypt_status_t *mongocrypt_status_new(void);
 
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_type_t mongocrypt_status_type(mongocrypt_status_t *status);
 
MONGOCRYPT_EXPORT
uint32_t mongocrypt_status_code(mongocrypt_status_t *status);
 
MONGOCRYPT_EXPORT
const char *mongocrypt_status_message(mongocrypt_status_t *status, uint32_t *len);
 
MONGOCRYPT_EXPORT
bool mongocrypt_status_ok(mongocrypt_status_t *status);
 
MONGOCRYPT_EXPORT
void mongocrypt_status_destroy(mongocrypt_status_t *status);
 
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;
 
typedef void (*mongocrypt_log_fn_t)(mongocrypt_log_level_t level, const char *message, uint32_t message_len, void *ctx);
 
typedef struct _mongocrypt_t mongocrypt_t;
 
MONGOCRYPT_EXPORT
mongocrypt_t *mongocrypt_new(void);
 
MONGOCRYPT_EXPORT
bool mongocrypt_setopt_log_handler(mongocrypt_t *crypt, mongocrypt_log_fn_t log_fn, void *log_ctx);
 
MONGOCRYPT_EXPORT
bool mongocrypt_setopt_retry_kms(mongocrypt_t *crypt, bool enable);
 
MONGOCRYPT_EXPORT
bool mongocrypt_setopt_enable_multiple_collinfo(mongocrypt_t *crypt);
 
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
bool mongocrypt_setopt_kms_provider_local(mongocrypt_t *crypt, mongocrypt_binary_t *key);
 
MONGOCRYPT_EXPORT
bool mongocrypt_setopt_kms_providers(mongocrypt_t *crypt, mongocrypt_binary_t *kms_providers);
 
MONGOCRYPT_EXPORT
bool mongocrypt_setopt_schema_map(mongocrypt_t *crypt, mongocrypt_binary_t *schema_map);
 
MONGOCRYPT_EXPORT
bool mongocrypt_setopt_encrypted_field_config_map(mongocrypt_t *crypt, mongocrypt_binary_t *efc_map);
 
MONGOCRYPT_EXPORT
void mongocrypt_setopt_append_crypt_shared_lib_search_path(mongocrypt_t *crypt, const char *path);
 
MONGOCRYPT_EXPORT
void mongocrypt_setopt_set_crypt_shared_lib_path_override(mongocrypt_t *crypt, const char *path);
 
MONGOCRYPT_EXPORT
void mongocrypt_setopt_use_need_kms_credentials_state(mongocrypt_t *crypt);
 
MONGOCRYPT_EXPORT
void mongocrypt_setopt_use_need_mongo_collinfo_with_db_state(mongocrypt_t *crypt);
 
MONGOCRYPT_EXPORT
bool mongocrypt_init(mongocrypt_t *crypt);
 
MONGOCRYPT_EXPORT
bool mongocrypt_status(mongocrypt_t *crypt, mongocrypt_status_t *status);
 
MONGOCRYPT_EXPORT
void mongocrypt_destroy(mongocrypt_t *crypt);
 
MONGOCRYPT_EXPORT
const char *mongocrypt_crypt_shared_lib_version_string(const mongocrypt_t *crypt, uint32_t *len);
 
MONGOCRYPT_EXPORT
uint64_t mongocrypt_crypt_shared_lib_version(const mongocrypt_t *crypt);
 
typedef struct _mongocrypt_ctx_t mongocrypt_ctx_t;
 
MONGOCRYPT_EXPORT
mongocrypt_ctx_t *mongocrypt_ctx_new(mongocrypt_t *crypt);
 
MONGOCRYPT_EXPORT
bool mongocrypt_ctx_status(mongocrypt_ctx_t *ctx, mongocrypt_status_t *status);
 
MONGOCRYPT_EXPORT
bool mongocrypt_ctx_setopt_key_id(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *key_id);
 
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
bool mongocrypt_ctx_setopt_algorithm(mongocrypt_ctx_t *ctx, const char *algorithm, int len);
 
#define MONGOCRYPT_ALGORITHM_DETERMINISTIC_STR "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"
#define MONGOCRYPT_ALGORITHM_RANDOM_STR "AEAD_AES_256_CBC_HMAC_SHA_512-Random"
#define MONGOCRYPT_ALGORITHM_INDEXED_STR "Indexed"
#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"
#define MONGOCRYPT_ALGORITHM_TEXTPREVIEW_STR "textPreview"
 
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_masterkey_aws_endpoint(mongocrypt_ctx_t *ctx, const char *endpoint, int32_t endpoint_len);
 
MONGOCRYPT_EXPORT
bool mongocrypt_ctx_setopt_masterkey_local(mongocrypt_ctx_t *ctx);
 
MONGOCRYPT_EXPORT
bool mongocrypt_ctx_setopt_key_encryption_key(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *bin);
 
MONGOCRYPT_EXPORT
bool mongocrypt_ctx_datakey_init(mongocrypt_ctx_t *ctx);
 
MONGOCRYPT_EXPORT
bool mongocrypt_ctx_encrypt_init(mongocrypt_ctx_t *ctx, const char *db, int32_t db_len, mongocrypt_binary_t *cmd);
 
MONGOCRYPT_EXPORT
bool mongocrypt_ctx_explicit_encrypt_init(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *msg);
 
MONGOCRYPT_EXPORT
bool mongocrypt_ctx_explicit_encrypt_expression_init(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *msg);
 
MONGOCRYPT_EXPORT
bool mongocrypt_ctx_decrypt_init(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *doc);
 
MONGOCRYPT_EXPORT
bool mongocrypt_ctx_explicit_decrypt_init(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *msg);
 
MONGOCRYPT_EXPORT
bool mongocrypt_ctx_rewrap_many_datakey_init(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *filter);
 
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;
 
MONGOCRYPT_EXPORT
mongocrypt_ctx_state_t mongocrypt_ctx_state(mongocrypt_ctx_t *ctx);
 
MONGOCRYPT_EXPORT
bool mongocrypt_ctx_mongo_op(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *op_bson);
 
MONGOCRYPT_EXPORT
const char *mongocrypt_ctx_mongo_db(mongocrypt_ctx_t *ctx);
 
MONGOCRYPT_EXPORT
bool mongocrypt_ctx_mongo_feed(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *reply);
 
MONGOCRYPT_EXPORT
bool mongocrypt_ctx_mongo_done(mongocrypt_ctx_t *ctx);
 
typedef struct _mongocrypt_kms_ctx_t mongocrypt_kms_ctx_t;
 
MONGOCRYPT_EXPORT
mongocrypt_kms_ctx_t *mongocrypt_ctx_next_kms_ctx(mongocrypt_ctx_t *ctx);
 
MONGOCRYPT_EXPORT
bool mongocrypt_kms_ctx_message(mongocrypt_kms_ctx_t *kms, mongocrypt_binary_t *msg);
 
MONGOCRYPT_EXPORT
bool mongocrypt_kms_ctx_endpoint(mongocrypt_kms_ctx_t *kms, const char **endpoint);
 
MONGOCRYPT_EXPORT
uint32_t mongocrypt_kms_ctx_bytes_needed(mongocrypt_kms_ctx_t *kms);
 
MONGOCRYPT_EXPORT
int64_t mongocrypt_kms_ctx_usleep(mongocrypt_kms_ctx_t *kms);
 
MONGOCRYPT_EXPORT
bool mongocrypt_kms_ctx_feed(mongocrypt_kms_ctx_t *kms, mongocrypt_binary_t *bytes);
 
MONGOCRYPT_EXPORT
bool mongocrypt_kms_ctx_feed_with_retry(mongocrypt_kms_ctx_t *kms, mongocrypt_binary_t *bytes, bool *should_retry);
 
MONGOCRYPT_EXPORT
bool mongocrypt_kms_ctx_fail(mongocrypt_kms_ctx_t *kms);
 
MONGOCRYPT_EXPORT
bool mongocrypt_kms_ctx_status(mongocrypt_kms_ctx_t *kms, mongocrypt_status_t *status);
 
MONGOCRYPT_EXPORT
const char *mongocrypt_kms_ctx_get_kms_provider(mongocrypt_kms_ctx_t *kms, uint32_t *len);
 
MONGOCRYPT_EXPORT
bool mongocrypt_ctx_kms_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_ctx_finalize(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *out);
 
MONGOCRYPT_EXPORT
void mongocrypt_ctx_destroy(mongocrypt_ctx_t *ctx);
 
typedef 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);
 
typedef bool (*mongocrypt_hmac_fn)(void *ctx,
                                   mongocrypt_binary_t *key,
                                   mongocrypt_binary_t *in,
                                   mongocrypt_binary_t *out,
                                   mongocrypt_status_t *status);
 
typedef bool (*mongocrypt_hash_fn)(void *ctx,
                                   mongocrypt_binary_t *in,
                                   mongocrypt_binary_t *out,
                                   mongocrypt_status_t *status);
 
typedef bool (*mongocrypt_random_fn)(void *ctx, mongocrypt_binary_t *out, uint32_t count, mongocrypt_status_t *status);
 
MONGOCRYPT_EXPORT
bool mongocrypt_setopt_crypto_hooks(mongocrypt_t *crypt,
                                    mongocrypt_crypto_fn aes_256_cbc_encrypt,
                                    mongocrypt_crypto_fn aes_256_cbc_decrypt,
                                    mongocrypt_random_fn random,
                                    mongocrypt_hmac_fn hmac_sha_512,
                                    mongocrypt_hmac_fn hmac_sha_256,
                                    mongocrypt_hash_fn sha_256,
                                    void *ctx);
 
MONGOCRYPT_EXPORT
bool mongocrypt_setopt_aes_256_ctr(mongocrypt_t *crypt,
                                   mongocrypt_crypto_fn aes_256_ctr_encrypt,
                                   mongocrypt_crypto_fn aes_256_ctr_decrypt,
                                   void *ctx);
 
MONGOCRYPT_EXPORT
bool mongocrypt_setopt_aes_256_ecb(mongocrypt_t *crypt, mongocrypt_crypto_fn aes_256_ecb_encrypt, void *ctx);
 
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_bypass_query_analysis(mongocrypt_t *crypt);
 
MONGOCRYPT_EXPORT
bool mongocrypt_setopt_use_range_v2(mongocrypt_t *crypt);
 
MONGOCRYPT_EXPORT
bool mongocrypt_ctx_setopt_contention_factor(mongocrypt_ctx_t *ctx, int64_t contention_factor);
 
MONGOCRYPT_EXPORT
bool mongocrypt_ctx_setopt_index_key_id(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *key_id);
 
MONGOCRYPT_EXPORT
bool mongocrypt_ctx_setopt_query_type(mongocrypt_ctx_t *ctx, const char *query_type, int len);
 
MONGOCRYPT_EXPORT
bool mongocrypt_ctx_setopt_algorithm_range(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *opts);
 
MONGOCRYPT_EXPORT
bool mongocrypt_ctx_setopt_algorithm_text(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *opts);
 
MONGOCRYPT_EXPORT
bool mongocrypt_setopt_key_expiration(mongocrypt_t *crypt, uint64_t cache_expiration_ms);
 
#define MONGOCRYPT_QUERY_TYPE_EQUALITY_STR "equality"
// DEPRECATED: Support "rangePreview" has been removed in favor of "range".
#define MONGOCRYPT_QUERY_TYPE_RANGEPREVIEW_DEPRECATED_STR "rangePreview"
#define MONGOCRYPT_QUERY_TYPE_RANGE_STR "range"
#define MONGOCRYPT_QUERY_TYPE_SUBSTRINGPREVIEW_STR "substringPreview"
#define MONGOCRYPT_QUERY_TYPE_SUFFIXPREVIEW_STR "suffixPreview"
#define MONGOCRYPT_QUERY_TYPE_PREFIXPREVIEW_STR "prefixPreview"
 
#endif /* MONGOCRYPT_H */