https://git.ruby-lang.org/ruby.git/commit/?id=2fc91da86c

From 2fc91da86c06405f836fb040a340c0f76a27f09f Mon Sep 17 00:00:00 2001
From: "nicholas a. evans" <nicholas.evans@g...>
Date: Wed, 28 Apr 2021 17:43:34 -0400
Subject: [ruby/net-imap] Clean up authenticators rdoc

Added RFC links to all SASL mechanism specifications.

https://github.com/ruby/net-imap/commit/53ff4b0c09
---
 lib/net/imap/authenticators.rb            |  6 +++---
 lib/net/imap/authenticators/cram_md5.rb   | 16 +++++++++-------
 lib/net/imap/authenticators/digest_md5.rb |  8 ++++----
 lib/net/imap/authenticators/login.rb      | 13 +++++++++++--
 lib/net/imap/authenticators/plain.rb      | 11 +++++++++--
 5 files changed, 36 insertions(+), 18 deletions(-)

diff --git a/lib/net/imap/authenticators.rb b/lib/net/imap/authenticators.rb
index f86b77b..b5dded3 100644
--- a/lib/net/imap/authenticators.rb
+++ b/lib/net/imap/authenticators.rb
@@ -3,11 +3,11 @@ https://github.com/ruby/ruby/blob/trunk/lib/net/imap/authenticators.rb#L3
 # 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 0bef638..0930c5a 100644
--- a/lib/net/imap/authenticators/cram_md5.rb
+++ b/lib/net/imap/authenticators/cram_md5.rb
@@ -2,17 +2,19 @@ https://github.com/ruby/ruby/blob/trunk/lib/net/imap/authenticators/cram_md5.rb#L2
 
 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 a5f4b90..19e1a46 100644
--- a/lib/net/imap/authenticators/digest_md5.rb
+++ b/lib/net/imap/authenticators/digest_md5.rb
@@ -3,14 +3,14 @@ https://github.com/ruby/ruby/blob/trunk/lib/net/imap/authenticators/digest_md5.rb#L3
 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 8925d6d..e1afebc 100644
--- a/lib/net/imap/authenticators/login.rb
+++ b/lib/net/imap/authenticators/login.rb
@@ -2,12 +2,21 @@ https://github.com/ruby/ruby/blob/trunk/lib/net/imap/authenticators/login.rb#L2
 
 # 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 2b6051c..a9d46c9 100644
--- a/lib/net/imap/authenticators/plain.rb
+++ b/lib/net/imap/authenticators/plain.rb
@@ -1,14 +1,21 @@ https://github.com/ruby/ruby/blob/trunk/lib/net/imap/authenticators/plain.rb#L1
 # 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
-- 
cgit v1.1


--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/