Add documentation for the autocrypt feature

Co-authored-by: Richard Russon <rich@flatcap.org>

diff --git a/doc/manual.xml.head b/doc/manual.xml.head
index 8d765b7b5e67258fc8bd40cfb5ce659208f8e269..b4e38238d86b0c5766ca992145d4dfdae62ab941 100644 (file)
--- a/doc/manual.xml.head
+++ b/doc/manual.xml.head
@@ -17367,6 +17367,258 @@ bind index D purge-message
         </itemizedlist>
       </sect2>
     </sect1>
+
+    <sect1 id="autocryptdoc">
+      <title>Autocrypt</title>
+    
+      <para>
+        Mutt can be compiled with Autocrypt support by running
+        <emphasis>configure</emphasis> with the
+        <emphasis>--enable-autocrypt</emphasis> flag.  Autocrypt provides
+        easy to use, passive protection against data collection.  Keys are
+        distributed via an <literal>Autocrypt:</literal> header added to
+        emails.  It does <emphasis>not</emphasis> 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 <ulink url="https://autocrypt.org/">https://autocrypt.org/</ulink>.
+      </para>
+    
+      <sect2 id="autocryptdoc-requirements">
+        <title>Requirements</title>
+        <para>
+          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.
+        </para>
+        <para>
+          Account and peer information is stored in a sqlite3 database, and
+          so Mutt must be configured with the <literal>--with-sqlite3</literal>
+          flag when autocrypt is enabled.
+        </para>
+        <para>
+          It is highly recommended Mutt be configured
+          <emphasis>--with-idn</emphasis> or
+          <emphasis>--with-idn2</emphasis> so that Autocrypt can properly
+          deal with international domain names.
+        </para>
+        <para>
+          While Mutt uses GPGME for Autocrypt, normal keyring operations
+          can still be performed via classic mode (i.e. with
+          <link linkend="crypt-use-gpgme">$crypt_use_gpgme</link> unset).
+          However, to avoid unnecessary prompts, it is recommended gpg not
+          be configured in <literal>loopback pinentry</literal> mode, and
+          that <link linkend="pgp-use-gpg-agent">$pgp_use_gpg_agent</link>
+          remain set (the default).
+        </para>
+      </sect2>
+    
+      <sect2 id="autocryptdoc-init">
+        <title>First Run</title>
+        <para>
+          To enable Autocrypt, set <link
+          linkend="autocrypt">$autocrypt</link>, and if desired change the
+          value of <link linkend="autocrypt-dir">$autocrypt_dir</link> in
+          your muttrc.  The first time Mutt is run after that, you will be
+          prompted to create
+          <link linkend="autocrypt-dir">$autocrypt_dir</link>.  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
+          <literal>700</literal>.  If you create the directory manually,
+          you should do the same.
+        </para>
+        <para>
+          Mutt recommends keeping the <link
+          linkend="autocrypt-dir">$autocrypt_dir</link> directory set
+          differently from your GnuPG keyring directory
+          (e.g. <literal>~/.gnupg</literal>).  Keys are automatically
+          imported into the keyring from <literal>Autocrypt:</literal>
+          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
+          <link linkend="crypt-opportunistic-encrypt">$crypt_opportunistic_encrypt</link>
+          and Autocrypt at the same time.
+        </para>
+        <para>
+          The <link linkend="autocrypt-dir">$autocrypt_dir</link> 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.
+        </para>
+        <para>
+          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 <literal>&lt;autocrypt-acct-menu&gt;</literal>
+          function in the index, by default bound to <literal>A</literal>.
+        </para>
+        <para>
+          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
+          <emphasis>both</emphasis> sender and receiver have set
+          <quote>prefer encryption</quote>.  Otherwise, you will need to
+          manually enable autocrypt encryption in the compose menu.  For
+          more details, see the compose menu section below.
+        </para>
+        <para>
+          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
+          <link linkend="header-cache">$header_cache</link> and opening a
+          mailbox.
+        </para>
+      </sect2>
+    
+      <sect2 id="autocryptdoc-compose">
+        <title>Compose Menu</title>
+        <para>
+          When enabled, Autocrypt will add a line to the compose menu with
+          two fields: <literal>Autocrypt:</literal> and
+          <literal>Recommendation:</literal>.
+        </para>
+        <para>
+          The <literal>Autocrypt:</literal> field shows whether the
+          message will be encrypted by Autocrypt when sent.  It has two
+          values: <literal>Encrypt</literal> and <literal>Off</literal>.
+          <literal>Encrypt</literal> can be enabled using the
+          <literal>&lt;autocrypt-menu&gt;</literal> function, by default
+          bound to <literal>o</literal>.
+        </para>
+        <para>
+          The <literal>Recommendation:</literal> field shows the output of
+          the Autocrypt recommendation engine.  This can have one of five
+          values:
+        </para>
+        <itemizedlist>
+          <listitem>
+            <para>
+              <literal>Off</literal> 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.
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>No</literal> 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.)
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>Discouraged</literal> 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).
+            </para>
+            <para>
+              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 <literal>Discouraged</literal>
+              status.
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>Available</literal> 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 <quote>prefer
+              encryption</quote>.
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>Yes</literal> is the same as
+              <literal>Available</literal>, with the addition that you and
+              all recipients have specified <quote>prefer encryption</quote>.
+              This value will automatically enable
+              encryption, unless you have manually switched it off or
+              enabled regular encryption or signing via the
+              <literal>&lt;pgp-menu&gt;</literal>.
+            </para>
+          </listitem>
+        </itemizedlist>
+        <para>
+          As mentioned above the <literal>&lt;autocrypt-menu&gt;</literal>
+          function, by default bound to <literal>o</literal>, can be used
+          to change the <literal>Encrypt:</literal> field value.
+          <literal>(e)ncrypt</literal> will toggle encryption on.
+          <literal>(c)lear</literal> will toggle encryption off.  If
+          either of these are chosen, the field will remain in that state
+          despite what the <literal>Recommendation:</literal> field shows.
+          Lastly, <literal>(a)utomatic</literal> will set the value based
+          on the recommendataion engine's output.
+        </para>
+        <para>
+          Autocrypt encryption defers to normal encryption or signing.
+          <emphasis>Anything</emphasis> 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
+          <link linkend="crypt-autosign">$crypt_autosign</link>,
+          <link linkend="crypt-autoencrypt">$crypt_autoencrypt</link>,
+          <link linkend="crypt-replyencrypt">$crypt_replyencrypt</link>,
+          <link linkend="crypt-replysign">$crypt_replysign</link>,
+          <link linkend="crypt-replysignencrypted">$crypt_replysignencrypted</link>, and
+          <link linkend="crypt-opportunistic-encrypt">$crypt_opportunistic_encrypt</link>.
+        </para>
+        <para>
+          When postponing a message, autocrypt will respect
+          <link linkend="postpone-encrypt">$postpone_encrypt</link>, but will
+          use the autocrypt account key to encrypt the message.  Be sure
+          to set <link linkend="postpone-encrypt">$postpone_encrypt</link>
+          to ensure postponed messages marked for autocrypt encryption are
+          encrypted.
+        </para>
+      </sect2>
+    
+      <sect2 id="autocryptdoc-acctmgmt">
+        <title>Account Management</title>
+        <para>
+          The Autocrypt Account Menu is available from the index via
+          <literal>&lt;autocrypt-acct-menu&gt;</literal>, by default bound
+          to <literal>A</literal>.  See <link
+          linkend="autocrypt-account-map">Autocrypt Account Menu</link> for the
+          list of functions and their default keybindings.
+        </para>
+        <para>
+          In this menu, you can create new accounts, delete accounts,
+          toggle an account active/inactive, and toggle the <quote>prefer
+          encryption</quote> flag for an account.
+        </para>
+        <para>
+          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.
+        </para>
+        <para>
+          The Autocrypt 1.1 <quote>Setup Message</quote> feature is not
+          available yet, but will be added in the future.
+        </para>
+      </sect2>
+    </sect1>
   </chapter>
 
   <chapter id="security">

diff --git a/init.h b/init.h
index 03f05ec72321a6dc15d54b74c94e7d5e3f125d91..d4191a99b3854a6266d67c7a81682761fd72ed1c 100644 (file)
--- 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 },