Package com.mongodb.crypt.capi

Class CAPI

  • public class CAPI
extends java.lang.Object
    For internal use only. Not part of the public API.

    • Field Detail

      • MONGOCRYPT_STATUS_ERROR_CLIENT

        public static final int MONGOCRYPT_STATUS_ERROR_CLIENT
        See Also:
        Constant Field Values

      • MONGOCRYPT_STATUS_ERROR_KMS

        public static final int MONGOCRYPT_STATUS_ERROR_KMS
        See Also:
        Constant Field Values

      • MONGOCRYPT_LOG_LEVEL_FATAL

        public static final int MONGOCRYPT_LOG_LEVEL_FATAL
        See Also:
        Constant Field Values

      • MONGOCRYPT_LOG_LEVEL_ERROR

        public static final int MONGOCRYPT_LOG_LEVEL_ERROR
        See Also:
        Constant Field Values

      • MONGOCRYPT_LOG_LEVEL_WARNING

        public static final int MONGOCRYPT_LOG_LEVEL_WARNING
        See Also:
        Constant Field Values

      • MONGOCRYPT_LOG_LEVEL_INFO

        public static final int MONGOCRYPT_LOG_LEVEL_INFO
        See Also:
        Constant Field Values

      • MONGOCRYPT_LOG_LEVEL_TRACE

        public static final int MONGOCRYPT_LOG_LEVEL_TRACE
        See Also:
        Constant Field Values

      • MONGOCRYPT_CTX_NEED_MONGO_COLLINFO

        public static final int MONGOCRYPT_CTX_NEED_MONGO_COLLINFO
        See Also:
        Constant Field Values

      • MONGOCRYPT_CTX_NEED_MONGO_MARKINGS

        public static final int MONGOCRYPT_CTX_NEED_MONGO_MARKINGS
        See Also:
        Constant Field Values

      • MONGOCRYPT_CTX_NEED_MONGO_KEYS

        public static final int MONGOCRYPT_CTX_NEED_MONGO_KEYS
        See Also:
        Constant Field Values

      • MONGOCRYPT_CTX_NEED_KMS

        public static final int MONGOCRYPT_CTX_NEED_KMS
        See Also:
        Constant Field Values

      • MONGOCRYPT_CTX_NEED_KMS_CREDENTIALS

        public static final int MONGOCRYPT_CTX_NEED_KMS_CREDENTIALS
        See Also:
        Constant Field Values

      • MONGOCRYPT_INDEX_TYPE_NONE

        public static final int MONGOCRYPT_INDEX_TYPE_NONE
        See Also:
        Constant Field Values

      • MONGOCRYPT_INDEX_TYPE_EQUALITY

        public static final int MONGOCRYPT_INDEX_TYPE_EQUALITY
        See Also:
        Constant Field Values

      • MONGOCRYPT_QUERY_TYPE_EQUALITY

        public static final int MONGOCRYPT_QUERY_TYPE_EQUALITY
        See Also:
        Constant Field Values

    • Constructor Detail

      • CAPI

        public CAPI()

    • Method Detail

      • mongocrypt_version

        public static CAPI.cstring mongocrypt_version​(com.sun.jna.Pointer len)
        Returns the version string x.y.z for libmongocrypt.
        Parameters:
        len - an optional length of the returned string. May be NULL.
        Returns:
        the version string x.y.z for libmongocrypt.

      • mongocrypt_binary_new

        public static CAPI.mongocrypt_binary_t mongocrypt_binary_new()
        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_binary_new_from_data

        public static CAPI.mongocrypt_binary_t mongocrypt_binary_new_from_data​(com.sun.jna.Pointer data,
                                                                       int len)
        Create a new non-owning view of a buffer (data + length).
        Parameters:
        data - A pointer to an array of bytes. This is not copied. data must outlive the binary object.
        len - The length of the @p data byte array.
        Returns:
        A new mongocrypt_binary_t.

      • mongocrypt_binary_data

        public static com.sun.jna.Pointer mongocrypt_binary_data​(CAPI.mongocrypt_binary_t binary)
        Get a pointer to the referenced data.
        Parameters:
        binary - The @ref mongocrypt_binary_t.
        Returns:
        A pointer to the referenced data.

      • mongocrypt_binary_len

        public static int mongocrypt_binary_len​(CAPI.mongocrypt_binary_t binary)
        Get the length of the referenced data.
        Parameters:
        binary - The @ref mongocrypt_binary_t.
        Returns:
        The length of the referenced data.

      • mongocrypt_binary_destroy

        public static void mongocrypt_binary_destroy​(CAPI.mongocrypt_binary_t binary)
        Free the @ref mongocrypt_binary_t.

        This does not free the referenced data. Refer to individual function documentation to determine the lifetime guarantees of the underlying data.

        Parameters:
        binary - The mongocrypt_binary_t destroy.

      • mongocrypt_status_new

        public static CAPI.mongocrypt_status_t mongocrypt_status_new()
        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_status_set

        public static void mongocrypt_status_set​(CAPI.mongocrypt_status_t status,
                                         int type,
                                         int code,
                                         CAPI.cstring message,
                                         int message_len)
        Set a status object with message, type, and code.

        Use this to set the mongocrypt_status_t given in the crypto hooks.

        Parameters:
        status - The status.
        type - The status type.
        code - The status code.
        message - The message.
        message_len - The length of @p message. Pass -1 to determine the * string length with strlen (must * be NULL terminated).

      • mongocrypt_status_type

        public static int mongocrypt_status_type​(CAPI.mongocrypt_status_t status)
        Indicates success or the type of error.
        Parameters:
        status - The status object.
        Returns:
        A @ref mongocrypt_status_type_t.

      • mongocrypt_status_code

        public static int mongocrypt_status_code​(CAPI.mongocrypt_status_t status)
        Get an error code or 0.
        Parameters:
        status - The status object.
        Returns:
        An error code.

      • mongocrypt_status_message

        public static CAPI.cstring mongocrypt_status_message​(CAPI.mongocrypt_status_t status,
                                                     com.sun.jna.Pointer len)
        Get the error message associated with a status, or an empty string.
        Parameters:
        status - The status object.
        len - an optional length of the returned string. May be NULL.
        Returns:
        An error message or an empty string.

      • mongocrypt_status_ok

        public static boolean mongocrypt_status_ok​(CAPI.mongocrypt_status_t status)
        Returns true if the status indicates success.
        Parameters:
        status - The status to check.
        Returns:
        A boolean indicating success.

      • mongocrypt_status_destroy

        public static void mongocrypt_status_destroy​(CAPI.mongocrypt_status_t status)
        Free the memory for a status object.
        Parameters:
        status - The status to destroy.

      • mongocrypt_new

        public static CAPI.mongocrypt_t mongocrypt_new()
        Allocate a new @ref mongocrypt_t object.

        Initialize with @ref mongocrypt_init. When done, free with @ref mongocrypt_destroy.

        Returns:
        A new @ref mongocrypt_t object.

      • mongocrypt_setopt_log_handler

        public static boolean mongocrypt_setopt_log_handler​(CAPI.mongocrypt_t crypt,
                                                    CAPI.mongocrypt_log_fn_t log_fn,
                                                    com.sun.jna.Pointer log_ctx)
        Set a handler to get called on every log message.
        Parameters:
        crypt - The @ref mongocrypt_t object.
        log_fn - The log callback.
        log_ctx - A context passed as an argument to the log callback every invokation.
        Returns:
        A boolean indicating success.

      • mongocrypt_setopt_aes_256_ctr

        public static boolean mongocrypt_setopt_aes_256_ctr​(CAPI.mongocrypt_t crypt,
                                                    CAPI.mongocrypt_crypto_fn aes_256_ctr_encrypt,
                                                    CAPI.mongocrypt_crypto_fn aes_256_ctr_decrypt,
                                                    com.sun.jna.Pointer ctx)
        Set a crypto hook for the AES256-CTR operations.
        Parameters:
        crypt - The @ref mongocrypt_t object.
        aes_256_ctr_encrypt - The crypto callback function for encrypt operation.
        aes_256_ctr_decrypt - The crypto callback function for decrypt operation.
        ctx - A context passed as an argument to the crypto callback every invocation.
        Returns:
        A boolean indicating success. If false, an error status is set. Retrieve it with @ref mongocrypt_status

      • mongocrypt_setopt_crypto_hook_sign_rsaes_pkcs1_v1_5

        public static boolean mongocrypt_setopt_crypto_hook_sign_rsaes_pkcs1_v1_5​(CAPI.mongocrypt_t crypt,
                                                                          CAPI.mongocrypt_hmac_fn sign_rsaes_pkcs1_v1_5,
                                                                          com.sun.jna.Pointer sign_ctx)
        Set a crypto hook for the RSASSA-PKCS1-v1_5 algorithm with a SHA-256 hash.

        See: https://tools.ietf.org/html/rfc3447#section-8.2

        Note: this function has the wrong name. It should be: mongocrypt_setopt_crypto_hook_sign_rsassa_pkcs1_v1_5

        Parameters:
        crypt - The @ref mongocrypt_t object.
        sign_rsaes_pkcs1_v1_5 - The crypto callback function.
        sign_ctx - A context passed as an argument to the crypto callback every invocation.
        Returns:
        A boolean indicating success. If false, an error status is set. Retrieve it with @ref mongocrypt_status

      • mongocrypt_setopt_kms_provider_aws

        public static boolean mongocrypt_setopt_kms_provider_aws​(CAPI.mongocrypt_t crypt,
                                                         CAPI.cstring aws_access_key_id,
                                                         int aws_access_key_id_len,
                                                         CAPI.cstring aws_secret_access_key,
                                                         int aws_secret_access_key_len)
        Set a handler to get called on every log message.
        Parameters:
        crypt - The @ref mongocrypt_t object.
        aws_access_key_id - The AWS access key ID used to generate KMS messages.
        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).
        aws_secret_access_key - The AWS secret access key used to generate KMS messages.
        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).
        Returns:
        A boolean indicating success.

      • mongocrypt_setopt_kms_provider_local

        public static boolean mongocrypt_setopt_kms_provider_local​(CAPI.mongocrypt_t crypt,
                                                           CAPI.mongocrypt_binary_t key)
        Configure a local KMS provider on the @ref mongocrypt_t object.
        Parameters:
        crypt - The @ref mongocrypt_t object.
        key - A 64 byte master key used to encrypt and decrypt key vault keys.
        Returns:
        A boolean indicating success.

      • mongocrypt_setopt_kms_providers

        public static boolean mongocrypt_setopt_kms_providers​(CAPI.mongocrypt_t crypt,
                                                      CAPI.mongocrypt_binary_t kms_providers)
        Configure KMS providers with a BSON document.
        Parameters:
        crypt - The @ref mongocrypt_t object.
        kms_providers - A BSON document mapping the KMS provider names to credentials.
        Returns:
        A boolean indicating success. If false, an error status is set.
        Since:
        1.1

      • mongocrypt_setopt_schema_map

        public static boolean mongocrypt_setopt_schema_map​(CAPI.mongocrypt_t crypt,
                                                   CAPI.mongocrypt_binary_t schema_map)
        Set a local schema map for encryption.
        Parameters:
        crypt - The @ref mongocrypt_t object.
        schema_map - A BSON document representing the schema map supplied by the user. The keys are collection namespaces and values are JSON schemas.
        Returns:
        A boolean indicating success. If false, an error status is set. Retrieve it with @ref mongocrypt_status

      • mongocrypt_setopt_use_need_kms_credentials_state

        public static void mongocrypt_setopt_use_need_kms_credentials_state​(CAPI.mongocrypt_t crypt)
        Opt-into setting KMS providers before each KMS request. If set, before entering the MONGOCRYPT_CTX_NEED_KMS state, contexts will enter the MONGOCRYPT_CTX_NEED_KMS_CREDENTIALS state and then wait for credentials to be supplied through @ref mongocrypt_ctx_provide_kms_providers.
        Parameters:
        crypt - The @ref mongocrypt_t object to update

      • mongocrypt_setopt_encrypted_field_config_map

        public static boolean mongocrypt_setopt_encrypted_field_config_map​(CAPI.mongocrypt_t crypt,
                                                                   CAPI.mongocrypt_binary_t encryptedFieldConfigMap)
        Set a local EncryptedFieldConfigMap for encryption.
        Parameters:
        crypt - The @ref mongocrypt_t object.
        encryptedFieldConfigMap - 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.
        Returns:
        A boolean indicating success. If false, an error status is set. Retrieve it with @ref mongocrypt_status

      • mongocrypt_setopt_bypass_query_analysis

        public static void mongocrypt_setopt_bypass_query_analysis​(CAPI.mongocrypt_t crypt)
        Opt-into skipping query analysis.

        If opted in:

        • The crypt_shared shared library will not attempt to be loaded.
        • A mongocrypt_ctx_t will never enter the MONGOCRYPT_CTX_NEED_MARKINGS state.
        Parameters:
        crypt - The @ref mongocrypt_t object to update
        Since:
        1.5

      • mongocrypt_ctx_setopt_contention_factor

        public static boolean mongocrypt_ctx_setopt_contention_factor​(CAPI.mongocrypt_ctx_t ctx,
                                                              long contention_factor)
        Set the contention factor used for explicit encryption. The contention factor is only used for indexed Queryable Encryption.
        Parameters:
        ctx - The @ref mongocrypt_ctx_t object.
        contention_factor - the contention factor
        Returns:
        A boolean indicating success. If false, an error status is set. Retrieve it with @ref mongocrypt_ctx_status.
        Since:
        1.5

      • mongocrypt_ctx_setopt_index_key_id

        public static boolean mongocrypt_ctx_setopt_index_key_id​(CAPI.mongocrypt_ctx_t ctx,
                                                         CAPI.mongocrypt_binary_t key_id)
        Set the index key id to use for Queryable Encryption explicit encryption. If the index key id not set, the key id from @ref mongocrypt_ctx_setopt_key_id is used.
        Parameters:
        ctx - The @ref mongocrypt_ctx_t object.
        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 key_id 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
        Since:
        1.5

      • mongocrypt_setopt_append_crypt_shared_lib_search_path

        public static void mongocrypt_setopt_append_crypt_shared_lib_search_path​(CAPI.mongocrypt_t crypt,
                                                                         CAPI.cstring path)
        Append an additional search directory to the search path for loading the crypt_shared dynamic library.
        Parameters:
        crypt - The @ref mongocrypt_t object to update
        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.

        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.

        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.

        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.

        Since:
        1.5

      • mongocrypt_setopt_set_crypt_shared_lib_path_override

        public static void mongocrypt_setopt_set_crypt_shared_lib_path_override​(CAPI.mongocrypt_t crypt,
                                                                        CAPI.cstring path)
        Set a single override path for loading the crypt_shared dynamic library.
        Parameters:
        crypt - The @ref mongocrypt_t object to update
        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.

        This function will do no IO nor path validation. All validation will occur during the call to @ref mongocrypt_init.

        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.

        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.

        Since:
        1.5

      • mongocrypt_ctx_setopt_query_type

        public static boolean mongocrypt_ctx_setopt_query_type​(CAPI.mongocrypt_ctx_t ctx,
                                                       CAPI.cstring query_type,
                                                       int len)
        Set the query type to use for Queryable Encryption explicit encryption. The query type is only used for indexed Queryable Encryption.
        Parameters:
        ctx - The @ref mongocrypt_ctx_t object.
        query_type - the query type
        Returns:
        A boolean indicating success. If false, an error status is set. Retrieve it with @ref mongocrypt_ctx_status

      • mongocrypt_init

        public static boolean mongocrypt_init​(CAPI.mongocrypt_t crypt)
        Initialize new @ref mongocrypt_t object.
        Parameters:
        crypt - The @ref mongocrypt_t object.
        Returns:
        A boolean indicating success. Failure may occur if previously set options are invalid.

      • mongocrypt_status

        public static boolean mongocrypt_status​(CAPI.mongocrypt_t crypt,
                                        CAPI.mongocrypt_status_t status)
        Get the status associated with a @ref mongocrypt_t object.
        Parameters:
        crypt - The @ref mongocrypt_t object.
        status - Receives the status.
        Returns:
        A boolean indicating success.

      • mongocrypt_destroy

        public static void mongocrypt_destroy​(CAPI.mongocrypt_t crypt)
        Destroy the @ref mongocrypt_t object.
        Parameters:
        crypt - The @ref mongocrypt_t object to destroy.

      • mongocrypt_crypt_shared_lib_version_string

        public static CAPI.cstring mongocrypt_crypt_shared_lib_version_string​(CAPI.mongocrypt_t crypt,
                                                                      com.sun.jna.Pointer len)
        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.
        Parameters:
        crypt - The mongocrypt_t object after a successful call to mongocrypt_init.
        len - an optional length of the returned string. May be NULL.
        Returns:
        A nul-terminated string of the dynamically loaded crypt_shared library.
        Since:
        1.5

      • mongocrypt_ctx_provide_kms_providers

        public static boolean mongocrypt_ctx_provide_kms_providers​(CAPI.mongocrypt_ctx_t ctx,
                                                           CAPI.mongocrypt_binary_t kms_providers)
        Call in response to the MONGOCRYPT_CTX_NEED_KMS_CREDENTIALS state to set per-context KMS provider settings. These follow the same format as @ref mongocrypt_setopt_kms_providers. If no keys are present in the BSON input, the KMS provider settings configured for the @ref mongocrypt_t at initialization are used.
        Parameters:
        ctx - The @ref mongocrypt_ctx_t object.
        kms_providers - A BSON document mapping the KMS provider names to credentials.
        Returns:
        A boolean indicating success. If false, an error status is set. Retrieve it with @ref mongocrypt_ctx_status.

      • mongocrypt_ctx_setopt_key_id

        public static boolean mongocrypt_ctx_setopt_key_id​(CAPI.mongocrypt_ctx_t ctx,
                                                   CAPI.mongocrypt_binary_t key_id)
        Set the key id to use for explicit encryption.
        Parameters:
        ctx - The @ref mongocrypt_ctx_t object.
        key_id - The key_id to use.
        Returns:
        A boolean indicating success.

      • mongocrypt_ctx_setopt_key_alt_name

        public static boolean mongocrypt_ctx_setopt_key_alt_name​(CAPI.mongocrypt_ctx_t ctx,
                                                         CAPI.mongocrypt_binary_t key_alt_name)
        Set the keyAltName to use for explicit encryption. keyAltName should be a binary encoding a bson document with the following format: { "keyAltName" : >BSON UTF8 value< }

        It is an error to set both this and the key id.

        Parameters:
        ctx - The @ref mongocrypt_ctx_t object.
        key_alt_name - The name to use.
        Returns:
        A boolean indicating success. If false, an error status is set. Retrieve it with @ref mongocrypt_ctx_status

      • mongocrypt_ctx_setopt_key_material

        public static boolean mongocrypt_ctx_setopt_key_material​(CAPI.mongocrypt_ctx_t ctx,
                                                         CAPI.mongocrypt_binary_t key_material)
        Set the keyMaterial to use for encrypting data.

        Pass the binary encoding of a BSON document like the following: { "keyMaterial" : (BSON BINARY value) }

        Parameters:
        ctx - The @ref mongocrypt_ctx_t object.
        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.
        Returns:
        A boolean indicating success. If false, an error status is set. Retrieve it with @ref mongocrypt_ctx_status

      • mongocrypt_ctx_setopt_algorithm

        public static boolean mongocrypt_ctx_setopt_algorithm​(CAPI.mongocrypt_ctx_t ctx,
                                                      CAPI.cstring algorithm,
                                                      int len)
        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-Randomized"
        Parameters:
        ctx - The @ref mongocrypt_ctx_t object.
        algorithm - A string specifying the algorithm to use for encryption.
        len - The length of the algorithm string.
        Returns:
        A boolean indicating success.

      • mongocrypt_ctx_new

        public static CAPI.mongocrypt_ctx_t mongocrypt_ctx_new​(CAPI.mongocrypt_t crypt)
        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.

        Parameters:
        crypt - The @ref mongocrypt_t object.
        Returns:
        A new context.

      • mongocrypt_ctx_status

        public static boolean mongocrypt_ctx_status​(CAPI.mongocrypt_ctx_t ctx,
                                            CAPI.mongocrypt_status_t status)
        Get the status associated with a @ref mongocrypt_ctx_t object.
        Parameters:
        ctx - The @ref mongocrypt_ctx_t object.
        status - Receives the status.
        Returns:
        A boolean indicating success.

      • mongocrypt_ctx_setopt_masterkey_aws

        public static boolean mongocrypt_ctx_setopt_masterkey_aws​(CAPI.mongocrypt_ctx_t ctx,
                                                          CAPI.cstring region,
                                                          int region_len,
                                                          CAPI.cstring cmk,
                                                          int cmk_len)
        Identify the AWS KMS master key to use for creating a data key.
        Parameters:
        ctx - The @ref mongocrypt_ctx_t object.
        region - The AWS region.
        region_len - The string length of @p region. Pass -1 to determine the string length with strlen (must be NULL terminated).
        cmk - The Amazon Resource Name (ARN) of the customer master key (CMK).
        cmk_len - The string length of @p cmk_len. Pass -1 to determine the string length with strlen (must be NULL terminated).
        Returns:
        A boolean indicating success.

      • mongocrypt_ctx_setopt_masterkey_aws_endpoint

        public static boolean mongocrypt_ctx_setopt_masterkey_aws_endpoint​(CAPI.mongocrypt_ctx_t ctx,
                                                                   CAPI.cstring endpoint,
                                                                   int endpoint_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 mongocrypt_kms_ctx_endpoint.
        Parameters:
        ctx - The @ref mongocrypt_ctx_t object.
        endpoint - The endpoint.
        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_ctx_setopt_masterkey_local

        public static boolean mongocrypt_ctx_setopt_masterkey_local​(CAPI.mongocrypt_ctx_t ctx)
        Set the master key to "local" for creating a data key.
        Parameters:
        ctx - The @ref mongocrypt_ctx_t object.
        Returns:
        A boolean indicating success.

      • mongocrypt_ctx_setopt_key_encryption_key

        public static boolean mongocrypt_ctx_setopt_key_encryption_key​(CAPI.mongocrypt_ctx_t ctx,
                                                               CAPI.mongocrypt_binary_t keyDocument)
        Set key encryption key document for creating a data key.
        Parameters:
        ctx - The @ref mongocrypt_ctx_t object.
        keyDocument - BSON representing the key encryption key document.
        Returns:
        A boolean indicating success. If false, and error status is set.
        Since:
        1.1

      • mongocrypt_ctx_datakey_init

        public static boolean mongocrypt_ctx_datakey_init​(CAPI.mongocrypt_ctx_t ctx)
        Initialize a context to create a data key. Set options before using @ref mongocrypt_ctx_setopt_masterkey_aws and mongocrypt_ctx_setopt_masterkey_local.
        Parameters:
        ctx - The @ref mongocrypt_ctx_t object.
        Returns:
        A boolean indicating success. Assumes a master key option has been set, and an associated KMS provider has been set on the parent @ref mongocrypt_t.

      • mongocrypt_ctx_encrypt_init

        public static boolean mongocrypt_ctx_encrypt_init​(CAPI.mongocrypt_ctx_t ctx,
                                                  CAPI.cstring db,
                                                  int db_len,
                                                  CAPI.mongocrypt_binary_t cmd)
        Initialize a context for encryption. Associated options: - @ref mongocrypt_ctx_setopt_cache_noblock - @ref mongocrypt_ctx_setopt_schema
        Parameters:
        ctx - The @ref mongocrypt_ctx_t object.
        db - The database name.
        db_len - The byte length of @p db. Pass -1 to determine the string length with strlen (must be NULL terminated).
        cmd - The BSON command to be encrypted.
        Returns:
        A boolean indicating success. If false, an error status is set. Retrieve it with @ref mongocrypt_ctx_status

      • mongocrypt_ctx_explicit_encrypt_init

        public static boolean mongocrypt_ctx_explicit_encrypt_init​(CAPI.mongocrypt_ctx_t ctx,
                                                           CAPI.mongocrypt_binary_t msg)
        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 }
        Parameters:
        ctx - A @ref mongocrypt_ctx_t.
        msg - A @ref mongocrypt_binary_t the plaintext BSON value.
        Returns:
        A boolean indicating success.

      • mongocrypt_ctx_decrypt_init

        public static boolean mongocrypt_ctx_decrypt_init​(CAPI.mongocrypt_ctx_t ctx,
                                                  CAPI.mongocrypt_binary_t doc)
        Initialize a context for decryption.
        Parameters:
        ctx - The mongocrypt_ctx_t object.
        doc - The document to be decrypted.
        Returns:
        A boolean indicating success.

      • mongocrypt_ctx_explicit_decrypt_init

        public static boolean mongocrypt_ctx_explicit_decrypt_init​(CAPI.mongocrypt_ctx_t ctx,
                                                           CAPI.mongocrypt_binary_t msg)
        Explicit helper method to decrypt a single BSON object.
        Parameters:
        ctx - A @ref mongocrypt_ctx_t.
        msg - A @ref mongocrypt_binary_t the encrypted BSON.
        Returns:
        A boolean indicating success.

      • mongocrypt_ctx_state

        public static int mongocrypt_ctx_state​(CAPI.mongocrypt_ctx_t ctx)
        Get the current state of a context.
        Parameters:
        ctx - The @ref mongocrypt_ctx_t object.
        Returns:
        A @ref mongocrypt_ctx_state_t.

      • mongocrypt_ctx_mongo_op

        public static boolean mongocrypt_ctx_mongo_op​(CAPI.mongocrypt_ctx_t ctx,
                                              CAPI.mongocrypt_binary_t op_bson)
        Get BSON necessary to run the mongo operation when mongocrypt_ctx_t is in MONGOCRYPT_CTX_NEED_MONGO_* states.

        op_bson is a BSON document to be used for the operation. - For MONGOCRYPT_CTX_NEED_MONGO_COLLINFO it is a listCollections filter. - For MONGOCRYPT_CTX_NEED_MONGO_KEYS it is a find filter. - For MONGOCRYPT_CTX_NEED_MONGO_MARKINGS it is a JSON schema to append.

        Parameters:
        ctx - The @ref mongocrypt_ctx_t object.
        op_bson - A BSON document for the MongoDB operation.
        Returns:
        A boolean indicating success.

      • mongocrypt_ctx_mongo_feed

        public static boolean mongocrypt_ctx_mongo_feed​(CAPI.mongocrypt_ctx_t ctx,
                                                CAPI.mongocrypt_binary_t reply)
        Feed a BSON reply or result when when mongocrypt_ctx_t is in MONGOCRYPT_CTX_NEED_MONGO_* states. This may be called multiple times depending on the operation.

        op_bson is a BSON document to be used for the operation. - For MONGOCRYPT_CTX_NEED_MONGO_COLLINFO it is a doc from a listCollections cursor. - For MONGOCRYPT_CTX_NEED_MONGO_KEYS it is a doc from a find cursor. - For MONGOCRYPT_CTX_NEED_MONGO_MARKINGS it is a reply from mongocryptd.

        Parameters:
        ctx - The @ref mongocrypt_ctx_t object.
        reply - A BSON document for the MongoDB operation.
        Returns:
        A boolean indicating success.

      • mongocrypt_ctx_mongo_done

        public static boolean mongocrypt_ctx_mongo_done​(CAPI.mongocrypt_ctx_t ctx)
        Call when done feeding the reply (or replies) back to the context.
        Parameters:
        ctx - The @ref mongocrypt_ctx_t object.
        Returns:
        A boolean indicating success.

      • mongocrypt_ctx_next_kms_ctx

        public static CAPI.mongocrypt_kms_ctx_t mongocrypt_ctx_next_kms_ctx​(CAPI.mongocrypt_ctx_t ctx)
        Get the next KMS handle.

        Multiple KMS handles may be retrieved at once. Drivers may do this to fan out multiple concurrent KMS HTTP requests. Feeding multiple KMS requests is thread-safe.

        Is KMS handles are being handled synchronously, the driver can reuse the same TLS socket to send HTTP requests and receive responses.

        Parameters:
        ctx - A @ref mongocrypt_ctx_t.
        Returns:
        a new @ref mongocrypt_kms_ctx_t or NULL.

      • mongocrypt_kms_ctx_get_kms_provider

        public static CAPI.cstring mongocrypt_kms_ctx_get_kms_provider​(CAPI.mongocrypt_kms_ctx_t kms,
                                                               com.sun.jna.Pointer len)
        Get the KMS provider identifier associated with this KMS request. This is used to conditionally configure TLS connections based on the KMS request. It is useful for KMIP, which authenticates with a client certificate.
        Parameters:
        kms - The mongocrypt_kms_ctx_t object.
        len - Receives the length of the returned string.
        Returns:
        The name of the KMS provider

      • mongocrypt_kms_ctx_message

        public static boolean mongocrypt_kms_ctx_message​(CAPI.mongocrypt_kms_ctx_t kms,
                                                 CAPI.mongocrypt_binary_t msg)
        Get the HTTP request message for a KMS handle.
        Parameters:
        kms - A @ref mongocrypt_kms_ctx_t.
        msg - The HTTP request to send to KMS.
        Returns:
        A boolean indicating success.

      • mongocrypt_kms_ctx_endpoint

        public static boolean mongocrypt_kms_ctx_endpoint​(CAPI.mongocrypt_kms_ctx_t kms,
                                                  com.sun.jna.ptr.PointerByReference endpoint)
        Get the hostname from which to connect over TLS.

        The storage for @p endpoint is not owned by the caller, but is valid until calling @ref mongocrypt_ctx_kms_done on the parent @ref mongocrypt_ctx_t.

        Parameters:
        kms - A @ref mongocrypt_kms_ctx_t.
        endpoint - The output hostname.
        Returns:
        A boolean indicating success.

      • mongocrypt_kms_ctx_bytes_needed

        public static int mongocrypt_kms_ctx_bytes_needed​(CAPI.mongocrypt_kms_ctx_t kms)
        Indicates how many bytes to feed into @ref mongocrypt_kms_ctx_feed.
        Parameters:
        kms - The @ref mongocrypt_kms_ctx_t.
        Returns:
        The number of requested bytes.

      • mongocrypt_kms_ctx_feed

        public static boolean mongocrypt_kms_ctx_feed​(CAPI.mongocrypt_kms_ctx_t kms,
                                              CAPI.mongocrypt_binary_t bytes)
        Feed bytes from the HTTP response.

        Feeding more bytes than what has been returned in @ref mongocrypt_kms_ctx_bytes_needed is an error.

        Parameters:
        kms - The @ref mongocrypt_kms_ctx_t.
        bytes - The bytes to feed.
        Returns:
        A boolean indicating success.

      • mongocrypt_kms_ctx_status

        public static boolean mongocrypt_kms_ctx_status​(CAPI.mongocrypt_kms_ctx_t kms,
                                                CAPI.mongocrypt_status_t status)
        Get the status associated with a @ref mongocrypt_kms_ctx_t object.
        Parameters:
        kms - The @ref mongocrypt_kms_ctx_t object.
        status - Receives the status.
        Returns:
        A boolean indicating success.

      • mongocrypt_ctx_kms_done

        public static boolean mongocrypt_ctx_kms_done​(CAPI.mongocrypt_ctx_t ctx)
        Call when done handling all KMS contexts.
        Parameters:
        ctx - The @ref mongocrypt_ctx_t object.
        Returns:
        A boolean indicating success.

      • mongocrypt_ctx_finalize

        public static boolean mongocrypt_ctx_finalize​(CAPI.mongocrypt_ctx_t ctx,
                                              CAPI.mongocrypt_binary_t out)
        Perform the final encryption or decryption.
        Parameters:
        ctx - A @ref mongocrypt_ctx_t.
        out - The final BSON to send to the server.
        Returns:
        a boolean indicating success.

      • mongocrypt_ctx_destroy

        public static void mongocrypt_ctx_destroy​(CAPI.mongocrypt_ctx_t ctx)
        Destroy and free all memory associated with a @ref mongocrypt_ctx_t.
        Parameters:
        ctx - A @ref mongocrypt_ctx_t.