mongo 2.11.6 → 2.12.0.rc0

data/lib/mongo/crypt/explicit_decryption_context.rb

@@ -0,0 +1,40 @@
+# Copyright (C) 2019 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 explicit decryption
+    #
+    # @api private
+    class ExplicitDecryptionContext < Context
+
+      # Create a new ExplicitDecryptionContext 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 [ BSON::Document ] doc A document to decrypt
+      def initialize(mongocrypt, io, doc)
+        super(mongocrypt, io)
+
+        # Initialize the underlying mongocrypt_ctx_t object to perform
+        # explicit decryption
+        Binding.ctx_explicit_decrypt_init(self, doc)
+      end
+    end
+  end
+end

data/lib/mongo/crypt/explicit_encrypter.rb

@@ -0,0 +1,117 @@
+# Copyright (C) 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 ExplicitEncrypter is an object that performs explicit encryption
+    # operations and handles all associated options and instance variables.
+    #
+    # @api private
+    class ExplicitEncrypter
+      # Create a new ExplicitEncrypter object.
+      #
+      # @params [ Mongo::Client ] key_vault_client An instance of Mongo::Client
+      #   to connect to the key vault collection.
+      # @params [ String ] key_vault_namespace The namespace of the key vault
+      #   collection in the format "db_name.collection_name".
+      # @option options [ Hash ] :kms_providers A hash of key management service
+      #   configuration information. Valid hash keys are :local or :aws. There
+      #   may be more than one KMS provider specified.
+      def initialize(key_vault_client, key_vault_namespace, kms_providers)
+        @crypt_handle = Handle.new(kms_providers)
+
+        @encryption_io = EncryptionIO.new(
+          key_vault_client: key_vault_client,
+          key_vault_namespace: key_vault_namespace
+        )
+      end
+
+      # Generates a data key used for encryption/decryption and stores
+      # that key in the KMS collection. The generated key is encrypted with
+      # the KMS master key.
+      #
+      # @param [ String ] kms_provider The KMS provider to use. Valid values are
+      #   "aws" and "local".
+      # @params [ Hash ] options
+      #
+      # @option options [ Hash ] :master_key Information about the AWS master key. Required
+      #   if kms_provider is "aws".
+      #   - :region [ String ] The The AWS region of the master key (required).
+      #   - :key [ String ] The Amazon Resource Name (ARN) of the master key (required).
+      #   - :endpoint [ String ] An alternate host to send KMS requests to (optional).
+      #     endpoint should be a host name with an optional port number separated
+      #     by a colon (e.g. "kms.us-east-1.amazonaws.com" or
+      #     "kms.us-east-1.amazonaws.com:443"). An endpoint in any other format
+      #     will not be properly parsed.
+      # @option options [ Array<String> ] :key_alt_names An optional array of strings specifying
+      #   alternate names for the new data key.
+      #
+      # @return [ BSON::Binary ] The 16-byte UUID of the new data key as a
+      #   BSON::Binary object with type :uuid.
+      def create_and_insert_data_key(kms_provider, options)
+        data_key_document = Crypt::DataKeyContext.new(
+          @crypt_handle,
+          @encryption_io,
+          kms_provider,
+          options
+        ).run_state_machine
+
+        @encryption_io.insert_data_key(data_key_document).inserted_id
+      end
+
+      # Encrypts a value using the specified encryption key and algorithm
+      #
+      # @param [ Object ] value The value to encrypt
+      # @param [ Hash ] options
+      #
+      # @option options [ BSON::Binary ] :key_id A BSON::Binary object of type :uuid
+      #   representing the UUID of the encryption key as it is stored in the key
+      #   vault collection.
+      # @option options [ String ] :key_alt_name The alternate name for the
+      #   encryption key.
+      # @option options [ String ] :algorithm The algorithm used to encrypt the value.
+      #   Valid algorithms are "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"
+      #   or "AEAD_AES_256_CBC_HMAC_SHA_512-Random".
+      #
+      # @note The :key_id and :key_alt_name options are mutually exclusive. Only
+      #   one is required to perform explicit encryption.
+      #
+      # @return [ BSON::Binary ] A BSON Binary object of subtype 6 (ciphertext)
+      #   representing the encrypted value
+      def encrypt(value, options)
+        Crypt::ExplicitEncryptionContext.new(
+          @crypt_handle,
+          @encryption_io,
+          { 'v': value },
+          options
+        ).run_state_machine['v']
+      end
+
+      # Decrypts a value that has already been encrypted
+      #
+      # @param [ BSON::Binary ] value A BSON Binary object of subtype 6 (ciphertext)
+      #   that will be decrypted
+      #
+      # @return [ Object ] The decrypted value
+      def decrypt(value)
+        result = Crypt::ExplicitDecryptionContext.new(
+          @crypt_handle,
+          @encryption_io,
+          { 'v': value },
+        ).run_state_machine['v']
+      end
+    end
+  end
+end

data/lib/mongo/crypt/explicit_encryption_context.rb

@@ -0,0 +1,89 @@
+# Copyright (C) 2019 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 explicit encryption
+    #
+    # @api private
+    class ExplicitEncryptionContext < Context
+
+      # Create a new ExplicitEncryptionContext 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 [ BSON::Document ] doc A document to encrypt
+      # @param [ Hash ] options
+      #
+      # @option options [ BSON::Binary ] :key_id A BSON::Binary object of type
+      #   :uuid representing the UUID of the data key to use for encryption.
+      # @option options [ String ] :key_alt_name The alternate name of the data key
+      #   that will be used to encrypt the value.
+      # @option options [ String ] :algorithm The algorithm used to encrypt the
+      #   value. Valid algorithms are "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"
+      #   or "AEAD_AES_256_CBC_HMAC_SHA_512-Random"
+      #
+      # @raises [ ArgumentError|Mongo::Error::CryptError ] If invalid options are provided
+      def initialize(mongocrypt, io, doc, options={})
+        super(mongocrypt, io)
+
+        if options[:key_id].nil? && options[:key_alt_name].nil?
+          raise ArgumentError.new(
+            'The :key_id and :key_alt_name options cannot both be nil. ' +
+            'Specify a :key_id option or :key_alt_name option (but not both)'
+          )
+        end
+
+        if options[:key_id] && options[:key_alt_name]
+          raise ArgumentError.new(
+            'The :key_id and :key_alt_name options cannot both be present. ' +
+            'Identify the data key by specifying its id with the :key_id ' +
+            'option or specifying its alternate name with the :key_alt_name option'
+          )
+        end
+
+        # Set the key id or key alt name option on the mongocrypt_ctx_t object
+        # and raise an exception if the key_id or key_alt_name is invalid.
+        if options[:key_id]
+          unless options[:key_id].is_a?(BSON::Binary) &&
+            options[:key_id].type == :uuid
+              raise ArgumentError.new(
+                "Expected the :key_id option to be a BSON::Binary object with " +
+                "type :uuid. #{options[:key_id]} is an invalid :key_id option"
+              )
+          end
+
+          Binding.ctx_setopt_key_id(self, options[:key_id].data)
+        elsif options[:key_alt_name]
+          unless options[:key_alt_name].is_a?(String)
+            raise ArgumentError.new(':key_alt_name option must be a String')
+          end
+          Binding.ctx_setopt_key_alt_names(self, [options[:key_alt_name]])
+        end
+
+        # Set the algorithm option on the mongocrypt_ctx_t object and raises
+        # an exception if the algorithm is invalid.
+        Binding.ctx_setopt_algorithm(self, options[:algorithm])
+
+        # Initializes the mongocrypt_ctx_t object for explicit encryption and
+        # passes in the value to be encrypted.
+        Binding.ctx_explicit_encrypt_init(self, doc)
+      end
+    end
+  end
+end

data/lib/mongo/crypt/handle.rb

@@ -0,0 +1,293 @@
+# Copyright (C) 2019 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'
+require 'base64'
+
+module Mongo
+  module Crypt
+
+    # A handle to the libmongocrypt library that wraps a mongocrypt_t object,
+    # allowing clients to set options on that object or perform operations such
+    # as encryption and decryption
+    #
+    # @api private
+    class Handle
+      # Creates a new Handle object and initializes it with options
+      #
+      # @param [ Hash ] kms_providers A hash of KMS settings. The only supported
+      #   key is currently :local. Local KMS options must be passed in the
+      #   format { local: { key: <master key> } } where the master key is a
+      #   96-byte, base64 encoded string.
+      # @param [ Hash ] options A hash of options
+      #
+      # @option options [ Hash | nil ] :schema_map A hash representing the JSON schema
+      #   of the collection that stores auto encrypted documents.
+      # @option options [ Logger ] :logger A Logger object to which libmongocrypt logs
+      #   will be sent
+      def initialize(kms_providers, options={})
+        # FFI::AutoPointer uses a custom release strategy to automatically free
+        # the pointer once this object goes out of scope
+        @mongocrypt = FFI::AutoPointer.new(
+          Binding.mongocrypt_new,
+          Binding.method(:mongocrypt_destroy)
+        )
+
+        @schema_map = options[:schema_map]
+        set_schema_map if @schema_map
+
+        @logger = options[:logger]
+        set_logger_callback if @logger
+
+        set_crypto_hooks
+
+        set_kms_providers(kms_providers)
+        initialize_mongocrypt
+      end
+
+      # Return the reference to the underlying @mongocrypt object
+      #
+      # @return [ FFI::Pointer ]
+      def ref
+        @mongocrypt
+      end
+
+      private
+
+      # Set the schema map option on the underlying mongocrypt_t object
+      def set_schema_map
+        unless @schema_map.is_a?(Hash)
+          raise ArgumentError.new(
+            "#{@schema_map} is an invalid schema_map; schema_map must be a Hash or nil"
+          )
+        end
+
+        Binding.setopt_schema_map(self, @schema_map)
+      end
+
+      # Send the logs from libmongocrypt to the Mongo::Logger
+      def set_logger_callback
+        @log_callback = Proc.new do |level, msg|
+          @logger.send(level, msg)
+        end
+
+        Binding.setopt_log_handler(@mongocrypt, @log_callback)
+      end
+
+      # Yields to the provided block and rescues exceptions raised by
+      # the block. If an exception was raised, sets the specified status
+      # to the exception message and returns false. If no exceptions were
+      # raised, does not modify the status and returns true.
+      #
+      # This method is meant to be used with libmongocrypt callbacks and
+      # follows the API defined by libmongocrypt.
+      #
+      # @param [ FFI::Pointer ] status_p A pointer to libmongocrypt status object
+      #
+      # @return [ true | false ] Whether block executed without raising
+      #   exceptions.
+      def handle_error(status_p)
+        begin
+          yield
+
+          true
+        rescue => e
+          status = Status.from_pointer(status_p)
+          status.update(:error_client, 1, "#{e.class}: #{e}")
+          false
+        end
+      end
+
+      # Yields to the provided block and writes the return value of block
+      # to the specified mongocrypt_binary_t object. If an exception is
+      # raised during execution of the block, writes the exception message
+      # to the specified status object and returns false. If no exception is
+      # raised, does not modify status and returns true.
+      # message to the mongocrypt_status_t object.
+      #
+      # @param [ FFI::Pointer ] output_binary_p A pointer to libmongocrypt
+      #   Binary object to receive the result of block's execution
+      # @param [ FFI::Pointer ] status_p A pointer to libmongocrypt status object
+      #
+      # @return [ true | false ] Whether block executed without raising
+      #   exceptions.
+      def write_binary_string_and_set_status(output_binary_p, status_p)
+        handle_error(status_p) do
+          output = yield
+
+          Binary.from_pointer(output_binary_p).write(output)
+        end
+      end
+
+      # Perform AES encryption or decryption and write the output to the
+      # provided mongocrypt_binary_t object.
+      def do_aes(key_binary_p, iv_binary_p, input_binary_p, output_binary_p,
+        response_length_p, status_p, decrypt: false)
+        key = Binary.from_pointer(key_binary_p).to_s
+        iv = Binary.from_pointer(iv_binary_p).to_s
+        input = Binary.from_pointer(input_binary_p).to_s
+
+        write_binary_string_and_set_status(output_binary_p, status_p) do
+          output = Hooks.aes(key, iv, input, decrypt: decrypt)
+          response_length_p.write_int(output.bytesize)
+
+          output
+        end
+      end
+
+      # Perform HMAC SHA encryption and write the output to the provided
+      # mongocrypt_binary_t object.
+      def do_hmac_sha(digest_name, key_binary_p, input_binary_p,
+        output_binary_p, status_p)
+        key = Binary.from_pointer(key_binary_p).to_s
+        input = Binary.from_pointer(input_binary_p).to_s
+
+        write_binary_string_and_set_status(output_binary_p, status_p) do
+          Hooks.hmac_sha(digest_name, key, input)
+        end
+      end
+
+      # We are buildling libmongocrypt without crypto functions to remove the
+      # external dependency on OpenSSL. This method binds native Ruby crypto
+      # methods to the underlying mongocrypt_t object so that libmongocrypt can
+      # still perform cryptography.
+      #
+      # Every crypto binding ignores its first argument, which is an option
+      # mongocrypt_ctx_t object and is not required to use crypto hooks.
+      def set_crypto_hooks
+        @aes_encrypt = Proc.new do |_, key_binary_p, iv_binary_p, input_binary_p,
+          output_binary_p, response_length_p, status_p|
+          do_aes(
+            key_binary_p,
+            iv_binary_p,
+            input_binary_p,
+            output_binary_p,
+            response_length_p,
+            status_p
+          )
+        end
+
+        @aes_decrypt = Proc.new do |_, key_binary_p, iv_binary_p, input_binary_p,
+          output_binary_p, response_length_p, status_p|
+          do_aes(
+            key_binary_p,
+            iv_binary_p,
+            input_binary_p,
+            output_binary_p,
+            response_length_p,
+            status_p,
+            decrypt: true
+          )
+        end
+
+        @random = Proc.new do |_, output_binary_p, num_bytes, status_p|
+          write_binary_string_and_set_status(output_binary_p, status_p) do
+            Hooks.random(num_bytes)
+          end
+        end
+
+        @hmac_sha_512 = Proc.new do |_, key_binary_p, input_binary_p,
+          output_binary_p, status_p|
+          do_hmac_sha('SHA512', key_binary_p, input_binary_p, output_binary_p, status_p)
+        end
+
+        @hmac_sha_256 = Proc.new do |_, key_binary_p, input_binary_p,
+          output_binary_p, status_p|
+          do_hmac_sha('SHA256', key_binary_p, input_binary_p, output_binary_p, status_p)
+        end
+
+        @hmac_hash = Proc.new do |_, input_binary_p, output_binary_p, status_p|
+          input = Binary.from_pointer(input_binary_p).to_s
+
+          write_binary_string_and_set_status(output_binary_p, status_p) do
+            Hooks.hash_sha256(input)
+          end
+        end
+
+        Binding.setopt_crypto_hooks(
+          self,
+          @aes_encrypt,
+          @aes_decrypt,
+          @random,
+          @hmac_sha_512,
+          @hmac_sha_256,
+          @hmac_hash,
+        )
+      end
+
+      # Validate the kms_providers option and use it to set the KMS provider
+      # information on the underlying mongocrypt_t object
+      def set_kms_providers(kms_providers)
+        unless kms_providers
+          raise ArgumentError.new("The kms_providers option must not be nil")
+        end
+
+        unless kms_providers.key?(:local) || kms_providers.key?(:aws)
+          raise ArgumentError.new(
+            'The kms_providers option must have one of the following keys: ' +
+            ':aws, :local'
+          )
+        end
+
+        set_kms_providers_local(kms_providers) if kms_providers.key?(:local)
+        set_kms_providers_aws(kms_providers) if kms_providers.key?(:aws)
+      end
+
+    # Validate and set the local KMS provider information on the underlying
+      # mongocrypt_t object and raise an exception if the operation fails
+      def set_kms_providers_local(kms_providers)
+        unless kms_providers[:local][:key] && kms_providers[:local][:key].is_a?(String)
+          raise ArgumentError.new(
+            "The specified local kms_providers option is invalid: " +
+            "#{kms_providers[:local]}. kms_providers with :local key must be " +
+            "in the format: { local: { key: 'MASTER-KEY' } }"
+          )
+        end
+
+        master_key = kms_providers[:local][:key]
+        Binding.setopt_kms_provider_local(self, master_key)
+      end
+
+      # Validate and set the aws KMS provider information on the underlying
+      # mongocrypt_t object and raise an exception if the operation fails
+      def set_kms_providers_aws(kms_providers)
+        unless kms_providers[:aws]
+          raise ArgumentError.new('The :aws KMS provider must not be nil')
+        end
+
+        access_key_id = kms_providers[:aws][:access_key_id]
+        secret_access_key = kms_providers[:aws][:secret_access_key]
+
+        valid_access_key_id = access_key_id && access_key_id.is_a?(String)
+        valid_secret_access_key = secret_access_key && secret_access_key.is_a?(String)
+
+        unless valid_access_key_id && valid_secret_access_key
+          raise ArgumentError.new(
+            "The specified aws kms_providers option is invalid: #{kms_providers[:aws]}. " +
+            "kms_providers with :aws key must be in the format: " +
+            "{ aws: { access_key_id: 'YOUR-ACCESS-KEY-ID', secret_access_key: 'SECRET-ACCESS-KEY' } }"
+          )
+        end
+
+        Binding.setopt_kms_provider_aws(self, access_key_id, secret_access_key)
+      end
+
+      # Initialize the underlying mongocrypt_t object and raise an error if the operation fails
+      def initialize_mongocrypt
+        Binding.init(self)
+        # There is currently no test for the error(?) code path
+      end
+    end
+  end
+end