95.1.6. pepsi-stage-encrypt

sign outgoing mail as its author and encrypt it to each recipient

Manual section:

1

95.1.6.1.1. Name

pepsi-stage-encrypt - outbound end-to-end signing and encryption stage of the Pepsi pipeline.

95.1.6.1.2. Synopsis

pepsi-stage-encrypt [GLOBAL-OPTIONS] worker

95.1.6.1.3. Description

pepsi-stage-encrypt is a stage program run by pepsi-dispatch(1) as a persistent worker reading message ids on standard input. For every locally submitted message it decides what protection to apply, applies it, and routes each recipient onward.

The name understates the stage: it signs as well as encrypts, in that order (sign inside, encrypt outside). Signing uses the key of the From: author, never the envelope sender — the signature is about the author that the recipient sees, and a signature whose identity does not match is what verifiers flag. If the From: address is not one that this deployment serves, or holds no signing material, the message is sent unsigned rather than bounced: an unservable author is still legitimate mail, and DKIM already carries the domain-level claim.

An OpenPGP signature made inside the ciphertext names the recipient’s certificate (an RFC 9580 Intended Recipient Fingerprint subpacket), so a recipient who decrypts the message and re-encrypts it, still signed, to a third party cannot pass it off as signed for them: a verifier that checks the subpacket, pepsi-stage-decrypt(1) included, reports it as not addressed to it. An S/MIME signature made inside the ciphertext does the same with a private signed CMS attribute that lists the SHA-256 of every recipient certificate (object identifier 1.3.6.1.4.1.32473.808069.1, provisional until the project holds an IANA enterprise number); pepsi-stage-decrypt(1) checks it like the OpenPGP subpacket, and other S/MIME clients ignore it, as RFC 5652 requires for any signed attribute that they do not know. For those clients the protected To: and Cc: of PROTECT_HEADERS (off by default) carry the recipients inside the signature instead. A cleartext signature names nobody.

Before signing, an 8-bit body is converted to quoted-printable or base64, as RFC 3156 section 5 requires of signed content: a next hop that does not offer 8BITMIME would otherwise make the relay re-encode the signed parts and the signature would no longer verify. This applies inside a ciphertext too, because the recipient’s gateway may decrypt the message and relay it on. The conversion is the one that pepsi-stage-dkim-sign(1) applies, and it is skipped in the same cases, for example when the author’s own client already signed a part.

Encryption is per recipient. Every recipient that gets ciphertext gets their own ciphertext and their own queue row: no ciphertext names the other recipients, no content key is shared between recipients, and no ciphertext reveals a Bcc recipient. Grouping S/MIME recipients into a single EnvelopedData would be cheaper and is what the format is for, but it reveals the recipient set to each recipient and lets one compromised key open the message for all of them.

The stage performs no network I/O of any kind. When a recipient’s key is not in the cache, the stage pauses the message and enqueues a discovery request; a pepsi-keydisc(1) service releases it when the request settles, whether or not a key was found. A recipient with a fresh negative cache entry takes the no-key path immediately, with no pause, because there is nothing to wait for. A recipient whose best key is one that nobody published — harvested from their own mail, signed or not, or gossiped — is encrypted to it without a pause, and a discovery request is raised in the background, at most once per [pepsi-keydiscovery] NEGATIVE_TTL and never while one is pending or a fresh negative answer stands, so that a key that the owner published (WKD, DANE, a key server) can replace the harvested one for the next message.

A message this deployment did not originate (no state.local_origin) is advanced untouched. Encrypting a relayed third-party message would invalidate the originator’s DKIM signature and ARC chain, and signing it as one of our users would be a lie. Its X-Pepsi-* request headers are still stripped, so an outside sender cannot leave Pepsi’s own control channel on the wire.

Warning

Place this stage before pepsi-stage-dkim-sign(1), not after.

The recommended outbound chain is:

submission -> ... -> encrypt -> srs -> dkim-sign -> relay

DKIM must sign the bytes that are actually transmitted. If DKIM signing runs first, this stage rewrites the body underneath the signature and the result is mail that looks perfectly valid and whose signature does not verify — which is worse than no signature at all, because a broken signature is a stronger negative signal to a receiver than an absent one. pepsi-setup(1) warns when it finds a DKIM-signing stage that leads to this one.

Two other neighbouring stages need cleartext and get it: the pay-to-send gate (pepsi-stage-anti-spam(1)) and language detection (pepsi-stage-detect-language(1)) read the message body, and on the outbound path they run before this stage. That is why encryption is last.

95.1.6.1.3.1. Policy resolution

What protection a message asks for is resolved from four inputs, most specific first:

  1. the state.local_origin gate — nothing below it applies to a message that we are merely forwarding;

  2. the request headers that an add-in set (X-Pepsi-Sign, X-Pepsi-Encrypt, each yes / no / required);

  3. a subject keyword (SUBJECT_KEYWORDS_SIGN / _ENCRYPT / _BOTH);

  4. the [stage-encrypt] defaults SIGN and ENCRYPT, which already carry any per-address override from the pepsi.settings table.

The two request headers are stripped from the outgoing message whatever they say and whatever STRIP_REQUEST_HEADERS is set to: a control channel that survives onto the wire is a control channel that the next hop can be told to obey. A matched subject keyword is likewise removed from the Subject.

So are Pepsi’s own indicator tags, on every message a local user sends and before the subject is signed or copied into the protected headers: a reply to [verified: a@example.org] report goes out as Re: report. The tags are the built-in [decrypted], [verified] in every shape ([verified: …], [verified (except reply-to): …]), [decrypted, unauthenticated], [unverified signer], [bad signature], [unsigned, usually signed] and [external], and whatever the decrypt stages’ TAG_* options and [pepsi-ingress] TAG_EXTERNAL configure. They are statements that this deployment made to its own user and mean nothing to the recipient; inside a signed message’s protected headers a receiving decrypt stage would read them as a forged indicator and withhold valid. They are matched as the inbound strip matches them, by skeleton, at the front of the subject and behind Re:/Fwd: prefixes and list tags, but only in their bracketed form; everything else in the subject is left as the user wrote it.

An encrypting subject keyword (SUBJECT_KEYWORDS_ENCRYPT or _BOTH) or an X-Pepsi-Encrypt: required header raises the policy to required for that message, and required never degrades to cleartext — if the resolved ON_NO_KEY says cleartext, it is raised to the secure link (or a bounce) for that message. A user who explicitly asked for protection is not silently ignored.

With ENABLE_PEP = no, key material is created only when a message asks for it: an explicit request of any kind (X-Pepsi-Sign/X-Pepsi-Encrypt other than no, or any subject keyword – an [encrypt] keyword under SIGN = no included), or SIGN = always unless X-Pepsi-Sign: no refused the signature. When [pepsi-crypto] AUTO_CREATE_IDENTITY is on, a KEY_WRAP_SECRET is configured, the From: domain is one of [pepsi-ingress] ACCEPTED_DOMAINS and the author has no identity of any kind, one is generated inline, in the protocol of the recipient’s key when the message is being encrypted and in PREFER’s protocol otherwise. An address that merely appeared in an envelope never triggers this, so a user who never uses the feature never has key material and is never exposed by it. Under the default ENABLE_PEP = yes a key is instead created on the sender’s first submission, request or not; see The pEp preset below.

Whichever way it is created, the identity’s owner is the passwd login that [pepsi-crypto]’s LOCAL_DOMAINS, TARGETS and RECIPIENT_DELIMITER resolve the address to, exactly as for pepsi-keys(1); none when the address is a role address or a hosted domain.

Either way, automatic creation is refused for an address that already has a crypto_identity row of any kind – an MUA key registered by the user, an imported public-only key, or a revoked key. A [sign] keyword from a user who brought their own key therefore does not mint a second key behind their back; a user who wants a server-managed key next to their own asks for one explicitly (the generate command below, pepsi-keys identity generate, or the web console).

A key that should be created and cannot be – the database refuses the write, generation itself errors – is logged at warn, and the message proceeds as for an address with no key: its policy decides whether it goes unsigned or is refused. The user did not ask for the key to be made, and holding their mail hostage to a broken key store is worse than sending it without one. (A deployment with no KEY_WRAP_SECRET creates no keys at all and is not affected.) Registering the key that a user’s client advertises is best-effort in the same way.

Once a signing key exists and cannot be opened (an unreadable key-encryption key, a revoked grant), the message is not sent unsigned: that error is retried until the stage’s MAX_LIFETIME (see pepsi-dispatch(1)), like every other fault of this host, since sending unsigned would hide a broken deployment. 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), and the dispatcher holds the queue until it is fixed.

95.1.6.1.3.2. The pEp preset

ENABLE_PEP (default yes) makes the stage behave like the pretty Easy privacy (pEp) project: every local sender gets a key, mail is encrypted whenever a recipient’s key is known or discoverable, and the sender’s public key goes out with every message. It is a preset of defaults, not a forcing mode: it changes the defaults of other options, and any option written out explicitly in the section (or in a per-address pepsi.settings override) still wins.

Behaviour

ENABLE_PEP = yes

ENABLE_PEP = no

SIGN default

encrypted-only

opportunistic

Key creation

eager (first submission)

on request, or SIGN = always

ENCRYPT default

opportunistic

opportunistic

AUTOCRYPT default

yes

yes

ATTACH_KEYS_AS_FILES

no (independent)

no (independent)

The preset concerns only mail that users send: under it, cleartext mail from a user who holds a key is not signed by Pepsi, and senders get keys that they did not ask for. What anyone can receive does not depend on it: inbound mail is handled the same either way.

The standard wire formats are unchanged: the messages are ordinary PGP/MIME and Autocrypt. There are no X-pEp-Version headers, no pEp 2.x message wrapping, no trustwords or handshake, and no key synchronisation between devices, and the preset does not change PROTECT_HEADERS.

Eager key creation. On every committed locally submitted message, the stage generates an OpenPGP MTA key for the From: address when all of the conditions below hold. This applies to the cleartext pass-through as well as to the protected route, so that the first message already carries the new key in its Autocrypt: header. The conditions are:

  • ENABLE_PEP is on for the message (it is per-address overridable);

  • the From: domain is one of [pepsi-ingress] ACCEPTED_DOMAINS: a key is only ever made for an address whose inbound mail comes through this deployment, which is what lets pepsi-stage-decrypt(1) open replies encrypted to it;

  • [pepsi-crypto] AUTO_CREATE_IDENTITY is on – the operator’s veto, which no per-address setting can override;

  • a [pepsi-crypto] KEY_WRAP_SECRET is configured;

  • the address has no crypto_identity row of any kind, whatever its status, protocol or custody. A revoked key counts: if somebody revoked a key, Pepsi does not quietly mint a replacement.

This covers every submission route, including mynetworks and client-cert relays, so a Pepsi deployed as a proxy behind an MTA that authenticates the users works the same way. A web application that sends as noreply@ at a domain for which Pepsi does not receive mail gets no key. Two workers seeing the same first-time sender at once store exactly one key: the test and the insert run under a per-address lock in the SQL function crypto_identity_create_if_absent, and the loser discards what it generated. An automatically created key is marked auto_created, published over the deployment’s own WKD, and never uploaded to a key server unless its owner asks (vks_wanted = false; see pepsi-keys(1)).

SIGN = encrypted-only (the preset’s default) signs a message only when this stage encrypts it, and then inside the ciphertext. Cleartext mail carries the sender’s key (the Autocrypt: header, plus the key file when ATTACH_KEYS_AS_FILES is on) but no signature, so a recipient who does not use cryptography never sees a signature.asc. An explicit request (X-Pepsi-Sign: yes, a [sign] subject keyword) still signs cleartext. Writing SIGN = opportunistic keeps sign-everything behaviour under the preset.

The first message to a new correspondent may still wait for key discovery up to DISCOVERY_TIMEOUT and then go out in cleartext; the preset does not change discovery.

95.1.6.1.3.3. Two keys per user: MTA keys, MUA keys and the public face

An address may hold two kinds of identity:

MTA key

custody = local: Pepsi holds the private half (wrapped in crypto_identity.private_wrapped). Pepsi signs, decrypts and advertises with it. Generated automatically, on request, or imported with its private half.

MUA key

custody = client: the user’s own key, whose private half lives only in their mail client. The row is public-only for ever. Pepsi encrypts to it and recognises inbound mail encrypted to it, but can never open, sign with or advertise it.

The public face of an address is the key that a correspondent should use: the newest active MUA key when the user has one, otherwise the primary active MTA key that still holds its private half. The Autocrypt: header, the key file, the deployment’s WKD and local encryption all read it through the same ordering, so they cannot disagree:

  • WKD serves only MUA keys when there is one – every active one, newest first, at most eight – and never the MTA key beside them;

  • mail from one local user to another is encrypted to the public face and to the user’s other MUA keys of its protocol, the set that WKD serves;

  • Pepsi adds no Autocrypt: header and attaches no key file when the public face is an MUA key. The mail client advertises its own key, and Pepsi advertising a different one on some of the same user’s messages would make correspondents’ key state flip under Autocrypt’s newest-wins rule.

The MTA key is not retired when an MUA key appears. It keeps decrypting mail from correspondents who still use it, and it still signs, inside the ciphertext, cleartext mail that Pepsi encrypts on the user’s behalf. Inbound mail encrypted to an MUA key is passed to the mail client unopened; see pepsi-stage-decrypt(1).

95.1.6.1.3.4. Registering the user’s own key

A locally submitted message whose From: address is at a served domain can register the key that its mail client uses as an MUA key. Registration does not depend on ENABLE_PEP. The key is taken from:

  1. the message’s single valid Autocrypt: header, whose addr= must equal the From: address; or, failing that,

  2. an attached application/pgp-keys part whose User IDs name the address – but only for the address’s very first key. An attachment is a weaker signal than a header that the mail client manages, so a second key is registered only from Autocrypt:.

It happens only when the submitter may speak for the From: address, which is stricter than being allowed to send as it: the message arrived from a trusted relay (state.origin.auth_method is mynetworks or client-cert), or from an authenticated account (sasl, peercred) for which ingress recorded state.origin.from_bound = true – the From: is exactly one mailbox that matched a concrete, wildcard-free USERNAME_MAP entry of the account, or its default login@HOSTNAME. An account granted a wildcard (*@example.org, *) may send as its colleagues but never registers a key for them.

A fingerprint that the address already has, retired or not, is not registered again, so a key that the user retired does not come back because an old device still sends it. A new MUA key is stored with vks_wanted = false and becomes the public face at once. When the address already had another identity, the user is sent a null-sender notice (Auto-Submitted: auto-generated, the key-registered.<lang>.body template) at RESPONSE_STAGE, naming the fingerprint and saying how to retire it – so a key added with a stolen password does not go unnoticed. The notice (and the reply to register) also says what losing the key costs: mail encrypted to it, and inbound mail that pepsi-stage-reencrypt(1) seals again before it is filed, opens only with the user’s registered keys, and the gateway keeps no key of its own that could open it. The way back that it names is a second or third registered key (another device, a backup token), since mail is sealed to every registered key. With no RESPONSE_STAGE the key is still registered but no notice can be sent. The message itself goes on unchanged apart from the usual header hygiene.

An address that has enrolled a second factor (otp enroll, below) registers nothing this way: a message cannot carry a code, and this path is exactly the one that an attacker with a stolen password would use. Its owner registers a new key with register CODE instead.

95.1.6.1.3.5. Mail the client already protected

Only the outermost layer of the submitted message is consulted:

Already encrypted

PGP/MIME, an enveloped S/MIME application/pkcs7-mime, an inline -----BEGIN PGP MESSAGE, a signature wrapped around ciphertext, or anything that no classifier could identify. The stage encrypts, signs and attaches nothing, and adds no Autocrypt: header. Header hygiene and the MUA-key registration above still run. state.crypto.out.client_protected = true is recorded.

Already signed (multipart/signed, inline PGP signed)

The stage may still encrypt it, as encrypted(signed), but adds no signature of its own and no cleartext key file.

A forwarded encrypted message attached as message/rfc822 is somebody else’s protection and does not count.

95.1.6.1.3.6. Attaching the key as a file

ATTACH_KEYS_AS_FILES (default no, independent of the preset) also attaches the sender’s public key the classic OpenPGP way, in addition to the Autocrypt: header, for correspondents whose client does not read Autocrypt. The part is application/pgp-keys, named OpenPGP_0x<long key ID>.asc (the last 16 hex digits of the fingerprint, the name that Thunderbird uses), holding the same minimal certificate that the header carries, ASCII-armoured.

  • On the encrypting route it goes inside the ciphertext, placed like gossip.

  • On the cleartext route the committed message is wrapped in a new multipart/mixed holding the original entity and the key part, or the key becomes one more part of an existing multipart/mixed. The stage runs before pepsi-stage-dkim-sign(1), so the deployment’s DKIM signature covers the result.

  • It is attached until every recipient of the row provably holds the key (the pepsi.peer_has_own_key record that pepsi-stage-autocrypt-learn(1) writes when a correspondent sends an encrypted and signed reply). The record is keyed on the fingerprint, so a new key starts attaching again. A multi-recipient cleartext row is not split for this: the key goes to all if any recipient lacks proof.

  • Never when the public face is an MUA key, never on a message the client encrypted, and not on cleartext the client signed. A message already carrying the key’s file is not given a second one.

state.crypto.out.key_attached = true records that the file went out.

95.1.6.1.3.7. Operating your keys by e-mail

With RESPONSE_STAGE set and KEYS_CONTROL_LOCAL_PART not none, a locally submitted message whose only recipient is <KEYS_CONTROL_LOCAL_PART>@<served domain> (default pepsi-keys@) is a key command. It is consumed – deleted, never relayed – and answered at RESPONSE_STAGE with the keys.<lang>.body template, which lists the address’s keys. The command is the Subject:, case-insensitive. A subject starting with a reply or forward prefix – any word of up to twelve letters followed by a colon, such as Re:, Fwd:, AW:, SV: or Re[2]: – is read as status or as the command after the prefix, but every command except status is then refused and changes nothing: the user’s client composed that subject from a message that somebody else wrote, and an outsider who sends a user Subject: retire FPR with Reply-To: pointing at this address would otherwise have the key retired by the user’s reply. A command that changes something has to be written as a new message. The commands are:

status

List the address’s keys: kind (server-managed or the user’s own), status, key-server state, and which one is given to correspondents.

generate

Create a server-managed OpenPGP MTA key. Always allowed on request, even next to the user’s own key or a revoked one. Its key-server upload is requested when [pepsi-keys] VKS_PUBLISH is on.

register

Register the key in this message’s Autocrypt: header, or its attached key file, as the user’s own MUA key.

publish [FPR]

Ask for an upload to the key server (and publish over WKD), by default of the public face. Only an active OpenPGP key can be uploaded. The upload itself is made by the next run of pepsi-keys identity publish --retry, and cannot be undone.

retire FPR

Revoke a key; also how a wrongly registered MUA key is removed. For a server-managed OpenPGP key whose private half is still held, a revocation certificate signed by the key itself is made first and stored as its public half: the Web Key Directory then serves the key as revoked rather than falling silent, and when the key had been uploaded to a key server the next run of pepsi-keys identity publish --retry uploads the revocation there. The reply says exactly which of these happened. A user’s own MUA key gets no certificate here (only the client holding it can sign one), nor does an S/MIME certificate; the reply says that correspondents who hold such a key are not told.

pin FPR

Record that the user compared a correspondent’s key out of band: every live cached key (pepsi.peer_key) with exactly this fingerprint is pinned and raised to the manual source, so it is used for that correspondent whatever later messages offer, is never displaced or refreshed away, and its signatures verify as valid – for every user of the deployment, since the cache is shared. Refused unless the address has an enrolled second factor (the code then goes in the subject, as for every command) and unless FPR is the whole fingerprint (at least 40 hex digits; a long key ID is not enough). A revoked key cannot be pinned. Audited as key.peer.pin with actor mail:<address> and each row’s previous source; only the operator unpins (pepsi-keys peer unpin). The key-change notice of pepsi-stage-autocrypt-learn(1) prints the exact subject to send.

otp enroll

Set up (or replace) a second factor for these commands: a TOTP secret (RFC 6238, SHA-1, six digits, 30-second steps). The reply carries it once – as an otpauth:// URI, in base32, and as an attached QR code (second-factor.png) for an authenticator app – and should be deleted once the secret is in the app. Replacing an existing one needs its current code. The new secret is stored as pending (pepsi.otp_pending): a second factor already in force stays in force until otp confirm. When the address has active keys of its own (MUA keys, registered from the user’s client), the reply is encrypted to them before it is queued, unsigned (the notice signer passes a sealed notice on as it is); otherwise it goes out in clear. It carries an Expires: header (RFC 4021) at the end of OTP_CONFIRM_WINDOW. Being the only copy of the secret, the reply is committed in one transaction with the pending secret it carries, and rendered (and sealed) before either: if it cannot be built or queued, nothing is stored, everything stays as it was, and the command is retried. Audited as key.otp.enroll (with pending and sealed); telemetry encrypt-otp-enroll-sealed or encrypt-otp-enroll-clear.

otp confirm CODE

Make the pending secret the second factor, with a current code from it, within OTP_CONFIRM_WINDOW of otp enroll (default 1h). The code’s time step becomes the replay floor, so it cannot be used again. A missing code is refused uncounted; a wrong one counts against the pending secret only (never against a second factor in force), and ten discard it; a lapsed one is refused and deleted (pepsi-queue gc deletes the rest). The reply says again to delete the enrolment message. Audited as key.otp.confirm. verify and activate are accepted for confirm.

otp remove

Remove the second factor; needs its current code. otp alone (or otp status) is status.

With a second factor enrolled, every command but status (and otp confirm, whose code is the new secret’s) must carry the app’s current code: a word of exactly six digits anywhere in the Subject: (register 123456; otp=123456 is accepted too). A command without one is refused and not counted. A wrong code, or a code already used (a code is valid once), counts as a failure and a right one resets the count; after ten failures in a row the second factor is locked and every command but status is refused until the operator resets it (pepsi-keys otp reset). The secret is wrapped under the key store’s key-encryption key and readable by the pepsi-crypto role only; see pepsi-keys(1). The reply to status says whether the address has one and whether it is locked.

A command is answered once. A command message whose reply is already queued (an earlier pass carried it out and was interrupted before consuming it) is only consumed, so a retry never repeats a command – in particular never mints a second secret behind the reply that carries the first. A command that fails for a reason of this server is answered with a generic “try again later”; the error itself is in the log, not in the mail.

FPR is the full fingerprint or at least its last 16 hex digits (pin: the full fingerprint), written as one word (a 0x prefix is accepted); being at least 16 digits, it is never mistaken for a code. list, upload and revoke are accepted for status, publish and retire, and 2fa/totp for otp; any other subject is answered with the key list and the valid commands. The command acts on the From: address, and only when the submitter may speak for it (see Registering the user’s own key); otherwise, and for an address at a domain that the deployment does not serve, the reply says the request was refused. With no RESPONSE_STAGE there is nowhere to answer, so the surface is off and such a message is sent on like any other.

95.1.6.1.3.8. Choosing the recipient’s key

Normally the key comes from the pepsi.peer_key cache, best-ranked source first and subject to MIN_TRUST — see pepsi.conf(5) and pepsi-keydisc(1). The rank is compared across both protocols: PREFER decides only between an OpenPGP key and an S/MIME certificate on the same rung of the trust ladder, and a better-ranked key of the other protocol always wins. The store’s conflict rule compares keys of one protocol only. With the other order, one forged Autocrypt: header could take over a correspondent whose S/MIME certificate came from a directory, from DANE, from the operator or from an authenticated signed message, with no rotation event, although such a header on unsigned mail lands only on the inbound rung.

There is one exception, and it is a security boundary rather than an optimisation. If this deployment holds an ``active`` identity for the recipient, that key is used and no ``peer_key`` row for the address is consulted at all — whatever its rank, and however it arrived. state.crypto records the source as own.

The reason is that peer_key is fed in part by harvesting inbound mail, which files keys under the From: address that the sender writes. Inbound authentication is deliberately fail-open, so a message claiming to be from one of this deployment’s own users can seed a peer key for that user with a stranger’s key in it; without the exception, mail from one local user to another would then be encrypted to the planted key and would look exactly like success.

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, and their real key is one that this host can only learn by discovery, harvesting or gossip — so the exception does not apply to them. See the manual’s Our own users’ keys are not discovered for the trade-off in full, including its cost: a signature made with a user’s separate personal key stops verifying once an identity is held for that address.

The same preference applies to the gossip fields below: a subject of ours is introduced with the key that we issued them, never with one that somebody planted.

A cached key is not used when it cannot be trusted with the message whatever its rank: an RSA key below [pepsi] CRYPTO_MIN_RSA_BITS, an RSA modulus whose private half can be computed from it (ROCA, primes close enough for Fermat’s method, a small prime factor), or a key of any type that is known to be compromised — on the known-compromised list pepsi.compromised_key (the badkeys blocklist, kept current by pepsi-keys blocklist update, and the moduli that the daily pepsi-keys peer screen factored). Such a recipient is treated as one with no usable key and takes the ON_NO_KEY route. So is a recipient whose cached S/MIME certificate pepsi-keydisc(1) has marked revoked – its issuer’s revocation list, verified against an enabled trust anchor, named it – or whose OpenPGP key carries its owner’s revocation: a revoked key is no key, the stage consults no revocation data of its own, and the recipient’s reason says revoked (with the fingerprint) rather than “no usable key”. An expired key is no key either: an S/MIME certificate past its notAfter (or before its notBefore) and an OpenPGP key whose primary key’s expiry has passed are set aside before the key is chosen, so a recipient with a current key of the other protocol gets that one, and one with none takes the ON_NO_KEY route (after a discovery request where DISCOVERY allows one, which is how a renewed certificate replaces the lapsed one); the reason then says expired on with the date.

95.1.6.1.3.9. Recipient outcomes

Per recipient, exactly one of:

encrypted

A usable key was found (subject to MIN_TRUST) and the message was encrypted to it. The container actually emitted is recorded, together with whether it was a downgrade from the AES-256-GCM default and, for S/MIME, which capability record chose it (smime_capability: configured or learnt; absent when there was none).

signed-only

No usable recipient key, policy allows ordinary mail, and the author’s signature was applied.

cleartext

Neither signed nor encrypted.

secure-link

Routed to SECURE_LINK_STAGE instead of being sent.

bounced

Encryption was required and could not be applied; routed to BOUNCE_STAGE with an RFC 3463 5.7.0 enhanced status. A row can hold several recipients without a key: each goes there on a row of its own, so that a DSN reports on every one of them and honours each recipient’s NOTIFY. The message is not rewritten first. With no BOUNCE_STAGE the message is failed rather than sent unprotected.

oversize

The message was larger than MAX_SIZE and took the ON_OVERSIZE route.

When the recipients of one message do not all share an outcome, the stage splits the row (each new row’s state.dsn.rcpt sliced in lockstep with its rcpt_to) and hands the message back to the queue: every recipient with a key, or with a lookup still pending, gets a row of its own, and the recipients with no key share one row, since they share the no-key outcome. Each row then re-enters this stage. A message whose recipients do all share an outcome — the common case of “nobody has a key, send it as usual” — is never split.

Every outcome that puts unprotected content on the wire while encryption was wanted is logged at WARN and recorded per recipient in state. Sending cleartext is never a silent outcome in the log; whether the author hears of it is NOTIFY_CLEARTEXT’s question.

95.1.6.1.3.10. Telling the author

The author of a locally submitted message sees only the copy that their mail client filed before the gateway acted, so two outcomes are worth a message to them. Both are null-sender notices at RESPONSE_STAGE, to the From: address, Auto-Submitted: auto-generated, rendered in the sender’s language; neither is sent for a message with a null sender or a mailing-list post, and neither holds the message up.

NOTIFY_CLEARTEXT = author (default no)

For every copy that left unencrypted although encryption was wanted – no usable key under ON_NO_KEY = cleartext, or over MAX_SIZE under ON_OVERSIZE = cleartext – one notice, subject Sent without encryption: and the original subject, naming the recipients and the reason, and the keyword that would have refused cleartext (template cleartext-notice.<lang>.body). The keyless recipients of a message share one copy (above), so they share one notice; a recipient whose key lookup was still pending when the message was split, and who then got cleartext, gets one of its own. The option is per-address overridable, which is how a user asks for it; set in the file, the worker refuses to start without RESPONSE_STAGE. Telemetry encrypt-cleartext-notice.

A near-miss subject keyword (always)

A subject that starts – after Re:/Fwd: and up to three bracketed groups such as a list tag – with something that looks like one of the SUBJECT_KEYWORDS_* but is not one is ordinary mail to this stage, so the author is warned (subject Subject keyword not recognised:, template keyword-near-miss.<lang>.body): a misspelling one edit or one swap of adjacent letters away from a keyword of six letters or more ([encyrpt], [encrpyt]), a look-alike letter or other spelling with the same skeleton (a Cyrillic letter in place of a Latin one, (encrypt)), or a bracketed group that asks for protection in other words ([encrypted], [signed], [secured]). The comparison is the one that the decrypt stage uses to strip forged security tags. A keyword written in another language is not recognised. Sent once per message, from the row that keeps the message’s own queue token. Telemetry encrypt-keyword-near-miss.

95.1.6.1.3.11. Recipient DNS failures

A recipient for whom discovery found no key because the lookup failed in the DNS is not treated as one with no key. pepsi-keydisc(1) classifies the failure (see its “A lookup that fails in the DNS”) and the settled request carries the verdict:

unreachable (nothing about the recipient’s domain answers), or transient (its key records failed while the domain answered, not yet persistently)

The message is deferred: paused until the settled lookup ages out (about 15 minutes), then parked on a fresh lookup. state.encrypt_dns_deferred and state.last_error say why. Once it has waited the stage’s MAX_LIFETIME — capped at the relay stages’ default of 120 h, so this stage never holds a message past the point at which a relay would have given up on it — it is bounced with RFC 3463 status 5.4.3. While it waits, a sender who asked for NOTIFY=DELAY gets one “delayed” DSN after DELAY_DSN_AFTER (default 4 h), through the same mechanism that the relay stages use.

inconsistent (the domain’s MX or A/AAAA answer while its key records have failed in three consecutive rounds within an hour of each other)

That is what an attacker suppressing the recipient’s key would cause, so the message is routed to SECURE_LINK_STAGE when one is configured, and bounced (5.7.0) otherwise. The sender is told why and how to override: in the bounce’s diagnostic, or, on the portal route, in a null-sender notice injected at RESPONSE_STAGE. With no RESPONSE_STAGE that notice is not sent, and a warning is logged.

This applies only where the no-key route would otherwise have been cleartext (ENCRYPT = opportunistic with ON_NO_KEY = cleartext): ENCRYPT = required, a [secure]/[encrypt] keyword and an ON_NO_KEY that already refuses cleartext are unaffected. It does not apply when discovery is off for the message (DISCOVERY = no, or a domain excluded by ALLOW_DOMAINS/DENY_DOMAINS), since nothing would ever ask again.

The override. A local sender who accepts that the message travels unencrypted puts [clear-ok] (SUBJECT_KEYWORDS_CLEAR_OK) in the Subject; like [secure] it is removed before sending and honoured only for state.local_origin mail. CLEAR_ON_DNS_FAILURE = yes says the same as a standing setting, normally given per sender through pepsi.settings. Neither weakens ENCRYPT = required, and a recipient with a key is still encrypted to.

What remains: without DNSSEC on the recipient’s zone a forged NXDOMAIN or empty answer is indistinguishable from a real “no record”, and still reads as “no key”.

95.1.6.1.3.12. Autocrypt key advertisement

Unless AUTOCRYPT is turned off, every locally submitted message leaves this stage carrying an Autocrypt: header advertising the From: author’s own OpenPGP key:

Autocrypt: addr=alice@example.org; prefer-encrypt=mutual;
 keydata=xjMEZ8kAABYJKwYBBAHaRw8BAQdA…

This happens on every message — signed, encrypted, routed to the secure link or plain cleartext. The pass-through case is the one that matters: a correspondent has to be able to learn the key from ordinary mail, because until they have it there is nothing to encrypt with. Advertising only on already protected mail would tell the key to exactly the people who already know it.

The advertised key is the minimal transferable public key of Autocrypt Level 1 §2.1.1 — primary key, primary User ID, its self-signature, one transport-encryption subkey and its binding signature, and nothing else. Extra User IDs, the signing subkey and any third-party certifications are stripped: the header goes out with every message, so its size is paid over and over, and republishing certifications would publish the sender’s social graph as a side effect of sending mail.

Five rules bound it:

  • OpenPGP only. Autocrypt is defined over an OpenPGP transferable public key and has no S/MIME form, so a sender holding only an X.509 identity advertises nothing.

  • Locally submitted mail only, like everything else this stage does.

  • Never over an existing header. A real client (Thunderbird, K-9, Delta Chat) may have set its own Autocrypt: field naming the key whose secret half it holds. That one is better than ours and is left alone — and a second field would be worse than useless, because Autocrypt Level 1 discards a message carrying two of them outright.

  • The key must still be openable here. Only an identity that still holds its private material is advertised, so ciphertext sent to an advertised key is always ciphertext that pepsi-stage-decrypt(1) can open.

  • Only the public face. When the user registered their own MUA key, it is the public face and Pepsi advertises nothing; the mail client advertises its key itself. A message the client already encrypted gets no header either.

prefer-encrypt=mutual is emitted only when the stage’s effective ENCRYPT is required — including when that comes from a per-address pepsi.settings override, so one user can advertise it without the deployment doing so. Under Autocrypt Level 1 §2.4 a correspondent’s client enables encryption by default only when both ends say mutual; claiming it under opportunistic, where ON_NO_KEY = cleartext says cleartext is an acceptable outcome, would announce a preference that this deployment does not enforce. The attribute is then omitted, which Level 1 reads as nopreference: the correspondent still records the key and is still offered encryption, only not by default. The value follows the configured mode rather than the one resolved for a single message, so a [secure] subject keyword does not make a correspondent’s key state oscillate with our users’ subject lines.

Because this stage runs before pepsi-stage-dkim-sign(1), the header is covered by the deployment’s own DKIM signature.

95.1.6.1.3.13. Autocrypt key gossip

AUTOCRYPT_GOSSIP (default NO) turns on the other half of Autocrypt Level 1: Autocrypt-Gossip: fields advertising the other recipients’ keys. It covers a case that the header above cannot cover. Alice writes to Bob and Carol, who have never corresponded. Both learn Alice’s key from her Autocrypt: header, but neither learns the other’s — so Bob’s reply-all cannot be encrypted to Carol until some later message happens to introduce them. One gossiped message closes that gap:

Autocrypt-Gossip: addr=carol@example.org;
 keydata=xjMEZ8kAABYJKwYBBAHaRw8BAQdA…

It is off by default because it is a different kind of act from AUTOCRYPT: that one publishes a key that its owner asked this deployment to hold, while this one redistributes third parties’ key material — cached here for our own use — to correspondents who never asked for it. That is an operator’s decision.

Three rules follow from the specification, and one from this stage’s own shape.

  • Only inside a ciphertext. Level 1 §5.3 puts these fields in the header section of the encrypted part, and not as a nicety: an outer Autocrypt-Gossip: field would publish the recipient set of an encrypted message to every relay on the path, which is most of what the encryption was for. So there is no gossip on the cleartext pass-through, none on a message that was only signed, and none on an S/MIME container — Autocrypt is defined over OpenPGP and has no S/MIME form, so a gossip field there would be redistribution into a place where no client looks.

  • Several are expected. One field per introduced recipient, in To:/Cc: order — the opposite of Autocrypt:, where a second field makes a Level 1 parser discard the message outright.

  • No ``prefer-encrypt``. The attribute states the sender’s policy, and these fields speak for somebody else. Asserting one on a correspondent’s behalf is a claim that this deployment has no standing to make, and Level 1 leaves it out of the gossip form for the same reason.

  • A cached key or nothing. A visible recipient for whom this deployment holds no usable OpenPGP key is left out of the set. The stage performs no discovery on their behalf and never pauses a message to fetch a third party’s key: an introduction is a courtesy, and delaying the sender’s mail to perform one would not be. The floor is the stricter of MIN_TRUST and GOSSIP_MIN_TRUST (default owner-confirmed): a key that would not have been good enough to encrypt to is not good enough to pass on either, and by default a key that this deployment merely harvested from inbound mail, or that was itself gossiped, is not republished at all. Introducing a correspondent to a key that nobody vouched for is a stronger claim than using it oneself.

Warning

A blind carbon copy is never gossiped. The subject addresses come from the message’s parsed To: and Cc: fields and from nowhere else. The envelope recipient list is consulted only to remove an address from the set (this copy’s own recipient, and the From: author), although it does contain the Bcc recipients: that is the entire meaning of a blind copy.

A Bcc recipient therefore cannot appear in any copy of the message, and the guarantee does not depend on a Bcc: field having been stripped upstream: the field is not read at all. Level 1 §5.3 requires the same of a receiving client, which ignores a gossip header whose addr is not a To:/Cc: recipient — so such a header would leak the address and achieve nothing.

The converse is deliberate. A blind recipient’s own copy does carry gossip about the To:/Cc: recipients: they received those header fields like everybody else, so it tells them nothing they cannot already read, and withholding it would break reply-all for exactly the recipient least likely to have corresponded with the others before.

A message with more than 50 visible recipients gets no gossip at all. Each introduced key is repeated in every recipient’s own ciphertext, so the cost grows with the square of the address count, and at that size the message is a broadcast where nobody will reply-all. Introducing an arbitrary fifty of them would be a silent choice with no defensible rule behind it, so the stage introduces none and says so in the log.

95.1.6.1.3.14. Content-algorithm negotiation

For OpenPGP the recipient’s certificate states whether it can read RFC 9580 SEIPDv2/AEAD; most of the installed base (GnuPG 2.4 and older) cannot. Under [pepsi] CRYPTO_ALLOW_DOWNGRADE = negotiate (the default) the stage emits SEIPDv1+MDC only when the recipient’s own key proves it cannot do better, logs it at INFO, and records it — a downgrade is a fact about the correspondent, not a failure. Under no the same recipient is refused and falls into ON_NO_KEY; see the caution under that option.

An X.509 certificate advertises no content-encryption capability, so for S/MIME the stage negotiates against the recipient’s S/MIME capability record instead (table pepsi.smime_capability): learnt by pepsi-stage-autocrypt-learn(1) from the RFC 8551 SMIMECapabilities attribute of the correspondent’s own signed mail, keyed on the certificate that signed it, or configured by the operator with pepsi-keys peer capability set ADDRESS aead|cbc (also *@domain; a configured record wins over a learnt one). Under negotiate a recipient whose record says it cannot read AEAD gets AES-256-CBC EnvelopedData; every other recipient — including one with no record — gets RFC 5083 AuthEnvelopedData (AES-256-GCM). Under no the recorded recipient is refused and falls into ON_NO_KEY; under yes every S/MIME recipient gets EnvelopedData, whatever its record.

RFC 9709 key derivation. The content-encryption algorithm identifier of a CMS message is not authenticated, so an AES-GCM message’s RecipientInfo can be re-submitted under a synthetic AES-CBC container that opens with the same content key. A recipient whose learnt record says its own signed SMIMECapabilities name id-alg-cek-hkdf-sha256 gets a message whose content key is derived from the delivered one with HKDF-SHA256 over the real algorithm identifier, in either container, which binds the algorithm (and its nonce or IV) into the key. Every certificate to which the message is sealed must have made that claim; a configured record never turns it on, since a client that does not know the identifier cannot read the message at all. The recipient’s line in state.crypto.out.recipients then carries cek_hkdf: true (absent otherwise; telemetry encrypt-cek-hkdf). Pepsi’s own S/MIME signatures advertise AES-256-GCM, AES-256-CBC and id-alg-cek-hkdf-sha256, so a correspondent’s client — another Pepsi above all — learns all three.

Thunderbird 140.12.0esr cannot read AuthEnvelopedData and fails silently (the recipient sees a blank message). A Thunderbird correspondent who has sent us a signed message is learnt automatically, since NSS does not list AES-GCM among its capabilities; a Thunderbird user who has never sent a signed message is told once, with the first message, how to get there (below) — or the operator configures the record (pepsi-keys peer capability set ADDRESS cbc). See pepsi.conf(5) and pepsi-keys(1).

95.1.6.1.3.15. The first-message notice

A recipient with no record gets the authenticated container on an assumption, and the client that cannot read it fails without an error. So the first S/MIME message encrypted to a certificate that has no capability record carries a short plaintext notice outside the ciphertext: the message becomes a multipart/mixed of a text/plain part followed by the application/pkcs7-mime part, under the message’s own header fields. The notice says that the message is protected with an authenticated S/MIME container, that an empty or unreadable message should be reported to the sender, and that a reply signed with the recipient’s certificate lets this server learn what their client reads. It says nothing about the message, and the ciphertext is byte-for-byte what it would have been without it: a receiver that opens the pkcs7-mime part gets the original message, and pepsi-stage-decrypt(1) keeps the ciphertext as the message and moves the notice into an inert attachment, as it does with any content beside a ciphertext.

The notice is sent once per certificate: smime_capability gains a row for the certificate’s fingerprint with notice_sent_at set and no capability (pepsi-keys peer capability list shows it as notice), and a learnt or configured record ends the notices for good — the learnt claim replaces the notice row whatever the signature’s date. The row is written just before the message is committed, so a crash in between sends the retried message without the notice rather than sending it twice. The recipient’s line in state.crypto.out.recipients carries aead_notice: true when the notice went out (absent otherwise).

The text is the smime-aead-notice.<lang>.body template under [pepsi] TEMPLATE_DIR (ten languages are shipped), chosen like this stage’s other notices from the message’s detected language (state.language), English last. A deployment whose template directory lacks it sends the message without the notice and warns; nothing is recorded, so the next message tries again. Whether a client that does read AuthEnvelopedData also opens it when the pkcs7-mime part is not the top-level entity has been verified for OpenSSL and for pepsi-stage-decrypt(1) only; the notice goes with one message per certificate for that reason too.

95.1.6.1.3.16. Length padding

Encryption hides what a message says, not how long it is, and a length is often enough to tell which of a few known documents was sent. Under PADDING (default on) every message this stage encrypts is padded to a Padmé length: rounded up so that only the top bits of its binary exponent survive, which leaks O(log log M) bits about a length below M at no more than 12 % of overhead (Nikitin et al., PETS 2019).

  • OpenPGP SEIPDv2: an RFC 9580 padding packet (type 21) inside the encryption, written after the signature, so it is neither visible nor signed.

  • OpenPGP SEIPDv1 and S/MIME: neither has padding that every reader skips, so the encrypted MIME entity carries a Pepsi-Padding: header field of filler, folded at 78 octets. A reader ignores a header field that it does not know; Pepsi’s own decrypt stages keep only an entity’s Content-* fields, so it never reaches a mailbox through Pepsi.

Neither content encryption compresses, so the filler costs exactly its size. The recipient’s key identifier stays in clear in each copy, which names only the recipient that its own envelope names: the stage splits a message one recipient per row before it encrypts. pepsi-stage-reencrypt(1) does not pad the copy that it seals for a user’s own mailbox.

95.1.6.1.3.17. Header protection

With PROTECT_HEADERS = yes the protected entity (the signed part, or the plaintext inside the ciphertext) carries a protected-headers="v1" parameter and verbatim copies of From, Sender, To, Cc, Reply-To, Subject, Date, Message-ID, In-Reply-To and References (RFC 9788 injected headers; Bcc is never copied), and, on a message that is encrypted, the outer Subject is replaced with .... A message that is only signed keeps its outer Subject: it hides nothing from anyone who can read it, and RFC 9788 applies header confidentiality to encrypted messages alone. The outer fields are copied, not moved, so DKIM, threading and DSN generation keep what they need. A receiver such as pepsi-stage-decrypt(1) can then compare the protected From: with the outer one and withhold its valid verdict from a signed message re-sent under another author, and the protected To: and Cc: put the recipients inside an S/MIME signature for a client that does not read Pepsi’s own recipient attribute. The option is off by default, because a client that does not render protected headers shows ... as the subject of every encrypted message; PROTECT_HEADERS = yes is for a population whose clients do.

95.1.6.1.4. Signing Pepsi’s own notices

The messages that Pepsi composes itself — console sign-in links, secure-link portal notifications and receipts, secretary challenges, payment requests, the replies to key, settings and wallet commands, key-change notices and out-of-office replies — carry an aligned DKIM signature and nothing else, which a recipient’s provider checks and their client never sees. With NOTICE_SIGNER set to the address of an identity in the key store, an instance of this program signs every one of them with that identity, in OpenPGP or S/MIME (the first protocol in PREFER that the identity has), with the header protection of PROTECT_HEADERS, so a client that verifies signatures can tell a genuine notice from a forged one. The usual shape is a second instance between the notice emitters and signing:

[stage-notice]
PROGRAM = pepsi-stage-encrypt
NEXT_STAGE = dkim-sign
NOTICE_SIGNER = notices@example.org

with every RESPONSE_STAGE, BLOCK_RESPONSE_STAGE, [pepsi-admin] ENROL_STAGE and [pepsi-secure-link] NOTIFY_STAGE pointing at it (pepsi-setup(1) --wizard writes it with NOTICE_SIGNER commented out). Create the identity first, at a served domain so the Web Key Directory publishes it:

pepsi-keys identity generate notices@example.org --protocol openpgp --name "example.org notices"

What is signed is decided by the message, not by the stage: only a row whose state.notice mark was set by the component that composed it (see pepsi.state(7)) is signed, and it is signed only, never encrypted, even to a recipient whose key is cached. Every other row takes the stage’s ordinary path, which for mail without state.local_origin is header hygiene only. A notice to a third party (payment request, secretary challenge, out-of-office reply) is not marked while a per-address override applies to the message that caused it, because an override can change its wording; portal replies, list mail, digests, bounces and TLS reports are never marked. NOTICE_SIGNER is read from the configuration file alone, never through pepsi.settings, so the recipient of a key-change notice cannot name the key that signs it.

A configured signer is never skipped: a missing identity, an unreadable key store or a failed signature is an error on which the message is retried (with the stage’s usual back-off), not a notice sent unsigned, and the worker refuses to start when NOTICE_SIGNER is set without [pepsi-crypto] KEY_WRAP_SECRET. A signed notice is sent from the signer: a verifier holds a signature to the From: address (RFC 8551 §3.1; pepsi-stage-decrypt(1) reports a mismatch as identity-mismatch), and the notices come from many addresses that one identity cannot name. Before signing, the stage therefore replaces From: with <NOTICE_SIGNER> and keeps the previous value as Reply-To: unless the notice set one, so a reply reaches whoever it reached before; the protected From: inside the signature is the signer too. Telemetry key encrypt-notice-sign.

95.1.6.1.5. Configuration

The stage reads its own [stage-<name>] section (PROGRAM = pepsi-stage-encrypt, a required NEXT_STAGE — every outcome this stage has is an onward hop — and BOUNCE_STAGE, which pepsi-setup(1) in turn requires whenever ON_NO_KEY/ON_OVERSIZE resolves to bounce, 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_*, STRIP_REQUEST_HEADERS, PROTECT_HEADERS, AUTOCRYPT, AUTOCRYPT_GOSSIP, GOSSIP_MIN_TRUST, MAX_SIZE, SECURE_LINK_STAGE, DISCOVERY, DISCOVERY_TIMEOUT, CLEAR_ON_DNS_FAILURE, DELAY_DSN_AFTER, NOTICE_SIGNER, NOTIFY_CLEARTEXT), all documented in pepsi.conf(5). Those are behavioural options and are per-address overridable through the pepsi.settings table — except NOTICE_SIGNER, which is read from the configuration file alone.

The cryptographic policy — algorithm choice, downgrade permission, 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).

95.1.6.1.6. 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.

95.1.6.1.7. State

Inputs: state.local_origin (the gate), state.notice (the mark of a message that Pepsi composed itself, signed under NOTICE_SIGNER), state.dsn (honoured and sliced in lockstep with any recipient split), state.origin.auth_method and state.origin.from_bound (whether the submitter may speak for the From: address, for key registration and the e-mail key commands).

Outputs: state.crypto.out — whether the message was signed, by which identity, and one entry per recipient carrying the outcome, protocol, fingerprint, key source, trust rank, content algorithm and downgrade flag (and, for S/MIME, the source of the capability record that chose the container). A local recipient who registered several MUA keys (pepsi-keys(1) identity import, the register command, their own Autocrypt: header) is encrypted to all of them, same protocol as the newest, at most eight: the entry then lists them under fingerprints (the public face first), and under skipped any of the others the policy refused (compromised, too short), which are dropped alone rather than sending the message in the clear; key_attached = true when the sender’s key went out as a file, and client_protected = true when the submitting client had already encrypted the message and the stage left it alone. Also state.encrypted = true when a recipient’s message was encrypted, which pepsi-stage-auto-whitelist(1) reads. While a message is deferred on a recipient DNS failure, state.encrypt_dns_deferred = true and state.last_error (plus state.delay_sent once a delay DSN went out). On a bounce, state.bounce. The state layout is described in pepsi.state(7).

Transitions: NEXT_STAGE for a sent message (encrypted, signed-only or cleartext); SECURE_LINK_STAGE or BOUNCE_STAGE for a recipient that could not be protected; paused while waiting for key discovery or deferred on a recipient DNS failure; pending at this same stage after a recipient split. A key command to the control address is deleted (finish) after its reply has been injected at RESPONSE_STAGE; the key-registered notices are injected there too, as new null-sender messages.

95.1.6.1.8. 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-encrypt -c /etc/pepsi/pepsi.conf worker

95.1.6.1.9. Security

The mechanisms this stage implements are described in the Security chapter of the Pepsi manual: “The private-key custody boundary” (why the binary is setuid pepsi-crypto), “A second factor for key management” (the otp commands), “Who a signed and encrypted message was for” (the Intended Recipient Fingerprint), “Protected headers against the outer ones”, “Which S/MIME container a correspondent gets”, “A key lookup that fails in the DNS” and “Signed notices”. The Threat model chapter states what they claim: “End-to-end encryption: two custody modes”, “Keys of correspondents” and “Forged notices”. One residual is documented there rather than defended against: the stage signs as the queue row’s From:, which any pepsi stage may rewrite after ingress enforced the sender’s addresses, so the custody split protects the disclosure of a key, not its use.

95.1.6.1.10. 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. The dispatcher requeues what it handed over and retries the stage later.

95.1.6.1.11. See Also

pepsi-stage-dkim-sign(1), pepsi-stage-srs(1), pepsi-keys(1), pepsi-keydisc(1), pepsi-stage-auto-whitelist(1), pepsi-stage-bounce(1), pepsi-dispatch(1), pepsi-setup(1), pepsi.conf(5), pepsi.state(7)

95.1.6.1.12. Bugs

Report bugs to the Pepsi issue tracker.