95.1.28. pepsi-stage-reencrypt¶
seal decrypted inbound mail to the recipient’s own key before filing it
- Manual section:
1
95.1.28.1.1. Name¶
pepsi-stage-reencrypt - the storage re-encryption stage of the Pepsi pipeline.
95.1.28.1.2. Synopsis¶
pepsi-stage-reencrypt [GLOBAL-OPTIONS] worker
95.1.28.1.3. Description¶
pepsi-stage-reencrypt is a stage program run by pepsi-dispatch(1)
as a persistent worker reading message ids on standard input. It loads the
message’s pepsi.workqueue row (refusing to act unless its status is
running) and reads its [stage-<stage>] section.
pepsi-stage-decrypt(1) opens mail encrypted to a user’s gateway (MTA) key,
so that the language, spam, whitelist and key-learning stages can read it. The
plaintext is then what would be filed in the mailbox. This stage runs after all
of those readers and puts the message back under encryption, this time to the
key that the user registered for their own mail client. That key is the
MUA key: a custody = client row in pepsi.crypto_identity, registered
with pepsi-keys(1) identity import or the e-mail key commands, or
learnt from the Autocrypt: header of the user’s own submissions. What is
filed is then ciphertext that only that client can open.
It acts only on a message that the decrypt stage opened: state.crypto.in
must say that it arrived encrypted and was decrypted. Mail that arrived in
plaintext is never touched, because sealing it would claim a confidentiality
that it never had on the wire. Mail that the decrypt stage left unopened because
it was already encrypted to the MUA key (for_client) needs nothing either.
Only recipients that this host serves are considered; a recipient that an alias
expanded to another provider is left alone.
For each local recipient, the sealed copy is encrypted to every active MUA
key that can receive encryption. A user who holds two keys, such as a hardware
token and its backup or one key per device, can therefore open the mailbox with
whichever key is to hand. One message carries one protocol: when the keys mix
OpenPGP and S/MIME, the protocol of the newest key wins and the others are
recorded as skipped.
At most eight keys are used, newest first. A key that cannot be sealed to, such
as an expired certificate or a key below [pepsi] CRYPTO_MIN_RSA_BITS or on
the known-compromised list, is dropped on its own with a warning, and the copy
is sealed to the rest; only when no key is usable does ON_NO_CLIENT_KEY
apply. For S/MIME the weakest of the keys’ capability records decides the
container, so that every device of the user can read it. A message with
several recipients is first split into one row per recipient when any of them
is to be sealed for or refused, since each copy is sealed to one person’s keys;
state.dsn.rcpt is sliced in lockstep.
Mail to an alias works the same way, because the stage runs after pepsi-stage-aliases(1): a message encrypted to a role address’s gateway key is opened with that key, expanded to the alias’s members, and each member’s copy is sealed to that member’s own keys.
95.1.28.1.4. Where to put it¶
Immediately before local delivery (pepsi-stage-relay-to-maildir(1), pepsi-stage-relay-to-lmtp(1)), and therefore:
after pepsi-stage-decrypt(1): placed before it, the stage finds nothing opened and only passes mail through;
after every stage that reads the content: language detection and blocking, the whitelist and pay-to-send gates, pepsi-stage-autocrypt-learn(1) (which reads gossip from the plaintext), pepsi-stage-vacation(1);
after pepsi-stage-aliases(1) and pepsi-stage-dot-forward(1): a copy forwarded elsewhere must not leave sealed to a local user’s key, because its new recipient cannot open it.
pepsi-setup(1) warns when no decrypt stage leads to it, and when it leads to any of the stages above. Note that an LMTP server’s Sieve script sees the sealed message: rules that test the body, or with PROTECT_HEADERS the subject, no longer match.
95.1.28.1.5. What it writes¶
The envelope split is the one pepsi-stage-encrypt(1) uses. The
Content-* fields and Autocrypt-Gossip: (Autocrypt Level 1 §5.3) go
inside the ciphertext, and everything else stays on the outer block.
That includes Received:, From:/To:/Date:/Message-ID:, the
sender’s own Autocrypt: header (which a client must read before it can
decrypt anything), the DKIM/ARC fields, and X-Pepsi-Crypto, the gateway’s
verdict on how the message arrived. With PROTECT_HEADERS the RFC 5322
fields are also copied inside and the outer Subject becomes ....
No signature is added. The decrypt stage has already judged the sender’s
signature and recorded its verdict in state.crypto.in and in
X-Pepsi-Crypto. A gateway signature would only say “the gateway sealed
this”, and a mail client cannot tell that apart from a signature by the author.
A sender signature that survived decryption as a MIME layer (S/MIME, or PGP/MIME
multipart/signed inside the ciphertext) is part of the plaintext, so it is
sealed with it and still verifies in the client. An OpenPGP signature packed
into the same stream as the encryption is consumed by decryption and cannot be
reconstructed; the client then shows an unsigned message and the gateway’s
verdict header.
The container follows [pepsi] CRYPTO_ALLOW_DOWNGRADE exactly as for
outbound encryption (see pepsi.conf(5)). For an S/MIME client key the
per-peer capability record applies as well: a local user whose client cannot
read AuthEnvelopedData (Thunderbird) needs pepsi-keys peer capability set
ADDRESS cbc, or the stored copy arrives blank. With no record the copy is
sealed as AES-256-GCM AuthEnvelopedData.
95.1.28.1.6. With no key¶
ON_NO_CLIENT_KEY decides what happens to a local recipient who has no
usable MUA key, either because none is registered or because none can be sealed
to (an expired certificate, a container that the policy refuses, a key below
[pepsi] CRYPTO_MIN_RSA_BITS or on the known-compromised list
pepsi.compromised_key; this second case is also logged as a warning):
plaintext(default)File the plaintext, exactly as without this stage.
bounceRefuse the message: route it to BOUNCE_STAGE with enhanced status
5.7.5(RFC 3463, cryptographic failure). The returned DSN carries neither the body nor any header that the sender could have protected, because the sender encrypted the message and a DSN travels in clear: the header block is cut down toFrom,Sender,To,Cc,DateandMessage-ID, the body is emptied, andRET=HDRSis forced whatever the sender asked. Without a BOUNCE_STAGE the row is failed instead (and pepsi-setup(1) refuses that combination).A message that arrived in an S/MIME
EnvelopedData(AES-CBC or 3DES, no integrity protection;state.crypto.in.layersnames the container) is dropped instead of bounced, with a warning in the log and the telemetry keydecrypt-dropped. This stage only ever sees a message that the decrypt stage opened, so its bounce would tell the sender that the ciphertext opened: for a modified CBC ciphertext, that its padding was valid. A dropped message looks to its sender like one that did not open.
A refusal bounces rather than defers on purpose. A deferral would keep the plaintext in the queue for the message’s whole lifetime, which is a longer exposure, not a shorter one, and nothing would wake the message when a key is registered.
The option is read through the per-address override layer, so the site default in the section can be changed for one recipient with pepsi-settings(1):
pepsi-settings set bob@example.org reencrypt ON_NO_CLIENT_KEY bounce
95.1.28.1.7. Configuration¶
Options live in the stage’s own [stage-<name>] section (see
pepsi.conf(5)):
- NEXT_STAGE (mandatory)
Local delivery.
- BOUNCE_STAGE
Where a refusal goes; required when ON_NO_CLIENT_KEY is
bouncein the section, and advisable whenever a per-address override might say so.- ON_NO_CLIENT_KEY =
plaintext|bounce See With no key. Default
plaintext.- PROTECT_HEADERS = yes | no
Copy the RFC 5322 fields inside the ciphertext and replace the outer
Subjectwith.... The default is no, as for pepsi-stage-encrypt(1): the copy is for the mailbox, whose server lists and searches messages by the outer subject, and a client that cannot look inside shows every subject as....- ENABLED = yes | no
When off, the stage passes every message through unchanged. Default yes.
- LOCAL_DOMAINS, TARGETS, RECIPIENT_DELIMITER, REQUIRE_ACCOUNT
Which recipients this host serves, with the meaning and defaults of pepsi-stage-decrypt(1) (LOCAL_DOMAINS falls back to
[pepsi-ingress] ACCEPTED_DOMAINS).
The stage is unprivileged and folded into the multi-call pepsi binary:
sealing to a public key needs no private material, and the stage reads only
the public columns of pepsi.crypto_identity, which the ordinary pepsi
pipeline role may read.
95.1.28.1.8. State¶
Inputs: state.crypto.in.encrypted, state.crypto.in.decrypted and
state.crypto.in.for_client, written by pepsi-stage-decrypt(1).
Outputs: state.crypto.store, whose presence also keeps the stage from
ever sealing a row twice:
outcomereencrypted,plaintextorbounced.protocol,fingerprint,fingerprints,container,downgradedFor
reencrypted: which MUA keys the copy was sealed to (fingerprints, newest first;fingerprintis the first of them) and the container emitted.skippedFor
reencrypted, when present: the recipient’s other active keys that the copy was not sealed to, each with itsfingerprintand areason, which isprotocol(not the newest key’s protocol),limit(beyond the eighth), or the error that sealing to the key returned.reasonFor
plaintext/bounced:no-client-keyornot-localwhen the message was filed as it is, otherwise a short phrase (no usable key of the recipient’s own, or the error that made sealing to their key fail).
The state layout is described in pepsi.state(7).
Transitions: advances to NEXT_STAGE; reroutes to BOUNCE_STAGE (or
fails without one) under ON_NO_CLIENT_KEY = bounce; hands a multi-recipient
row back to the queue after splitting it.
95.1.28.1.9. Commands¶
- worker
Run as a persistent pepsi-dispatch(1) worker, reading message ids on standard input.
95.1.28.1.10. Global Options¶
- -c FILE, –config FILE
Read the configuration from FILE instead of searching the default locations.
- -L LOGLEVEL, –log LOGLEVEL
Set the logging verbosity (default
[pepsi] LOG, elseinfo).- -v, –verbose
Show log messages from all sources.
- -h, –help; -V, –version
Print a usage summary / the version and exit.
95.1.28.1.11. Security¶
The mechanism is described under “Re-sealing decrypted mail for storage” in the
Security chapter of the Pepsi manual, and what the manual claims for it under
“Client custody” in its Threat model chapter (and the Filed mail column of
its guarantees matrix). The guarantee is about copies already filed: while a
message is queued, every pepsi stage, this one included, sees the plaintext,
and a compromised stage could route a message past this stage.
95.1.28.1.12. Exit Status¶
- 0
The worker exited cleanly (standard input closed).
- 1
An error occurred (misconfiguration or a database error). The reason is written to the log.
- 78
The worker refused to start: its section or the
[pepsi]crypto policy does not parse. The dispatcher requeues what it handed over and retries the stage later. A database error while a message is processed is retried the same way as any other fault of this host (see pepsi-dispatch(1)).
95.1.28.1.13. Examples¶
Re-encrypt message 42 (it must be running):
echo 42 | pepsi-stage-reencrypt -c /etc/pepsi/pepsi.conf worker
The tail of an inbound pipeline:
[stage-dot-forward]
PROGRAM = pepsi-stage-dot-forward
NEXT_STAGE = reencrypt
[stage-reencrypt]
PROGRAM = pepsi-stage-reencrypt
NEXT_STAGE = local
BOUNCE_STAGE = bounce
Never file readable mail for anybody, and hide subjects too:
[stage-reencrypt]
PROGRAM = pepsi-stage-reencrypt
NEXT_STAGE = local
BOUNCE_STAGE = bounce
ON_NO_CLIENT_KEY = bounce
PROTECT_HEADERS = yes
95.1.28.1.14. See Also¶
pepsi-stage-decrypt(1), pepsi-stage-encrypt(1), pepsi-keys(1), pepsi-settings(1), pepsi-stage-relay-to-maildir(1), pepsi-stage-relay-to-lmtp(1), pepsi-dispatch(1), pepsi.conf(5), pepsi.state(7), pepsi-setup(1)
95.1.28.1.15. Bugs¶
Report bugs to the Pepsi issue tracker.