net-imap 0.4.12 → 0.5.6

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.
       #

data/lib/net/imap/sasl.rb

@@ -5,7 +5,7 @@ module Net
 
     # Pluggable authentication mechanisms for protocols which support SASL
     # (Simple Authentication and Security Layer), such as IMAP4, SMTP, LDAP, and
-    # XMPP.  {RFC-4422}[https://tools.ietf.org/html/rfc4422] specifies the
+    # XMPP.  {RFC-4422}[https://www.rfc-editor.org/rfc/rfc4422] specifies the
     # common \SASL framework:
     # >>>
     #   SASL is conceptually a framework that provides an abstraction layer
@@ -114,8 +114,8 @@ module Net
       # messages has not passed integrity checks.
       AuthenticationFailed = Class.new(Error)
 
-      # Indicates that authentication cannot proceed because one of the server's
-      # ended authentication prematurely.
+      # Indicates that authentication cannot proceed because the server ended
+      # authentication prematurely.
       class AuthenticationIncomplete < AuthenticationFailed
         # The success response from the server
         attr_reader :response
@@ -159,7 +159,10 @@ module Net
       # Returns the default global SASL::Authenticators instance.
       def self.authenticators; @authenticators ||= Authenticators.new end
 
-      # Delegates to <tt>registry.new</tt>  See Authenticators#new.
+      # Creates a new SASL authenticator, using SASL::Authenticators#new.
+      #
+      # +registry+ defaults to SASL.authenticators.  All other arguments are
+      # forwarded to to <tt>registry.new</tt>.
       def self.authenticator(*args, registry: authenticators, **kwargs, &block)
         registry.new(*args, **kwargs, &block)
       end

data/lib/net/imap/sasl_adapter.rb

@@ -12,7 +12,6 @@ module Net
 
       def response_errors;          RESPONSE_ERRORS                 end
       def sasl_ir_capable?;         client.capable?("SASL-IR")      end
-      def auth_capable?(mechanism); client.auth_capable?(mechanism) end
       def drop_connection;          client.logout!                  end
       def drop_connection!;         client.disconnect               end
     end

data/lib/net/imap/search_result.rb

@@ -100,10 +100,10 @@ module Net
       #    data.to_s("SORT")   # => "* SORT 2 8 32 128 256 512"
       #    data.to_s(nil)      # => "2 8 32 128 256 512"
       #
-      #    data = Net::IMAP::SearchResult[1, 3, 16, 1024, modseq: 2048].to_s
+      #    data = Net::IMAP::SearchResult[1, 3, 16, 1024, modseq: 2048]
       #    data.to_s           # => "* SEARCH 1 3 16 1024 (MODSEQ 2048)"
       #    data.to_s("SORT")   # => "* SORT 1 3 16 1024 (MODSEQ 2048)"
-      #    data.to_s           # => "1 3 16 1024 (MODSEQ 2048)"
+      #    data.to_s(nil)      # => "1 3 16 1024 (MODSEQ 2048)"
       #
       def to_s(type = "SEARCH")
         str = +""