70.1.29. pepsi-stage-secure-link

hold a message that could not be encrypted, and mail the link

Manual section:

1

70.1.29.1.1. Name

pepsi-stage-secure-link - the secure-link fallback stage of the Pepsi pipeline.

70.1.29.1.2. Synopsis

pepsi-stage-secure-link [GLOBAL-OPTIONS] worker

70.1.29.1.3. Description

pepsi-stage-secure-link is a stage program run by pepsi-dispatch(1) as a persistent worker reading message ids on standard input.

It is the far end of [stage-encrypt] ON_NO_KEY = secure-link. When pepsi-stage-encrypt(1) must encrypt a message and the recipient publishes no usable key, it routes the message here instead of sending it in the clear or bouncing it. This stage then takes the message off the wire entirely:

1. it generates a PIN and a random URL token, derives a content key from them and the server-side pepper, and stores only the AEAD ciphertext of the whole message in pepsi.secure_message;

2. it injects a notification mail to the recipient carrying the link, and — under the default PIN_DELIVERY = sender — a second mail to the sender carrying the PIN, for the sender to relay by telephone or text message;

3. it deletes the queue row.

The row is deleted rather than advanced because advancing it would transmit the cleartext to the very recipient who must not receive cleartext. The message’s continuation is the notification, which is an ordinary outbound message injected at [pepsi-secure-link] NOTIFY_STAGE and signed and relayed like any other. The stage is therefore terminal and has no NEXT_STAGE.

A message with several keyless recipients produces one stored message per recipient, each with its own token, PIN and ciphertext, so one recipient’s PIN never opens another’s copy and the recipient list is not disclosed to any of them.

70.1.29.1.4. Configuration

The stage’s [stage-<name>] section carries only PROGRAM. Everything else lives in the global [pepsi-secure-link] section (see pepsi.conf(5)), deliberately: the expiry window, the PIN length and the lockout are not behavioural knobs a correspondent may edit by e-mail through pepsi-stage-edit-settings(1), and a global section is out of reach of the per-address override layer.

70.1.29.1.5. Example

[stage-encrypt]
PROGRAM = pepsi-stage-encrypt
ENCRYPT = required
SECURE_LINK_STAGE = secure-link
NEXT_STAGE = srs

[stage-secure-link]
PROGRAM = pepsi-stage-secure-link

[pepsi-secure-link]
BASE_URL = https://secure.example.org
NOTIFY_STAGE = srs
# PEPPER is written to secrets.d/pepsi-secure-link.secret by pepsi-setup.

70.1.29.1.6. Failure

Everything that can fail is done before the queue row is deleted, and a failure fails the message rather than dropping it: a message that reached this stage is by definition one the operator said must not go out unprotected. In particular the stage fails when [pepsi-secure-link] is unconfigured, when NOTIFY_STAGE is unset, when a notification template is missing, when PIN_DELIVERY = command and the gateway command fails, and when the envelope sender is null (there would be nobody to give the PIN to).

70.1.29.1.7. Exit status

The worker exits 0 on a clean end of input. Per-message failure is reported through the queue, not the exit status.

70.1.29.1.8. See also

pepsi-secure-link(1), pepsi-stage-encrypt(1), pepsi-httpd(1), pepsi-dispatch(1), pepsi.conf(5), pepsi.state(7)