Class: Mongo::Crypt::Binding Private

Inherits:
Object
  • Object
show all
Extended by:
FFI::Library
Defined in:
lib/mongo/crypt/binding.rb

Overview

This class is part of a private API. You should avoid using this class if possible, as it may be removed or be changed in the future.

A Ruby binding for the libmongocrypt C library

Constant Summary collapse

MIN_LIBMONGOCRYPT_VERSION =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

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.

Gem::Version.new('1.20.0')

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.check_ctx_status(context) ⇒ nil

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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

Returns:

  • (nil) —

    Always nil.



1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
 
# File 'lib/mongo/crypt/binding.rb', line 1958

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

  return unless do_raise

  status = Status.new

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

.check_kms_ctx_status(kms_context) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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

Parameters:

Raises:



1106
1107
1108
1109
1110
 
# File 'lib/mongo/crypt/binding.rb', line 1106

def self.check_kms_ctx_status(kms_context)
  return if yield

  kms_ctx_status(kms_context).raise_crypt_error(kms: true)
end

.check_status(handle) ⇒ nil

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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

Returns:

  • (nil) —

    Always nil.



1945
1946
1947
1948
1949
1950
1951
1952
 
# File 'lib/mongo/crypt/binding.rb', line 1945

def self.check_status(handle)
  return if yield

  status = Status.new

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

.crypt_shared_lib_version(handle) ⇒ Integer

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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:

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.



1644
1645
1646
 
# File 'lib/mongo/crypt/binding.rb', line 1644

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

.ctx_datakey_init(context) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Initialize the Context to create a data key

Parameters:

Raises:



623
624
625
626
627
 
# File 'lib/mongo/crypt/binding.rb', line 623

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) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Initialize the Context for auto-decryption

Parameters:

Raises:



784
785
786
787
788
789
790
791
792
 
# File 'lib/mongo/crypt/binding.rb', line 784

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) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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:



690
691
692
693
694
695
696
697
698
 
# File 'lib/mongo/crypt/binding.rb', line 690

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) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Initialize the Context for explicit decryption

Parameters:

Raises:



814
815
816
817
818
819
820
821
822
 
# File 'lib/mongo/crypt/binding.rb', line 814

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) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Initialize the Context for explicit expression encryption.

Parameters:

Raises:



758
759
760
761
762
763
764
765
766
 
# File 'lib/mongo/crypt/binding.rb', line 758

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) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Initialize the Context for explicit encryption

Parameters:

Raises:



724
725
726
727
728
729
730
731
732
 
# File 'lib/mongo/crypt/binding.rb', line 724

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) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Finalize the state machine represented by the Context

Parameters:

Raises:



1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
 
# File 'lib/mongo/crypt/binding.rb', line 1217

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: context.bson_mode)
end

.ctx_kms_done(context) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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

Parameters:

Raises:



1194
1195
1196
1197
1198
 
# File 'lib/mongo/crypt/binding.rb', line 1194

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

.ctx_mongo_db(context) ⇒ String

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Get the database name for the current collinfo operation.

Parameters:

Returns:

  • (String) —

    The database name.



1745
1746
1747
1748
1749
1750
 
# File 'lib/mongo/crypt/binding.rb', line 1745

def self.ctx_mongo_db(context)
  db_name = mongocrypt_ctx_mongo_db(context.ctx_p)
  return db_name if db_name

  check_ctx_status(context)
end

.ctx_mongo_feed(context, doc) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Feed a response from the driver back to libmongocrypt

Parameters:

Raises:



896
897
898
899
900
901
902
903
904
 
# File 'lib/mongo/crypt/binding.rb', line 896

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

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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:

Returns:

  • (BSON::Document) —

    The operation that the driver must perform

Raises:

  • (Mongo::Crypt) —

    If there is an error getting the operation



867
868
869
870
871
872
873
874
875
876
877
878
 
# File 'lib/mongo/crypt/binding.rb', line 867

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

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Return a new KmsContext object needed by a Context object.

Parameters:

Returns:

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

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



928
929
930
931
932
933
934
935
936
 
# File 'lib/mongo/crypt/binding.rb', line 928

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) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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:



1784
1785
1786
1787
1788
1789
1790
1791
1792
 
# File 'lib/mongo/crypt/binding.rb', line 1784

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

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



654
655
656
657
658
659
660
661
 
# File 'lib/mongo/crypt/binding.rb', line 654

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) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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:



567
568
569
570
571
 
# File 'lib/mongo/crypt/binding.rb', line 567

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) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Note:

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

Set options for explicit encryption with the "range" algorithm.

public use.

Parameters:

Raises:



1891
1892
1893
1894
1895
1896
1897
1898
1899
 
# File 'lib/mongo/crypt/binding.rb', line 1891

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_algorithm_text(context, opts) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Set options for explicit encryption with the "String" algorithm.

Parameters:

Raises:



1931
1932
1933
1934
1935
1936
1937
1938
1939
 
# File 'lib/mongo/crypt/binding.rb', line 1931

def self.ctx_setopt_algorithm_text(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_text(context.ctx_p, data_p)
    end
  end
end

.ctx_setopt_contention_factor(context, factor) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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:



1854
1855
1856
1857
1858
 
# File 'lib/mongo/crypt/binding.rb', line 1854

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) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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:



498
499
500
501
502
503
504
505
506
507
508
 
# File 'lib/mongo/crypt/binding.rb', line 498

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) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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:



596
597
598
599
600
601
602
603
604
 
# File 'lib/mongo/crypt/binding.rb', line 596

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) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Sets the key id option on an explicit encryption context.

Parameters:

Raises:



465
466
467
468
469
470
471
 
# File 'lib/mongo/crypt/binding.rb', line 465

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) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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:



533
534
535
536
537
538
539
540
 
# File 'lib/mongo/crypt/binding.rb', line 533

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) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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:



1822
1823
1824
1825
1826
 
# File 'lib/mongo/crypt/binding.rb', line 1822

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) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



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

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

.get_binary_len_direct(mongocrypt_binary_t) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



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

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

.init(handle) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Initialize the Mongo::Crypt::Handle object

Parameters:

Raises:



405
406
407
408
409
 
# File 'lib/mongo/crypt/binding.rb', line 405

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

.kms_ctx_bytes_needed(kms_context) ⇒ Integer

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Get the number of bytes needed by the KmsContext.

Parameters:

Returns:

  • (Integer) —

    The number of bytes needed



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

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

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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

Parameters:

Returns:

  • (String | nil) —

    The hostname, or nil if none exists

Raises:



1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
 
# File 'lib/mongo/crypt/binding.rb', line 1038

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

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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

Parameters:

Returns:

  • (true, false) —

    whether the failed request may be retried.



1157
1158
1159
 
# File 'lib/mongo/crypt/binding.rb', line 1157

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

.kms_ctx_feed(kms_context, bytes) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Feed replies from the KMS back to libmongocrypt.

Parameters:

Raises:



1082
1083
1084
1085
1086
1087
1088
 
# File 'lib/mongo/crypt/binding.rb', line 1082

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) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
 
# File 'lib/mongo/crypt/binding.rb', line 969

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

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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

Parameters:

Returns:

  • (String) —

    The HTTP message

Raises:



1009
1010
1011
1012
1013
1014
1015
1016
1017
 
# File 'lib/mongo/crypt/binding.rb', line 1009

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

  binary.to_s
end

.kms_ctx_setopt_retry_kms(handle, value) ⇒ true, fale

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Enable or disable KMS retry behavior.

Parameters:

Returns:

  • (true, fale) —

    true is the option was set, otherwise false.



1176
1177
1178
 
# File 'lib/mongo/crypt/binding.rb', line 1176

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

.kms_ctx_status(kms_context) ⇒ Mongo::Crypt::Status

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Read the status information for the given KmsContext into a Status object without raising.

Parameters:

Returns:



1118
1119
1120
1121
1122
1123
 
# File 'lib/mongo/crypt/binding.rb', line 1118

def self.kms_ctx_status(kms_context)
  status = Status.new

  mongocrypt_kms_ctx_status(kms_context.kms_ctx_p, status.ref)
  status
end

.kms_ctx_usleep(kms_context) ⇒ Integer

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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

Parameters:

Returns:

  • (Integer) —

    A 64-bit encoded number of microseconds to sleep.



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

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

.mongocrypt_binary_data(binary) ⇒ FFI::Pointer

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



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

attach_function :mongocrypt_binary_data, [ :pointer ], :pointer

.mongocrypt_binary_destroy(binary) ⇒ nil

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Destroy the mongocrypt_binary_t object.

Parameters:

  • binary (FFI::Pointer) —

    A pointer to a mongocrypt_binary_t object.

Returns:

  • (nil) —

    Always nil.



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

attach_function :mongocrypt_binary_destroy, [ :pointer ], :void

.mongocrypt_binary_len(binary) ⇒ Integer

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



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

attach_function :mongocrypt_binary_len, [ :pointer ], :int

.mongocrypt_binary_new ⇒ FFI::Pointer

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



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

attach_function :mongocrypt_binary_new, [], :pointer

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

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



157
158
159
160
161
 
# File 'lib/mongo/crypt/binding.rb', line 157

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

.mongocrypt_crypt_shared_lib_version(crypt) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



1622
1623
1624
1625
1626
 
# File 'lib/mongo/crypt/binding.rb', line 1622

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

.mongocrypt_ctx_datakey_init(ctx, filter) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



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

attach_function :mongocrypt_ctx_datakey_init, [ :pointer ], :bool

.mongocrypt_ctx_decrypt_init(ctx, doc) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



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

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

.mongocrypt_ctx_destroy(ctx) ⇒ nil

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



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

attach_function :mongocrypt_ctx_destroy, [ :pointer ], :void

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

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



676
677
678
679
680
 
# File 'lib/mongo/crypt/binding.rb', line 676

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

.mongocrypt_ctx_explicit_decrypt_init(ctx, msg) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



802
803
804
805
806
 
# File 'lib/mongo/crypt/binding.rb', line 802

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

.mongocrypt_ctx_explicit_encrypt_init(ctx, msg) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



712
713
714
715
716
 
# File 'lib/mongo/crypt/binding.rb', line 712

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

.mongocrypt_ctx_finalize(ctx, op_bson) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



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

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

.mongocrypt_ctx_mongo_db(ctx) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



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

attach_function :mongocrypt_ctx_mongo_db, [ :pointer ], :string

.mongocrypt_ctx_mongo_done(ctx) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



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

attach_function :mongocrypt_ctx_mongo_done, [ :pointer ], :bool

.mongocrypt_ctx_mongo_feed(ctx, reply) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



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

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

.mongocrypt_ctx_mongo_next_kms_ctx(ctx) ⇒ FFI::Pointer

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



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

attach_function :mongocrypt_ctx_next_kms_ctx, [ :pointer ], :pointer

.mongocrypt_ctx_mongo_op(ctx, op_bson) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



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

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

.mongocrypt_ctx_new(crypt) ⇒ FFI::Pointer

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



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

attach_function :mongocrypt_ctx_new, [ :pointer ], :pointer

.mongocrypt_ctx_provide_kms_providers(ctx, kms_providers) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



1767
1768
1769
1770
1771
 
# File 'lib/mongo/crypt/binding.rb', line 1767

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

.mongocrypt_ctx_setopt_algorithm(ctx, algorithm, len) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



553
554
555
556
557
 
# File 'lib/mongo/crypt/binding.rb', line 553

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

.mongocrypt_ctx_setopt_algorithm_range(ctx, opts) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



1873
1874
1875
1876
1877
1878
1879
1880
 
# File 'lib/mongo/crypt/binding.rb', line 1873

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

.mongocrypt_ctx_setopt_algorithm_text(ctx, opts) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



1916
1917
1918
1919
1920
1921
1922
1923
 
# File 'lib/mongo/crypt/binding.rb', line 1916

attach_function(
  :mongocrypt_ctx_setopt_algorithm_text,
  %i[
    pointer
    pointer
  ],
  :bool
)

.mongocrypt_ctx_setopt_contention_factor(ctx, contention_factor) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



1838
1839
1840
1841
1842
1843
1844
1845
 
# File 'lib/mongo/crypt/binding.rb', line 1838

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

.mongocrypt_ctx_setopt_key_alt_name(ctx, binary) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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": }.

Returns:

  • (Boolean) —

    Whether the alternative name was successfully set.



485
486
487
488
489
 
# File 'lib/mongo/crypt/binding.rb', line 485

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

.mongocrypt_ctx_setopt_key_encryption_key(ctx) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



583
584
585
586
587
 
# File 'lib/mongo/crypt/binding.rb', line 583

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

.mongocrypt_ctx_setopt_key_id(ctx, key_id) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



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

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

.mongocrypt_ctx_setopt_key_material(ctx, binary) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



520
521
522
523
524
 
# File 'lib/mongo/crypt/binding.rb', line 520

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

.mongocrypt_ctx_setopt_query_type(ctx, mongocrypt_query_type) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



1805
1806
1807
1808
1809
1810
1811
1812
1813
 
# File 'lib/mongo/crypt/binding.rb', line 1805

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

.mongocrypt_ctx_state(ctx) ⇒ Symbol

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



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

attach_function :mongocrypt_ctx_state, [ :pointer ], :mongocrypt_ctx_state

.mongocrypt_ctx_status(ctx, status) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



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

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

.mongocrypt_destroy(crypt) ⇒ nil

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Destroy the reference the mongocrypt_t object.

Parameters:

  • crypt (FFI::Pointer) —

    A pointer to a mongocrypt_t object.

Returns:

  • (nil) —

    Always nil.



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

attach_function :mongocrypt_destroy, [ :pointer ], :void

.mongocrypt_init(crypt) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



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

attach_function :mongocrypt_init, [ :pointer ], :bool

.mongocrypt_kms_ctx_bytes_needed(kms) ⇒ Integer

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



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

attach_function :mongocrypt_kms_ctx_bytes_needed, [ :pointer ], :int

.mongocrypt_kms_ctx_done(ctx) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



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

attach_function :mongocrypt_ctx_kms_done, [ :pointer ], :bool

.mongocrypt_kms_ctx_endpoint(kms, endpoint) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



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

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

.mongocrypt_kms_ctx_fail(ctx) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



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

attach_function :mongocrypt_kms_ctx_fail, [ :pointer ], :bool

.mongocrypt_kms_ctx_feed(kms, bytes) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



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

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

.mongocrypt_kms_ctx_get_kms_provider(crypt, kms_providers) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



954
955
956
957
958
 
# File 'lib/mongo/crypt/binding.rb', line 954

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

.mongocrypt_kms_ctx_message(kms, msg) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



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

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

.mongocrypt_kms_ctx_status(kms, status) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



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

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

.mongocrypt_kms_ctx_usleep(ctx) ⇒ int64

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



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

attach_function :mongocrypt_kms_ctx_usleep, [ :pointer ], :int64

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

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
 
# File 'lib/mongo/crypt/binding.rb', line 1518

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

.mongocrypt_setopt_append_crypt_shared_lib_search_path(crypt, path) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



1555
1556
1557
1558
1559
1560
1561
1562
 
# File 'lib/mongo/crypt/binding.rb', line 1555

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

.mongocrypt_setopt_bypass_query_analysis(crypt) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



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

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

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



1386
1387
1388
1389
1390
1391
1392
1393
1394
 
# File 'lib/mongo/crypt/binding.rb', line 1386

attach_function(
  :mongocrypt_setopt_crypto_hook_sign_rsaes_pkcs1_v1_5,
  %i[
    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

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
 
# File 'lib/mongo/crypt/binding.rb', line 1341

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

.mongocrypt_setopt_enable_multiple_collinfo(crypt) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



1693
1694
1695
1696
1697
 
# File 'lib/mongo/crypt/binding.rb', line 1693

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

.mongocrypt_setopt_encrypted_field_config_map(crypt, efc_map) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



1428
1429
1430
1431
1432
1433
1434
1435
 
# File 'lib/mongo/crypt/binding.rb', line 1428

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

.mongocrypt_setopt_key_expiration(crypt, cache_expiration_ms) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Set the expiration time for the data encryption key cache.

Parameters:

  • crypt (FFI::Pointer) —

    A pointer to a mongocrypt_t object.

  • cache_expiration_ms (Integer) —

    The cache expiration time in milliseconds. If zero, the cache never expires.

Returns:

  • (Boolean) —

    Returns whether the option was set successfully.



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

attach_function(:mongocrypt_setopt_key_expiration, %i[pointer uint64], :bool)

.mongocrypt_setopt_kms_providers(crypt, kms_providers) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



342
343
344
345
346
 
# File 'lib/mongo/crypt/binding.rb', line 342

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

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

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



313
314
315
316
317
 
# File 'lib/mongo/crypt/binding.rb', line 313

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

.mongocrypt_setopt_retry_kms(crypt, enable) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



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

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

.mongocrypt_setopt_schema_map(crypt, schema_map) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



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

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

.mongocrypt_setopt_set_crypt_shared_lib_path_override(crypt, path) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



1584
1585
1586
1587
1588
1589
1590
1591
 
# File 'lib/mongo/crypt/binding.rb', line 1584

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

.mongocrypt_setopt_use_need_kms_credentials_state(crypt) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



1663
1664
1665
1666
1667
 
# File 'lib/mongo/crypt/binding.rb', line 1663

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

.mongocrypt_setopt_use_need_mongo_collinfo_with_db_state(crypt) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



1717
1718
1719
1720
1721
 
# File 'lib/mongo/crypt/binding.rb', line 1717

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

.mongocrypt_status(crypt, status) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



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

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

.mongocrypt_status_code(status) ⇒ Integer

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Return the status error code.

Parameters:

  • status (FFI::Pointer) —

    A pointer to a mongocrypt_status_t.

Returns:

  • (Integer) —

    The status code.



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

attach_function :mongocrypt_status_code, [ :pointer ], :int

.mongocrypt_status_destroy(status) ⇒ nil

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Destroys the reference to the mongocrypt_status_t object.

Parameters:

  • status (FFI::Pointer) —

    A pointer to a mongocrypt_status_t.

Returns:

  • (nil) —

    Always nil.



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

attach_function :mongocrypt_status_destroy, [ :pointer ], :void

.mongocrypt_status_message(status, len = nil) ⇒ String

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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 return string will be written.

Returns:

  • (String) —

    The status message.



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

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

.mongocrypt_status_new ⇒ FFI::Pointer

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Create a new mongocrypt_status_t object.

Returns:

  • (FFI::Pointer) —

    A pointer to the new mongocrypt_status_ts.



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

attach_function :mongocrypt_status_new, [], :pointer

.mongocrypt_status_ok(status) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



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

attach_function :mongocrypt_status_ok, [ :pointer ], :bool

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

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



221
222
223
224
225
 
# File 'lib/mongo/crypt/binding.rb', line 221

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

.mongocrypt_status_type(status) ⇒ Symbol

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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



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

attach_function :mongocrypt_status_type, [ :pointer ], :status_type

.mongocrypt_version(len) ⇒ String

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



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

attach_function :mongocrypt_version, [ :pointer ], :string

.ongocrypt_new ⇒ FFI::Pointer

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Creates a new mongocrypt_t object.

Returns:

  • (FFI::Pointer) —

    A pointer to a new mongocrypt_t object.



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

attach_function :mongocrypt_new, [], :pointer

.parse_version(version) ⇒ Gem::Version

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



106
107
108
109
110
111
112
113
114
115
116
117
118
119
 
# File 'lib/mongo/crypt/binding.rb', line 106

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) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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:



1536
1537
1538
1539
1540
1541
 
# File 'lib/mongo/crypt/binding.rb', line 1536

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) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Append an additional search directory to the search path for loading the crypt_shared dynamic library.

Parameters:



1569
1570
1571
1572
1573
 
# File 'lib/mongo/crypt/binding.rb', line 1569

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) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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:



1478
1479
1480
 
# File 'lib/mongo/crypt/binding.rb', line 1478

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) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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:



1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
 
# File 'lib/mongo/crypt/binding.rb', line 1403

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) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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:



1367
1368
1369
1370
1371
1372
1373
1374
1375
 
# File 'lib/mongo/crypt/binding.rb', line 1367

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_enable_multiple_collinfo(handle) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Enable support for multiple collection schemas. Required to support $lookup.

Parameters:

Returns:

  • (Boolean) —

    Whether the option was set successfully.



1703
1704
1705
1706
1707
 
# File 'lib/mongo/crypt/binding.rb', line 1703

def self.setopt_enable_multiple_collinfo(handle)
  check_status(handle) do
    mongocrypt_setopt_enable_multiple_collinfo(handle.ref)
  end
end

.setopt_encrypted_field_config_map(handle, efc_map) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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:



1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
 
# File 'lib/mongo/crypt/binding.rb', line 1446

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_key_expiration(handle, cache_expiration_ms) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Set the expiration time for the data encryption key cache on the Mongo::Crypt::Handle object.

Parameters:

  • handle (Mongo::Crypt::Handle)
  • cache_expiration_ms (Integer) —

    The cache expiration time in milliseconds. If zero, the cache never expires.

Raises:



1501
1502
1503
1504
1505
 
# File 'lib/mongo/crypt/binding.rb', line 1501

def self.setopt_key_expiration(handle, cache_expiration_ms)
  check_status(handle) do
    mongocrypt_setopt_key_expiration(handle.ref, cache_expiration_ms)
  end
end

.setopt_kms_providers(handle, kms_providers) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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:



355
356
357
358
359
360
361
362
363
 
# File 'lib/mongo/crypt/binding.rb', line 355

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) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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

Parameters:

Raises:



325
326
327
328
329
 
# File 'lib/mongo/crypt/binding.rb', line 325

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) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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:



382
383
384
385
386
387
388
389
390
 
# File 'lib/mongo/crypt/binding.rb', line 382

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) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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

Parameters:



1597
1598
1599
1600
1601
 
# File 'lib/mongo/crypt/binding.rb', line 1597

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) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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:



1681
1682
1683
 
# File 'lib/mongo/crypt/binding.rb', line 1681

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

.setopt_use_need_mongo_collinfo_with_db_state(handle) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Opt into handling the MONGOCRYPT_CTX_NEED_MONGO_COLLINFO_WITH_DB state.

Parameters:



1726
1727
1728
 
# File 'lib/mongo/crypt/binding.rb', line 1726

def self.setopt_use_need_mongo_collinfo_with_db_state(handle)
  mongocrypt_setopt_use_need_mongo_collinfo_with_db_state(handle.ref)
end

.validate_document(data) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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:



1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
 
# File 'lib/mongo/crypt/binding.rb', line 1981

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

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

  raise Error::CryptError.new(message)
end

.validate_version(lmc_version) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



129
130
131
132
133
134
 
# File 'lib/mongo/crypt/binding.rb', line 129

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

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



1259
1260
1261
1262
1263
 
# File 'lib/mongo/crypt/binding.rb', line 1259

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

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

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



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

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

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

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



1284
1285
1286
1287
1288
 
# File 'lib/mongo/crypt/binding.rb', line 1284

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

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

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



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

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

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

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



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

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