net-imap 0.2.1 → 0.2.2

data/lib/net/imap/authenticators.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# Registry for SASL authenticators used by Net::IMAP.
+module Net::IMAP::Authenticators
+
+  # Adds an authenticator for use with Net::IMAP#authenticate.  +auth_type+ is the
+  # {SASL mechanism}[https://www.iana.org/assignments/sasl-mechanisms/sasl-mechanisms.xhtml]
+  # supported by +authenticator+ (for instance, "+PLAIN+").  The +authenticator+
+  # is an object which defines a +#process+ method to handle authentication with
+  # the server.  See Net::IMAP::PlainAuthenticator, Net::IMAP::LoginAuthenticator,
+  # Net::IMAP::CramMD5Authenticator, and Net::IMAP::DigestMD5Authenticator for
+  # examples.
+  #
+  # If +auth_type+ refers to an existing authenticator, it will be
+  # replaced by the new one.
+  def add_authenticator(auth_type, authenticator)
+    authenticators[auth_type] = authenticator
+  end
+
+  # Builds an authenticator for Net::IMAP#authenticate.  +args+ will be passed
+  # directly to the chosen authenticator's +#initialize+.
+  def authenticator(auth_type, *args)
+    auth_type = auth_type.upcase
+    unless authenticators.has_key?(auth_type)
+      raise ArgumentError,
+        format('unknown auth type - "%s"', auth_type)
+    end
+    authenticators[auth_type].new(*args)
+  end
+
+  private
+
+  def authenticators
+    @authenticators ||= {}
+  end
+
+end
+
+Net::IMAP.extend Net::IMAP::Authenticators
+
+require_relative "authenticators/login"
+require_relative "authenticators/plain"
+require_relative "authenticators/cram_md5"
+require_relative "authenticators/digest_md5"

data/lib/net/imap/authenticators/cram_md5.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "digest/md5"
+
+# Authenticator for the "+CRAM-MD5+" SASL mechanism, specified in
+# RFC2195[https://tools.ietf.org/html/rfc2195].  See Net::IMAP#authenticate.
+#
+# == Deprecated
+#
+# +CRAM-MD5+ is obsolete and insecure.  It is included for compatibility with
+# existing servers.
+# {draft-ietf-sasl-crammd5-to-historic}[https://tools.ietf.org/html/draft-ietf-sasl-crammd5-to-historic-00.html]
+# recommends using +SCRAM-*+ or +PLAIN+ protected by TLS instead.
+#
+# Additionally, RFC8314[https://tools.ietf.org/html/rfc8314] discourage the use
+# of cleartext and recommends TLS version 1.2 or greater be used for all
+# traffic.  With TLS +CRAM-MD5+ is okay, but so is +PLAIN+
+class Net::IMAP::CramMD5Authenticator
+  def process(challenge)
+    digest = hmac_md5(challenge, @password)
+    return @user + " " + digest
+  end
+
+  private
+
+  def initialize(user, password)
+    @user = user
+    @password = password
+  end
+
+  def hmac_md5(text, key)
+    if key.length > 64
+      key = Digest::MD5.digest(key)
+    end
+
+    k_ipad = key + "\0" * (64 - key.length)
+    k_opad = key + "\0" * (64 - key.length)
+    for i in 0..63
+      k_ipad[i] = (k_ipad[i].ord ^ 0x36).chr
+      k_opad[i] = (k_opad[i].ord ^ 0x5c).chr
+    end
+
+    digest = Digest::MD5.digest(k_ipad + text)
+
+    return Digest::MD5.hexdigest(k_opad + digest)
+  end
+
+  Net::IMAP.add_authenticator "PLAIN", self
+end

data/lib/net/imap/authenticators/digest_md5.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "digest/md5"
+require "strscan"
+
+# Net::IMAP authenticator for the "`DIGEST-MD5`" SASL mechanism type, specified
+# in RFC2831(https://tools.ietf.org/html/rfc2831).  See Net::IMAP#authenticate.
+#
+# == Deprecated
+#
+# "+DIGEST-MD5+" has been deprecated by
+# {RFC6331}[https://tools.ietf.org/html/rfc6331] and should not be relied on for
+# security.  It is included for compatibility with existing servers.
+class Net::IMAP::DigestMD5Authenticator
+  def process(challenge)
+    case @stage
+    when STAGE_ONE
+      @stage = STAGE_TWO
+      sparams = {}
+      c = StringScanner.new(challenge)
+      while c.scan(/(?:\s*,)?\s*(\w+)=("(?:[^\\"]+|\\.)*"|[^,]+)\s*/)
+        k, v = c[1], c[2]
+        if v =~ /^"(.*)"$/
+          v = $1
+          if v =~ /,/
+            v = v.split(',')
+          end
+        end
+        sparams[k] = v
+      end
+
+      raise DataFormatError, "Bad Challenge: '#{challenge}'" unless c.rest.size == 0
+      raise Error, "Server does not support auth (qop = #{sparams['qop'].join(',')})" unless sparams['qop'].include?("auth")
+
+      response = {
+        :nonce => sparams['nonce'],
+        :username => @user,
+        :realm => sparams['realm'],
+        :cnonce => Digest::MD5.hexdigest("%.15f:%.15f:%d" % [Time.now.to_f, rand, Process.pid.to_s]),
+        :'digest-uri' => 'imap/' + sparams['realm'],
+        :qop => 'auth',
+        :maxbuf => 65535,
+        :nc => "%08d" % nc(sparams['nonce']),
+        :charset => sparams['charset'],
+      }
+
+      response[:authzid] = @authname unless @authname.nil?
+
+      # now, the real thing
+      a0 = Digest::MD5.digest( [ response.values_at(:username, :realm), @password ].join(':') )
+
+      a1 = [ a0, response.values_at(:nonce,:cnonce) ].join(':')
+      a1 << ':' + response[:authzid] unless response[:authzid].nil?
+
+      a2 = "AUTHENTICATE:" + response[:'digest-uri']
+      a2 << ":00000000000000000000000000000000" if response[:qop] and response[:qop] =~ /^auth-(?:conf|int)$/
+
+      response[:response] = Digest::MD5.hexdigest(
+        [
+          Digest::MD5.hexdigest(a1),
+          response.values_at(:nonce, :nc, :cnonce, :qop),
+          Digest::MD5.hexdigest(a2)
+        ].join(':')
+      )
+
+      return response.keys.map {|key| qdval(key.to_s, response[key]) }.join(',')
+    when STAGE_TWO
+      @stage = nil
+      # if at the second stage, return an empty string
+      if challenge =~ /rspauth=/
+        return ''
+      else
+        raise ResponseParseError, challenge
+      end
+    else
+      raise ResponseParseError, challenge
+    end
+  end
+
+  def initialize(user, password, authname = nil)
+    @user, @password, @authname = user, password, authname
+    @nc, @stage = {}, STAGE_ONE
+  end
+
+  private
+
+  STAGE_ONE = :stage_one
+  STAGE_TWO = :stage_two
+
+  def nc(nonce)
+    if @nc.has_key? nonce
+      @nc[nonce] = @nc[nonce] + 1
+    else
+      @nc[nonce] = 1
+    end
+    return @nc[nonce]
+  end
+
+  # some responses need quoting
+  def qdval(k, v)
+    return if k.nil? or v.nil?
+    if %w"username authzid realm nonce cnonce digest-uri qop".include? k
+      v.gsub!(/([\\"])/, "\\\1")
+      return '%s="%s"' % [k, v]
+    else
+      return '%s=%s' % [k, v]
+    end
+  end
+
+  Net::IMAP.add_authenticator "DIGEST-MD5", self
+end

data/lib/net/imap/authenticators/login.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# Authenticator for the "+LOGIN+" SASL mechanism.  See Net::IMAP#authenticate.
+#
+# +LOGIN+ authentication sends the password in cleartext.
+# RFC3501[https://tools.ietf.org/html/rfc3501] encourages servers to disable
+# cleartext authentication until after TLS has been negotiated.
+# RFC8314[https://tools.ietf.org/html/rfc8314] recommends TLS version 1.2 or
+# greater be used for all traffic, and deprecate cleartext access ASAP.  +LOGIN+
+# can be secured by TLS encryption.
+#
+# == Deprecated
+#
+# The {SASL mechanisms
+# registry}[https://www.iana.org/assignments/sasl-mechanisms/sasl-mechanisms.xhtml]
+# marks "LOGIN" as obsoleted in favor of "PLAIN".  It is included here for
+# compatibility with existing servers.  See
+# {draft-murchison-sasl-login}[https://www.iana.org/go/draft-murchison-sasl-login]
+# for both specification and deprecation.
+class Net::IMAP::LoginAuthenticator
+  def process(data)
+    case @state
+    when STATE_USER
+      @state = STATE_PASSWORD
+      return @user
+    when STATE_PASSWORD
+      return @password
+    end
+  end
+
+  private
+
+  STATE_USER = :USER
+  STATE_PASSWORD = :PASSWORD
+
+  def initialize(user, password)
+    @user = user
+    @password = password
+    @state = STATE_USER
+  end
+
+  Net::IMAP.add_authenticator "LOGIN", self
+end

data/lib/net/imap/authenticators/plain.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# Authenticator for the "+PLAIN+" SASL mechanism, specified in
+# RFC4616[https://tools.ietf.org/html/rfc4616].  See Net::IMAP#authenticate.
+#
+# +PLAIN+ authentication sends the password in cleartext.
+# RFC3501[https://tools.ietf.org/html/rfc3501] encourages servers to disable
+# cleartext authentication until after TLS has been negotiated.
+# RFC8314[https://tools.ietf.org/html/rfc8314] recommends TLS version 1.2 or
+# greater be used for all traffic, and deprecate cleartext access ASAP.  +PLAIN+
+# can be secured by TLS encryption.
+class Net::IMAP::PlainAuthenticator
+
+  def process(data)
+    return "#@authzid\0#@username\0#@password"
+  end
+
+  # :nodoc:
+  NULL = -"\0".b
+
+  private
+
+  # +username+ is the authentication identity, the identity whose +password+ is
+  # used.  +username+ is referred to as +authcid+ by
+  # RFC4616[https://tools.ietf.org/html/rfc4616].
+  #
+  # +authzid+ is the authorization identity (identity to act as).  It can
+  # usually be left blank. When +authzid+ is left blank (nil or empty string)
+  # the server will derive an identity from the credentials and use that as the
+  # authorization identity.
+  def initialize(username, password, authzid: nil)
+    raise ArgumentError, "username contains NULL" if username&.include?(NULL)
+    raise ArgumentError, "password contains NULL" if password&.include?(NULL)
+    raise ArgumentError, "authzid  contains NULL" if authzid&.include?(NULL)
+    @username = username
+    @password = password
+    @authzid  = authzid
+  end
+
+  Net::IMAP.add_authenticator "PLAIN", self
+end

data/lib/net/imap/command_data.rb

@@ -0,0 +1,301 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP < Protocol
+
+    private
+
+    def validate_data(data)
+      case data
+      when nil
+      when String
+      when Integer
+        NumValidator.ensure_number(data)
+      when Array
+        if data[0] == 'CHANGEDSINCE'
+          NumValidator.ensure_mod_sequence_value(data[1])
+        else
+          data.each do |i|
+            validate_data(i)
+          end
+        end
+      when Time
+      when Symbol
+      else
+        data.validate
+      end
+    end
+
+    def send_data(data, tag = nil)
+      case data
+      when nil
+        put_string("NIL")
+      when String
+        send_string_data(data, tag)
+      when Integer
+        send_number_data(data)
+      when Array
+        send_list_data(data, tag)
+      when Time
+        send_time_data(data)
+      when Symbol
+        send_symbol_data(data)
+      else
+        data.send_data(self, tag)
+      end
+    end
+
+    def send_string_data(str, tag = nil)
+      case str
+      when ""
+        put_string('""')
+      when /[\x80-\xff\r\n]/n
+        # literal
+        send_literal(str, tag)
+      when /[(){ \x00-\x1f\x7f%*"\\]/n
+        # quoted string
+        send_quoted_string(str)
+      else
+        put_string(str)
+      end
+    end
+
+    def send_quoted_string(str)
+      put_string('"' + str.gsub(/["\\]/n, "\\\\\\&") + '"')
+    end
+
+    def send_literal(str, tag = nil)
+      synchronize do
+        put_string("{" + str.bytesize.to_s + "}" + CRLF)
+        @continued_command_tag = tag
+        @continuation_request_exception = nil
+        begin
+          @continuation_request_arrival.wait
+          e = @continuation_request_exception || @exception
+          raise e if e
+          put_string(str)
+        ensure
+          @continued_command_tag = nil
+          @continuation_request_exception = nil
+        end
+      end
+    end
+
+    def send_number_data(num)
+      put_string(num.to_s)
+    end
+
+    def send_list_data(list, tag = nil)
+      put_string("(")
+      first = true
+      list.each do |i|
+        if first
+          first = false
+        else
+          put_string(" ")
+        end
+        send_data(i, tag)
+      end
+      put_string(")")
+    end
+
+    DATE_MONTH = %w(Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec)
+
+    def send_time_data(time)
+      t = time.dup.gmtime
+      s = format('"%2d-%3s-%4d %02d:%02d:%02d +0000"',
+                 t.day, DATE_MONTH[t.month - 1], t.year,
+                 t.hour, t.min, t.sec)
+      put_string(s)
+    end
+
+    def send_symbol_data(symbol)
+      put_string("\\" + symbol.to_s)
+    end
+
+    class RawData # :nodoc:
+      def send_data(imap, tag)
+        imap.__send__(:put_string, @data)
+      end
+
+      def validate
+      end
+
+      private
+
+      def initialize(data)
+        @data = data
+      end
+    end
+
+    class Atom # :nodoc:
+      def send_data(imap, tag)
+        imap.__send__(:put_string, @data)
+      end
+
+      def validate
+      end
+
+      private
+
+      def initialize(data)
+        @data = data
+      end
+    end
+
+    class QuotedString # :nodoc:
+      def send_data(imap, tag)
+        imap.__send__(:send_quoted_string, @data)
+      end
+
+      def validate
+      end
+
+      private
+
+      def initialize(data)
+        @data = data
+      end
+    end
+
+    class Literal # :nodoc:
+      def send_data(imap, tag)
+        imap.__send__(:send_literal, @data, tag)
+      end
+
+      def validate
+      end
+
+      private
+
+      def initialize(data)
+        @data = data
+      end
+    end
+
+    class MessageSet # :nodoc:
+      def send_data(imap, tag)
+        imap.__send__(:put_string, format_internal(@data))
+      end
+
+      def validate
+        validate_internal(@data)
+      end
+
+      private
+
+      def initialize(data)
+        @data = data
+      end
+
+      def format_internal(data)
+        case data
+        when "*"
+          return data
+        when Integer
+          if data == -1
+            return "*"
+          else
+            return data.to_s
+          end
+        when Range
+          return format_internal(data.first) +
+            ":" + format_internal(data.last)
+        when Array
+          return data.collect {|i| format_internal(i)}.join(",")
+        when ThreadMember
+          return data.seqno.to_s +
+            ":" + data.children.collect {|i| format_internal(i).join(",")}
+        end
+      end
+
+      def validate_internal(data)
+        case data
+        when "*"
+        when Integer
+          NumValidator.ensure_nz_number(data)
+        when Range
+        when Array
+          data.each do |i|
+            validate_internal(i)
+          end
+        when ThreadMember
+          data.children.each do |i|
+            validate_internal(i)
+          end
+        else
+          raise DataFormatError, data.inspect
+        end
+      end
+    end
+
+    class ClientID # :nodoc:
+
+      def send_data(imap, tag)
+        imap.__send__(:send_data, format_internal(@data), tag)
+      end
+
+      def validate
+        validate_internal(@data)
+      end
+
+      private
+
+      def initialize(data)
+        @data = data
+      end
+
+      def validate_internal(client_id)
+        client_id.to_h.each do |k,v|
+          unless StringFormatter.valid_string?(k)
+            raise DataFormatError, client_id.inspect
+          end
+        end
+      rescue NoMethodError, TypeError # to_h failed
+        raise DataFormatError, client_id.inspect
+      end
+
+      def format_internal(client_id)
+        return nil if client_id.nil?
+        client_id.to_h.flat_map {|k,v|
+          [StringFormatter.string(k), StringFormatter.nstring(v)]
+        }
+      end
+
+    end
+
+    module StringFormatter
+
+      LITERAL_REGEX = /[\x80-\xff\r\n]/n
+
+      module_function
+
+      # Allows symbols in addition to strings
+      def valid_string?(str)
+        str.is_a?(Symbol) || str.respond_to?(:to_str)
+      end
+
+      # Allows nil, symbols, and strings
+      def valid_nstring?(str)
+        str.nil? || valid_string?(str)
+      end
+
+      # coerces using +to_s+
+      def string(str)
+        str = str.to_s
+        if str =~ LITERAL_REGEX
+          Literal.new(str)
+        else
+          QuotedString.new(str)
+        end
+      end
+
+      # coerces non-nil using +to_s+
+      def nstring(str)
+        str.nil? ? nil : string(str)
+      end
+
+    end
+
+  end
+end