Improved authenticator system

.github/workflows/unit-testing-and-coverage.yml

@@ -25,15 +25,22 @@ jobs:
         include:
           - os: "windows-latest"
             platform: "mswin"
-            # Only the latest stable branch as indicated on
-            # https://devguide.python.org/#branchstatus
-            # ('stable' means Status == "security")
-            # Reason being that Windows users can change their Python anytime,
-            # so there is no benefit in testing all released Python versions.
-            # Plus pypy3 implementation in Windows is ... complicated. We
-            # should stay away from all those complications; users choosing to
-            # run aiosmtpd on pypy3 on Windows should be considered advanced
-            # and know what they're doing.
+            # For Windows, we'll use only the latest "frozen" branch.
+            #     "Frozen" here means Status == "security" as indicated on the
+            #     https://devguide.python.org/#status-of-python-branches page.
+            #     I call it "frozen" because "no more binaries are released", so
+            #     for the great majority of users not compiling their own CPython,
+            #     the behavior won't change. Originally I call it "stable" but
+            #     someone apparently defined the term "stable" as "still receiving
+            #     bugfixes" so I had to change to prevent confusion.
+            #
+            # Also, Windows users can change their Python anytime since it's not part of the OS.
+            # Hence there is no benefit in testing all released Python versions.
+            #
+            # In addition, pypy3 implementation in Windows is ... complicated. We should stay
+            # away from all those complications; users choosing to use pypy3 on Windows to run
+            # aiosmtpd should be considered advanced, know what they're doing, and ready for
+            # all the consequences
             python-version: "3.7"
     runs-on: ${{ matrix.os }}
     steps:

aiosmtpd/docs/NEWS.rst

@@ -3,6 +3,25 @@
 ===================
 
 
+1.3.0 (aiosmtpd-next-next)
+==========================
+
+Added
+-----
+* authenticator system improves on auth_callback by enabling the called function to see the
+  SMTP Session and other info. (We can deprecate auth_callback in a future version)
+
+
+1.2.4 (aiosmtpd-next)
+=====================
+
+Fixed/Improved
+--------------
+* Remove special handling for lone ``=`` during AUTH;
+  it is now treated as simple Base64-encoded ``b""``.
+  This is the correct, strict interpretation of :rfc:`4954` mentions about ``=``
+
+
 1.2.3 (2021-01-14)
 ==================
 

aiosmtpd/docs/handlers.rst

@@ -183,7 +183,7 @@ those methods of the handler instance will override the built-in methods.
 
   :boldital:`server` is the instance of the ``SMTP`` class invoking the AUTH hook.
   This allows the AUTH hook implementation to invoke facilities such as the
-  ``push()`` and ``_auth_interact()`` methods.
+  ``push()`` and ``challenge_auth()`` methods.
 
   :boldital:`args` is a list of string split from the string after the ``AUTH`` command.
   ``args[0]`` is always equal to ``MECHANISM``.

aiosmtpd/docs/smtp.rst

@@ -4,10 +4,10 @@
  The SMTP class
 ================
 
-At the heart of this module is the ``SMTP`` class.  This class implements the
-:rfc:`5321` Simple Mail Transport
-Protocol.  Often you won't run an ``SMTP`` instance directly, but instead will
-use a :ref:`controller <controller>` instance to run the server in a subthread.
+At the heart of this module is the ``SMTP`` class.
+This class implements the :rfc:`5321` Simple Mail Transport Protocol.
+Often you won't run an ``SMTP`` instance directly,
+but instead will use a :ref:`Controller <controller>` instance to run the server in a subthread.
 
     >>> from aiosmtpd.controller import Controller
 
@@ -107,7 +107,7 @@ SMTP API
    decode_data=False, hostname=None, ident=None, tls_context=None, \
    require_starttls=False, timeout=300, auth_required=False, \
    auth_require_tls=True, auth_exclude_mechanism=None, auth_callback=None, \
-   command_call_limit=None, loop=None)
+   authenticator=None, command_call_limit=None, loop=None)
 
    **Parameters**
 
@@ -159,6 +159,31 @@ SMTP API
    ``login: bytes``, and ``password: bytes``. Based on these args, the function
    must return a ``bool`` that indicates whether the client's authentication
    attempt is accepted/successful or not.
+   The** ``authenticator`` parameter below, if set, **overrides** this parameter.
+
+   :boldital:`authenticator` is a function whose signature is identical to ``aiosmtpd.smtp.AuthenticatorType``.
+   This parameter, if set, **overrides** the ``auth_callback`` parameter above.
+   The function must accept five arguments:
+
+      * ``server`` -- reference to the calling SMTP instance
+      * ``session`` -- the Session object of the current SMTP session
+      * ``envelope`` -- the Envelope object of the current SMTP session so far
+      * ``mechanism`` -- the SMTP Auth Mechanism chosen by the SMTP Client
+      * ``auth_data`` -- a data structure containing information necessary for authentication.
+        For built-in mechanisms this invariably contains a tuple of ``(username, password)``
+
+   The function must return an instance of ``AuthResult``,
+   a namedtuple with the following fields/attributes:
+
+      * ``success`` -- True if authentication successful
+      * ``handled`` -- (ignored if ``success`` is True)
+        Indicates all necessary processing (e.g., sending of SMTP Status Codes) has been handled and
+        the calling SMTP instance does not need to perform further processing
+      * ``message`` -- (Optional) Message explaining the ``success`` value.
+        If ``handled`` is false, then contains the SMTP Status Code to be sent by the calling SMTP instance
+      * ``auth_data`` -- (only if ``success`` is True)
+        A free-form data structure containing the authentication information.
+        For the built-in AUTH mechanisms, invariably contains a tuple of ``(username, password)``
 
    :boldital:`command_call_limit` if not ``None`` sets the maximum time a certain SMTP
    command can be invoked.
@@ -203,7 +228,7 @@ SMTP API
    :boldital:`loop` is the asyncio event loop to use.  If not given,
    :meth:`asyncio.new_event_loop()` is called to create the event loop.
 
-   **Attributes**
+   **Attributes & Methods**
 
    .. py:attribute:: line_length_limit
 
@@ -221,6 +246,16 @@ SMTP API
          :attr:`line_length_limit` to ``2**16`` *before* instantiating the
          :class:`SMTP` class.
 
+   .. py:attribute:: AuthLoginUsernameChallenge
+
+      A ``str`` containing the base64-encoded challenge to be sent as the first challenge
+      in the ``AUTH LOGIN`` mechanism.
+
+   .. py:attribute:: AuthLoginPasswordChallenge
+
+      A ``str`` containing the base64-encoded challenge to be sent as the second challenge
+      in the ``AUTH LOGIN`` mechanism.
+
    .. attribute:: event_handler
 
       The *handler* instance passed into the constructor.
@@ -301,9 +336,10 @@ SMTP API
 Enabling STARTTLS
 =================
 
-To enable :rfc:`3207` ``STARTTLS``, you must supply the *tls_context* argument
-to the :class:`SMTP` class.  *tls_context* is created with the
-:func:`ssl.create_default_context` call from the :mod:`ssl` module, as follows::
+To enable :rfc:`3207` ``STARTTLS``,
+you must supply the *tls_context* argument to the :class:`SMTP` class.
+*tls_context* is created with the :func:`ssl.create_default_context` call
+from the :mod:`ssl` module, as follows::
 
     context = ssl.create_default_context(ssl.Purpose.CLIENT_AUTH)