This document describes the basic capabilities required for a mail app (MUA) to be Autocrypt-capable at Level 0. The design of Level 0 is driven by usability concerns and by the realities of incremental deployment. A user may use both Autocrypt-enabled mail apps and traditional plain ones and we’d like to avoid annoyances like unexpected unreadable mails while supporting users who want to explicitly turn on encryption.
For ease of implementation and deployment, Level 0 does not support multi-device configurations. We intend to support the multi-device use case (and other features) as part of Level 1. We want to keep Level 0 minimal enough that it’s easy for developers to adopt it and we can start to drive efforts from real-life experiences as soon as possible.
Throughout this document, we refer to a mail app or Mail User Agent (MUA) as though it was only capable of controlling a single e-mail account. An MUA that is capable of connecting to multiple e-mail accounts should have a separate Autocrypt state for each e-mail account it has access to.
- Autocrypt Level 0: Enabling encryption, avoiding annoyances
- Requirements on MUA/E-mail Provider interactions
- Secret key generation and storage
- Avoiding Client Conflicts
- Secret Key Transfer
- Header injection in outbound mail
- Deriving a Parsed Autocrypt Header from a Message
- Internal state storage
- Updating internal state upon message receipt
- Provide a recommendation for message encryption
- Encrypt outbound mail as requested
- Specific User Interface Elements
Autocrypt tries to impose minimal requirements on how MUAs and e-mail services interact. We assume that an Autocrypt-capable MUA has credentials and capabilities to perform these network services:
- The ability to send e-mail (e.g. via SMTP or Submission) where the MUA can control the entire message being sent, including both message headers and message body.
- The ability to receive e-mail where the MUA gets access to the entire message being received, including both message headers and message body.
- Optionally, a way to scan the user’s Sent folder for mail with specific headers.
Discuss with webmail developers how to work with, refine the interactions.
The MUA MUST be capable of generating and storing two RSA 2048-bit secret keys, one for signing and self-certification and the other for decrypting. It MUST be capable of assembling these keys into an OpenPGP certificate (RFC 4880 “Transferable Public Key”) that indicates these capabilities.
The secret key material is critical for security as in other end-to-end applications, and should be protected from access by other applications or co-tenants of the device, at least as well as the passwords the MUA retains for the user’s IMAP or SMTP accounts.
If more than one Autocrypt-enabled client generates a key and then distributes it to communication peers, encrypted mail sent to the user is only readable by the MUA that sent the last message. This can lead to behavior that is unpredictable and confusing for the user.
As a simple measure of mitigation, Level 0 MUAs SHOULD check before key generation whether there is evidence in the user’s mailbox of other active Autocrypt clients. To do this, they SHOULD scan the user’s Sent folder for mail that contains Autocrypt headers. If such mail exists, the MUA SHOULD warn the user and abort key generation, unless explicitly instructed to proceed regardless.
In cases where this mechanism cannot be provided, the MUA MUST inform the user that they should only set up one Autocrypt client.
To solve this problem in a better way, bi-directional communication between the user’s different MUAs is required. However, this is out of scope for Level 0.
Although bi-directional communication between different MUAs is out of scope for Level 0, self-sent email is used as a simple way to transfer secret key material to other clients. A Level 0 client SHOULD support this mechanism, to make sure that secret keys are never stuck on the device they were generated on, but can be retrieved by other Autocrypt clients in a predictable way.
- create self-sent message
- contains secret key
- symmetric encryption format
- high-entropy passphrase - bit strength? - is s2k sufficient for a kdf? or scrypt on top? - must not end up in the user’s mail store!!
- message format - attachment? something else?
- message text
During message composition, if the From: header of the
outgoing e-mail matches an address that the Autocrypt-capable agent
knows the secret key material for, it SHOULD include an Autocrypt
header. This header contains the associated public key material as
key= attribute, and the same sender address that is used in the
From header in the
to= attribute to confirm the
association. The most minimal Level 0 MUA will only include these two
If the From: address changes during message composition (E.g. if the user selects a different outbound identity), the Autocrypt-capable client MUST change the Autocrypt header appropriately.
See “Happy path” example: 1:1 communication for examples of outbound headers and the following sections for header format definitions and parsing.
The Autocrypt header has the following format:
Autocrypt: firstname.lastname@example.org; [type=p;] [prefer-encrypted=(yes|no);] key=BASE64
to attribute indicates the single recipient address this
header is valid for. In case this address differs from the one the MUA
considers the sender of the e-mail in parsing, which will usually be
the one specified in the From header, the entire header
MUST be treated as invalid.
key attributes specify the type and data of the
key material. For now the only supported type is
represents a specific subset of OpenPGP (see the next section), and is
also the default. Headers with an unknown
type MUST be treated as
invalid. The value of the
key attribute is a Base64
representation of the public key material. For ease of parsing, the
key attribute MUST be the last attribute in the header.
prefer-encrypted attribute indicates whether agents should
default to encrypting when composing e-mails to this recipient. If
prefer-encrypted is not set, the value of
prefer-encrypted is set, but neither
no, the MUA must skip the header as invalid.
Additional attributes unspecified here are also possible before the
key attribute. If an attribute name starts with an underscore
_), it is a “non-critical” attribute. An attribute name without
a leading underscore is a “critical” attribute. The MUA SHOULD ignore
any unsupported non-critical attribute and continue parsing the rest
of the header as though the attribute does not exist, but MUST treat
the entire header as invalid if it encounters a “critical” attribute
it doesn’t support.
When parsing an incoming message, a MUA MUST examine all Autocrypt headers, rather than just the first one. If there is more than one valid header, this MUST be treated as an error, and all Autocrypt headers discarded as invalid.
- Document why we skip on more than one valid header?
For maximum interoperability, a certificate sent by an Autocrypt-enabled Level 0 MUA MUST consist of an OpenPGP “Transferable Public Key”) containing exactly these five OpenPGP packets:
- a signing-capable primary key
- a user id
- a self signature
- an encryption-capable subkey
- a binding signature over
The content of the user id packet is only decorative. By convention, it
contains the same address used in the
to attribute in angle brackets,
conforming to the RFC 2822 grammar
These packets MUST be assembled in binary format (not ASCII-armored), and then base64-encoded.
A Level 0 MUA MUST be capable of processing and handling 2048-bit RSA
keys. It SHOULD be capable of handling Curve 25519 keys (ed25519 for
Kp and cv25519 for
Ke), but some underlying toolkits may not
yet support Curve 25519. It MAY support other OpenPGP key formats.
You should be familiar with “Happy path” example: 1:1 communication before reading the following.
If a remote peer disables Autocrypt or drops back to using a non-Autocrypt MUA only we must be able to disable sending encrypted mails to this peer automatically. MUAs capable of Autocrypt level 0 therefore MUST store state about the capabilities of their remote peers.
Agents MAY also store additional information gathered for heuristic purposes, or for other cryptographic schemes. However, in order to support future syncing of Autocrypt state between agents, it is critical that Autocrypt-capable agents maintain the state specified here.
Conceptually, we represent this state as a table named
autocrypt_peer_state indexed by the peer’s canonicalized
e-mail address and key type. In level 0,
there is only one type,
p, so level 0 agents can implement this by
indexing only the peer’s e-mail address.
For each e-mail and type, an agent MUST store the following attributes:
pah: Parsed Autocrypt Header, which could be
changed: UTC Timestamp when
pahwas last changed
last_seen: Most recent UTC time that
Autocrypt-compatible agents SHOULD track and store in
autocrypt_peer_state a parsed interpretation
pah, which is not
necessarily the literal header emitted (for the literal header, see
next section). The
pah MUST contain the following fields:
key: the raw key material, after base64 decoding
prefer_encrypted: a quad-state:
Optionally, an agent MAY store and maintain the following data in order to provide clearer feedback to the user:
counting_since: The UTC timestamp of when we started counting
count_have_ach: A count of parsed AutoCrypt headers
count_no_ach: A count of messages without AutoCrypt headers
bad_user_agent: The apparent user-agent (if known) of the last message seen without AutoCrypt headers.
These attributes are all optional, and are presented here as a recommendation of the type of data an AutoCrypt capable user-agent might record in order to provide the user with more detailed feedback and guidance when we detect a potential conflict.
The theory is that a message of the form “The recipient may not be able to read encrypted mail” could be augmented with reasons such as “The last 5 messages we saw from them all came from a non-AutoCrypt capable e-mail application”, or “Their most recent message was sent on April 5th using Apple Mail on an iPad.”
This is not an exhaustive list; implementors are encouraged to improve upon this scheme as they see fit.
When first encountering an incoming e-mail
M from an e-mail
A, the MUA should follow the following
- Set a local
message_dateto the Date: header of
message_dateis in the future, set
message_dateto the current time.
This implies that Autocrypt clients keep track of whether they have encountered a given message before, but does not provide them with guidance on how to do so. Message-ID? Digest of full message body? The consequences of re-triggering the message receipt process should only matter for messages that are erroneously marked with a future date. Another approach that would not require keeping track of the message would be to simply ignore messages whose Date: header is in the future.
- Set a local
message_pahto be the Autocrypt:
- header in
M. This is either a single Parsed Autocrypt Header, or
- Set a local
The agent continues this message receipt process even when
null, since updating the stored state with
null is sometimes the correct action.
- OPTIONAL: If
null, and the MUA knows about additional OpenPGP keys and the message is cryptographically signed with a valid, verifiable message signature from a known OpenPGP certificate
K, then we may replace
synthesized_pahgenerated from the message itself:
Kis not encryption-capable (i.e. if the primary key has no encryption-capabilities marked, and no valid subkeys are encryption-capable), or if K does not have an OpenPGP User ID which contains the e-mail address in the message’s
- Otherwise, with an encryption-capable
synthesized_pahis set to
synthesized_pahis set to
Kis encryption-capable and one of the message headers is an OpenPGP header which expresses a preference for encrypted e-mail, the
synthesized_pahshould be set to
This behaviour is optional: MUAs which support non-Autocrypt OpenPGP
workflows may have other strategies they prefer. Implementing the
synthesized_pah is not necessary to guarantee correct interop
with other Autocrypt implementations, but it will improve compatibility
with the rest of the OpenPGP ecosystem and is therefore presented here
as a suggestion.
We do not synthesize the Autocrypt header from any
application/pgp-keys message parts. This is because it’s
possible that an attached OpenPGP key is not intended to be the
sender’s OpenPGP key. For example, Alice might send Bob Carol’s
OpenPGP key in an attachment, but Bob should not interpret it as
- Maybe move
synthesized_pahinto Interoperability With Other Cryptographic E-mail Mechanisms ?
- Can we synthesize from attached keys, e.g. if it has a matching user id?
counting_sinceis unset, set it to the current time. Otherwise, if
message_dateis greater than
Next, the agent compares the
autocrypt_peer_statehas no record at all for address
A, the MUA sets
message_date, and then terminates this receipt process.
last_seengreater than or equal to
message_date, then the agent terminates this receipt process, since it already knows about something more recent. For example, this might be if mail is delivered out of order, or if a mailbox is scanned from newest to oldest.
message_date, then we compare
pahcurrently stored in
This is done as a literal comparison using only the
prefer_encryptfields, even if the Agent stores additional fields as an augmentation, as follows:
null, or if
keyis bytewise different, or if
prefer_encryptedhas a different value, then this is an update.
prefer_encryptedmatch exactly, then it is considered a match.
- If both
null, it is a match.
pahis not), it is a reset.
In the case of a match, set
In the case of an update:
In the case of a reset:
OPTIONAL in the case of a reset:
autocrypt_peer_state[A].bad_user_agentto the apparent user-agent of the message
OPTIONAL in the case of a reset AND
counting_sinceis more than a month older than
The above algorithm results in a non-deterministic
autocrypt_peer_state if two Autocrypt headers are processed
using the same
message_date (depending on which message is
encountered first). For consistency and predictability across
implementations, it would be better to have a strict ordering
between parsed Autocrypt headers, and to always select the lower
header in case of equal values of
OpenPGP’s composable certificate format suggests that there could
be alternate ways to compare
key values besides strict bytewise
comparison. For example, this could be done by comparing only the
fingerprint of the OpenPGP primary key instead of the keydata.
However, this would miss updates of the encryption-capable subkey,
or updates to the capabilities advertised in the OpenPGP
self-signature. Alternately, the message receipt process could
incorporate fancier date comparisons by integrating the timestamps
within the OpenPGP messages during the date comparison step. For
simplicity and ease of implementation, level 0 Autocrypt-capable
agents are expected to avoid these approaches and to do full
bytestring comparisons of
key data instead.
the spec currently doesn’t say how to integrate Autocrypt processing on message receipt with spam filtering. Should we say something about not doing Autocrypt processing on message receipt if the message is believed to be spam?
On message composition, an Autocrypt-capable agent also has an opportunity to decide whether to try to encrypt an e-mail. Autocrypt aims to provide a reasonable recommendation for the agent.
Any Autocrypt-capable agent may have other means for making this decision outside of Autocrypt (see Interoperability With Other Cryptographic E-mail Mechanisms). Autocrypt provides a recommendation to this process, but there is no requirement for Autocrypt-capable agents to always follow the Autocrypt recommendation.
That said, all Autocrypt-capable agents should be able to calculate the same Autocrypt recommendation due to their internal state.
The Autocrypt recommendation depends on the list of recipient addresses for the message being composed. When the user edits the list of recipients, the recommendation may change. The MUA should reflect this change.
It’s possible that the user manually overriddes the Autocrypt recommendation and then edits the list of recipients. The MUA SHOULD retain the user’s manual choices for a given message even if the Autcrypt recommendation changes.
Discuss how to deal with the case where the user manually selects encryption and subsequently adds a recipient whom the MUA has no key.
Autocrypt can produce four possible recommendations to the agent during message composition:
disable: Disable or hide any UI that would allow the user to choose to encrypt the message. Prepare the message in cleartext.
discourage: Enable UI that would allow the user to choose to encrypt the message, but do not default to encryption. Prepare the message in cleartext. If the user manually enables encryption, warn them that the recipient may not be able to read the message.
available: Enable UI that would allow the user to choose to encrypt the message, but do not default to encryption. Prepare the message in cleartext.
encrypt: Enable UI that would allow the user to choose to send the message in cleartext, and default to encryption. Prepare the message as an encrypted message.
For level 0 MUAs, the Autocrypt recommendation for message composed to
a single recipient with e-mail address
A is derived from the value
null, or if
pah.key is known to be unusable
for encryption (e.g. it is otherwise known to be revoked or expired),
then the recommendation is
pah is not
the message being composed is a reply to an encrypted message, then
the recommendation is
pah is not
then the recommendation is
pah is not
prefer-encrypted is either
nopreference, then the recommendation is
For level 0 agents, the Autocrypt recommendation for a message composed to multiple recipients is derived from the recommendations for each recipient individually.
If any recipient has a recommendation of
disable then the message
If the message being composed is a reply to an encrypted message, or
if every recipient other than “myself” (the e-mail address that the
From:) has a recommendation of
encrypt then the
message recommendation is
If any recipient has a recommendation of
discourage then the message
Otherwise, the message recommendation is
As you can see above, in the common use case, a reply to an encrypted
message will also be encrypted. Due to Autocrypt’s opportunistic
approach, however, it’s possible that
null for some
recipient, which means the reply will be sent in the clear.
To avoid leaking cleartext from the original encrypted message in this case, the MUA MAY prepare the cleartext reply without including any of the typically quoted and attributed text from the previous message. Additionally, the MUA MAY include brief text in message body along the lines of:
The message this is a reply to was sent encrypted, but this reply is unencrypted because I don't yet know how to encrypt to ``email@example.com``. If ``firstname.lastname@example.org`` would reply here, my future messages in this thread will be encrypted.
The above recommendations are only “MAY” and not “SHOULD” or “MUST” because we want to accomodate a user-friendly level 0 MUA that stays silent and does not impede the user’s ability to reply. Opportunistic encryption means we can’t guarantee encryption in every case.
As the user composes mail, in some circumstances, the MUA may be
instructed by the user to encrypt the message. If the recipient’s
keys are all of
type=p, and the sender has keys for all recipients
(as well as themselves), they should construct the encrypted message
as a PGP/MIME encrypted+signed message, encrypted to all
recipients and the public key whose secret is controlled by the MUA
If the recommendation is
discourage the user SHOULD be presented
with a clear warning explaining that there is reason to believe one or
more recipients will not be able to read the mail if it is sent
encrypted. This message SHOULD state which recipients are considered
problematic and provide useful information to help the user guage the
risk. The optional counters and user-agent state are intended for this.
For messages that are going to be encrypted when sent, the MUA MUST take care not to leak the cleartext of drafts or other partially-composed messages to their e-mail provider (e.g. in the “Drafts” folder).
If there is a chance that a message could be encrypted, the MUA SHOULD encrypt drafts only to itself before storing it remotely.
Ideally, Autocrypt users see very little UI. However, some UI is inevitable if we want users to be able to interoperate with existing, non-Autocrypt users.
Level 0 MUAs MUST allow the user to disable Autocrypt completely for each account they control. For level 0, we expect most MUAs to have Autocrypt disabled by default.
If Autocrypt is enabled for a given account, the MUA SHOULD allow the user to specify whether they explicitly prefer encryption for inbound messages, or explicitly prefer cleartext for inbound messages, or choose to express no preference. The default SHOULD be “no preference”.
Please see Example User Interface for Autocrypt for specific examples of how this might look.
If an MUA is willing to compose encrypted mail, it SHOULD include some UI mechanism at message composition time for the user to choose between encrypted message or cleartext. This may be as simple as a single checkbox.
If the Autocrypt recommendation is
disable for a given message,
the MUA MAY choose to avoid exposing this UI during message
composition at all.
If the Autocrypt recommendation is either
encrypt, the MUA SHOULD expose this UI during message composition
to allow the user to make a different decision.
- Should we really recommend hiding the encrypt UI? This reduces UI consistency!