Class: Mongo::Crypt::Binding Private

Do not use. This class is for internal use only.

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Class Chain: self, FFI::Library
Inherits:	Object
Defined in:	lib/mongo/crypt/binding.rb

Overview

A Ruby binding for the libmongocrypt C library

Constant Summary

MIN_LIBMONGOCRYPT_VERSION =

Minimum version of libmongocrypt required by this version of the driver. An attempt to use the driver with any previous version of libmongocrypt will cause a LoadError.

# File 'lib/mongo/crypt/binding.rb', line 86
```
Gem::Version.new("1.12.0")
```

Class Method Summary

.check_ctx_status(context) ⇒ nil Internal use only

Raise a Mongo::Error::CryptError based on the status of the underlying mongocrypt_ctx_t object.
.check_kms_ctx_status(kms_context) Internal use only

If the provided block returns false, raise a CryptError with the status information from the provided KmsContext object.
.check_status(handle) ⇒ nil Internal use only

Raise a Mongo::Error::CryptError based on the status of the underlying mongocrypt_t object.
.crypt_shared_lib_version(handle) ⇒ Integer Internal use only

Obtain a 64-bit constant encoding the version of the loaded crypt_shared library, if available.
.ctx_datakey_init(context) Internal use only

Initialize the Context to create a data key.
.ctx_decrypt_init(context, command) Internal use only

Initialize the Context for auto-decryption.
.ctx_encrypt_init(context, db_name, command) Internal use only

Initialize the Context for auto-encryption.
.ctx_explicit_decrypt_init(context, doc) Internal use only

Initialize the Context for explicit decryption.
.ctx_explicit_encrypt_expression_init(context, doc) Internal use only

Initialize the Context for explicit expression encryption.
.ctx_explicit_encrypt_init(context, doc) Internal use only

Initialize the Context for explicit encryption.
.ctx_finalize(context) Internal use only

Finalize the state machine represented by the Context.
.ctx_kms_done(context) Internal use only

Indicate to libmongocrypt that it will receive no more KMS replies.
.ctx_mongo_feed(context, doc) Internal use only

Feed a response from the driver back to libmongocrypt.
.ctx_mongo_op(context) ⇒ BSON::Document Internal use only

Returns a BSON::Document representing an operation that the driver must perform on behalf of libmongocrypt to get the information it needs in order to continue with encryption/decryption (for example, a filter for a key vault query).
.ctx_next_kms_ctx(context) ⇒ Mongo::Crypt::KmsContext | nil Internal use only

Return a new KmsContext object needed by a Context object.
.ctx_provide_kms_providers(context, kms_providers) Internal use only

Call in response to the MONGOCRYPT_CTX_NEED_KMS_CREDENTIALS state to set per-context KMS provider settings.
.ctx_rewrap_many_datakey_init(context, filter) ⇒ Boolean Internal use only

Initialize a context to rewrap datakeys.
.ctx_setopt_algorithm(context, name) Internal use only

Set the algorithm on the context.
.ctx_setopt_algorithm_range(context, opts) Internal use only

Set options for explicit encryption with the “range” algorithm.
.ctx_setopt_contention_factor(context, factor) Internal use only

Set the contention factor used for explicit encryption.
.ctx_setopt_key_alt_names(context, key_alt_names) Internal use only

Set multiple alternate key names on data key creation.
.ctx_setopt_key_encryption_key(context, key_document) Internal use only

Set key encryption key document for creating a data key.
.ctx_setopt_key_id(context, key_id) Internal use only

Sets the key id option on an explicit encryption context.
.ctx_setopt_key_material(context, key_material) Internal use only

Set set a custom key material to use for.
.ctx_setopt_query_type(context, query_type) Internal use only

Set the query type to use for FLE 2 explicit encryption.
.get_binary_data_direct(mongocrypt_binary_t) Internal use only
.get_binary_len_direct(mongocrypt_binary_t) Internal use only
.init(handle) Internal use only

Initialize the Mongo::Crypt::Handle object.
.kms_ctx_bytes_needed(kms_context) ⇒ Integer Internal use only

Get the number of bytes needed by the KmsContext.
.kms_ctx_endpoint(kms_context) ⇒ String | nil Internal use only

Get the hostname with which to connect over TLS to get information about the AWS master key.
.kms_ctx_fail(kms_context) ⇒ true, false Internal use only

Check whether the last failed request for the KMS context may be retried.
.kms_ctx_feed(kms_context, bytes) Internal use only

Feed replies from the KMS back to libmongocrypt.
.kms_ctx_get_kms_provider(kms_context) Internal use only

Get the KMS provider identifier associated with this KMS request.
.kms_ctx_message(kms_context) ⇒ String Internal use only

Get the HTTP message needed to fetch the AWS KMS master key from a KmsContext object.
.kms_ctx_setopt_retry_kms(handle, value) ⇒ true, fale Internal use only

Enable or disable KMS retry behavior.
.kms_ctx_usleep(kms_context) ⇒ Integer Internal use only

Returns number of milliseconds to sleep before sending KMS request for the given KMS context.
.mongocrypt_binary_data(binary) ⇒ FFI::Pointer Internal use only

Get the pointer to the underlying data for the mongocrypt_binary_t.
.mongocrypt_binary_destroy(binary) ⇒ nil Internal use only

Destroy the mongocrypt_binary_t object.
.mongocrypt_binary_len(binary) ⇒ Integer Internal use only

Get the length of the underlying data array.
.mongocrypt_binary_new ⇒ FFI::Pointer Internal use only

Creates a new mongocrypt_binary_t object (a non-owning view of a byte.
.mongocrypt_binary_new_from_data(data, len) ⇒ FFI::Pointer Internal use only

Create a new mongocrypt_binary_t object that maintains a pointer to.
.mongocrypt_crypt_shared_lib_version(crypt) Internal use only
.mongocrypt_ctx_datakey_init(ctx, filter) Internal use only
.mongocrypt_ctx_decrypt_init(ctx, doc) ⇒ Boolean Internal use only

Initializes the ctx for auto-decryption.
.mongocrypt_ctx_destroy(ctx) ⇒ nil Internal use only

Destroy the reference to the mongocrypt_ctx_t object.
.mongocrypt_ctx_encrypt_init(ctx, db, db_len, cmd) ⇒ Boolean Internal use only

Initializes the ctx for auto-encryption.
.mongocrypt_ctx_explicit_decrypt_init(ctx, msg) ⇒ Boolean Internal use only

Initializes the ctx for explicit decryption.
.mongocrypt_ctx_explicit_encrypt_init(ctx, msg) ⇒ Boolean Internal use only

Initializes the ctx for explicit expression encryption.
.mongocrypt_ctx_finalize(ctx, op_bson) ⇒ Boolean Internal use only

Perform the final encryption or decryption and return a BSON document.
.mongocrypt_ctx_mongo_done(ctx) ⇒ Boolean Internal use only

Indicate to libmongocrypt that the driver is done feeding replies.
.mongocrypt_ctx_mongo_feed(ctx, reply) ⇒ Boolean Internal use only

Feed a BSON reply to libmongocrypt.
.mongocrypt_ctx_mongo_next_kms_ctx(ctx) ⇒ FFI::Pointer Internal use only

Return a pointer to a mongocrypt_kms_ctx_t object or NULL.
.mongocrypt_ctx_mongo_op(ctx, op_bson) ⇒ Boolean Internal use only

Get a BSON operation for the driver to run against the MongoDB.
.mongocrypt_ctx_new(crypt) ⇒ FFI::Pointer Internal use only

Create a new mongocrypt_ctx_t object (a wrapper for the libmongocrypt.
.mongocrypt_ctx_provide_kms_providers(ctx, kms_providers) Internal use only
.mongocrypt_ctx_setopt_algorithm(ctx, algorithm, len) ⇒ Boolean Internal use only

Set the algorithm used for explicit encryption.
.mongocrypt_ctx_setopt_algorithm_range(ctx, opts) Internal use only
.mongocrypt_ctx_setopt_contention_factor(ctx, contention_factor) Internal use only
.mongocrypt_ctx_setopt_key_alt_name(ctx, binary) ⇒ Boolean Internal use only

When creating a data key, set an alternate name on that key.
.mongocrypt_ctx_setopt_key_encryption_key(ctx) ⇒ Boolean Internal use only

Set key encryption key document for creating a data key.
.mongocrypt_ctx_setopt_key_id(ctx, key_id) ⇒ Boolean Internal use only

Set the key id used for explicit encryption.
.mongocrypt_ctx_setopt_key_material(ctx, binary) ⇒ Boolean Internal use only

When creating a data key, set a custom key material to use for.
.mongocrypt_ctx_setopt_query_type(ctx, mongocrypt_query_type) Internal use only
.mongocrypt_ctx_state(ctx) ⇒ Symbol Internal use only

Get the current state of the ctx.
.mongocrypt_ctx_status(ctx, status) ⇒ Boolean Internal use only

Set the status information from the mongocrypt_ctx_t object on the.
.mongocrypt_destroy(crypt) ⇒ nil Internal use only

Destroy the reference the mongocrypt_t object.
.mongocrypt_init(crypt) ⇒ Boolean Internal use only

Initialize the mongocrypt_t object.
.mongocrypt_kms_ctx_bytes_needed(kms) ⇒ Integer Internal use only

Get the number of bytes needed by the KMS context.
.mongocrypt_kms_ctx_done(ctx) ⇒ Boolean Internal use only

Indicate to libmongocrypt that it will receive no more replies from.
.mongocrypt_kms_ctx_endpoint(kms, endpoint) ⇒ Boolean Internal use only

Get the hostname with which to connect over TLS to get information about.
.mongocrypt_kms_ctx_fail(ctx) Internal use only
.mongocrypt_kms_ctx_feed(kms, bytes) ⇒ Boolean Internal use only

Feed replies from the KMS back to libmongocrypt.
.mongocrypt_kms_ctx_get_kms_provider(crypt, kms_providers) Internal use only
.mongocrypt_kms_ctx_message(kms, msg) ⇒ Boolean Internal use only

Get the message needed to fetch the AWS KMS master key.
.mongocrypt_kms_ctx_status(kms, status) ⇒ Boolean Internal use only

Write status information about the mongocrypt_kms_ctx_t object.
.mongocrypt_kms_ctx_usleep(ctx) ⇒ int64 Internal use only

Indicates how long to sleep before sending KMS request.
.mongocrypt_setopt_aes_256_ctr(crypt, aes_256_ctr_encrypt, aes_256_ctr_decrypt, ctx) ⇒ Boolean Internal use only

Set a crypto hook for the AES256-CTR operations.
.mongocrypt_setopt_append_crypt_shared_lib_search_path(crypt, path) Internal use only
.mongocrypt_setopt_bypass_query_analysis(crypt) Internal use only
.mongocrypt_setopt_crypto_hook_sign_rsaes_pkcs1_v1_5(crypt, sign_rsaes_pkcs1_v1_5, ctx = nil) ⇒ Boolean Internal use only

Set a crypto hook for the RSASSA-PKCS1-v1_5 algorithm with a SHA-256 hash.
.mongocrypt_setopt_crypto_hooks(crypt, aes_enc_fn, aes_dec_fn, random_fn, sha_512_fn, sha_256_fn, hash_fn, ctx = nil) ⇒ Boolean Internal use only

Set crypto hooks on the provided mongocrypt object.
.mongocrypt_setopt_encrypted_field_config_map(crypt, efc_map) Internal use only
.mongocrypt_setopt_kms_providers(crypt, kms_providers) Internal use only

Configure KMS providers with a BSON document.
.mongocrypt_setopt_log_handler(crypt, log_fn, log_ctx = nil) ⇒ Boolean Internal use only

Set the handler on the mongocrypt_t object to be called every time.
.mongocrypt_setopt_retry_kms(crypt, enable) Internal use only
.mongocrypt_setopt_schema_map(crypt, schema_map) ⇒ Boolean Internal use only

Sets a local schema map for encryption.
.mongocrypt_setopt_set_crypt_shared_lib_path_override(crypt, path) Internal use only
.mongocrypt_setopt_use_need_kms_credentials_state(crypt) Internal use only
.mongocrypt_status(crypt, status) ⇒ Boolean Internal use only

Set the status information from the mongocrypt_t object on the.
.mongocrypt_status_code(status) ⇒ Integer Internal use only

Return the status error code.
.mongocrypt_status_destroy(status) ⇒ nil Internal use only

Destroys the reference to the mongocrypt_status_t object.
.mongocrypt_status_message(status, len = nil) ⇒ String Internal use only

Returns the status message.
.mongocrypt_status_new ⇒ FFI::Pointer Internal use only

Create a new mongocrypt_status_t object.
.mongocrypt_status_ok(status) ⇒ Boolean Internal use only

Returns whether the status is ok or an error.
.mongocrypt_status_set(status, type, code, message, len) ⇒ nil Internal use only

Set a message, type, and code on an existing status.
.mongocrypt_status_type(status) ⇒ Symbol Internal use only

Indicates the status type.
.mongocrypt_version(len) ⇒ String Internal use only

Returns the version string of the libmongocrypt library.
.ongocrypt_new ⇒ FFI::Pointer Internal use only

Creates a new mongocrypt_t object.
.parse_version(version) ⇒ Gem::Version Internal use only

Given a string representing a version number, parses it into a Gem::Version object.
.setopt_aes_256_ctr(handle, aes_ctr_encrypt_cb, aes_ctr_decrypt_cb) Internal use only

Set a crypto hook for the AES256-CTR operations.
.setopt_append_crypt_shared_lib_search_path(handle, path) Internal use only

Append an additional search directory to the search path for loading.
.setopt_bypass_query_analysis(handle) Internal use only

Opt-into skipping query analysis.
.setopt_crypto_hook_sign_rsaes_pkcs1_v1_5(handle, rsaes_pkcs_signature_cb) Internal use only

Set a crypto hook for the RSASSA-PKCS1-v1_5 algorithm with.
.setopt_crypto_hooks(handle, aes_encrypt_cb, aes_decrypt_cb, random_cb, hmac_sha_512_cb, hmac_sha_256_cb, hmac_hash_cb) Internal use only

Set crypto callbacks on the Handle.
.setopt_encrypted_field_config_map(handle, efc_map) Internal use only

Set a local EncryptedFieldConfigMap for encryption.
.setopt_kms_providers(handle, kms_providers) Internal use only

Set KMS providers options on the Mongo::Crypt::Handle object.
.setopt_log_handler(handle, log_callback) Internal use only

Set the logger callback function on the Mongo::Crypt::Handle object.
.setopt_schema_map(handle, schema_map_doc) Internal use only

Set schema map on the Mongo::Crypt::Handle object.
.setopt_set_crypt_shared_lib_path_override(handle, path) Internal use only

Set a single override path for loading the crypt shared library.
.setopt_use_need_kms_credentials_state(handle) Internal use only

Opt-into handling the MONGOCRYPT_CTX_NEED_KMS_CREDENTIALS state.
.validate_document(data) Internal use only

Checks that the specified data is a Hash before serializing it to BSON to prevent errors from libmongocrypt.
.validate_version(lmc_version) Internal use only

Validates if provided version of libmongocrypt is valid, i.e. equal or greater than minimum required version.

Instance Method Summary

#mongocrypt_crypto_fn(ctx, key, iv, input, output, status) ⇒ Bool Internal use only

A callback to a function that performs AES encryption or decryption.
#mongocrypt_hash_fn(ctx, input, output, status) ⇒ Bool Internal use only

A callback to a SHA-256 hash function.
#mongocrypt_hmac_fn(ctx, key, input, output, status) ⇒ Bool Internal use only

A callback to a function that performs HMAC SHA-512 or SHA-256.
#mongocrypt_log_fn_t(level, message, len, ctx) ⇒ nil Internal use only

A callback to the mongocrypt log function.
#mongocrypt_random_fn(ctx, output, count, status) ⇒ Bool Internal use only

A callback to a crypto secure random function.

Class Method Details

.check_ctx_status(context) ⇒ `nil`

Raise a Mongo::Error::CryptError based on the status of the underlying mongocrypt_ctx_t object.

Returns:

(nil) —

Always nil.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1821


def self.check_ctx_status(context)
  if block_given?
    do_raise = !yield
  else
    do_raise = true
  end

  if do_raise
    status = Status.new

    mongocrypt_ctx_status(context.ctx_p, status.ref)
    status.raise_crypt_error
  end
end

.check_kms_ctx_status(kms_context)

If the provided block returns false, raise a CryptError with the status information from the provided KmsContext object.

Parameters:

kms_context (Mongo::Crypt::KmsContext)

Raises:

(Mongo::Error::CryptError) —

If the provided block returns false

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1107


def self.check_kms_ctx_status(kms_context)
  unless yield
    status = Status.new

    mongocrypt_kms_ctx_status(kms_context.kms_ctx_p, status.ref)
    status.raise_crypt_error(kms: true)
  end
end

.check_status(handle) ⇒ `nil`

Raise a Mongo::Error::CryptError based on the status of the underlying mongocrypt_t object.

Returns:

(nil) —

Always nil.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1808


def self.check_status(handle)
  unless yield
    status = Status.new

    mongocrypt_status(handle.ref, status.ref)
    status.raise_crypt_error
  end
end

.crypt_shared_lib_version(handle) ⇒ `Integer`

Obtain a 64-bit constant encoding the version of the loaded crypt_shared library, if available.

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

Parameters:

handle (Mongo::Crypt::Handle)

Returns:

(Integer) —

A 64-bit encoded version number, with the version encoded as four sixteen-bit integers, or zero if no crypt_shared library was loaded.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1614


def self.crypt_shared_lib_version(handle)
  mongocrypt_crypt_shared_lib_version(handle.ref)
end

.ctx_datakey_init(context)

Initialize the Context to create a data key

Parameters:

context (Mongo::Crypt::Context)

Raises:

(Mongo::Error::CryptError) —

If initialization fails

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 625


def self.ctx_datakey_init(context)
  check_ctx_status(context) do
    mongocrypt_ctx_datakey_init(context.ctx_p)
  end
end

.ctx_decrypt_init(context, command)

Initialize the Context for auto-decryption

Parameters:

context (Mongo::Crypt::Context)
command (BSON::Document) —

A BSON document to decrypt

Raises:

(Mongo::Error::CryptError) —

If initialization fails

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 786


def self.ctx_decrypt_init(context, command)
  validate_document(command)
  data = command.to_bson.to_s
  Binary.wrap_string(data) do |data_p|
    check_ctx_status(context) do
      mongocrypt_ctx_decrypt_init(context.ctx_p, data_p)
    end
  end
end

.ctx_encrypt_init(context, db_name, command)

Initialize the Context for auto-encryption

Parameters:

context (Mongo::Crypt::Context)
db_name (String) —

The name of the database against which the encrypted command is being performed
command (Hash) —

The command to be encrypted

Raises:

(Mongo::Error::CryptError) —

If initialization fails

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 692


def self.ctx_encrypt_init(context, db_name, command)
  validate_document(command)
  data = command.to_bson.to_s
  Binary.wrap_string(data) do |data_p|
    check_ctx_status(context) do
      mongocrypt_ctx_encrypt_init(context.ctx_p, db_name, -1, data_p)
    end
  end
end

.ctx_explicit_decrypt_init(context, doc)

Initialize the Context for explicit decryption

Parameters:

context (Mongo::Crypt::Context)
doc (Hash) —

A BSON document to decrypt

Raises:

(Mongo::Error::CryptError) —

If initialization fails

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 816


def self.ctx_explicit_decrypt_init(context, doc)
  validate_document(doc)
  data = doc.to_bson.to_s
  Binary.wrap_string(data) do |data_p|
    check_ctx_status(context) do
      mongocrypt_ctx_explicit_decrypt_init(context.ctx_p, data_p)
    end
  end
end

.ctx_explicit_encrypt_expression_init(context, doc)

Initialize the Context for explicit expression encryption.

Parameters:

context (Mongo::Crypt::Context)
doc (Hash) —

A BSON document to encrypt

Raises:

(Mongo::Error::CryptError) —

If initialization fails

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 760


def self.ctx_explicit_encrypt_expression_init(context, doc)
  validate_document(doc)
  data = doc.to_bson.to_s
  Binary.wrap_string(data) do |data_p|
    check_ctx_status(context) do
      mongocrypt_ctx_explicit_encrypt_expression_init(context.ctx_p, data_p)
    end
  end
end

.ctx_explicit_encrypt_init(context, doc)

Initialize the Context for explicit encryption

Parameters:

context (Mongo::Crypt::Context)
doc (Hash) —

A BSON document to encrypt

Raises:

(Mongo::Error::CryptError) —

If initialization fails

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 726


def self.ctx_explicit_encrypt_init(context, doc)
  validate_document(doc)
  data = doc.to_bson.to_s
  Binary.wrap_string(data) do |data_p|
    check_ctx_status(context) do
      mongocrypt_ctx_explicit_encrypt_init(context.ctx_p, data_p)
    end
  end
end

.ctx_finalize(context)

Finalize the state machine represented by the Context

Parameters:

context (Mongo::Crypt::Context)

Raises:

(Mongo::Error::CryptError) —

If the state machine is not successfully finalized

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1209


def self.ctx_finalize(context)
  binary = Binary.new

  check_ctx_status(context) do
    mongocrypt_ctx_finalize(context.ctx_p, binary.ref)
  end

  # TODO since the binary references a C pointer, and ByteBuffer is
  # written in C in MRI, we could omit a copy of the data by making
  # ByteBuffer reference the string that is owned by libmongocrypt.
  BSON::Document.from_bson(BSON::ByteBuffer.new(binary.to_s), mode: :bson)
end

.ctx_kms_done(context)

Indicate to libmongocrypt that it will receive no more KMS replies.

Parameters:

context (Mongo::Crypt::Context)

Raises:

(Mongo::Error::CryptError) —

If the operation is unsuccessful

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1186


def self.ctx_kms_done(context)
  check_ctx_status(context) do
    mongocrypt_ctx_kms_done(context.ctx_p)
  end
end

.ctx_mongo_feed(context, doc)

Feed a response from the driver back to libmongocrypt

Parameters:

context (Mongo::Crypt::Context)
doc (BSON::Document) —

The document representing the response

Raises:

(Mongo::Error::CryptError) —

If the response is not fed successfully

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 897


def self.ctx_mongo_feed(context, doc)
  validate_document(doc)
  data = doc.to_bson.to_s
  Binary.wrap_string(data) do |data_p|
    check_ctx_status(context) do
      mongocrypt_ctx_mongo_feed(context.ctx_p, data_p)
    end
  end
end

.ctx_mongo_op(context) ⇒ `BSON::Document`

Returns a BSON::Document representing an operation that the driver must perform on behalf of libmongocrypt to get the information it needs in order to continue with encryption/decryption (for example, a filter for a key vault query).

Parameters:

context (Mongo::Crypt::Context)

Returns:

(BSON::Document) —

The operation that the driver must perform

Raises:

(Mongo::Crypt) —

If there is an error getting the operation

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 868


def self.ctx_mongo_op(context)
  binary = Binary.new

  check_ctx_status(context) do
    mongocrypt_ctx_mongo_op(context.ctx_p, binary.ref)
  end

  # TODO since the binary references a C pointer, and ByteBuffer is
  # written in C in MRI, we could omit a copy of the data by making
  # ByteBuffer reference the string that is owned by libmongocrypt.
  BSON::Document.from_bson(BSON::ByteBuffer.new(binary.to_s), mode: :bson)
end

.ctx_next_kms_ctx(context) ⇒ Mongo::Crypt::KmsContext | `nil`

Return a new KmsContext object needed by a Context object.

Parameters:

context (Mongo::Crypt::Context)

Returns:

(Mongo::Crypt::KmsContext | nil) —

The KmsContext needed to fetch an AWS master key or nil, if no KmsContext is needed

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 929


def self.ctx_next_kms_ctx(context)
  kms_ctx_p = mongocrypt_ctx_next_kms_ctx(context.ctx_p)

  if kms_ctx_p.null?
    nil
  else
    KmsContext.new(kms_ctx_p)
  end
end

.ctx_provide_kms_providers(context, 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 ‘mongocrypt_setopt_kms_providers“. If no keys are present in the BSON input, the KMS provider settings configured for the mongocrypt_t at initialization are used.

Parameters:

context (Mongo::Crypt::Context) —

Encryption context.
kms_providers (BSON::Document) —

BSON document mapping the KMS provider names to credentials.

Raises:

(Mongo::Error::CryptError) —

If the option is not set successfully.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1687


def self.ctx_provide_kms_providers(context, kms_providers)
  validate_document(kms_providers)
  data = kms_providers.to_bson.to_s
  Binary.wrap_string(data) do |data_p|
    check_ctx_status(context) do
      mongocrypt_ctx_provide_kms_providers(context.ctx_p, data_p)
    end
  end
end

.ctx_rewrap_many_datakey_init(context, filter) ⇒ `Boolean`

Initialize a context to rewrap datakeys.

Parameters:

context (Mongo::Crypt::Context)
filter (BSON::Document) —

BSON Document that represents filter to use for the find command on the key vault collection to retrieve datakeys to rewrap.

Returns:

(Boolean) —

Whether the initialization was successful.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 656


def self.ctx_rewrap_many_datakey_init(context, filter)
  filter_data = filter.to_bson.to_s
  Binary.wrap_string(filter_data) do |data_p|
    check_ctx_status(context) do
      mongocrypt_ctx_rewrap_many_datakey_init(context.ctx_p, data_p)
    end
  end
end

.ctx_setopt_algorithm(context, name)

Set the algorithm on the context

Parameters:

context (Mongo::Crypt::Context)
name (String) —
The algorithm name. Valid values are:
- “AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic”
- “AEAD_AES_256_CBC_HMAC_SHA_512-Random”

Raises:

(Mongo::Error::CryptError) —

If the operation failed

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 569


def self.ctx_setopt_algorithm(context, name)
  check_ctx_status(context) do
    mongocrypt_ctx_setopt_algorithm(context.ctx_p, name, -1)
  end
end

.ctx_setopt_algorithm_range(context, opts)

Note:

The Range algorithm is experimental only. It is not intended for

Set options for explicit encryption with the “range” algorithm.

public use.

Parameters:

context (Mongo::Crypt::Context)
opts (Hash) —

options

Raises:

(Mongo::Error::CryptError) —

If the operation failed

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1794


def self.ctx_setopt_algorithm_range(context, opts)
  validate_document(opts)
  data = opts.to_bson.to_s
  Binary.wrap_string(data) do |data_p|
    check_ctx_status(context) do
      mongocrypt_ctx_setopt_algorithm_range(context.ctx_p, data_p)
    end
  end
end

.ctx_setopt_contention_factor(context, factor)

Set the contention factor used for explicit encryption. The contention factor is only used for indexed FLE 2 encryption.

Parameters:

context (Mongo::Crypt::Context) —

Explicit encryption context.
factor (Integer) —

Contention factor used for explicit encryption.

Raises:

(Mongo::Error::CryptError) —

If the operation failed.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1757


def self.ctx_setopt_contention_factor(context, factor)
  check_ctx_status(context) do
    mongocrypt_ctx_setopt_contention_factor(context.ctx_p, factor)
  end
end

.ctx_setopt_key_alt_names(context, key_alt_names)

Set multiple alternate key names on data key creation

Parameters:

context (Mongo::Crypt::Context) —

A DataKeyContext
key_alt_names (Array) —

An array of alternate key names as strings

Raises:

(Mongo::Error::CryptError) —

If any of the alternate names are not valid UTF8 strings

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 500


def self.ctx_setopt_key_alt_names(context, key_alt_names)
  key_alt_names.each do |key_alt_name|
    key_alt_name_bson = { :keyAltName => key_alt_name }.to_bson.to_s

    Binary.wrap_string(key_alt_name_bson) do |key_alt_name_p|
      check_ctx_status(context) do
        mongocrypt_ctx_setopt_key_alt_name(context.ctx_p, key_alt_name_p)
      end
    end
  end
end

.ctx_setopt_key_encryption_key(context, key_document)

Set key encryption key document for creating a data key.

Parameters:

context (Mongo::Crypt::Context)
key_document (BSON::Document) —

BSON document representing the key encryption key document with an additional “provider” field.

Raises:

(Mongo::Error::CryptError) —

If the operation failed

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 598


def self.ctx_setopt_key_encryption_key(context, key_document)
  validate_document(key_document)
  data = key_document.to_bson.to_s
  Binary.wrap_string(data) do |data_p|
    check_ctx_status(context) do
      mongocrypt_ctx_setopt_key_encryption_key(context.ctx_p, data_p)
    end
  end
end

.ctx_setopt_key_id(context, key_id)

Sets the key id option on an explicit encryption context.

Parameters:

context (Mongo::Crypt::Context) —

Explicit encryption context
key_id (String) —

The key id

Raises:

(Mongo::Error::CryptError) —

If the operation failed

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 467


def self.ctx_setopt_key_id(context, key_id)
  Binary.wrap_string(key_id) do |key_id_p|
    check_ctx_status(context) do
      mongocrypt_ctx_setopt_key_id(context.ctx_p, key_id_p)
    end
  end
end

.ctx_setopt_key_material(context, key_material)

Set set a custom key material to use for

encrypting data.

Parameters:

context (Mongo::Crypt::Context) —

A DataKeyContext
key_material (BSON::Binary) —

96 bytes of custom key material

Raises:

(Mongo::Error::CryptError) —

If the key material is not 96 bytes.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 535


def self.ctx_setopt_key_material(context, key_material)
  data = {'keyMaterial' => key_material}.to_bson.to_s
  Binary.wrap_string(data) do |data_p|
    check_ctx_status(context) do
      mongocrypt_ctx_setopt_key_material(context.ctx_p, data_p)
    end
  end
end

.ctx_setopt_query_type(context, query_type)

Set the query type to use for FLE 2 explicit encryption. The query type is only used for indexed FLE 2 encryption.

Parameters:

context (Mongo::Crypt::Context) —

Explicit encryption context.
:mongocrypt_query_type (String) —

query_type Type of the query.

Raises:

(Mongo::Error::CryptError) —

If the operation failed.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1725


def self.ctx_setopt_query_type(context, query_type)
  check_ctx_status(context) do
    mongocrypt_ctx_setopt_query_type(context.ctx_p, query_type, -1)
  end
end

.get_binary_data_direct(mongocrypt_binary_t)

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 181


def self.get_binary_data_direct(mongocrypt_binary_t)
  mongocrypt_binary_t.get_pointer(0)
end

.get_binary_len_direct(mongocrypt_binary_t)

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 185


def self.get_binary_len_direct(mongocrypt_binary_t)
  mongocrypt_binary_t.get_uint32(FFI::NativeType::POINTER.size)
end

.init(handle)

Initialize the Mongo::Crypt::Handle object

Parameters:

handle (Mongo::Crypt::Handle)

Raises:

(Mongo::Error::CryptError) —

If initialization fails

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 407


def self.init(handle)
  check_status(handle) do
    mongocrypt_init(handle.ref)
  end
end

.kms_ctx_bytes_needed(kms_context) ⇒ `Integer`

Get the number of bytes needed by the KmsContext.

Parameters:

kms_context (Mongo::Crypt::KmsContext)

Returns:

(Integer) —

The number of bytes needed

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1063


def self.kms_ctx_bytes_needed(kms_context)
  mongocrypt_kms_ctx_bytes_needed(kms_context.kms_ctx_p)
end

.kms_ctx_endpoint(kms_context) ⇒ `String` | `nil`

Get the hostname with which to connect over TLS to get information about the AWS master key.

Parameters:

kms_context (Mongo::Crypt::KmsContext)

Returns:

(String | nil) —

The hostname, or nil if none exists

Raises:

(Mongo::Error::CryptError) —

If the response is not fed successfully

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1039


def self.kms_ctx_endpoint(kms_context)
  ptr = FFI::MemoryPointer.new(:pointer, 1)

  check_kms_ctx_status(kms_context) do
    mongocrypt_kms_ctx_endpoint(kms_context.kms_ctx_p, ptr)
  end

  str_ptr = ptr.read_pointer
  str_ptr.null? ? nil : str_ptr.read_string.force_encoding('UTF-8')
end

.kms_ctx_fail(kms_context) ⇒ `true`, `false`

Check whether the last failed request for the KMS context may be retried.

Parameters:

kms_context (Mongo::Crypt::KmsContext) —

KMS Context

Returns:

(true, false) —

whether the failed request may be retried.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1148


def self.kms_ctx_fail(kms_context)
  mongocrypt_kms_ctx_fail(kms_context.kms_ctx_p)
end

.kms_ctx_feed(kms_context, bytes)

Feed replies from the KMS back to libmongocrypt.

Parameters:

kms_context (Mongo::Crypt::KmsContext)
bytes (String) —

The data to feed to libmongocrypt

Raises:

(Mongo::Error::CryptError) —

If the response is not fed successfully

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1083


def self.kms_ctx_feed(kms_context, bytes)
  check_kms_ctx_status(kms_context) do
    Binary.wrap_string(bytes) do |bytes_p|
      mongocrypt_kms_ctx_feed(kms_context.kms_ctx_p, bytes_p)
    end
  end
end

.kms_ctx_get_kms_provider(kms_context)

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 (FFI::Pointer) —

Pointer mongocrypt_kms_ctx_t object.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 970


def self.kms_ctx_get_kms_provider(kms_context)
  len_ptr = FFI::MemoryPointer.new(:uint32, 1)
  provider = mongocrypt_kms_ctx_get_kms_provider(
    kms_context.kms_ctx_p,
    len_ptr
  )
  if len_ptr.nil?
    nil
  else
    len = if BSON::Environment.jruby?
      # JRuby FFI implementation does not have `read(type)` method, but it
      # has this `get_uint32`.
      len_ptr.get_uint32
    else
      # For MRI we use a documented `read` method - https://www.rubydoc.info/github/ffi/ffi/FFI%2FPointer:read
      len_ptr.read(:uint32)
    end
    provider.read_string(len).to_sym
  end
end

.kms_ctx_message(kms_context) ⇒ `String`

Get the HTTP message needed to fetch the AWS KMS master key from a KmsContext object.

Parameters:

kms_context (Mongo::Crypt::KmsContext)

Returns:

(String) —

The HTTP message

Raises:

(Mongo::Error::CryptError) —

If the response is not fed successfully

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1010


def self.kms_ctx_message(kms_context)
  binary = Binary.new

  check_kms_ctx_status(kms_context) do
    mongocrypt_kms_ctx_message(kms_context.kms_ctx_p, binary.ref)
  end

  return binary.to_s
end

.kms_ctx_setopt_retry_kms(handle, value) ⇒ `true`, `fale`

Enable or disable KMS retry behavior.

Parameters:

handle (Mongo::Crypt::Handle)
value (true, false) —

whether to retry operations.

Returns:

(true, fale) —

true is the option was set, otherwise false.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1167


def self.kms_ctx_setopt_retry_kms(handle, value)
  mongocrypt_setopt_retry_kms(handle.ref, value)
end

.kms_ctx_usleep(kms_context) ⇒ `Integer`

Returns number of milliseconds to sleep before sending KMS request for the given KMS context.

Parameters:

kms_context (Mongo::Crypt::KmsContext) —

KMS Context we are going to send KMS request for.

Returns:

(Integer) —

A 64-bit encoded number of microseconds to sleep.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1131


def self.kms_ctx_usleep(kms_context)
  mongocrypt_kms_ctx_usleep(kms_context.kms_ctx_p)
end

.mongocrypt_binary_data(binary) ⇒ `FFI::Pointer`

Get the pointer to the underlying data for the mongocrypt_binary_t.

Parameters:

binary (FFI::Pointer) —

A pointer to a mongocrypt_binary_t object.

Returns:

(FFI::Pointer) —

A pointer to the data array.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 171


attach_function :mongocrypt_binary_data, [:pointer], :pointer

.mongocrypt_binary_destroy(binary) ⇒ `nil`

Destroy the mongocrypt_binary_t object.

Parameters:

binary (FFI::Pointer) —

A pointer to a mongocrypt_binary_t object.

Returns:

(nil) —

Always nil.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 195


attach_function :mongocrypt_binary_destroy, [:pointer], :void

.mongocrypt_binary_len(binary) ⇒ `Integer`

Get the length of the underlying data array.

Parameters:

binary (FFI::Pointer) —

A pointer to a mongocrypt_binary_t object.

Returns:

(Integer) —

The length of the data array.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 179


attach_function :mongocrypt_binary_len, [:pointer], :int

.mongocrypt_binary_new ⇒ `FFI::Pointer`

Creates a new mongocrypt_binary_t object (a non-owning view of a byte

array).

Returns:

(FFI::Pointer) —

A pointer to the newly-created mongocrypt_binary_t object.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 147


attach_function :mongocrypt_binary_new, [], :pointer

.mongocrypt_binary_new_from_data(data, len) ⇒ `FFI::Pointer`

Create a new mongocrypt_binary_t object that maintains a pointer to

the specified byte array.

Parameters:

data (FFI::Pointer) —

A pointer to an array of bytes; the data is not copied and must outlive the mongocrypt_binary_t object.
len (Integer) —

The length of the array argument.

Returns:

(FFI::Pointer) —

A pointer to the newly-created mongocrypt_binary_t object.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 159


attach_function(
  :mongocrypt_binary_new_from_data,
  [:pointer, :int],
  :pointer
)

.mongocrypt_crypt_shared_lib_version(crypt)

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1592


attach_function(
  :mongocrypt_crypt_shared_lib_version,
  [ :pointer ],
  :uint64
)

.mongocrypt_ctx_datakey_init(ctx, filter)

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 618


attach_function :mongocrypt_ctx_datakey_init, [:pointer], :bool

.mongocrypt_ctx_decrypt_init(ctx, doc) ⇒ `Boolean`

Initializes the ctx for auto-decryption.

Parameters:

ctx (FFI::Pointer) —

A pointer to a mongocrypt_ctx_t object.
doc (FFI::Pointer) —

A pointer to a mongocrypt_binary_t object that references the document to be decrypted as a BSON binary string.

Returns:

(Boolean) —

Whether the initialization was successful.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 778


attach_function :mongocrypt_ctx_decrypt_init, [:pointer, :pointer], :bool

.mongocrypt_ctx_destroy(ctx) ⇒ `nil`

Destroy the reference to the mongocrypt_ctx_t object.

Parameters:

ctx (FFI::Pointer) —

A pointer to a mongocrypt_ctx_t object.

Returns:

(nil) —

Always nil.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1228


attach_function :mongocrypt_ctx_destroy, [:pointer], :void

.mongocrypt_ctx_encrypt_init(ctx, db, db_len, cmd) ⇒ `Boolean`

Note:

This method expects the passed-in BSON to be in the format: { “v”: BSON value to decrypt }.

Initializes the ctx for auto-encryption.

Parameters:

ctx (FFI::Pointer) —

A pointer to a mongocrypt_ctx_t object.
db (String) —

The database name.
db_len (Integer) —

The length of the database name argument (or -1 for a null-terminated string).
cmd (FFI::Pointer) —

A pointer to a mongocrypt_binary_t object that references the database command as a binary string.

Returns:

(Boolean) —

Whether the initialization was successful.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 678


attach_function(
  :mongocrypt_ctx_encrypt_init,
  [:pointer, :string, :int, :pointer],
  :bool
)

.mongocrypt_ctx_explicit_decrypt_init(ctx, msg) ⇒ `Boolean`

Initializes the ctx for explicit decryption.

Parameters:

ctx (FFI::Pointer) —

A pointer to a mongocrypt_ctx_t object.
msg (FFI::Pointer) —

A pointer to a mongocrypt_binary_t object that references the message to be decrypted as a BSON binary string.

Returns:

(Boolean) —

Whether the initialization was successful.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 804


attach_function(
  :mongocrypt_ctx_explicit_decrypt_init,
  [:pointer, :pointer],
  :bool
)

.mongocrypt_ctx_explicit_encrypt_init(ctx, msg) ⇒ `Boolean`

Note:

Before calling this method, set a key_id, key_alt_name (optional), and encryption algorithm using the following methods: mongocrypt_ctx_setopt_key_id, mongocrypt_ctx_setopt_key_alt_name, and mongocrypt_ctx_setopt_algorithm.

Initializes the ctx for explicit expression encryption.

Parameters:

ctx (FFI::Pointer) —

A pointer to a mongocrypt_ctx_t object.
msg (FFI::Pointer) —

A pointer to a mongocrypt_binary_t object that references the message to be encrypted as a binary string.

Returns:

(Boolean) —

Whether the initialization was successful.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 714


attach_function(
  :mongocrypt_ctx_explicit_encrypt_init,
  [:pointer, :pointer],
  :bool
)

.mongocrypt_ctx_finalize(ctx, op_bson) ⇒ `Boolean`

Perform the final encryption or decryption and return a BSON document.

Parameters:

ctx (FFI::Pointer) —

A pointer to a mongocrypt_ctx_t object.
op_bson (FFI::Pointer) —

(out param) A pointer to a mongocrypt_binary_t object that will have a reference to the final encrypted BSON document.

Returns:

(Boolean) —

A boolean indicating the success of the operation.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1201


attach_function :mongocrypt_ctx_finalize, [:pointer, :pointer], :void

.mongocrypt_ctx_mongo_done(ctx) ⇒ `Boolean`

Indicate to libmongocrypt that the driver is done feeding replies.

Parameters:

ctx (FFI::Pointer) —

A pointer to a mongocrypt_ctx_t object.

Returns:

(Boolean) —

A boolean indicating the success of the operation.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 913


attach_function :mongocrypt_ctx_mongo_done, [:pointer], :bool

.mongocrypt_ctx_mongo_feed(ctx, reply) ⇒ `Boolean`

Feed a BSON reply to libmongocrypt.

Parameters:

ctx (FFI::Pointer) —

A pointer to a mongocrypt_ctx_t object.
reply (FFI::Pointer) —

A mongocrypt_binary_t object that references the BSON reply to feed to libmongocrypt.

Returns:

(Boolean) —

A boolean indicating the success of the operation.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 889


attach_function :mongocrypt_ctx_mongo_feed, [:pointer, :pointer], :bool

.mongocrypt_ctx_mongo_next_kms_ctx(ctx) ⇒ `FFI::Pointer`

Return a pointer to a mongocrypt_kms_ctx_t object or NULL.

Parameters:

ctx (FFI::Pointer) —

A pointer to a mongocrypt_ctx_t object.

Returns:

(FFI::Pointer) —

A pointer to a mongocrypt_kms_ctx_t object.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 921


attach_function :mongocrypt_ctx_next_kms_ctx, [:pointer], :pointer

.mongocrypt_ctx_mongo_op(ctx, op_bson) ⇒ `Boolean`

Get a BSON operation for the driver to run against the MongoDB

collection, the key vault database, or mongocryptd.

Parameters:

ctx (FFI::Pointer) —

A pointer to a mongocrypt_ctx_t object.
op_bson (FFI::Pointer) —

(out param) A pointer to a mongocrypt_binary_t object that will have a reference to the BSON operation written to it by libmongocrypt.

Returns:

(Boolean) —

A boolean indicating the success of the operation.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 857


attach_function :mongocrypt_ctx_mongo_op, [:pointer, :pointer], :bool

.mongocrypt_ctx_new(crypt) ⇒ `FFI::Pointer`

Create a new mongocrypt_ctx_t object (a wrapper for the libmongocrypt

state machine).

Parameters:

crypt (FFI::Pointer) —

A pointer to a mongocrypt_t object.

Returns:

(FFI::Pointer) —

A new mongocrypt_ctx_t object.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 438


attach_function :mongocrypt_ctx_new, [:pointer], :pointer

.mongocrypt_ctx_provide_kms_providers(ctx, kms_providers)

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1670


attach_function(
  :mongocrypt_ctx_provide_kms_providers,
  [ :pointer, :pointer ],
  :bool
)

.mongocrypt_ctx_setopt_algorithm(ctx, algorithm, len) ⇒ `Boolean`

Note:

Do not initialize ctx before calling this method.

Set the algorithm used for explicit encryption.

Parameters:

ctx (FFI::Pointer) —

A pointer to a mongocrypt_ctx_t object.
algorithm (String) —
The algorithm name. Valid values are:
- “AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic”
- “AEAD_AES_256_CBC_HMAC_SHA_512-Random”
len (Integer) —

The length of the algorithm string.

Returns:

(Boolean) —

Whether the option was successfully set.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 555


attach_function(
  :mongocrypt_ctx_setopt_algorithm,
  [:pointer, :string, :int],
  :bool
)

.mongocrypt_ctx_setopt_algorithm_range(ctx, opts)

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1776


attach_function(
  :mongocrypt_ctx_setopt_algorithm_range,
  [
    :pointer,
    :pointer
  ],
  :bool
)

.mongocrypt_ctx_setopt_contention_factor(ctx, contention_factor)

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1741


attach_function(
  :mongocrypt_ctx_setopt_contention_factor,
  [
    :pointer,
    :int64
  ],
  :bool
)

.mongocrypt_ctx_setopt_key_alt_name(ctx, binary) ⇒ `Boolean`

Note:

Do not initialize ctx before calling this method.

When creating a data key, set an alternate name on that key. When

performing explicit encryption, specifying which data key to use for
encryption based on its keyAltName field.

Parameters:

ctx (FFI::Pointer) —

A pointer to a mongocrypt_ctx_t object.
binary (FFI::Pointer) —

A pointer to a mongocrypt_binary_t object that references a BSON document in the format { “keyAltName”: <BSON UTF8 value> }.

Returns:

(Boolean) —

Whether the alternative name was successfully set.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 487


attach_function(
  :mongocrypt_ctx_setopt_key_alt_name,
  [:pointer, :pointer],
  :bool
)

.mongocrypt_ctx_setopt_key_encryption_key(ctx) ⇒ `Boolean`

Note:

Do not initialize ctx before calling this method.

Set key encryption key document for creating a data key.

Parameters:

ctx (FFI::Pointer) —

A pointer to a mongocrypt_ctx_t object.
bin (FFI::Pointer) —

A pointer to a mongocrypt_binary_t object that references a BSON document representing the key encryption key document with an additional “provider” field.

Returns:

(Boolean) —

Whether the option was successfully set.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 585


attach_function(
  :mongocrypt_ctx_setopt_key_encryption_key,
  [:pointer, :pointer],
  :bool
)

.mongocrypt_ctx_setopt_key_id(ctx, key_id) ⇒ `Boolean`

Note:

Do not initialize ctx before calling this method.

Set the key id used for explicit encryption.

Parameters:

ctx (FFI::Pointer) —

A pointer to a mongocrypt_ctx_t object.
key_id (FFI::Pointer) —

A pointer to a mongocrypt_binary_t object that references the 16-byte key-id.

Returns:

(Boolean) —

Whether the option was successfully set.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 459


attach_function :mongocrypt_ctx_setopt_key_id, [:pointer, :pointer], :bool

.mongocrypt_ctx_setopt_key_material(ctx, binary) ⇒ `Boolean`

Note:

Do not initialize ctx before calling this method.

When creating a data key, set a custom key material to use for

encrypting data.

Parameters:

ctx (FFI::Pointer) —

A pointer to a mongocrypt_ctx_t object.
binary (FFI::Pointer) —

A pointer to a mongocrypt_binary_t object that references the data encryption key to use.

Returns:

(Boolean) —

Whether the custom key material was successfully set.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 522


attach_function(
  :mongocrypt_ctx_setopt_key_material,
  [:pointer, :pointer],
  :bool
)

.mongocrypt_ctx_setopt_query_type(ctx, mongocrypt_query_type)

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1708


attach_function(
  :mongocrypt_ctx_setopt_query_type,
  [
    :pointer,
    :string,
    :int
  ],
  :bool
)

.mongocrypt_ctx_state(ctx) ⇒ Symbol

Get the current state of the ctx.

Parameters:

ctx (FFI::Pointer) —

A pointer to a mongocrypt_ctx_t object.

Returns:

(Symbol) —

The current state, will be one of the values defined by the mongocrypt_ctx_state enum.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 845


attach_function :mongocrypt_ctx_state, [:pointer], :mongocrypt_ctx_state

.mongocrypt_ctx_status(ctx, status) ⇒ `Boolean`

Set the status information from the mongocrypt_ctx_t object on the

mongocrypt_status_t object.

Parameters:

ctx (FFI::Pointer) —

A pointer to a mongocrypt_ctx_t object.
status (FFI::Pointer) —

A pointer to a mongocrypt_status_t object.

Returns:

(Boolean) —

Whether the status was successfully set.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 448


attach_function :mongocrypt_ctx_status, [:pointer, :pointer], :bool

.mongocrypt_destroy(crypt) ⇒ `nil`

Destroy the reference the mongocrypt_t object.

Parameters:

crypt (FFI::Pointer) —

A pointer to a mongocrypt_t object.

Returns:

(nil) —

Always nil.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 429


attach_function :mongocrypt_destroy, [:pointer], :void

.mongocrypt_init(crypt) ⇒ `Boolean`

Initialize the mongocrypt_t object.

Parameters:

crypt (FFI::Pointer) —

A pointer to a mongocrypt_t object.

Returns:

(Boolean) —

Returns whether the crypt was initialized successfully.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 400


attach_function :mongocrypt_init, [:pointer], :bool

.mongocrypt_kms_ctx_bytes_needed(kms) ⇒ `Integer`

Get the number of bytes needed by the KMS context.

Parameters:

kms (FFI::Pointer) —

The mongocrypt_kms_ctx_t object.

Returns:

(Integer) —

The number of bytes needed.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1056


attach_function :mongocrypt_kms_ctx_bytes_needed, [:pointer], :int

.mongocrypt_kms_ctx_done(ctx) ⇒ `Boolean`

Indicate to libmongocrypt that it will receive no more replies from

mongocrypt_kms_ctx_t objects.

Parameters:

ctx (FFI::Pointer) —

A pointer to a mongocrypt_ctx_t object.

Returns:

(Boolean) —

Whether the operation was successful.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1179


attach_function :mongocrypt_ctx_kms_done, [:pointer], :bool

.mongocrypt_kms_ctx_endpoint(kms, endpoint) ⇒ `Boolean`

Get the hostname with which to connect over TLS to get information about

the AWS master key.

Parameters:

kms (FFI::Pointer) —

A pointer to a mongocrypt_kms_ctx_t object.
endpoint (FFI::Pointer) —

(out param) A pointer to which the endpoint string will be written by libmongocrypt.

Returns:

(Boolean) —

Whether the operation was successful.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1029


attach_function :mongocrypt_kms_ctx_endpoint, [:pointer, :pointer], :bool

.mongocrypt_kms_ctx_fail(ctx)

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1142


attach_function :mongocrypt_kms_ctx_fail, [:pointer], :bool

.mongocrypt_kms_ctx_feed(kms, bytes) ⇒ `Boolean`

Feed replies from the KMS back to libmongocrypt.

Parameters:

kms (FFI::Pointer) —

A pointer to the mongocrypt_kms_ctx_t object.
bytes (FFI::Pointer) —

A pointer to a mongocrypt_binary_t object that references the response from the KMS.

Returns:

(Boolean) —

Whether the operation was successful.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1075


attach_function :mongocrypt_kms_ctx_feed, [:pointer, :pointer], :bool

.mongocrypt_kms_ctx_get_kms_provider(crypt, kms_providers)

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 955


attach_function(
  :mongocrypt_kms_ctx_get_kms_provider,
  [:pointer, :pointer],
  :pointer
)

.mongocrypt_kms_ctx_message(kms, msg) ⇒ `Boolean`

Get the message needed to fetch the AWS KMS master key.

Parameters:

kms (FFI::Pointer) —

Pointer to the mongocrypt_kms_ctx_t object
msg (FFI::Pointer) —

(outparam) Pointer to a mongocrypt_binary_t object that will have the location of the message written to it by libmongocrypt.

Returns:

(Boolean) —

Whether the operation is successful.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1000


attach_function :mongocrypt_kms_ctx_message, [:pointer, :pointer], :bool

.mongocrypt_kms_ctx_status(kms, status) ⇒ `Boolean`

Write status information about the mongocrypt_kms_ctx_t object

to the mongocrypt_status_t object.

Parameters:

kms (FFI::Pointer) —

A pointer to the mongocrypt_kms_ctx_t object.
status (FFI::Pointer) —

A pointer to a mongocrypt_status_t object.

Returns:

(Boolean) —

Whether the operation was successful.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1099


attach_function :mongocrypt_kms_ctx_status, [:pointer, :pointer], :bool

.mongocrypt_kms_ctx_usleep(ctx) ⇒ `int64`

Indicates how long to sleep before sending KMS request.

Parameters:

ctx (FFI::Pointer) —

A pointer to a mongocrypt_ctx_t object.

Returns:

(int64) —

A 64-bit encoded number of microseconds of how long to sleep.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1123


attach_function :mongocrypt_kms_ctx_usleep, [:pointer], :int64

.mongocrypt_setopt_aes_256_ctr(crypt, aes_256_ctr_encrypt, aes_256_ctr_decrypt, ctx) ⇒ `Boolean`

Set a crypto hook for the AES256-CTR operations.

Parameters:

crypt (FFI::Pointer) —

A pointer to a mongocrypt_t object.
aes_enc_fn (Proc) —

An AES-CTR encryption method.
aes_dec_fn (Proc) —

An AES-CTR decryption method.
ctx (FFI::Pointer | nil) —

An optional pointer to a context object that may have been set when hooks were enabled.

Returns:

(Boolean) —

Whether setting this option succeeded.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1487


attach_function(
  :mongocrypt_setopt_aes_256_ctr,
  [
    :pointer,
    :mongocrypt_crypto_fn,
    :mongocrypt_crypto_fn,
    :pointer
  ],
  :bool
)

.mongocrypt_setopt_append_crypt_shared_lib_search_path(crypt, path)

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1525


attach_function(
  :mongocrypt_setopt_append_crypt_shared_lib_search_path,
  [
    :pointer,
    :string,
  ],
  :void
)

.mongocrypt_setopt_bypass_query_analysis(crypt)

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1463


attach_function(:mongocrypt_setopt_bypass_query_analysis, [:pointer], :void)

.mongocrypt_setopt_crypto_hook_sign_rsaes_pkcs1_v1_5(crypt, sign_rsaes_pkcs1_v1_5, ctx = nil) ⇒ `Boolean`

Set a crypto hook for the RSASSA-PKCS1-v1_5 algorithm with a SHA-256 hash.

Parameters:

crypt (FFI::Pointer) —

A pointer to a mongocrypt_t object.
sign_rsaes_pkcs1_v1_5 (Proc) —

A RSASSA-PKCS1-v1_5 signing method.
ctx (FFI::Pointer | nil) (defaults to: nil) —

An optional pointer to a context object that may have been set when hooks were enabled.

Returns:

(Boolean) —

Whether setting this option succeeded.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1380


attach_function(
  :mongocrypt_setopt_crypto_hook_sign_rsaes_pkcs1_v1_5,
  [
    :pointer,
    :mongocrypt_hmac_fn,
    :pointer
  ],
  :bool
)

.mongocrypt_setopt_crypto_hooks(crypt, aes_enc_fn, aes_dec_fn, random_fn, sha_512_fn, sha_256_fn, hash_fn, ctx = nil) ⇒ `Boolean`

Set crypto hooks on the provided mongocrypt object.

Parameters:

crypt (FFI::Pointer) —

A pointer to a mongocrypt_t object.
aes_enc_fn (Proc) —

An AES encryption method.
aes_dec_fn (Proc) —

An AES decryption method.
random_fn (Proc) —

A random method.
sha_512_fn (Proc) —

A HMAC SHA-512 method.
sha_256_fn (Proc) —

A HMAC SHA-256 method.
hash_fn (Proc) —

A SHA-256 hash method.
ctx (FFI::Pointer | nil) (defaults to: nil) —

An optional pointer to a context object that may have been set when hooks were enabled.

Returns:

(Boolean) —

Whether setting this option succeeded.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1333


attach_function(
  :mongocrypt_setopt_crypto_hooks,
  [
    :pointer,
    :mongocrypt_crypto_fn,
    :mongocrypt_crypto_fn,
    :mongocrypt_random_fn,
    :mongocrypt_hmac_fn,
    :mongocrypt_hmac_fn,
    :mongocrypt_hash_fn,
    :pointer
  ],
  :bool
)

.mongocrypt_setopt_encrypted_field_config_map(crypt, efc_map)

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1422


attach_function(
  :mongocrypt_setopt_encrypted_field_config_map,
  [
    :pointer,
    :pointer
  ],
  :bool
)

.mongocrypt_setopt_kms_providers(crypt, kms_providers)

Note:

Do not initialize ctx before calling this method.

Configure KMS providers with a BSON document.

Parameters:

crypt (FFI::Pointer) —

A pointer to a mongocrypt_t object.
kms_providers (FFI::Pointer) —

A pointer to a mongocrypt_binary_t object that references a BSON document mapping the KMS provider names to credentials.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 344


attach_function(
  :mongocrypt_setopt_kms_providers,
  [:pointer, :pointer],
  :bool
)

.mongocrypt_setopt_log_handler(crypt, log_fn, log_ctx = nil) ⇒ `Boolean`

Set the handler on the mongocrypt_t object to be called every time

libmongocrypt logs a message.

Parameters:

crypt (FFI::Pointer) —

A pointer to a mongocrypt_t object.
log_fn (Method) —

A logging callback method.
log_ctx (FFI::Pointer | nil) (defaults to: nil) —

An optional pointer to a context to be passed into the log callback on every invocation.

Returns:

(Boolean) —

Whether setting the callback was successful.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 315


attach_function(
  :mongocrypt_setopt_log_handler,
  [:pointer, :mongocrypt_log_fn_t, :pointer],
  :bool
)

.mongocrypt_setopt_retry_kms(crypt, enable)

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1160


attach_function :mongocrypt_setopt_retry_kms, [:pointer, :bool], :bool

.mongocrypt_setopt_schema_map(crypt, schema_map) ⇒ `Boolean`

Sets a local schema map for encryption.

Parameters:

crypt (FFI::Pointer) —

A pointer to a mongocrypt_t object.
schema_map (FFI::Pointer) —

A pointer to a mongocrypt_binary_t. object that references the schema map as a BSON binary string.

Returns:

(Boolean) —

Returns whether the option was set successfully.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 375


attach_function :mongocrypt_setopt_schema_map, [:pointer, :pointer], :bool

.mongocrypt_setopt_set_crypt_shared_lib_path_override(crypt, path)

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1554


attach_function(
  :mongocrypt_setopt_set_crypt_shared_lib_path_override,
  [
    :pointer,
    :string,
  ],
  :void
)

.mongocrypt_setopt_use_need_kms_credentials_state(crypt)

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1633


attach_function(
  :mongocrypt_setopt_use_need_kms_credentials_state,
  [ :pointer ],
  :void
)

.mongocrypt_status(crypt, status) ⇒ `Boolean`

Set the status information from the mongocrypt_t object on the

mongocrypt_status_t object.

Parameters:

crypt (FFI::Pointer) —

A pointer to a mongocrypt_t object.
status (FFI::Pointer) —

A pointer to a mongocrypt_status_t object.

Returns:

(Boolean) —

Whether the status was successfully set.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 421


attach_function :mongocrypt_status, [:pointer, :pointer], :bool

.mongocrypt_status_code(status) ⇒ `Integer`

Return the status error code.

Parameters:

status (FFI::Pointer) —

A pointer to a mongocrypt_status_t.

Returns:

(Integer) —

The status code.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 243


attach_function :mongocrypt_status_code, [:pointer], :int

.mongocrypt_status_destroy(status) ⇒ `nil`

Destroys the reference to the mongocrypt_status_t object.

Parameters:

status (FFI::Pointer) —

A pointer to a mongocrypt_status_t.

Returns:

(nil) —

Always nil.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 269


attach_function :mongocrypt_status_destroy, [:pointer], :void

.mongocrypt_status_message(status, len = nil) ⇒ `String`

Returns the status message.

Parameters:

status (FFI::Pointer) —

A pointer to a mongocrypt_status_t.
len (FFI::Pointer | nil) (defaults to: nil) —

(out param) An optional pointer to a uint32, where the length of the retun string will be written.

Returns:

(String) —

The status message.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 253


attach_function :mongocrypt_status_message, [:pointer, :pointer], :string

.mongocrypt_status_new ⇒ `FFI::Pointer`

Create a new mongocrypt_status_t object.

Returns:

(FFI::Pointer) —

A pointer to the new mongocrypt_status_ts.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 209


attach_function :mongocrypt_status_new, [], :pointer

.mongocrypt_status_ok(status) ⇒ `Boolean`

Returns whether the status is ok or an error.

Parameters:

status (FFI::Pointer) —

A pointer to a mongocrypt_status_t.

Returns:

(Boolean) —

Whether the status is ok.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 261


attach_function :mongocrypt_status_ok, [:pointer], :bool

.mongocrypt_status_set(status, type, code, message, len) ⇒ `nil`

Set a message, type, and code on an existing status.

Parameters:

status (FFI::Pointer) —

A pointer to a mongocrypt_status_t.
type (Symbol) —

The status type; possible values are defined by the status_type enum.
code (Integer) —

The status code.
message (String) —

The status message.
len (Integer) —

The length of the message argument (or -1 for a null-terminated string).

Returns:

(nil) —

Always nil.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 223


attach_function(
  :mongocrypt_status_set,
  [:pointer, :status_type, :int, :string, :int],
  :void
)

.mongocrypt_status_type(status) ⇒ Symbol

Indicates the status type.

Parameters:

status (FFI::Pointer) —

A pointer to a mongocrypt_status_t.

Returns:

(Symbol) —

The status type (as defined by the status_type enum).

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 235


attach_function :mongocrypt_status_type, [:pointer], :status_type

.mongocrypt_version(len) ⇒ `String`

Returns the version string of the libmongocrypt library.

Parameters:

len (FFI::Pointer | nil) —

(out param) An optional pointer to a uint8 that will reference the length of the returned string.

Returns:

(String) —

A version string for libmongocrypt.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 95


attach_function :mongocrypt_version, [:pointer], :string

.ongocrypt_new ⇒ `FFI::Pointer`

Creates a new mongocrypt_t object.

Returns:

(FFI::Pointer) —

A pointer to a new mongocrypt_t object.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 303


attach_function :mongocrypt_new, [], :pointer

.parse_version(version) ⇒ `Gem::Version`

Given a string representing a version number, parses it into a Gem::Version object. This handles the case where the string is not in a format supported by Gem::Version by doing some custom parsing.

Parameters:

version (String) —

String representing a version number.

Returns:

(Gem::Version) —

the version number

Raises:

(ArgumentError) —

if the string cannot be parsed.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 108


def self.parse_version(version)
  Gem::Version.new(version)
rescue ArgumentError
  match = version.match(/\A(?<major>\d+)\.(?<minor>\d+)\.(?<patch>\d+)?(-[A-Za-z\+\d]+)?\z/)
  raise ArgumentError.new("Malformed version number string #{version}") if match.nil?

  Gem::Version.new(
    [
      match[:major],
      match[:minor],
      match[:patch]
    ].join('.')
  )
end

.setopt_aes_256_ctr(handle, aes_ctr_encrypt_cb, aes_ctr_decrypt_cb)

Set a crypto hook for the AES256-CTR operations.

Parameters:

handle (Mongo::Crypt::Handle)
aes_encrypt_cb (Method) —

An AES-CTR encryption method
aes_decrypt_cb (Method) —

A AES-CTR decryption method

Raises:

(Mongo::Error::CryptError) —

If the callbacks aren’t set successfully

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1505


def self.setopt_aes_256_ctr(handle, aes_ctr_encrypt_cb, aes_ctr_decrypt_cb)
  check_status(handle) do
    mongocrypt_setopt_aes_256_ctr(handle.ref,
      aes_ctr_encrypt_cb, aes_ctr_decrypt_cb, nil
    )
  end
end

.setopt_append_crypt_shared_lib_search_path(handle, path)

Append an additional search directory to the search path for loading

the crypt_shared dynamic library.

Parameters:

handle (Mongo::Crypt::Handle)
path (String) —

A search path for the crypt shared library.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1539


def self.setopt_append_crypt_shared_lib_search_path(handle, path)
  check_status(handle) do
    mongocrypt_setopt_append_crypt_shared_lib_search_path(handle.ref, path)
  end
end

.setopt_bypass_query_analysis(handle)

Opt-into skipping query analysis.

If opted in:

The csfle shared library will not attempt to be loaded.
A mongocrypt_ctx_t will never enter the MONGOCRYPT_CTX_NEED_MARKINGS state.

Parameters:

handle (Mongo::Crypt::Handle)

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1472


def self.setopt_bypass_query_analysis(handle)
  mongocrypt_setopt_bypass_query_analysis(handle.ref)
end

.setopt_crypto_hook_sign_rsaes_pkcs1_v1_5(handle, rsaes_pkcs_signature_cb)

Set a crypto hook for the RSASSA-PKCS1-v1_5 algorithm with

a SHA-256 hash oh the Handle.

Parameters:

handle (Mongo::Crypt::Handle)
rsaes_pkcs_signature_cb (Method) —

A RSASSA-PKCS1-v1_5 signing method.

Raises:

(Mongo::Error::CryptError) —

If the callbacks aren’t set successfully

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1397


def self.setopt_crypto_hook_sign_rsaes_pkcs1_v1_5(
  handle,
  rsaes_pkcs_signature_cb
)
  check_status(handle) do
    mongocrypt_setopt_crypto_hook_sign_rsaes_pkcs1_v1_5(
      handle.ref,
      rsaes_pkcs_signature_cb,
      nil
    )
  end
end

.setopt_crypto_hooks(handle, aes_encrypt_cb, aes_decrypt_cb, random_cb, hmac_sha_512_cb, hmac_sha_256_cb, hmac_hash_cb)

Set crypto callbacks on the Handle

Parameters:

handle (Mongo::Crypt::Handle)
aes_encrypt_cb (Method) —

An AES encryption method
aes_decrypt_cb (Method) —

A AES decryption method
random_cb (Method) —

A method that returns a string of random bytes
hmac_sha_512_cb (Method) —

A HMAC SHA-512 method
hmac_sha_256_cb (Method) —

A HMAC SHA-256 method
hmac_hash_cb (Method) —

A SHA-256 hash method

Raises:

(Mongo::Error::CryptError) —

If the callbacks aren’t set successfully

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1359


def self.setopt_crypto_hooks(handle,
  aes_encrypt_cb, aes_decrypt_cb, random_cb,
  hmac_sha_512_cb, hmac_sha_256_cb, hmac_hash_cb
)
  check_status(handle) do
    mongocrypt_setopt_crypto_hooks(handle.ref,
      aes_encrypt_cb, aes_decrypt_cb, random_cb,
      hmac_sha_512_cb, hmac_sha_256_cb, hmac_hash_cb, nil
    )
  end
end

.setopt_encrypted_field_config_map(handle, efc_map)

Set a local EncryptedFieldConfigMap for encryption.

Parameters:

handle (Mongo::Crypt::Handle)
efc_map (BSON::Document) —

A BSON document representing the EncryptedFieldConfigMap supplied by the user. The keys are collection namespaces and values are EncryptedFieldConfigMap documents.

Raises:

(Mongo::Error::CryptError) —

If the operation failed.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1440


def self.setopt_encrypted_field_config_map(handle, efc_map)
  validate_document(efc_map)
  data = efc_map.to_bson.to_s
  Binary.wrap_string(data) do |data_p|
    check_status(handle) do
      mongocrypt_setopt_encrypted_field_config_map(
        handle.ref,
        data_p
      )
    end
  end
end

.setopt_kms_providers(handle, kms_providers)

Set KMS providers options on the Mongo::Crypt::Handle object

Parameters:

handle (Mongo::Crypt::Handle)
kms_providers (BSON::Document) —

BSON document mapping the KMS provider names to credentials.

Raises:

(Mongo::Error::CryptError) —

If the option is not set successfully

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 357


def self.setopt_kms_providers(handle, kms_providers)
  validate_document(kms_providers)
  data = kms_providers.to_bson.to_s
  Binary.wrap_string(data) do |data_p|
    check_status(handle) do
      mongocrypt_setopt_kms_providers(handle.ref, data_p)
    end
  end
end

.setopt_log_handler(handle, log_callback)

Set the logger callback function on the Mongo::Crypt::Handle object

Parameters:

handle (Mongo::Crypt::Handle)
log_callback (Method)

Raises:

(Mongo::Error::CryptError) —

If the callback is not set successfully

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 327


def self.setopt_log_handler(handle, log_callback)
  check_status(handle) do
    mongocrypt_setopt_log_handler(handle, log_callback, nil)
  end
end

.setopt_schema_map(handle, schema_map_doc)

Set schema map on the Mongo::Crypt::Handle object

Parameters:

handle (Mongo::Crypt::Handle)
schema_map_doc (BSON::Document) —

The schema map as a BSON::Document object

Raises:

(Mongo::Error::CryptError) —

If the schema map is not set successfully

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 384


def self.setopt_schema_map(handle, schema_map_doc)
  validate_document(schema_map_doc)
  data = schema_map_doc.to_bson.to_s
  Binary.wrap_string(data) do |data_p|
    check_status(handle) do
      mongocrypt_setopt_schema_map(handle.ref, data_p)
    end
  end
end

.setopt_set_crypt_shared_lib_path_override(handle, path)

Set a single override path for loading the crypt shared library.

Parameters:

handle (Mongo::Crypt::Handle)
path (String) —

A path to crypt shared library file.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1567


def self.setopt_set_crypt_shared_lib_path_override(handle, path)
  check_status(handle) do
    mongocrypt_setopt_set_crypt_shared_lib_path_override(handle.ref, path)
  end
end

.setopt_use_need_kms_credentials_state(handle)

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 .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 .mongocrypt_setopt_kms_providers.

Parameters:

handle (Mongo::Crypt::Handle)

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1651


def self.setopt_use_need_kms_credentials_state(handle)
  mongocrypt_setopt_use_need_kms_credentials_state(handle.ref)
end

.validate_document(data)

Note:

All BSON::Document instances are also Hash instances

Checks that the specified data is a Hash before serializing it to BSON to prevent errors from libmongocrypt

Parameters:

data (Object) —

The data to be passed to libmongocrypt

Raises:

(Mongo::Error::CryptError) —

If the data is not a Hash

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1844


def self.validate_document(data)
  return if data.is_a?(Hash)

  if data.nil?
    message = "Attempted to pass nil data to libmongocrypt. " +
      "Data must be a Hash"
  else
    message = "Attempted to pass invalid data to libmongocrypt: #{data} " +
      "Data must be a Hash"
  end

  raise Error::CryptError.new(message)
end

.validate_version(lmc_version)

Validates if provided version of libmongocrypt is valid, i.e. equal or greater than minimum required version. Raises a LoadError if not.

Parameters:

lmc_version (String) —

String representing libmongocrypt version.

Raises:

(LoadError) —

if given version is lesser than minimum required version.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 131


def self.validate_version(lmc_version)
  if (actual_version = parse_version(lmc_version)) < MIN_LIBMONGOCRYPT_VERSION
    raise LoadError, "libmongocrypt version #{MIN_LIBMONGOCRYPT_VERSION} or above is required, " +
      "but version #{actual_version} was found."
  end
end

Instance Method Details

#mongocrypt_crypto_fn(ctx, key, iv, input, output, status) ⇒ `Bool`

Note:

This defines a method signature for an FFI callback; it is not an instance method on the Binding class.

A callback to a function that performs AES encryption or decryption.

Parameters:

ctx (FFI::Pointer | nil) —

An optional pointer to a context object that may have been set when hooks were enabled.
key (FFI::Pointer) —

A pointer to a mongocrypt_binary_t object that references the 32-byte AES encryption key.
iv (FFI::Pointer) —

A pointer to a mongocrypt_binary_t object that references the 16-byte AES IV.
input (FFI::Pointer) —

A pointer to a mongocrypt_binary_t object that references the value to be encrypted/decrypted.
output (FFI::Pointer) —

(out param) A pointer to a mongocrypt_binary_t object will have a reference to the encrypted/ decrypted value written to it by libmongocrypt.
status (FFI::Pointer) —

A pointer to a mongocrypt_status_t object to which an error message will be written if encryption fails.

Returns:

(Bool) —

Whether encryption/decryption was successful.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1251


callback(
  :mongocrypt_crypto_fn,
  [:pointer, :pointer, :pointer, :pointer, :pointer, :pointer, :pointer],
  :bool
)

#mongocrypt_hash_fn(ctx, input, output, status) ⇒ `Bool`

Note:

This defines a method signature for an FFI callback; it is not an instance method on the Binding class.

A callback to a SHA-256 hash function.

Parameters:

ctx (FFI::Pointer | nil) —

An optional pointer to a context object that may have been set when hooks were enabled.
input (FFI::Pointer) —

A pointer to a mongocrypt_binary_t object that references the value to be hashed.
output (FFI::Pointer) —

(out param) A pointer to a mongocrypt_binary_t object will have a reference to the output value written to it by libmongocrypt.
status (FFI::Pointer) —

A pointer to a mongocrypt_status_t object to which an error message will be written if encryption fails.

Returns:

(Bool) —

Whether hashing was successful.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1299


callback :mongocrypt_hash_fn, [:pointer, :pointer, :pointer, :pointer], :bool

#mongocrypt_hmac_fn(ctx, key, input, output, status) ⇒ `Bool`

Note:

This defines a method signature for an FFI callback; it is not an instance method on the Binding class.

A callback to a function that performs HMAC SHA-512 or SHA-256.

Parameters:

ctx (FFI::Pointer | nil) —

An optional pointer to a context object that may have been set when hooks were enabled.
key (FFI::Pointer) —

A pointer to a mongocrypt_binary_t object that references the 32-byte HMAC SHA encryption key.
input (FFI::Pointer) —

A pointer to a mongocrypt_binary_t object that references the input value.
output (FFI::Pointer) —

(out param) A pointer to a mongocrypt_binary_t object will have a reference to the output value written to it by libmongocrypt.
status (FFI::Pointer) —

A pointer to a mongocrypt_status_t object to which an error message will be written if encryption fails.

Returns:

(Bool) —

Whether HMAC-SHA was successful.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1276


callback(
  :mongocrypt_hmac_fn,
  [:pointer, :pointer, :pointer, :pointer, :pointer],
  :bool
)

#mongocrypt_log_fn_t(level, message, len, ctx) ⇒ `nil`

Note:

This defines a method signature for an FFI callback; it is not an instance method on the Binding class.

A callback to the mongocrypt log function. Set a custom log callback

with the mongocrypt_setopt_log_handler method

Parameters:

level (Symbol) —

The log level; possible values defined by the log_level enum
message (String) —

The log message
len (Integer) —

The length of the message param, or -1 if the string is null terminated
ctx (FFI::Pointer | nil) —

An optional pointer to a context object when this callback was set

Returns:

(nil) —

Always nil.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 296


callback :mongocrypt_log_fn_t, [:log_level, :string, :int, :pointer], :void

#mongocrypt_random_fn(ctx, output, count, status) ⇒ `Bool`

Note:

This defines a method signature for an FFI callback; it is not an instance method on the Binding class.

A callback to a crypto secure random function.

Parameters:

ctx (FFI::Pointer | nil) —

An optional pointer to a context object that may have been set when hooks were enabled.
output (FFI::Pointer) —

(out param) A pointer to a mongocrypt_binary_t object will have a reference to the output value written to it by libmongocrypt.
count (Integer) —

The number of random bytes to return.
status (FFI::Pointer) —

A pointer to a mongocrypt_status_t object to which an error message will be written if encryption fails.

Returns:

(Bool) —

Whether hashing was successful.

[ GitHub ]

# File 'lib/mongo/crypt/binding.rb', line 1317


callback :mongocrypt_random_fn, [:pointer, :pointer, :int, :pointer], :bool

Class: Mongo::Crypt::Binding Private

Overview

Constant Summary

Class Method Summary

Instance Method Summary

Class Method Details

.check_ctx_status(context) ⇒ nil

.check_kms_ctx_status(kms_context)

.check_status(handle) ⇒ nil

.crypt_shared_lib_version(handle) ⇒ Integer

.ctx_datakey_init(context)

.ctx_decrypt_init(context, command)

.ctx_encrypt_init(context, db_name, command)

.ctx_explicit_decrypt_init(context, doc)

.ctx_explicit_encrypt_expression_init(context, doc)

.ctx_explicit_encrypt_init(context, doc)

.ctx_finalize(context)

.ctx_kms_done(context)

.ctx_mongo_feed(context, doc)

.ctx_mongo_op(context) ⇒ BSON::Document

.ctx_next_kms_ctx(context) ⇒ Mongo::Crypt::KmsContext | nil

.ctx_provide_kms_providers(context, kms_providers)

.ctx_rewrap_many_datakey_init(context, filter) ⇒ Boolean

.ctx_setopt_algorithm(context, name)

.ctx_setopt_algorithm_range(context, opts)

.ctx_setopt_contention_factor(context, factor)

.ctx_setopt_key_alt_names(context, key_alt_names)

.ctx_setopt_key_encryption_key(context, key_document)

.ctx_setopt_key_id(context, key_id)

.ctx_setopt_key_material(context, key_material)

.ctx_setopt_query_type(context, query_type)

.get_binary_data_direct(mongocrypt_binary_t)

.get_binary_len_direct(mongocrypt_binary_t)

.init(handle)

.kms_ctx_bytes_needed(kms_context) ⇒ Integer

.kms_ctx_endpoint(kms_context) ⇒ String | nil

.kms_ctx_fail(kms_context) ⇒ true, false

.kms_ctx_feed(kms_context, bytes)

.kms_ctx_get_kms_provider(kms_context)

.kms_ctx_message(kms_context) ⇒ String

.kms_ctx_setopt_retry_kms(handle, value) ⇒ true, fale

.kms_ctx_usleep(kms_context) ⇒ Integer

.mongocrypt_binary_data(binary) ⇒ FFI::Pointer

.mongocrypt_binary_destroy(binary) ⇒ nil

.mongocrypt_binary_len(binary) ⇒ Integer

.mongocrypt_binary_new ⇒ FFI::Pointer

.mongocrypt_binary_new_from_data(data, len) ⇒ FFI::Pointer

.mongocrypt_crypt_shared_lib_version(crypt)

.mongocrypt_ctx_datakey_init(ctx, filter)

.mongocrypt_ctx_decrypt_init(ctx, doc) ⇒ Boolean

.mongocrypt_ctx_destroy(ctx) ⇒ nil

.mongocrypt_ctx_encrypt_init(ctx, db, db_len, cmd) ⇒ Boolean

.mongocrypt_ctx_explicit_decrypt_init(ctx, msg) ⇒ Boolean

.mongocrypt_ctx_explicit_encrypt_init(ctx, msg) ⇒ Boolean

.mongocrypt_ctx_finalize(ctx, op_bson) ⇒ Boolean

.mongocrypt_ctx_mongo_done(ctx) ⇒ Boolean

.mongocrypt_ctx_mongo_feed(ctx, reply) ⇒ Boolean

.mongocrypt_ctx_mongo_next_kms_ctx(ctx) ⇒ FFI::Pointer

.mongocrypt_ctx_mongo_op(ctx, op_bson) ⇒ Boolean

.mongocrypt_ctx_new(crypt) ⇒ FFI::Pointer

.mongocrypt_ctx_provide_kms_providers(ctx, kms_providers)

.mongocrypt_ctx_setopt_algorithm(ctx, algorithm, len) ⇒ Boolean

.mongocrypt_ctx_setopt_algorithm_range(ctx, opts)

.mongocrypt_ctx_setopt_contention_factor(ctx, contention_factor)

.mongocrypt_ctx_setopt_key_alt_name(ctx, binary) ⇒ Boolean

.mongocrypt_ctx_setopt_key_encryption_key(ctx) ⇒ Boolean

.mongocrypt_ctx_setopt_key_id(ctx, key_id) ⇒ Boolean

.mongocrypt_ctx_setopt_key_material(ctx, binary) ⇒ Boolean

.mongocrypt_ctx_setopt_query_type(ctx, mongocrypt_query_type)

.mongocrypt_ctx_state(ctx) ⇒ Symbol

.mongocrypt_ctx_status(ctx, status) ⇒ Boolean

.mongocrypt_destroy(crypt) ⇒ nil

.mongocrypt_init(crypt) ⇒ Boolean

.mongocrypt_kms_ctx_bytes_needed(kms) ⇒ Integer

.mongocrypt_kms_ctx_done(ctx) ⇒ Boolean

.mongocrypt_kms_ctx_endpoint(kms, endpoint) ⇒ Boolean

.mongocrypt_kms_ctx_fail(ctx)

.mongocrypt_kms_ctx_feed(kms, bytes) ⇒ Boolean

.mongocrypt_kms_ctx_get_kms_provider(crypt, kms_providers)

.mongocrypt_kms_ctx_message(kms, msg) ⇒ Boolean

.check_ctx_status(context) ⇒ `nil`

.check_status(handle) ⇒ `nil`

.crypt_shared_lib_version(handle) ⇒ `Integer`

.ctx_mongo_op(context) ⇒ `BSON::Document`

.ctx_next_kms_ctx(context) ⇒ Mongo::Crypt::KmsContext | `nil`

.ctx_rewrap_many_datakey_init(context, filter) ⇒ `Boolean`

.kms_ctx_bytes_needed(kms_context) ⇒ `Integer`

.kms_ctx_endpoint(kms_context) ⇒ `String` | `nil`

.kms_ctx_fail(kms_context) ⇒ `true`, `false`

.kms_ctx_message(kms_context) ⇒ `String`

.kms_ctx_setopt_retry_kms(handle, value) ⇒ `true`, `fale`

.kms_ctx_usleep(kms_context) ⇒ `Integer`

.mongocrypt_binary_data(binary) ⇒ `FFI::Pointer`

.mongocrypt_binary_destroy(binary) ⇒ `nil`

.mongocrypt_binary_len(binary) ⇒ `Integer`

.mongocrypt_binary_new ⇒ `FFI::Pointer`

.mongocrypt_binary_new_from_data(data, len) ⇒ `FFI::Pointer`

.mongocrypt_ctx_decrypt_init(ctx, doc) ⇒ `Boolean`

.mongocrypt_ctx_destroy(ctx) ⇒ `nil`

.mongocrypt_ctx_encrypt_init(ctx, db, db_len, cmd) ⇒ `Boolean`

.mongocrypt_ctx_explicit_decrypt_init(ctx, msg) ⇒ `Boolean`

.mongocrypt_ctx_explicit_encrypt_init(ctx, msg) ⇒ `Boolean`

.mongocrypt_ctx_finalize(ctx, op_bson) ⇒ `Boolean`

.mongocrypt_ctx_mongo_done(ctx) ⇒ `Boolean`

.mongocrypt_ctx_mongo_feed(ctx, reply) ⇒ `Boolean`

.mongocrypt_ctx_mongo_next_kms_ctx(ctx) ⇒ `FFI::Pointer`

.mongocrypt_ctx_mongo_op(ctx, op_bson) ⇒ `Boolean`

.mongocrypt_ctx_new(crypt) ⇒ `FFI::Pointer`

.mongocrypt_ctx_setopt_algorithm(ctx, algorithm, len) ⇒ `Boolean`

.mongocrypt_ctx_setopt_key_alt_name(ctx, binary) ⇒ `Boolean`

.mongocrypt_ctx_setopt_key_encryption_key(ctx) ⇒ `Boolean`

.mongocrypt_ctx_setopt_key_id(ctx, key_id) ⇒ `Boolean`

.mongocrypt_ctx_setopt_key_material(ctx, binary) ⇒ `Boolean`

.mongocrypt_ctx_status(ctx, status) ⇒ `Boolean`

.mongocrypt_destroy(crypt) ⇒ `nil`

.mongocrypt_init(crypt) ⇒ `Boolean`

.mongocrypt_kms_ctx_bytes_needed(kms) ⇒ `Integer`

.mongocrypt_kms_ctx_done(ctx) ⇒ `Boolean`

.mongocrypt_kms_ctx_endpoint(kms, endpoint) ⇒ `Boolean`

.mongocrypt_kms_ctx_feed(kms, bytes) ⇒ `Boolean`

.mongocrypt_kms_ctx_message(kms, msg) ⇒ `Boolean`

.mongocrypt_kms_ctx_status(kms, status) ⇒ `Boolean`

.mongocrypt_kms_ctx_usleep(ctx) ⇒ `int64`

.mongocrypt_setopt_aes_256_ctr(crypt, aes_256_ctr_encrypt, aes_256_ctr_decrypt, ctx) ⇒ `Boolean`

.mongocrypt_setopt_crypto_hook_sign_rsaes_pkcs1_v1_5(crypt, sign_rsaes_pkcs1_v1_5, ctx = nil) ⇒ `Boolean`

.mongocrypt_setopt_crypto_hooks(crypt, aes_enc_fn, aes_dec_fn, random_fn, sha_512_fn, sha_256_fn, hash_fn, ctx = nil) ⇒ `Boolean`

.mongocrypt_setopt_log_handler(crypt, log_fn, log_ctx = nil) ⇒ `Boolean`

.mongocrypt_setopt_schema_map(crypt, schema_map) ⇒ `Boolean`

.mongocrypt_status(crypt, status) ⇒ `Boolean`

.mongocrypt_status_code(status) ⇒ `Integer`

.mongocrypt_status_destroy(status) ⇒ `nil`

.mongocrypt_status_message(status, len = nil) ⇒ `String`

.mongocrypt_status_new ⇒ `FFI::Pointer`

.mongocrypt_status_ok(status) ⇒ `Boolean`

.mongocrypt_status_set(status, type, code, message, len) ⇒ `nil`

.mongocrypt_version(len) ⇒ `String`

.ongocrypt_new ⇒ `FFI::Pointer`

.parse_version(version) ⇒ `Gem::Version`

#mongocrypt_crypto_fn(ctx, key, iv, input, output, status) ⇒ `Bool`

#mongocrypt_hash_fn(ctx, input, output, status) ⇒ `Bool`

#mongocrypt_hmac_fn(ctx, key, input, output, status) ⇒ `Bool`

#mongocrypt_log_fn_t(level, message, len, ctx) ⇒ `nil`

#mongocrypt_random_fn(ctx, output, count, status) ⇒ `Bool`