summaryrefslogtreecommitdiff
path: root/mail
diff options
context:
space:
mode:
authordrebs <drebs@leap.se>2015-06-18 12:29:37 -0300
committerdrebs <drebs@leap.se>2015-06-18 12:31:53 -0300
commitdb77e43fe78b0440ea568bc54b31894afe1d42a6 (patch)
tree6e8adde41ac6c1ee4069b9244572139c96fa2262 /mail
parent0413a50b42eae2f1cd609d2a3c07edc6def87a51 (diff)
[doc] update smtp gateway doc on message encryption
Closes: #7169.
Diffstat (limited to 'mail')
-rw-r--r--mail/changes/bug_7169_update-smtp-gateway-doc1
-rw-r--r--mail/src/leap/mail/smtp/README.rst41
-rw-r--r--mail/src/leap/mail/smtp/gateway.py32
3 files changed, 48 insertions, 26 deletions
diff --git a/mail/changes/bug_7169_update-smtp-gateway-doc b/mail/changes/bug_7169_update-smtp-gateway-doc
new file mode 100644
index 00000000..5b86140a
--- /dev/null
+++ b/mail/changes/bug_7169_update-smtp-gateway-doc
@@ -0,0 +1 @@
+ o Update SMTP gateway docs. Closes #7169.
diff --git a/mail/src/leap/mail/smtp/README.rst b/mail/src/leap/mail/smtp/README.rst
index f6254419..1d3a9038 100644
--- a/mail/src/leap/mail/smtp/README.rst
+++ b/mail/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/mail/src/leap/mail/smtp/gateway.py b/mail/src/leap/mail/smtp/gateway.py
index dd2c32d9..f6182a24 100644
--- a/mail/src/leap/mail/smtp/gateway.py
+++ b/mail/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)