net-imap 0.6.3 → 0.6.4.1

data/lib/net/imap/response_data.rb

@@ -75,9 +75,18 @@ module Net
     #
     # Net::IMAP::UnparsedData represents data for unknown response types or
     # unknown extensions to response types without a well-defined extension
-    # grammar.
+    # grammar.  UnparsedData represents the portion of the response which the
+    # parser has skipped over, without attempting to parse it.
     #
-    # See also: UnparsedNumericResponseData, ExtensionData, IgnoredResponse
+    #    parser = Net::IMAP::ResponseParser.new
+    #    response = parser.parse "* X-UNKNOWN-TYPE can't parse this\r\n"
+    #    response => Net::IMAP::UntaggedResponse(
+    #      name: "X-UNKNOWN-TYPE",
+    #      data: Net::IMAP::UnparsedData(unparsed_data: "can't parse this"),
+    #    )
+    #
+    # See also: UnparsedNumericResponseData, ExtensionData, IgnoredResponse,
+    # InvalidParseData.
     class UnparsedData < Struct.new(:unparsed_data)
       ##
       # method: unparsed_data
@@ -86,6 +95,61 @@ module Net
       # The unparsed data
     end
 
+    # **Note:** This represents an intentionally _unstable_ API.  Where
+    # instances of this class are returned, future releases may return a
+    # different (incompatible) object <em>without deprecation or warning</em>.
+    #
+    # When the response parser encounters a recoverable error,
+    # Net::IMAP::InvalidParseData represents that portion of the response which
+    # could not be parsed, allowing the parser to parse the remainder of the
+    # response.  InvalidParseData is always associated with a ResponseParseError
+    # which has been rescued.
+    #
+    # This could be caused by a malformed server response, by a bug in
+    # Net::IMAP::ResponseParser, or by an unsupported extension to the response
+    # syntax.  For example, if a server supports +UIDPLUS+, but sends an invalid
+    # +COPYUID+ response code:
+    #
+    #    parser = Net::IMAP::ResponseParser.new
+    #    parsed = parser.parse "* OK [COPYUID 701  ] copied one message\r\n"
+    #    parsed => {
+    #      data: Net::IMAP::ResponseText(
+    #        code: Net::IMAP::ResponseCode(
+    #          name: "COPYUID",
+    #          data: Net::IMAP::InvalidParseData(
+    #            parse_error: Net::IMAP::ResponseParseError,
+    #            unparsed_data: "701  ",
+    #            parsed_data: nil,
+    #          )
+    #        )
+    #      )
+    #    }
+    #
+    # In this example, although <tt>[COPYUID 701  ]</tt> uses valid syntax for a
+    # _generic_ ResponseCode, it is _invalid_ syntax for a +COPYUID+ response
+    # code.
+    #
+    # See also: UnparsedData, ExtensionData
+    class InvalidParseData < Data.define(:parse_error, :unparsed_data, :parsed_data)
+      ##
+      # method: parse_error
+      # :call-seq: parse_error -> ResponseParseError
+      #
+      # Returns the rescued ResponseParseError.
+
+      ##
+      # method: unparsed_data
+      # :call-seq: unparsed_data -> string
+      #
+      # Returns the raw string which was skipped over by the parser.
+
+      ##
+      # method: parsed_data
+      #
+      # May return a partial parse result for unparsed_data, which had already
+      # been parsed before the parse_error.
+    end
+
     # **Note:** This represents an intentionally _unstable_ API.  Where
     # instances of this class are returned, future releases may return a
     # different (incompatible) object <em>without deprecation or warning</em>.
@@ -93,7 +157,17 @@ module Net
     # Net::IMAP::UnparsedNumericResponseData represents data for unhandled
     # response types with a numeric prefix.  See the documentation for #number.
     #
-    # See also: UnparsedData, ExtensionData, IgnoredResponse
+    #    parser = Net::IMAP::ResponseParser.new
+    #    response = parser.parse "* 123 X-UNKNOWN-TYPE can't parse this\r\n"
+    #    response => Net::IMAP::UntaggedResponse(
+    #      name: "X-UNKNOWN-TYPE",
+    #      data: Net::IMAP::UnparsedNumericData(
+    #        number: 123,
+    #        unparsed_data: "can't parse this"
+    #      ),
+    #    )
+    #
+    # See also: UnparsedData, ExtensionData, IgnoredResponse, InvalidParseData
     class UnparsedNumericResponseData < Struct.new(:number, :unparsed_data)
       ##
       # method: number
@@ -306,6 +380,14 @@ module Net
     #   because the server doesn't allow deletion of mailboxes with children.
     #   #data is +nil+.
     #
+    # === <tt>QUOTA=RES-*</tt> response codes
+    # See {[RFC9208]}[https://www.rfc-editor.org/rfc/rfc9208.html#section-4.3].
+    # * +OVERQUOTA+ (also in RFC5530[https://www.rfc-editor.org/rfc/rfc5530]),
+    #   with a tagged +NO+ response to an +APPEND+/+COPY+/+MOVE+ command when
+    #   the command would put the target mailbox over any quota, and with an
+    #   untagged +NO+ when a mailbox exceeds a soft quota (which may be caused
+    #   be external events).  #data is +nil+.
+    #
     # === +CONDSTORE+ extension
     # See {[RFC7162]}[https://www.rfc-editor.org/rfc/rfc7162.html].
     # * +NOMODSEQ+, when selecting a mailbox that does not support
@@ -324,9 +406,10 @@ module Net
     #
     # Response codes are backwards compatible:  Servers are allowed to send new
     # response codes even if the client has not enabled the extension that
-    # defines them.  When Net::IMAP does not know how to parse response
-    # code text, #data returns the unparsed string.
-    #
+    # defines them.  When ResponseParser does not know how to parse the response
+    # code data, #data may return the unparsed string, ExtensionData, or
+    # UnparsedData.  When ResponseParser attempts but fails to parse the
+    # response code data, #data returns InvalidParseData.
     class ResponseCode < Struct.new(:name, :data)
       ##
       # method: name
@@ -341,8 +424,13 @@ module Net
       #
       # Returns the parsed response code data, e.g: an array of capabilities
       # strings, an array of character set strings, a list of permanent flags,
-      # an Integer, etc.  The response #code determines what form the response
-      # code data can take.
+      # an Integer, etc.  The response #name determines what form the response
+      # code #data can take.
+      #
+      # When ResponseParser does not know how to parse the response code data,
+      # #data may return the unparsed string, ExtensionData, or UnparsedData.
+      # When ResponseParser attempts but fails to parse the response code data,
+      # #data returns InvalidParseData.
     end
 
     # MailboxList represents the data of an untagged +LIST+ response, for a
@@ -383,14 +471,23 @@ module Net
     # and MailboxQuota objects.
     #
     # == Required capability
+    #
     # Requires +QUOTA+ [RFC2087[https://www.rfc-editor.org/rfc/rfc2087]]
-    # capability.
+    # or <tt>QUOTA=RES-STORAGE</tt>
+    # [RFC9208[https://www.rfc-editor.org/rfc/rfc9208]] capability.
     class MailboxQuota < Struct.new(:mailbox, :usage, :quota)
       ##
       # method: mailbox
       # :call-seq: mailbox -> string
       #
-      # The mailbox with the associated quota.
+      # The quota root with the associated quota.
+      #
+      # NOTE: this was mistakenly named "mailbox".  But the quota root's name may
+      # differ from the mailbox.  A single quota root may cover multiple
+      # mailboxes, and a single mailbox may be governed by multiple quota roots.
+
+      # The quota root with the associated quota.
+      alias quota_root mailbox
 
       ##
       # method: usage
@@ -402,7 +499,7 @@ module Net
       # method: quota
       # :call-seq: quota -> Integer
       #
-      # Quota limit imposed on the mailbox.
+      # Storage limit imposed on the mailbox.
       #
     end
 

data/lib/net/imap/response_parser.rb

@@ -691,6 +691,8 @@ module Net
         CRLF!
         EOF!
         resp
+      rescue SystemStackError
+        parse_error("response recursion too deep")
       end
 
       # RFC3501 & RFC9051:
@@ -1961,6 +1963,7 @@ module Net
       #   resp-text-code   =/ "UIDREQUIRED"
       def resp_text_code
         name = resp_text_code__name
+        state = current_state
         data =
           case name
           when "CAPABILITY"         then resp_code__capability
@@ -1983,8 +1986,18 @@ module Net
           when "MAILBOXID"          then SP!; parens__objectid     # RFC8474: OBJECTID
           when "UIDREQUIRED"        then                           # RFC9586: UIDONLY
           else
+            state = nil # don't backtrack
             SP? and text_chars_except_rbra
           end
+        peek_rbra? or
+          parse_error("expected resp-text-code %p to be complete", name)
+        ResponseCode.new(name, data)
+      rescue Net::IMAP::ResponseParseError => parse_error
+        raise unless state
+        raise if parse_error.message.include?("uid-set")
+        restore_state state
+        unparsed_data = SP? && text_chars_except_rbra
+        data = InvalidParseData[parse_error:, unparsed_data:, parsed_data: data]
         ResponseCode.new(name, data)
       end
 
@@ -2199,10 +2212,7 @@ module Net
             if $1
               return Token.new(T_SPACE, $+)
             elsif $2
-              len = $+.to_i
-              val = @str[@pos, len]
-              @pos += len
-              return Token.new(T_LITERAL8, val)
+              literal_token($+, T_LITERAL8)
             elsif $3 && $7
               # greedily match ATOM, prefixed with NUMBER, NIL, or PLUS.
               return Token.new(T_ATOM, $3)
@@ -2230,10 +2240,7 @@ module Net
             elsif $15
               return Token.new(T_RBRA, $+)
             elsif $16
-              len = $+.to_i
-              val = @str[@pos, len]
-              @pos += len
-              return Token.new(T_LITERAL, val)
+              literal_token($+)
             elsif $17
               return Token.new(T_PERCENT, $+)
             elsif $18
@@ -2259,10 +2266,7 @@ module Net
             elsif $4
               return Token.new(T_QUOTED, Patterns.unescape_quoted($+))
             elsif $5
-              len = $+.to_i
-              val = @str[@pos, len]
-              @pos += len
-              return Token.new(T_LITERAL, val)
+              literal_token($+)
             elsif $6
               return Token.new(T_LPAR, $+)
             elsif $7
@@ -2277,6 +2281,15 @@ module Net
         else
           parse_error("invalid @lex_state - %s", @lex_state.inspect)
         end
+      rescue DataFormatError => error
+        parse_error error.message
+      end
+
+      def literal_token(len, type = T_LITERAL)
+        len = NumValidator.coerce_number64 len
+        val = @str[@pos, len]
+        @pos += len
+        Token.new(type, val)
       end
 
     end

data/lib/net/imap/response_reader.rb

@@ -4,55 +4,69 @@ module Net
   class IMAP
     # See https://www.rfc-editor.org/rfc/rfc9051#section-2.2.2
     class ResponseReader # :nodoc:
+      include NumValidator
+
       attr_reader :client
 
       def initialize(client, sock)
         @client, @sock = client, sock
+        # cached config
+        @max_response_size = nil
+        # response buffer state
+        @buff = @literal_size = nil
       end
 
       def read_response_buffer
+        @max_response_size = client.max_response_size
         @buff = String.new
         catch :eof do
           while true
+            guard_response_too_large!
             read_line
-            break unless (@literal_size = get_literal_size)
+            # check before allocating memory for literal
+            guard_response_too_large!
+            break unless literal_size
             read_literal
           end
         end
         buff
       ensure
-        @buff = nil
+        @buff = @literal_size = nil
       end
 
       private
 
+      # cached config
+      attr_reader :max_response_size
+
+      # response buffer state
       attr_reader :buff, :literal_size
 
       def bytes_read          = buff.bytesize
       def empty?              = buff.empty?
-      def done?               = line_done? && !get_literal_size
+      def done?               = line_done? && !literal_size
       def line_done?          = buff.end_with?(CRLF)
-      def get_literal_size    = /\{(\d+)\}\r\n\z/n =~ buff && $1.to_i
+
+      def get_literal_size(buff)
+        buff.end_with?("}\r\n") && buff.rindex(/\{(\d+)\}\r\n\z/n) &&
+          coerce_number64($1)
+      rescue DataFormatError
+        raise DataFormatError, format("invalid response literal size (%s)", $1)
+      end
 
       def read_line
-        buff << (@sock.gets(CRLF, read_limit) or throw :eof)
-        max_response_remaining! unless line_done?
+        line = (@sock.gets(CRLF, max_response_remaining) or throw :eof)
+        @literal_size = get_literal_size(line)
+        buff << line
       end
 
       def read_literal
-        # check before allocating memory for literal
-        max_response_remaining!
         literal = String.new(capacity: literal_size)
-        buff << (@sock.read(read_limit(literal_size), literal) or throw :eof)
+        buff << (@sock.read(literal_size, literal) or throw :eof)
       ensure
         @literal_size = nil
       end
 
-      def read_limit(limit = nil)
-        [limit, max_response_remaining!].compact.min
-      end
-
-      def max_response_size      = client.max_response_size
       def max_response_remaining = max_response_size &.- bytes_read
       def response_too_large?    = max_response_size &.< min_response_size
       def min_response_size      = bytes_read + min_response_remaining
@@ -61,8 +75,8 @@ module Net
         empty? ? 3 : done? ? 0 : (literal_size || 0) + 2
       end
 
-      def max_response_remaining!
-        return max_response_remaining unless response_too_large?
+      def guard_response_too_large!
+        return unless response_too_large?
         raise ResponseTooLargeError.new(
           max_response_size:, bytes_read:, literal_size:,
         )

data/lib/net/imap/sasl/scram_authenticator.rb

@@ -75,13 +75,19 @@ module Net
         # * #password ― Password or passphrase associated with this #username.
         # * _optional_ #authzid ― Alternate identity to act as or on behalf of.
         # * _optional_ #min_iterations - Overrides the default value (4096).
+        # * _optional_ #max_iterations - Overrides the default value (2³¹ - 1).
         #
         # Any other keyword parameters are quietly ignored.
+        #
+        # *NOTE:* <em>It is the user's responsibility</em> to enforce minimum
+        # and maximum iteration counts that are appropriate for their security
+        # context.
         def initialize(username_arg = nil, password_arg = nil,
                        authcid: nil, username: nil,
                        authzid: nil,
                        password: nil, secret: nil,
                        min_iterations: 4096, # see both RFC5802 and RFC7677
+                       max_iterations: 2**31 - 1,  # max int32
                        cnonce: nil, # must only be set in tests
                        **options)
           @username = username || username_arg || authcid or
@@ -94,7 +100,22 @@ module Net
           @min_iterations.positive? or
             raise ArgumentError, "min_iterations must be positive"
 
+          @max_iterations = Integer max_iterations.to_int
+          @min_iterations <= @max_iterations or
+            raise ArgumentError, "max_iterations must be more than min_iterations"
+
           @cnonce = cnonce || SecureRandom.base64(32)
+
+          # These attrs are set from the server challenges
+          @server_first_message = @snonce = @salt = @iterations = nil
+          @server_error = nil
+
+          # Memoized after @salt and @iterations have been sent.
+          @salted_password = @client_key = @server_key = nil
+
+          # These values are created and cached in response to server challenges
+          @client_first_message_bare = nil
+          @client_final_message_without_proof = nil
         end
 
         # Authentication identity: the identity that matches the #password.
@@ -127,8 +148,43 @@ module Net
 
         # The minimal allowed iteration count.  Lower #iterations will raise an
         # Error.
+        #
+        # *WARNING:* The default value (4096) is set to match guidance from
+        # both {RFC5802}[https://www.rfc-editor.org/rfc/rfc5802#page-12]
+        # and RFC7677[https://www.rfc-editor.org/rfc/rfc7677#section-4], but
+        # {modern recommendations}[https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html#pbkdf2]
+        # are significantly higher.
+        #
+        # It is ultimately the server's responsibility to securely store
+        # password hashes.  While this parameter can alert the user to
+        # insecure password storage and prevent insecure authentication
+        # exchange, updating the iteration count generally requires resetting
+        # the password on the server.
         attr_reader :min_iterations
 
+        # The maximal allowed iteration count.  Higher #iterations will raise an
+        # Error.
+        #
+        # As noted in {RFC5802}[https://www.rfc-editor.org/rfc/rfc5802#section-9]
+        # >>>
+        #   A hostile server can perform a computational denial-of-service
+        #   attack on clients by sending a big iteration count value.
+        #
+        # *WARNING:* The default value is <tt>2³¹ - 1</tt>, the maximum signed
+        # 32-bit integer.  This is large enough for the computation to take
+        # several minutes, and insufficient protection against hostile servers.
+        #
+        # Note that <tt>OpenSSL::KDF.pbkdf2_hmac</tt> is implemented by a
+        # blocking C function, and cannot be interrupted by +Timeout+ or
+        # <tt>Thread.raise</tt>.  And it keeps the Global VM lock, as of v4.0 of
+        # the +openssl+ gem, so other ruby threads will not be able to run.
+        #
+        # <em>To prevent a denial of service attack,</em> this must be set to a
+        # safe value, depending on hardware and version of OpenSSL.  <em>It is
+        # the user's responsibility</em> to enforce minimum and maximum
+        # iteration counts that are appropriate for their security context.
+        attr_reader :max_iterations
+
         # The client nonce, generated by SecureRandom
         attr_reader :cnonce
 
@@ -147,6 +203,15 @@ module Net
         # Net::IMAP::NoResponseError.
         attr_reader :server_error
 
+        # Memoized ScramAlgorithm#salted_password (needs #salt and #iterations)
+        def salted_password = @salted_password ||= compute_salted { super }
+
+        # Memoized ScramAlgorithm#client_key (needs #salt and #iterations)
+        def client_key = @client_key ||= compute_salted { super }
+
+        # Memoized ScramAlgorithm#server_key (needs #salt and #iterations)
+        def server_key = @server_key ||= compute_salted { super }
+
         # Returns a new OpenSSL::Digest object, set to the appropriate hash
         # function for the chosen mechanism.
         #
@@ -186,6 +251,13 @@ module Net
 
         private
 
+        # Checks for +salt+ and +iterations+ before yielding
+        def compute_salted
+          salt       in String  or raise Error, "unknown salt"
+          iterations in Integer or raise Error, "unknown iterations"
+          yield
+        end
+
         # Need to store this for auth_message
         attr_reader :server_first_message
 
@@ -202,6 +274,8 @@ module Net
             raise Error, "server did not send iteration count"
           min_iterations <= iterations or
             raise Error, "too few iterations: %d" % [iterations]
+          max_iterations.nil? || iterations <= max_iterations or
+            raise Error, "too many iterations: %d" % [iterations]
           mext = sparams["m"] and
             raise Error, "mandatory extension: %p" % [mext]
           snonce.start_with? cnonce or

data/lib/net/imap/search_result.rb

@@ -123,7 +123,11 @@ module Net
       #     Net::IMAP::SearchResult[9, 1, 2, 4, 10, 12, 3, modseq: 123_456]
       #       .to_sequence_set
       #     # => Net::IMAP::SequenceSet["1:4,9:10,12"]
-      def to_sequence_set; SequenceSet[*self] end
+      #
+      # >>>
+      #   *NOTE:* +SORT+ order is not preserved.  The result will be sorted.
+      #
+      def to_sequence_set; empty? ? SequenceSet.empty : SequenceSet[to_a] end
 
       def pretty_print(pp)
         return super if modseq.nil?