net-imap 0.3.4 → 0.5.6

data/lib/net/imap/sasl.rb

@@ -5,13 +5,12 @@ 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
-    # common SASL framework and the +EXTERNAL+ mechanism, and the
-    # {SASL mechanism registry}[https://www.iana.org/assignments/sasl-mechanisms/sasl-mechanisms.xhtml]
-    # lists the specification for others.
-    #
-    # "SASL is conceptually a framework that provides an abstraction layer
-    # between protocols and mechanisms as illustrated in the following diagram."
+    # 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
+    #   between protocols and mechanisms as illustrated in the following
+    #   diagram.
     #
     #               SMTP    LDAP    XMPP   Other protocols ...
     #                  \       |    |      /
@@ -21,58 +20,163 @@ module Net
     #                  /       |    |      \
     #           EXTERNAL   GSSAPI  PLAIN   Other mechanisms ...
     #
+    # Net::IMAP uses SASL via the Net::IMAP#authenticate method.
+    #
+    # == Mechanisms
+    #
+    # Each mechanism has different properties and requirements.  Please consult
+    # the documentation for the specific mechanisms you are using:
+    #
+    # +ANONYMOUS+::
+    #     See AnonymousAuthenticator.
+    #
+    #     Allows the user to gain access to public services or resources without
+    #     authenticating or disclosing an identity.
+    #
+    # +EXTERNAL+::
+    #     See ExternalAuthenticator.
+    #
+    #     Authenticates using already established credentials, such as a TLS
+    #     certificate or IPSec.
+    #
+    # +OAUTHBEARER+::
+    #     See OAuthBearerAuthenticator.
+    #
+    #     Login using an OAuth2 Bearer token.  This is the standard mechanism
+    #     for using OAuth2 with \SASL, but it is not yet deployed as widely as
+    #     +XOAUTH2+.
+    #
+    # +PLAIN+::
+    #     See PlainAuthenticator.
+    #
+    #     Login using clear-text username and password.
+    #
+    # +SCRAM-SHA-1+::
+    # +SCRAM-SHA-256+::
+    #     See ScramAuthenticator.
+    #
+    #     Login by username and password.  The password is not sent to the
+    #     server but is used in a salted challenge/response exchange.
+    #     +SCRAM-SHA-1+ and +SCRAM-SHA-256+ are directly supported by
+    #     Net::IMAP::SASL.  New authenticators can easily be added for any other
+    #     <tt>SCRAM-*</tt> mechanism if the digest algorithm is supported by
+    #     OpenSSL::Digest.
+    #
+    # +XOAUTH2+::
+    #     See XOAuth2Authenticator.
+    #
+    #     Login using a username and an OAuth2 access token.  Non-standard and
+    #     obsoleted by +OAUTHBEARER+, but widely supported.
+    #
+    # See the {SASL mechanism
+    # registry}[https://www.iana.org/assignments/sasl-mechanisms/sasl-mechanisms.xhtml]
+    # for a list of all SASL mechanisms and their specifications.  To register
+    # new authenticators, see Authenticators.
+    #
+    # === Deprecated mechanisms
+    #
+    # <em>Obsolete mechanisms should be avoided, but are still available for
+    # backwards compatibility.</em>
+    #
+    # >>>
+    #   For +DIGEST-MD5+ see DigestMD5Authenticator.
+    #
+    #   For +LOGIN+, see LoginAuthenticator.
+    #
+    #   For +CRAM-MD5+, see CramMD5Authenticator.
+    #
+    # <em>Using a deprecated mechanism will print a warning.</em>
+    #
     module SASL
+      # Exception class for any client error detected during the authentication
+      # exchange.
+      #
+      # When the _server_ reports an authentication failure, it will respond
+      # with a protocol specific error instead, e.g: +BAD+ or +NO+ in IMAP.
+      #
+      # When the client encounters any error, it *must* consider the
+      # authentication exchange to be unsuccessful and it might need to drop the
+      # connection.  For example, if the server reports that the authentication
+      # exchange was successful or the protocol does not allow additional
+      # authentication attempts.
+      Error = Class.new(StandardError)
 
-      # autoloading to avoid loading all of the regexps when they aren't used.
+      # Indicates an authentication exchange that will be or has been canceled
+      # by the client, not due to any error or failure during processing.
+      AuthenticationCanceled = Class.new(Error)
 
-      autoload :StringPrep, File.expand_path("sasl/stringprep", __dir__)
-      autoload :SASLprep, File.expand_path("#{__dir__}/sasl/saslprep", __dir__)
+      # Indicates an error when processing a server challenge, e.g: an invalid
+      # or unparsable challenge.  An underlying exception may be available as
+      # the exception's #cause.
+      AuthenticationError = Class.new(Error)
 
-      # ArgumentError raised when +string+ is invalid for the stringprep
-      # +profile+.
-      class StringPrepError < ArgumentError
-        attr_reader :string, :profile
+      # Indicates that authentication cannot proceed because one of the server's
+      # messages has not passed integrity checks.
+      AuthenticationFailed = Class.new(Error)
 
-        def initialize(*args, string: nil, profile: nil)
-          @string  = -string.to_str  unless string.nil?
-          @profile = -profile.to_str unless profile.nil?
-          super(*args)
-        end
-      end
+      # Indicates that authentication cannot proceed because the server ended
+      # authentication prematurely.
+      class AuthenticationIncomplete < AuthenticationFailed
+        # The success response from the server
+        attr_reader :response
 
-      # StringPrepError raised when +string+ contains a codepoint prohibited by
-      # +table+.
-      class ProhibitedCodepoint < StringPrepError
-        attr_reader :table
-
-        def initialize(table, *args, **kwargs)
-          @table = -table.to_str
-          details = (title = StringPrep::TABLE_TITLES[table]) ?
-            "%s [%s]" % [title, table] : table
-          message = "String contains a prohibited codepoint: %s" % [details]
-          super(message, *args, **kwargs)
+        def initialize(response, message = "authentication ended prematurely")
+          super(message)
+          @response = response
         end
       end
 
-      # StringPrepError raised when +string+ contains bidirectional characters
-      # which violate the StringPrep requirements.
-      class BidiStringError < StringPrepError
+      # autoloading to avoid loading all of the regexps when they aren't used.
+      sasl_stringprep_rb = File.expand_path("sasl/stringprep", __dir__)
+      autoload :StringPrep,          sasl_stringprep_rb
+      autoload :SASLprep,            sasl_stringprep_rb
+      autoload :StringPrepError,     sasl_stringprep_rb
+      autoload :ProhibitedCodepoint, sasl_stringprep_rb
+      autoload :BidiStringError,     sasl_stringprep_rb
+
+      sasl_dir = File.expand_path("sasl", __dir__)
+      autoload :AuthenticationExchange,   "#{sasl_dir}/authentication_exchange"
+      autoload :ClientAdapter,            "#{sasl_dir}/client_adapter"
+      autoload :ProtocolAdapters,         "#{sasl_dir}/protocol_adapters"
+
+      autoload :Authenticators,           "#{sasl_dir}/authenticators"
+      autoload :GS2Header,                "#{sasl_dir}/gs2_header"
+      autoload :ScramAlgorithm,           "#{sasl_dir}/scram_algorithm"
+
+      autoload :AnonymousAuthenticator,   "#{sasl_dir}/anonymous_authenticator"
+      autoload :ExternalAuthenticator,    "#{sasl_dir}/external_authenticator"
+      autoload :OAuthBearerAuthenticator, "#{sasl_dir}/oauthbearer_authenticator"
+      autoload :PlainAuthenticator,       "#{sasl_dir}/plain_authenticator"
+      autoload :ScramAuthenticator,       "#{sasl_dir}/scram_authenticator"
+      autoload :ScramSHA1Authenticator,   "#{sasl_dir}/scram_authenticator"
+      autoload :ScramSHA256Authenticator, "#{sasl_dir}/scram_authenticator"
+      autoload :XOAuth2Authenticator,     "#{sasl_dir}/xoauth2_authenticator"
+
+      autoload :CramMD5Authenticator,     "#{sasl_dir}/cram_md5_authenticator"
+      autoload :DigestMD5Authenticator,   "#{sasl_dir}/digest_md5_authenticator"
+      autoload :LoginAuthenticator,       "#{sasl_dir}/login_authenticator"
+
+      # Returns the default global SASL::Authenticators instance.
+      def self.authenticators; @authenticators ||= Authenticators.new end
+
+      # 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
 
-      #--
-      # We could just extend SASLprep module directly.  It's done this way so
-      # SASLprep can be lazily autoloaded.  Most users won't need it.
-      #++
-      extend self
+      # Delegates to ::authenticators.  See Authenticators#add_authenticator.
+      def self.add_authenticator(...) authenticators.add_authenticator(...) end
+
+      module_function
 
-      # See SASLprep#saslprep.
+      # See Net::IMAP::StringPrep::SASLprep#saslprep.
       def saslprep(string, **opts)
-        SASLprep.saslprep(string, **opts)
+        Net::IMAP::StringPrep::SASLprep.saslprep(string, **opts)
       end
 
     end
   end
-
 end
-
-Net::IMAP.extend Net::IMAP::SASL

data/lib/net/imap/sasl_adapter.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP
+
+    # Experimental
+    class SASLAdapter < SASL::ClientAdapter
+      include SASL::ProtocolAdapters::IMAP
+
+      RESPONSE_ERRORS = [NoResponseError, BadResponseError, ByeResponseError]
+        .freeze
+
+      def response_errors;          RESPONSE_ERRORS                 end
+      def sasl_ir_capable?;         client.capable?("SASL-IR")      end
+      def drop_connection;          client.logout!                  end
+      def drop_connection!;         client.disconnect               end
+    end
+
+  end
+end

data/lib/net/imap/search_result.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP
+
+    # An array of sequence numbers returned by Net::IMAP#search, or unique
+    # identifiers returned by Net::IMAP#uid_search.
+    #
+    # For backward compatibility, SearchResult inherits from Array.
+    class SearchResult < Array
+
+      # Returns a SearchResult populated with the given +seq_nums+.
+      #
+      #     Net::IMAP::SearchResult[1, 3, 5, modseq: 9]
+      #     # => Net::IMAP::SearchResult[1, 3, 5, modseq: 9]
+      def self.[](*seq_nums, modseq: nil)
+        new(seq_nums, modseq: modseq)
+      end
+
+      # A modification sequence number, as described by the +CONDSTORE+
+      # extension in {[RFC7162
+      # §3.1.6]}[https://www.rfc-editor.org/rfc/rfc7162.html#section-3.1.6].
+      attr_reader :modseq
+
+      # Returns a SearchResult populated with the given +seq_nums+.
+      #
+      #     Net::IMAP::SearchResult.new([1, 3, 5], modseq: 9)
+      #     # => Net::IMAP::SearchResult[1, 3, 5, modseq: 9]
+      def initialize(seq_nums, modseq: nil)
+        super(seq_nums.to_ary.map { Integer _1 })
+        @modseq = Integer modseq if modseq
+      end
+
+      # Returns whether +other+ is a SearchResult with the same values and the
+      # same #modseq.  The order of numbers is irrelevant.
+      #
+      #     Net::IMAP::SearchResult[123, 456, modseq: 789] ==
+      #       Net::IMAP::SearchResult[123, 456, modseq: 789]
+      #     # => true
+      #     Net::IMAP::SearchResult[123, 456, modseq: 789] ==
+      #       Net::IMAP::SearchResult[456, 123, modseq: 789]
+      #     # => true
+      #
+      #     Net::IMAP::SearchResult[123, 456, modseq: 789] ==
+      #       Net::IMAP::SearchResult[987, 654, modseq: 789]
+      #     # => false
+      #     Net::IMAP::SearchResult[123, 456, modseq: 789] ==
+      #       Net::IMAP::SearchResult[1, 2, 3, modseq: 9999]
+      #     # => false
+      #
+      # SearchResult can be compared directly with Array, if #modseq is nil and
+      # the array is sorted.
+      #
+      #     Net::IMAP::SearchResult[9, 8, 6, 4, 1] == [1, 4, 6, 8, 9] # => true
+      #     Net::IMAP::SearchResult[3, 5, 7, modseq: 99] == [3, 5, 7] # => false
+      #
+      # Note that Array#== does require matching order and ignores #modseq.
+      #
+      #     [9, 8, 6, 4, 1] == Net::IMAP::SearchResult[1, 4, 6, 8, 9] # => false
+      #     [3, 5, 7] == Net::IMAP::SearchResult[3, 5, 7, modseq: 99] # => true
+      #
+      def ==(other)
+        (modseq ?
+         other.is_a?(self.class) && modseq == other.modseq :
+         other.is_a?(Array)) &&
+          size == other.size &&
+          sort == other.sort
+      end
+
+      # Hash equality.  Unlike #==, order will be taken into account.
+      def hash
+        return super if modseq.nil?
+        [super, self.class, modseq].hash
+      end
+
+      # Hash equality.  Unlike #==, order will be taken into account.
+      def eql?(other)
+        return super if modseq.nil?
+        self.class == other.class && hash == other.hash
+      end
+
+      # Returns a string that represents the SearchResult.
+      #
+      #    Net::IMAP::SearchResult[123, 456, 789].inspect
+      #    # => "[123, 456, 789]"
+      #
+      #    Net::IMAP::SearchResult[543, 210, 678, modseq: 2048].inspect
+      #    # => "Net::IMAP::SearchResult[543, 210, 678, modseq: 2048]"
+      #
+      def inspect
+        return super if modseq.nil?
+        "%s[%s, modseq: %p]" % [self.class, join(", "), modseq]
+      end
+
+      # Returns a string that follows the formal \IMAP syntax.
+      #
+      #    data = Net::IMAP::SearchResult[2, 8, 32, 128, 256, 512]
+      #    data.to_s           # => "* SEARCH 2 8 32 128 256 512"
+      #    data.to_s("SEARCH") # => "* SEARCH 2 8 32 128 256 512"
+      #    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]
+      #    data.to_s           # => "* SEARCH 1 3 16 1024 (MODSEQ 2048)"
+      #    data.to_s("SORT")   # => "* SORT 1 3 16 1024 (MODSEQ 2048)"
+      #    data.to_s(nil)      # => "1 3 16 1024 (MODSEQ 2048)"
+      #
+      def to_s(type = "SEARCH")
+        str = +""
+        str << "* %s " % [type.to_str] unless type.nil?
+        str << join(" ")
+        str << " (MODSEQ %d)" % [modseq] if modseq
+        -str
+      end
+
+      # Converts the SearchResult into a SequenceSet.
+      #
+      #     Net::IMAP::SearchResult[9, 1, 2, 4, 10, 12, 3, modseq: 123_456]
+      #       .to_sequence_set
+      #     # => Net::IMAP::SequenceSet["1:4,9:10,12"]
+      def to_sequence_set; SequenceSet[*self] end
+
+      def pretty_print(pp)
+        return super if modseq.nil?
+        pp.text self.class.name + "["
+        pp.group_sub do
+          pp.nest(2) do
+            pp.breakable ""
+            each do |num|
+              pp.pp num
+              pp.text ","
+              pp.fill_breakable
+            end
+            pp.breakable ""
+            pp.text "modseq: "
+            pp.pp modseq
+          end
+          pp.breakable ""
+          pp.text "]"
+        end
+      end
+
+    end
+
+  end
+end