42. pepsi-stage-autocrypt-learn

Learn correspondents’ keys from the mail they send us.

42.1. Role

pepsi-stage-autocrypt-learn is where an inbound message teaches Pepsi a public key: the sender’s Autocrypt: header, an attached application/pgp-keys part, the certificates an S/MIME signature carries, and — for a message that arrived encrypted — the Autocrypt-Gossip: fields introducing 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).

42.2. Features

  • Placement is the feature. This used to live inside pepsi-stage-decrypt, which runs first on the inbound path so everything downstream sees plaintext — and therefore before any stage has an opinion about whether the message is junk. Level 1 §5.3 says peer state SHOULD be ignored for a message believed to be spam, so the rule was unimplementable there. As a stage of its own it goes after the spam checks and before delivery.

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

  • Only the sender’s own key from a message’s headers and attachments; introducing a third party is what gossip is for, and gossip lands on a lower rung.

  • Gossip only from ciphertext: 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.

  • 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.

42.3. Configuration

LEARN_KEYS, LEARN_GOSSIP, LEARN_FROM_SPAM, the LOCAL_DOMAINS locality options and a mandatory NEXT_STAGE. See Configuration.

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

42.4. What a learnt key is worth

Little, deliberately. Harvested keys sit at rank inbound and gossiped ones at gossip — the bottom two 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 this host holds an identity for. Within those two rungs the rule is newest wins on the message’s Autocrypt effective date, so a correspondent who reinstalls their client stops receiving mail encrypted to a key they no longer hold — protection against a passive adversary, which is all Autocrypt claims.