95.1.7. pepsi-stage-decrypt

decrypt mail addressed to our users and verify what signed it

Manual section:

1

95.1.7.1.1. Name

pepsi-stage-decrypt - inbound end-to-end decryption and signature verification stage of the Pepsi pipeline.

95.1.7.1.2. Synopsis

pepsi-stage-decrypt [GLOBAL-OPTIONS] worker

95.1.7.1.3. Description

pepsi-stage-decrypt is a stage program run by pepsi-dispatch(1) as a persistent worker reading message ids on standard input. For a message addressed to a recipient that this host serves, it opens whatever ciphertext the message carries, verifies whatever signature it carries against a real trust chain, records the verdict, and removes any security indicator the sender forged. It reads the certificates the message carries in order to check that signature, but stores none of them: learning correspondents’ keys is pepsi-stage-autocrypt-learn(1)’s job, and it is a separate stage because it must run after the spam verdict, which does not exist yet here.

Doing this on the server is what removes the need for a client plugin: the user reads ordinary mail in their usual client. The trade is only sound because the message is about to stop being an SMTP object and become a file in a mailbox — see Locality. That file is plaintext unless the recipient registered their own mail-client key and pepsi-stage-reencrypt(1) sits in front of local delivery, sealing what this stage opened to that key once the later stages have read it.

The verification half is deliberately strict about one distinction. A cryptographically sound signature tells you the message was signed by some key; whether that key is the sender’s is a separate question. The two are never reported as the same thing (Verdicts).

95.1.7.1.4. Locality

The stage runs only for recipients that this host serves, and for a message that it does not serve it does not even try — a failed decryption attempt should not colour the verdict, and there is no key for such a message anyway.

The reason is that decryption rewrites the body. The sender’s DKIM signature then no longer verifies, and an ARC seal made before decryption (see Placement) covers the encrypted form. For a message about to be delivered locally that is harmless. For a message being forwarded onward it is not: it would arrive at the next hop with a broken signature, which is a stronger negative signal than no signature at all.

Locality is the same test the delivery stages use — LOCAL_DOMAINS, TARGETS and RECIPIENT_DELIMITER — with one difference. By default only the domain has to match, because this stage does not have to know whose mailbox to write; a hosted domain whose users hold crypto identities but no shell accounts is an ordinary deployment. Set REQUIRE_ACCOUNT = yes to demand a passwd entry in TARGETS as well.

A message with both local and foreign recipients is split: the foreign recipients are peeled onto a sibling row at NEXT_STAGE carrying the message exactly as it arrived, and this row keeps the local ones. The per-recipient DSN state is sliced in lockstep by the same code that every other recipient split uses.

A message carrying ciphertext for several local recipients is split one recipient per row before any key is loaded, and each copy is opened with its own recipient’s keys only. A row is opened once and its plaintext goes to every recipient that it carries. If it were opened with all their keys, anybody could take a ciphertext captured on its way to Bob, send it to Bob and to themselves (or to a second local user), and have it decrypted and delivered to that other recipient. A recipient whose own keys cannot open the ciphertext gets it as a decryption failure (ON_DECRYPT_FAILURE).

95.1.7.1.5. Placement

The recommended inbound chain is:

init = arc -> decrypt -> aliases -> (anti-spam / language / …) -> local delivery

ARC runs first. An ARC set seals the message as it arrived; decrypting first would make the sealed AMS describe bytes that nobody else ever saw, so the seal would be a claim about a message that never existed. pepsi-setup(1) warns when it finds an ARC stage reachable from a decrypt stage.

Content inspection runs after. Language detection, the pay-to-send gate and the From:-header whitelist check all read the body, and all of them need cleartext.

Placement is also a performance matter. The stage declares Load::Full, because whether a message is protected cannot be told from the envelope columns and Load is fixed per stage. Every message that passes through it therefore loads its whole body from the database, even one that turns out to be ordinary unencrypted mail. That is affordable on an inbound path terminating in local delivery; it is not a stage to put in front of bulk relay traffic.

95.1.7.1.6. Verdicts

state.crypto.in.signature.status is one of:

none

The message carries no signature.

valid

Cryptographically sound and the key was anchored: an X.509 chain to a configured ca_trust anchor, or an OpenPGP key found by WKD or by DANE with a DNSSEC-validated answer, one the operator added (pepsi-keys(1) or the API), or our own identity for the sender — and the signer is bound to the From: line as the reader sees it (What valid is granted for).

partial

Would be valid, but the reader is shown text beside the signed text that the signature does not cover. This is the inline clearsigned block, which is delivered as it arrived: an armor header line other than Hash: between the BEGIN PGP SIGNED MESSAGE marker and the text (the armor reader accepts any Key: value line there and hashes none of it), or a block that is the body of a text/html part, which a client renders as markup where such a line can hide the signed text. The block is left as it came, so the reader’s own client can re-verify it; this stage writes no tag and does not set state.signature_verified. X-Pepsi-Crypto says which (unsigned-surface=armor-headers or html).

valid-untrusted

Cryptographically sound, but the key could not be tied to anything: a key seen for the first time, learnt from the message itself, from an Autocrypt header or from gossip, fetched from a key server (VKS, LDAP) or from DANE without DNSSEC validation, or a certificate from a CA for which this deployment holds no anchor. Most of the world’s signed mail is in this state. Also an anchored signature from which one of this stage’s own rules withheld valid — a signature over ciphertext only, a protected From: or reply-steering field that differs, a certificate naming no mailbox, a display name showing another address, a From: with several mailboxes, a signer domain that looks like a known one, a signature made long before the message arrived; withheld= in X-Pepsi-Crypto and signature.withheld in the state say which.

This is never reported as ``valid``. It is the distinction that the stage exists to make, and a security indicator that conflates the two is worse than none.

invalid

The signature does not verify over the bytes it covers, or the signer’s certificate is expired, revoked, or bound to an address other than the message’s From:. An S/MIME certificate is judged at the time the stage runs, never at the signingTime the signature claims, and a mailbox name that is not a bare local@domain matches no From: address. An OpenPGP signature inside the ciphertext that names its intended recipients (the RFC 9580 Intended Recipient Fingerprint) without naming the certificate that opened the message is invalid too, with the layer verdict wrong-recipient: it was signed for somebody else, who re-encrypted it to us. An S/MIME signature inside the ciphertext is held to the same rule through the private signed attribute that Pepsi writes when it signs and encrypts (see pepsi-stage-encrypt(1)), which names the SHA-256 of each recipient certificate. A signature that names no recipients is unaffected; no other S/MIME client writes the attribute.

unverifiable

No key or certificate was available for the claimed signer, so nothing could be established either way. This is the verdict that makes the stage wait for a key (Key discovery).

A message carrying several signature layers takes the worst of the verdicts of the layers that speak for it. One broken signature makes the message invalid however good the others are. A layer that only covers ciphertext is one of those only when nothing covers the plaintext (see below): such a layer can never make the message valid, and once some layer does cover the plaintext it is disregarded entirely, however bad it is.

Only valid sets state.signature_verified, the flag on which pepsi-stage-check-whitelist(1) gates a whitelist entry.

95.1.7.1.6.1. What valid is granted for

The verifier binds the signer’s key to the first mailbox of From: (an OpenPGP User ID, an S/MIME rfc822Name or RFC 9598 SmtpUTF8Mailbox, or the subject’s emailAddress), and a key that names other addresses is invalid (identity-mismatch). The [verified] tag promises more: that the signer is the sender as the reader sees the From: line. So a signature that verified is reported valid-untrusted instead of valid when:

  • the display name shows another address — From: "Alice <alice@victim.example>" <x@attacker.example> signed by the attacker’s own anchored key. Judged from the field itself and from what pepsi-ingress(1) recorded (state.auth.display_name_mismatch), reason display-name;

  • the From: names more than one mailbox — only the first is bound, and a client that shows another shows a sender nothing vouched for; reason multiple-from;

  • the certificate names no mailbox and chains to a ca_trust anchor — it contradicts no From:, so the binding cannot fail it, but it vouches for no address either, and would otherwise be valid for every sender. Reason no-identity. An operator who knows that a CA’s own issuance process binds each leaf to its holder’s mailbox opts that anchor in (pepsi-keys(1) ca add --accept-nameless, ca accept-nameless); a key that was found by looking the address up (WKD, DANE, a pin, our own identity) is bound by the lookup and unaffected;

  • the signer’s domain looks like a served or known domain — its skeleton (decomposed, marks stripped, look-alikes folded through the UTS #39 confusables data, the same folding that the subject-tag stripper uses) equals that of a domain in LOCAL_DOMAINS, of an address in the key store (crypto_identity, peer_key) or of a from whitelist row, while the domain itself differs. Reason lookalike-domain, and the domain’s A-label is written to X-Pepsi-Crypto (signer-domain=) where a reader can see what the rendered form hides. The known domains are read from the database only for a message that would otherwise be valid, cached for TRUST_ANCHOR_TTL; the cost is a legitimate internationalised domain whose skeleton happens to equal a known ASCII one, which is delivered and verified but not tagged;

  • a protected From: or reply-steering field (Reply-To:, Mail-Reply-To:, Mail-Followup-To:) differs, or the protected Subject: carries a forged indicator (Protected headers), reasons protected-from, reply-to and protected-subject;

  • the signature was made long before the message arrived: its creation time (the OpenPGP signature creation time, the S/MIME signingTime attribute) lies more than MAX_SIGNATURE_AGE_DAYS (default 7) before the row’s arrival time, reason old-signature, or more than a day after it, reason future-signature. A captured signed message replayed under a fresh outer Subject: or Date: is the shape this catches: the signature is genuine, but it does not say that its signer sent this message at this time. The arrival time is the one that this host recorded, never the Date: field, which the replayer writes. A signature without a creation time (CMS without signingTime) is not judged, and 0 turns the check off. Mail legitimately delivered late (a list moderation queue, a message forwarded as it is) loses only the tag. X-Pepsi-Crypto shows every recorded creation time (signed-at=);

  • the signature covers only ciphertext (next section), reason ciphertext-cover.

A valid signature records the address it is bound to (bound-to, signature.bound_to), which is what the tag names.

95.1.7.1.6.2. A signature that covers ciphertext

In signed(encrypted(body)) the signature is computed over the ciphertext, not over anything a reader will ever see. That proves the signer transmitted the blob; it does not prove they wrote it, and it does not prove they can read it — anybody who obtains an encrypted message can wrap it in their own signature and forward it. Such a layer is recorded with "covers_ciphertext": true in state.crypto.in.layers and, whatever its own verdict, it is never allowed to make the message ``valid``: a good one is reported as valid-untrusted, so it earns no [verified] tag and does not set state.signature_verified. A bad one is reported as invalid and routes under ON_BAD_SIGNATURE only when it is all there is — that is, when no layer covers the plaintext.

Once some layer does cover the plaintext, the ciphertext-covering ones are set aside entirely, whatever their own verdict. A layer that cannot grant a verdict must not be able to destroy one: anybody who obtains the encrypted blob can re-wrap it, so if a corrupt wrapper forced invalid then corrupting the wrapper would be strictly more useful to an attacker than removing it (which leaves an ordinary encrypted(signed(body)) that still verifies). The outer signature of a triple wrap is in any case a hop-by-hop artefact (in RFC 8551 §3.7 a mailing-list agent applies it), so its failure says nothing about the author. The tampering is not lost: it stays visible in state.crypto.in.layers and in X-Pepsi-Crypto, as an observation rather than a routing input. The same reasoning covers the commoner case of an outer signature that is merely unverifiable (no key for the forwarder), so the triple wrap below is not punished for a signer we happen not to know.

So in signed(encrypted(signed(body))) — the triple wrap RFC 8551 §3.7 recommends — the inner signature is the one that speaks for the content, and it is the one this stage reports. That shape is therefore reported as valid where a single outer signature is not.

Whenever there is a signature verdict, state.crypto.in.signature also records covers_plaintext: true when the verdict was granted by a signature over the plaintext, false when it came from a layer wrapped around ciphertext. pepsi-stage-autocrypt-learn(1) accepts only the first kind as proof that a correspondent holds one of our keys.

95.1.7.1.6.3. Protected headers

A signer can cover From:, To:, Reply-To:, Mail-Reply-To:, Mail-Followup-To: and Subject: by placing them inside the entity it signs: the injected-headers form of RFC 9788 (the protected-headers="v1" form that pepsi-stage-encrypt(1) writes under PROTECT_HEADERS), or a signed message/rfc822 whose embedded header block carries them. The reader is shown the outer fields, which no signature covers, so the stage compares the two for every signature over the plaintext:

  • A protected From: whose address differs from the outer From:’s (compared as addr-specs of the first mailbox, case-insensitively, display names and comments ignored) withholds valid: the signature is reported valid-untrusted (withheld=protected-from), earns no [verified] tag and does not set state.signature_verified. The signer vouched for a message from somebody else; a signed message re-sent under a new outer From: (surreptitious forwarding) is the shape this catches. A protected block with two From: fields that disagree, or one with no legible address, counts as a difference. Only the positive verdict is withheld; invalid and unverifiable are unchanged. Mailing-list software that rewrites the outer From: of signed mail therefore costs such mail its valid, never more.

  • A reply-steering field — Reply-To:, Mail-Reply-To: or Mail-Followup-To: — that differs withholds valid the same way (withheld=reply-to). These are the fields that a reply-redirection attack changes or adds, so an outer one that the signer did not protect counts as a difference too, as does a signed one that was removed. Each is compared as a set of addr-specs and reported under its own name (protected-mismatch=). The one exception is a field a mailing list added — the outer block carries a List-Id: and the signer protected none of the three: the signature stays valid and the tag reads [verified (except reply-to): …] (TAG_VERIFIED_EXCEPT_REPLY_TO, reply-to=unsigned in X-Pepsi-Crypto), so the key fact survives and reply-to munging keeps working, at the price of one more tag to understand, for list users only. The cost of the rule is a client that protects some headers but not these fields on a message whose sender set one: such mail loses valid, never more. Sender: is not compared: lists and delegates set it legitimately, and replies do not go to it.

  • A Subject: that differs only by bracketed segments inserted in front — a list tag, an [external] marker, this stage’s own tags on a message that went round once — is no difference. Both subjects are first reduced to what a reader sees (RFC 2047 decoded, whitespace collapsed, this stage’s own tags and any forged indicator stripped from the front); the outer one is then accepted when, after its leading […] segments and Re:-style prefixes are set aside, the rest is the signed subject, the reply prefixes agree in order, and every bracketed segment that the signer wrote is still there in order — the outer side may have more, before or after a Re:. A larger difference is reported, and when the signature is otherwise valid the signed subject is shown in place of the outer one (subject=protected in X-Pepsi-Crypto, state.crypto.in.subject_promoted), so the message keeps [verified] under the subject its signer wrote. A marker written without brackets, such as EXTERNAL:, is thereby removed; so is anything else added on the way. Header protection replaces the outer Subject: by design, so an outer ... or [...] is not a difference and nothing is promoted over it.

  • A protected Subject: that carries a forged indicator withholds valid (withheld=protected-subject). The subject-tag sanitiser (Subject tags) is run over the protected subject as over the outer one; the outer one is cleaned, but the protected one cannot be without breaking the signature, and a client that shows protected headers shows it. When the sanitiser would change it (a security tag or a look-alike of one at the front, an indicator symbol, a bidi control), the signature is reported valid-untrusted. A Pepsi deployment never sends its own tags on: a reply quoting [verified: …] leaves pepsi-stage-encrypt(1) without it, so such a reply keeps valid.

  • To: differences are only reported. Forwarders and lists change it legitimately. Compared as a set of addr-specs.

A signature whose covered entity carries none of these six fields is not compared at all; the signer’s certificate is still bound to the outer From: as described under invalid. A layer that covers ciphertext has no plaintext header block and is never compared. The differing field names are recorded as state.crypto.in.protected_mismatch and in X-Pepsi-Crypto as protected-mismatch (from, to, reply-to, mail-reply-to, mail-followup-to, subject). Apart from the subject promotion above, the protected copies are never promoted onto the delivered header block.

95.1.7.1.7. Failure handling

Both failure paths deliver by default, matching Pepsi’s deliberate fail-open posture on inbound SPF, DKIM and DMARC:

ON_DECRYPT_FAILURE = passthrough

The still-encrypted message is delivered. The user may well hold the key in their own client, and bouncing mail that we merely could not open helps nobody. quarantine and bounce-if-unproblematic are available. The value bounce is an alias for the longer but unambiguous bounce-if-unproblematic: the bounce is only sent on messages where the CBC oracle does not apply because the message is not encrypted with CBC. The worker and pepsi-setup(1) warn when the short spelling is used.

ON_BAD_SIGNATURE = record

A bad signature is a recorded verdict, never a delivery failure. Mailing lists that rewrite bodies, forwarders and clients with broken canonicalisation all produce bad signatures on entirely legitimate mail; quarantining them would cost far more than it catches. quarantine and bounce are available; bounce drops instead of bouncing a message whose signature came out of a ciphertext without integrity protection (see below).

Note that only invalid is a “bad signature” for this purpose. valid-untrusted and unverifiable are the normal state of mail from a correspondent nobody here has heard of, and routing those anywhere would route most of the internet.

The decryption policy is consulted first: a message that could not be opened has no signature verdict worth acting on.

95.1.7.1.7.1. Correspondents who usually sign

A signature only protects against a forged From: if its absence is noticed. Whenever a signature earns valid – an anchored key bound to the From: address – the stage records the address, the signing key and the time in pepsi.signed_sender. Only valid writes there, so nobody can create or refresh the record for an address whose anchored key they do not hold.

A later message from that address that carries no valid signature (unsigned, unverifiable, valid-untrusted or partial), within MISSING_SIGNATURE_WINDOW_DAYS (default 90) of the last valid one, is handled under ON_MISSING_SIGNATURE:

record (default)

X-Pepsi-Crypto gains usually-signed=<date of the last valid signature> and state.crypto.in.usually_signed records it, for Sieve rules and the client extensions; nothing else changes. A correspondent writing from a phone or a new client produces exactly this shape, which is why nothing stronger is the default.

tag

Also prepends TAG_MISSING_SIGNATURE (default [unsigned, usually signed]) to the Subject.

quarantine

Routes the message to QUARANTINE_STAGE.

An invalid signature is ON_BAD_SIGNATURE’s, and a message this stage did not open (a decryption failure, mail for the user’s own client key, a plaintext withheld under UNAUTHENTICATED_PLAINTEXT) is not judged, since its signature could not be seen. MISSING_SIGNATURE_WINDOW_DAYS = 0 turns the check off; valid signatures are still recorded. A database error while reading or writing the record is logged and treated as no record. Telemetry decrypt-missing-signature.

95.1.7.1.7.2. Telling a sender that decryption failed

A bounce for every failed decryption would tell whoever sent the message whether it could be opened. For a ciphertext without integrity protection, an S/MIME EnvelopedData with AES-CBC or 3DES, that is a decryption oracle. An attacker who captured a message encrypted to one of our users re-sends modified copies under their own envelope sender; whether a copy bounces says whether its modified CBC padding was valid, and about 2,000 copies decrypt one 16-byte block (a padding-oracle attack). AES-GCM mail sent without RFC 9709 key derivation can be re-wrapped as CBC under the same key transport, so the oracle would reach it too. No setting of the stage gives that answer.

ON_DECRYPT_FAILURE = bounce-if-unproblematic keeps the bounce where it gives nothing away. It bounces a message only when the ciphertext that failed is integrity-protected — every OpenPGP container Pepsi accepts, and S/MIME AuthEnvelopedData — because then every modified ciphertext fails alike and the sender learns only that they modified it. The container is read from the ciphertext’s DER, never from the smime-type label, which the sender writes. The DSN’s diagnostic says only that the message could not be decrypted; the failure class (no-decryption-key, decryption-failed, malformed) goes to the log and X-Pepsi-Crypto for the operator, never into the DSN, since which class a modified ciphertext falls into would itself be a format oracle. Any other failed message (CBC, 3DES, or a container nobody could identify) is dropped and logged: a DSN, or its absence, would be the oracle. The drop costs the sender of a legitimate CBC message the notice that it was not read; with passthrough that message would have been delivered encrypted instead, which is why passthrough stays the default.

ON_BAD_SIGNATURE = bounce gets the same treatment. A CBC gadget can make a garbled plaintext look signed, so for content that came out of an EnvelopedData container a bad signature, and with it the bounce, depends on the padding. Such a message is dropped and logged instead (telemetry decrypt-dropped); a bad signature from an authenticated container, or on a message that was not encrypted, still bounces. pepsi-stage-reencrypt(1) applies the same rule to ON_NO_CLIENT_KEY = bounce, whose bounce would be sent only for a message that opened.

The same reasoning is why the stage starts no key discovery for a signature inside content that came out of a ciphertext without integrity protection (see Key discovery).

A recipient key that this host holds but cannot open — a key-encryption key that does not match the stored blob, a secrets.d fragment gone missing, a revoked database grant — also ends as decrypt-failure=no-decryption-key and takes the ON_DECRYPT_FAILURE route, exactly like a message addressed to a key that we never had. That is deliberate (one broken identity must not stop the others from being tried), but it is a broken deployment and not the sender’s doing, so each such identity is logged at error with the address and the reason. The same goes for recipients who hold decryption identities on a host with no [pepsi-crypto] KEY_WRAP_SECRET configured at all.

95.1.7.1.8. Errors of this host

Everything else that goes wrong on this host is retried rather than failed (see pepsi-dispatch(1)): when the database cannot answer, the message is paused and tried again until the stage’s MAX_LIFETIME. That includes the lookup of the recipients’ own MUA keys, which is never read as “no such key”, since that would open mail that is meant for the user’s own client. The stage’s section, the [pepsi] crypto policy, [pepsi-keydiscovery] and, when a key-encryption key is configured, the key ring built from it are checked when the worker starts: one that does not work makes the worker refuse to start (exit 78), so the dispatcher holds the queue instead of each message failing on the same fault. A message that makes the cryptography crash (a panic while parsing it) is failed at once: it is the message’s doing, and it would only crash again.

95.1.7.1.9. Isolating protected content

Before it looks up a key or opens anything, the stage reduces a message for a local recipient to its protected content. Two rules apply, each with its own switch:

ISOLATE_ENCRYPTED = yes (the default)

When the message carries an encrypted unit – a PGP/MIME multipart/encrypted, an application/pkcs7-mime part that is or may be ciphertext, or an inline -----BEGIN PGP MESSAGE----- block – next to any other content, the first encrypted unit becomes the message and everything else is moved into inert attachments. The kept unit becomes the body under the message’s original header fields; an inline block becomes a text/plain part holding only the armor, and the text that surrounded it becomes an attachment of its own. Every moved part is rewritten as application/octet-stream with Content-Disposition: attachment, a sanitised file name (the sender’s, or part-N.html, message-N.eml, encrypted-N.asc and the like), a Content-Description saying that Pepsi moved it and that the message’s protection does not cover it, and no Content-ID, Content-Location or Content-Base, so the body cannot pull it back in by reference. A part that already is such an attachment is kept byte for byte. We do this to avoid EFAIL direct exfiltration: an attacker who captured a ciphertext wraps it between two HTML parts that open and close an image URL, and a mail client that renders the decrypted part together with its neighbours sends the plaintext to the attacker’s server. No client renders an application/octet-stream attachment inline, so nothing is left to splice the plaintext into, while a real attachment still arrives. A sender’s own label is not trusted for this: common clients show a text/* part inline even when it is marked as an attachment, so every moved part is rewritten (RFC 9787 section 6.2.2 likewise requires a decrypted part found inside other content to be kept apart from everything else). Further ciphertexts are moved as well, since an attacker can encrypt the two HTML halves to the recipient’s public key; a ciphertext that arrived as an inert attachment never becomes the message. Because the reduction happens before decryption, it also protects mail the stage does not open – a message it holds no key for, or one encrypted to the user’s own MUA key (Mail for the user’s own key) – whose decryption is then done by a client that may itself be vulnerable. What is delivered is set out under Moved parts.

ISOLATE_SIGNED = yes (the default)

When the message carries no ciphertext but signed content — a multipart/signed, an opaque S/MIME SignedData or an inline clearsigned block — next to unsigned content, the unsigned content is dropped (several signed units are kept together in a multipart/mixed). We do this so that a signature verdict, and the [verified] tag, speaks for everything the user sees: a valid signature on one part must not lend its verdict to text a stranger put beside it, before or after it.

A signature container whose only content is the ciphertext (signed(encrypted(body)), the RFC 8551 triple wrap) is structure, not other content, and is left intact. An attached message (message/rfc822, message/global) is a different message, which a client opens – and decrypts – on its own. So under ISOLATE_ENCRYPTED every attached message that carries an encrypted unit next to other content is first reduced by the same rule: its first encrypted unit stays, everything else becomes inert attachments inside it, and it stays an attached message. This is followed through three levels of attached messages; one nested deeper that still carries ciphertext becomes an inert .eml attachment whole. The reduced attached message then goes where any other part goes: beside a top-level ciphertext it is moved into an .eml attachment, which holds the reduced form, and under ISOLATE_SIGNED it is dropped. A signature over a container holding such an attached message does not verify, since the reader is not given what was signed. The kept entity keeps its own bytes otherwise, so a signature over it still verifies.

Both rules are applied again to every plaintext the stage recovers, so a ciphertext nested beside attacker parts inside another ciphertext, or a partially signed plaintext, is reduced the same way before the next layer is opened, and the parts moved out of the plaintext join the others. A reduction is recorded as state.crypto.in.isolated (encrypted, signed) and as isolated= in X-Pepsi-Crypto; how many moved parts were delivered and how many dropped as demoted/dropped in both places, and how many attached messages were reduced as nested.

95.1.7.1.9.1. Moved parts

What the recipient gets depends on whether the stage opens the ciphertext that it kept, and on whether that plaintext is signed:

  • Opened, unsigned. The plaintext is the body and every moved part follows it as an attachment. A moved ciphertext is opened with the same keys (up to 16 of them per message) and delivered as its plaintext, again as inert attachments: a single-part plaintext keeps the ciphertext’s file name without its .pgp, .gpg, .asc or .p7m suffix (report.pdf.pgp arrives as report.pdf), a multipart one becomes one attachment per part. One that cannot be opened is delivered as the ciphertext attachment.

  • Opened, signed. The signature must not appear to vouch for what somebody else put beside the message, so cleartext moved parts are dropped, and a moved ciphertext is kept only when its own plaintext carries a valid or valid-untrusted signature made by the same key as the message’s. This is the encrypted counterpart of ISOLATE_SIGNED: unsigned content is dropped only where signed and unsigned content are mixed.

  • Not opened (no key, a failure, or the user’s own MUA key). A PGP/MIME or S/MIME container is delivered alone, at the root of the message, which is where clients look for it (Thunderbird opens S/MIME only there), and the moved parts are dropped. A sender’s real attachments are inside such a container, so what is lost is only what was added around it, such as a mailing-list footer. An inline block keeps the moved parts as attachments, because that is how inline PGP carries files.

A message whose signer key is being looked up (see Key discovery) is not committed as plaintext while it has moved parts, since which of them may stay depends on the verdict; it is decrypted again when it resumes.

The rules still cost content in two cases, which is why each can be switched off: a mailing-list footer appended outside a signature, or around a container this host does not open, is lost; and a plaintext note beside a separately encrypted file is kept only when the note is unsigned. Mail for recipients that this host does not serve is never reduced (it is forwarded as it arrived, see Locality).

95.1.7.1.10. Mail for the user’s own key

A user may register their own key, whose private half lives only in their mail client (an MUA key, crypto_identity.custody = client; see pepsi-stage-encrypt(1) and pepsi-keys(1)). Mail encrypted to such a key is for the mail client, and the stage recognises it before it tries to open anything: it reads the recipient identifiers of the ciphertext (OpenPGP PKESK key IDs, S/MIME RecipientIdentifiers) without decrypting and matches them against the recipients’ client keys that are not revoked. A wildcard (“hidden recipient”) key ID matches nothing and takes the ordinary path.

On a match the message is passed on unopened, even when one of our own MTA keys is among its recipients too: the user registered their own key to get end-to-end protection, and opening a copy on the server and storing the plaintext in the mailbox would silently undo that. The stage records state.crypto.in.decryption = for-client, for_client = true and client_fingerprint, sets state.encrypted, and adds for-client=yes to X-Pepsi-Crypto. This is not a decryption failure, so ON_DECRYPT_FAILURE is not consulted, and the message advances to NEXT_STAGE like any other: the spam checks and the rest of the pipeline still decide its fate. A message with several local recipients has already been split one per row (see above), so one recipient’s client key says nothing about another’s copy.

The consequence is that server-side features cannot see into such mail. Content-reading stages (language detection, for example) see ciphertext and fall back as they do for any undecryptable message, and nothing was verified, so state.signature_verified is never set and a whitelist entry with signature_required does not match it.

95.1.7.1.11. Anti-forgery

Every X-Pepsi-* header field is removed from every message this stage sees — including a message it is not going to touch, and including one for which the stage is disabled. Only then is our own added. The one exception is X-Pepsi-Warning on the outer header block: pepsi-ingress(1) writes it only after removing every copy a sender wrote, so it is kept for the reader (a copy inside decrypted content is removed with the rest).

X-Pepsi-Crypto is a private header, so it is forgeable by definition; the unconditional removal is the entire basis on which a client may believe it. The Pepsi-Origin proof-of-origin header is deliberately not in the namespace and survives.

The same argument applies to the Subject. With STRIP_SUBJECT_TAGS = yes (the default) anything that would display as a security indicator is removed from the front of an inbound subject before ours is prepended; otherwise an external sender simply writes [verified] themselves. The subject is judged by what a mail client displays, not by its bytes:

  • RFC 2047 encoded-words are decoded first, so =?UTF-8?B?W3ZlcmlmaWVkXQ==?= counts as [verified];

  • text is compared by its skeleton: compatibility-decomposed (full-width brackets become ASCII), without accents, every character folded to its prototype from the full confusables data of Unicode Technical Standard #39 (Cyrillic, Greek, Armenian, Cherokee and every other script’s look-alikes; m reads as rn), small capitals and digit substitutions folded to the letter they imitate, and lower-cased;

  • removed are this stage’s own tag vocabulary (every TAG_* option, the built-in [decrypted], [verified], [decrypted, unauthenticated], [unverified signer], [bad signature] and [verified (except reply-to)], the address form [verified: …] whole however long its address, and STRIP_SUBJECT_KEYWORDS), matched by skeleton; any bracketed group, in ASCII or Unicode brackets, containing a word that is, or is one letter away from, a security word (verified, decrypted, encrypted, signed, signature, secure, trusted, authentic and their close forms) or a word of our own tags; a leading Verified:-style claim; check-mark, padlock, key and shield symbols; and invisible characters (zero-width characters, byte-order marks, soft hyphens);

  • bidirectional embedding, override and isolate controls are removed from the whole subject, since they can make text anywhere in the line render as a tag at its start.

Tags are removed from the front of the subject, from behind Re:/Fwd: prefixes and from behind unrelated bracketed groups such as a mailing-list tag; a subject that mentions [verified] mid-sentence keeps it. The rule errs on the side of removing: a legitimate subject that opens with [Signed contract] loses that prefix. The same cleaning is applied to the subject of a decrypted message’s own header block (a protected subject replaces the outer one) and to mail passed through unopened for the user’s own key. A subject that needs no change is left byte for byte.

95.1.7.1.12. Subject tags

With SUBJECT_TAGS = yes (the default) the earned tags are prepended to the Subject in nesting order:

encrypted(signed(body))   ->  [decrypted][verified] quarterly figures
signed(encrypted(body))   ->  [verified][decrypted] quarterly figures

Both shapes open. The second line states the ordering rule; note that the second example earns its [verified] only from an inner signature, because an outer signature over ciphertext never reaches the valid verdict the tag is written for (A signature that covers ciphertext). A signed(encrypted(body)) message with no inner signature is therefore tagged [decrypted] alone.

For most users this is the only signal they will ever see — nobody reading mail in a webmail client inspects headers — so doing the work invisibly would waste it. The cost is that a user-visible field is mutated: it affects search, threading and the quoted subject of replies. Set SUBJECT_TAGS = no to rely on the header alone.

[verified] is written only for the valid verdict, and it names the address the signer is bound to, inside the closing bracket:

[verified: alice@example.org] quarterly figures

[verified] alone says only that somebody with an anchored key signed, and the reader would still have to rely on a From: line whose display name the sender writes as they like; with the address in the tag, the one field that every client shows says who signed. (A TAG_VERIFIED spelt without a closing bracket gets the address appended after a colon.) When a mailing list added the outer Reply-To: (or Mail-Followup-To:) outside the signature (Protected headers) the tag is TAG_VERIFIED_EXCEPT_REPLY_TO instead, [verified (except reply-to): alice@example.org]: the key fact survives, and the one field the signature does not cover is named.

A signature inside a ciphertext is tagged whatever its verdict. Anyone can re-send a captured ciphertext, or encrypt to a published key, from an address of their own; the reader would otherwise see [decrypted] and nothing that says the signer is not the sender, and a quoting reply returns the plaintext to whoever sent it. So a signature there that is sound but not valid — an untrusted or unknown key, a partial cover — earns TAG_UNVERIFIED_SIGNER ([unverified signer]), and a bad one TAG_BAD_SIGNATURE_ENCRYPTED ([bad signature]), both on by default (none silences either):

encrypted(signed(body)), untrusted key  ->  [decrypted][unverified signer] …
encrypted(signed(body)), bad signature  ->  [decrypted][bad signature] …

Outside a ciphertext, TAG_BAD_SIGNATURE is empty by default: a bad signature is a routine property of legitimate mail (a list rewrites bodies), so a default-on tag would decorate a large part of a user’s inbox with an accusation. That argument does not hold inside a ciphertext — a list cannot rewrite a body it cannot read — which is why the two have separate defaults. An untrusted or unverifiable cleartext signature earns no tag.

Every shape this stage writes, the address form included, is removed from an inbound subject before ours is added, however long the address a sender puts into a forged one.

95.1.7.1.13. The result header

With ADD_RESULT_HEADER = yes (the default) a message that carried any protection gains one header field, prepended at the top so it disturbs no existing signature:

X-Pepsi-Crypto: encrypted=yes; decrypted=yes; protocol=openpgp;
  signature=valid; signer=alice@example.net;
  fingerprint=0123456789ABCDEF; key-source=wkd; trust=wkd;
  layers="encrypted,signed"

The grammar is semicolon-separated key=value pairs in a fixed order. A value that is not a bare token (A–Z, a–z, 0–9 and . _ @ : + / -) is double-quoted; an embedded " becomes ', and control characters are replaced by spaces, so no value from the message can end the field or start another one. Long values are folded at whitespace.

The keys are:

encrypted

yes/no — the message arrived carrying ciphertext. What counts is the packet stream, not the label: an armored PGP MESSAGE (or a multipart/encrypted body) that holds only a literal or signed OpenPGP packet opens without any key, its content is delivered, and it is reported encrypted=no, with no [decrypted] tag and no identity recorded as having opened it. A signature inside it is still verified.

decrypted

yes/no — present only when encrypted=yes.

for-client

yes when the message is encrypted to the recipient’s own MUA key and was passed through unopened (Mail for the user’s own key).

protocol

openpgp or smime.

container

The content-encryption container of the opened ciphertext, as the decryptor read it from the bytes: auth-enveloped-data or enveloped-data (S/MIME), seipdv2-aead or seipdv1-mdc (OpenPGP). Only enveloped-data lacks integrity protection. Present when a ciphertext was opened.

signature

One of the verdicts above.

signer, fingerprint, key-source, trust, algorithm

The signing key, where it came from and what it was worth. key-source and trust both carry the verifier’s provenance word (anchor, dane, wkd, pinned, autocrypt, attached or unknown). Present only when known.

binding

How the signer’s key related to the From: address as the verifier saw it: matched, mismatched or no-identity (the key names no address). Present when a key was found.

anchor

The fingerprint of the ca_trust anchor the signer’s chain ended at. Present for an anchored S/MIME signature.

bound-to

The address a valid signature is bound to — the From: address as written, which the tag names. Present only on valid.

signed-at

The creation time the signature claims, as an RFC 3339 UTC timestamp (2026-10-20T09:00:00Z). Present when the signature carries one. It is the signer’s claim, compared only with this host’s arrival time (MAX_SIGNATURE_AGE_DAYS).

withheld

Why a signature that verified is valid-untrusted rather than valid: ciphertext-cover, protected-from, protected-subject, reply-to, no-identity, display-name, multiple-from, lookalike-domain, old-signature or future-signature (What valid is granted for). Present only then.

unsigned-surface

Why a verified clearsigned block is partial: armor-headers or html. Present only then.

reply-to

unsigned when the signature is valid and the outer Reply-To: (or Mail-Reply-To:, Mail-Followup-To:) was added by a mailing list outside it (the [verified (except reply-to)] tag). Present only then.

signer-domain

The signer’s domain as an A-label, when it is an internationalised domain name or looks like a known one. Present only then.

usually-signed

The date (UTC, YYYY-MM-DD) a valid signature from the From: address last verified, on a message that carries none (Correspondents who usually sign). Present only then; a message with this key alone also gets the header.

failure

The machine-readable reason a signature verdict is not good.

decrypt-failure

The machine-readable reason decryption failed.

unauthenticated

yes when the plaintext came out of a container without integrity protection and no valid signature covers it (Plaintext from a malleable container). Present only then.

sanitised

text when the plaintext was reduced to content no client renders as markup (UNAUTHENTICATED_PLAINTEXT = text, or DECRYPTED_MARKUP = text for any decrypted plaintext). Present only then.

isolated

Which rules of Isolating protected content changed the message (encrypted, signed), comma separated. Present only when one did.

protected-mismatch

The signed protected header fields (from, to, reply-to, mail-reply-to, mail-followup-to, subject) that differ from the outer ones, comma separated (see Protected headers). Present only when one does.

subject

protected when the signer’s protected Subject: was shown in place of an outer one changed in transit. Present only then.

demoted, dropped

How many parts isolation moved out of the message were delivered as attachments, and how many were not (see Moved parts). Present only when not zero.

nested

How many attached messages carrying ciphertext beside other content were reduced (Isolating protected content). Present only when not zero.

layers

The protection layers, outermost first, comma separated.

RFC 8601 registers no smime or pgp method, so an Authentication-Results extension would mean inventing a method name in a registry that we do not own, and other implementations would be entitled to ignore or mistrust that name. A private header with a documented grammar is the honest choice, and the price of it is the unconditional stripping described above.

95.1.7.1.14. Plaintext from a malleable container

An S/MIME EnvelopedData container (AES-CBC, or 3DES where [pepsi] CRYPTO_ALLOW_DOWNGRADE admits it) protects nothing but confidentiality. Whoever holds a copy of the ciphertext can rewrite its plaintext block by block – EFAIL’s CBC gadgets – and, knowing or guessing one plaintext block, build an HTML element whose URL takes in the blocks that follow, so that a client which renders the result sends the plaintext to the attacker. The stage must read such containers (most S/MIME mail still uses them), and isolation does not help, because the rewrite happens inside the one encrypted unit that is kept. What the stage does not do is hand a client markup that it cannot vouch for.

A plaintext from such a container is covered when a valid signature inside the container speaks for it – valid or valid-untrusted; the key’s worth is beside the point, since a rewrite breaks any signature. A signature around the ciphertext does not count: an attacker re-signs the rewritten ciphertext with a key of their own. A covered plaintext is delivered as it is. An uncovered one is handled as UNAUTHENTICATED_PLAINTEXT says:

text (the default)

Every part a client would render as markup – text/html, text/enriched and the other text/* types, application/xhtml+xml, inside an attached message too – is relabelled text/plain with its charset kept and loses its Content-ID, Content-Location and Content-Base; a multipart/alternative offering a plain alternative is reduced to it. Plain text, images, files and signatures keep their bytes, and a part whose content does not change is not rewritten, so a signature over it still verifies in the client. The text arrives, nothing renders, and the HTML formatting of unsigned CBC mail is lost. The Subject is tagged TAG_UNAUTHENTICATED ([decrypted, unauthenticated]) in place of TAG_DECRYPTED, and X-Pepsi-Crypto says unauthenticated=yes; sanitised=text.

require-signature

The message is passed on unopened, as it arrived, for the user’s own mail client, which then sees the S/MIME container and applies its own EFAIL defences. decryption reads withheld, no identity is recorded as having opened the message, nothing is tagged, and ON_DECRYPT_FAILURE is not consulted: it is not a failure. Unsigned CBC mail to a user without a client key arrives unreadable, which is the price of the setting.

open

The plaintext is delivered as it came out of the container, markup included, for a site that accepts the exposure. It is still tagged TAG_UNAUTHENTICATED and recorded unauthenticated=yes.

OPEN_ENVELOPED_DATA = no goes one step further and does not open an EnvelopedData container at all, signed or not: the message is passed on as it arrived, exactly like require-signature (decryption reads withheld, not a failure), and no private key is applied to it. The container’s content-encryption algorithm identifier is not authenticated, so an attacker holding an AES-GCM message to one of our users that was sent without RFC 9709 key derivation can re-submit its RecipientInfo under a synthetic AES-CBC container; opening it applies the GCM message’s content key to a ciphertext of the attacker’s making. With the option off that key is never used for anything but the AEAD container it came with. The option defaults to yes (open) because most S/MIME clients still send nothing but EnvelopedData. Like every option of this section it can be set for one recipient address or domain through an address: or domain: overlay (pepsi-config(1)), so a user whose correspondents all send AuthEnvelopedData can have CBC left to their client while everybody else keeps it opened. There is no per-correspondent switch: the container’s sender is known only from the outer From:, which is exactly what a spliced or relabelled ciphertext lets the attacker write.

95.1.7.1.14.1. Markup in decrypted mail

An authenticated plaintext – from an integrity-protected container, or one a valid signature covers – is delivered as it came out, HTML included (DECRYPTED_MARKUP = keep, the default). Nobody can have rewritten it, but it can still load remote content: an image, a stylesheet, a font from the sender’s server tells the sender when, and roughly where, the message was read, and CSS can fingerprint the client. Blocking that is the mail client’s job, and matters more here than for ordinary mail: when the gateway has decrypted a message the client cannot tell it was encrypted, and a client that blocks remote content only in encrypted mail does not block it in this one. The manual’s chapter on mail clients lists the settings. DECRYPTED_MARKUP = text takes the choice away from the client: every decrypted plaintext is reduced exactly as UNAUTHENTICATED_PLAINTEXT = text reduces an unauthenticated one, recorded as sanitised=text, at the price of the formatting of every encrypted message; a signature over a part that was relabelled does not verify in the client. The cost falls on the reader, which is why it is an option a user can be given per address.

A container whose content-encryption algorithm is RFC 9709 id-alg-cek-hkdf-sha256 is opened whichever kind it is: the key the RecipientInfo delivers is run through HKDF-SHA256 over the real algorithm identifier (cipher, IV or nonce) before use, so the same delivered key under another algorithm yields another content key. The layer’s algorithm reads, for example, aes-256-gcm+cek-hkdf-sha256. Pepsi derives keys this way for a correspondent whose own signed SMIMECapabilities name the identifier, and advertises it in its own signatures.

Content from an AEAD container – S/MIME AuthEnvelopedData, every OpenPGP container this stage accepts – is never affected: a rewritten ciphertext fails to open at all. Which way an uncovered plaintext goes is visible to the recipient alone, so the decision is no padding oracle for the sender; a broken inner signature of a rewritten message is still reported invalid and handled by ON_BAD_SIGNATURE. The container is named in X-Pepsi-Crypto (container=) and in state.crypto.in.layers for every opened ciphertext.

95.1.7.1.15. Key discovery

The stage performs no network I/O of any kind. When the signer’s key is neither in the message nor in the peer_key cache, it enqueues a discovery request and parks the message; a pepsi-keydisc(1) service releases it when the request settles, found or not, and the stage runs again. A settled request with no key releases the message just the same, and it then verifies as unverifiable. When a fresh negative-cache entry exists, the message does not wait at all. This stops a spammer who signs with an unknown key from making every message wait: the first one parks, the rest do not.

[pepsi-keydiscovery] INBOUND_TIMEOUT bounds the wait and is separately tunable from the outbound TIMEOUT; DISCOVERY_TIMEOUT in this stage’s own section overrides it. DISCOVERY = no suppresses the request altogether and leaves the stage on the cache-only path.

No discovery is started for a signature inside content that came out of a ciphertext without integrity protection (S/MIME EnvelopedData, AES-CBC or 3DES, as the decryptor found it in the DER). A CBC gadget lets an attacker make a garbled plaintext look signed only when its padding is valid, and the lookup goes to the From: domain, which the attacker chooses; the WKD request or DNS query would arrive at their server exactly when the padding was valid. Not looking the key up removes that signal entirely. Keys already cached and certificates that the message carries are still used, so the cost is confined to CBC-encrypted mail signed with a key that is neither cached nor attached, which is delivered as unverifiable.

Whether a parked message is stored decrypted depends on the shape of the message, and the difference matters:

  • An S/MIME signature nested inside an envelope survives decryption as an ordinary MIME layer, so the message is parked with the plaintext committed and is decrypted exactly once.

  • An OpenPGP signature lives only inside the packet stream, so it is gone the moment the plaintext is out. Committing the plaintext would destroy the evidence that the key is being fetched to check, so such a message is parked unchanged and decrypted again on resume.

A message parked with its plaintext committed sits in pepsi.workqueue decrypted for up to the discovery deadline. That is the same exposure that delivery would create a moment later anyway; it is a longer window, not a new one.

95.1.7.1.16. Certificates the message carries

Most signed mail carries the certificate that signed it, so before deciding anything the stage reads the S/MIME signer certificates and application/pgp-keys parts out of the message and offers them to the verifier. It does this again on the plaintext once the message is open, since a certificate attached inside the ciphertext is invisible until then, and re-evaluates once if that yielded something the first pass did not have.

These certificates are used and dropped. This stage stores nothing: learning from inbound mail — the Autocrypt: header, attached keys, and gossip — is the job of pepsi-stage-autocrypt-learn(1), which runs later in the pipeline, after the stages that decide whether a message is spam. That split is what lets Autocrypt Level 1 §5.3’s spam rule be honoured at all: this stage runs first on the inbound path by design, before any such verdict exists. It also means nothing is written to the key store by the process that holds the private keys.

Using a certificate the message carried can only ever lower a verdict’s standing, never raise it: such material is untrusted provenance, so a signature checked against it comes back valid-untrusted and does not set state.signature_verified, the state key on which pepsi-stage-check-whitelist(1) gates. That is the same rung a stored harvested key would have, so routing it through the database would gain nothing. What can raise an S/MIME signer is a path to an anchor (see Trust anchors): a certificate carried in the message, or learnt from an earlier one, that chains to a pepsi.ca_trust anchor is valid on the anchor’s authority, never on its own.

95.1.7.1.17. Two facts recorded for the learn stage

Decryption commits the plaintext over the bytes that arrived, so two things that only this stage can see are written to state.crypto.in for pepsi-stage-autocrypt-learn(1) to read: encrypted, that the message carried ciphertext at all, and outer_gossip, that the arriving header block already had an Autocrypt-Gossip: field. Both are preconditions for believing a message’s gossip, and neither is answerable once the plaintext is in the row.

95.1.7.1.18. Our own users’ keys are never overridden

Keys are harvested under the From: address, which the sender writes, and inbound authentication is deliberately fail-open. A message claiming to come from one of this deployment’s own users will therefore seed a peer_key row for that user with whatever key it carried — and a signature checked against it would otherwise verify, setting state.signature_verified, on which pepsi-stage-check-whitelist(1) gates.

So before the store is consulted, the stage asks whether the claimed sender is somebody for whom it holds an identity. If it is, that identity’s public key is the only candidate: no peer_key row for the address is offered to the verifier, whatever its rank and however it arrived. Anything but a revoked identity counts, expired ones included — a signature made last year was made with last year’s key, and refusing to look at it would report our own users’ mail as unverifiable every time a key rolled over.

The rule is conditional on holding a key, not on serving the address: a user who runs their own OpenPGP client and never uploaded a key here has no identity, so their harvested or gossiped key is used exactly as any correspondent’s would be. The cost is the mirror image — once an identity is held for an address, a signature made with that user’s separate personal key no longer verifies. See the manual’s Our own users’ keys are not discovered.

95.1.7.1.19. Trust anchors

X.509 anchors come from the pepsi.ca_trust table (pepsi-keys(1) ca) and are cached per worker process for TRUST_ANCHOR_TTL (default five minutes). An anchor added or disabled therefore becomes effective within that window; restart the workers to apply it at once. They are loaded lazily and only for a message that actually carries an S/MIME layer, so ordinary traffic costs no query.

Revocation data is not fetched by the stage: a CRL retrieval would be network I/O in a stage, which the discovery design exists to avoid. Instead pepsi-keydisc(1) fetches the CRLs that cached S/MIME peer certificates name into pepsi.crl_cache, and the stage reads the current ones with the anchors (lazily, for an S/MIME layer only, behind the same TRUST_ANCHOR_TTL). A list counts for a certificate only if the issuer’s key signed it, it is current and its scope covers the certificate; a listed serial makes the signature invalid (failure revoked). Every chain covered by such lists is reported not-revoked. Anything less – no list for a certificate in the chain, a stale or unverifiable one, a cache that cannot be read – is reported as revocation not-checked, which is stated rather than being allowed to imply “not revoked”: revocation checking soft-fails.

A path is built from the anchors, the certificates that the message carried, the sender’s cached keys and, under [pepsi-keydiscovery] CA_ISSUERS_FETCH, the intermediate CA certificates that pepsi-keydisc(1) fetched from the caIssuers pointers of cached certificates into pepsi.ca_issuer_cache (read like the lists, lazily and behind TRUST_ANCHOR_TTL). A fetched certificate is searched last, only as an issuer – never as a signer, never as an anchor – so it can complete the chain of a signer who sent no intermediates and can do nothing else. A sender’s certificate that the key store learnt from their mail does not end the search either: it is validated against the anchors like one the message carried, and its learnt standing (valid-untrusted) is reported only when no path reaches an anchor.

95.1.7.1.20. Configuration

The stage reads its own [stage-<name>] section (PROGRAM = pepsi-stage-decrypt, NEXT_STAGE (required), BOUNCE_STAGE, plus ENABLED, LOCAL_DOMAINS, TARGETS, RECIPIENT_DELIMITER, REQUIRE_ACCOUNT, ON_DECRYPT_FAILURE, ON_BAD_SIGNATURE, ON_MISSING_SIGNATURE, MISSING_SIGNATURE_WINDOW_DAYS, TAG_MISSING_SIGNATURE, MAX_SIGNATURE_AGE_DAYS, UNAUTHENTICATED_PLAINTEXT, DECRYPTED_MARKUP, OPEN_ENVELOPED_DATA, QUARANTINE_STAGE, SUBJECT_TAGS, TAG_DECRYPTED, TAG_VERIFIED, TAG_VERIFIED_EXCEPT_REPLY_TO, TAG_UNAUTHENTICATED, TAG_BAD_SIGNATURE, TAG_BAD_SIGNATURE_ENCRYPTED, TAG_UNVERIFIED_SIGNER, STRIP_SUBJECT_TAGS, STRIP_SUBJECT_KEYWORDS, ADD_RESULT_HEADER, ISOLATE_ENCRYPTED, ISOLATE_SIGNED, MAX_LAYERS, TRUST_ANCHOR_TTL, DISCOVERY, DISCOVERY_TIMEOUT), all documented in pepsi.conf(5). pepsi-setup(1) requires a BOUNCE_STAGE whenever ON_BAD_SIGNATURE is bounce or ON_DECRYPT_FAILURE is bounce-if-unproblematic, and a QUARANTINE_STAGE whenever any of ON_DECRYPT_FAILURE, ON_BAD_SIGNATURE and ON_MISSING_SIGNATURE is quarantine. Without a BOUNCE_STAGE a bounce route fails the message instead. A row with several recipients is split before it bounces, and each copy returns to this stage, so that a DSN reports on every recipient and honours each recipient’s NOTIFY. A message routed to the QUARANTINE_STAGE holds its decrypted plaintext for as long as it waits there; pepsi-queue(1) gc bounces one still waiting [pepsi-queue] QUARANTINE_MAX_AGE_DAYS (default 14) after its arrival, without its content – unless it came out of, or failed to open from, an EnvelopedData (AES-CBC) ciphertext: that one is dropped, as the bounce routes drop it, since whether it was held at all depended on the padding. Those are behavioural options and are per-address overridable through the pepsi.settings table.

The cryptographic policy — algorithm choice, weak-digest acceptance, minimum key sizes — lives in [pepsi]’s CRYPTO_* options and [pepsi-crypto]. Those are system-administrator-only and are deliberately not reachable from pepsi.settings or pepsi-stage-edit-settings(1).

One of them does not apply here. CRYPTO_ALLOW_DOWNGRADE governs what may be emitted: OpenPGP SEIPDv1+MDC and CMS EnvelopedData are readable whatever it says (only this stage’s own OPEN_ENVELOPED_DATA = no leaves the latter unopened), because refusing them inbound would make this host unable to receive mail from most of the world while protecting nobody. Only 3DES and the weak signature digests are gated inbound, and each refusal produces its own verdict rather than a generic failure. The 3DES gate is not the same on both sides: an inbound S/MIME 3DES message is accepted only under yes, an inbound OpenPGP one under negotiate as well, because an OpenPGP certificate states its own cipher capabilities and an X.509 one states none. OpenPGP Blowfish, the other 64-bit-block cipher, is gated exactly like OpenPGP 3DES. The container that was actually used is recorded per layer, so a deployment can see how much of its inbound mail is still pre-AEAD.

95.1.7.1.21. Privilege

The binary is installed setuid pepsi-crypto, mode 4750 pepsi-crypto:pepsi, and is therefore not folded into the unified pepsi multi-call binary.

Both halves of the key-custody boundary key on that identity. The database role pepsi-crypto is the only one granted crypto_identity.private_wrapped, and PostgreSQL peer authentication keys off the effective uid; the key-encryption key lives in secrets.d/pepsi-crypto.secret, mode 0640 owned by the same account. A setgid binary would gain the group — enough to read the fragment — and would still authenticate to the database as pepsi, precisely the role that is denied the column.

The group in the mode restricts execution to the dispatcher’s account and root; the program also refuses at run time unless its real uid is root or one of the pepsi, pepsi-crypto and pepsi-owner accounts. That run-time check applies only when the binary actually carries the setuid bit — a build installed without it (a developer tree, cargo test) lets anyone run it, on the grounds that such a caller reaches the database as themselves and PostgreSQL’s own grants are then the authority. -c is accepted from those callers (the dispatcher’s documented spawn shape is PROGRAM -c cfg worker) and the environment is sanitised before the configuration is loaded, because the configuration layer is steerable through XDG_CONFIG_HOME, HOME, PATH and the PG* family.

Decryption keys are selected by capability: every non-revoked identity of every local recipient whose purpose is encrypt or both, including expired ones, because old mail must stay readable.

95.1.7.1.22. Resource limits

MAX_LAYERS (default 4) caps how many nested encrypted layers are unwrapped; a message with more is delivered with the remainder unopened and decrypt-failure=unsupported recorded.

An OpenPGP message is routinely compressed and the expansion ratio is the sender’s choice, so pepsi-crypto refuses a plaintext over 64 MiB outright rather than truncating it — a partial plaintext must never be reported as verified. That case is reported as its own failure reason, decrypt-failure=too-large, and not as a generic decryption failure: “this message is a bomb” and “we could not open this” are different facts for an operator.

95.1.7.1.23. State

Inputs: state.dsn (honoured and sliced in lockstep with the locality split), state.crypto.in (on a resumed row, what the pass that decrypted it recorded).

Outputs: state.crypto.in — whether the message was encrypted, what became of the ciphertext (decryption: not-encrypted, decrypted, failed, for-client or withheld), which identity opened it, the signature verdict and its detail (including covers_plaintext), the ordered layer list, and, for mail to a user’s own key, for_client and client_fingerprint, and isolated, demoted and dropped when content beside the protected parts was moved or dropped, protected_mismatch when signed protected header fields differ from the outer ones, unauthenticated and sanitised for a plaintext from a container without integrity protection that no signature covers (Plaintext from a malleable container), and encrypted and outer_gossip for pepsi-stage-autocrypt-learn(1) (see Two facts recorded for the learn stage); on a failure, failure (the reason), failed_unauthenticated when the ciphertext that failed had no integrity protection, and route when a failure policy routed the message. Also state.encrypted = true when the message arrived encrypted, and state.signature_verified = true for the valid verdict only; pepsi-stage-check-whitelist(1) and pepsi-stage-auto-whitelist(1) read those. On a bounce, state.bounce. The state layout is described in pepsi.state(7).

Transitions: NEXT_STAGE for a delivered message; QUARANTINE_STAGE or BOUNCE_STAGE per the failure policies; paused while waiting for key discovery; pending at this same stage after a locality split.

95.1.7.1.24. Commands

worker

Run as a persistent dispatcher worker, reading message ids on standard input and writing one status line per message. This is the only mode; there is no one-shot form. To run a single message by hand, pipe its id:

echo 1234 | pepsi-stage-decrypt -c /etc/pepsi/pepsi.conf worker

95.1.7.1.25. Exit Status

0

The worker exited cleanly (standard input closed).

1

An error occurred (misconfiguration, an unreadable key store, or a database error). The reason is written to the log.

78

The worker refused to start: its configuration or key ring does not work (see Errors of this host). The dispatcher requeues what it handed over and retries the stage later.

95.1.7.1.26. See Also

pepsi-stage-encrypt(1), pepsi-stage-reencrypt(1), pepsi-stage-arc(1), pepsi-keys(1), pepsi-keydisc(1), pepsi-stage-check-whitelist(1), pepsi-stage-relay-to-maildir(1), pepsi-stage-relay-to-lmtp(1), pepsi-stage-bounce(1), pepsi-dispatch(1), pepsi-setup(1), pepsi.conf(5), pepsi.state(7)

The manual’s Security chapter states the mechanisms this stage implements (The private-key custody boundary, Who a signed and encrypted message was for, Protected headers against the outer ones, Header forgery, Protected content stands alone, Bounces and replies to encrypted mail); its Threat model chapter states what they promise (What a security indicator means, End-to-end encryption: two custody modes).

95.1.7.1.27. Bugs

Report bugs to the Pepsi issue tracker.