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, unlessLEARN_FROM_SPAMsays 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
SignerInfoof the message verifies under its key over the signed content, never because aSignedDatacarries it. It lands oninbound-signedwhen DMARC passed at ingress or an aligned, passing DKIM signature covered the body, and oninboundotherwise; 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 fromstate.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, apepsi.peer_has_own_keyrow is written, so pepsi-stage-encrypt stops attaching that key as a file (ATTACH_KEYS_AS_FILES). This happens whateverLEARN_KEYSand the spam verdict say, since it concerns our key, not theirs.Records what a correspondent’s S/MIME client reads: the RFC 8551
SMIMECapabilitiesa verified signature carries are recorded per signing certificate inpepsi.smime_capability, from which pepsi-stage-encrypt and pepsi-stage-reencrypt choose AES-GCMAuthEnvelopedDataor AES-CBCEnvelopedDatafor 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_keyis 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.rotateaudit row and, withRESPONSE_STAGEset, 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 thepincommand that records a comparison (A user’s own pin).ACCEPT_ROTATION = expiredinstead holds a new key until the stored one is dead. A gossiped key that its owner later advertises themselves is promoted to theinboundrung.Unprivileged: it writes only public key material, so unlike the crypto stages it needs no setuid bit and is folded into the multi-call
pepsibinary.
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).