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.

bounce

Refuse 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 to From, Sender, To, Cc, Date and Message-ID, the body is emptied, and RET=HDRS is 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.layers names the container) is dropped instead of bounced, with a warning in the log and the telemetry key decrypt-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 bounce in 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 Subject with .... 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:

outcome

reencrypted, plaintext or bounced.

protocol, fingerprint, fingerprints, container, downgraded

For reencrypted: which MUA keys the copy was sealed to (fingerprints, newest first; fingerprint is the first of them) and the container emitted.

skipped

For reencrypted, when present: the recipient’s other active keys that the copy was not sealed to, each with its fingerprint and a reason, which is protocol (not the newest key’s protocol), limit (beyond the eighth), or the error that sealing to the key returned.

reason

For plaintext/bounced: no-client-key or not-local when 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, else info).

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