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

API:

  • private

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.

API:

  • private

Gem::Version.new("1.7.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:

  • Always nil.

API:

  • private



1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
 
# File 'lib/mongo/crypt/binding.rb', line 1757

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

  • If the provided block returns false

API:

  • private



1099
1100
1101
1102
1103
1104
1105
1106
 
# File 'lib/mongo/crypt/binding.rb', line 1099

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

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:

  • Always nil.

API:

  • private



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

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

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:

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

API:

  • private



1550
1551
1552
 
# File 'lib/mongo/crypt/binding.rb', line 1550

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:

  • If initialization fails

API:

  • private



617
618
619
620
621
 
# File 'lib/mongo/crypt/binding.rb', line 617

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:

  • A BSON document to decrypt

Raises:

  • If initialization fails

API:

  • private



778
779
780
781
782
783
784
785
786
 
# File 'lib/mongo/crypt/binding.rb', line 778

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:

  • The name of the database against which the encrypted command is being performed

  • The command to be encrypted

Raises:

  • If initialization fails

API:

  • private



684
685
686
687
688
689
690
691
692
 
# File 'lib/mongo/crypt/binding.rb', line 684

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:

  • A BSON document to decrypt

Raises:

  • If initialization fails

API:

  • private



808
809
810
811
812
813
814
815
816
 
# File 'lib/mongo/crypt/binding.rb', line 808

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:

  • A BSON document to encrypt

Raises:

  • If initialization fails

API:

  • private



752
753
754
755
756
757
758
759
760
 
# File 'lib/mongo/crypt/binding.rb', line 752

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:

  • A BSON document to encrypt

Raises:

  • If initialization fails

API:

  • private



718
719
720
721
722
723
724
725
726
 
# File 'lib/mongo/crypt/binding.rb', line 718

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:

  • If the state machine is not successfully finalized

API:

  • private



1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
 
# File 'lib/mongo/crypt/binding.rb', line 1145

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

  • If the operation is unsuccessful

API:

  • private



1122
1123
1124
1125
1126
 
# File 'lib/mongo/crypt/binding.rb', line 1122

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

  • The document representing the response

Raises:

  • If the response is not fed successfully

API:

  • private



889
890
891
892
893
894
895
896
897
 
# File 'lib/mongo/crypt/binding.rb', line 889

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:

  • The operation that the driver must perform

Raises:

  • If there is an error getting the operation

API:

  • private



860
861
862
863
864
865
866
867
868
869
870
871
 
# File 'lib/mongo/crypt/binding.rb', line 860

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:

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

API:

  • private



921
922
923
924
925
926
927
928
929
 
# File 'lib/mongo/crypt/binding.rb', line 921

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:

  • Encryption context.

  • BSON document mapping the KMS provider names to credentials.

Raises:

  • If the option is not set successfully.

API:

  • private



1623
1624
1625
1626
1627
1628
1629
1630
1631
 
# File 'lib/mongo/crypt/binding.rb', line 1623

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:

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

Returns:

  • Whether the initialization was successful.

API:

  • private



648
649
650
651
652
653
654
655
 
# File 'lib/mongo/crypt/binding.rb', line 648

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:

  • The algorithm name. Valid values are:

    • “AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic”

    • “AEAD_AES_256_CBC_HMAC_SHA_512-Random”

Raises:

  • If the operation failed

API:

  • private



561
562
563
564
565
 
# File 'lib/mongo/crypt/binding.rb', line 561

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 RangePreview algorithm is experimental only. It is not intended for

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

public use.

Parameters:

  • options

Raises:

  • If the operation failed

API:

  • private



1730
1731
1732
1733
1734
1735
1736
1737
1738
 
# File 'lib/mongo/crypt/binding.rb', line 1730

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

  • Explicit encryption context.

  • Contention factor used for explicit encryption.

Raises:

  • If the operation failed.

API:

  • private



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

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:

  • A DataKeyContext

  • An array of alternate key names as strings

Raises:

  • If any of the alternate names are not valid UTF8 strings

API:

  • private



492
493
494
495
496
497
498
499
500
501
502
 
# File 'lib/mongo/crypt/binding.rb', line 492

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:

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

Raises:

  • If the operation failed

API:

  • private



590
591
592
593
594
595
596
597
598
 
# File 'lib/mongo/crypt/binding.rb', line 590

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:

  • Explicit encryption context

  • The key id

Raises:

  • If the operation failed

API:

  • private



459
460
461
462
463
464
465
 
# File 'lib/mongo/crypt/binding.rb', line 459

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:

  • A DataKeyContext

  • 96 bytes of custom key material

Raises:

  • If the key material is not 96 bytes.

API:

  • private



527
528
529
530
531
532
533
534
 
# File 'lib/mongo/crypt/binding.rb', line 527

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:

  • Explicit encryption context.

  • query_type Type of the query.

Raises:

  • If the operation failed.

API:

  • private



1661
1662
1663
1664
1665
 
# File 'lib/mongo/crypt/binding.rb', line 1661

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

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

  • If initialization fails

API:

  • private



399
400
401
402
403
 
# File 'lib/mongo/crypt/binding.rb', line 399

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:

  • The number of bytes needed

API:

  • private



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

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:

  • The hostname, or nil if none exists

Raises:

  • If the response is not fed successfully

API:

  • private



1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
 
# File 'lib/mongo/crypt/binding.rb', line 1031

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_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:

  • The data to feed to libmongocrypt

Raises:

  • If the response is not fed successfully

API:

  • private



1075
1076
1077
1078
1079
1080
1081
 
# File 'lib/mongo/crypt/binding.rb', line 1075

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:

  • Pointer mongocrypt_kms_ctx_t object.

API:

  • private



962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
 
# File 'lib/mongo/crypt/binding.rb', line 962

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:

  • The HTTP message

Raises:

  • If the response is not fed successfully

API:

  • private



1002
1003
1004
1005
1006
1007
1008
1009
1010
 
# File 'lib/mongo/crypt/binding.rb', line 1002

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

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

  • A pointer to a mongocrypt_binary_t object.

Returns:

  • A pointer to the data array.

API:

  • private



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

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:

  • A pointer to a mongocrypt_binary_t object.

Returns:

  • Always nil.

API:

  • private



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

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:

  • A pointer to a mongocrypt_binary_t object.

Returns:

  • The length of the data array.

API:

  • private



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

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:

  • A pointer to the newly-created mongocrypt_binary_t object.

API:

  • private



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

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:

  • A pointer to an array of bytes; the data is not copied and must outlive the mongocrypt_binary_t object.

  • The length of the array argument.

Returns:

  • A pointer to the newly-created mongocrypt_binary_t object.

API:

  • private



159
160
161
162
163
 
# File 'lib/mongo/crypt/binding.rb', line 159

attach_function(
  :mongocrypt_binary_new_from_data,
  [: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.

API:

  • private



1528
1529
1530
1531
1532
 
# File 'lib/mongo/crypt/binding.rb', line 1528

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.

API:

  • private



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

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:

  • A pointer to a mongocrypt_ctx_t object.

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

Returns:

  • Whether the initialization was successful.

API:

  • private



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

attach_function :mongocrypt_ctx_decrypt_init, [: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:

  • A pointer to a mongocrypt_ctx_t object.

Returns:

  • Always nil.

API:

  • private



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

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:

  • A pointer to a mongocrypt_ctx_t object.

  • The database name.

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

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

Returns:

  • Whether the initialization was successful.

API:

  • private



670
671
672
673
674
 
# File 'lib/mongo/crypt/binding.rb', line 670

attach_function(
  :mongocrypt_ctx_encrypt_init,
  [: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:

  • A pointer to a mongocrypt_ctx_t object.

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

Returns:

  • Whether the initialization was successful.

API:

  • private



796
797
798
799
800
 
# File 'lib/mongo/crypt/binding.rb', line 796

attach_function(
  :mongocrypt_ctx_explicit_decrypt_init,
  [: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:

  • A pointer to a mongocrypt_ctx_t object.

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

Returns:

  • Whether the initialization was successful.

API:

  • private



706
707
708
709
710
 
# File 'lib/mongo/crypt/binding.rb', line 706

attach_function(
  :mongocrypt_ctx_explicit_encrypt_init,
  [: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:

  • A pointer to a mongocrypt_ctx_t object.

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

Returns:

  • A boolean indicating the success of the operation.

API:

  • private



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

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

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

  • A pointer to a mongocrypt_ctx_t object.

Returns:

  • A boolean indicating the success of the operation.

API:

  • private



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

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:

  • A pointer to a mongocrypt_ctx_t object.

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

Returns:

  • A boolean indicating the success of the operation.

API:

  • private



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

attach_function :mongocrypt_ctx_mongo_feed, [: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:

  • A pointer to a mongocrypt_ctx_t object.

Returns:

  • A pointer to a mongocrypt_kms_ctx_t object.

API:

  • private



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

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:

  • A pointer to a mongocrypt_ctx_t object.

  • (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:

  • A boolean indicating the success of the operation.

API:

  • private



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

attach_function :mongocrypt_ctx_mongo_op, [: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:

  • A pointer to a mongocrypt_t object.

Returns:

  • A new mongocrypt_ctx_t object.

API:

  • private



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

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.

API:

  • private



1606
1607
1608
1609
1610
 
# File 'lib/mongo/crypt/binding.rb', line 1606

attach_function(
  :mongocrypt_ctx_provide_kms_providers,
  [ :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:

  • A pointer to a mongocrypt_ctx_t object.

  • The algorithm name. Valid values are:

    • “AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic”

    • “AEAD_AES_256_CBC_HMAC_SHA_512-Random”

  • The length of the algorithm string.

Returns:

  • Whether the option was successfully set.

API:

  • private



547
548
549
550
551
 
# File 'lib/mongo/crypt/binding.rb', line 547

attach_function(
  :mongocrypt_ctx_setopt_algorithm,
  [: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.

API:

  • private



1712
1713
1714
1715
1716
1717
1718
1719
 
# File 'lib/mongo/crypt/binding.rb', line 1712

attach_function(
  :mongocrypt_ctx_setopt_algorithm_range,
  [
    :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.

API:

  • private



1677
1678
1679
1680
1681
1682
1683
1684
 
# File 'lib/mongo/crypt/binding.rb', line 1677

attach_function(
  :mongocrypt_ctx_setopt_contention_factor,
  [
    :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:

  • A pointer to a mongocrypt_ctx_t object.

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

Returns:

  • Whether the alternative name was successfully set.

API:

  • private



479
480
481
482
483
 
# File 'lib/mongo/crypt/binding.rb', line 479

attach_function(
  :mongocrypt_ctx_setopt_key_alt_name,
  [: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:

  • A pointer to a mongocrypt_ctx_t object.

  • 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:

  • Whether the option was successfully set.

API:

  • private



577
578
579
580
581
 
# File 'lib/mongo/crypt/binding.rb', line 577

attach_function(
  :mongocrypt_ctx_setopt_key_encryption_key,
  [: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:

  • A pointer to a mongocrypt_ctx_t object.

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

Returns:

  • Whether the option was successfully set.

API:

  • private



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

attach_function :mongocrypt_ctx_setopt_key_id, [: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:

  • A pointer to a mongocrypt_ctx_t object.

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

Returns:

  • Whether the custom key material was successfully set.

API:

  • private



514
515
516
517
518
 
# File 'lib/mongo/crypt/binding.rb', line 514

attach_function(
  :mongocrypt_ctx_setopt_key_material,
  [: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.

API:

  • private



1644
1645
1646
1647
1648
1649
1650
1651
1652
 
# File 'lib/mongo/crypt/binding.rb', line 1644

attach_function(
  :mongocrypt_ctx_setopt_query_type,
  [
    :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:

  • A pointer to a mongocrypt_ctx_t object.

Returns:

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

API:

  • private



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

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:

  • A pointer to a mongocrypt_ctx_t object.

  • A pointer to a mongocrypt_status_t object.

Returns:

  • Whether the status was successfully set.

API:

  • private



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

attach_function :mongocrypt_ctx_status, [: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:

  • A pointer to a mongocrypt_t object.

Returns:

  • Always nil.

API:

  • private



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

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:

  • A pointer to a mongocrypt_t object.

Returns:

  • Returns whether the crypt was initialized successfully.

API:

  • private



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

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:

  • The mongocrypt_kms_ctx_t object.

Returns:

  • The number of bytes needed.

API:

  • private



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

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:

  • A pointer to a mongocrypt_ctx_t object.

Returns:

  • Whether the operation was successful.

API:

  • private



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

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:

  • A pointer to a mongocrypt_kms_ctx_t object.

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

Returns:

  • Whether the operation was successful.

API:

  • private



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

attach_function :mongocrypt_kms_ctx_endpoint, [:pointer, :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:

  • A pointer to the mongocrypt_kms_ctx_t object.

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

Returns:

  • Whether the operation was successful.

API:

  • private



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

attach_function :mongocrypt_kms_ctx_feed, [: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.

API:

  • private



947
948
949
950
951
 
# File 'lib/mongo/crypt/binding.rb', line 947

attach_function(
  :mongocrypt_kms_ctx_get_kms_provider,
  [: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:

  • Pointer to the mongocrypt_kms_ctx_t object

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

Returns:

  • Whether the operation is successful.

API:

  • private



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

attach_function :mongocrypt_kms_ctx_message, [: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:

  • A pointer to the mongocrypt_kms_ctx_t object.

  • A pointer to a mongocrypt_status_t object.

Returns:

  • Whether the operation was successful.

API:

  • private



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

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

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

  • A pointer to a mongocrypt_t object.

  • An AES-CTR encryption method.

  • An AES-CTR decryption method.

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

Returns:

  • Whether setting this option succeeded.

API:

  • private



1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
 
# File 'lib/mongo/crypt/binding.rb', line 1423

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

API:

  • private



1461
1462
1463
1464
1465
1466
1467
1468
 
# File 'lib/mongo/crypt/binding.rb', line 1461

attach_function(
  :mongocrypt_setopt_append_crypt_shared_lib_search_path,
  [
    :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.

API:

  • private



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

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:

  • A pointer to a mongocrypt_t object.

  • A RSASSA-PKCS1-v1_5 signing method.

  • (defaults to: nil)

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

Returns:

  • Whether setting this option succeeded.

API:

  • private



1316
1317
1318
1319
1320
1321
1322
1323
1324
 
# File 'lib/mongo/crypt/binding.rb', line 1316

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

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:

  • A pointer to a mongocrypt_t object.

  • An AES encryption method.

  • An AES decryption method.

  • A random method.

  • A HMAC SHA-512 method.

  • A HMAC SHA-256 method.

  • A SHA-256 hash method.

  • (defaults to: nil)

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

Returns:

  • Whether setting this option succeeded.

API:

  • private



1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
 
# File 'lib/mongo/crypt/binding.rb', line 1269

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

API:

  • private



1358
1359
1360
1361
1362
1363
1364
1365
 
# File 'lib/mongo/crypt/binding.rb', line 1358

attach_function(
  :mongocrypt_setopt_encrypted_field_config_map,
  [
    :pointer,
    :pointer
  ],
  :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:

  • A pointer to a mongocrypt_t object.

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

API:

  • private



336
337
338
339
340
 
# File 'lib/mongo/crypt/binding.rb', line 336

attach_function(
  :mongocrypt_setopt_kms_providers,
  [: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:

  • A pointer to a mongocrypt_t object.

  • A logging callback method.

  • (defaults to: nil)

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

Returns:

  • Whether setting the callback was successful.

API:

  • private



307
308
309
310
311
 
# File 'lib/mongo/crypt/binding.rb', line 307

attach_function(
  :mongocrypt_setopt_log_handler,
  [:pointer, :mongocrypt_log_fn_t, :pointer],
  :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:

  • A pointer to a mongocrypt_t object.

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

Returns:

  • Returns whether the option was set successfully.

API:

  • private



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

attach_function :mongocrypt_setopt_schema_map, [: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.

API:

  • private



1490
1491
1492
1493
1494
1495
1496
1497
 
# File 'lib/mongo/crypt/binding.rb', line 1490

attach_function(
  :mongocrypt_setopt_set_crypt_shared_lib_path_override,
  [
    :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.

API:

  • private



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

attach_function(
  :mongocrypt_setopt_use_need_kms_credentials_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:

  • A pointer to a mongocrypt_t object.

  • A pointer to a mongocrypt_status_t object.

Returns:

  • Whether the status was successfully set.

API:

  • private



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

attach_function :mongocrypt_status, [: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:

  • A pointer to a mongocrypt_status_t.

Returns:

  • The status code.

API:

  • private



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

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:

  • A pointer to a mongocrypt_status_t.

Returns:

  • Always nil.

API:

  • private



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

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:

  • A pointer to a mongocrypt_status_t.

  • (defaults to: nil)

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

Returns:

  • The status message.

API:

  • private



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

attach_function :mongocrypt_status_message, [: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:

  • A pointer to the new mongocrypt_status_ts.

API:

  • private



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

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:

  • A pointer to a mongocrypt_status_t.

Returns:

  • Whether the status is ok.

API:

  • private



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

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:

  • A pointer to a mongocrypt_status_t.

  • The status type; possible values are defined by the status_type enum.

  • The status code.

  • The status message.

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

Returns:

  • Always nil.

API:

  • private



215
216
217
218
219
 
# File 'lib/mongo/crypt/binding.rb', line 215

attach_function(
  :mongocrypt_status_set,
  [: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:

  • A pointer to a mongocrypt_status_t.

Returns:

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

API:

  • private



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

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:

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

Returns:

  • A version string for libmongocrypt.

API:

  • private



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

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:

  • A pointer to a new mongocrypt_t object.

API:

  • private



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

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:

  • String representing a version number.

Returns:

  • the version number

Raises:

  • if the string cannot be parsed.

API:

  • private



108
109
110
111
112
113
114
115
116
117
118
119
120
121
 
# 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) ⇒ 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:

  • An AES-CTR encryption method

  • A AES-CTR decryption method

Raises:

  • If the callbacks aren’t set successfully

API:

  • private



1441
1442
1443
1444
1445
1446
1447
 
# File 'lib/mongo/crypt/binding.rb', line 1441

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:

  • A search path for the crypt shared library.

API:

  • private



1475
1476
1477
1478
1479
 
# File 'lib/mongo/crypt/binding.rb', line 1475

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:

API:

  • private



1408
1409
1410
 
# File 'lib/mongo/crypt/binding.rb', line 1408

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:

  • A RSASSA-PKCS1-v1_5 signing method.

Raises:

  • If the callbacks aren’t set successfully

API:

  • private



1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
 
# File 'lib/mongo/crypt/binding.rb', line 1333

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:

  • An AES encryption method

  • A AES decryption method

  • A method that returns a string of random bytes

  • A HMAC SHA-512 method

  • A HMAC SHA-256 method

  • A SHA-256 hash method

Raises:

  • If the callbacks aren’t set successfully

API:

  • private



1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
 
# File 'lib/mongo/crypt/binding.rb', line 1295

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

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

Raises:

  • If the operation failed.

API:

  • private



1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
 
# File 'lib/mongo/crypt/binding.rb', line 1376

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

  • BSON document mapping the KMS provider names to credentials.

Raises:

  • If the option is not set successfully

API:

  • private



349
350
351
352
353
354
355
356
357
 
# File 'lib/mongo/crypt/binding.rb', line 349

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:

  • If the callback is not set successfully

API:

  • private



319
320
321
322
323
 
# File 'lib/mongo/crypt/binding.rb', line 319

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:

  • The schema map as a BSON::Document object

Raises:

  • If the schema map is not set successfully

API:

  • private



376
377
378
379
380
381
382
383
384
 
# File 'lib/mongo/crypt/binding.rb', line 376

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:

  • A path to crypt shared library file.

API:

  • private



1503
1504
1505
1506
1507
 
# File 'lib/mongo/crypt/binding.rb', line 1503

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:

API:

  • private



1587
1588
1589
 
# File 'lib/mongo/crypt/binding.rb', line 1587

def self.setopt_use_need_kms_credentials_state(handle)
  mongocrypt_setopt_use_need_kms_credentials_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:

  • The data to be passed to libmongocrypt

Raises:

  • If the data is not a Hash

API:

  • private



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

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

  • String representing libmongocrypt version.

Raises:

  • if given version is lesser than minimum required version.

API:

  • private



131
132
133
134
135
136
 
# 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

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:

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

  • A pointer to a mongocrypt_binary_t object that references the 32-byte AES encryption key.

  • A pointer to a mongocrypt_binary_t object that references the 16-byte AES IV.

  • A pointer to a mongocrypt_binary_t object that references the value to be encrypted/decrypted.

  • (out param) A pointer to a mongocrypt_binary_t object will have a reference to the encrypted/ decrypted value written to it by libmongocrypt.

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

Returns:

  • Whether encryption/decryption was successful.

API:

  • private



1187
1188
1189
1190
1191
 
# File 'lib/mongo/crypt/binding.rb', line 1187

callback(
  :mongocrypt_crypto_fn,
  [: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:

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

  • A pointer to a mongocrypt_binary_t object that references the value to be hashed.

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

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

Returns:

  • Whether hashing was successful.

API:

  • private



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

callback :mongocrypt_hash_fn, [: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:

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

  • A pointer to a mongocrypt_binary_t object that references the 32-byte HMAC SHA encryption key.

  • A pointer to a mongocrypt_binary_t object that references the input value.

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

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

Returns:

  • Whether HMAC-SHA was successful.

API:

  • private



1212
1213
1214
1215
1216
 
# File 'lib/mongo/crypt/binding.rb', line 1212

callback(
  :mongocrypt_hmac_fn,
  [: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:

  • The log level; possible values defined by the log_level enum

  • The log message

  • The length of the message param, or -1 if the string is null terminated

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

Returns:

  • Always nil.

API:

  • private



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

callback :mongocrypt_log_fn_t, [: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:

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

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

  • The number of random bytes to return.

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

Returns:

  • Whether hashing was successful.

API:

  • private



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

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