[Rt-commit] rt branch, 4.4/secure-email-doc, created. rt-4.4.2-238-g88032f84d

[Brian Duggan]

The branch, 4.4/secure-email-doc has been created
        at  88032f84d418bc13b4314afb64df2b042931aa71 (commit)

- Log -----------------------------------------------------------------
commit 88032f84d418bc13b4314afb64df2b042931aa71
Author: Brian C. Duggan <brian at bestpractical.com>
Date:   Wed May 16 18:06:34 2018 -0400

    WIP Add high-level secure email documentation

diff --git a/docs/secure_email.pod b/docs/secure_email.pod
new file mode 100644
index 000000000..a579b39eb
--- /dev/null
+++ b/docs/secure_email.pod
@@ -0,0 +1,121 @@
+=head1 Introduction
+
+GnuPG and S/MIME can encrypt and sign messages in email before the
+user's MUA sends the mail. The mail recipient can decrypt the message
+and verify the sender's signature on the message in their MUA. The
+sender and recipient must install each other's public keys to exchange
+these messages.
+
+When a GnuPG or S/MIME user sends a message to multiple recipients,
+they must have installed all of the recipients' public keys. Each of
+the recipients must have installed the sender's key to verify the
+message.
+
+RT can use GnuPG and S/MIME to decrypt, encrypt, sign, and verify mail
+as an intermediary. Unlike the workflows described above, senders and
+recipients only need to install the RT instance's public key. Instead
+of encrypting a message to the final mail recipients, a sender only
+needs to encrypt the message to the RT instance's key. RT will decrypt
+and verify the message. Then, RT will encrypt the message to each of
+the ticket's watchers individually and sign the message with its own
+key.
+
+This document describes how to implement an RT workflow using GnuPG or
+S/MIME to protect the content and integrity of messages in email.
+
+=head1 Background
+
+=head2 What encrypted mail does
+
+TLS encrypts the IMAP, POP, and SMTP connections from users' MUAs to
+mail servers. It also encrypts the SMTP connections between mail
+servers. This prevents entities like ISPs from eavesdropping on email
+in transit between at any point between users' email clients. But TLS
+does not prevent mail servers from eavesdropping on email messages. It
+also does not protect mail from man-in-the-middle attacks against TLS
+connections.
+
+GnuPG and S/MIME protect messages in email while it is in transit
+between the individual users' email clients and while email is at rest
+on a mail server. Mail servers cannot read the messages in encrypted
+mails that they relay or store.
+
+GnuPG and S/MIME only protect messages in email. They cannot hide mail
+headers.
+
+RT can store the encrypted messages as they were received and decrypt
+them on display. Or RT can decrypt the messages on receipt and store
+the decrypted content.
+
+=head2 How encrypted mail works
+
+GnuPG and S/MIME both use public key cryptography. Each user must have
+a private key and a public key for their own identity. And each user
+must have a public key for every person they exchange encrypted mail
+with.
+
+Users encrypt messages to public keys. They decrypt mail encrypted to
+their own public key with their private key.
+
+Users sign messages with their private keys. They verify other users'
+signatures with those users' public keys.
+
+RT has its own set of keys, like any other encrypted mail user. RT
+must have at least one public and private key pair. It must also have
+the public keys for any email addresses that RT users want to exchange
+encrypted mail with.
+
+=head2 How GnuPG and S/MIME are different
+
+=head3 GnuPG background
+
+GnuPG does not depend on a trusted authority to distribute or verify
+keys. Users can install any public key from any source and decide how
+much they trust that key. But it is up to the user to verify the
+authenticity of that key.
+
+RT administrators must manage RT's GnuPG keyring manually.
+
+=head3 S/MIME background
+
+S/MIME depends on a trusted authority to verify the authenticity of
+other users' public keys.
+
+...
+
+RT administrators must install the trusted authority keys, certificate
+authorities, that sign the keys of users that want to communicate with
+it.
+
+=head1 Using encrypted mail with RT
+
+When two encrypted mail users communicate directly with each other,
+they must each have a collection of encryption keys. Each user must
+have a public key and a private key for their own identity. And they
+must have the other user's public key.
+
+When three encrypted mail users communicate directly with each other,
+they must each have public and private keys for themselves. And each
+of them must have the public keys for the other two users.
+
+Encrypted mail in RT operates differently. Instead of communicating
+directly with each other, RT acts as a mail intermediary. Users
+encrypt messages to RT's key. RT decrypts those messages. Then RT
+re-encrypts the messages to all mail recipients for that ticket. Users
+receive encrypted mail from RT, not the original sender.
+
+Users sign messages with their private key to send to RT. RT verifies
+those signatures. Then RT signs the message with its own key and sends
+it to all mail recipients for that ticket.
+
+When encrypted mail users communicate with each other through RT, each
+of them must have RT's public key. They do not need each others'
+public keys. Only RT must have every user's public key.
+
+=head2 An example
+
+=head3 The story of Alice and Bob.
+
+=head3 The story of Alice, Bob, Carol, and Faythe
+
+=cut

-----------------------------------------------------------------------