diff options
| -rw-r--r-- | changes/bug_7169_update-smtp-gateway-doc | 1 | ||||
| -rw-r--r-- | src/leap/mail/smtp/README.rst | 41 | ||||
| -rw-r--r-- | src/leap/mail/smtp/gateway.py | 32 |
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) |