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
55
 
# 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. 



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

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:



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
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
 
# File 'lib/mongo/crypt/context.rb', line 81

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
      filter = Binding.ctx_mongo_op(self)

      @encryption_io.find_keys(filter, timeout_ms: timeout_ms).each do |key|
        mongocrypt_feed(key) if key
      end

      mongocrypt_done
    when :need_mongo_collinfo
      filter = Binding.ctx_mongo_op(self)

      result = @encryption_io.collection_info(@db_name, filter, timeout_ms: timeout_ms)
      mongocrypt_feed(result) if result

      mongocrypt_done
    when :need_mongo_markings
      cmd = Binding.ctx_mongo_op(self)

      result = @encryption_io.mark_command(cmd, timeout_ms: timeout_ms)
      mongocrypt_feed(result)

      mongocrypt_done
    when :need_kms
      while kms_context = Binding.ctx_next_kms_ctx(self) do
        provider = Binding.kms_ctx_get_kms_provider(kms_context)
        tls_options = @mongocrypt_handle.kms_tls_options(provider)
        @encryption_io.feed_kms(kms_context, tls_options)
      end

      Binding.ctx_kms_done(self)
    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



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

def state
  Binding.mongocrypt_ctx_state(@ctx_p)
end