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:
the
state.local_origingate — nothing below it applies to a message that we are merely forwarding;the request headers that an add-in set (
X-Pepsi-Sign,X-Pepsi-Encrypt, eachyes/no/required);a subject keyword (
SUBJECT_KEYWORDS_SIGN/_ENCRYPT/_BOTH);the
[stage-encrypt]defaultsSIGNandENCRYPT, which already carry any per-address override from thepepsi.settingstable.
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 |
|
|
|---|---|---|
|
|
|
Key creation |
eager (first submission) |
on request, or |
|
|
|
|
|
|
|
|
|
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_PEPis 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_IDENTITYis on – the operator’s veto, which no per-address setting can override;a
[pepsi-crypto] KEY_WRAP_SECRETis configured;the address has no
crypto_identityrow 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 incrypto_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:
the message’s single valid
Autocrypt:header, whoseaddr=must equal theFrom:address; or, failing that,an attached
application/pgp-keyspart 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 fromAutocrypt:.
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 noAutocrypt:header. Header hygiene and the MUA-key registration above still run.state.crypto.out.client_protected = trueis 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/mixedholding the original entity and the key part, or the key becomes one more part of an existingmultipart/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_keyrecord 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:
statusList the address’s keys: kind (server-managed or the user’s own), status, key-server state, and which one is given to correspondents.
generateCreate 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_PUBLISHis on.registerRegister 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.retireFPRRevoke 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 --retryuploads 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.pinFPRRecord 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 themanualsource, so it is used for that correspondent whatever later messages offer, is never displaced or refreshed away, and its signatures verify asvalid– 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 askey.peer.pinwith actormail:<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 enrollSet 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 untilotp 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 anExpires:header (RFC 4021) at the end ofOTP_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 askey.otp.enroll(withpendingandsealed); telemetryencrypt-otp-enroll-sealedorencrypt-otp-enroll-clear.otp confirmCODEMake the pending secret the second factor, with a current code from it, within
OTP_CONFIRM_WINDOWofotp enroll(default1h). 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 gcdeletes the rest). The reply says again to delete the enrolment message. Audited askey.otp.confirm.verifyandactivateare accepted forconfirm.otp removeRemove the second factor; needs its current code.
otpalone (orotp status) isstatus.
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:
encryptedA 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:configuredorlearnt; absent when there was none).signed-onlyNo usable recipient key, policy allows ordinary mail, and the author’s signature was applied.
cleartextNeither signed nor encrypted.
secure-linkRouted to
SECURE_LINK_STAGEinstead of being sent.bouncedEncryption was required and could not be applied; routed to
BOUNCE_STAGEwith an RFC 34635.7.0enhanced 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’sNOTIFY. The message is not rewritten first. With noBOUNCE_STAGEthe message is failed rather than sent unprotected.oversizeThe message was larger than
MAX_SIZEand took theON_OVERSIZEroute.
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.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_deferredandstate.last_errorsay why. Once it has waited the stage’sMAX_LIFETIME— capped at the relay stages’ default of120 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 status5.4.3. While it waits, a sender who asked forNOTIFY=DELAYgets one “delayed” DSN afterDELAY_DSN_AFTER(default4 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_STAGEwhen 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 atRESPONSE_STAGE. With noRESPONSE_STAGEthat 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 ofAutocrypt:, 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_TRUSTandGOSSIP_MIN_TRUST(defaultowner-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’sContent-*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.