net-imap 0.3.7 → 0.4.7

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,30 +17,39 @@
 # 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
+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 = nil, pass = nil,
+                 authcid: nil, username: nil,
+                 password: nil, secret: nil,
+                 warn_deprecation: true,
+                 **)
+    if warn_deprecation
+      warn "WARNING: LOGIN SASL mechanism is deprecated. Use PLAIN instead."
+    end
+    @user = authcid || username || user
+    @password = password || secret || pass
+    @state = STATE_USER
+  end
+
+  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
 
-  private
-
-  STATE_USER = :USER
-  STATE_PASSWORD = :PASSWORD
-
-  def initialize(user, password, warn_deprecation: true, **_ignored)
-    if warn_deprecation
-      warn "WARNING: LOGIN SASL mechanism is deprecated. Use PLAIN instead."
-    end
-    @user = user
-    @password = password
-    @state = STATE_USER
-  end
-
-  Net::IMAP.add_authenticator "LOGIN", self
+  def done?; @state == STATE_DONE end
 end

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

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require_relative "gs2_header"
+
+module Net
+  class IMAP < Protocol
+    module SASL
+
+      # Abstract base class for the SASL mechanisms defined in
+      # RFC7628[https://tools.ietf.org/html/rfc7628]:
+      # * OAUTHBEARER[rdoc-ref:OAuthBearerAuthenticator]
+      #   (OAuthBearerAuthenticator)
+      # * OAUTH10A
+      class OAuthAuthenticator
+        include GS2Header
+
+        # 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 "PLAIN", "root", passwd, authzid: "user"
+        #
+        attr_reader :authzid
+        alias username authzid
+
+        # Hostname to which the client connected.  (optional)
+        attr_reader :host
+
+        # Service port to which the client connected.  (optional)
+        attr_reader :port
+
+        # HTTP method.  (optional)
+        attr_reader :mthd
+
+        # HTTP path data.  (optional)
+        attr_reader :path
+
+        # HTTP post data.  (optional)
+        attr_reader :post
+
+        # The query string.  (optional)
+        attr_reader :qs
+        alias query qs
+
+        # Stores the most recent server "challenge".  When authentication fails,
+        # this may hold information about the failure reason, as JSON.
+        attr_reader :last_server_response
+
+        # Creates an RFC7628[https://tools.ietf.org/html/rfc7628] OAuth
+        # authenticator.
+        #
+        # ==== Parameters
+        #
+        # See child classes for required parameter(s).  The following parameters
+        # are all optional, but it is worth noting that <b>application protocols
+        # are allowed to require</b> #authzid (or other parameters, such as
+        # #host or #port) <b>as are specific server implementations</b>.
+        #
+        # * _optional_ #authzid  ― Authorization identity to act as or on behalf of.
+        #
+        #   _optional_ #username — An alias for #authzid.
+        #
+        #   Note that, unlike some other authenticators, +username+ sets the
+        #   _authorization_ identity and not the _authentication_ identity.  The
+        #   authentication identity is established for the client by the OAuth
+        #   token.
+        #
+        # * _optional_ #host — Hostname to which the client connected.
+        # * _optional_ #port — Service port to which the client connected.
+        # * _optional_ #mthd — HTTP method
+        # * _optional_ #path — HTTP path data
+        # * _optional_ #post — HTTP post data
+        # * _optional_ #qs   — HTTP query string
+        #
+        #   _optional_ #query — An alias for #qs
+        #
+        # Any other keyword parameters are quietly ignored.
+        def initialize(authzid: nil, host: nil, port: nil,
+                       username: nil, query: nil,
+                       mthd: nil, path: nil, post: nil, qs: nil, **)
+          @authzid = authzid || username
+          @host    = host
+          @port    = port
+          @mthd    = mthd
+          @path    = path
+          @post    = post
+          @qs      = qs || query
+          @done    = false
+        end
+
+        # The {RFC7628 §3.1}[https://www.rfc-editor.org/rfc/rfc7628#section-3.1]
+        # formatted response.
+        def initial_client_response
+          kv_pairs = {
+            host: host, port: port, mthd: mthd, path: path, post: post, qs: qs,
+            auth: authorization, # authorization is implemented by subclasses
+          }.compact
+          [gs2_header, *kv_pairs.map {|kv| kv.join("=") }, "\1"].join("\1")
+        end
+
+        # Returns initial_client_response the first time, then "<tt>^A</tt>".
+        def process(data)
+          @last_server_response = data
+          done? ? "\1" : initial_client_response
+        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
+
+        # Value of the HTTP Authorization header
+        #
+        # <b>Implemented by subclasses.</b>
+        def authorization; raise "must be implemented by subclass" end
+
+      end
+
+      # Authenticator for the "+OAUTHBEARER+" SASL mechanism, specified in
+      # RFC7628[https://tools.ietf.org/html/rfc7628].  Authenticates using OAuth
+      # 2.0 bearer tokens, as described in
+      # RFC6750[https://tools.ietf.org/html/rfc6750].  Use via
+      # Net::IMAP#authenticate.
+      #
+      # RFC6750[https://tools.ietf.org/html/rfc6750] requires Transport Layer
+      # Security (TLS) to secure the protocol interaction between the client and
+      # the resource server.  TLS _MUST_ be used for +OAUTHBEARER+ to protect
+      # the bearer token.
+      class OAuthBearerAuthenticator < OAuthAuthenticator
+
+        # An OAuth 2.0 bearer token.  See {RFC-6750}[https://www.rfc-editor.org/rfc/rfc6750]
+        attr_reader :oauth2_token
+        alias secret oauth2_token
+
+        # :call-seq:
+        #   new(oauth2_token,          **options) -> authenticator
+        #   new(authzid, oauth2_token, **options) -> authenticator
+        #   new(oauth2_token:,         **options) -> authenticator
+        #
+        # Creates an Authenticator for the "+OAUTHBEARER+" SASL mechanism.
+        #
+        # Called by Net::IMAP#authenticate and similar methods on other clients.
+        #
+        # ==== Parameters
+        #
+        # * #oauth2_token — An OAuth2 bearer token
+        #
+        # All other keyword parameters are passed to
+        # {super}[rdoc-ref:OAuthAuthenticator::new] (see OAuthAuthenticator).
+        # The most common ones are:
+        #
+        # * _optional_ #authzid  ― Authorization identity to act as or on behalf of.
+        #
+        #   _optional_ #username — An alias for #authzid.
+        #
+        #   Note that, unlike some other authenticators, +username+ sets the
+        #   _authorization_ identity and not the _authentication_ identity.  The
+        #   authentication identity is established for the client by
+        #   #oauth2_token.
+        #
+        # * _optional_ #host — Hostname to which the client connected.
+        # * _optional_ #port — Service port to which the client connected.
+        #
+        # Although only oauth2_token is required by this mechanism, it is worth
+        # noting that <b><em>application protocols are allowed to
+        # require</em></b> #authzid (<em>or other parameters, such as</em> #host
+        # _or_ #port) <b><em>as are specific server implementations</em></b>.
+        def initialize(arg1 = nil, arg2 = nil,
+                       oauth2_token: nil, secret: nil,
+                       **args, &blk)
+          username, oauth2_token_arg = arg2.nil? ? [nil, arg1] : [arg1, arg2]
+          super(username: username, **args, &blk)
+          @oauth2_token = oauth2_token || secret || oauth2_token_arg or
+            raise ArgumentError, "missing oauth2_token"
+        end
+
+        # :call-seq:
+        #   initial_response? -> true
+        #
+        # +OAUTHBEARER+ sends an initial client response.
+        def initial_response?; true end
+
+        # Value of the HTTP Authorization header
+        def authorization; "Bearer #{oauth2_token}" end
+
+      end
+    end
+
+  end
+end

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

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+# Authenticator for the "+PLAIN+" SASL mechanism, specified in
+# RFC-4616[https://tools.ietf.org/html/rfc4616].  See Net::IMAP#authenticate.
+#
+# +PLAIN+ authentication sends the password in cleartext.
+# RFC-3501[https://tools.ietf.org/html/rfc3501] encourages servers to disable
+# cleartext authentication until after TLS has been negotiated.
+# RFC-8314[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::SASL::PlainAuthenticator
+
+  NULL = -"\0".b
+  private_constant :NULL
+
+  # 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
+  # this to +authcid+.
+  attr_reader :username
+  alias authcid username
+
+  # A password or passphrase that matches the #username.
+  attr_reader :password
+  alias secret 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 "PLAIN", "root", passwd, authzid: "user"
+  #
+  attr_reader :authzid
+
+  # :call-seq:
+  #   new(username,  password,  authzid: nil, **) -> authenticator
+  #   new(username:, password:, authzid: nil, **) -> authenticator
+  #   new(authcid:,  password:, authzid: nil, **) -> authenticator
+  #
+  # Creates an Authenticator for the "+PLAIN+" SASL mechanism.
+  #
+  # Called by Net::IMAP#authenticate and similar methods on other clients.
+  #
+  # ==== Parameters
+  #
+  # * #authcid ― Authentication identity that is associated with #password.
+  #
+  #   #username ― An alias for #authcid.
+  #
+  # * #password ― A password or passphrase associated with the #authcid.
+  #
+  # * _optional_ #authzid  ― Authorization identity to act as or on behalf of.
+  #
+  #   When +authzid+ is not set, the server should derive the authorization
+  #   identity from the authentication identity.
+  #
+  # Any other keyword parameters are quietly ignored.
+  def initialize(user = nil, pass = nil,
+                 authcid: nil, secret: nil,
+                 username: nil, password: nil, authzid: nil, **)
+    username ||= authcid || user or
+      raise ArgumentError, "missing username (authcid)"
+    password ||= secret || pass or raise ArgumentError, "missing password"
+    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
+    @done = false
+  end
+
+  # :call-seq:
+  #   initial_response? -> true
+  #
+  # +PLAIN+ can send an initial client response.
+  def initial_response?; true end
+
+  # Responds with the client's credentials.
+  def process(data)
+    return "#@authzid\0#@username\0#@password"
+  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

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP
+    module SASL
+
+      module ProtocolAdapters
+        # This API is experimental, and may change.
+        module Generic
+          def command_name;     "AUTHENTICATE" end
+          def service;          raise "Implement in subclass or module" end
+          def host;             client.host end
+          def port;             client.port end
+          def encode_ir(string) string.empty? ? "=" : encode(string) end
+          def encode(string)    [string].pack("m0") end
+          def decode(string)    string.unpack1("m0") end
+          def cancel_response;  "*" end
+        end
+
+        # See RFC-3501 (IMAP4rev1), RFC-4959 (SASL-IR capability),
+        # and RFC-9051 (IMAP4rev2).
+        module IMAP
+          include Generic
+          def service; "imap" end
+        end
+
+        # See RFC-4954 (AUTH capability).
+        module SMTP
+          include Generic
+          def command_name; "AUTH" end
+          def service; "smtp" end
+        end
+
+        # See RFC-5034 (SASL capability).
+        module POP
+          include Generic
+          def command_name; "AUTH" end
+          def service; "pop" end
+        end
+
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP
+    module SASL
+
+      # For method descriptions,
+      # see {RFC5802 §2.2}[https://www.rfc-editor.org/rfc/rfc5802#section-2.2]
+      # and {RFC5802 §3}[https://www.rfc-editor.org/rfc/rfc5802#section-3].
+      module ScramAlgorithm
+        def Normalize(str) SASL.saslprep(str) end
+
+        def Hi(str, salt, iterations)
+          length = digest.digest_length
+          OpenSSL::KDF.pbkdf2_hmac(
+            str,
+            salt:       salt,
+            iterations: iterations,
+            length: length,
+            hash: digest,
+          )
+        end
+
+        def H(str) digest.digest str end
+
+        def HMAC(key, data) OpenSSL::HMAC.digest(digest, key, data) end
+
+        def XOR(str1, str2)
+          str1.unpack("C*")
+            .zip(str2.unpack("C*"))
+            .map {|a, b| a ^ b }
+            .pack("C*")
+        end
+
+        def auth_message
+          [
+            client_first_message_bare,
+            server_first_message,
+            client_final_message_without_proof,
+          ]
+            .join(",")
+        end
+
+        def salted_password
+          Hi(Normalize(password), salt, iterations)
+        end
+
+        def client_key;       HMAC(salted_password, "Client Key") end
+        def server_key;       HMAC(salted_password, "Server Key") end
+        def stored_key;       H(client_key)                       end
+        def client_signature; HMAC(stored_key, auth_message)      end
+        def server_signature; HMAC(server_key, auth_message)      end
+        def client_proof;     XOR(client_key, client_signature)   end
+      end
+
+    end
+  end
+end