52. pepsi-stage-autocrypt-learn

Learn correspondents’ keys from the mail they send us.

52.1. Role

pepsi-stage-autocrypt-learn is where Pepsi learns public keys from inbound mail. It reads the sender’s Autocrypt: header, an attached application/pgp-keys part, the certificate that made an S/MIME signature over the message and, for a message that arrived encrypted, the Autocrypt-Gossip: fields that introduce the other recipients (Autocrypt Level 1 §5.3). It learns and advances; it never drops, pauses, bounces or rewrites a message, so NEXT_STAGE is mandatory. Reference: pepsi-stage-autocrypt-learn(1).

52.2. Features

  • Placement. It runs after the spam checks and before delivery, because Level 1 §5.3 says peer state SHOULD be ignored for a message believed to be spam, and that can only be honoured once a spam verdict exists. pepsi-stage-decrypt runs first on the inbound path, so that everything downstream sees plaintext; at that point no stage has yet judged whether the message is junk.

  • Honours the spam verdict: the stage learns nothing from a message with state.spam = true, unless LEARN_FROM_SPAM says otherwise.

  • Only the sender’s own key: from a message’s headers and attachments, the stage learns only the sender’s key. Introducing a third party is what gossip is for, and a gossiped key lands on a lower rung.

  • Only a certificate that signed: an S/MIME certificate is learnt when a SignerInfo of the message verifies under its key over the signed content, never because a SignedData carries it. It lands on inbound-signed when DMARC passed at ingress or an aligned, passing DKIM signature covered the body, and on inbound otherwise; a certificate from unauthenticated mail never replaces one from authenticated mail.

  • Gossip only from ciphertext: gossip is believed only when pepsi-stage-decrypt recorded that the message arrived encrypted and that its arriving header block carried no Autocrypt-Gossip: field of its own. Neither is visible from the committed plaintext, so both are read from state.crypto.in.

  • Never a key for an address this host serves: a peer key for a local address is what our own outbound mail to that user would be encrypted with, so a gossip field naming one is a key substitution rather than an introduction.

  • Records that a correspondent holds our key: when a message was decrypted with one of our MTA keys and carries a valid signature by its From: address covering the plaintext, a pepsi.peer_has_own_key row is written, so pepsi-stage-encrypt stops attaching that key as a file (ATTACH_KEYS_AS_FILES). This happens whatever LEARN_KEYS and the spam verdict say, since it concerns our key, not theirs.

  • Records what a correspondent’s S/MIME client reads: the RFC 8551 SMIMECapabilities a verified signature carries are recorded per signing certificate in pepsi.smime_capability, from which pepsi-stage-encrypt and pepsi-stage-reencrypt choose AES-GCM AuthEnvelopedData or AES-CBC EnvelopedData for that peer; a record set by hand (pepsi-keys peer capability set) wins over a learnt one. See Which S/MIME container a correspondent gets.

  • Refuses known-compromised keys: a key on the badkeys blocklist or in pepsi.compromised_key is never stored, and the stage learns no key from a message that offers more than eight keys for its sender.

  • Key changes are never silent: when a correspondent’s key is replaced under the newest-wins rule, the stage writes a key.peer.rotate audit row and, with RESPONSE_STAGE set, mails the message’s local recipients a notice. The notice shows both fingerprints as hex and as PGP words, the new key’s trust rung and the pin command that records a comparison (A user’s own pin). ACCEPT_ROTATION = expired instead holds a new key until the stored one is dead. A gossiped key that its owner later advertises themselves is promoted to the inbound rung.

  • Unprivileged: it writes only public key material, so unlike the crypto stages it needs no setuid bit and is folded into the multi-call pepsi binary.

52.3. Configuration

LEARN_KEYS (default yes; off makes the stage learn no key at all), LEARN_GOSSIP (default yes, and only meaningful while LEARN_KEYS is on), LEARN_FROM_SPAM (default no, which follows Autocrypt Level 1 §5.3’s SHOULD), ACCEPT_ROTATION (newest, the default, or expired: replace a correspondent’s stored key only once every stored key for the address is revoked or expired), the optional RESPONSE_STAGE (where the notices telling local recipients that a correspondent’s key changed are injected; without it a change is only logged and audited as key.peer.rotate), the locality options LOCAL_DOMAINS (defaulting to [pepsi-ingress] ACCEPTED_DOMAINS), TARGETS and RECIPIENT_DELIMITER, which serve to refuse gossip about local users and to pick the local recipients to notify, and a mandatory NEXT_STAGE. The whole message is loaded, since the key material is in it. See Configuration.

[stage-autocrypt-learn]
PROGRAM = pepsi-stage-autocrypt-learn
NEXT_STAGE = local

52.4. What a learnt key is worth

A learnt key is deliberately worth little. Harvested keys sit at rank inbound-signed (when a passing DKIM signature aligned with From: covered them, or, for an S/MIME certificate that signed, DMARC passed) or inbound, and gossiped ones at gossip. These are the bottom three rungs of the trust ladder. Such a key can never displace one from discovery or from an operator; a signature checked against one is reported valid-untrusted at best, so it never sets state.signature_verified; and a peer_key row is ignored entirely for an address for which this host holds an identity. Within one of those rungs the rule is newest wins on the message’s Autocrypt effective date (a key from a lower rung never replaces one from a higher), so a correspondent who reinstalls their client stops receiving mail encrypted to a key that they no longer hold. This protects against a passive adversary, which is all that Autocrypt claims. Keys of correspondents states what such keys are trusted for.

52.5. See also

pepsi-stage-decrypt, pepsi-stage-encrypt, pepsi-keydisc, pepsi-keys, Key management, Which S/MIME container a correspondent gets, Keys of correspondents, pepsi-stage-autocrypt-learn(1).