mongo 2.17.4 → 2.18.0.beta1

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,128 @@
+# 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
+          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
+
+          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)
+            @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
+
+          # Convert credentials object to a BSON document in libmongocrypt format.
+          #
+          # @return [ BSON::Document ] AWS KMS credentials in libmongocrypt format.
+          def to_document
+            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,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 Azure
+        # Azure KMS Credentials object contains credentials for using Azure KMS provider.
+        #
+        # @api private
+        class Credentials
+          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
+
+          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)
+            @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
+
+          # Convert credentials object to a BSON document in libmongocrypt format.
+          #
+          # @return [ BSON::Document ] Azure KMS credentials in libmongocrypt format.
+          def to_document
+            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

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

@@ -0,0 +1,81 @@
+# 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
+
+      # KMS Credentials object contains credentials for using KMS providers.
+      #
+      # @api private
+      class Credentials
+
+        # Creates a KMS credentials object form a parameters hash.
+        #
+        # @param [ Hash ] kms_providers A hash that contains credential for
+        #   KMS providers. The hash should have KMS provider names as keys,
+        #   and required parameters for every provider as values.
+        #   Required parameters for KMS providers are described in corresponding
+        #   classes inside Mongo::Crypt::KMS module.
+        #
+        # @note There may be more than one KMS provider specified.
+        #
+        # @raise [ ArgumentError ] If required options are missing or incorrectly
+        #   formatted.
+        def initialize(kms_providers)
+          if kms_providers.nil?
+            raise ArgumentError.new("KMS providers options must not be nil")
+          end
+          if kms_providers.key?(:aws)
+            @aws = AWS::Credentials.new(kms_providers[:aws])
+          end
+          if kms_providers.key?(:azure)
+            @azure = Azure::Credentials.new(kms_providers[:azure])
+          end
+          if kms_providers.key?(:gcp)
+            @gcp = GCP::Credentials.new(kms_providers[:gcp])
+          end
+          if kms_providers.key?(:kmip)
+            @kmip = KMIP::Credentials.new(kms_providers[:kmip])
+          end
+          if kms_providers.key?(:local)
+            @local = Local::Credentials.new(kms_providers[:local])
+          end
+          if @aws.nil? && @azure.nil? && @gcp.nil? && @kmip.nil? && @local.nil?
+            raise ArgumentError.new(
+              "KMS providers options must have one of the following keys: " +
+              ":aws, :azure, :gcp, :kmip, :local"
+            )
+          end
+        end
+
+        # Convert credentials object to a BSON document in libmongocrypt format.
+        #
+        # @return [ BSON::Document ] Credentials as BSON document.
+        def to_document
+          BSON::Document.new({}).tap do |bson|
+            bson[:aws] = @aws.to_document if @aws
+            bson[:azure] = @azure.to_document if @azure
+            bson[:gcp] = @gcp.to_document if @gcp
+            bson[:kmip] = @kmip.to_document if @kmip
+            bson[:local] = @local.to_document if @local
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,182 @@
+# 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 GCP
+        # GCP Cloud Key Management Credentials object contains credentials for
+        # using GCP KMS provider.
+        #
+        # @api private
+        class Credentials
+          include KMS::Validations
+
+          # @return [ String ] GCP email to authenticate with.
+          attr_reader :email
+
+          # @return [ String ] GCP private key, base64 encoded DER format.
+          attr_reader :private_key
+
+          # @return [ String | nil ] GCP KMS endpoint.
+          attr_reader :endpoint
+
+          FORMAT_HINT = "GCP KMS provider options must be in the format: " +
+              "{ email: 'EMAIL', private_key: 'PRIVATE-KEY' }"
+
+          # Creates an GCP KMS credentials object form a parameters hash.
+          #
+          # @param [ Hash ] opts A hash that contains credentials for
+          #   GCP KMS provider
+          # @option opts [ String ] :email GCP email.
+          # @option opts [ String ] :private_key GCP private key. This method accepts
+          #   private key in either base64 encoded DER format, or PEM format.
+          # @option opts [ String | nil ] :endpoint GCP endpoint, optional.
+          #
+          # @raise [ ArgumentError ] If required options are missing or incorrectly
+          #   formatted.
+          def initialize(opts)
+            @email = validate_param(:email, opts, FORMAT_HINT)
+
+            @private_key = begin
+              private_key_opt = validate_param(:private_key, opts, FORMAT_HINT)
+              if BSON::Environment.jruby?
+                # We cannot really validate private key on JRuby, so we assume
+                # it is in base64 encoded DER format.
+                private_key_opt
+              else
+                # Check if private key is in PEM format.
+                pkey = OpenSSL::PKey::RSA.new(private_key_opt)
+                # PEM it is, need to be converted to base64 encoded DER.
+                der = if pkey.respond_to?(:private_to_der)
+                  pkey.private_to_der
+                else
+                  pkey.to_der
+                end
+                Base64.encode64(der)
+              end
+            rescue OpenSSL::PKey::RSAError
+              # Check if private key is in DER.
+              begin
+                OpenSSL::PKey.read(Base64.decode64(private_key_opt))
+                # Private key is fine, use it.
+                private_key_opt
+              rescue OpenSSL::PKey::PKeyError
+                raise ArgumentError.new(
+                  "The private_key option must be either either base64 encoded DER format, or PEM format."
+                )
+              end
+            end
+
+            @endpoint = validate_param(
+              :endpoint, opts, FORMAT_HINT, required: false
+            )
+          end
+
+          # Convert credentials object to a BSON document in libmongocrypt format.
+          #
+          # @return [ BSON::Document ] Azure KMS credentials in libmongocrypt format.
+          def to_document
+            BSON::Document.new({
+              email: email,
+              privateKey: BSON::Binary.new(private_key, :generic),
+            }).tap do |bson|
+              unless endpoint.nil?
+                bson.update({ endpoint: endpoint })
+              end
+            end
+          end
+        end
+
+        # GCP KMS master key document object contains KMS master key parameters.
+        #
+        # @api private
+        class MasterKeyDocument
+          include KMS::Validations
+
+          # @return [ String ] GCP project id.
+          attr_reader :project_id
+
+          # @return [ String ] GCP location.
+          attr_reader :location
+
+          # @return [ String ] GCP KMS key ring.
+          attr_reader :key_ring
+
+          # @return [ String ] GCP KMS key name.
+          attr_reader :key_name
+
+          # @return [ String | nil ] GCP KMS key version.
+          attr_reader :key_version
+
+          # @return [ String | nil ] GCP KMS endpoint.
+          attr_reader :endpoint
+
+          FORMAT_HINT = "GCP key document  must be in the format: " +
+                        "{ project_id: 'PROJECT_ID', location: 'LOCATION', " +
+                        "key_ring: 'KEY-RING', 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 GCP KMS provider.
+        # @option opts [ String ] :project_id GCP  project id.
+        # @option opts [ String ] :location GCP location.
+        # @option opts [ String ] :key_ring GCP KMS key ring.
+        # @option opts [ String ] :key_name GCP KMS key name.
+        # @option opts [ String | nil ] :key_version GCP KMS key version, optional.
+        # @option opts [ String | nil ] :endpoint GCP KMS key 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
+            @project_id = validate_param(:project_id, opts, FORMAT_HINT)
+            @location = validate_param(:location, opts, FORMAT_HINT)
+            @key_ring = validate_param(:key_ring, opts, FORMAT_HINT)
+            @key_name = validate_param(:key_name, opts, FORMAT_HINT)
+            @key_version = validate_param(:key_version, opts, FORMAT_HINT, required: false)
+            @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 ] GCP KMS credentials in libmongocrypt format.
+          def to_document
+            BSON::Document.new({
+              provider: 'gcp',
+              projectId: project_id,
+              location: location,
+              keyRing: key_ring,
+              keyName: key_name
+            }).tap do |bson|
+              unless key_version.nil?
+                bson.update({ keyVersion: key_version })
+              end
+              unless endpoint.nil?
+                bson.update({ endpoint: endpoint })
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,110 @@
+# 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 KMIP
+        # KMIP KMS Credentials object contains credentials for a
+        # remote KMIP KMS provider.
+        #
+        # @api private
+        class Credentials
+          include KMS::Validations
+
+          # @return [ String ] KMIP KMS endpoint with optional port.
+          attr_reader :endpoint
+
+          FORMAT_HINT = "KMIP KMS provider options must be in the format: " +
+                        "{ endpoint: 'ENDPOINT' }"
+
+          # Creates a KMIP KMS credentials object form a parameters hash.
+          #
+          # @param [ Hash ] opts A hash that contains credentials for
+          #   KMIP KMS provider.
+          # @option opts [ String ] :endpoint KMIP endpoint.
+          #
+          # @raise [ ArgumentError ] If required options are missing or incorrectly
+          #   formatted.
+          def initialize(opts)
+            @endpoint = validate_param(:endpoint, opts, FORMAT_HINT)
+          end
+
+          # Convert credentials object to a BSON document in libmongocrypt format.
+          #
+          # @return [ BSON::Document ] Local KMS credentials in libmongocrypt format.
+          def to_document
+            BSON::Document.new({
+              endpoint: endpoint,
+            })
+          end
+        end
+
+        # KMIP KMS master key document object contains KMS master key parameters.
+        #
+        # @api private
+        class MasterKeyDocument
+          include KMS::Validations
+
+          # @return [ String | nil ] The KMIP Unique Identifier to a 96 byte
+          #   KMIP Secret Data managed object.
+          attr_reader :key_id
+
+          # @return [ String | nil ] KMIP KMS endpoint with optional port.
+          attr_reader :endpoint
+
+          FORMAT_HINT = "KMIP KMS key document must be in the format: " +
+                        "{ key_id: 'KEY-ID', endpoint: 'ENDPOINT' }"
+
+          # Creates a master key document object form a parameters hash.
+          #
+          # @param [ Hash ] opts A hash that contains master key options for
+          #   KMIP KMS provider
+          # @option opts [ String ] :key_id KMIP Unique Identifier to
+          #   a 96 byte KMIP Secret Data managed object, optional. If key_id
+          #   is omitted, the driver creates a random 96 byte identifier.
+          # @option opts [ String ] :endpoint KMIP endpoint, optional.
+          #
+          # @raise [ ArgumentError ] If required options are missing or incorrectly
+          #   formatted.
+          def initialize(opts)
+            @key_id = validate_param(
+              :key_id, opts, FORMAT_HINT, required: false
+            ) || SecureRandom.alphanumeric(96)
+            @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 ] KMIP KMS credentials in libmongocrypt format.
+          def to_document
+            BSON::Document.new({
+              provider: 'kmip',
+              keyId: key_id
+            }).tap do |bson|
+              unless endpoint.nil?
+                bson.update({ endpoint: endpoint })
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end