net-imap 0.4.17 → 0.5.6

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

@@ -1,16 +1,16 @@
 # frozen_string_literal: true
 
 # Authenticator for the "+CRAM-MD5+" SASL mechanism, specified in
-# RFC2195[https://tools.ietf.org/html/rfc2195].  See Net::IMAP#authenticate.
+# RFC2195[https://www.rfc-editor.org/rfc/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]
+# {draft-ietf-sasl-crammd5-to-historic}[https://www.rfc-editor.org/rfc/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
+# Additionally, RFC8314[https://www.rfc-editor.org/rfc/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::SASL::CramMD5Authenticator
@@ -20,7 +20,7 @@ class Net::IMAP::SASL::CramMD5Authenticator
                  warn_deprecation: true,
                  **)
     if warn_deprecation
-      warn "WARNING: CRAM-MD5 mechanism is deprecated." # TODO: recommend SCRAM
+      warn "WARNING: CRAM-MD5 mechanism is deprecated.", category: :deprecated
     end
     require "digest/md5"
     @user = authcid || username || user

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

@@ -1,25 +1,46 @@
 # frozen_string_literal: true
 
-# Net::IMAP authenticator for the "`DIGEST-MD5`" SASL mechanism type, specified
-# in RFC-2831[https://tools.ietf.org/html/rfc2831].  See Net::IMAP#authenticate.
+# Net::IMAP authenticator for the +DIGEST-MD5+ SASL mechanism type, specified
+# in RFC-2831[https://www.rfc-editor.org/rfc/rfc2831].  See Net::IMAP#authenticate.
 #
 # == Deprecated
 #
 # "+DIGEST-MD5+" has been deprecated by
-# RFC-6331[https://tools.ietf.org/html/rfc6331] and should not be relied on for
+# RFC-6331[https://www.rfc-editor.org/rfc/rfc6331] and should not be relied on for
 # security.  It is included for compatibility with existing servers.
 class Net::IMAP::SASL::DigestMD5Authenticator
+  DataFormatError    = Net::IMAP::DataFormatError
+  ResponseParseError = Net::IMAP::ResponseParseError
+  private_constant :DataFormatError, :ResponseParseError
+
   STAGE_ONE = :stage_one
   STAGE_TWO = :stage_two
   STAGE_DONE = :stage_done
   private_constant :STAGE_ONE, :STAGE_TWO, :STAGE_DONE
 
+  # Directives which must not have multiples.  The RFC states:
+  # >>>
+  #   This directive may appear at most once; if multiple instances are present,
+  #   the client should abort the authentication exchange.
+  NO_MULTIPLES = %w[nonce stale maxbuf charset algorithm].freeze
+
+  # Required directives which must occur exactly once.  The RFC states: >>>
+  #   This directive is required and MUST appear exactly once; if not present,
+  #   or if multiple instances are present, the client should abort the
+  #   authentication exchange.
+  REQUIRED = %w[nonce algorithm].freeze
+
+  # Directives which are composed of one or more comma delimited tokens
+  QUOTED_LISTABLE = %w[qop cipher].freeze
+
+  private_constant :NO_MULTIPLES, :REQUIRED, :QUOTED_LISTABLE
+
   # Authentication identity: the identity that matches the #password.
   #
-  # RFC-2831[https://tools.ietf.org/html/rfc2831] uses the term +username+.
+  # RFC-2831[https://www.rfc-editor.org/rfc/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
+  # RFC-4422[https://www.rfc-editor.org/rfc/rfc4422].
+  # RFC-4616[https://www.rfc-editor.org/rfc/rfc4616] and many later RFCs abbreviate
   # this to +authcid+.
   attr_reader :username
   alias authcid username
@@ -42,6 +63,59 @@ class Net::IMAP::SASL::DigestMD5Authenticator
   #
   attr_reader :authzid
 
+  # A namespace or collection of identities which contains +username+.
+  #
+  # Used by DIGEST-MD5, GSS-API, and NTLM.  This is often a domain name that
+  # contains the name of the host performing the authentication.
+  #
+  # <em>Defaults to the last realm in the server-provided list of
+  # realms.</em>
+  attr_reader :realm
+
+  # Fully qualified canonical DNS host name for the requested service.
+  #
+  # <em>Defaults to #realm.</em>
+  attr_reader :host
+
+  # The service protocol, a
+  # {registered GSSAPI service name}[https://www.iana.org/assignments/gssapi-service-names/gssapi-service-names.xhtml],
+  # e.g. "imap", "ldap", or "xmpp".
+  #
+  # For Net::IMAP, the default is "imap" and should not be overridden.  This
+  # must be set appropriately to use authenticators in other protocols.
+  #
+  # If an IANA-registered name isn't available, GSS-API
+  # (RFC-2743[https://www.rfc-editor.org/rfc/rfc2743]) allows the generic name
+  # "host".
+  attr_reader :service
+
+  # The generic server name when the server is replicated.
+  #
+  # +service_name+ will be ignored when it is +nil+ or identical to +host+.
+  #
+  # From RFC-2831[https://www.rfc-editor.org/rfc/rfc2831]:
+  # >>>
+  #     The service is considered to be replicated if the client's
+  #     service-location process involves resolution using standard DNS lookup
+  #     operations, and if these operations involve DNS records (such as SRV, or
+  #     MX) which resolve one DNS name into a set of other DNS names.  In this
+  #     case, the initial name used by the client is the "serv-name", and the
+  #     final name is the "host" component.
+  attr_reader :service_name
+
+  # Parameters sent by the server are stored in this hash.
+  attr_reader :sparams
+
+  # The charset sent by the server.  "UTF-8" (case insensitive) is the only
+  # allowed value.  +nil+ should be interpreted as ISO 8859-1.
+  attr_reader :charset
+
+  # nonce sent by the server
+  attr_reader :nonce
+
+  # qop-options sent by the server
+  attr_reader :qop
+
   # :call-seq:
   #   new(username,  password,  authzid = nil, **options) -> authenticator
   #   new(username:, password:, authzid:  nil, **options) -> authenticator
@@ -64,27 +138,59 @@ class Net::IMAP::SASL::DigestMD5Authenticator
   #   When +authzid+ is not set, the server should derive the authorization
   #   identity from the authentication identity.
   #
+  # * _optional_ #realm — A namespace for the #username, e.g. a domain.
+  #   <em>Defaults to the last realm in the server-provided realms list.</em>
+  # * _optional_ #host — FQDN for requested service.
+  #   <em>Defaults to</em> #realm.
+  # * _optional_ #service_name — The generic host name when the server is
+  #   replicated.
+  # * _optional_ #service — the registered service protocol.  E.g. "imap",
+  #   "smtp", "ldap", "xmpp".
+  #   <em>For Net::IMAP, this defaults to "imap".</em>
+  #
   # * _optional_ +warn_deprecation+ — Set to +false+ to silence the warning.
   #
   # Any other keyword arguments are silently ignored.
   def initialize(user = nil, pass = nil, authz = nil,
                  username: nil, password: nil, authzid: nil,
                  authcid: nil, secret: nil,
+                 realm: nil, service: "imap", host: nil, service_name: nil,
                  warn_deprecation: true, **)
     username = authcid || username || user or
       raise ArgumentError, "missing username (authcid)"
     password ||= secret || 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.
+      warn("WARNING: DIGEST-MD5 SASL mechanism was deprecated by RFC6331.",
+           category: :deprecated)
     end
+
     require "digest/md5"
+    require "securerandom"
     require "strscan"
     @username, @password, @authzid = username, password, authzid
+    @realm        = realm
+    @host         = host
+    @service      = service
+    @service_name = service_name
     @nc, @stage = {}, STAGE_ONE
   end
 
+  # From RFC-2831[https://www.rfc-editor.org/rfc/rfc2831]:
+  # >>>
+  #     Indicates the principal name of the service with which the client wishes
+  #     to connect, formed from the serv-type, host, and serv-name.  For
+  #     example, the FTP service on "ftp.example.com" would have a "digest-uri"
+  #     value of "ftp/ftp.example.com"; the SMTP server from the example above
+  #     would have a "digest-uri" value of "smtp/mail3.example.com/example.com".
+  def digest_uri
+    if service_name && service_name != host
+      "#{service}/#{host}/#{service_name}"
+    else
+      "#{service}/#{host}"
+    end
+  end
+
   def initial_response?; false end
 
   # Responds to server challenge in two stages.
@@ -92,78 +198,134 @@ class Net::IMAP::SASL::DigestMD5Authenticator
     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
+      @sparams = parse_challenge(challenge)
+      @qop     = sparams.key?("qop") ? ["auth"] : sparams["qop"].flatten
+      @nonce   = sparams["nonce"]  &.first
+      @charset = sparams["charset"]&.first
+      @realm ||= sparams["realm"]  &.last
+      @host  ||= realm
 
-      raise Net::IMAP::DataFormatError, "Bad Challenge: '#{challenge}'" unless c.eos? and sparams['qop']
-      raise Net::IMAP::Error, "Server does not support auth (qop = #{sparams['qop'].join(',')})" unless sparams['qop'].include?("auth")
+      if !qop.include?("auth")
+        raise DataFormatError, "Server does not support auth (qop = %p)" % [
+          sparams["qop"]
+        ]
+      elsif (emptykey = REQUIRED.find { sparams[_1].empty? })
+        raise DataFormatError, "Server didn't send %s (%p)" % [emptykey, challenge]
+      elsif (multikey = NO_MULTIPLES.find { sparams[_1].length > 1 })
+        raise DataFormatError, "Server sent multiple %s (%p)" % [multikey, challenge]
+      end
 
       response = {
-        :nonce => sparams['nonce'],
-        :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'],
-        :qop => 'auth',
-        :maxbuf => 65535,
-        :nc => "%08d" % nc(sparams['nonce']),
-        :charset => sparams['charset'],
+        nonce:        nonce,
+        username:     username,
+        realm:        realm,
+        cnonce:       SecureRandom.base64(32),
+        "digest-uri": digest_uri,
+        qop:          "auth",
+        maxbuf:       65535,
+        nc:           "%08d" % nc(nonce),
+        charset:      charset,
       }
 
       response[:authzid] = @authzid unless @authzid.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(',')
+      response[:response] = response_value(response)
+      format_response(response)
     when STAGE_TWO
       @stage = STAGE_DONE
-      # if at the second stage, return an empty string
-      if challenge =~ /rspauth=/
-        return ''
-      else
-        raise ResponseParseError, challenge
-      end
+      raise ResponseParseError, challenge unless challenge =~ /rspauth=/
+      "" # if at the second stage, return an empty string
     else
       raise ResponseParseError, challenge
     end
+  rescue => error
+    @stage = error
+    raise
   end
 
   def done?; @stage == STAGE_DONE end
 
   private
 
+  LWS        = /[\r\n \t]*/n # less strict than RFC, more strict than '\s'
+  TOKEN      = /[^\x00-\x20\x7f()<>@,;:\\"\/\[\]?={}]+/n
+  QUOTED_STR = /"(?: [\t\x20-\x7e&&[^"]] | \\[\x00-\x7f] )*"/nx
+  LIST_DELIM = /(?:#{LWS} , )+ #{LWS}/nx
+  AUTH_PARAM = /
+    (#{TOKEN}) #{LWS} = #{LWS} (#{QUOTED_STR} | #{TOKEN}) #{LIST_DELIM}?
+  /nx
+  private_constant :LWS, :TOKEN, :QUOTED_STR, :LIST_DELIM, :AUTH_PARAM
+
+  def parse_challenge(challenge)
+    sparams = Hash.new {|h, k| h[k] = [] }
+    c = StringScanner.new(challenge)
+    c.skip LIST_DELIM
+    while c.scan AUTH_PARAM
+      k, v = c[1], c[2]
+      k = k.downcase
+      if v =~ /\A"(.*)"\z/mn
+        v = $1.gsub(/\\(.)/mn, '\1')
+        v = split_quoted_list(v, challenge) if QUOTED_LISTABLE.include? k
+      end
+      sparams[k] << v
+    end
+    if !c.eos?
+      raise DataFormatError, "Unparsable challenge: %p" % [challenge]
+    elsif sparams.empty?
+      raise DataFormatError, "Empty challenge: %p" % [challenge]
+    end
+    sparams
+  end
+
+  def split_quoted_list(value, challenge)
+    value.split(LIST_DELIM).reject(&:empty?).tap do
+      _1.any? or raise DataFormatError, "Bad Challenge: %p" % [challenge]
+    end
+  end
+
   def nc(nonce)
     if @nc.has_key? nonce
       @nc[nonce] = @nc[nonce] + 1
     else
       @nc[nonce] = 1
     end
-    return @nc[nonce]
+  end
+
+  def response_value(response)
+    a1 = compute_a1(response)
+    a2 = compute_a2(response)
+    Digest::MD5.hexdigest(
+      [
+        Digest::MD5.hexdigest(a1),
+        response.values_at(:nonce, :nc, :cnonce, :qop),
+        Digest::MD5.hexdigest(a2)
+      ].join(":")
+    )
+  end
+
+  def compute_a0(response)
+    Digest::MD5.digest(
+      [ response.values_at(:username, :realm), password ].join(":")
+    )
+  end
+
+  def compute_a1(response)
+    a0 = compute_a0(response)
+    a1 = [ a0, response.values_at(:nonce, :cnonce) ].join(":")
+    a1 << ":#{response[:authzid]}" unless response[:authzid].nil?
+    a1
+  end
+
+  def compute_a2(response)
+    a2 = "AUTHENTICATE:#{response[:"digest-uri"]}"
+    if response[:qop] and response[:qop] =~ /^auth-(?:conf|int)$/
+      a2 << ":00000000000000000000000000000000"
+    end
+    a2
+  end
+
+  def format_response(response)
+    response.map {|k, v| qdval(k.to_s, v) }.join(",")
   end
 
   # some responses need quoting

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

@@ -5,7 +5,7 @@ module Net
     module SASL
 
       # Authenticator for the "+EXTERNAL+" SASL mechanism, as specified by
-      # RFC-4422[https://tools.ietf.org/html/rfc4422].  See
+      # RFC-4422[https://www.rfc-editor.org/rfc/rfc4422].  See
       # Net::IMAP#authenticate.
       #
       # The EXTERNAL mechanism requests that the server use client credentials
@@ -33,7 +33,7 @@ module Net
         #   new(username = nil, **) -> authenticator
         #
         # Creates an Authenticator for the "+EXTERNAL+" SASL mechanism, as
-        # specified in RFC-4422[https://tools.ietf.org/html/rfc4422].  To use
+        # specified in RFC-4422[https://www.rfc-editor.org/rfc/rfc4422].  To use
         # this, see Net::IMAP#authenticate or your client's authentication
         # method.
         #

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

@@ -5,15 +5,15 @@ module Net
     module SASL
 
       # Originally defined for the GS2 mechanism family in
-      # RFC5801[https://tools.ietf.org/html/rfc5801],
+      # RFC5801[https://www.rfc-editor.org/rfc/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]
+      # * +GS2-*+       --- RFC5801[https://www.rfc-editor.org/rfc/rfc5801]
+      # * +SCRAM-*+     --- RFC5802[https://www.rfc-editor.org/rfc/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]
+      # * +SAML20+      --- RFC6595[https://www.rfc-editor.org/rfc/rfc6595]
+      # * +OPENID20+    --- RFC6616[https://www.rfc-editor.org/rfc/rfc6616]
+      # * +OAUTH10A+    --- RFC7628[https://www.rfc-editor.org/rfc/rfc7628]
+      # * +OAUTHBEARER+ --- RFC7628[https://www.rfc-editor.org/rfc/rfc7628]
       #   (OAuthBearerAuthenticator)
       #
       # Classes that include this module must implement +#authzid+.

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

@@ -3,9 +3,9 @@
 # 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
+# RFC3501[https://www.rfc-editor.org/rfc/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
+# RFC8314[https://www.rfc-editor.org/rfc/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.
 #
@@ -29,7 +29,8 @@ class Net::IMAP::SASL::LoginAuthenticator
                  warn_deprecation: true,
                  **)
     if warn_deprecation
-      warn "WARNING: LOGIN SASL mechanism is deprecated. Use PLAIN instead."
+      warn "WARNING: LOGIN SASL mechanism is deprecated. Use PLAIN instead.",
+           category: :deprecated
     end
     @user = authcid || username || user
     @password = password || secret || pass

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

@@ -7,7 +7,7 @@ module Net
     module SASL
 
       # Abstract base class for the SASL mechanisms defined in
-      # RFC7628[https://tools.ietf.org/html/rfc7628]:
+      # RFC7628[https://www.rfc-editor.org/rfc/rfc7628]:
       # * OAUTHBEARER[rdoc-ref:OAuthBearerAuthenticator]
       #   (OAuthBearerAuthenticator)
       # * OAUTH10A
@@ -52,7 +52,7 @@ module Net
         # 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
+        # Creates an RFC7628[https://www.rfc-editor.org/rfc/rfc7628] OAuth
         # authenticator.
         #
         # ==== Parameters
@@ -126,12 +126,12 @@ module Net
       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
+      # RFC7628[https://www.rfc-editor.org/rfc/rfc7628].  Authenticates using
+      # OAuth 2.0 bearer tokens, as described in
+      # RFC6750[https://www.rfc-editor.org/rfc/rfc6750].  Use via
       # Net::IMAP#authenticate.
       #
-      # RFC6750[https://tools.ietf.org/html/rfc6750] requires Transport Layer
+      # RFC6750[https://www.rfc-editor.org/rfc/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.

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

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
 # Authenticator for the "+PLAIN+" SASL mechanism, specified in
-# RFC-4616[https://tools.ietf.org/html/rfc4616].  See Net::IMAP#authenticate.
+# RFC-4616[https://www.rfc-editor.org/rfc/rfc4616].  See Net::IMAP#authenticate.
 #
 # +PLAIN+ authentication sends the password in cleartext.
-# RFC-3501[https://tools.ietf.org/html/rfc3501] encourages servers to disable
+# RFC-3501[https://www.rfc-editor.org/rfc/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
+# RFC-8314[https://www.rfc-editor.org/rfc/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
@@ -16,11 +16,11 @@ class Net::IMAP::SASL::PlainAuthenticator
 
   # Authentication identity: the identity that matches the #password.
   #
-  # RFC-2831[https://tools.ietf.org/html/rfc2831] uses the term +username+.
+  # RFC-2831[https://www.rfc-editor.org/rfc/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+.
+  # RFC-4422[https://www.rfc-editor.org/rfc/rfc4422].
+  # RFC-4616[https://www.rfc-editor.org/rfc/rfc4616] and many later RFCs
+  # abbreviate this to +authcid+.
   attr_reader :username
   alias authcid username
 

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

@@ -4,16 +4,72 @@ module Net
   class IMAP
     module SASL
 
+      # SASL::ProtocolAdapters modules are meant to be used as mixins for
+      # SASL::ClientAdapter and its subclasses.  Where the client adapter must
+      # be customized for each client library, the protocol adapter mixin
+      # handles \SASL requirements that are part of the protocol specification,
+      # but not specific to any particular client library.  In particular, see
+      # {RFC4422 §4}[https://www.rfc-editor.org/rfc/rfc4422.html#section-4]
+      #
+      # === Interface
+      #
+      # >>>
+      #   NOTE: This API is experimental, and may change.
+      #
+      # - {#command_name}[rdoc-ref:Generic#command_name] -- The name of the
+      #   command used to to initiate an authentication exchange.
+      # - {#service}[rdoc-ref:Generic#service] -- The GSSAPI service name.
+      # - {#encode_ir}[rdoc-ref:Generic#encode_ir]--Encodes an initial response.
+      # - {#decode}[rdoc-ref:Generic#decode] -- Decodes a server challenge.
+      # - {#encode}[rdoc-ref:Generic#encode] -- Encodes a client response.
+      # - {#cancel_response}[rdoc-ref:Generic#cancel_response] -- The encoded
+      #   client response used to cancel an authentication exchange.
+      #
+      # Other protocol requirements of the \SASL authentication exchange are
+      # handled by SASL::ClientAdapter.
+      #
+      # === Included protocol adapters
+      #
+      # - Generic -- a basic implementation of all of the methods listed above.
+      # - IMAP -- An adapter for the IMAP4 protocol.
+      # - SMTP -- An adapter for the \SMTP protocol with the +AUTH+ capability.
+      # - POP  -- An adapter for the POP3  protocol with the +SASL+ capability.
       module ProtocolAdapters
-        # This API is experimental, and may change.
+        # See SASL::ProtocolAdapters@Interface.
         module Generic
+          # The name of the protocol command used to initiate a \SASL
+          # authentication exchange.
+          #
+          # The generic implementation returns <tt>"AUTHENTICATE"</tt>.
           def command_name;     "AUTHENTICATE" end
-          def service;          raise "Implement in subclass or module" end
-          def host;             client.host end
-          def port;             client.port end
+
+          # A service name from the {GSSAPI/Kerberos/SASL Service Names
+          # registry}[https://www.iana.org/assignments/gssapi-service-names/gssapi-service-names.xhtml].
+          #
+          # The generic implementation returns <tt>"host"</tt>, which is the
+          # generic GSSAPI host-based service name.
+          def service;          "host" end
+
+          # Encodes an initial response string.
+          #
+          # The generic implementation returns the result of #encode, or returns
+          # <tt>"="</tt> when +string+ is empty.
           def encode_ir(string) string.empty? ? "=" : encode(string) end
+
+          # Encodes a client response string.
+          #
+          # The generic implementation returns the Base64 encoding of +string+.
           def encode(string)    [string].pack("m0") end
+
+          # Decodes a server challenge string.
+          #
+          # The generic implementation returns the Base64 decoding of +string+.
           def decode(string)    string.unpack1("m0") end
+
+          # Returns the message used by the client to abort an authentication
+          # exchange.
+          #
+          # The generic implementation returns <tt>"*"</tt>.
           def cancel_response;  "*" end
         end
 

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

@@ -11,7 +11,7 @@ module Net
     module SASL
 
       # Abstract base class for the "+SCRAM-*+" family of SASL mechanisms,
-      # defined in RFC5802[https://tools.ietf.org/html/rfc5802].  Use via
+      # defined in RFC5802[https://www.rfc-editor.org/rfc/rfc5802].  Use via
       # Net::IMAP#authenticate.
       #
       # Directly supported:
@@ -99,11 +99,11 @@ module Net
 
         # 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+.
+        # RFC-2831[https://www.rfc-editor.org/rfc/rfc2831] uses the term
+        # +username+.  "Authentication identity" is the generic term used by
+        # RFC-4422[https://www.rfc-editor.org/rfc/rfc4422].
+        # RFC-4616[https://www.rfc-editor.org/rfc/rfc4616] and many later RFCs
+        # abbreviate this to +authcid+.
         attr_reader :username
         alias authcid username
 
@@ -263,7 +263,7 @@ module Net
       end
 
       # Authenticator for the "+SCRAM-SHA-1+" SASL mechanism, defined in
-      # RFC5802[https://tools.ietf.org/html/rfc5802].
+      # RFC5802[https://www.rfc-editor.org/rfc/rfc5802].
       #
       # Uses the "SHA-1" digest algorithm from OpenSSL::Digest.
       #
@@ -273,7 +273,7 @@ module Net
       end
 
       # Authenticator for the "+SCRAM-SHA-256+" SASL mechanism, defined in
-      # RFC7677[https://tools.ietf.org/html/rfc7677].
+      # RFC7677[https://www.rfc-editor.org/rfc/rfc7677].
       #
       # Uses the "SHA-256" digest algorithm from OpenSSL::Digest.
       #