From ea2424cf4df8ba78dd31f2eb2f1e3710c4c8feca Mon Sep 17 00:00:00 2001 From: Kevin McCarthy Date: Fri, 2 Aug 2019 09:03:41 -0700 Subject: [PATCH] Add documentation for the autocrypt feature Co-authored-by: Richard Russon --- doc/manual.xml.head | 252 ++++++++++++++++++++++++++++++++++++++++++++ init.h | 9 +- 2 files changed, 258 insertions(+), 3 deletions(-) diff --git a/doc/manual.xml.head b/doc/manual.xml.head index 8d765b7b5..b4e38238d 100644 --- a/doc/manual.xml.head +++ b/doc/manual.xml.head @@ -17367,6 +17367,258 @@ bind index D purge-message + + + Autocrypt + + + Mutt can be compiled with Autocrypt support by running + configure with the + --enable-autocrypt flag. Autocrypt provides + easy to use, passive protection against data collection. Keys are + distributed via an Autocrypt: header added to + emails. It does not protect against active + adversaries, and so should not be considered a substitute for + normal encryption via your keyring, using key signing and the web + of trust to verify identities. With an understanding of these + limitations, Autocrypt still provides an easy way to minimize + cleartext emails sent between common correspondants, without + having to explicitly exchange keys. More information can be found + at https://autocrypt.org/. + + + + Requirements + + Autocrypt requires support for ECC cryptography, and Mutt by + default will generate ECC keys. Therefore GnuPG 2.1 or greater + is required. Additionally, Mutt's Autocrypt implementation uses + GPGME and requires at least version 1.8.0. + + + Account and peer information is stored in a sqlite3 database, and + so Mutt must be configured with the --with-sqlite3 + flag when autocrypt is enabled. + + + It is highly recommended Mutt be configured + --with-idn or + --with-idn2 so that Autocrypt can properly + deal with international domain names. + + + While Mutt uses GPGME for Autocrypt, normal keyring operations + can still be performed via classic mode (i.e. with + $crypt_use_gpgme unset). + However, to avoid unnecessary prompts, it is recommended gpg not + be configured in loopback pinentry mode, and + that $pgp_use_gpg_agent + remain set (the default). + + + + + First Run + + To enable Autocrypt, set $autocrypt, and if desired change the + value of $autocrypt_dir in + your muttrc. The first time Mutt is run after that, you will be + prompted to create + $autocrypt_dir. Mutt will then + automatically create an sqlite3 database and gpg keyring in that + directory. Note since these files should be considered private, + Mutt will create this directory with mode + 700. If you create the directory manually, + you should do the same. + + + Mutt recommends keeping the $autocrypt_dir directory set + differently from your GnuPG keyring directory + (e.g. ~/.gnupg). Keys are automatically + imported into the keyring from Autocrypt: + headers. Compared to standard WOT keys, Autocrypt keys are + somewhat ephemeral, and the autocrypt database is used to track + when keys change or fall out of use. Having these keys mixed in + with your normal keyring will make it more difficult to use + features such as + $crypt_opportunistic_encrypt + and Autocrypt at the same time. + + + The $autocrypt_dir variable + is not designed to be changed while Mutt is running. The + database is created (if necessary) and connected to during + startup. Changing the variable can result in a situation where + Mutt is looking in one place for the database and a different + place for the GPG keyring, resulting in strange behavior. + + + Once the directory, keyring, and database are created, Mutt will + ask whether you would like to create an account. In order to + use Autocrypt, each sending address needs an account. As a + convenience you can create an account during the first run. If + you would like to add additional accounts later, this can be + done via the <autocrypt-acct-menu> + function in the index, by default bound to A. + + + Creating an account requires specifying an email address, and + then deciding whether this address should prefer encryption or + not. Autocrypt 1.1 allows automatically enabling encryption if + both sender and receiver have set + prefer encryption. Otherwise, you will need to + manually enable autocrypt encryption in the compose menu. For + more details, see the compose menu section below. + + + After optionally creating an account, Mutt will prompt you to + scan mailboxes for Autocrypt headers. This step occurs because + header cached messages are not re-scanned for Autocrypt headers. + Scanning during this step will temporarily disable the header + cache while opening each mailbox. If you wish to do this + manually later, you can simulate the same thing by unsetting + $header_cache and opening a + mailbox. + + + + + Compose Menu + + When enabled, Autocrypt will add a line to the compose menu with + two fields: Autocrypt: and + Recommendation:. + + + The Autocrypt: field shows whether the + message will be encrypted by Autocrypt when sent. It has two + values: Encrypt and Off. + Encrypt can be enabled using the + <autocrypt-menu> function, by default + bound to o. + + + The Recommendation: field shows the output of + the Autocrypt recommendation engine. This can have one of five + values: + + + + + Off means the engine is disabled. This + can happen if the From address doesn't have an autocrypt + account, or if the account has been manually disabled. + + + + + No means one or more recipients are + missing an autocrypt key, or the key found is unusable + (i.e. expired, revoked, disabled, invalid, or not usable for + encryption.) + + + + + Discouraged means a key was found for + every recipient, but the engine is not confident the message + will be decryptable by the recipient. This can happen if + the key hasn't been used recently (compared to their last + seen email). + + + It can also happen if the key wasn't seen first-hand from + the sender. Autocrypt has a feature where recipient keys + can be included in group-encrypted emails. This allows you + to reply to a conversation where you don't have a key + first-hand from one of the other recipients. However, those + keys are not trusted as much as from first-hand emails, so + the engine warns you with a Discouraged + status. + + + + + Available means a key was found for every + recipient, and the engine believes all keys are recent and + seen from the recipient first hand. However, either you or + one of the recipients chose not to specify prefer + encryption. + + + + + Yes is the same as + Available, with the addition that you and + all recipients have specified prefer encryption. + This value will automatically enable + encryption, unless you have manually switched it off or + enabled regular encryption or signing via the + <pgp-menu>. + + + + + As mentioned above the <autocrypt-menu> + function, by default bound to o, can be used + to change the Encrypt: field value. + (e)ncrypt will toggle encryption on. + (c)lear will toggle encryption off. If + either of these are chosen, the field will remain in that state + despite what the Recommendation: field shows. + Lastly, (a)utomatic will set the value based + on the recommendataion engine's output. + + + Autocrypt encryption defers to normal encryption or signing. + Anything that enables normal encryption or + signing will cause autocrypt encryption to turn off. The only exception is + when replying to an autocrypt-encrypted email. In those cases, autocrypt + will override settings + $crypt_autosign, + $crypt_autoencrypt, + $crypt_replyencrypt, + $crypt_replysign, + $crypt_replysignencrypted, and + $crypt_opportunistic_encrypt. + + + When postponing a message, autocrypt will respect + $postpone_encrypt, but will + use the autocrypt account key to encrypt the message. Be sure + to set $postpone_encrypt + to ensure postponed messages marked for autocrypt encryption are + encrypted. + + + + + Account Management + + The Autocrypt Account Menu is available from the index via + <autocrypt-acct-menu>, by default bound + to A. See Autocrypt Account Menu for the + list of functions and their default keybindings. + + + In this menu, you can create new accounts, delete accounts, + toggle an account active/inactive, and toggle the prefer + encryption flag for an account. + + + Deleting an account only removes the account from the database. + The GPG key is kept, to ensure you still have the ability to + read past encrypted emails. + + + The Autocrypt 1.1 Setup Message feature is not + available yet, but will be added in the future. + + + diff --git a/init.h b/init.h index 03f05ec72..d4191a99b 100644 --- a/init.h +++ b/init.h @@ -394,9 +394,10 @@ struct ConfigDef MuttVars[] = { { "autocrypt", DT_BOOL, &C_Autocrypt, false }, /* ** .pp - ** When \fIset\fP, enables autocrypt, https://autocrypt.org/, which provides + ** When \fIset\fP, enables autocrypt, which provides ** passive encryption protection with keys exchanged via headers. - ** TODO: add a section in the manual describing this is more detail. + ** See ``$autocryptdoc'' for more details. + ** (Autocrypt only) */ { "autocrypt_acct_format", DT_STRING|R_MENU, &C_AutocryptAcctFormat, IP "%4n %-30a %20p %10s" }, /* @@ -411,12 +412,14 @@ struct ConfigDef MuttVars[] = { ** .dt %s .dd status flag (active/inactive) ** .de ** .pp + ** (Autocrypt only) */ { "autocrypt_dir", DT_STRING|DT_PATH, &C_AutocryptDir, IP "~/.mutt/autocrypt" }, /* ** .pp ** This variable sets where autocrypt files are stored, including the GPG - ** keyring and sqlite database. + ** keyring and sqlite database. See ``$autocryptdoc'' for more details. + ** (Autocrypt only) */ #endif { "autoedit", DT_BOOL, &C_Autoedit, false }, -- 2.40.0