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 = negotiate emits 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 the SMIMECapabilities of the correspondent’s signed mail, or configured with pepsi-keys peer capability set. The stage emits RFC 5083/5084 AuthEnvelopedData (AES-256-GCM) unless that record says the recipient cannot read it; in that case it emits RFC 3565 AES-256-CBC EnvelopedData. 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 5753 KeyAgreeRecipientInfo with 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 8BITMIME does 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 Bcc recipient. When the recipients of one message diverge, the stage splits them one per row, slicing state.dsn.rcpt in 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. PREFER decides only between keys on the same rung of the trust ladder, so a forged Autocrypt: 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-CBC EnvelopedData only 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_KEY derives from ENCRYPT: opportunistic sends ordinary mail, required uses the secure-link portal when one is configured and bounces otherwise. required never 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’s reason says 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-Sign and X-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 the Subject too, 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_OVERSIZE decides.

  • 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, a Pepsi-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 makes SIGN default to encrypted-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_IDENTITY allows it. With ENABLE_PEP = no a key is created only when an author explicitly asks for protection (a signature or only encryption) or under SIGN = always. The key’s owning login is resolved through [pepsi-crypto]’s locality options, as for pepsi-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 its Autocrypt: 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 no Autocrypt: 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 attaches OpenPGP_0x<long key ID>.asc until 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_STAGE set, a message to KEYS_CONTROL_LOCAL_PART@<served domain> (default pepsi-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 than status under 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 but status, and registers no key from its Autocrypt: header. otp enroll sets up a secret that takes over only once otp confirm CODE confirms it within OTP_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 an Expires: header.

  • It advertises the author’s key. AUTOCRYPT (default on) adds an Autocrypt Level 1 Autocrypt: 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, and prefer-encrypt=mutual is claimed only when the configured ENCRYPT is required. On the encrypting path the field goes on the outer header block.

  • Gossip is opt-in. AUTOCRYPT_GOSSIP (default off) additionally renders one Autocrypt-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 parsed To:/Cc:, so a Bcc recipient 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 (default owner-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 and MIN_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 that pepsi-keys blocklist update keeps current, and the daily batch GCD of pepsi-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.3 after MAX_LIFETIME (at most 120 h), with one delay DSN after DELAY_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 to SECURE_LINK_STAGE (or bounced). A local sender accepts cleartext with the [clear-ok] subject keyword (SUBJECT_KEYWORDS_CLEAR_OK) or CLEAR_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 outer Subject with ...; pepsi-stage-decrypt compares such a protected From: with the outer one (Protected headers against the outer ones), and the protected To:/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 SMIMECapabilities name id-alg-cek-hkdf-sha256 gets 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_SIGNER set, 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 the state.notice mark 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)