Add autocrypt documentation about shared key and keyring strategies

diff --git a/doc/manual.xml.head b/doc/manual.xml.head
index c84ac0be4bb3feb080a6a335b37b5d496ff4dd12..f5dcb3baa5c95deafda8bd84522744e205b426a6 100644 (file)
--- a/doc/manual.xml.head
+++ b/doc/manual.xml.head
@@ -17626,6 +17626,65 @@ bind index D purge-message
           available yet, but will be added in the future.
         </para>
       </sect2>
+
+      <sect2 id="autocryptdoc-keyrings">
+        <title>Alternative Key and Keyring Strategies</title>
+        <para>
+          Mutt by default partitions Autocrypt from normal keyring
+          encryption/signing.  It does this by using a separate GPG
+          keyring (in <link linkend="autocrypt-dir">$autocrypt_dir</link>)
+          and creating a new ECC key in that keyring for accounts.  There
+          are good reasons for doing this by default.  It keeps random
+          keys found inside email headers out of your normal keyring.  ECC
+          keys are compact and better suited for email headers.  Autocrypt
+          key selection is completely different from <quote>web of
+          trust</quote> key selection, based on last-seen rules as opposed
+          to trust and validity.  It also allows Mutt to distinguish
+          Autocrypt encrypted emails from regular encrypted emails, and
+          set the mode appropriately when replying to each type of email.
+        </para>
+        <para>
+          Still, some users may want to use an existing key from their
+          normal keyring for Autocrypt too.  There are two ways this can
+          be accomplished: by copying the key over to the Autocrypt
+          keyring, or by pointing <link
+          linkend="autocrypt-dir">$autocrypt_dir</link> at your normal
+          keyring directory (e.g. <literal>~/.gnupg</literal>).  The first
+          can be done using gpg from the command line, along the lines of
+          <literal>gpg --export [keyid] | gpg --homedir=~/.mutt/autocrypt
+          --import</literal> followed by <literal>gpg --export-secret-keys
+          [keyid] | gpg --homedir=~/.mutt/autocrypt --import</literal>.
+          Once this is done, choosing <quote>(s)elect existing GPG
+          key</quote> during account creation will list and allow
+          selecting that key for the account.
+        </para>
+        <para>
+        Copying your key over has the advantage of keeping Autocrypt keys
+        out of your normal keyring, but there is a downside.  Mutt
+        <emphasis>first</emphasis> tries to decrypt messages using the
+        Autocrypt keyring, and if that fails tries the normal keyring
+        second.  This means all encrypted emails to that key will be
+        decrypted, and have signatures verified from, the Autocrypt
+        keyring.  Keys signatures and web of trust from your normal
+        keyring will no longer show up in signatures when decrypting.
+        </para>
+        <para>
+          Pointing <link linkend="autocrypt-dir">$autocrypt_dir</link> to
+          <literal>~/.gnupg</literal> allows Autocrypt header keys to be
+          imported there, but also allows <quote>web of trust</quote> to show
+          an appropriate signature message for verified messages.
+        </para>
+        <para>
+          Both methods have one additional caveat: replying to an
+          Autocrypt decrypted message by default forces Autocrypt mode on.
+          By sharing the same key, all replies will then start in
+          Autocrypt mode, even if the message wasn't sent by one of your
+          Autocrypt peers.  <link
+          linkend="autocrypt-reply">$autocrypt_reply</link> can be
+          <emphasis>unset</emphasis> to allow manual control of the mode
+          when replying.
+        </para>
+      </sect2>
     </sect1>
   </chapter>