[doc] update smtp gateway doc on message encryption

Closes: #7169.

3 files changed, 48 insertions, 26 deletions

diff --git a/changes/bug_7169_update-smtp-gateway-doc b/changes/bug_7169_update-smtp-gateway-doc
new file mode 100644
index 0000000..5b86140
--- /dev/null
+++ b/changes/bug_7169_update-smtp-gateway-doc
@@ -0,0 +1 @@
+  o Update SMTP gateway docs. Closes #7169.
diff --git a/src/leap/mail/smtp/README.rst b/src/leap/mail/smtp/README.rst
index f625441..1d3a903 100644
--- a/src/leap/mail/smtp/README.rst
+++ b/src/leap/mail/smtp/README.rst
@@ -1,18 +1,39 @@
 Leap SMTP Gateway
 =================
 
+The Bitmask Client runs a thin SMTP gateway on the user's device, which
+intends to encrypt and sign outgoing messages to achieve point to point
+encryption.
+
+The gateway is bound to localhost and the user's MUA should be configured to
+send messages to it. After doing its thing, the gateway will relay the
+messages to the remote SMTP server.
+
 Outgoing mail workflow:
 
-    * LEAP client runs a thin SMTP proxy on the user's device, bound to
-      localhost.
-    * User's MUA is configured outgoing SMTP to localhost.
-    * When SMTP proxy receives an email from MUA:
-        * SMTP proxy queries Key Manager for the user's private key and public
-          keys of all recipients.
-        * Message is signed by sender and encrypted to recipients.
-        * If recipient's key is missing, email goes out in cleartext (unless
-          user has configured option to send only encrypted email).
-        * Finally, message is gatewayed to provider's SMTP server.
+  * SMTP gateway receives a message from the MUA.
+
+  * SMTP gateway queries Key Manager for the user's private key.
+
+  * For each recipient (including addresses in "To", "Cc" anc "Bcc" fields),
+    the following happens:
+
+    - The recipient's address is validated against RFC2822.
+
+    - An attempt is made to fetch the recipient's public PGP key.
+
+    - If key is not found:
+
+      - If the gateway is configured to only send encrypted messages the
+        recipient is rejected.
+
+      - Otherwise, the message is signed and sent as plain text.
+
+    - If the key is found, the message is encrypted to the recipient and
+      signed with the sender's private PGP key.
+
+  * Finally, one message for each recipient is gatewayed to provider's SMTP
+    server.
 
 
 Running tests
diff --git a/src/leap/mail/smtp/gateway.py b/src/leap/mail/smtp/gateway.py
index dd2c32d..f6182a2 100644
--- a/src/leap/mail/smtp/gateway.py
+++ b/src/leap/mail/smtp/gateway.py
@@ -21,15 +21,13 @@ The following classes comprise the SMTP gateway service:
 
     * SMTPFactory - A twisted.internet.protocol.ServerFactory that provides
       the SMTPDelivery protocol.
+
     * SMTPDelivery - A twisted.mail.smtp.IMessageDelivery implementation. It
       knows how to validate sender and receiver of messages and it generates
       an EncryptedMessage for each recipient.
-    * SSLContextFactory - Contains the relevant ssl information for the
-      connection.
+
     * EncryptedMessage - An implementation of twisted.mail.smtp.IMessage that
       knows how to encrypt/sign itself before sending.
-
-
 """
 
 from zope.interface import implements
@@ -173,27 +171,29 @@ class SMTPDelivery(object):
 
     def validateTo(self, user):
         """
-        Validate the address of C{user}, a recipient of the message.
+        Validate the address of a recipient of the message, possibly
+        rejecting it if the recipient key is not available.
+
+        This method is called once for each recipient, i.e. for each SMTP
+        protocol line beginning with "RCPT TO:", which includes all addresses
+        in "To", "Cc" and "Bcc" MUA fields.
 
-        This method is called once for each recipient and validates the
-        C{user}'s address against the RFC 2822 definition. If the
-        configuration option ENCRYPTED_ONLY_KEY is True, it also asserts the
-        existence of the user's key.
+        The recipient's address is validated against the RFC 2822 definition.
+        If self._encrypted_only is True and no key is found for a recipient,
+        then that recipient is rejected.
 
-        In the end, it returns an encrypted message object that is able to
-        send itself to the C{user}'s address.
+        The method returns an encrypted message object that is able to send
+        itself to the user's address.
 
         :param user: The user whose address we wish to validate.
         :type: twisted.mail.smtp.User
 
-        @return: A Deferred which becomes, or a callable which takes no
-            arguments and returns an object implementing IMessage. This will
-            be called and the returned object used to deliver the message when
-            it arrives.
+        @return: A callable which takes no arguments and returns an
+                 encryptedMessage.
         @rtype: no-argument callable
 
         @raise SMTPBadRcpt: Raised if messages to the address are not to be
-            accepted.
+                            accepted.
         """
         # try to find recipient's public key
         address = validate_address(user.dest.addrstr)