Add autocrypt documentation about shared key and keyring strategies.

diff --git a/doc/manual.xml.head b/doc/manual.xml.head
index 7896e5fb3c6ec3d12c3d51ca5977b533523d5f7c..f3984aa279d282b28a25700283d5c8f06f564d94 100644 (file)
--- a/doc/manual.xml.head
+++ b/doc/manual.xml.head
@@ -9838,6 +9838,65 @@ please have a look at the mixmaster documentation.
       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>