net-imap 0.3.8 → 0.4.0

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP < Protocol
+    module SASL
+
+      # Authenticator for the "+ANONYMOUS+" SASL mechanism, as specified by
+      # RFC-4505[https://tools.ietf.org/html/rfc4505].  See
+      # Net::IMAP#authenticate.
+      class AnonymousAuthenticator
+
+        # An optional token sent for the +ANONYMOUS+ mechanism., up to 255 UTF-8
+        # characters in length.
+        #
+        # If it contains an "@" sign, the message must be a valid email address
+        # (+addr-spec+ from RFC-2822[https://tools.ietf.org/html/rfc2822]).
+        # Email syntax is _not_ validated by AnonymousAuthenticator.
+        #
+        # Otherwise, it can be any UTF8 string which is permitted by the
+        # StringPrep::Trace profile.
+        attr_reader :anonymous_message
+
+        # :call-seq:
+        #   new(anonymous_message = "", **) -> authenticator
+        #   new(anonymous_message:  "", **) -> authenticator
+        #
+        # Creates an Authenticator for the "+ANONYMOUS+" SASL mechanism, as
+        # specified in RFC-4505[https://tools.ietf.org/html/rfc4505].  To use
+        # this, see Net::IMAP#authenticate or your client's authentication
+        # method.
+        #
+        # #anonymous_message is an optional message which is sent to the server.
+        # It may be sent as a positional argument or as a keyword argument.
+        #
+        # Any other keyword arguments are silently ignored.
+        def initialize(anon_msg = nil, anonymous_message: nil, **)
+          message = (anonymous_message || anon_msg || "").to_str
+          @anonymous_message = StringPrep::Trace.stringprep_trace message
+          if (size = @anonymous_message&.length)&.> 255
+            raise ArgumentError,
+                  "anonymous_message is too long.  (%d codepoints)" % [size]
+          end
+          @done = false
+        end
+
+        # :call-seq:
+        #   initial_response? -> true
+        #
+        # +ANONYMOUS+ can send an initial client response.
+        def initial_response?; true end
+
+        # Returns #anonymous_message.
+        def process(_server_challenge_string)
+          anonymous_message
+        ensure
+          @done = true
+        end
+
+        # Returns true when the initial client response was sent.
+        #
+        # The authentication should not succeed unless this returns true, but it
+        # does *not* indicate success.
+        def done?; @done end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Net::IMAP::SASL
+
+  # Registry for SASL authenticators
+  #
+  # Registered authenticators must respond to +#new+ or +#call+ (e.g. a class or
+  # a proc), receiving any credentials and options and returning an
+  # authenticator instance. The returned object represents a single
+  # authentication exchange and <em>must not</em> be reused for multiple
+  # authentication attempts.
+  #
+  # An authenticator instance object must respond to +#process+, receiving the
+  # server's challenge and returning the client's response.  Optionally, it may
+  # also respond to +#initial_response?+ and +#done?+.  When
+  # +#initial_response?+ returns +true+, +#process+ may be called the first
+  # time with +nil+.  When +#done?+ returns +false+, the exchange is incomplete
+  # and an exception should be raised if the exchange terminates prematurely.
+  #
+  # See the source for PlainAuthenticator, XOAuth2Authenticator, and
+  # ScramSHA1Authenticator for examples.
+  class Authenticators
+
+    # Create a new Authenticators registry.
+    #
+    # This class is usually not instantiated directly.  Use SASL.authenticators
+    # to reuse the default global registry.
+    #
+    # When +use_defaults+ is +false+, the registry will start empty.  When
+    # +use_deprecated+ is +false+, deprecated authenticators will not be
+    # included with the defaults.
+    def initialize(use_defaults: true, use_deprecated: true)
+      @authenticators = {}
+      return unless use_defaults
+      add_authenticator "Anonymous"
+      add_authenticator "External"
+      add_authenticator "OAuthBearer"
+      add_authenticator "Plain"
+      add_authenticator "Scram-SHA-1"
+      add_authenticator "Scram-SHA-256"
+      add_authenticator "XOAuth2"
+      return unless use_deprecated
+      add_authenticator "Login"      # deprecated
+      add_authenticator "Cram-MD5"   # deprecated
+      add_authenticator "Digest-MD5" # deprecated
+    end
+
+    # Returns the names of all registered SASL mechanisms.
+    def names; @authenticators.keys end
+
+    # :call-seq:
+    #   add_authenticator(mechanism)
+    #   add_authenticator(mechanism, authenticator_class)
+    #   add_authenticator(mechanism, authenticator_proc)
+    #
+    # Registers an authenticator for #authenticator to use.  +mechanism+ is the
+    # name of the
+    # {SASL mechanism}[https://www.iana.org/assignments/sasl-mechanisms/sasl-mechanisms.xhtml]
+    # implemented by +authenticator_class+ (for instance, <tt>"PLAIN"</tt>).
+    #
+    # If +mechanism+ refers to an existing authenticator, a warning will be
+    # printed and the old authenticator will be replaced.
+    #
+    # When only a single argument is given, the authenticator class will be
+    # lazily loaded from <tt>Net::IMAP::SASL::#{name}Authenticator</tt> (case is
+    # preserved and non-alphanumeric characters are removed..
+    def add_authenticator(name, authenticator = nil)
+      key = name.upcase.to_sym
+      authenticator ||= begin
+        class_name = "#{name.gsub(/[^a-zA-Z0-9]/, "")}Authenticator".to_sym
+        auth_class = nil
+        ->(*creds, **props, &block) {
+          auth_class ||= Net::IMAP::SASL.const_get(class_name)
+          auth_class.new(*creds, **props, &block)
+        }
+      end
+      @authenticators[key] = authenticator
+    end
+
+    # Removes the authenticator registered for +name+
+    def remove_authenticator(name)
+      key = name.upcase.to_sym
+      @authenticators.delete(key)
+    end
+
+    # :call-seq:
+    #   authenticator(mechanism, ...) -> auth_session
+    #
+    # Builds an authenticator instance using the authenticator registered to
+    # +mechanism+.  The returned object represents a single authentication
+    # exchange and <em>must not</em> be reused for multiple authentication
+    # attempts.
+    #
+    # All arguments (except +mechanism+) are forwarded to the registered
+    # authenticator's +#new+ or +#call+ method.  Each authenticator must
+    # document its own arguments.
+    #
+    # [Note]
+    #   This method is intended for internal use by connection protocol code
+    #   only.  Protocol client users should see refer to their client's
+    #   documentation, e.g. Net::IMAP#authenticate.
+    def authenticator(mechanism, ...)
+      auth = @authenticators.fetch(mechanism.upcase.to_sym) do
+        raise ArgumentError, 'unknown auth type - "%s"' % mechanism
+      end
+      auth.respond_to?(:new) ? auth.new(...) : auth.call(...)
+    end
+    alias new authenticator
+
+  end
+
+end

data/lib/net/imap/{authenticators/cram_md5.rb → sasl/cram_md5_authenticator.rb}

@@ -13,14 +13,7 @@
 # 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
-
+class Net::IMAP::SASL::CramMD5Authenticator
   def initialize(user, password, warn_deprecation: true, **_ignored)
     if warn_deprecation
       warn "WARNING: CRAM-MD5 mechanism is deprecated." # TODO: recommend SCRAM
@@ -28,8 +21,22 @@ class Net::IMAP::CramMD5Authenticator
     require "digest/md5"
     @user = user
     @password = password
+    @done = false
+  end
+
+  def initial_response?; false end
+
+  def process(challenge)
+    digest = hmac_md5(challenge, @password)
+    return @user + " " + digest
+  ensure
+    @done = true
   end
 
+  def done?; @done end
+
+  private
+
   def hmac_md5(text, key)
     if key.length > 64
       key = Digest::MD5.digest(key)
@@ -47,5 +54,4 @@ class Net::IMAP::CramMD5Authenticator
     return Digest::MD5.hexdigest(k_opad + digest)
   end
 
-  Net::IMAP.add_authenticator "CRAM-MD5", self
 end

data/lib/net/imap/{authenticators/digest_md5.rb → sasl/digest_md5_authenticator.rb}

@@ -1,14 +1,81 @@
 # frozen_string_literal: true
 
 # Net::IMAP authenticator for the "`DIGEST-MD5`" SASL mechanism type, specified
-# in RFC2831(https://tools.ietf.org/html/rfc2831).  See Net::IMAP#authenticate.
+# in RFC-2831[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
+# RFC-6331[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
+class Net::IMAP::SASL::DigestMD5Authenticator
+  STAGE_ONE = :stage_one
+  STAGE_TWO = :stage_two
+  STAGE_DONE = :stage_done
+  private_constant :STAGE_ONE, :STAGE_TWO, :STAGE_DONE
+
+  # Authentication identity: the identity that matches the #password.
+  #
+  # RFC-2831[https://tools.ietf.org/html/rfc2831] uses the term +username+.
+  # "Authentication identity" is the generic term used by
+  # RFC-4422[https://tools.ietf.org/html/rfc4422].
+  # RFC-4616[https://tools.ietf.org/html/rfc4616] and many later RFCs abbreviate
+  # that to +authcid+.  So +authcid+ is available as an alias for #username.
+  attr_reader :username
+
+  # A password or passphrase that matches the #username.
+  #
+  # The +password+ will be used to create the response digest.
+  attr_reader :password
+
+  # Authorization identity: an identity to act as or on behalf of.  The identity
+  # form is application protocol specific.  If not provided or left blank, the
+  # server derives an authorization identity from the authentication identity.
+  # The server is responsible for verifying the client's credentials and
+  # verifying that the identity it associates with the client's authentication
+  # identity is allowed to act as (or on behalf of) the authorization identity.
+  #
+  # For example, an administrator or superuser might take on another role:
+  #
+  #     imap.authenticate "DIGEST-MD5", "root", ->{passwd}, authzid: "user"
+  #
+  attr_reader :authzid
+
+  # :call-seq:
+  #   new(username,  password,  authzid = nil, **options) -> authenticator
+  #   new(username:, password:, authzid:  nil, **options) -> authenticator
+  #
+  # Creates an Authenticator for the "+DIGEST-MD5+" SASL mechanism.
+  #
+  # Called by Net::IMAP#authenticate and similar methods on other clients.
+  #
+  # ==== Parameters
+  #
+  # * #username — Identity whose #password is used.
+  # * #password — A password or passphrase associated with this #username.
+  # * #authzid ― Alternate identity to act as or on behalf of.  Optional.
+  # * +warn_deprecation+ — Set to +false+ to silence the warning.
+  #
+  # See the documentation for each attribute for more details.
+  def initialize(user = nil, pass = nil, authz = nil,
+                 username: nil, password: nil, authzid: nil,
+                 warn_deprecation: true, **)
+    username ||= user or raise ArgumentError, "missing username"
+    password ||= pass or raise ArgumentError, "missing password"
+    authzid  ||= authz
+    if warn_deprecation
+      warn "WARNING: DIGEST-MD5 SASL mechanism was deprecated by RFC6331."
+      # TODO: recommend SCRAM instead.
+    end
+    require "digest/md5"
+    require "strscan"
+    @username, @password, @authzid = username, password, authzid
+    @nc, @stage = {}, STAGE_ONE
+  end
+
+  def initial_response?; false end
+
+  # Responds to server challenge in two stages.
   def process(challenge)
     case @stage
     when STAGE_ONE
@@ -31,7 +98,7 @@ class Net::IMAP::DigestMD5Authenticator
 
       response = {
         :nonce => sparams['nonce'],
-        :username => @user,
+        :username => @username,
         :realm => sparams['realm'],
         :cnonce => Digest::MD5.hexdigest("%.15f:%.15f:%d" % [Time.now.to_f, rand, Process.pid.to_s]),
         :'digest-uri' => 'imap/' + sparams['realm'],
@@ -41,7 +108,7 @@ class Net::IMAP::DigestMD5Authenticator
         :charset => sparams['charset'],
       }
 
-      response[:authzid] = @authname unless @authname.nil?
+      response[:authzid] = @authzid unless @authzid.nil?
 
       # now, the real thing
       a0 = Digest::MD5.digest( [ response.values_at(:username, :realm), @password ].join(':') )
@@ -62,7 +129,7 @@ class Net::IMAP::DigestMD5Authenticator
 
       return response.keys.map {|key| qdval(key.to_s, response[key]) }.join(',')
     when STAGE_TWO
-      @stage = nil
+      @stage = STAGE_DONE
       # if at the second stage, return an empty string
       if challenge =~ /rspauth=/
         return ''
@@ -74,23 +141,10 @@ class Net::IMAP::DigestMD5Authenticator
     end
   end
 
-  def initialize(user, password, authname = nil, warn_deprecation: true)
-    if warn_deprecation
-      warn "WARNING: DIGEST-MD5 SASL mechanism was deprecated by RFC6331."
-      # TODO: recommend SCRAM instead.
-    end
-    require "digest/md5"
-    require "strscan"
-    @user, @password, @authname = user, password, authname
-    @nc, @stage = {}, STAGE_ONE
-  end
-
+  def done?; @stage == STAGE_DONE end
 
   private
 
-  STAGE_ONE = :stage_one
-  STAGE_TWO = :stage_two
-
   def nc(nonce)
     if @nc.has_key? nonce
       @nc[nonce] = @nc[nonce] + 1
@@ -111,5 +165,4 @@ class Net::IMAP::DigestMD5Authenticator
     end
   end
 
-  Net::IMAP.add_authenticator "DIGEST-MD5", self
 end

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP < Protocol
+    module SASL
+
+      # Authenticator for the "+EXTERNAL+" SASL mechanism, as specified by
+      # RFC-4422[https://tools.ietf.org/html/rfc4422].  See
+      # Net::IMAP#authenticate.
+      #
+      # The EXTERNAL mechanism requests that the server use client credentials
+      # established external to SASL, for example by TLS certificate or IPsec.
+      class ExternalAuthenticator
+
+        # Authorization identity: an identity to act as or on behalf of.
+        #
+        # If not explicitly provided, the server defaults to using the identity
+        # that was authenticated by the external credentials.
+        attr_reader :authzid
+
+        # :call-seq:
+        #   new(authzid: nil, **) -> authenticator
+        #
+        # Creates an Authenticator for the "+EXTERNAL+" SASL mechanism, as
+        # specified in RFC-4422[https://tools.ietf.org/html/rfc4422].  To use
+        # this, see Net::IMAP#authenticate or your client's authentication
+        # method.
+        #
+        # #authzid is an optional identity to act as or on behalf of.
+        #
+        # Any other keyword parameters are quietly ignored.
+        def initialize(authzid: nil, **)
+          @authzid = authzid&.to_str&.encode "UTF-8"
+          if @authzid&.match?(/\u0000/u) # also validates UTF8 encoding
+            raise ArgumentError, "contains NULL"
+          end
+          @done = false
+        end
+
+        # :call-seq:
+        #   initial_response? -> true
+        #
+        # +EXTERNAL+ can send an initial client response.
+        def initial_response?; true end
+
+        # Returns #authzid, or an empty string if there is no authzid.
+        def process(_)
+          authzid || ""
+        ensure
+          @done = true
+        end
+
+        # Returns true when the initial client response was sent.
+        #
+        # The authentication should not succeed unless this returns true, but it
+        # does *not* indicate success.
+        def done?; @done end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP < Protocol
+    module SASL
+
+      # Originally defined for the GS2 mechanism family in
+      # RFC5801[https://tools.ietf.org/html/rfc5801],
+      # several different mechanisms start with a GS2 header:
+      # * +GS2-*+       --- RFC5801[https://tools.ietf.org/html/rfc5801]
+      # * +SCRAM-*+     --- RFC5802[https://tools.ietf.org/html/rfc5802]
+      #   (ScramAuthenticator)
+      # * +SAML20+      --- RFC6595[https://tools.ietf.org/html/rfc6595]
+      # * +OPENID20+    --- RFC6616[https://tools.ietf.org/html/rfc6616]
+      # * +OAUTH10A+    --- RFC7628[https://tools.ietf.org/html/rfc7628]
+      # * +OAUTHBEARER+ --- RFC7628[https://tools.ietf.org/html/rfc7628]
+      #   (OAuthBearerAuthenticator)
+      #
+      # Classes that include this module must implement +#authzid+.
+      module GS2Header
+        NO_NULL_CHARS = /\A[^\x00]+\z/u.freeze # :nodoc:
+
+        ##
+        # Matches {RFC5801 §4}[https://www.rfc-editor.org/rfc/rfc5801#section-4]
+        # +saslname+.  The output from gs2_saslname_encode matches this Regexp.
+        RFC5801_SASLNAME = /\A(?:[^,=\x00]|=2C|=3D)+\z/u.freeze
+
+        # The {RFC5801 §4}[https://www.rfc-editor.org/rfc/rfc5801#section-4]
+        # +gs2-header+, which prefixes the #initial_client_response.
+        #
+        # >>>
+        #   <em>Note: the actual GS2 header includes an optional flag to
+        #   indicate that the GSS mechanism is not "standard", but since all of
+        #   the SASL mechanisms using GS2 are "standard", we don't include that
+        #   flag.  A class for a nonstandard GSSAPI mechanism should prefix with
+        #   "+F,+".</em>
+        def gs2_header
+          "#{gs2_cb_flag},#{gs2_authzid},"
+        end
+
+        # The {RFC5801 §4}[https://www.rfc-editor.org/rfc/rfc5801#section-4]
+        # +gs2-cb-flag+:
+        #
+        # "+n+":: The client doesn't support channel binding.
+        # "+y+":: The client does support channel binding
+        #         but thinks the server does not.
+        # "+p+":: The client requires channel binding.
+        #         The selected channel binding follows "+p=+".
+        #
+        # The default always returns "+n+".  A mechanism that supports channel
+        # binding must override this method.
+        #
+        def gs2_cb_flag; "n" end
+
+        # The {RFC5801 §4}[https://www.rfc-editor.org/rfc/rfc5801#section-4]
+        # +gs2-authzid+ header, when +#authzid+ is not empty.
+        #
+        # If +#authzid+ is empty or +nil+, an empty string is returned.
+        def gs2_authzid
+          return "" if authzid.nil? || authzid == ""
+          "a=#{gs2_saslname_encode(authzid)}"
+        end
+
+        module_function
+
+        # Encodes +str+ to match RFC5801_SASLNAME.
+        def gs2_saslname_encode(str)
+          str = str.encode("UTF-8")
+          # Regexp#match raises "invalid byte sequence" for invalid UTF-8
+          NO_NULL_CHARS.match str or
+            raise ArgumentError, "invalid saslname: %p" % [str]
+          str
+            .gsub(?=, "=3D")
+            .gsub(?,, "=2C")
+        end
+
+      end
+    end
+  end
+end

data/lib/net/imap/{authenticators/login.rb → sasl/login_authenticator.rb}

@@ -17,21 +17,11 @@
 # 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
-
+class Net::IMAP::SASL::LoginAuthenticator
   STATE_USER = :USER
   STATE_PASSWORD = :PASSWORD
+  STATE_DONE = :DONE
+  private_constant :STATE_USER, :STATE_PASSWORD, :STATE_DONE
 
   def initialize(user, password, warn_deprecation: true, **_ignored)
     if warn_deprecation
@@ -42,5 +32,20 @@ class Net::IMAP::LoginAuthenticator
     @state = STATE_USER
   end
 
-  Net::IMAP.add_authenticator "LOGIN", self
+  def initial_response?; false end
+
+  def process(data)
+    case @state
+    when STATE_USER
+      @state = STATE_PASSWORD
+      return @user
+    when STATE_PASSWORD
+      @state = STATE_DONE
+      return @password
+    when STATE_DONE
+      raise ResponseParseError, data
+    end
+  end
+
+  def done?; @state == STATE_DONE end
 end