formatting, minor cleanup (use :rfc: and :mailheader: where possible)

doc/cleanup.rst

@@ -1,15 +1,12 @@
 Cleanup needed
 --------------
 
-RFC 2231 talks about the elements of a MIME header as "parameters"
-instead of "attributes".  RFC 2045 specifies the same vocab.  We
+:rfc:`2231` talks about the elements of a MIME header as "parameters"
+instead of "attributes".  :rfc:`2045` specifies the same vocab.  We
 should normalize.
 
 Let's use "cert" where we mean "cert" and "key" where we mean "key"
 
-need a tight document for what is expected of level 0 clients
-(level0.rst).
-
 user-facing material probably should use "app" -- for technical
 documentation, we need to settle internally on "agent" or "client" or
 "MUA" or "MUAA"

doc/ecosystem-dangers.rst

@@ -24,9 +24,9 @@ communication.
 Message Deliverability
 ----------------------
 
-Autocrypt headers that use RSA 2048 are large enough that, when
-unwrapped, they exceed the SMTP line length limit of 1000 ASCII
-characters.
+:mailheader:`Autocrypt` headers that use RSA 2048 are large enough
+that, when unwrapped, they exceed the SMTP line length limit of 1000
+ASCII characters.
 
 It's conceivable that some MTAs or MUAs will choke upon trying to deal
 with these headers, and render the message undeliverable or
@@ -52,11 +52,11 @@ Autocrypt-capable client.
 
 Mallory crafts a new key K.  She can throw away the secret key
 material entirely if she wants to.  She then forges an e-mail from
-Alice and adds an Autocrypt header to it containing that public key and
-`prefer-encrypted=yes`.  If Bob writes a message to Alice after
-receiving that key, and before receiving any other legitimate message
-to Alice, his message will be encrypted to a key that Alice cannot
-read.
+Alice and adds an :mailheader:`Autocrypt` header to it containing that
+public key and `prefer-encrypted=yes`.  If Bob writes a message to
+Alice after receiving that key, and before receiving any other
+legitimate message to Alice, his message will be encrypted to a key
+that Alice cannot read.
 
 this represents a risk to Alice, even if she has never adopted an
 Autocrypt-capable client in the first place.
@@ -70,7 +70,7 @@ Mitigations:
 
  - we should specify that any spam/malware flag set from a filter that
    the user trusts should be sufficient to discourage processing of
-   Autocrypt headers, so that Mallory needs to craft a
+   :mailheader:`Autocrypt` headers, so that Mallory needs to craft a
    sufficiently-plausible message (including DKIM and whatever other
    indicators the filters care about) to make it into the
    Autocrypt-capable agent's internal state storage.

doc/examples.rst

@@ -33,15 +33,16 @@ Basic network protocol flow
 
 Establishing encryption happens as a side effect when people send each other mail:
 
-- A MUA (mail user agent) always adds an ``Autocrypt:`` header to all messages it
-  sends out.
+- A MUA (mail user agent) always adds an :mailheader:`Autocrypt:`
+  header to all messages it sends out.
 
-  The autocrypt header contains all necessary information to allow encryption
-  (especially the key; see :ref:`autocryptheaderformat` for the format in detail).
+  The :mailcrypt:`Autocrypt:` header contains all necessary
+  information to allow encryption (especially the key; see
+  :ref:`autocryptheaderformat` for the format in detail).
 
 - A MUA will scan incoming mails for encryption headers and associate
-  the info with a canonicalized version of the ``From:`` address contained
-  in the :rfc:`822` message.
+  the info with a canonicalized version of the :mailheader:`From:`
+  address contained in the :rfc:`822` message.
 
 - A MUA will encrypt a message if it earlier saw encryption keys
   (and the request to encrypt) for all recipients.
@@ -65,27 +66,30 @@ encryption key::
 
     Autocrypt: to=alice@a.example; type=p; prefer-encrypted=yes; key=...
 
-Bob's MUA will scan the incoming mail, find Alice's key and store it associated
-to the ``alice@a.example`` address taken from the ``to``-attribute.
-When Bob now composes a mail to Alice his MUA will find the key and signal to
-Bob that the mail will be encrypted and after finalization of the mail encrypt
-it.  Moreover, Bob's MUA will add its own Encryption Info::
+Bob's MUA will scan the incoming mail, find Alice's key and store it
+associated to the ``alice@a.example`` address taken from the
+``to``-attribute.  When Bob now composes a mail to Alice his MUA will
+find the key and signal to Bob that the mail will be encrypted and
+after finalization of the mail encrypt it.  Moreover, Bob's MUA will
+add its own encryption info::
 
     Autocrypt: to=bob@b.example; type=p; prefer-encrypted=yes; key=...
 
 When Alice's MUA now scans the incoming mail from Bob it will store
 Bob's key and the fact that Bob sent an encrypted mail.  Subsequently
 both Alice and Bob will have their MUAs encrypt mails to each other.
 
-If ``prefer-encrypted`` is sent as 'yes' the MUA MUST default to encrypting
-the next e-mail. If it is set as 'no' the MUA MUST default to plaintext.
-If ``prefer-encrypted`` is not sent the MUA should stick to what it was doing
-before. If the attribute has never been sent it's up to the MUA to decide. The
-safe way to go about it is to default to plaintext to make sure the recipient
-can read the e-mail.
+If ``prefer-encrypted`` is sent as ``yes`` the MUA MUST default to
+encrypting the next e-mail. If it is set as ``no`` the MUA MUST
+default to plaintext.  If ``prefer-encrypted`` is not sent the MUA
+should stick to what it was doing before. If the attribute has never
+been sent it's up to the MUA to decide. The safe way to go about it is
+to default to plaintext to make sure the recipient can read the
+e-mail.
 
-We encourage MUA developers to propose heuristics for handling the undirected
-case. We will document the best approaches to develop a shared understanding.
+We encourage MUA developers to propose heuristics for handling the
+undirected case. We will document the best approaches to develop a
+shared understanding.
 
 
 Group mail communication (1:N)
@@ -119,7 +123,8 @@ If Alice loses access to her decryption secret:
 
 - she lets her MUA generate a new key
 
-- her MUA will add an Autocrypt header containing the new key with each mail
+- her MUA will add an :mailheader:`Autocrypt` header containing the
+  new key with each mail
 
 - receiving MUAs will replace the old key with the new key
 
@@ -129,7 +134,7 @@ your mail") Bob's MUA will see the new key and subsequently use it.
 
 .. todo::
 
-    Check if we can encrypt a mime mail such that non-decrypt-capable clients
+    Check if we can encrypt a MIME e-mail such that non-decrypt-capable clients
     will show a message that helps Alice to reply in the suggested way.  We don't
     want people to read handbooks before using Autocrypt so any guidance we can
     "automatically" provide in case of errors is good.
@@ -145,8 +150,13 @@ your mail") Bob's MUA will see the new key and subsequently use it.
 Downgrading / switch to a MUA without Autocrypt support
 -------------------------------------------------------
 
-Alice might decide to switch to a different MUA which does not support Autocrypt.
+Alice might decide to switch to a different MUA which does not support
+Autocrypt.
 
-A MUA which previously saw an Autocrypt header and/or encryption from Alice
-now sees an unencrypted mail from Alice and no encryption header. This
-will disable encryption to Alice for subsequent mails.
+A MUA which previously saw an :mailheader:`Autocrypt` header and/or
+encryption from Alice now sees an unencrypted mail from Alice and no
+:mailheader:`Autocrypt` header. This will disable encryption to Alice
+for subsequent mails.
+
+Autocrypt relies on non-Autocrypt-capable MUAs to act as a sort of
+"reset" for the user in the case where they stop using Autocrypt.

doc/faq.rst

@@ -33,10 +33,10 @@ Why not use IMAP METADATA instead of specially-named folders?
 We ultimately want Autocrypt to be more generic than IMAP, to make it
 clear how other mail-checking protocols could work (e.g. MAPI, webmail
 interfaces) as long as they offer some sort of namespaced shared
-storage.  Using `IMAP METADATA <https://tools.ietf.org/html/rfc5464>`_
-would tie Autocrypt more tightly to IMAP, and would also limit the
-number of IMAP implementations that Autocrypt-enabled clients could
-connect to (METADATA is `not widely supported by today's IMAP server
+storage.  Using :rfc:`IMAP METADATA <5464>` would tie Autocrypt more
+tightly to IMAP, and would also limit the number of IMAP
+implementations that Autocrypt-enabled clients could connect to
+(METADATA is `not widely supported by today's IMAP server
 implementations <http://www.imapwiki.org/Specs>`_).
 
 If we wanted Autocrypt to use METADATA where it was available on the
@@ -85,9 +85,11 @@ If you really care about supporting other keys than what we use in
 Autocrypt there is the OpenPGP header that could use some standardization and
 automatic client support. Feel free to innovate there.
 
-If we want to enable multiple headers in the future we can still add Autocrypt
-headers with a critical attribute 'priority'. Versions that do not support it
-yet will drop these headers and fall back to the one without priority.
+If we want to enable multiple headers in the future we can still add
+:mailheader:`Autocrypt:` headers with a critical attribute
+``priority``. Versions that do not support it yet will ignore these
+headers as invalid and fall back to the one without a ``priority``
+attribute.
 
 
 Why do you use the ``to=`` attribute rather than the uid from the key?
@@ -126,14 +128,14 @@ adoption, not to re-invent the encryption mechanism itself.
 
 Please see `key-formats` for more discussion.
 
-Why don't you use the ``User-Agent`` header to detect different mail apps?
---------------------------------------------------------------------------
+Why don't you use the :mailheader:`User-Agent` header to detect different mail apps?
+------------------------------------------------------------------------------------
 
-Not all mail apps implement the ``User-Agent`` header (and there is an
-ongoing effort to discourage its use as a way to reduce metadata
-leakage).  Also, some mail apps are used only to read mail, and are
-not used to send at all, so the remote peer can't see anything about
-those specific apps.
+Not all mail apps implement the :mailheader:`User-Agent` header (and
+there is an ongoing effort to discourage its use as a way to reduce
+metadata leakage).  Also, some mail apps are used only to read mail,
+and are not used to send at all, so the remote peer can't see anything
+about those specific apps.
 
 We could encourage each MUA to publish a UUID to inform the remote
 peer that multiple mail apps are in use, but it's not clear that this
@@ -145,17 +147,18 @@ What about spammers accidentally downgrading encryption?
 
 A spammer who forges mail from a given address could potentially
 downgrade encryption for that person as a side effect.  Please see
-`level0/public-key-management` for details about expected interaction
-with spam filters.
+:ref:`the Level 0 documentation <spam-filters>` for details
+about expected interaction with spam filters.
 
 How does Autocrypt interact with today's mailing list managers?
 ---------------------------------------------------------------
 
 Mailing lists that distribute cleartext (unencrypted) mail may end up
-distributing their user's public key material in the ``Autocrypt:``
-headers of the distributed mail.  For mailing lists that rewrite
-``From:`` headers, these ``Autocrypt:`` headers will be dropped by
-recipients, which is fine.
+distributing their user's public key material in the
+:mailheader:`Autocrypt:` headers of the distributed mail.  For mailing
+lists that rewrite :mailheader:`From:` headers, these
+:mailheader:`Autocrypt:` headers will be dropped by recipients, which
+is fine.
 
 For encrypted mailing lists like `schleuder
 <http://schleuder2.nadir.org/>`_, we haven't done a full analysis yet.
@@ -206,11 +209,11 @@ sending different keys.
    by an agent you no longer use)
 
 
-Why do you clamp ``Date:`` to the current time?
------------------------------------------------
+Why do you clamp :mailheader:`Date:` to the current time?
+---------------------------------------------------------
 
-E-mail messages with ``Date:`` in the future could destroy the ability
-to update the internal state.
+E-mail messages with :mailheader:`Date:` in the future could destroy
+the ability to update the internal state.
 
 However, since different MUAs view messages at different times,
 future-dated e-mails could result in state de-synchronization.
@@ -219,7 +222,7 @@ future-dated e-mails could result in state de-synchronization.
 
    deeper analysis of this state de-sync issue with future-dated
    e-mails, or alternate, more-stable approaches to dealing with wrong
-   ``Date:`` headers.
+   :mailheader:`Date:` headers.
 
 Why do you always encrypt-to-self?
 ----------------------------------

doc/features.rst

@@ -9,10 +9,9 @@ To better understand how the Autocrypt effort is different
 from previous ones here are some of its features:
 
 - **Protect first against passive data-collecting adversaries**,
-  resist the temptation to early-add complexity which aim to
-  prevent active attacks.  See `RFC7435 A New Perspective
-  <https://tools.ietf.org/html/rfc7435#section-1.2>`_ for some
-  motivation of this and the next points.
+  resist the temptation to early-add complexity which aim to prevent
+  active attacks.  See :rfc:`RFC7435 A New Perspective
+  <7435#section-1.2>` for some motivation of this and the next points.
 
 - **Focus on incremental deployment**, always consider that there
   will be both Autocrypt-enabled mail apps and traditional plain ones,

doc/index.rst

@@ -37,10 +37,11 @@ The technical Autocrypt approach
 --------------------------------------
 
 Autocrypt uses regular e-mail messages between people to piggyback
-necessary information to allow encrypting subsequent messages; it
-adds a new ``Autocrypt`` e-mail header for transferring public keys and
-driving encryption behaviour. By default, key management is not visible
-to users. See :doc:`features` for more technical and UI cornerstones.
+necessary information to allow encrypting subsequent messages; it adds
+a new :mailheader:`Autocrypt` e-mail header for transferring public
+keys and driving encryption behaviour. By default, key management is
+not visible to users. See :doc:`features` for more technical and UI
+cornerstones.
 
 We are following this approach step-by-step using different "Levels"
 of implementation compliance.  Driven by usability concerns, we are