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

    • 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_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_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_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_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_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_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_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_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.