Class: Mongo::Crypt::Context Private

Inherits:
Object
  • Object
show all
Defined in:
build/ruby-driver-master/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.



37
38
39
40
41
42
43
44
45
46
47
48
49
50
 
# File 'build/ruby-driver-master/lib/mongo/crypt/context.rb', line 37

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



52
53
54
 
# File 'build/ruby-driver-master/lib/mongo/crypt/context.rb', line 52

def ctx_p
  @ctx_p
end

Instance Method Details

#run_state_machine ⇒ 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 libmongocrypt

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

Returns:

  • (BSON::Document) —

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

Raises:



73
74
75
76
77
78
79
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
111
112
113
114
115
116
117
118
119
120
121
122
 
# File 'build/ruby-driver-master/lib/mongo/crypt/context.rb', line 73

def run_state_machine
  while true
    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).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)
      mongocrypt_feed(result) if result

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

      result = @encryption_io.mark_command(cmd)
      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)
    else
      raise Error::CryptError.new(
        # TODO: fix CryptError to improve this API -- the first argument
        # in the initializer should not be optional
        nil,
        "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



57
58
59
 
# File 'build/ruby-driver-master/lib/mongo/crypt/context.rb', line 57

def state
  Binding.mongocrypt_ctx_state(@ctx_p)
end