net-imap 0.4.23 → 0.4.25

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a15f49a20256632f692729c868dfb503e025f999bd2f520270674218869aae77
-  data.tar.gz: dd5daa492ba441af22036909b46dc57b40ab6f1d26742f5487756af89befe858
+  metadata.gz: bf05b4f7aec9127531e83134b740620da216f847851f8ca464ef54e71e3431ad
+  data.tar.gz: 18361d6ee25983da0e4814d42a0ec851e10ce88789559e30778a945a7024a297
 SHA512:
-  metadata.gz: 245c92501ec0e7b3d48dc59537f72cee04609c83c402bdbdc49c315cf021087e02180a2bf6ba165b9dbf3afd5d3998c4f7cd7112293143f1b188d9d87c2b2445
-  data.tar.gz: b23b4c65e667f681d25511f611791b14654de6222f4dd3aad6dcb1b134f003332f6d0984135bbda0acef0448a4b288bbd4855f0c2c26910110efab1f3e15799e
+  metadata.gz: 697214c436f129746ad8986dde31e4b819854cf131472158c4aacf5a35ef665b8529528bd0a843ba17d9be105711b4163ecccfa525989d9fe0b3f807f4ae9d58
+  data.tar.gz: ef657a1dbfd5bc73fa317248ae19589a842f87eabfe966b43b026e9dceff68d510621d3e17136b266d22f68b85d20fc22b4ea67a482fdca193d8a5290c643abf

data/lib/net/imap/command_data.rb

@@ -14,17 +14,19 @@ module Net
       when nil
       when String
       when Integer
-        NumValidator.ensure_number(data)
+        # Covers modseq-valzer, which is the largest valid IMAP integer
+        if data.negative?
+          raise DataFormatError, "Integer argument must be unsigned: #{data}"
+        elsif 0xffff_ffff_ffff_ffff < data
+          raise DataFormatError, "Integer argument must fit in 64 bits: #{data}"
+        end
       when Array
-        if data[0] == 'CHANGEDSINCE'
-          NumValidator.ensure_mod_sequence_value(data[1])
-        else
-          data.each do |i|
-            validate_data(i)
-          end
+        data.each do |i|
+          validate_data(i)
         end
       when Time, Date, DateTime
       when Symbol
+        Flag.validate(data)
       else
         data.validate
       end
@@ -45,7 +47,7 @@ module Net
       when Date
         send_date_data(data)
       when Symbol
-        send_symbol_data(data)
+        Flag[data].send_data(self, tag)
       else
         data.send_data(self, tag)
       end
@@ -77,9 +79,31 @@ module Net
       put_string('"' + str.gsub(/["\\]/, "\\\\\\&") + '"')
     end
 
-    def send_literal(str, tag = nil)
+    def send_binary_literal(*a, **kw) send_literal(*a, **kw, binary: true) end
+
+    # `non_sync` is an optional tri-state flag:
+    # * `true`  -> Force non-synchronizing `LITERAL+`/`LITERAL-` behavior.
+    #   NOTE: raises DataFormatError when server doesn't support
+    #   non-synchronizing literal, or literal is too large for LITERAL-.
+    # * `false` -> Force normal synchronizing literal behavior.
+    # * `nil`   -> (default) Currently behaves like `false` (will be dynamic).
+    #   TODO: Dynamic, based on capabilities and bytesize.
+    def send_literal(str, tag = nil, binary: false, non_sync: nil)
+      bytesize = str.bytesize
       synchronize do
-        put_string("{" + str.bytesize.to_s + "}" + CRLF)
+        if non_sync && !non_sync_literal_allowed?(bytesize)
+          # TODO: check in Printer, so we don't need to close the connection.
+          @sock.close
+          raise DataFormatError, "Connection closed: " \
+            "Cannot send non-synchronizing literal without known server support"
+        end
+        prefix = "~" if binary
+        plus = "+" if non_sync
+        put_string("#{prefix}{#{bytesize}#{plus}}\r\n")
+        if non_sync
+          put_string(str)
+          return
+        end
         @continued_command_tag = tag
         @continuation_request_exception = nil
         begin
@@ -94,8 +118,18 @@ module Net
       end
     end
 
+    def non_sync_literal_allowed?(bytesize)
+      return unless capabilities_cached?
+      return "+" if capable?("LITERAL+")
+      return "-" if capable_literal_minus? && bytesize <= 4096
+      false
+    end
+
+    def capable_literal_minus?; capable?("LITERAL-") || capable?("IMAP4rev2") end
+
+    # NOTE: +num+ should already be an Integer
     def send_number_data(num)
-      put_string(num.to_s)
+      put_string(Integer(num).to_s)
     end
 
     def send_list_data(list, tag = nil)
@@ -115,67 +149,233 @@ module Net
     def send_date_data(date) put_string Net::IMAP.encode_date(date) end
     def send_time_data(time) put_string Net::IMAP.encode_time(time) end
 
-    def send_symbol_data(symbol)
-      put_string("\\" + symbol.to_s)
-    end
+    # simplistic emulation of CommandData = Data.define(:data)
+    class CommandData # :nodoc:
+      class << self
+        def new(arg = nil, data: arg) super(data: data) end
+        alias :[] :new
+      end
+
+      def initialize(data:)
+        @data = data
+        freeze
+      end
+
+      attr_reader :data
+
+      def to_h(&block) block ? to_h.to_h(&block) : { data: data } end
+      def ==(other)   self.class === other && to_h  ==  other.to_h  end
+      def eql?(other) self.class === other && to_h.eql?(other.to_h) end
+
+      # following class definition goes beyond the basic Data.define(:data)
+      ##
+
+      def self.validate(...)
+        data = new(...)
+        data.validate
+        data
+      end
 
-    class RawData # :nodoc:
       def send_data(imap, tag)
-        imap.__send__(:put_string, @data)
+        raise NoMethodError, "#{self.class} must implement #{__method__}"
       end
 
       def validate
       end
+    end
 
-      private
+    # Represents IMAP +text+ or +quoted+ data, which share the same
+    # validations of decoded #data, and differ only in how they are formatted.
+    #
+    # +data+ may contain any 7-bit ASCII character except +NULL+, +CR+, or +LF+.
+    # Any multibyte +UTF-8+ character is also allowed when the connection
+    # supports UTF8: either +UTF8=ACCEPT+ or +IMAP4rev2+ have been enabled, or
+    # the server supports only +IMAP4rev2+ and not earlier IMAP revisions, or
+    # the server advertises +UTF8=ONLY+.
+    #
+    # NOTE: This does not verify whether the connection supports UTF-8, but that
+    # may change in future versions.
+    #
+    # The string's bytes must be valid ASCII or valid UTF-8.  The string's
+    # reported encoding is ignored, but the string is _not_ transcoded.
+    class ValidNonLiteralData < CommandData
+      def initialize(data:)
+        data = String(data.to_str)
+        unless [Encoding::ASCII, Encoding::UTF_8].include?(data.encoding)
+          data = data.dup.force_encoding(data.ascii_only? ? "ASCII" : "UTF-8")
+        end
+        data = -data
+        super
+        validate
+      end
 
-      def initialize(data)
-        @data = data
+      def validate
+        if ![Encoding::ASCII, Encoding::UTF_8].include?(data.encoding)
+          raise DataFormatError, "must use ASCII or UTF-8 encoding"
+        elsif !data.valid_encoding?
+          raise DataFormatError, "invalid UTF-8 must be literal encoded"
+        elsif data.include?("\0")
+          raise DataFormatError, "NULL byte must be binary literal encoded"
+        elsif /[\r\n]/.match?(data)
+          raise DataFormatError, "CR and LF bytes must be literal encoded"
+        end
       end
+
+      def ascii_only?; data.ascii_only? end
+
+      def send_data(imap, tag = nil) imap.__send__(:put_string, formatted) end
     end
 
-    class Atom # :nodoc:
-      def send_data(imap, tag)
-        imap.__send__(:put_string, @data)
+    # Represents IMAP +text+ data, which covers everything in the IMAP grammar,
+    # except for +literal+, +literal8+, and the concluding +CRLF+.
+    #
+    # NOTE: The current implementation does not verify that the connection
+    # supports UTF-8.  Future versions may validate this.
+    class RawText < ValidNonLiteralData # :nodoc:
+      # raw: no formatting necessary
+      alias formatted data
+    end
+
+    class RawData < CommandData # :nodoc:
+      def initialize(data:)
+        case data
+        when String
+          data = self.class.split(data)
+        when Array
+          unless data.all? { |part| RawText === part || Literal === part }
+            raise TypeError, "expected String or Array[#{RawText} | #{Literal}]"
+          end
+        else
+          raise TypeError, "expected String or Array[#{RawText} | #{Literal}]"
+        end
+        super
+        validate
       end
 
+      def send_data(imap, tag) data.each do _1.send_data(imap, tag) end end
+
       def validate
+        return unless RawText === data.last
+        text = data.last.data
+        if text.rindex(/\{\d+\+?\}\z/n)
+          raise DataFormatError, "RawData cannot end with literal continuation"
+        end
       end
 
-      private
+      # Splits an input +string+ into an array of RawText and Literal/Literal8.
+      #
+      # NOTE: unlike RawData#validate, this does not prevent the final RawText
+      # from ending with a literal prefix.
+      def self.split(data)
+        data = data.b # dups and ensures BINARY encoding
+        parts = []
+        while data.match(/(~)?\{(0|[1-9]\d*)(\+)?\}\r\n/n)
+          text, binary, bytesize, non_sync, data = $`, !!$1, $2, !!$3, $'
+          bytesize = Integer bytesize, 10
+          parts << RawText[text] unless text.empty?
+          parts << extract_literal(data,
+                                   binary: binary,
+                                   bytesize: bytesize,
+                                   non_sync: non_sync)
+          data[0, bytesize] = ""
+        end
+        parts << RawText[data] unless data.empty?
+        parts
+      end
 
-      def initialize(data)
-        @data = data
+      def self.extract_literal(data, binary:, bytesize:, non_sync:)
+        if data.bytesize < bytesize
+          raise DataFormatError, "Too few bytes in string for literal, " \
+            "expected: %s, remaining: %s" % [bytesize, data.bytesize]
+        end
+        literal = data.byteslice(0, bytesize)
+        (binary ? Literal8 : Literal).new(data: literal, non_sync: non_sync)
       end
+      private_class_method :extract_literal
     end
 
-    class QuotedString # :nodoc:
-      def send_data(imap, tag)
-        imap.__send__(:send_quoted_string, @data)
+    class Atom < CommandData # :nodoc:
+      def initialize(**)
+        super
+        validate
       end
 
       def validate
+        data.to_s.ascii_only? \
+          or raise DataFormatError, "#{self.class} must be ASCII only"
+        data.match?(ResponseParser::Patterns::ATOM_SPECIALS) \
+          and raise DataFormatError, "#{self.class} must not contain atom-specials"
+        data.empty? \
+          and raise DataFormatError, "#{self.class} must not be empty"
       end
 
-      private
+      def send_data(imap, tag)
+        imap.__send__(:put_string, data.to_s)
+      end
+    end
 
-      def initialize(data)
-        @data = data
+    class Flag < Atom # :nodoc:
+      def send_data(imap, tag)
+        imap.__send__(:put_string, "\\#{data}")
       end
     end
 
+    # Represents a IMAP +quoted+ string, which can encode any valid ASCII or
+    # UTF-8 string, unless it contains any +CR+, +LF+, or +NULL+ bytes.
+    #
+    # NOTE: The current implementation does not verify that the connection
+    # supports UTF-8.  Future versions may validate this.
+    class QuotedString < ValidNonLiteralData # :nodoc:
+      def formatted; %("#{data.gsub(/["\\]/, "\\\\\\&")}") end
+    end
+
     class Literal # :nodoc:
-      def send_data(imap, tag)
-        imap.__send__(:send_literal, @data, tag)
+      class << self
+        def new(_data = nil, _non_sync = nil, data: _data, non_sync: _non_sync)
+          super(data: data, non_sync: non_sync)
+        end
+        alias :[] :new
+      end
+
+      attr_reader :data, :non_sync
+
+      def to_h(&block) block ? to_h.to_h(&block) : { data: data, non_sync: non_sync } end
+      def ==(other)   self.class === other && to_h  ==  other.to_h  end
+      def eql?(other) self.class === other && to_h.eql?(other.to_h) end
+
+      def initialize(data:, non_sync: nil)
+        data = -String(data.to_str).b or
+          raise DataFormatError, "#{self.class} expects string input"
+        @data, @non_sync = data, non_sync
+        validate
+        freeze
       end
 
+      def self.validate(...)
+        data = new(...)
+        data.validate
+        data
+      end
+
+      def bytesize; data.bytesize end
+
       def validate
+        if data.include?("\0")
+          raise DataFormatError, "NULL byte not allowed in #{self.class}.  " \
+            "Use #{Literal8} or a null-safe encoding."
+        end
       end
 
-      private
+      def send_data(imap, tag)
+        imap.__send__(:send_literal, data, tag, non_sync: non_sync)
+      end
+    end
 
-      def initialize(data)
-        @data = data
+    class Literal8 < Literal # :nodoc:
+      def validate; nil end # all bytes are okay
+
+      def send_data(imap, tag)
+        imap.__send__(:send_binary_literal, data, tag, non_sync: non_sync)
       end
     end
 

data/lib/net/imap/response_data.rb

@@ -295,6 +295,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
@@ -369,12 +377,24 @@ module Net
     # Net::IMAP#getquotaroot returns an array containing both MailboxQuotaRoot
     # and MailboxQuota objects.
     #
+    # ==== Required capability
+    #
+    # Requires +QUOTA+ [RFC2087[https://www.rfc-editor.org/rfc/rfc2087]]
+    # 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
@@ -386,7 +406,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

@@ -2055,10 +2055,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)
@@ -2086,10 +2083,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
@@ -2115,10 +2109,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
@@ -2133,6 +2124,23 @@ 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 = coerce_number64 len.to_i
+        val = @str[@pos, len]
+        @pos += len
+        Token.new(type, val)
+      end
+
+      # copied/adapted from NumValidator in v0.6
+      def coerce_number64(num)
+        int = num.to_i
+        return int if 0 <= int && int <= 0x7fff_ffff_ffff_ffff
+        raise DataFormatError,
+          "number64 must be unsigned 63-bit integer: #{num}"
       end
 
     end

data/lib/net/imap/response_reader.rb

@@ -4,10 +4,13 @@ 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
+        @buff = @literal_size = nil
       end
 
       def read_response_buffer
@@ -15,13 +18,13 @@ module Net
         catch :eof do
           while true
             read_line
-            break unless (@literal_size = get_literal_size)
+            break unless literal_size
             read_literal
           end
         end
         buff
       ensure
-        @buff = nil
+        @buff = @literal_size = nil
       end
 
       private
@@ -30,13 +33,21 @@ module Net
 
       def bytes_read;       buff.bytesize                         end
       def empty?;           buff.empty?                           end
-      def done?;            line_done? && !get_literal_size       end
+      def done?;            line_done? && !literal_size           end
       def line_done?;       buff.end_with?(CRLF)                  end
-      def get_literal_size; /\{(\d+)\}\r\n\z/n =~ buff && $1.to_i end
+
+      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)
+        line = (@sock.gets(CRLF, read_limit) or throw :eof)
+        buff << line
         max_response_remaining! unless line_done?
+        @literal_size = get_literal_size(line)
       end
 
       def read_literal
@@ -70,6 +81,14 @@ module Net
         )
       end
 
+      # copied/adapted from NumValidator in v0.6
+      def coerce_number64(num)
+        int = num.to_i
+        return int if 0 <= int && int <= 0x7fff_ffff_ffff_ffff
+        raise DataFormatError,
+          "number64 must be unsigned 63-bit integer: #{num}"
+      end
+
     end
   end
 end

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 } end
+
+        # Memoized ScramAlgorithm#client_key (needs #salt and #iterations)
+        def client_key; @client_key ||= compute_salted { super } end
+
+        # Memoized ScramAlgorithm#server_key (needs #salt and #iterations)
+        def server_key; @server_key ||= compute_salted { super } end
+
         # 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
+          String === salt        or raise Error, "unknown salt"
+          Integer === iterations 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.rb

@@ -460,6 +460,9 @@ module Net
   #   +LITERAL-+, and +SPECIAL-USE+.</em>
   #
   # ==== RFC2087: +QUOTA+
+  # +NOTE:+ Only the +STORAGE+ quota resource type is currently supported.
+  # - Obsoleted by <tt>QUOTA=RES-*</tt> [RFC9208[https://www.rfc-editor.org/rfc/rfc9208]],
+  #   although the commands are backward compatible.
   # - #getquota: returns the resource usage and limits for a quota root
   # - #getquotaroot: returns the list of quota roots for a mailbox, as well as
   #   their resource usage and limits.
@@ -572,6 +575,16 @@ module Net
   #   See FetchData#emailid and FetchData#emailid.
   # - Updates #status with support for the +MAILBOXID+ status attribute.
   #
+  # ==== RFC9208: <tt>QUOTA=RES-*</tt>
+  # +NOTE:+ Only the +STORAGE+ quota resource type is currently supported.
+  # - Obsoletes the +QUOTA+ [RFC2087[https://www.rfc-editor.org/rfc/rfc2087]]
+  #   extension and provides strict semantics for different resource types.
+  # - #getquota: returns the resource usage and limits for a quota root
+  # - #getquotaroot: returns the list of quota roots for a mailbox, as well as
+  #   their resource usage and limits.
+  # - #setquota: sets the resource limits for a given quota root.
+  # - Updates #status with <tt>"DELETED"</tt> and +DELETED-STORAGE+ attributes.
+  #
   # == References
   #
   # [{IMAP4rev1}[https://www.rfc-editor.org/rfc/rfc3501.html]]::
@@ -681,14 +694,13 @@ module Net
   #
   # === \IMAP Extensions
   #
-  # [QUOTA[https://tools.ietf.org/html/rfc9208]]::
-  #   Melnikov, A., "IMAP QUOTA Extension", RFC 9208, DOI 10.17487/RFC9208,
-  #   March 2022, <https://www.rfc-editor.org/info/rfc9208>.
+  # [QUOTA[https://www.rfc-editor.org/rfc/rfc2087]]::
+  #   Myers, J., "IMAP4 QUOTA extension", RFC 2087, DOI 10.17487/RFC2087,
+  #   January 1997, <https://www.rfc-editor.org/info/rfc2087>.
   #
-  #   <em>Note: obsoletes</em>
-  #   RFC-2087[https://tools.ietf.org/html/rfc2087]<em> (January 1997)</em>.
-  #   <em>Net::IMAP does not fully support the RFC9208 updates yet.</em>
-  # [IDLE[https://tools.ietf.org/html/rfc2177]]::
+  #   *NOTE*: _obsoleted_ by RFC9208[https://www.rfc-editor.org/rfc/rfc9208]
+  #   (March 2022).
+  # [IDLE[https://www.rfc-editor.org/rfc/rfc2177]]::
   #   Leiba, B., "IMAP4 IDLE command", RFC 2177, DOI 10.17487/RFC2177,
   #   June 1997, <https://www.rfc-editor.org/info/rfc2177>.
   # [NAMESPACE[https://tools.ietf.org/html/rfc2342]]::
@@ -739,9 +751,15 @@ module Net
   #   Gondwana, B., Ed., "IMAP Extension for Object Identifiers",
   #   RFC 8474, DOI 10.17487/RFC8474, September 2018,
   #   <https://www.rfc-editor.org/info/rfc8474>.
+  # [{QUOTA=RES-*}[https://www.rfc-editor.org/rfc/rfc9208]]::
+  #   Melnikov, A., "IMAP QUOTA Extension", RFC 9208, DOI 10.17487/RFC9208,
+  #   March 2022, <https://www.rfc-editor.org/info/rfc9208>.
+  #
+  #   Obsoletes RFC2087[https://www.rfc-editor.org/rfc/rfc2087].
   #
   # === IANA registries
   # * {IMAP Capabilities}[http://www.iana.org/assignments/imap4-capabilities]
+  #   * {IMAP Quota Resource Types}[http://www.iana.org/assignments/imap4-capabilities#imap-capabilities-2]
   # * {IMAP Response Codes}[https://www.iana.org/assignments/imap-response-codes/imap-response-codes.xhtml]
   # * {IMAP Mailbox Name Attributes}[https://www.iana.org/assignments/imap-mailbox-name-attributes/imap-mailbox-name-attributes.xhtml]
   # * {IMAP and JMAP Keywords}[https://www.iana.org/assignments/imap-jmap-keywords/imap-jmap-keywords.xhtml]
@@ -761,7 +779,7 @@ module Net
   # * {IMAP URLAUTH Authorization Mechanism Registry}[https://www.iana.org/assignments/urlauth-authorization-mechanism-registry/urlauth-authorization-mechanism-registry.xhtml]
   #
   class IMAP < Protocol
-    VERSION = "0.4.23"
+    VERSION = "0.4.25"
 
     # Aliases for supported capabilities, to be used with the #enable command.
     ENABLE_ALIASES = {
@@ -1031,26 +1049,22 @@ module Net
 
     # Disconnects from the server.
     #
+    # Waits for receiver thread to close before returning.  Slow or stuck
+    # response handlers can cause #disconnect to hang until they complete.
+    #
     # Related: #logout, #logout!
     def disconnect
       return if disconnected?
+      in_receiver_thread = Thread.current == @receiver_thread
       begin
-        begin
-          # try to call SSL::SSLSocket#io.
-          @sock.io.shutdown
-        rescue NoMethodError
-          # @sock is not an SSL::SSLSocket.
-          @sock.shutdown
-        end
+        @sock.to_io.shutdown
       rescue Errno::ENOTCONN
         # ignore `Errno::ENOTCONN: Socket is not connected' on some platforms.
       rescue Exception => e
-        @receiver_thread.raise(e)
-      end
-      @receiver_thread.join
-      synchronize do
-        @sock.close
+        @receiver_thread.raise(e) unless in_receiver_thread
       end
+      @sock.close
+      @receiver_thread.join unless mon_owned? || in_receiver_thread
       raise e if e
     end
 
@@ -1294,9 +1308,11 @@ module Net
     #
     def starttls(**options)
       @ssl_ctx_params, @ssl_ctx = build_ssl_ctx(options)
+      handled = false
       error = nil
       ok = send_command("STARTTLS") do |resp|
         if resp.kind_of?(TaggedResponse) && resp.name == "OK"
+          handled = true
           clear_cached_capabilities
           clear_responses
           start_tls_session
@@ -1308,6 +1324,13 @@ module Net
         disconnect
         raise error
       end
+      unless handled
+        disconnect
+        raise InvalidResponseError,
+              "STARTTLS handler was bypassed, although server responded %p" % [
+                ok.raw_data.chomp
+              ]
+      end
       ok
     end
 
@@ -1742,12 +1765,18 @@ module Net
     # to both admin and user.  If this mailbox exists, it returns an array
     # containing objects of type MailboxQuotaRoot and MailboxQuota.
     #
+    # *NOTE:* Currently, Net::IMAP only supports +QUOTA+ responses with a single
+    # resource type.  This is usually +STORAGE+, but you may need to verify this
+    # with UntaggedResponse#raw_data.
+    #
     # Related: #getquota, #setquota, MailboxQuotaRoot, MailboxQuota
     #
     # ===== Capabilities
     #
-    # The server's capabilities must include +QUOTA+
-    # [RFC2087[https://tools.ietf.org/html/rfc2087]].
+    # Requires +QUOTA+ [RFC2087[https://www.rfc-editor.org/rfc/rfc2087]]
+    # capability, or a capability prefixed with <tt>QUOTA=RES-*</tt>
+    # {[RFC9208]}[https://www.rfc-editor.org/rfc/rfc9208] for each supported
+    # resource type.
     def getquotaroot(mailbox)
       synchronize do
         send_command("GETQUOTAROOT", mailbox)
@@ -1759,41 +1788,59 @@ module Net
     end
 
     # Sends a {GETQUOTA command [RFC2087 §4.2]}[https://www.rfc-editor.org/rfc/rfc2087#section-4.2]
-    # along with specified +mailbox+.  If this mailbox exists, then an array
-    # containing a MailboxQuota object is returned.  This command is generally
-    # only available to server admin.
+    # for the +quota_root+.  If this quota root exists, then an array
+    # containing a MailboxQuota object is returned.
+    #
+    # The names of quota roots that are applicable to a particular mailbox can
+    # be discovered with #getquotaroot.
+    #
+    # *NOTE:* Currently, Net::IMAP only supports +QUOTA+ responses with a single
+    # resource type.  This is usually +STORAGE+, but you may need to verify this
+    # with UntaggedResponse#raw_data.
     #
     # Related: #getquotaroot, #setquota, MailboxQuota
     #
     # ===== Capabilities
     #
-    # The server's capabilities must include +QUOTA+
-    # [RFC2087[https://tools.ietf.org/html/rfc2087]].
-    def getquota(mailbox)
+    # Requires +QUOTA+ [RFC2087[https://www.rfc-editor.org/rfc/rfc2087]]
+    # capability, or a capability prefixed with <tt>QUOTA=RES-*</tt>
+    # {[RFC9208]}[https://www.rfc-editor.org/rfc/rfc9208] for each supported
+    # resource type.
+    def getquota(quota_root)
       synchronize do
-        send_command("GETQUOTA", mailbox)
+        send_command("GETQUOTA", quota_root)
         clear_responses("QUOTA")
       end
     end
 
     # Sends a {SETQUOTA command [RFC2087 §4.1]}[https://www.rfc-editor.org/rfc/rfc2087#section-4.1]
-    # along with the specified +mailbox+ and +quota+.  If +quota+ is nil, then
-    # +quota+ will be unset for that mailbox.  Typically one needs to be logged
-    # in as a server admin for this to work.
+    # along with the specified +quota_root+ and +storage_limit+.  If
+    # +storage_limit+ is +nil+, resource limits are unset for that quota root.
+    # If +storage_limit+ is a number, it sets the +STORAGE+ resource limit.
+    #
+    #   imap.setquota "#user/alice", 100
+    #   imap.getquota "#user/alice"
+    #   # => [#<struct Net::IMAP::MailboxQuota mailbox="#user/alice" usage=54 quota=100>]
+    #
+    # Typically one needs to be logged in as a server admin for this to work.
+    #
+    # *NOTE:* Currently, Net::IMAP only supports setting +STORAGE+ quota limits.
     #
     # Related: #getquota, #getquotaroot
     #
     # ===== Capabilities
     #
-    # The server's capabilities must include +QUOTA+
-    # [RFC2087[https://tools.ietf.org/html/rfc2087]].
-    def setquota(mailbox, quota)
-      if quota.nil?
-        data = '()'
+    # Requires +QUOTA+ [RFC2087[https://www.rfc-editor.org/rfc/rfc2087]]
+    # capability, or both +QUOTASET+ and a capability prefixed with
+    # <tt>QUOTA=RES-*</tt> {[RFC9208]}[https://www.rfc-editor.org/rfc/rfc9208]
+    # for each supported resource type.
+    def setquota(quota_root, storage_limit)
+      if storage_limit.nil?
+        list = []
       else
-        data = '(STORAGE ' + quota.to_s + ')'
+        list = ["STORAGE", Integer(storage_limit)]
       end
-      send_command("SETQUOTA", mailbox, RawData.new(data))
+      send_command("SETQUOTA", quota_root, list)
     end
 
     # Sends a {SETACL command [RFC4314 §3.1]}[https://www.rfc-editor.org/rfc/rfc4314#section-3.1]
@@ -1900,7 +1947,10 @@ module Net
     # <tt>STATUS=SIZE</tt>
     # {[RFC8483]}[https://www.rfc-editor.org/rfc/rfc8483.html].
     #
-    # +DELETED+ requires the server's capabilities to include +IMAP4rev2+.
+    # +DELETED+ must be supported when the server's capabilities includes
+    # +IMAP4rev2+.
+    # or <tt>QUOTA=RES-MESSAGES</tt>
+    # {[RFC9208]}[https://www.rfc-editor.org/rfc/rfc9208.html].
     #
     # +HIGHESTMODSEQ+ requires the server's capabilities to include +CONDSTORE+
     # {[RFC7162]}[https://www.rfc-editor.org/rfc/rfc7162.html].
@@ -2041,6 +2091,8 @@ module Net
     # string holding the entire search string, or a single-dimension array of
     # search keywords and arguments.
     #
+    # <em>Please note</em> the warning (below) when +keys+ is a String.
+    #
     # Returns a SearchResult object.  SearchResult inherits from Array (for
     # backward compatibility) but adds SearchResult#modseq when the +CONDSTORE+
     # capability has been enabled.
@@ -2049,6 +2101,14 @@ module Net
     #
     # ===== Search criteria
     #
+    # >>>
+    #   When +keys+ is an Array, elements in the array will be validated and
+    #   formatted.  When +keys+ is a String, it will be sent <em>with
+    #   minimal validation and no encoding or formatting</em>.
+    #
+    #   <em>*WARNING:* Although CRLF is prohibited, this is vulnerable to other
+    #   types of attribute injection attack if unvetted user input is used.</em>
+    #
     # For a full list of search criteria,
     # see [{IMAP4rev1 §6.4.4}[https://www.rfc-editor.org/rfc/rfc3501.html#section-6.4.4]],
     # or  [{IMAP4rev2 §6.4.4}[https://www.rfc-editor.org/rfc/rfc9051.html#section-6.4.4]],
@@ -2114,7 +2174,8 @@ module Net
     # backward compatibility) but adds SearchResult#modseq when the +CONDSTORE+
     # capability has been enabled.
     #
-    # See #search for documentation of search criteria.
+    # See #search for documentation of parameters.  <em>Please note</em> the
+    # warning for when +keys+ is a String.
     def uid_search(keys, charset = nil)
       return search_internal("UID SEARCH", keys, charset)
     end
@@ -2136,6 +2197,13 @@ module Net
     #
     # +attr+ is a list of attributes to fetch; see the documentation
     # for FetchData for a list of valid attributes.
+    # >>>
+    #   When +attr+ is a String, it will be sent <em>with minimal validation and
+    #   no encoding or formatting</em>.  When +attr+ is an Array, each String in
+    #   +attr+ will be sent this way.
+    #
+    #   <em>*WARNING:* Although CRLF is prohibited, this is vulnerable to other
+    #   types of attribute injection attack if unvetted user input is used.</em>
     #
     # +changedsince+ is an optional integer mod-sequence.  It limits results to
     # messages with a mod-sequence greater than +changedsince+.
@@ -2184,6 +2252,8 @@ module Net
     # Similar to #fetch, but the +set+ parameter contains unique identifiers
     # instead of message sequence numbers.
     #
+    # +attr+ behaves the same as with #fetch.  <em>Please note</em> the #fetch
+    # warning on the +attr+ argument.
     # >>>
     #   *Note:* Servers _MUST_ implicitly include the +UID+ message data item as
     #   part of any +FETCH+ response caused by a +UID+ command, regardless of
@@ -2336,8 +2406,10 @@ module Net
 
     # Sends a {SORT command [RFC5256 §3]}[https://www.rfc-editor.org/rfc/rfc5256#section-3]
     # to search a mailbox for messages that match +search_keys+ and return an
-    # array of message sequence numbers, sorted by +sort_keys+.  +search_keys+
-    # are interpreted the same as for #search.
+    # array of message sequence numbers, sorted by +sort_keys+.
+    #
+    # +search_keys+ are interpreted the same as the +criteria+ argument for
+    # #search.  <em>Please note</em> the #search warning for String +criteria+.
     #
     #--
     # TODO: describe +sort_keys+
@@ -2362,8 +2434,10 @@ module Net
 
     # Sends a {UID SORT command [RFC5256 §3]}[https://www.rfc-editor.org/rfc/rfc5256#section-3]
     # to search a mailbox for messages that match +search_keys+ and return an
-    # array of unique identifiers, sorted by +sort_keys+.  +search_keys+ are
-    # interpreted the same as for #search.
+    # array of unique identifiers, sorted by +sort_keys+.
+    #
+    # +search_keys+ are interpreted the same as the +criteria+ argument for
+    # #search.  <em>Please note</em> the #search warning for String +criteria+.
     #
     # Related: #sort, #search, #uid_search, #thread, #uid_thread
     #
@@ -2377,8 +2451,10 @@ module Net
 
     # Sends a {THREAD command [RFC5256 §3]}[https://www.rfc-editor.org/rfc/rfc5256#section-3]
     # to search a mailbox and return message sequence numbers in threaded
-    # format, as a ThreadMember tree.  +search_keys+ are interpreted the same as
-    # for #search.
+    # format, as a ThreadMember tree.
+    #
+    # +search_keys+ are interpreted the same as the +criteria+ argument for
+    # #search.  <em>Please note</em> the #search warning for String +criteria+.
     #
     # The supported algorithms are:
     #
@@ -2404,6 +2480,9 @@ module Net
     # Similar to #thread, but returns unique identifiers instead of
     # message sequence numbers.
     #
+    # +search_keys+ are interpreted the same as the +criteria+ argument for
+    # #search.  <em>Please note</em> the #search warning for String +criteria+.
+    #
     # Related: #thread, #search, #uid_search, #sort, #uid_sort
     #
     # ===== Capabilities
@@ -2491,10 +2570,11 @@ module Net
       capabilities = capabilities
         .flatten
         .map {|e| ENABLE_ALIASES[e] || e }
+        .flat_map { _1.is_a?(String) && !_1.empty? ? _1.split(/ /, -1) : [_1] }
         .uniq
-        .join(' ')
+        .map { Atom[_1] }
       synchronize do
-        send_command("ENABLE #{capabilities}")
+        send_command("ENABLE", *capabilities)
         result = clear_responses("ENABLED").last || []
         @utf8_strings ||= result.include? "UTF8=ACCEPT"
         @utf8_strings ||= result.include? "IMAP4REV2"
@@ -2992,6 +3072,7 @@ module Net
           put_string(" ")
           send_data(i, tag)
         end
+        guard_against_tagged_response_skipping_handler!(tag)
         put_string(CRLF)
         if cmd == "LOGOUT"
           @logout_command_tag = tag
@@ -3007,6 +3088,17 @@ module Net
           end
         end
       end
+    rescue InvalidResponseError
+      disconnect
+      raise
+    end
+
+    def guard_against_tagged_response_skipping_handler!(tag)
+      return unless (resp = @tagged_responses[tag])&.name&.upcase == "OK"
+      raise(InvalidResponseError,
+            "Server sent tagged 'OK' before command was finished: %p. " \
+            "This could indicate a malicious server or client-side " \
+            "command injection. Disconnecting." % [resp.raw_data.chomp])
     end
 
     def generate_tag
@@ -3071,7 +3163,7 @@ module Net
     end
 
     def store_internal(cmd, set, attr, flags, unchangedsince: nil)
-      attr = RawData.new(attr) if attr.instance_of?(String)
+      attr = Atom.new(attr) if attr.instance_of?(String)
       args = [MessageSet.new(set)]
       args << ["UNCHANGEDSINCE", Integer(unchangedsince)] if unchangedsince
       args << attr << flags

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: net-imap
 version: !ruby/object:Gem::Version
-  version: 0.4.23
+  version: 0.4.25
 platform: ruby
 authors:
 - Shugo Maeda
@@ -125,7 +125,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Ruby client api for Internet Message Access Protocol
 test_files: []