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:
noneThe message carries no signature.
validCryptographically sound and the key was anchored: an X.509 chain to a configured
ca_trustanchor, 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 theFrom:line as the reader sees it (What valid is granted for).partialWould 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 thanHash:between theBEGIN PGP SIGNED MESSAGEmarker and the text (the armor reader accepts anyKey: valueline there and hashes none of it), or a block that is the body of atext/htmlpart, 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 setstate.signature_verified.X-Pepsi-Cryptosays which (unsigned-surface=armor-headersorhtml).valid-untrustedCryptographically sound, but the key could not be tied to anything: a key seen for the first time, learnt from the message itself, from an
Autocryptheader 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 withheldvalid— a signature over ciphertext only, a protectedFrom:or reply-steering field that differs, a certificate naming no mailbox, a display name showing another address, aFrom:with several mailboxes, a signer domain that looks like a known one, a signature made long before the message arrived;withheld=inX-Pepsi-Cryptoandsignature.withheldin 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.
invalidThe 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 thesigningTimethe signature claims, and a mailbox name that is not a barelocal@domainmatches noFrom: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 isinvalidtoo, with the layer verdictwrong-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.unverifiableNo 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), reasondisplay-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; reasonmultiple-from;the certificate names no mailbox and chains to a
ca_trustanchor — it contradicts noFrom:, so the binding cannot fail it, but it vouches for no address either, and would otherwise bevalidfor every sender. Reasonno-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 afromwhitelist row, while the domain itself differs. Reasonlookalike-domain, and the domain’s A-label is written toX-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 bevalid, cached forTRUST_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 protectedSubject:carries a forged indicator (Protected headers), reasonsprotected-from,reply-toandprotected-subject;the signature was made long before the message arrived: its creation time (the OpenPGP signature creation time, the S/MIME
signingTimeattribute) lies more thanMAX_SIGNATURE_AGE_DAYS(default 7) before the row’s arrival time, reasonold-signature, or more than a day after it, reasonfuture-signature. A captured signed message replayed under a fresh outerSubject:orDate: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 theDate:field, which the replayer writes. A signature without a creation time (CMS withoutsigningTime) is not judged, and0turns the check off. Mail legitimately delivered late (a list moderation queue, a message forwarded as it is) loses only the tag.X-Pepsi-Cryptoshows 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 outerFrom:’s (compared as addr-specs of the first mailbox, case-insensitively, display names and comments ignored) withholdsvalid: the signature is reportedvalid-untrusted(withheld=protected-from), earns no[verified]tag and does not setstate.signature_verified. The signer vouched for a message from somebody else; a signed message re-sent under a new outerFrom:(surreptitious forwarding) is the shape this catches. A protected block with twoFrom:fields that disagree, or one with no legible address, counts as a difference. Only the positive verdict is withheld;invalidandunverifiableare unchanged. Mailing-list software that rewrites the outerFrom:of signed mail therefore costs such mail itsvalid, never more.A reply-steering field —
Reply-To:,Mail-Reply-To:orMail-Followup-To:— that differs withholdsvalidthe 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 aList-Id:and the signer protected none of the three: the signature staysvalidand the tag reads[verified (except reply-to): …](TAG_VERIFIED_EXCEPT_REPLY_TO,reply-to=unsignedinX-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 losesvalid, 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 andRe:-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 aRe:. A larger difference is reported, and when the signature is otherwisevalidthe signed subject is shown in place of the outer one (subject=protectedinX-Pepsi-Crypto,state.crypto.in.subject_promoted), so the message keeps[verified]under the subject its signer wrote. A marker written without brackets, such asEXTERNAL:, is thereby removed; so is anything else added on the way. Header protection replaces the outerSubject:by design, so an outer...or[...]is not a difference and nothing is promoted over it.A protected
Subject:that carries a forged indicator withholdsvalid(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 reportedvalid-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 keepsvalid.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 = passthroughThe 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.
quarantineandbounce-if-unproblematicare available. The valuebounceis an alias for the longer but unambiguousbounce-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 = recordA 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.
quarantineandbounceare available;bouncedrops 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-Cryptogainsusually-signed=<date of the last valid signature>andstate.crypto.in.usually_signedrecords 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.tagAlso prepends
TAG_MISSING_SIGNATURE(default[unsigned, usually signed]) to theSubject.quarantineRoutes 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, anapplication/pkcs7-mimepart 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 atext/plainpart holding only the armor, and the text that surrounded it becomes an attachment of its own. Every moved part is rewritten asapplication/octet-streamwithContent-Disposition: attachment, a sanitised file name (the sender’s, orpart-N.html,message-N.eml,encrypted-N.ascand the like), aContent-Descriptionsaying that Pepsi moved it and that the message’s protection does not cover it, and noContent-ID,Content-LocationorContent-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 anapplication/octet-streamattachment 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 atext/*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/MIMESignedDataor an inline clearsigned block — next to unsigned content, the unsigned content is dropped (several signed units are kept together in amultipart/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,.ascor.p7msuffix (report.pdf.pgparrives asreport.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
validorvalid-untrustedsignature made by the same key as the message’s. This is the encrypted counterpart ofISOLATE_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;
mreads asrn), 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, andSTRIP_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,authenticand their close forms) or a word of our own tags; a leadingVerified:-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.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:
encryptedyes/no— the message arrived carrying ciphertext. What counts is the packet stream, not the label: an armoredPGP MESSAGE(or amultipart/encryptedbody) that holds only a literal or signed OpenPGP packet opens without any key, its content is delivered, and it is reportedencrypted=no, with no[decrypted]tag and no identity recorded as having opened it. A signature inside it is still verified.decryptedyes/no— present only whenencrypted=yes.for-clientyeswhen the message is encrypted to the recipient’s own MUA key and was passed through unopened (Mail for the user’s own key).protocolopenpgporsmime.containerThe content-encryption container of the opened ciphertext, as the decryptor read it from the bytes:
auth-enveloped-dataorenveloped-data(S/MIME),seipdv2-aeadorseipdv1-mdc(OpenPGP). Onlyenveloped-datalacks integrity protection. Present when a ciphertext was opened.signatureOne of the verdicts above.
signer,fingerprint,key-source,trust,algorithmThe signing key, where it came from and what it was worth.
key-sourceandtrustboth carry the verifier’s provenance word (anchor,dane,wkd,pinned,autocrypt,attachedorunknown). Present only when known.bindingHow the signer’s key related to the
From:address as the verifier saw it:matched,mismatchedorno-identity(the key names no address). Present when a key was found.anchorThe fingerprint of the
ca_trustanchor the signer’s chain ended at. Present for an anchored S/MIME signature.bound-toThe address a
validsignature is bound to — theFrom:address as written, which the tag names. Present only onvalid.signed-atThe 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).withheldWhy a signature that verified is
valid-untrustedrather thanvalid:ciphertext-cover,protected-from,protected-subject,reply-to,no-identity,display-name,multiple-from,lookalike-domain,old-signatureorfuture-signature(What valid is granted for). Present only then.unsigned-surfaceWhy a verified clearsigned block is
partial:armor-headersorhtml. Present only then.reply-tounsignedwhen the signature isvalidand the outerReply-To:(orMail-Reply-To:,Mail-Followup-To:) was added by a mailing list outside it (the[verified (except reply-to)]tag). Present only then.signer-domainThe signer’s domain as an A-label, when it is an internationalised domain name or looks like a known one. Present only then.
usually-signedThe date (UTC,
YYYY-MM-DD) avalidsignature from theFrom: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.failureThe machine-readable reason a signature verdict is not good.
decrypt-failureThe machine-readable reason decryption failed.
unauthenticatedyeswhen the plaintext came out of a container without integrity protection and no valid signature covers it (Plaintext from a malleable container). Present only then.sanitisedtextwhen the plaintext was reduced to content no client renders as markup (UNAUTHENTICATED_PLAINTEXT = text, orDECRYPTED_MARKUP = textfor any decrypted plaintext). Present only then.isolatedWhich rules of Isolating protected content changed the message (
encrypted,signed), comma separated. Present only when one did.protected-mismatchThe 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.subjectprotectedwhen the signer’s protectedSubject:was shown in place of an outer one changed in transit. Present only then.demoted,droppedHow 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.
nestedHow many attached messages carrying ciphertext beside other content were reduced (Isolating protected content). Present only when not zero.
layersThe 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/enrichedand the othertext/*types,application/xhtml+xml, inside an attached message too – is relabelledtext/plainwith its charset kept and loses itsContent-ID,Content-LocationandContent-Base; amultipart/alternativeoffering 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. TheSubjectis taggedTAG_UNAUTHENTICATED([decrypted, unauthenticated]) in place ofTAG_DECRYPTED, andX-Pepsi-Cryptosaysunauthenticated=yes; sanitised=text.require-signatureThe 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.
decryptionreadswithheld, no identity is recorded as having opened the message, nothing is tagged, andON_DECRYPT_FAILUREis 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.openThe plaintext is delivered as it came out of the container, markup included, for a site that accepts the exposure. It is still tagged
TAG_UNAUTHENTICATEDand recordedunauthenticated=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.