Clean up authenticators rdoc

Added RFC links to all SASL mechanism specifications.

Author: nevans

lib/net/imap/authenticators.rb

@@ -3,11 +3,11 @@
 # Registry for SASL authenticators used by Net::IMAP.
 module Net::IMAP::Authenticators
 
- # Adds an authenticator for Net::IMAP#authenticate. +auth_type+ is the
+ # 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, "+LOGIN+"). The +authenticator+
+ # 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::LoginAuthenticator,
+ # the server. See Net::IMAP::PlainAuthenticator, Net::IMAP::LoginAuthenticator,
  # Net::IMAP::CramMD5Authenticator, and Net::IMAP::DigestMD5Authenticator for
  # examples.
  #

lib/net/imap/authenticators/cram_md5.rb

@@ -2,17 +2,19 @@
 
 require "digest/md5"
 
-# Authenticator for the "+CRAM-MD5+" SASL mechanism. See
-# Net::IMAP#authenticate.
+# Authenticator for the "+CRAM-MD5+" SASL mechanism, specified in
+# RFC2195[https://tools.ietf.org/html/rfc2195]. See Net::IMAP#authenticate.
 #
 # == Deprecated
 #
-# +CRAM-MD5+ should be considered obsolete and insecure. It is included for
-# backward compatibility with historic servers.
+# +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.
+# 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)

lib/net/imap/authenticators/digest_md5.rb

@@ -3,14 +3,14 @@
 require "digest/md5"
 require "strscan"
 
-# Net::IMAP authenticator for the "`DIGEST-MD5`" SASL mechanism type. See
-# Net::IMAP#authenticate.
+# 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 used. It
-# is included for backward compatibility with historic servers.
+# {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

lib/net/imap/authenticators/login.rb

@@ -2,12 +2,21 @@
 
 # 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". See also
-# {draft-murchison-sasl-login}[https://www.iana.org/go/draft-murchison-sasl-login].
+# 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

lib/net/imap/authenticators/plain.rb

@@ -1,14 +1,21 @@
 # frozen_string_literal: true
 
-# Authenticator for the "+PLAIN+" SASL mechanism. See Net::IMAP#authenticate.
+# Authenticator for the "+PLAIN+" SASL mechanism, specified in
+# RFC4616[https://tools.ietf.org/html/rfc4616]. See Net::IMAP#authenticate.
 #
-# See RFC4616[https://tools.ietf.org/html/rfc4616] for the specification.
+# +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