mongo 2.11.2 → 2.13.0.beta1

data/lib/mongo/crypt.rb

@@ -0,0 +1,33 @@
+# Copyright (C) 2019-2020 MongoDB Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module Mongo
+  module Crypt
+    autoload(:Binding, 'mongo/crypt/binding')
+    autoload(:Binary, 'mongo/crypt/binary')
+    autoload(:Status, 'mongo/crypt/status')
+    autoload(:Hooks, 'mongo/crypt/hooks')
+    autoload(:Handle, 'mongo/crypt/handle')
+    autoload(:KmsContext, 'mongo/crypt/kms_context')
+    autoload(:Context, 'mongo/crypt/context')
+    autoload(:DataKeyContext, 'mongo/crypt/data_key_context')
+    autoload(:ExplicitEncryptionContext, 'mongo/crypt/explicit_encryption_context')
+    autoload(:AutoEncryptionContext, 'mongo/crypt/auto_encryption_context')
+    autoload(:ExplicitDecryptionContext, 'mongo/crypt/explicit_decryption_context')
+    autoload(:AutoDecryptionContext, 'mongo/crypt/auto_decryption_context')
+    autoload(:EncryptionIO, 'mongo/crypt/encryption_io')
+    autoload(:ExplicitEncrypter, 'mongo/crypt/explicit_encrypter')
+    autoload(:AutoEncrypter, 'mongo/crypt/auto_encrypter')
+  end
+end

data/lib/mongo/crypt/auto_decryption_context.rb

@@ -0,0 +1,40 @@
+# Copyright (C) 2019-2020 MongoDB Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module Mongo
+  module Crypt
+
+    # A Context object initialized for auto decryption
+    #
+    # @api private
+    class AutoDecryptionContext < Context
+
+      # Create a new AutoEncryptionContext object
+      #
+      # @param [ Mongo::Crypt::Handle ] mongocrypt a Handle that
+      #   wraps a mongocrypt_t object used to create a new mongocrypt_ctx_t.
+      # @param [ ClientEncryption::IO ] io A instance of the IO class
+      #   that implements driver I/O methods required to run the
+      #   state machine.
+      # @param [ Hash ] command The command to be decrypted.
+      def initialize(mongocrypt, io, command)
+        super(mongocrypt, io)
+
+        @command = command
+
+        Binding.ctx_decrypt_init(self, @command)
+      end
+    end
+  end
+end

data/lib/mongo/crypt/auto_encrypter.rb

@@ -0,0 +1,179 @@
+# Copyright (C) 2019-2020 MongoDB Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module Mongo
+  module Crypt
+
+    # An AutoEcnrypter is an object that encapsulates the behavior of
+    # automatic encryption. It controls all resources associated with
+    # auto-encryption, including the libmongocrypt handle, key vault client
+    # object, mongocryptd client object, and encryption I/O.
+    #
+    # The AutoEncrypter is kept as an instance on a Mongo::Client. Client
+    # objects with the same auto_encryption_options Hash may share
+    # AutoEncrypters.
+    #
+    # @api private
+    class AutoEncrypter
+
+      attr_reader :mongocryptd_client
+      attr_reader :key_vault_client
+      attr_reader :options
+
+      # A Hash of default values for the :extra_options option
+      DEFAULT_EXTRA_OPTIONS = Options::Redacted.new({
+        mongocryptd_uri: 'mongodb://localhost:27020',
+        mongocryptd_bypass_spawn: false,
+        mongocryptd_spawn_path: 'mongocryptd',
+        mongocryptd_spawn_args: ['--idleShutdownTimeoutSecs=60'],
+      })
+
+      # Set up encryption-related options and instance variables
+      # on the class that includes this module. Calls the same method
+      # on the Mongo::Crypt::Encrypter module.
+      #
+      # @param [ Hash ] options
+      #
+      # @option options [ Mongo::Client ] :client A client connected to the
+      #   encrypted collection.
+      # @option options [ Mongo::Client | nil ] :key_vault_client A client connected
+      #   to the MongoDB instance containing the encryption key vault; optional.
+      #   If not provided, will default to :client option.
+      # @option options [ String ] :key_vault_namespace The namespace of the key
+      #   vault in the format database.collection.
+      # @option options [ Hash | nil ] :schema_map The JSONSchema of the collection(s)
+      #   with encrypted fields.
+      # @option options [ Boolean | nil ] :bypass_auto_encryption When true, disables
+      #   auto-encryption. Default is false.
+      # @option options [ Hash | nil ] :extra_options Options related to spawning
+      #   mongocryptd. These are set to default values if no option is passed in.
+      #
+      # @raise [ ArgumentError ] If required options are missing or incorrectly
+      #   formatted.
+      def initialize(options)
+        @options = set_default_options(options).freeze
+
+        @crypt_handle = Crypt::Handle.new(
+          @options[:kms_providers],
+          schema_map: @options[:schema_map]
+        )
+
+        @key_vault_client = @options[:key_vault_client]
+
+        # Set server selection timeout to 1 to prevent the client waiting for a
+        # long timeout before spawning mongocryptd
+        @mongocryptd_client = Client.new(
+          @options[:extra_options][:mongocryptd_uri],
+          monitoring_io: @options[:client].options[:monitoring_io],
+          server_selection_timeout: 1,
+        )
+
+        begin
+          @encryption_io = EncryptionIO.new(
+            client: @options[:client],
+            mongocryptd_client: @mongocryptd_client,
+            key_vault_namespace: @options[:key_vault_namespace],
+            key_vault_client: @key_vault_client,
+            mongocryptd_options: @options[:extra_options]
+          )
+        rescue
+          begin
+            @mongocryptd_client.close
+          rescue => e
+            log_warn("Eror closing mongocryptd client in auto encrypter's constructor: #{e.class}: #{e}")
+            # Drop this exception so that the original exception is raised
+          end
+          raise
+        end
+      end
+
+      # Whether this encrypter should perform encryption (returns false if
+      # the :bypass_auto_encryption option is set to true).
+      #
+      # @return [ Boolean ] Whether to perform encryption.
+      def encrypt?
+        !@options[:bypass_auto_encryption]
+      end
+
+      # Encrypt a database command.
+      #
+      # @param [ String ] database_name The name of the database on which the
+      #   command is being run.
+      # @param [ Hash ] command The command to be encrypted.
+      #
+      # @return [ BSON::Document ] The encrypted command.
+      def encrypt(database_name, command)
+        AutoEncryptionContext.new(
+          @crypt_handle,
+          @encryption_io,
+          database_name,
+          command
+        ).run_state_machine
+      end
+
+      # Decrypt a database command.
+      #
+      # @param [ Hash ] command The command with encrypted fields.
+      #
+      # @return [ BSON::Document ] The decrypted command.
+      def decrypt(command)
+        AutoDecryptionContext.new(
+          @crypt_handle,
+          @encryption_io,
+          command
+        ).run_state_machine
+      end
+
+      # Close the resources created by the AutoEncrypter.
+      #
+      # @return [ true ] Always true.
+      def close
+        @mongocryptd_client.close if @mongocryptd_client
+
+        true
+      end
+
+      private
+
+      # Returns a new set of options with the following changes:
+      # - sets default values for all extra_options
+      # - adds --idleShtudownTimeoutSecs=60 to extra_options[:mongocryptd_spawn_args]
+      #   if not already present
+      # - sets bypass_auto_encryption to false
+      # - sets default key vault client
+      def set_default_options(options)
+        opts = options.dup
+
+        extra_options = opts.delete(:extra_options) || Options::Redacted.new
+        extra_options = DEFAULT_EXTRA_OPTIONS.merge(extra_options)
+
+        has_timeout_string_arg = extra_options[:mongocryptd_spawn_args].any? do |elem|
+          elem.is_a?(String) && elem.match(/\A--idleShutdownTimeoutSecs=\d+\z/)
+        end
+
+        timeout_int_arg_idx = extra_options[:mongocryptd_spawn_args].index('--idleShutdownTimeoutSecs')
+        has_timeout_int_arg = timeout_int_arg_idx && extra_options[:mongocryptd_spawn_args][timeout_int_arg_idx + 1].is_a?(Integer)
+
+        unless has_timeout_string_arg || has_timeout_int_arg
+          extra_options[:mongocryptd_spawn_args] << '--idleShutdownTimeoutSecs=60'
+        end
+
+        opts[:bypass_auto_encryption] ||= false
+        opts[:key_vault_client] ||= opts[:client]
+
+        Options::Redacted.new(opts).merge(extra_options: extra_options)
+      end
+    end
+  end
+end

data/lib/mongo/crypt/auto_encryption_context.rb

@@ -0,0 +1,44 @@
+# Copyright (C) 2019-2020 MongoDB Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module Mongo
+  module Crypt
+
+    # A Context object initialized for auto encryption
+    #
+    # @api private
+    class AutoEncryptionContext < Context
+
+      # Create a new AutoEncryptionContext object
+      #
+      # @param [ Mongo::Crypt::Handle ] mongocrypt a Handle that
+      #   wraps a mongocrypt_t object used to create a new mongocrypt_ctx_t
+      # @param [ ClientEncryption::IO ] io A instance of the IO class
+      #   that implements driver I/O methods required to run the
+      #   state machine
+      # @param [ String ] db_name The name of the database against which
+      #   the command is being made
+      # @param [ Hash ] command The command to be encrypted
+      def initialize(mongocrypt, io, db_name, command)
+        super(mongocrypt, io)
+
+        @db_name = db_name
+        @command = command
+
+        # Initialize the ctx object for auto encryption
+        Binding.ctx_encrypt_init(self, @db_name, @command)
+      end
+    end
+  end
+end

data/lib/mongo/crypt/binary.rb

@@ -0,0 +1,155 @@
+# Copyright (C) 2019-2020 MongoDB Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'ffi'
+
+module Mongo
+  module Crypt
+
+    # A wrapper around mongocrypt_binary_t, a non-owning buffer of
+    # uint-8 byte data. Each Binary instance keeps a copy of the data
+    # passed to it in order to keep that data alive.
+    #
+    # @api private
+    class Binary
+      # Create a new Binary object that wraps a byte string
+      #
+      # @param [ String ] data The data string wrapped by the
+      #   byte buffer (optional)
+      # @param [ FFI::Pointer ] pointer A pointer to an existing
+      #   mongocrypt_binary_t object
+      #
+      # @note When initializing a Binary object with a string or a pointer,
+      # it is recommended that you use #self.from_pointer or #self.from_data
+      # methods
+      def initialize(data: nil, pointer: nil)
+        if data
+          # Represent data string as array of uint-8 bytes
+          bytes = data.unpack('C*')
+
+          # FFI::MemoryPointer automatically frees memory when it goes out of scope
+          @data_p = FFI::MemoryPointer.new(bytes.length)
+                    .write_array_of_uint8(bytes)
+
+          # FFI::AutoPointer uses a custom release strategy to automatically free
+          # the pointer once this object goes out of scope
+          @bin = FFI::AutoPointer.new(
+            Binding.mongocrypt_binary_new_from_data(@data_p, bytes.length),
+            Binding.method(:mongocrypt_binary_destroy)
+          )
+        elsif pointer
+          # If the Binary class is used this way, it means that the pointer
+          # for the underlying mongocrypt_binary_t object is allocated somewhere
+          # else. It is not the responsibility of this class to de-allocate data.
+          @bin = pointer
+        else
+          # FFI::AutoPointer uses a custom release strategy to automatically free
+          # the pointer once this object goes out of scope
+          @bin = FFI::AutoPointer.new(
+            Binding.mongocrypt_binary_new,
+            Binding.method(:mongocrypt_binary_destroy)
+          )
+        end
+      end
+
+      # Initialize a Binary object from an existing pointer to a mongocrypt_binary_t
+      # object.
+      #
+      # @param [ FFI::Pointer ] pointer A pointer to an existing
+      #   mongocrypt_binary_t object
+      #
+      # @return [ Mongo::Crypt::Binary ] A new binary object
+      def self.from_pointer(pointer)
+        self.new(pointer: pointer)
+      end
+
+      # Initialize a Binary object with a string. The Binary object will store a
+      # copy of the specified string and destroy the allocated memory when
+      # it goes out of scope.
+      #
+      # @param [ String ] data A string to be wrapped by the Binary object
+      #
+      # @return [ Mongo::Crypt::Binary ] A new binary object
+      def self.from_data(data)
+        self.new(data: data)
+      end
+
+      # Overwrite the existing data wrapped by this Binary object
+      #
+      # @note The data passed in must not take up more memory than the
+      # original memory allocated to the underlying mongocrypt_binary_t
+      # object. Do NOT use this method unless required to do so by libmongocrypt.
+      #
+      # @param [ String ] data The new string data to be wrapped by this binary object
+      #
+      # @return [ true ] Always true
+      #
+      # @raise [ ArgumentError ] Raises when trying to write more data
+      # than was originally allocated or when writing to an object that
+      # already owns data.
+      def write(data)
+        if @data
+          raise ArgumentError, 'Cannot write to an owned Binary'
+        end
+
+        # Cannot write a string that's longer than the space currently allocated
+        # by the mongocrypt_binary_t object
+        str_p = Binding.mongocrypt_binary_data(ref)
+        len = Binding.mongocrypt_binary_len(ref)
+
+        if len < data.bytesize
+          raise ArgumentError.new(
+            "Cannot write #{data.bytesize} bytes of data to a Binary object " +
+            "that was initialized with #{Binding.mongocrypt_binary_len(@bin)} bytes."
+          )
+        end
+
+        str_p.put_bytes(0, data)
+
+        true
+      end
+
+      # Returns the data stored as a string
+      #
+      # @return [ String ] Data stored in the mongocrypt_binary_t as a string
+      def to_s
+        str_p = Binding.mongocrypt_binary_data(ref)
+        len = Binding.mongocrypt_binary_len(ref)
+        str_p.read_string(len)
+      end
+
+      # Returns the reference to the underlying mongocrypt_binary_t
+      # object
+      #
+      # @return [ FFI::Pointer ] The underlying mongocrypt_binary_t object
+      def ref
+        @bin
+      end
+
+      # Wraps a String with a mongocrypt_binary_t, yielding an FFI::Pointer
+      # to the wrapped struct.
+      def self.wrap_string(str)
+        binary_p = Binding.mongocrypt_binary_new_from_data(
+          FFI::MemoryPointer.from_string(str),
+          str.bytesize,
+        )
+        begin
+          yield binary_p
+        ensure
+          Binding.mongocrypt_binary_destroy(binary_p)
+        end
+      end
+    end
+  end
+end