[ruby/net-imap] Clean up authenticators rdoc

Added RFC links to all SASL mechanism specifications.

https://github.com/ruby/net-imap/commit/53ff4b0c09

5 files changed, 36 insertions, 18 deletions

diff --git a/lib/net/imap/authenticators.rb b/lib/net/imap/authenticators.rb
index f86b77b09f..b5dded35a5 100644
--- a/lib/net/imap/authenticators.rb
+++ b/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.
   #
diff --git a/lib/net/imap/authenticators/cram_md5.rb b/lib/net/imap/authenticators/cram_md5.rb
index 0bef638185..0930c5ac34 100644
--- a/lib/net/imap/authenticators/cram_md5.rb
+++ b/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)
diff --git a/lib/net/imap/authenticators/digest_md5.rb b/lib/net/imap/authenticators/digest_md5.rb
index a5f4b9093e..19e1a460c8 100644
--- a/lib/net/imap/authenticators/digest_md5.rb
+++ b/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
diff --git a/lib/net/imap/authenticators/login.rb b/lib/net/imap/authenticators/login.rb
index 8925d6de62..e1afebc323 100644
--- a/lib/net/imap/authenticators/login.rb
+++ b/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
diff --git a/lib/net/imap/authenticators/plain.rb b/lib/net/imap/authenticators/plain.rb
index 2b6051c0f2..a9d46c920e 100644
--- a/lib/net/imap/authenticators/plain.rb
+++ b/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