53. pepsi-stage-reencrypt

Before a message is filed, seal what the gateway decrypted again, to the recipient’s own key.

53.1. Role

pepsi-stage-decrypt opens mail encrypted to a user’s gateway (MTA) key so that the stages after it can read the content. pepsi-stage-reencrypt runs after those stages, immediately before local delivery, and seals the message again: to the key that the user registered for their own mail client (a custody = client identity, the MUA key). The mailbox then holds ciphertext that only this client can open. Reference: pepsi-stage-reencrypt(1).

53.2. Features

  • Only what the gateway opened. state.crypto.in must say the message arrived encrypted and was decrypted. Mail that arrived in plaintext, and mail that the decrypt stage left unopened for the client, pass through untouched.

  • One recipient, one key. A message with several recipients is split into one row per recipient first whenever any of them needs a sealed copy or a refusal; each copy is sealed to that recipient’s newest active MUA key, OpenPGP or S/MIME.

  • Headers. The sender’s Autocrypt: header, the transport trace, the addressing fields and X-Pepsi-Crypto stay outside; the content fields and Autocrypt-Gossip: go inside. PROTECT_HEADERS also hides the subject.

  • No signature is added: the decrypt stage’s verdict is already recorded in state.crypto.in and X-Pepsi-Crypto, and a gateway signature would only claim that the gateway sealed the message.

  • A policy for users with no key (ON_NO_CLIENT_KEY): deliver plaintext (default) or refuse with a 5.7.5 DSN that returns neither body nor subject. Settable per recipient through pepsi-settings. A message that arrived in an AES-CBC EnvelopedData is dropped rather than bounced, since the bounce would tell its sender that a possibly modified ciphertext opened (Bounces and replies to encrypted mail).

  • Unprivileged: sealing to a public key needs no private material, so unlike the other crypto stages it is folded into the multi-call pepsi binary and runs as the ordinary pepsi user.

  • The container is negotiated as for outbound encryption: [pepsi] CRYPTO_ALLOW_DOWNGRADE and, for an S/MIME client key, the per-peer capability record (Which S/MIME container a correspondent gets). With no record the copy is sealed as AES-256-GCM AuthEnvelopedData, so a Thunderbird user needs pepsi-keys peer capability set ADDRESS cbc or the stored copy arrives blank. A key that cannot be sealed to — expired, refused by the policy, too short or known to be compromised — is treated like no key, with a warning.

The guarantee that this stage provides is stated in Client custody (custody = client, the MUA key): copies already filed are readable only by the user’s own client. While a message is queued, every pepsi stage sees its plaintext.

53.3. Configuration

A mandatory NEXT_STAGE (local delivery), BOUNCE_STAGE (for refusals), ON_NO_CLIENT_KEY (plaintext/bounce), PROTECT_HEADERS (default no), ENABLED and the locality options LOCAL_DOMAINS / TARGETS / RECIPIENT_DELIMITER / REQUIRE_ACCOUNT with the decrypt stage’s defaults. The whole message is loaded. See Configuration.

[stage-reencrypt]
PROGRAM = pepsi-stage-reencrypt
NEXT_STAGE = local
BOUNCE_STAGE = bounce

53.4. Placement

After everything that reads the message or may forward a copy elsewhere — language detection, the spam gates, pepsi-stage-autocrypt-learn, aliases, vacation, ~/.forward — and directly in front of pepsi-stage-relay-to-maildir or pepsi-stage-relay-to-lmtp. The setup wizard offers it with the cryptography question and places it there; pepsi-setup warns about any other order.