mongo 2.17.1 → 2.18.1

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,189 @@
+# 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
+          extend Forwardable
+          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
+
+          # @api private
+          def_delegator :@opts, :empty?
+
+          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)
+            @opts = opts
+            return if empty?
+
+            @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
+            return BSON::Document.new if empty?
+            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)
+            if opts.empty?
+              @empty = true
+              return
+            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
+            return BSON::Document.new({}) if @empty
+            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,116 @@
+# 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
+          extend Forwardable
+          include KMS::Validations
+
+          # @return [ String ] KMIP KMS endpoint with optional port.
+          attr_reader :endpoint
+
+          # @api private
+          def_delegator :@opts, :empty?
+
+          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)
+            @opts = opts
+            unless empty?
+              @endpoint = validate_param(:endpoint, opts, FORMAT_HINT)
+            end
+          end
+
+          # Convert credentials object to a BSON document in libmongocrypt format.
+          #
+          # @return [ BSON::Document ] Local KMS credentials in libmongocrypt format.
+          def to_document
+            return BSON::Document.new({}) if empty?
+            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 | nil ] :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 | nil ] :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
+            )
+            @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',
+            }).tap do |bson|
+              bson.update({ endpoint: endpoint }) unless endpoint.nil?
+              bson.update({ keyId: key_id }) unless key_id.nil?
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,82 @@
+# 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 Local
+        # Local KMS Credentials object contains credentials for using local KMS provider.
+        #
+        # @api private
+        class Credentials
+          extend Forwardable
+          include KMS::Validations
+
+          # @return [ String ] Master key.
+          attr_reader :key
+
+          # @api private
+          def_delegator :@opts, :empty?
+
+          FORMAT_HINT = "Local KMS provider options must be in the format: " +
+                        "{ key: 'MASTER-KEY' }"
+
+          # Creates a local KMS credentials object form a parameters hash.
+          #
+          # @param [ Hash ] opts A hash that contains credentials for
+          #   local KMS provider
+          # @option opts [ String ] :key Master key.
+          #
+          # @raise [ ArgumentError ] If required options are missing or incorrectly
+          #   formatted.
+          def initialize(opts)
+            @opts = opts
+            unless empty?
+              @key = validate_param(:key, opts, FORMAT_HINT)
+            end
+          end
+
+          # @return [ BSON::Document ] Local KMS credentials in libmongocrypt format.
+          def to_document
+            return BSON::Document.new({}) if empty?
+            BSON::Document.new({
+              key: BSON::Binary.new(@key, :generic),
+            })
+          end
+        end
+
+        # Local KMS master key document object contains KMS master key parameters.
+        #
+        # @api private
+        class MasterKeyDocument
+
+          # Creates a master key document object form a parameters hash.
+          # This empty method is to keep a uniform interface for all KMS providers.
+          def initialize(_opts)
+          end
+
+          # Convert master key document object to a BSON document in libmongocrypt format.
+          #
+          # @return [ BSON::Document ] Local KMS credentials in libmongocrypt format.
+          def to_document
+            BSON::Document.new({ provider: "local" })
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+# 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 master key document object contains KMS master key parameters
+      # that are used for creation of data keys.
+      #
+      # @api private
+      class MasterKeyDocument
+
+        # Known KMS provider names.
+        KMS_PROVIDERS = %w(aws azure gcp kmip local).freeze
+
+        # Creates a master key document object form a parameters hash.
+        #
+        # @param [ String ] kms_provider. KMS provider name.
+        # @param [ Hash ] options A hash that contains master key options for
+        #   the KMS provider.
+        #   Required parameters for KMS providers are described in corresponding
+        #   classes inside Mongo::Crypt::KMS module.
+        #
+        # @raise [ ArgumentError ] If required options are missing or incorrectly.
+        def initialize(kms_provider, options)
+          if options.nil?
+            raise ArgumentError.new('Key document options must not be nil')
+          end
+          master_key = options.fetch(:master_key, {})
+          @key_document = case kms_provider.to_s
+            when 'aws' then KMS::AWS::MasterKeyDocument.new(master_key)
+            when 'azure' then KMS::Azure::MasterKeyDocument.new(master_key)
+            when 'gcp' then KMS::GCP::MasterKeyDocument.new(master_key)
+            when 'kmip' then KMS::KMIP::MasterKeyDocument.new(master_key)
+            when 'local' then KMS::Local::MasterKeyDocument.new(master_key)
+            else
+              raise ArgumentError.new("KMS provider must be one of #{KMS_PROVIDERS}")
+          end
+        end
+
+        # Convert master key document object to a BSON document in libmongocrypt format.
+        #
+        # @return [ BSON::Document ] Master key document as BSON document.
+        def to_document
+          @key_document.to_document
+        end
+      end
+    end
+  end
+end

data/lib/mongo/crypt/kms.rb

@@ -0,0 +1,117 @@
+# 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
+      # This module contains helper methods for validating KMS parameters.
+      #
+      # @api private
+      module Validations
+        # Validate if a KMS parameter is valid.
+        #
+        # @param [ Symbol ] key The parameter name.
+        # @param [ Hash ] opts Hash should contain the parameter under the key.
+        # @param [ Boolean ] required Whether the parameter is required or not.
+        #   Non-required parameters can be nil.
+        #
+        # @return [ String | nil ] String parameter value or nil if a
+        #   non-required parameter is missing.
+        #
+        # @raise [ ArgumentError ] If required options are missing or incorrectly
+        #   formatted.
+        def validate_param(key, opts, format_hint, required: true)
+          value = opts.fetch(key)
+          return nil if value.nil? && !required
+          if value.nil?
+            raise ArgumentError.new(
+              "The #{key} option must be a String with at least one character; " \
+              "currently have nil"
+            )
+          end
+          unless value.is_a?(String)
+            raise ArgumentError.new(
+              "The #{key} option must be a String with at least one character; " \
+              "currently have #{value}"
+            )
+          end
+          if value.empty?
+            raise ArgumentError.new(
+              "The #{key} option must be a String with at least one character; " \
+              "it is currently an empty string"
+            )
+          end
+          value
+        rescue KeyError
+          if required
+            raise ArgumentError.new(
+              "The specified KMS provider options are invalid: #{opts}. " +
+              format_hint
+            )
+          else
+            nil
+          end
+        end
+
+        # Validate KMS TLS options.
+        #
+        # @param [ Hash | nil ] 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.
+        #
+        # @return [ Hash ] Provided TLS options if valid.
+        #
+        # @raise [ ArgumentError ] If required options are missing or incorrectly
+        #   formatted.
+        def validate_tls_options(options)
+          opts = options || {}
+          opts.each do |provider, provider_opts|
+            if provider_opts[:ssl] == false || opts[:tls] == false
+              raise ArgumentError.new(
+                "Incorrect TLS options for #{provider}: TLS is required"
+              )
+            end
+            %i(
+              ssl_verify_certificate
+              ssl_verify_hostname
+              ssl_verify_ocsp_endpoint
+            ).each do |opt|
+              if provider_opts[opt] == false
+                raise ArgumentError.new(
+                  "Incorrect TLS options for #{provider}: " +
+                  'Insecure TLS options prohibited, ' +
+                  "#{opt} cannot be set to false for KMS"
+                )
+              end
+            end
+          end
+          opts
+        end
+        module_function :validate_tls_options
+      end
+    end
+  end
+end
+
+require "mongo/crypt/kms/credentials"
+require "mongo/crypt/kms/master_key_document"
+require 'mongo/crypt/kms/aws'
+require 'mongo/crypt/kms/azure'
+require 'mongo/crypt/kms/gcp'
+require 'mongo/crypt/kms/kmip'
+require 'mongo/crypt/kms/local'

data/lib/mongo/crypt/rewrap_many_data_key_context.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+# encoding: utf-8
+
+# 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 specifically for the purpose of rewrapping
+    # data keys (decrypting and re-rencryting using a new KEK).
+    #
+    # @api private
+    class RewrapManyDataKeyContext < Context
+
+      # Create a new RewrapManyDataKeyContext object
+      #
+      # @param [ Mongo::Crypt::Handle ] mongocrypt a Handle that
+      #   wraps a mongocrypt_t object used to create a new mongocrypt_ctx_t
+      # @param [ Mongo::Crypt::EncryptionIO ] io An object that performs all
+      #   driver I/O on behalf of libmongocrypt
+      # @param [ Hash ] filter Filter used to find keys to be updated.
+      #   alternate names for the new data key.
+      # @param [ Mongo::Crypt::KMS::MasterKeyDocument | nil ] master_key_document The optional master
+      #   key document that contains master encryption key parameters.
+      def initialize(mongocrypt, io, filter, master_key_document)
+        super(mongocrypt, io)
+        if master_key_document
+          Binding.ctx_setopt_key_encryption_key(self, master_key_document.to_document)
+        end
+        Binding.ctx_rewrap_many_datakey_init(self, filter)
+      end
+    end
+  end
+end