mongo 2.18.2 → 2.19.0

data/lib/mongo/crypt/explicit_decryption_context.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 # Copyright (C) 2019-2020 MongoDB Inc.
 #

data/lib/mongo/crypt/explicit_encrypter.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 # Copyright (C) 2020 MongoDB Inc.
 #
@@ -17,12 +16,13 @@
 
 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
+      extend Forwardable
+
       # Create a new ExplicitEncrypter object.
       #
       # @param [ Mongo::Client ] key_vault_client An instance of Mongo::Client
@@ -36,6 +36,7 @@ module Mongo
       #   should be hashes of TLS connection options. The options are equivalent
       #   to TLS connection options of Mongo::Client.
       def initialize(key_vault_client, key_vault_namespace, kms_providers, kms_tls_options)
+        Crypt.validate_ffi!
         @crypt_handle = Handle.new(
           kms_providers,
           kms_tls_options,
@@ -44,7 +45,7 @@ module Mongo
         @encryption_io = EncryptionIO.new(
           key_vault_client: key_vault_client,
           metadata_client: nil,
-          key_vault_namespace: key_vault_namespace,
+          key_vault_namespace: key_vault_namespace
         )
       end
 
@@ -108,7 +109,66 @@ module Mongo
         Crypt::ExplicitEncryptionContext.new(
           @crypt_handle,
           @encryption_io,
-          { 'v': value },
+          { v: value },
+          options
+        ).run_state_machine['v']
+      end
+
+      # Encrypts a Match Expression or Aggregate Expression to query a range index.
+      #
+      # @example Encrypt Match Expression.
+      #   encryption.encrypt_expression(
+      #     {'$and' =>  [{'field' => {'$gt' => 10}}, {'field' =>  {'$lt' => 20 }}]}
+      #   )
+      # @example Encrypt Aggregate Expression.
+      #   encryption.encrypt_expression(
+      #     {'$and' =>  [{'$gt' => ['$field', 10]}, {'$lt' => ['$field', 20]}}
+      #   )
+      #   {$and: [{$gt: [<fieldpath>, <value1>]}, {$lt: [<fieldpath>, <value2>]}]
+      # Only supported when queryType is "rangePreview" and algorithm is "RangePreview".
+      # @note: The Range algorithm is experimental only. It is not intended
+      #   for public use. It is subject to breaking changes.
+      #
+      # @param [ Hash ] expression Expression 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
+      #   expression. The only allowed value is "RangePreview"
+      # @option options [ Integer | nil ] :contention_factor Contention factor
+      #   to be applied If not  provided, it defaults to a value of 0.
+      # @option options [ String | nil ] query_type Query type to be applied.
+      #   The only allowed value is "rangePreview".
+      # @option options [ Hash | nil ] :range_opts Specifies index options for
+      #   a Queryable Encryption field supporting "rangePreview" queries.
+      #   Allowed options are:
+      #   - :min
+      #   - :max
+      #   - :sparsity
+      #   - :precision
+      #   min, max, sparsity, and range must match the values set in
+      #   the encryptedFields of the destination collection.
+      #   For double and decimal128, min/max/precision must all be set,
+      #   or all be unset.
+      #
+      # @note The RangePreview algorithm is experimental only. It is not
+      # intended for public use.
+      #
+      # @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 expression.
+      #
+      # @raise [ ArgumentError ] if disallowed values in options are set.
+      def encrypt_expression(expression, options)
+        Crypt::ExplicitEncryptionExpressionContext.new(
+          @crypt_handle,
+          @encryption_io,
+          { v: expression },
           options
         ).run_state_machine['v']
       end
@@ -120,10 +180,10 @@ module Mongo
       #
       # @return [ Object ] The decrypted value
       def decrypt(value)
-        result = Crypt::ExplicitDecryptionContext.new(
+        Crypt::ExplicitDecryptionContext.new(
           @crypt_handle,
           @encryption_io,
-          { 'v': value },
+          { v: value }
         ).run_state_machine['v']
       end
 
@@ -144,9 +204,7 @@ module Mongo
       #
       # @return [ Operation::Result ] The response from the database for the delete_one
       #   operation that deletes the key.
-      def delete_key(id)
-        @encryption_io.delete_key(id)
-      end
+      def_delegators :@encryption_io, :delete_key
 
       # Finds a single key with the given id.
       #
@@ -154,9 +212,7 @@ module Mongo
       #
       # @return [ BSON::Document | nil ] The found key document or nil
       #   if not found.
-      def get_key(id)
-        @encryption_io.get_key(id)
-      end
+      def_delegators :@encryption_io, :get_key
 
       # Returns a key in the key vault collection with the given key_alt_name.
       #
@@ -164,16 +220,12 @@ module Mongo
       #
       # @return [ BSON::Document | nil ] The found key document or nil
       #   if not found.
-      def get_key_by_alt_name(key_alt_name)
-        @encryption_io.get_key_by_alt_name(key_alt_name)
-      end
+      def_delegators :@encryption_io, :get_key_by_alt_name
 
       # Returns all keys in the key vault collection.
       #
       # @return [ Collection::View ] Keys in the key vault collection.
-      def get_keys
-        @encryption_io.get_keys
-      end
+      def_delegators :@encryption_io, :get_keys
 
       # Removes a key_alt_name from a key in the key vault collection with the given id.
       #
@@ -182,9 +234,7 @@ module Mongo
       #
       # @return [ BSON::Document | nil ] Document describing the identified key
       #   before removing the key alt name, or nil if no such key.
-      def remove_key_alt_name(id, key_alt_name)
-        @encryption_io.remove_key_alt_name(id, key_alt_name)
-      end
+      def_delegators :@encryption_io, :remove_key_alt_name
 
       # Decrypts multiple data keys and (re-)encrypts them with a new master_key,
       #   or with their current master_key if a new one is not given.
@@ -198,11 +248,9 @@ module Mongo
       #
       # @return [ Crypt::RewrapManyDataKeyResult ] Result of the operation.
       def rewrap_many_data_key(filter, opts = {})
-        master_key_document = if opts[:provider]
-          options = opts.dup
-          provider = options.delete(:provider)
-          KMS::MasterKeyDocument.new(provider, options)
-        end
+        validate_rewrap_options!(opts)
+
+        master_key_document = master_key_for_provider(opts)
 
         rewrap_result = Crypt::RewrapManyDataKeyContext.new(
           @crypt_handle,
@@ -210,11 +258,52 @@ module Mongo
           filter,
           master_key_document
         ).run_state_machine
-        if rewrap_result.nil?
-          return RewrapManyDataKeyResult.new(nil)
-        end
-        data_key_documents = rewrap_result.fetch('v')
-        updates = data_key_documents.map do |doc|
+
+        return RewrapManyDataKeyResult.new(nil) if rewrap_result.nil?
+
+        updates = updates_from_data_key_documents(rewrap_result.fetch('v'))
+        RewrapManyDataKeyResult.new(@encryption_io.update_data_keys(updates))
+      end
+
+      private
+
+      # Ensures the consistency of the options passed to #rewrap_many_data_keys.
+      #
+      # @param [ Hash ] opts the options hash to validate
+      #
+      # @raise [ ArgumentError ] if the options are not consistent or
+      #   compatible.
+      def validate_rewrap_options!(opts)
+        return unless opts.key?(:master_key) && !opts.key?(:provider)
+
+        raise ArgumentError, 'If :master_key is specified, :provider must also be given'
+      end
+
+      # If a :provider is given, construct a new master key document
+      # with that provider.
+      #
+      # @param [ Hash ] opts the options hash
+      #
+      # @option [ String ] :provider KMS provider to encrypt keys.
+      #
+      # @return [ KMS::MasterKeyDocument | nil ] the new master key document,
+      #   or nil if no provider was given.
+      def master_key_for_provider(opts)
+        return nil unless opts[:provider]
+
+        options = opts.dup
+        provider = options.delete(:provider)
+        KMS::MasterKeyDocument.new(provider, options)
+      end
+
+      # Returns the corresponding update document for each for of the given
+      # data key documents.
+      #
+      # @param [ Array<Hash> ] documents the data key documents
+      #
+      # @return [ Array<Hash> ] the update documents
+      def updates_from_data_key_documents(documents)
+        documents.map do |doc|
           {
             update_one: {
               filter: { _id: doc[:_id] },
@@ -228,9 +317,6 @@ module Mongo
             }
           }
         end
-        RewrapManyDataKeyResult.new(
-          @encryption_io.update_data_keys(updates)
-        )
       end
     end
   end

data/lib/mongo/crypt/explicit_encryption_context.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 # Copyright (C) 2019-2020 MongoDB Inc.
 #
@@ -31,35 +31,57 @@ module Mongo
       #   that implements driver I/O methods required to run the
       #   state machine
       # @param [ BSON::Document ] doc A document to encrypt
-      # @param [ Hash ] options
       #
+      # @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",
-      #   "AEAD_AES_256_CBC_HMAC_SHA_512-Random", "Indexed", "Unindexed".
+      #   "AEAD_AES_256_CBC_HMAC_SHA_512-Random", "Indexed", "Unindexed", "RangePreview".
       # @option options [ Integer | nil ] :contention_factor Contention factor
       #   to be applied if encryption algorithm is set to "Indexed". If not
       #   provided, it defaults to a value of 0. Contention factor should be set
       #   only if encryption algorithm is set to "Indexed".
       # @option options [ String | nil ] query_type Query type to be applied
-      # if encryption algorithm is set to "Indexed". Query type should be set
-      #   only if encryption algorithm is set to "Indexed".  The only allowed
-      #   value is "equality".
+      #   if encryption algorithm is set to "Indexed" or "RangePreview".
+      #   Allowed values are "equality" and "rangePreview".
+      # @option options [ Hash | nil ] :range_opts Specifies index options for
+      #   a Queryable Encryption field supporting "rangePreview" queries.
+      #   Allowed options are:
+      #   - :min
+      #   - :max
+      #   - :sparsity
+      #   - :precision
+      #   min, max, sparsity, and range must match the values set in
+      #   the encryptedFields of the destination collection.
+      #   For double and decimal128, min/max/precision must all be set,
+      #   or all be unset.
+      #
+      # @note The RangePreview algorithm is experimental only. It is not intended for
+      # public use.
       #
       # @raise [ ArgumentError|Mongo::Error::CryptError ] If invalid options are provided
-      def initialize(mongocrypt, io, doc, options={})
+      def initialize(mongocrypt, io, doc, options = {})
         super(mongocrypt, io)
+        set_key_opts(options)
+        set_algorithm_opts(options)
+        init(doc)
+      end
 
+      def init(doc)
+        Binding.ctx_explicit_encrypt_init(self, doc)
+      end
+
+      private
+      def set_key_opts(options)
         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. ' +
@@ -67,30 +89,34 @@ module Mongo
             '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
+          set_key_id(options[:key_id])
+        elsif options[:key_alt_name]
+          set_key_alt_name(options[:key_alt_name])
+        end
+      end
+
+      def set_key_id(key_id)
+        unless key_id.is_a?(BSON::Binary) &&
+            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"
+                "type :uuid. #{key_id} is an invalid :key_id option"
               )
           end
+          Binding.ctx_setopt_key_id(self, key_id.data)
+      end
 
-          Binding.ctx_setopt_key_id(self, options[:key_id].data)
-        elsif options[:key_alt_name]
-          unless options[:key_alt_name].is_a?(String)
+      def set_key_alt_name(key_alt_name)
+        unless 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
+          Binding.ctx_setopt_key_alt_names(self, [key_alt_name])
+      end
 
-        # Set the algorithm option on the mongocrypt_ctx_t object and raises
-        # an exception if the algorithm is invalid.
+      def set_algorithm_opts(options)
         Binding.ctx_setopt_algorithm(self, options[:algorithm])
-        if options[:algorithm] == 'Indexed'
+        if %w(Indexed RangePreview).include?(options[:algorithm])
           if options[:contention_factor]
             Binding.ctx_setopt_contention_factor(self, options[:contention_factor])
           end
@@ -99,16 +125,21 @@ module Mongo
           end
         else
           if options[:contention_factor]
-            raise ArgumentError.new(':contention_factor is allowed only for "Indexed" algorithm')
+            raise ArgumentError.new(':contention_factor is allowed only for "Indexed" or "RangePreview" algorithms')
           end
           if options[:query_type]
-            raise ArgumentError.new(':query_type is allowed only for "Indexed" algorithm')
+            raise ArgumentError.new(':query_type is allowed only for "Indexed" or "RangePreview" algorithms')
           end
         end
+        if options[:algorithm] == 'RangePreview'
+          Binding.ctx_setopt_algorithm_range(self, convert_range_opts(options[:range_opts]))
+        end
+      end
 
-        # Initializes the mongocrypt_ctx_t object for explicit encryption and
-        # passes in the value to be encrypted.
-        Binding.ctx_explicit_encrypt_init(self, doc)
+      def convert_range_opts(range_opts)
+        range_opts.dup.tap do |opts|
+          opts[:sparsity] = BSON::Int64.new(opts[:sparsity]) unless opts[:sparsity].is_a?(BSON::Int64)
+        end
       end
     end
   end

data/lib/mongo/crypt/explicit_encryption_expression_context.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+# rubocop:todo all
+
+# Copyright (C) 2019-2020 MongoDB Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module Mongo
+  module Crypt
+
+    # A Context object initialized for explicit expression encryption.
+    #
+    # @api private
+    class ExplicitEncryptionExpressionContext < ExplicitEncryptionContext
+      def init(doc)
+        Binding.ctx_explicit_encrypt_expression_init(self, doc)
+      end
+    end
+  end
+end

data/lib/mongo/crypt/handle.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 # Copyright (C) 2019-2020 MongoDB Inc.
 #
@@ -28,6 +28,9 @@ module Mongo
     # @api private
     class Handle
 
+      # @returns [ Crypt::KMS::Credentials ] Credentials for KMS providers.
+      attr_reader :kms_providers
+
       # Creates a new Handle object and initializes it with options
       #
       # @param [ Crypt::KMS::Credentials ] kms_providers Credentials for KMS providers.
@@ -69,6 +72,7 @@ module Mongo
           Binding.method(:mongocrypt_destroy)
         )
 
+        @kms_providers = kms_providers
         @kms_tls_options =  kms_tls_options
 
         maybe_set_schema_map(options)
@@ -92,7 +96,11 @@ module Mongo
 
         set_crypto_hooks
 
-        Binding.setopt_kms_providers(self, kms_providers.to_document)
+        Binding.setopt_kms_providers(self, @kms_providers.to_document)
+
+        if @kms_providers.aws&.empty? || @kms_providers.gcp&.empty? || @kms_providers.azure&.empty?
+          Binding.setopt_use_need_kms_credentials_state(self)
+        end
 
         initialize_mongocrypt
 

data/lib/mongo/crypt/hooks.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 # Copyright (C) 2019-2020 MongoDB Inc.
 #

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

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+# rubocop:todo all
+
+# 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
+      end
+    end
+  end
+end
+

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

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+# rubocop:todo all
+
+# 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 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