Class: Mongo::Crypt::Context Private

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Defined in:
lib/mongo/crypt/context.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 wrapper around mongocrypt_ctx_t, which manages the state machine for encryption and decription.

This class is a superclass that defines shared methods amongst contexts that are initialized for different purposes (e.g. data key creation, encryption, explicit encryption, etc.)

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(mongocrypt_handle, io) ⇒ Context

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 Context object

Parameters:

  • mongocrypt_handle (Mongo::Crypt::Handle) —

    A handle to libmongocrypt used to create a new context object.

  • io (ClientEncryption::IO) —

    An instance of the IO class that implements driver I/O methods required to run the state machine.



41
42
43
44
45
46
47
48
49
50
51
52
53
54
 
# File 'lib/mongo/crypt/context.rb', line 41

def initialize(mongocrypt_handle, io)
  @mongocrypt_handle = mongocrypt_handle
  # Ideally, this level of the API wouldn't be passing around pointer
  # references between objects, so this method signature is subject to change.

  # FFI::AutoPointer uses a custom release strategy to automatically free
  # the pointer once this object goes out of scope
  @ctx_p = FFI::AutoPointer.new(
    Binding.mongocrypt_ctx_new(@mongocrypt_handle.ref),
    Binding.method(:mongocrypt_ctx_destroy)
  )
  @encryption_io = io
  @cached_azure_token = nil
end

Instance Attribute Details

#ctx_p ⇒ Object (readonly)

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. 



56
57
58
 
# File 'lib/mongo/crypt/context.rb', line 56

def ctx_p
  @ctx_p
end

Instance Method Details

#run_state_machine(timeout_holder) ⇒ 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.

Runs the mongocrypt_ctx_t state machine and handles all I/O on behalf of

This method is not currently unit tested. It is integration tested in spec/integration/explicit_encryption_spec.rb

Parameters:

Returns:

  • (BSON::Document) —

    A BSON document representing the outcome of the state machine. Contents can differ depending on how the context was initialized..

Raises:



80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
 
# File 'lib/mongo/crypt/context.rb', line 80

def run_state_machine(timeout_holder)
  while true
    timeout_ms = timeout_holder.remaining_timeout_ms!
    case state
    when :error
      Binding.check_ctx_status(self)
    when :ready
      # Finalize the state machine and return the result as a BSON::Document
      return Binding.ctx_finalize(self)
    when :done
      return nil
    when :need_mongo_keys
      provide_keys(timeout_ms)
    when :need_mongo_collinfo
      provide_collection_info(timeout_ms)
    when :need_mongo_markings
      provide_markings(timeout_ms)
    when :need_kms
      feed_kms
    when :need_kms_credentials
      Binding.ctx_provide_kms_providers(
        self,
        retrieve_kms_credentials(timeout_holder).to_document
      )
    else
      raise Error::CryptError.new(
        "State #{state} is not supported by Mongo::Crypt::Context"
      )
    end
  end
end

#state ⇒ 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.

Returns the state of the mongocrypt_ctx_t

Returns:

  • (Symbol) —

    The context state



61
62
63
 
# File 'lib/mongo/crypt/context.rb', line 61

def state
  Binding.mongocrypt_ctx_state(@ctx_p)
end