✨ SASL EXTERNAL: Add mechanism

Author: nevans

lib/net/imap.rb

@@ -992,6 +992,10 @@ def starttls(options = {}, verify = true)
     #               Non-standard and obsoleted by +OAUTHBEARER+, but widely
     #               supported.
     #
+    # +EXTERNAL+::  See SASL::ExternalAuthenticator.
+    #               Login using already established credentials, such as a TLS
+    #               certificate or IPsec.
+    #
     # +ANONYMOUS+:: See SASL::AnonymousAuthenticator.
     #               Allow the user to gain access to public services or
     #               resources without authenticating or disclosing an

lib/net/imap/authenticators.rb

@@ -68,6 +68,7 @@ def authenticators
 Net::IMAP.extend Net::IMAP::Authenticators
 
 require_relative "sasl/anonymous_authenticator"
+require_relative "sasl/external_authenticator"
 require_relative "sasl/plain_authenticator"
 require_relative "sasl/xoauth2_authenticator"
 

lib/net/imap/sasl/authenticator.rb

@@ -27,6 +27,10 @@ module SASL
       #               Non-standard and obsoleted by +OAUTHBEARER+, but widely
       #               supported.
       #
+      # +EXTERNAL+::  See SASL::ExternalAuthenticator.
+      #               Login using already established credentials, such as a TLS
+      #               certificate or IPsec.
+      #
       # +ANONYMOUS+:: See SASL::AnonymousAuthenticator.
       #               Allow the user to gain access to public services or
       #               resources without authenticating or disclosing an

lib/net/imap/sasl/external_authenticator.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative "authenticator"
+
+module Net
+  class IMAP < Protocol
+    module SASL
+
+      # Authenticator for the "+EXTERNAL+" SASL mechanism, as specified by
+      # RFC-4422[https://tools.ietf.org/html/rfc4422].  See
+      # Net::IMAP#authenticate.
+      #
+      # The EXTERNAL mechanism requests that the server use client credentials
+      # established external to SASL, for example by TLS certificate or IPsec.
+      #
+      class ExternalAuthenticator < Authenticator
+        register Net::IMAP
+
+        # :call-seq:
+        #   initial_response? -> true
+        #
+        # +EXTERNAL+ can send an initial client response.
+        def initial_response?; true end
+
+        ##
+        # :call-seq:
+        #   new                                 -> authenticator
+        #   new(authzid,  **)                   -> authenticator
+        #   new(authzid:, **)                   -> authenticator
+        #   new {|propname, auth_ctx| propval } -> authenticator
+        #
+        # Creates an Authenticator for the "+EXTERNAL+" SASL mechanism, as
+        # specified in RFC-4422[https://tools.ietf.org/html/rfc4422].  To use
+        # this, see Net::IMAP#authenticate or your client's authentication
+        # method.
+        #
+        # ==== Properties
+        # Only one property, which is optional:
+        #
+        # * #authzid -- the identity to act as.  Leave blank to use the identity
+        #   associated with the client's credentials.
+        #
+        #   May be sent as a positional argument or as a keyword argument.
+        #
+        # See Net::IMAP::SASL::Authenticator@Properties for a detailed
+        # description of property assignment, lazy loading, and callbacks.
+        def initialize(authzid_arg = nil, authzid: nil)
+          super
+          propinit :authzid, authzid, authzid_arg
+        end
+
+        property :authzid
+
+        def process(_)
+          return "" if authzid.nil?
+          if /\u0000/u.match?(authzid) # also validates UTF8 encoding
+            raise DataFormatError, "authzid contains NULL"
+          end
+          authzid.encode "UTF-8"
+        end
+
+        private
+
+        NULL = "\0"
+
+        def propset(name, value)
+          if name == :authzid && !value.nil?
+            raise ArgumentError, "#{name} contains NULL"  if value.include? NULL
+            value = value.encode "UTF-8"
+            unless value.valid_encoding?
+              raise ArgumentError, "#{name} isn't valid UTF-8"
+            end
+          end
+          super(name, value)
+        end
+
+      end
+    end
+  end
+end

test/net/imap/sasl/test_authenticators.rb

@@ -80,6 +80,37 @@ def test_xoauth2_callbacks
     )
   end
 
+  # ----------------------
+  # EXTERNAL
+  # ----------------------
+
+  def external(*args, **kwargs, &block)
+    Net::IMAP.authenticator("EXTERNAL", *args, **kwargs, &block)
+  end
+
+  def test_external_matches_mechanism
+    assert_kind_of(Net::IMAP::SASL::ExternalAuthenticator, external)
+  end
+
+  def test_external_response
+    assert_equal("", external.process(nil))
+    assert_equal("hello world", external("hello world").process(nil))
+    assert_equal("kwargs",
+                 external(authzid: "kwargs").process(nil))
+  end
+
+  def test_external_utf8
+    assert_equal("", external.process(nil))
+    assert_equal("🏴󠁧󠁢󠁥󠁮󠁧󠁿 England", external("🏴󠁧󠁢󠁥󠁮󠁧󠁿 England").process(nil))
+    assert_equal("kwargs",
+                 external(authzid: "kwargs").process(nil))
+  end
+
+  def test_external_invalid
+    assert_raise(ArgumentError) { external("bad\0contains NULL") }
+    assert_raise(ArgumentError) { external("invalid utf8\x80") }
+  end
+
   # ----------------------
   # ANONYMOUS
   # ----------------------