mongo 2.11.6 → 2.12.0.rc0

data/lib/mongo/crypt/context.rb

@@ -0,0 +1,135 @@
+# Copyright (C) 2019 MongoDB, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module Mongo
+  module Crypt
+
+    # A wrapper around mongocrypt_ctx_t, which manages the
+    # state machine for encryption and decription.
+    #
+    # This class is a superclass that defines shared methods
+    # amongst contexts that are initialized for different purposes
+    # (e.g. data key creation, encryption, explicit encryption, etc.)
+    #
+    # @api private
+    class Context
+      #  Create a new Context object
+      #
+      # @param [ FFI::Pointer ] ctx A pointer to a mongocrypt_t object
+      #   used to create a new mongocrypt_ctx_t
+      # @param [ ClientEncryption::IO ] A instance of the IO class
+      #   that implements driver I/O methods required to run the
+      #   state machine
+      def initialize(mongocrypt_handle, io)
+        # Ideally, this level of the API wouldn't be passing around pointer
+        # references between objects, so this method signature is subject to change.
+
+        # FFI::AutoPointer uses a custom release strategy to automatically free
+        # the pointer once this object goes out of scope
+        @ctx_p = FFI::AutoPointer.new(
+          Binding.mongocrypt_ctx_new(mongocrypt_handle.ref),
+          Binding.method(:mongocrypt_ctx_destroy)
+        )
+
+        @encryption_io = io
+      end
+
+      attr_reader :ctx_p
+
+      # Returns the state of the mongocrypt_ctx_t
+      #
+      # @return [ Symbol ] The context state
+      def state
+        Binding.mongocrypt_ctx_state(@ctx_p)
+      end
+
+      # Runs the mongocrypt_ctx_t state machine and handles
+      # all I/O on behalf of libmongocrypt
+      #
+      # @return [ BSON::Document ] A BSON document representing the outcome
+      #   of the state machine. Contents can differ depending on how the
+      #   context was initialized..
+      #
+      # @raise [ Error::CryptError ] If the state machine enters the
+      #   :error state
+      #
+      # This method is not currently unit tested. It is integration tested
+      # in spec/integration/explicit_encryption_spec.rb
+      def run_state_machine
+        while true
+          case state
+          when :error
+            Binding.check_ctx_status(self)
+          when :ready
+            # Finalize the state machine and return the result as a BSON::Document
+            return Binding.ctx_finalize(self)
+          when :done
+            return nil
+          when :need_mongo_keys
+            filter = Binding.ctx_mongo_op(self)
+
+            @encryption_io.find_keys(filter).each do |key|
+              mongocrypt_feed(key) if key
+            end
+
+            mongocrypt_done
+          when :need_mongo_collinfo
+            filter = Binding.ctx_mongo_op(self)
+
+            result = @encryption_io.collection_info(@db_name, filter)
+            mongocrypt_feed(result) if result
+
+            mongocrypt_done
+          when :need_mongo_markings
+            cmd = Binding.ctx_mongo_op(self)
+
+            result = @encryption_io.mark_command(cmd)
+            mongocrypt_feed(result)
+
+            mongocrypt_done
+          when :need_kms
+            while kms_context = Binding.ctx_next_kms_ctx(self) do
+              @encryption_io.feed_kms(kms_context)
+            end
+
+            Binding.ctx_kms_done(self)
+          else
+            raise Error::CryptError.new(
+              # TODO: fix CryptError to improve this API -- the first argument
+              # in the initializer should not be optional
+              nil,
+              "State #{state} is not supported by Mongo::Crypt::Context"
+            )
+          end
+        end
+      end
+
+      private
+
+      # Indicate that state machine is done feeding I/O responses back to libmongocrypt
+      def mongocrypt_done
+        Binding.mongocrypt_ctx_mongo_done(ctx_p)
+      end
+
+      # Feeds the result of a Mongo operation back to libmongocrypt.
+      #
+      # @param [ Hash ] doc BSON document to feed.
+      #
+      # @return [ BSON::Document ] BSON document containing the result.
+      def mongocrypt_feed(doc)
+        Binding.ctx_mongo_feed(self, doc)
+      end
+    end
+  end
+end

data/lib/mongo/crypt/data_key_context.rb

@@ -0,0 +1,162 @@
+# Copyright (C) 2019 MongoDB, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module Mongo
+  module Crypt
+
+    # A Context object initialized specifically for the purpose of creating
+    # a data key in the key managemenet system.
+    #
+    # @api private
+    class DataKeyContext < Context
+
+      # Create a new DataKeyContext 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 [ String ] kms_provider The KMS provider to use. Options are
+      #   "aws" and "local".
+      # @param [ Hash ] options Data key creation options.
+      #
+      # @option options [ Hash ] :master_key A Hash of options related to the AWS
+      #   KMS provider option. Required if kms_provider is "aws".
+      #   - :region [ String ] The The AWS region of the master key (required).
+      #   - :key [ String ] The Amazon Resource Name (ARN) of the master key (required).
+      #   - :endpoint [ String ] An alternate host to send KMS requests to (optional).
+      # @option options [ Array<String> ] :key_alt_names An optional array of strings specifying
+      #   alternate names for the new data key.
+      def initialize(mongocrypt, io, kms_provider, options={})
+        super(mongocrypt, io)
+
+        case kms_provider
+        when 'local'
+          Binding.ctx_setopt_master_key_local(self)
+        when 'aws'
+          unless options
+            raise ArgumentError.new(
+              'When "aws" is specified as the KMS provider, options cannot be nil'
+            )
+          end
+
+          unless options.key?(:master_key)
+            raise ArgumentError.new(
+              'When "aws" is specified as the KMS provider, the options Hash ' +
+              'must contain a key named :master_key with a Hash value in the ' +
+              '{ region: "AWS-REGION", key: "AWS-KEY-ARN" }'
+            )
+          end
+
+          master_key_opts = options[:master_key]
+
+          set_aws_master_key(master_key_opts)
+          set_aws_endpoint(master_key_opts[:endpoint]) if master_key_opts[:endpoint]
+        else
+          raise ArgumentError.new(
+            "#{kms_provider} is an invalid kms provider. " +
+            "Valid options are 'aws' and 'local'"
+          )
+        end
+
+        set_key_alt_names(options[:key_alt_names]) if options[:key_alt_names]
+        initialize_ctx
+      end
+
+      private
+
+      # Configure the underlying mongocrypt_ctx_t object to accept AWS
+      # KMS options
+      def set_aws_master_key(master_key_opts)
+        unless master_key_opts
+          raise ArgumentError.new('The :master_key option cannot be nil')
+        end
+
+        unless master_key_opts.is_a?(Hash)
+          raise ArgumentError.new(
+            "#{master_key_opts} is an invalid :master_key option. " +
+            "The :master_key option must be a Hash in the format " +
+            "{ region: 'AWS-REGION', key: 'AWS-KEY-ARN' }"
+          )
+        end
+
+        region = master_key_opts[:region]
+        unless region
+          raise ArgumentError.new(
+            'The value of :region option of the :master_key options hash cannot be nil'
+          )
+        end
+
+        unless region.is_a?(String)
+          raise ArgumentError.new(
+            "#{master_key_opts[:region]} is an invalid AWS master_key region. " +
+            "The value of :region option of the :master_key options hash must be a String"
+          )
+        end
+
+        key = master_key_opts[:key]
+        unless key
+          raise ArgumentError.new(
+            'The value of :key option of the :master_key options hash cannot be nil'
+          )
+        end
+
+        unless key.is_a?(String)
+          raise ArgumentError.new(
+            "#{master_key_opts[:key]} is an invalid AWS master_key key. " +
+            "The value of :key option of the :master_key options hash must be a String"
+          )
+        end
+
+        Binding.ctx_setopt_master_key_aws(
+          self,
+          region,
+          key,
+        )
+      end
+
+      def set_aws_endpoint(endpoint)
+        unless endpoint.is_a?(String)
+          raise ArgumentError.new(
+            "#{endpoint} is an invalid AWS master_key endpoint. " +
+            "The value of :endpoint option of the :master_key options hash must be a String"
+          )
+        end
+
+        Binding.ctx_setopt_master_key_aws_endpoint(self, endpoint)
+      end
+
+      # Set the alt names option on the context
+      def set_key_alt_names(key_alt_names)
+        unless key_alt_names.is_a?(Array)
+          raise ArgumentError.new, 'The :key_alt_names option must be an Array'
+        end
+
+        unless key_alt_names.all? { |key_alt_name| key_alt_name.is_a?(String) }
+          raise ArgumentError.new(
+            "#{key_alt_names} contains an invalid alternate key name. All " +
+            "values of the :key_alt_names option Array must be Strings"
+          )
+        end
+
+        Binding.ctx_setopt_key_alt_names(self, key_alt_names)
+      end
+
+      # Initializes the underlying mongocrypt_ctx_t object
+      def initialize_ctx
+        Binding.ctx_datakey_init(self)
+      end
+    end
+  end
+end

data/lib/mongo/crypt/encryption_io.rb

@@ -0,0 +1,283 @@
+# Copyright (C) 2019 MongoDB, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module Mongo
+  module Crypt
+
+    # A class that implements I/O methods between the driver and
+    # the MongoDB server or mongocryptd.
+    #
+    # @api private
+    class EncryptionIO
+
+      # Timeout used for SSL socket connection, reading, and writing.
+      # There is no specific timeout written in the spec. See SPEC-1394
+      # for a discussion and updates on what this timeout should be.
+      SOCKET_TIMEOUT = 10
+
+      # Creates a new EncryptionIO object with information about how to connect
+      # to the key vault.
+      #
+      # @param [ Mongo::Client ] client: The client used to connect to the collection
+      #   that stores the encrypted documents, defaults to nil.
+      # @param [ Mongo::Client ] mongocryptd_client: The client connected to mongocryptd,
+      #   defaults to nil.
+      # @param [ Mongo::Client ] key_vault_client: The client connected to the
+      #   key vault collection.
+      # @param [ String ] key_vault_namespace: The key vault namespace in the format
+      #   db_name.collection_name.
+      # @param [ Hash ] mongocryptd_options: Options related to mongocryptd.
+      #
+      # @option mongocryptd_options [ Boolean ] :mongocryptd_bypass_spawn
+      # @option mongocryptd_options [ String ] :mongocryptd_spawn_path
+      # @option mongocryptd_options [ Array<String> ] :mongocryptd_spawn_args
+      #
+      # @note When being used for auto encryption, all arguments are required.
+      #   When being used for explicit encryption, only the key_vault_namespace
+      #   and key_vault_client arguments are required.
+      #
+      # @note This class expects that the key_vault_client and key_vault_namespace
+      #   options are not nil and are in the correct format.
+      def initialize(
+        client: nil, mongocryptd_client: nil, key_vault_namespace:,
+        key_vault_client:, mongocryptd_options: {}
+      )
+        validate_key_vault_client!(key_vault_client)
+        validate_key_vault_namespace!(key_vault_namespace)
+
+        @client = client
+        @mongocryptd_client = mongocryptd_client
+        @key_vault_db_name, @key_vault_collection_name = key_vault_namespace.split('.')
+        @key_vault_client = key_vault_client
+        @options = mongocryptd_options
+      end
+
+      # Query for keys in the key vault collection using the provided
+      # filter
+      #
+      # @param [ Hash ] filter
+      #
+      # @return [ Array<BSON::Document> ] The query results
+      def find_keys(filter)
+        key_vault_collection.find(filter).to_a
+      end
+
+      # Insert a document into the key vault collection
+      #
+      # @param [ Hash ] document
+      #
+      # @return [ Mongo::Operation::Insert::Result ] The insertion result
+      def insert_data_key(document)
+        key_vault_collection.insert_one(document)
+      end
+
+      # Get collection info for a collection matching the provided filter
+      #
+      # @param [ Hash ] filter
+      #
+      # @return [ Hash ] The collection information
+      def collection_info(db_name, filter)
+        unless @client
+          raise ArgumentError, 'collection_info requires client to have been passed to the constructor, but it was not'
+        end
+
+        @client.use(db_name).database.list_collections(filter: filter).first
+      end
+
+      # Send the command to mongocryptd to be marked with intent-to-encrypt markings
+      #
+      # @param [ Hash ] cmd
+      #
+      # @return [ Hash ] The marked command
+      def mark_command(cmd)
+        unless @mongocryptd_client
+          raise ArgumentError, 'mark_command requires mongocryptd_client to have been passed to the constructor, but it was not'
+        end
+
+        begin
+          response = @mongocryptd_client.database.command(cmd)
+        rescue Error::NoServerAvailable => e
+          raise e if @options[:mongocryptd_bypass_spawn]
+
+          spawn_mongocryptd
+          response = @mongocryptd_client.database.command(cmd)
+        end
+
+        return response.first
+      end
+
+      # Get information about the AWS encryption key and feed it to the the
+      # KmsContext object
+      #
+      # @param [ Mongo::Crypt::KmsContext ] kms_context A KmsContext object
+      #   corresponding to one AWS KMS data key. Contains information about
+      #   the endpoint at which to establish a TLS connection and the message
+      #   to send on that connection.
+      def feed_kms(kms_context)
+        with_ssl_socket(kms_context.endpoint) do |ssl_socket|
+
+          Timeout.timeout(SOCKET_TIMEOUT, Error::SocketTimeoutError,
+            'Socket write operation timed out'
+          ) do
+            ssl_socket.syswrite(kms_context.message)
+          end
+
+          bytes_needed = kms_context.bytes_needed
+          while bytes_needed > 0 do
+            bytes = Timeout.timeout(SOCKET_TIMEOUT, Error::SocketTimeoutError,
+              'Socket read operation timed out'
+            ) do
+              ssl_socket.sysread(bytes_needed)
+            end
+
+            kms_context.feed(bytes)
+            bytes_needed = kms_context.bytes_needed
+          end
+        end
+      end
+
+      private
+
+      def validate_key_vault_client!(key_vault_client)
+        unless key_vault_client
+          raise ArgumentError.new('The :key_vault_client option cannot be nil')
+        end
+
+        unless key_vault_client.is_a?(Client)
+          raise ArgumentError.new(
+            'The :key_vault_client option must be an instance of Mongo::Client'
+          )
+        end
+      end
+
+      def validate_key_vault_namespace!(key_vault_namespace)
+        unless key_vault_namespace
+          raise ArgumentError.new('The :key_vault_namespace option cannot be nil')
+        end
+
+        unless key_vault_namespace.split('.').length == 2
+          raise ArgumentError.new(
+            "#{key_vault_namespace} is an invalid key vault namespace." +
+            "The :key_vault_namespace option must be in the format database.collection"
+          )
+        end
+      end
+
+      # Use the provided key vault client and namespace to construct a
+      # Mongo::Collection object representing the key vault collection.
+      def key_vault_collection
+        @key_vault_collection ||= @key_vault_client.with(
+          database: @key_vault_db_name,
+          read_concern: { level: :majority }
+        )[@key_vault_collection_name]
+      end
+
+      # Spawn a new mongocryptd process using the mongocryptd_spawn_path
+      # and mongocryptd_spawn_args passed in through the extra auto
+      # encrypt options. Stdout and Stderr of this new process are written
+      # to /dev/null.
+      #
+      # @note To capture the mongocryptd logs, add "--logpath=/path/to/logs"
+      #   to auto_encryption_options -> extra_options -> mongocrpytd_spawn_args
+      #
+      # @return [ Integer ] The process id of the spawned process
+      #
+      # @raise [ ArgumentError ] Raises an exception if no encryption options
+      #   have been provided
+      def spawn_mongocryptd
+        mongocryptd_spawn_args = @options[:mongocryptd_spawn_args]
+        mongocryptd_spawn_path = @options[:mongocryptd_spawn_path]
+
+        unless mongocryptd_spawn_path
+          raise ArgumentError.new(
+            'Cannot spawn mongocryptd process when no ' +
+            ':mongocryptd_spawn_path option is provided'
+          )
+        end
+
+        if mongocryptd_spawn_path.nil? ||
+          mongocryptd_spawn_args.nil? || mongocryptd_spawn_args.empty?
+        then
+          raise ArgumentError.new(
+            'Cannot spawn mongocryptd process when no :mongocryptd_spawn_args ' +
+            'option is provided. To start mongocryptd without arguments, pass ' +
+            '"--" for :mongocryptd_spawn_args'
+          )
+        end
+
+        begin
+          Process.spawn(
+            mongocryptd_spawn_path,
+            *mongocryptd_spawn_args,
+            [:out, :err]=>'/dev/null'
+          )
+        rescue Errno::ENOENT => e
+          raise Error::MongocryptdSpawnError.new(
+            "Failed to spawn mongocryptd at the path \"#{mongocryptd_spawn_path}\" " +
+            "with arguments #{mongocryptd_spawn_args}. Received error " +
+            "#{e.class}: \"#{e.message}\""
+          )
+        end
+      end
+
+      # Provide an SSL socket to be used for KMS calls in a block API
+      #
+      # @param [ String ] endpoint The URI at which to connect the SSL socket
+      # @param [ Proc ] block The block to execute
+      #
+      # @raise [ Mongo::Error::KmsError ] If the socket times out or raises
+      #   an exception
+      #
+      # @note The socket is always closed when the provided block has finished
+      #   executing
+      def with_ssl_socket(endpoint)
+        host, port = endpoint.split(':')
+        port ||= 443 # Default port for AWS KMS API
+
+        begin
+          # Create TCPSocket and set nodelay option
+          tcp_socket = TCPSocket.open(host, port)
+          tcp_socket.setsockopt(::Socket::IPPROTO_TCP, ::Socket::TCP_NODELAY, 1)
+
+          ssl_socket = OpenSSL::SSL::SSLSocket.new(tcp_socket)
+          ssl_socket.sync_close = true # tcp_socket will be closed when ssl_socket is closed
+          ssl_socket.hostname = "#{host}:#{port}" # perform SNI
+
+          Timeout.timeout(
+            SOCKET_TIMEOUT,
+            Error::SocketTimeoutError,
+            'Socket connection timed out'
+          ) do
+            ssl_socket.connect
+          end
+
+          yield(ssl_socket)
+        rescue => e
+          raise Error::KmsError, "Error decrypting data key. #{e.class}: #{e.message}"
+        ensure
+          # If there is an error during socket creation, the
+          # ssl_socket object won't exist in this scope and this line will
+          # raise an exception
+          Timeout.timeout(
+            SOCKET_TIMEOUT,
+            Error::SocketTimeoutError,
+            'Socket close timed out'
+          ) do
+            ssl_socket.sysclose rescue nil
+          end
+        end
+      end
+    end
+  end
+end