mongo 2.15.0 → 2.18.1

data/lib/mongo/crypt/handle.rb

@@ -27,19 +27,41 @@ module Mongo
     #
     # @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
+      # @param [ Crypt::KMS::Credentials ] kms_providers Credentials for KMS providers.
+      #
+      # @param [ Hash ] kms_tls_options TLS options to connect to KMS
+      #   providers. Keys of the hash should be KSM provider names; values
+      #   should be hashes of TLS connection options. The options are equivalent
+      #   to TLS connection options of Mongo::Client.
       #
+      # @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.
+      #   of the collection that stores auto encrypted documents. This option is
+      #   mutually exclusive with :schema_map_path.
+      # @option options [ String | nil ] :schema_map_path A path to a file contains the JSON schema
+      #   of the collection that stores auto encrypted documents. This option is
+      #   mutually exclusive with :schema_map.
+      # @option options [ Hash | nil ] :encrypted_fields_map maps a collection
+      #   namespace to an encryptedFields.
+      #   - Note: If a collection is present on both the encryptedFieldsMap
+      #     and schemaMap, an error will be raised.
+      # @option options [ Boolean | nil ] :bypass_query_analysis When true
+      #   disables automatic analysis of outgoing commands.
+      # @option options [ String | nil ] :crypt_shared_lib_path Path that should
+      #   be  the used to load the crypt shared library. Providing this option
+      #   overrides default crypt shared library load paths for libmongocrypt.
+      # @option options [ Boolean | nil ] :crypt_shared_lib_required Whether
+      #   crypt_shared library is required. If 'true', an error will be raised
+      #   if a crypt_shared library cannot be loaded by libmongocrypt.
+      # @option options [ Boolean | nil ] :explicit_encryption_only Whether this
+      #   handle is going to be used only for explicit encryption. If true,
+      #   libmongocrypt is instructed not to load crypt shared library.
       # @option options [ Logger ] :logger A Logger object to which libmongocrypt logs
       #   will be sent
-      def initialize(kms_providers, options={})
+      def initialize(kms_providers, kms_tls_options, options={})
         # FFI::AutoPointer uses a custom release strategy to automatically free
         # the pointer once this object goes out of scope
         @mongocrypt = FFI::AutoPointer.new(
@@ -47,16 +69,39 @@ module Mongo
           Binding.method(:mongocrypt_destroy)
         )
 
-        @schema_map = options[:schema_map]
-        set_schema_map if @schema_map
+        @kms_tls_options =  kms_tls_options
+
+        maybe_set_schema_map(options)
+
+        @encrypted_fields_map = options[:encrypted_fields_map]
+        set_encrypted_fields_map if @encrypted_fields_map
+
+        @bypass_query_analysis = options[:bypass_query_analysis]
+        set_bypass_query_analysis if @bypass_query_analysis
+
+        @crypt_shared_lib_path = options[:crypt_shared_lib_path]
+        @explicit_encryption_only = options[:explicit_encryption_only]
+        if @crypt_shared_lib_path
+          Binding.setopt_set_crypt_shared_lib_path_override(self, @crypt_shared_lib_path)
+        elsif !@bypass_query_analysis && !@explicit_encryption_only
+          Binding.setopt_append_crypt_shared_lib_search_path(self, "$SYSTEM")
+        end
 
         @logger = options[:logger]
         set_logger_callback if @logger
 
         set_crypto_hooks
 
-        set_kms_providers(kms_providers)
+        Binding.setopt_kms_providers(self, kms_providers.to_document)
+
         initialize_mongocrypt
+
+        @crypt_shared_lib_required = !!options[:crypt_shared_lib_required]
+        if @crypt_shared_lib_required && crypt_shared_lib_version == 0
+          raise Mongo::Error::CryptError.new(
+            "Crypt shared library is required, but cannot be loaded  according to libmongocrypt"
+          )
+        end
       end
 
       # Return the reference to the underlying @mongocrypt object
@@ -66,17 +111,70 @@ module Mongo
         @mongocrypt
       end
 
+      # Return TLS options for KMS provider. If there are no TLS options set,
+      # empty hash is returned.
+      #
+      # @param [ String ] provider KSM provider name.
+      #
+      # @return [ Hash ] TLS options to connect to KMS provider.
+      def kms_tls_options(provider)
+        @kms_tls_options.fetch(provider, {})
+      end
+
+      def crypt_shared_lib_version
+        Binding.crypt_shared_lib_version(self)
+      end
+
+      def crypt_shared_lib_available?
+        crypt_shared_lib_version != 0
+      end
+
       private
 
       # Set the schema map option on the underlying mongocrypt_t object
-      def set_schema_map
-        unless @schema_map.is_a?(Hash)
+      def maybe_set_schema_map(options)
+        if !options[:schema_map] && !options[:schema_map_path]
+          @schema_map = nil
+        elsif options[:schema_map] && options[:schema_map_path]
           raise ArgumentError.new(
-            "#{@schema_map} is an invalid schema_map; schema_map must be a Hash or nil"
+            "Cannot set both schema_map and schema_map_path options."
+          )
+        elsif options[:schema_map]
+          unless options[:schema_map].is_a?(Hash)
+            raise ArgumentError.new(
+              "#{@schema_map} is an invalid schema_map; schema_map must be a Hash or nil."
+            )
+          end
+          @schema_map = options[:schema_map]
+          Binding.setopt_schema_map(self, @schema_map)
+        elsif options[:schema_map_path]
+          @schema_map = BSON::ExtJSON.parse(File.read(options[:schema_map_path]))
+          Binding.setopt_schema_map(self, @schema_map)
+        end
+      rescue Errno::ENOENT
+        raise ArgumentError.new(
+          "#{@schema_map_path} is an invalid path to a file contains schema_map."
+        )
+      end
+
+      def set_encrypted_fields_map
+        unless @encrypted_fields_map.is_a?(Hash)
+          raise ArgumentError.new(
+            "#{@encrypted_fields_map} is an invalid encrypted_fields_map: must be a Hash or nil"
+          )
+        end
+
+        Binding.setopt_encrypted_field_config_map(self, @encrypted_fields_map)
+      end
+
+      def set_bypass_query_analysis
+        unless [true, false].include?(@bypass_query_analysis)
+          raise ArgumentError.new(
+            "#{@bypass_query_analysis} is an invalid bypass_query_analysis value; must be a Boolean or nil"
           )
         end
 
-        Binding.setopt_schema_map(self, @schema_map)
+        Binding.setopt_bypass_query_analysis(self) if @bypass_query_analysis
       end
 
       # Send the logs from libmongocrypt to the Mongo::Logger
@@ -136,13 +234,13 @@ module Mongo
       # 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)
+        response_length_p, status_p, decrypt: false, mode: :CBC)
         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)
+          output = Hooks.aes(key, iv, input, decrypt: decrypt, mode: mode)
           response_length_p.write_int(output.bytesize)
 
           output
@@ -161,7 +259,19 @@ module Mongo
         end
       end
 
-      # We are buildling libmongocrypt without crypto functions to remove the
+      # Perform signing using RSASSA-PKCS1-v1_5 with SHA256 hash and write
+      # the output to the provided mongocrypt_binary_t object.
+      def do_rsaes_pkcs_signature(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.rsaes_pkcs_signature(key, input)
+        end
+      end
+
+      # We are building 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.
@@ -227,85 +337,49 @@ module Mongo
           @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' } }"
+        @aes_ctr_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,
+            mode: :CTR,
           )
         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]
-
-        unless kms_providers[:aws].key?(:access_key_id) && 
-            kms_providers[:aws].key?(: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' } }"
+        @aes_ctr_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,
+            mode: :CTR,
           )
         end
 
-        %i(access_key_id secret_access_key).each do |key|
-          value = kms_providers[:aws][key]
-          if value.nil?
-            raise ArgumentError.new(
-              "The aws #{key} option must be a String with at least one character; " \
-              "currently have nil"
-            )
-          end
-
-          unless value.is_a?(String)
-            raise ArgumentError.new(
-              "The aws #{key} option must be a String with at least one character; " \
-              "currently have #{value}"
-            )
-          end
+        Binding.setopt_aes_256_ctr(
+          self,
+          @aes_ctr_encrypt,
+          @aes_ctr_decrypt,
+        )
 
-          if value.empty?
-            raise ArgumentError.new(
-              "The aws #{key} option must be a String with at least one character; " \
-              "it is currently an empty string"
-            )
-          end
+        @rsaes_pkcs_signature_cb = Proc.new do |_, key_binary_p, input_binary_p,
+          output_binary_p, status_p|
+          do_rsaes_pkcs_signature(key_binary_p, input_binary_p, output_binary_p, status_p)
         end
 
-        Binding.setopt_kms_provider_aws(self, access_key_id, secret_access_key)
+        Binding.setopt_crypto_hook_sign_rsaes_pkcs1_v1_5(
+          self,
+          @rsaes_pkcs_signature_cb
+        )
       end
 
       # Initialize the underlying mongocrypt_t object and raise an error if the operation fails

data/lib/mongo/crypt/hooks.rb

@@ -35,12 +35,13 @@ module Mongo
       # @param [ String ] input The data to be encrypted/decrypted
       # @param [ true | false ] decrypt Whether this method is decrypting. Default is
       #   false, which means the method will create an encryption cipher by default
+      # @param [ Symbol ] mode AES mode of operation
       #
       # @return [ String ] Output
       # @raise [ Exception ] Exceptions raised during encryption are propagated
       #   to caller.
-      def aes(key, iv, input, decrypt: false)
-        cipher = OpenSSL::Cipher::AES.new(256, :CBC)
+      def aes(key, iv, input, decrypt: false, mode: :CBC)
+        cipher = OpenSSL::Cipher::AES.new(256, mode)
 
         decrypt ? cipher.decrypt : cipher.encrypt
         cipher.key = key
@@ -88,6 +89,28 @@ module Mongo
         Digest::SHA2.new(256).digest(input)
       end
       module_function :hash_sha256
+
+      # An RSASSA-PKCS1-v1_5 with SHA-256 signature function.
+      #
+      # @param [ String ] key The PKCS#8 private key in DER format, base64 encoded.
+      # @param [ String ] input The data to be signed.
+      #
+      # @return [ String ] The signature.
+      def rsaes_pkcs_signature(key, input)
+        private_key = if BSON::Environment.jruby?
+          # JRuby cannot read DER format, we need to convert key into PEM first.
+          key_pem = [
+            "-----BEGIN PRIVATE KEY-----",
+            Base64.strict_encode64(Base64.decode64(key)).scan(/.{1,64}/),
+            "-----END PRIVATE KEY-----",
+          ].join("\n")
+          OpenSSL::PKey::RSA.new(key_pem)
+        else
+          OpenSSL::PKey.read(Base64.decode64(key))
+        end
+        private_key.sign(OpenSSL::Digest::SHA256.new, input)
+      end
+      module_function :rsaes_pkcs_signature
     end
   end
 end

data/lib/mongo/crypt/kms/aws.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+# encoding: utf-8
+
+# Copyright (C) 2019-2021 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
+    module KMS
+      module AWS
+
+        # AWS KMS Credentials object contains credentials for using AWS KMS provider.
+        #
+        # @api private
+        class Credentials
+          extend Forwardable
+          include KMS::Validations
+
+          # @return [ String ] AWS access key.
+          attr_reader :access_key_id
+
+          # @return [ String ] AWS secret access key.
+          attr_reader :secret_access_key
+
+          # @return [ String | nil ] AWS session token.
+          attr_reader :session_token
+
+          # @api private
+          def_delegator :@opts, :empty?
+
+          FORMAT_HINT = "AWS KMS provider options must be in the format: " +
+                        "{ access_key_id: 'YOUR-ACCESS-KEY-ID', secret_access_key: 'SECRET-ACCESS-KEY' }"
+
+          # Creates an AWS KMS credentials object form a parameters hash.
+          #
+          # @param [ Hash ] opts A hash that contains credentials for
+          #   AWS KMS provider
+          # @option opts [ String ] :access_key_id AWS access key id.
+          # @option opts [ String ] :secret_access_key AWS secret access key.
+          # @option opts [ String | nil ] :session_token AWS session token, optional.
+          #
+          # @raise [ ArgumentError ] If required options are missing or incorrectly
+          #   formatted.
+          def initialize(opts)
+            @opts = opts
+            unless empty?
+              @access_key_id = validate_param(:access_key_id, opts, FORMAT_HINT)
+              @secret_access_key = validate_param(:secret_access_key, opts, FORMAT_HINT)
+              @session_token = validate_param(:session_token, opts, FORMAT_HINT, required: false)
+            end
+          end
+
+          # Convert credentials object to a BSON document in libmongocrypt format.
+          #
+          # @return [ BSON::Document ] AWS KMS credentials in libmongocrypt format.
+          def to_document
+            return BSON::Document.new if empty?
+            BSON::Document.new({
+              accessKeyId: access_key_id,
+              secretAccessKey: secret_access_key,
+            }).tap do |bson|
+              unless session_token.nil?
+                bson.update({ sessionToken: session_token })
+              end
+            end
+          end
+        end
+
+        # AWS KMS master key document object contains KMS master key parameters.
+        #
+        # @api private
+        class MasterKeyDocument
+          include KMS::Validations
+
+          # @return [ String ] AWS region.
+          attr_reader :region
+
+          # @return [ String ] AWS KMS key.
+          attr_reader :key
+
+          # @return [ String | nil ] AWS KMS endpoint.
+          attr_reader :endpoint
+
+          FORMAT_HINT = "AWS key document  must be in the format: " +
+                        "{ region: 'REGION', key: 'KEY' }"
+
+          # Creates a master key document object form a parameters hash.
+          #
+          # @param [ Hash ] opts A hash that contains master key options for
+          #   the AWS KMS provider.
+          # @option opts [ String ] :region AWS region.
+          # @option opts [ String ] :key AWS KMS key.
+          # @option opts [ String | nil ] :endpoint AWS KMS endpoint, optional.
+          #
+          # @raise [ ArgumentError ] If required options are missing or incorrectly.
+          def initialize(opts)
+            unless opts.is_a?(Hash)
+              raise ArgumentError.new(
+                'Key document options must contain a key named :master_key with a Hash value'
+              )
+            end
+            @region = validate_param(:region, opts, FORMAT_HINT)
+            @key = validate_param(:key, opts, FORMAT_HINT)
+            @endpoint = validate_param(:endpoint, opts, FORMAT_HINT, required: false)
+          end
+
+          # Convert master key document object to a BSON document in libmongocrypt format.
+          #
+          # @return [ BSON::Document ] AWS KMS master key document in libmongocrypt format.
+          def to_document
+            BSON::Document.new({
+              provider: 'aws',
+              region: region,
+              key: key,
+            }).tap do |bson|
+              unless endpoint.nil?
+                bson.update({ endpoint: endpoint })
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mongo/crypt/kms/azure.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+# encoding: utf-8
+
+# Copyright (C) 2019-2021 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
+    module KMS
+      module Azure
+        # Azure KMS Credentials object contains credentials for using Azure KMS provider.
+        #
+        # @api private
+        class Credentials
+          extend Forwardable
+          include KMS::Validations
+
+          # @return [ String ] Azure tenant id.
+          attr_reader :tenant_id
+
+          # @return [ String ] Azure client id.
+          attr_reader :client_id
+
+          # @return [ String ] Azure client secret.
+          attr_reader :client_secret
+
+          # @return [ String | nil ] Azure identity platform endpoint.
+          attr_reader :identity_platform_endpoint
+
+          # @api private
+          def_delegator :@opts, :empty?
+
+          FORMAT_HINT = "Azure KMS provider options must be in the format: " +
+              "{ tenant_id: 'TENANT-ID', client_id: 'TENANT_ID', client_secret: 'CLIENT_SECRET' }"
+
+          # Creates an Azure KMS credentials object form a parameters hash.
+          #
+          # @param [ Hash ] opts A hash that contains credentials for
+          #   Azure KMS provider
+          # @option opts [ String ] :tenant_id Azure tenant id.
+          # @option opts [ String ] :client_id Azure client id.
+          # @option opts [ String ] :client_secret Azure client secret.
+          # @option opts [ String | nil ] :identity_platform_endpoint Azure
+          #   identity platform endpoint, optional.
+          #
+          # @raise [ ArgumentError ] If required options are missing or incorrectly
+          #   formatted.
+          def initialize(opts)
+            @opts = opts
+            unless empty?
+              @tenant_id = validate_param(:tenant_id, opts, FORMAT_HINT)
+              @client_id = validate_param(:client_id, opts, FORMAT_HINT)
+              @client_secret = validate_param(:client_secret, opts, FORMAT_HINT)
+              @identity_platform_endpoint = validate_param(
+                :identity_platform_endpoint, opts, FORMAT_HINT, required: false
+              )
+            end
+          end
+
+          # Convert credentials object to a BSON document in libmongocrypt format.
+          #
+          # @return [ BSON::Document ] Azure KMS credentials in libmongocrypt format.
+          def to_document
+            return BSON::Document.new if empty?
+            BSON::Document.new({
+              tenantId: @tenant_id,
+              clientId: @client_id,
+              clientSecret: @client_secret,
+            }).tap do |bson|
+              unless identity_platform_endpoint.nil?
+                bson.update({ identityPlatformEndpoint: identity_platform_endpoint })
+              end
+            end
+          end
+        end
+
+        # Azure KMS master key document object contains KMS master key parameters.
+        #
+        # @api private
+        class MasterKeyDocument
+          include KMS::Validations
+
+          # @return [ String ] Azure key vault endpoint.
+          attr_reader :key_vault_endpoint
+
+          # @return [ String ] Azure KMS key name.
+          attr_reader :key_name
+
+          # @return [ String | nil ] Azure KMS key version.
+          attr_reader :key_version
+
+          FORMAT_HINT = "Azure key document  must be in the format: " +
+                        "{ key_vault_endpoint: 'KEY_VAULT_ENDPOINT', key_name: 'KEY_NAME' }"
+
+        # Creates a master key document object form a parameters hash.
+        #
+        # @param [ Hash ] opts A hash that contains master key options for
+        #   the Azure KMS provider.
+        # @option opts [ String ] :key_vault_endpoint Azure key vault endpoint.
+        # @option opts [ String ] :key_name Azure KMS key name.
+        # @option opts [ String | nil ] :key_version Azure KMS key version, optional.
+        #
+        # @raise [ ArgumentError ] If required options are missing or incorrectly.
+          def initialize(opts)
+            unless opts.is_a?(Hash)
+              raise ArgumentError.new(
+                'Key document options must contain a key named :master_key with a Hash value'
+              )
+            end
+            @key_vault_endpoint = validate_param(:key_vault_endpoint, opts, FORMAT_HINT)
+            @key_name = validate_param(:key_name, opts, FORMAT_HINT)
+            @key_version = validate_param(:key_version, opts, FORMAT_HINT, required: false)
+          end
+
+          # Convert master key document object to a BSON document in libmongocrypt format.
+          #
+          # @return [ BSON::Document ] Azure KMS credentials in libmongocrypt format.
+          def to_document
+            BSON::Document.new({
+              provider: 'azure',
+              keyVaultEndpoint: key_vault_endpoint,
+              keyName: key_name,
+            }).tap do |bson|
+              unless key_version.nil?
+                bson.update({ keyVersion: key_version })
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end