37. pepsi-stage-encrypt¶
Sign outgoing mail as its author, and encrypt it to each recipient.
37.1. Role¶
pepsi-stage-encrypt is the outbound half of Pepsi’s end-to-end cryptography.
For every locally submitted message it resolves what protection was asked for
and applies it: it signs with the key of the From: author, then encrypts to
the recipient’s key. It then routes each recipient onward. It performs no network I/O: a
recipient whose key is not cached pauses the message and a
pepsi-keydisc service releases it. Reference:
pepsi-stage-encrypt(1).
It writes the same two standards that pepsi-stage-decrypt reads: RFC 9580 with the RFC 3156 PGP/MIME containers for OpenPGP, and RFC 5652 CMS with the RFC 8551 profile for S/MIME. The writing side, however, has two choices that the reading side does not have, and both are visible in the configuration:
Which container to encrypt into. For OpenPGP this is negotiable: a certificate states which SEIPD versions its owner can read, so
CRYPTO_ALLOW_DOWNGRADE = negotiateemits RFC 9580 SEIPDv2 (AEAD) to a correspondent whose key says they can read it and SEIPDv1+MDC to one whose key says they cannot. An X.509 certificate advertises no content-encryption capability, so for S/MIME the stage reads the recipient’s capability record (The per-peer S/MIME capability record). The record is learnt from theSMIMECapabilitiesof the correspondent’s signed mail, or configured withpepsi-keys peer capability set. The stage emits RFC 5083/5084AuthEnvelopedData(AES-256-GCM) unless that record says the recipient cannot read it; in that case it emits RFC 3565 AES-256-CBCEnvelopedData. A recipient with no record gets AEAD, so a Thunderbird user who has never sent a signed message needs a configured record. Client interoperability records which clients are known to read which.Which recipient info to build, which is not a choice: it follows from the key type in the recipient’s certificate. RSA gets an RFC 5652 §6.2.1
KeyTransRecipientInfo(RFC 4055 RSAES-OAEP, or PKCS#1 v1.5 where required), and an EC certificate gets an RFC 5753KeyAgreeRecipientInfowith the content key wrapped per RFC 3394.
Inline (non-MIME) OpenPGP is never written; everything emitted is PGP/MIME.
Warning
Put this stage before the DKIM-signing stage. The recommended outbound
chain is submission → … → encrypt → srs → dkim-sign → relay. DKIM must
sign the bytes that are actually transmitted; the other way round produces
valid-looking mail whose signature does not verify, which is worse than no
signature. pepsi-setup warns when it finds the two the wrong way round.
37.2. Features¶
The signer is the author. Signing uses the key of the
From:address, never the envelope sender: the signature is about the author the recipient sees. Mail from an author that this deployment does not serve, or holds no material for, is sent unsigned rather than bounced: it is still legitimate mail, and DKIM already carries the domain-level claim. An OpenPGP signature made inside the ciphertext names the recipient’s certificate (RFC 9580 Intended Recipient Fingerprint), so a recipient cannot re-encrypt it to a third party as if it had been signed for them.Signed content is 7-bit. Before signing, an 8-bit body is converted to quoted-printable or base64 (RFC 3156 section 5), so a next hop without
8BITMIMEdoes not invalidate the signature; the conversion is skipped where pepsi-stage-dkim-sign skips it, for example when the author’s client already signed a part.One ciphertext per recipient. Every encrypted recipient gets their own ciphertext on their own queue row. So no ciphertext names the other recipients, no content key is shared, and no ciphertext reveals a
Bccrecipient. When the recipients of one message diverge, the stage splits them one per row, slicingstate.dsn.rcptin lockstep, and each row re-enters this stage alone. Recipients that all share an outcome are never split.Protocol per recipient. The stage uses OpenPGP (PGP/MIME, RFC 3156) or S/MIME (CMS, RFC 8551), whichever has the best-ranked key.
PREFERdecides only between keys on the same rung of the trust ladder, so a forgedAutocrypt:header cannot outrank a better-sourced S/MIME certificate. An author signing with one protocol and encrypting to the other still signs inside the ciphertext.Per-recipient container negotiation. Under the default
CRYPTO_ALLOW_DOWNGRADE = negotiate, OpenPGP falls back to SEIPDv1+MDC only when the recipient’s own certificate proves it cannot read AEAD, and S/MIME to AES-256-CBCEnvelopedDataonly when the recipient’s capability record says so. Such a fallback follows from a fact about the correspondent, and it is logged and recorded, never silent.An explicit policy for “no key”.
ON_NO_KEYderives fromENCRYPT:opportunisticsends ordinary mail,requireduses the secure-link portal when one is configured and bounces otherwise.requirednever degrades to cleartext. A revoked or expired key is no key: an S/MIME certificate outside its validity period or an OpenPGP key past its expiry is set aside before the choice, and the recipient’sreasonsays so with the date.The author hears about cleartext when they ask to.
NOTIFY_CLEARTEXT = author(off by default, per-address overridable) sends the author of a local message one notice per copy that left unencrypted, naming the recipients and the reason; the keyless recipients of a message share one copy. A subject that starts with a near miss of a request keyword ([encyrpt],[encrypted], a look-alike letter) is answered with a warning naming the keyword, always.Request headers never reach the wire.
X-Pepsi-SignandX-Pepsi-Encrypt(set by the Outlook add-in) are stripped from every outgoing message whatever they said, and are ignored entirely unless the message is local-origin. A matched subject keyword is removed from theSubjecttoo, and so are Pepsi’s own indicator tags ([verified: …],[decrypted],[external]and the rest, as configured) before the subject is signed or protected: a reply does not carry a local indicator to its recipient, where the protected copy would read as a forged one. See Indicator tags do not leave the deployment.A visible size cap.
MAX_SIZE(default 25 MB) bounds what is encrypted: neither the CMS builder nor the OpenPGP paths stream, so the whole message is resident once per recipient. Above the cap,ON_OVERSIZEdecides.Length padding.
PADDING(default on) pads every encrypted message to a Padmé length, at most 12 % longer: an RFC 9580 padding packet inside a SEIPDv2 container, aPepsi-Padding:filler header field on the encrypted entity for SEIPDv1 and S/MIME. See The length of an encrypted message.The pEp preset.
ENABLE_PEP(default on) is a preset of defaults, not a forcing mode: it makesSIGNdefault toencrypted-only(sign only what is encrypted, inside the ciphertext) and creates an OpenPGP key for a local sender at a served domain on their first submission, when the address has no identity of any kind and[pepsi-crypto] AUTO_CREATE_IDENTITYallows it. WithENABLE_PEP = noa key is created only when an author explicitly asks for protection (a signature or only encryption) or underSIGN = always. The key’s owning login is resolved through[pepsi-crypto]’s locality options, as forpepsi-keys. Any option written out explicitly still wins.The user’s own key. A local sender who may speak for the
From:address can register the key that their mail client holds (from itsAutocrypt:header, or an attached key for the address’s first key) as an MUA key (custody = client). It becomes the address’s public face: local mail is encrypted to it, WKD serves it, and Pepsi then adds noAutocrypt:header or key file of its own.Mail the client already protected is left alone. A submission whose outermost layer is ciphertext is not encrypted, signed or given a key a second time (
state.crypto.out.client_protected). A submission that the client signed may still be encrypted, but gets no signature of Pepsi’s.The key as a file.
ATTACH_KEYS_AS_FILES(default off) also attachesOpenPGP_0x<long key ID>.ascuntil every recipient has proved that they hold the key; on an encrypted message, the file goes inside the ciphertext.Keys by e-mail. With
RESPONSE_STAGEset, a message toKEYS_CONTROL_LOCAL_PART@<served domain>(defaultpepsi-keys@) is a key command (status,generate,register,publish,retire,pin,otp enroll,otp confirm,otp remove) and is answered rather than relayed. A command other thanstatusunder a reply or forward prefix (Re:,Fwd:, …) is refused, since an outsider may have written it and the user only answered it. An address with an enrolled TOTP second factor (A second factor for key management) must put the current code in the subject of every command butstatus, and registers no key from itsAutocrypt:header.otp enrollsets up a secret that takes over only onceotp confirm CODEconfirms it withinOTP_CONFIRM_WINDOW(default one hour); the reply carrying the secret is encrypted to the user’s own (MUA) keys when they have any, and carries anExpires:header.It advertises the author’s key.
AUTOCRYPT(default on) adds an Autocrypt Level 1Autocrypt:header to every locally submitted message that the stage commits, the plain cleartext pass-through included, since a correspondent must learn the key before there is anything to encrypt with. The header carries the minimal transferable public key of an OpenPGP identity whose private half this deployment still holds. It is never added over a header that the author’s own MUA set, nor when the public face is an MUA key, andprefer-encrypt=mutualis claimed only when the configuredENCRYPTisrequired. On the encrypting path the field goes on the outer header block.Gossip is opt-in.
AUTOCRYPT_GOSSIP(default off) additionally renders oneAutocrypt-Gossip:field per other recipient inside the protected part, because that redistributes third parties’ key material to correspondents who never asked for it. Gossip covers only the addresses in the parsedTo:/Cc:, so aBccrecipient can never be gossiped. It is OpenPGP only and triggers no discovery (an uncached address is dropped, never parked), and above 50 visible recipients there is no gossip at all.GOSSIP_MIN_TRUST(defaultowner-confirmed) is a floor of its own, since republishing a key is not the same act as using one; the floor applied is the stricter of it andMIN_TRUST.Weak and compromised keys are not used. Three kinds of recipient key count as no key at all: a key below
CRYPTO_MIN_RSA_BITS, an RSA modulus whose factors can be computed (ROCA, Fermat, a small factor), and a key on the known-compromised list (pepsi.compromised_key: the badkeys blocklist thatpepsi-keys blocklist updatekeeps current, and the daily batch GCD ofpepsi-keys peer screen).A DNS failure is not “no key”. Where the no-key route would be cleartext, the stage handles a recipient whose key lookup failed in the DNS (A key lookup that fails in the DNS) by what the domain does. While the domain does not answer, the recipient is deferred and bounced with
5.4.3afterMAX_LIFETIME(at most 120 h), with one delay DSN afterDELAY_DSN_AFTER(default 4 h) if the sender asked for one. When the domain answers but its key records keep failing, the recipient is routed toSECURE_LINK_STAGE(or bounced). A local sender accepts cleartext with the[clear-ok]subject keyword (SUBJECT_KEYWORDS_CLEAR_OK) orCLEAR_ON_DNS_FAILURE = yes.Header protection is opt-in.
PROTECT_HEADERS(default off) copies the RFC 5322 fields into the protected entity (RFC 9788 injected headers) and replaces the outerSubjectwith...; pepsi-stage-decrypt compares such a protectedFrom:with the outer one (Protected headers against the outer ones), and the protectedTo:/Cc:put the recipients inside the signature. It is off because a client that cannot render protected headers shows...as the subject; a population whose clients can render them turns it on.A signature says whom it was for. Signed-and-encrypted OpenPGP names the recipient certificates in Intended Recipient Fingerprint subpackets, and S/MIME names them in a private signed attribute (Who a signed and encrypted message was for), so a recipient cannot re-encrypt the signed message to a third party as if it had been signed for them.
RFC 9709 for those who ask. An S/MIME recipient whose own signed
SMIMECapabilitiesnameid-alg-cek-hkdf-sha256gets a content key derived over the algorithm identifier, which stops a captured AES-GCM message being re-submitted as AES-CBC under the same key; Pepsi’s own signatures advertise it.Pepsi’s own notices can be signed. With
NOTICE_SIGNERset, an instance of this stage signs every message that Pepsi composed itself with one identity of the deployment, published in its Web Key Directory, and never encrypts these messages (Signed notices, Forged notices). They are sign-in and portal links, secretary challenges, payment requests, command replies, and key-change and out-of-office notices; the stage recognises them by thestate.noticemark that their emitter set. The wizard writes such a[stage-notice]with the option commented out and points the notice emitters at it.
37.3. Where it sits¶
submission → aliases → anti-spam → detect-language → encrypt → srs → dkim-sign → relay
The two neighbours that read the message body, the pay-to-send gate and language detection, need cleartext; they get it because encryption comes last. ARC does not apply: it is for mail relayed on someone else’s behalf, and this stage signs and encrypts only mail that Pepsi originated.
A message that is not local-origin is advanced untouched (with its
X-Pepsi-* headers stripped): encrypting a relayed third-party message would
invalidate the originator’s DKIM signature and ARC chain.
37.4. Configuration¶
[stage-<name>]: PROGRAM = pepsi-stage-encrypt, NEXT_STAGE (required)
and BOUNCE_STAGE, plus ENABLE_PEP, SIGN, ENCRYPT,
ATTACH_KEYS_AS_FILES, KEYS_CONTROL_LOCAL_PART, OTP_CONFIRM_WINDOW,
RESPONSE_STAGE, PREFER, ON_NO_KEY,
ON_OVERSIZE, PADDING, MIN_TRUST, SUBJECT_KEYWORDS_SIGN / _ENCRYPT /
_BOTH, STRIP_REQUEST_HEADERS, PROTECT_HEADERS, MAX_SIZE,
AUTOCRYPT, AUTOCRYPT_GOSSIP, GOSSIP_MIN_TRUST,
SECURE_LINK_STAGE, DISCOVERY, DISCOVERY_TIMEOUT,
SUBJECT_KEYWORDS_CLEAR_OK, CLEAR_ON_DNS_FAILURE, DELAY_DSN_AFTER,
NOTICE_SIGNER and NOTIFY_CLEARTEXT. pepsi-setup requires a
BOUNCE_STAGE whenever ON_NO_KEY/ON_OVERSIZE resolve to bounce,
and checks that SECURE_LINK_STAGE and RESPONSE_STAGE name real stages.
All are documented in pepsi.conf(5).
Those are behavioural options and are per-address overridable through the
pepsi.settings table (keyed, for outbound mail, on the envelope sender),
except NOTICE_SIGNER, which the stage reads from the configuration file
alone. The cryptographic policy lives in [pepsi]’s CRYPTO_* options
and [pepsi-crypto]: which algorithms, whether a downgraded container may be
emitted, minimum key sizes. Only the system administrator sets it, and it is
deliberately not reachable from pepsi.settings or from
pepsi-stage-edit-settings.
37.5. Privilege¶
Installed setuid pepsi-crypto, mode 4750 pepsi-crypto:pepsi, and
therefore standalone rather than folded into the unified pepsi binary.
Both halves of the key-custody boundary depend 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 is a 0640 fragment owned by the same account. A setgid
binary would reach the fragment and still authenticate to the database as
pepsi, the role that is denied the column. See Key management for
the custody model, The private-key custody boundary for the mechanism and End-to-end encryption: two custody modes for
what it claims. The custody split protects a key’s disclosure, not its use:
the stage signs as the queue row’s From:, which any pepsi stage may
rewrite after ingress checked it; the threat model documents this residual.
37.6. State¶
Reads state.local_origin and state.notice.
Writes state.crypto.out: whether the message was signed, by which identity,
and one entry per recipient carrying outcome, protocol, fingerprint,
key_source, trust, content_algorithm and downgraded, plus
key_attached and client_protected when they apply. Sets
state.encrypted = true when something was encrypted: the key that
pepsi-stage-auto-whitelist reads for its signature_required column.
On a policy bounce it writes state.bounce with a 5.7.0 enhanced status
(5.4.3 for a recipient whose DNS kept failing); while a message is deferred on
a recipient DNS failure, state.encrypt_dns_deferred, state.last_error and,
once a delay DSN went out, state.delay_sent.
Every cleartext outcome reached while encryption was wanted is logged at
WARN: sending unprotected mail is never a silent event.
37.7. See also¶
pepsi-stage-decrypt (the inbound half), pepsi-stage-secure-link
(where the secure-link no-key route leads), pepsi-stage-dkim-sign,
pepsi-keys, pepsi-keydisc, Key management (identities,
custody and the trust ladder that this stage’s MIN_TRUST selects on),
The secure-link fallback portal, Who a signed and encrypted message was for,
Which S/MIME container a correspondent gets, Keys of correspondents,
Client interoperability (which clients have been
measured against what this stage emits), RFC Index,
pepsi.conf(5), pepsi.state(7)