Address review comments for login_plain

* Use an empty SASL authorization identity (RFC 4616): the previous
  code sent the user name as authzid, requesting proxy authorization,
  which many servers reject.
* Note that PLAIN is only base64-encoded and requires a TLS connection.
* Cite RFC 4616 for the mechanism; RFC 6855 only for UTF-8 support.
* Fix the versionadded marker and the documented parameter name.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: serhiy-storchaka

Doc/library/imaplib.rst

@@ -437,18 +437,20 @@ An :class:`IMAP4` instance has the following methods:
       An :exc:`IMAP4.error` is raised if MD5 support is not available.
 
 
-.. method:: IMAP4.login_plain(login, password)
+.. method:: IMAP4.login_plain(user, password)
 
-    Authenticate using PLAIN SASL mechanism.
+   Authenticate using the ``PLAIN`` SASL mechanism (:rfc:`4616`).
 
-    This is a plain-text authentication mechanism that can be used
-    instead of :meth:`IMAP4.login()` when UTF-8 support is required.
-    See :RFC:`6855`, page 5.
+   This is a plaintext authentication mechanism that can be used instead
+   of :meth:`login` when UTF-8 support is required (see :rfc:`6855`).
+   Since the credentials are only base64-encoded, not encrypted, this
+   method should only be used over a TLS-protected connection, such as
+   :class:`IMAP4_SSL` or after :meth:`starttls`.
 
-    It will only work if the server ``CAPABILITY`` response includes
-    the phrase ``AUTH=PLAIN``.
+   It will only work if the server ``CAPABILITY`` response includes
+   the phrase ``AUTH=PLAIN``.
 
-    .. versionadded:: 3.11
+   .. versionadded:: next
 
 
 .. method:: IMAP4.logout()

Lib/imaplib.py

@@ -740,15 +740,27 @@ def login(self, user, password):
 
 
     def login_plain(self, user, password):
-        """Authenticate using PLAIN SASL mechanism.
+        """Authenticate using the PLAIN SASL mechanism (RFC 4616).
 
-        This is a plain-text authentication mechanism that can be used
-        instead of login() when UTF-8 support is required.
+        This is a plaintext authentication mechanism that can be used
+        instead of login() when UTF-8 support is required.  Since the
+        credentials are only base64-encoded, not encrypted, it should
+        only be used over a TLS-protected connection.
+
+        'user' and 'password' can be strings (encoded to UTF-8) or
+        bytes-like objects.
         """
-        return self.authenticate(
-            "PLAIN",
-            lambda _: "{0}\x00{0}\x00{1}".format(user, password).encode()
-        )
+        if isinstance(user, str):
+            user = user.encode('utf-8')
+        if isinstance(password, str):
+            password = password.encode('utf-8')
+        if b'\0' in user or b'\0' in password:
+            raise ValueError("NUL is not allowed in user name or password")
+        # An empty authorization identity (RFC 4616) makes the server
+        # derive it from the authentication identity; a non-empty one
+        # requests proxy authorization and is often rejected.
+        response = b'\0' + bytes(user) + b'\0' + bytes(password)
+        return self.authenticate("PLAIN", lambda _: response)
 
 
     def login_cram_md5(self, user, password):

Lib/test/test_imaplib.py

@@ -420,6 +420,15 @@ def cmd_AUTHENTICATE(self, tag, args):
             self._send_tagged(tag, 'NO', 'No access')
 
 
+class AuthHandler_PLAIN(SimpleIMAPHandler):
+    capabilities = 'LOGINDISABLED AUTH=PLAIN'
+    def cmd_AUTHENTICATE(self, tag, args):
+        self.server.auth_args = args
+        self._send_textline('+')
+        self.server.response = yield
+        self._send_tagged(tag, 'OK', 'Logged in.')
+
+
 class NewIMAPTestsMixin:
     client = None
 
@@ -693,34 +702,33 @@ def test_login_cram_md5_blocked(self):
             client.login_cram_md5("tim", b"tanstaaftanstaaf")
 
     def test_login_plain_ascii(self):
-        class AuthHandler(SimpleIMAPHandler):
-            capabilities = 'LOGINDISABLED AUTH=PLAIN'
-            def cmd_AUTHENTICATE(self, tag, args):
-                self._send_textline('+')
-                r = yield
-                if r == b'cHJlbQBwcmVtAHBhc3M=\r\n':
-                    self._send_tagged(tag, 'OK', 'Logged in.')
-                else:
-                    self._send_tagged(tag, 'NO', 'No access')
-        client, _ = self._setup(AuthHandler)
-        self.assertTrue('AUTH=PLAIN' in client.capabilities)
+        client, server = self._setup(AuthHandler_PLAIN)
+        self.assertIn('AUTH=PLAIN', client.capabilities)
         ret, _ = client.login_plain("prem", "pass")
         self.assertEqual(ret, "OK")
+        self.assertEqual(server.auth_args, ['PLAIN'])
+        self.assertEqual(server.response, b'AHByZW0AcGFzcw==\r\n')
 
     def test_login_plain_utf8(self):
-        class AuthHandler(SimpleIMAPHandler):
-            capabilities = 'LOGINDISABLED AUTH=PLAIN'
-            def cmd_AUTHENTICATE(self, tag, args):
-                self._send_textline('+')
-                r = yield
-                if r == b'cHLEmW0AcHLEmW0AxbzDs8WCxIc=\r\n':
-                    self._send_tagged(tag, 'OK', 'Logged in.')
-                else:
-                    self._send_tagged(tag, 'NO', 'No access')
-        client, _ = self._setup(AuthHandler)
-        self.assertTrue('AUTH=PLAIN' in client.capabilities)
+        client, server = self._setup(AuthHandler_PLAIN)
+        self.assertIn('AUTH=PLAIN', client.capabilities)
         ret, _ = client.login_plain("pręm", "żółć")
         self.assertEqual(ret, "OK")
+        self.assertEqual(server.response, b'AHByxJltAMW8w7PFgsSH\r\n')
+
+    def test_login_plain_bytes(self):
+        # bytes are accepted and sent verbatim (not re-encoded).
+        client, server = self._setup(AuthHandler_PLAIN)
+        ret, _ = client.login_plain(b'pr\xc4\x99m', b'\xc5\xbc\xc3\xb3\xc5\x82\xc4\x87')
+        self.assertEqual(ret, "OK")
+        self.assertEqual(server.response, b'AHByxJltAMW8w7PFgsSH\r\n')
+
+    def test_login_plain_nul(self):
+        client, _ = self._setup(AuthHandler_PLAIN)
+        with self.assertRaises(ValueError):
+            client.login_plain('user\0', 'pass')
+        with self.assertRaises(ValueError):
+            client.login_plain('user', b'pa\0ss')
 
     def test_aborted_authentication(self):
         class MyServer(SimpleIMAPHandler):

Misc/NEWS.d/next/Library/2021-11-04-00-09-09.bpo-45706.XG7aHz.rst

@@ -0,0 +1,3 @@
+Add :meth:`imaplib.IMAP4.login_plain`, which authenticates using the
+``PLAIN`` SASL mechanism (:rfc:`4616`).  Unlike :meth:`~imaplib.IMAP4.login`,
+it supports non-ASCII user names and passwords.