mongo 2.11.6 → 2.12.0.rc0

data/lib/mongo/crypt/hooks.rb

@@ -0,0 +1,90 @@
+# 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.
+
+require 'securerandom'
+require 'digest'
+
+module Mongo
+  module Crypt
+
+    # A helper module that implements cryptography methods required
+    # for native Ruby crypto hooks. These methods are passed into FFI
+    # as C callbacks and called from the libmongocrypt library.
+    #
+    # @api private
+    module Hooks
+
+      # An AES encrypt or decrypt method.
+      #
+      # @param [ String ] key The 32-byte AES encryption key
+      # @param [ String ] iv The 16-byte AES IV
+      # @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
+      #
+      # @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)
+
+        decrypt ? cipher.decrypt : cipher.encrypt
+        cipher.key = key
+        cipher.iv = iv
+        cipher.padding = 0
+
+        encrypted = cipher.update(input)
+      end
+      module_function :aes
+
+      # Crypto secure random function
+      #
+      # @param [ Integer ] num_bytes The number of random bytes requested
+      #
+      # @return [ String ]
+      # @raise [ Exception ] Exceptions raised during encryption are propagated
+      #   to caller.
+      def random(num_bytes)
+        SecureRandom.random_bytes(num_bytes)
+      end
+      module_function :random
+
+      # An HMAC SHA-512 or SHA-256 function
+      #
+      # @param [ String ] The name of the digest, either "SHA256" or "SHA512"
+      # @param [ String ] key The 32-byte AES encryption key
+      # @param [ String ] input The data to be tagged
+      #
+      # @return [ String ]
+      # @raise [ Exception ] Exceptions raised during encryption are propagated
+      #   to caller.
+      def hmac_sha(digest_name, key, input)
+        OpenSSL::HMAC.digest(digest_name, key, input)
+      end
+      module_function :hmac_sha
+
+      # A crypto hash (SHA-256) function
+      #
+      # @param [ String ] input The data to be hashed
+      #
+      # @return [ String ]
+      # @raise [ Exception ] Exceptions raised during encryption are propagated
+      #   to caller.
+      def hash_sha256(input)
+        Digest::SHA2.new(256).digest(input)
+      end
+      module_function :hash_sha256
+    end
+  end
+end

data/lib/mongo/crypt/kms_context.rb

@@ -0,0 +1,67 @@
+# 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
+
+    # Wraps a libmongocrypt mongocrypt_kms_ctx_t object. Contains information
+    # about making an HTTP request to fetch information about a KMS
+    # data key.
+    class KmsContext
+      # Create a new KmsContext object.
+      #
+      # @param [ FFI::Pointer ] kms_ctx A pointer to a mongocrypt_kms_ctx_t
+      #   object. This object is managed by the mongocrypt_ctx_t object that
+      #   created it; this class is not responsible for de-allocating resources.
+      def initialize(kms_ctx)
+        @kms_ctx_p = kms_ctx
+      end
+
+      # Return the pointer to the underlying mongocrypt_kms_ctx_t object.
+      #
+      # @return [ FFI::Pointer ] A pointer to a mongocrypt_kms_ctx_t object.
+      attr_reader :kms_ctx_p
+
+      # Return the endpoint at which to make the HTTP request.
+      #
+      # @return [ String ] The endpoint.
+      def endpoint
+        Binding.kms_ctx_endpoint(self)
+      end
+
+      # Return the HTTP message to send to fetch information about the relevant
+      # KMS data key.
+      #
+      # @return [ String ] The HTTP message.
+      def message
+        Binding.kms_ctx_message(self)
+      end
+
+      # Return the number of bytes still needed by libmongocrypt to complete
+      # the request for information about the AWS data key.
+      #
+      # @return [ Integer ] The number of bytes needed.
+      def bytes_needed
+        Binding.kms_ctx_bytes_needed(self)
+      end
+
+      # Feed a response from the HTTP request to libmongocrypt.
+      #
+      # @param [ String ] data Data to feed to libmongocrypt.
+      def feed(data)
+        Binding.kms_ctx_feed(self, data)
+      end
+    end
+  end
+end

data/lib/mongo/crypt/status.rb

@@ -0,0 +1,131 @@
+## 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.
+
+require 'ffi'
+
+module Mongo
+  module Crypt
+
+    # A wrapper around mongocrypt_status_t, representing the status of
+    # a mongocrypt_t handle.
+    #
+    # @api private
+    class Status
+      # Create a new Status object
+      #
+      # @param [ FFI::Pointer | nil ] pointer A pointer to an existing
+      #   mongocrypt_status_t object. Defaults to nil.
+      #
+      # @note When initializing a Status object with a pointer, it is
+      # recommended that you use the #self.from_pointer method
+      def initialize(pointer: nil)
+        # If a pointer is passed in, this class is not responsible for
+        # destroying that pointer and deallocating data.
+        #
+        # FFI::AutoPointer uses a custom release strategy to automatically free
+        # the pointer once this object goes out of scope
+        @status = pointer || FFI::AutoPointer.new(
+                              Binding.mongocrypt_status_new,
+                              Binding.method(:mongocrypt_status_destroy)
+                            )
+      end
+
+      # Initialize a Status object from an existing pointer to a
+      # mongocrypt_status_t object.
+      #
+      # @param [ FFI::Pointer ] pointer A pointer to an existing
+      #   mongocrypt_status_t object
+      #
+      # @return [ Mongo::Crypt::Status ] A new Status object
+      def self.from_pointer(pointer)
+        self.new(pointer: pointer)
+      end
+
+      # Set a label, code, and message on the Status
+      #
+      # @param [ Symbol ] label One of :ok, :error_client, or :error_kms
+      # @param [ Integer ] code
+      # @param [ String ] message
+      #
+      # @return [ Mongo::Crypt::Status ] returns self
+      def update(label, code, message)
+        unless [:ok, :error_client, :error_kms].include?(label)
+          raise ArgumentError.new(
+            "#{label} is an invalid value for a Mongo::Crypt::Status label. " +
+            "Label must have one of the following values: :ok, :error_client, :error_kms"
+          )
+        end
+
+        message_length = message ? message.bytesize + 1 : 0
+        Binding.mongocrypt_status_set(@status, label, code, message, message_length)
+
+        self
+      end
+
+      # Return the label of the status
+      #
+      # @return [ Symbol ] The status label, either :ok, :error_kms, or :error_client,
+      #   defaults to :ok
+      def label
+        Binding.mongocrypt_status_type(@status)
+      end
+
+      # Return the integer code associated with the status
+      #
+      # @return [ Integer ] The status code, defaults to 0
+      def code
+        Binding.mongocrypt_status_code(@status)
+      end
+
+      # Return the status message
+      #
+      # @return [ String ] The status message, defaults to empty string
+      def message
+        message = Binding.mongocrypt_status_message(@status, nil)
+        message || ''
+      end
+
+      # Checks whether the status is labeled :ok
+      #
+      # @return [ Boolean ] Whether the status is :ok
+      def ok?
+        Binding.mongocrypt_status_ok(@status)
+      end
+
+      # Returns the reference to the underlying mongocrypt_status_t
+      # object
+      #
+      # @return [ FFI::Pointer ] Pointer to the underlying mongocrypt_status_t oject
+      def ref
+        @status
+      end
+
+      # Raises a Mongo::Error:CryptError corresponding to the
+      # information stored in this status
+      #
+      # Does nothing if self.ok? is true
+      def raise_crypt_error
+        return if ok?
+
+        if label == :error_kms
+          error = Error::KmsError.new(message, code: code)
+        else
+          error = Error::CryptError.new(message, code: code)
+        end
+
+        raise error
+      end
+    end
+  end
+end

data/lib/mongo/cursor.rb

@@ -19,8 +19,9 @@ module Mongo
   # Client-side representation of an iterator over a query result set on
   # the server.
   #
-  # A +Cursor+ is not created directly by a user. Rather, +CollectionView+
-  # creates a +Cursor+ in an Enumerable module method.
+  # +Cursor+ objects are not directly exposed to application code. Rather,
+  # +Collection::View+ exposes the +Enumerable+ interface to the applications,
+  # and the enumerator is backed by a +Cursor+ instance.
   #
   # @example Get an array of 5 users named Emily.
   #   users.find({:name => 'Emily'}).limit(5).to_a
@@ -28,8 +29,7 @@ module Mongo
   # @example Call a block on each user doc.
   #   users.find.each { |doc| puts doc }
   #
-  # @note The +Cursor+ API is semipublic.
-  # @api semipublic
+  # @api private
   class Cursor
     extend Forwardable
     include Enumerable
@@ -71,11 +71,14 @@ module Mongo
       @initial_result = result
       @remaining = limit if limited?
       @cursor_id = result.cursor_id
+      if @cursor_id.nil?
+        raise ArgumentError, 'Cursor id must be present in the result'
+      end
       @coll_name = nil
       @options = options
       @session = @options[:session]
-      register
-      if @cursor_id && @cursor_id > 0
+      unless closed?
+        register
         ObjectSpace.define_finalizer(self, self.class.finalize(@cursor_id,
           cluster,
           kill_cursors_op_spec,
@@ -122,6 +125,10 @@ module Mongo
 
     # Iterate through documents returned from the query.
     #
+    # A cursor may be iterated at most once. Incomplete iteration is also
+    # allowed. Attempting to iterate the cursor more than once raises
+    # InvalidCursorOperation.
+    #
     # @example Iterate over the documents in the cursor.
     #   cursor.each do |doc|
     #     ...
@@ -142,19 +149,29 @@ module Mongo
       # end of previous iteration or would always restart from the
       # beginning.
       if @get_more_called
-        raise NotImplementedError, 'Cannot restart iteration of a cursor which issued a getMore'
+        raise Error::InvalidCursorOperation, 'Cannot restart iteration of a cursor which issued a getMore'
       end
 
       # To maintain compatibility with pre-2.10 driver versions, reset
       # the documents array each time a new iteration is started.
       @documents = nil
 
-      loop do
-        document = try_next
-        yield document if document
+      if block_given?
+        # StopIteration raised by try_next ends this loop.
+        loop do
+          document = try_next
+          yield document if document
+        end
+        self
+      else
+        documents = []
+        # StopIteration raised by try_next ends this loop.
+        loop do
+          document = try_next
+          documents << document if document
+        end
+        documents
       end
-    rescue StopIteration => e
-      return self
     end
 
     # Return one document from the query, if one is available.
@@ -168,6 +185,10 @@ module Mongo
     # @note This method is experimental and subject to change.
     #
     # @return [ BSON::Document | nil ] A document.
+    #
+    # @raise [ StopIteration ] Raised on the calls after the cursor had been
+    #   completely iterated.
+    #
     # @api private
     def try_next
       if @documents.nil?
@@ -184,9 +205,9 @@ module Mongo
         # On empty batches, we cache the batch resume token
         cache_batch_resume_token
 
-        if more?
+        unless closed?
           if exhausted?
-            kill_cursors
+            close
             raise StopIteration
           end
           @documents = get_more
@@ -233,7 +254,28 @@ module Mongo
     #
     # @since 2.2.0
     def closed?
-      !more?
+      # @cursor_id should in principle never be nil
+      @cursor_id.nil? || @cursor_id == 0
+    end
+
+    # Closes this cursor, freeing any associated resources on the client and
+    # the server.
+    #
+    # @return [ nil ] Always nil.
+    #
+    # @raise [ Error::OperationFailure ] If the server cursor close fails.
+    def close
+      return if closed?
+
+      unregister
+      read_with_one_retry do
+        kill_cursors_operation.execute(@server, client: client)
+      end
+
+      nil
+    ensure
+      end_session
+      @cursor_id = 0
     end
 
     # Get the parsed collection name.
@@ -289,7 +331,7 @@ module Mongo
       # doing so may result in silent data loss, the driver no longer retries
       # getMore operations in any circumstance.
       # https://github.com/mongodb/specifications/blob/master/source/retryable-reads/retryable-reads.rst#qa
-      process(get_more_operation.execute(@server))
+      process(get_more_operation.execute(@server, client: client))
     end
 
     private
@@ -317,16 +359,6 @@ module Mongo
       Operation::GetMore.new(spec)
     end
 
-    def kill_cursors
-      unregister
-      read_with_one_retry do
-        kill_cursors_operation.execute(@server)
-      end
-    ensure
-      end_session
-      @cursor_id = 0
-    end
-
     def end_session
       @session.end_session if @session && @session.implicit?
     end
@@ -347,21 +379,21 @@ module Mongo
       limit ? limit > 0 : false
     end
 
-    def more?
-      @cursor_id != 0
-    end
-
     def process(result)
       @remaining -= result.returned_count if limited?
       @coll_name ||= result.namespace.sub("#{database.name}.", '') if result.namespace
-      unregister if result.cursor_id == 0
+      # #process is called for the first batch of results. In this case
+      # the @cursor_id may be zero (all results fit in the first batch).
+      # Thus we need to check both @cursor_id and the cursor_id of the result
+      # prior to calling unregister here.
+      unregister if !closed? && result.cursor_id == 0
       @cursor_id = result.cursor_id
 
       if result.respond_to?(:post_batch_resume_token)
         @post_batch_resume_token = result.post_batch_resume_token
       end
 
-      end_session if !more?
+      end_session if closed?
 
       # Since our iteration code mutates the documents array by calling #shift
       # on it, duplicate the documents here to permit restarting iteration