95.1.56. pepsi-secure-link¶
inspect and manage messages held in the portal
- Manual section:
1
95.1.56.1.1. Name¶
pepsi-secure-link - operator CLI for the secure-link fallback portal.
95.1.56.1.2. Synopsis¶
95.1.56.1.3. Description¶
pepsi-secure-link inspects and manages the messages held in the secure-link fallback portal (see pepsi-stage-secure-link(1) and pepsi-httpd(1)). It is an operator tool, not a stage.
Global options (-c/--config, -L/--log, -v) come before the
subcommand. When run as root, the tool adopts the pepsi service account,
so it authenticates to PostgreSQL as the role that owns the queue.
95.1.56.1.4. What it can and cannot show¶
It reports who and when, never what. There is no subcommand that displays a
stored message, no --decrypt flag and no escrow key: the content key is
derived with Argon2id from the recipient’s PIN, a per-message salt and a
server-side pepper, and the PIN is never stored. Nothing that an administrator
holds can reconstruct the key: not the database, not the pepper, and not both
together.
So when a recipient loses the PIN, the sender sends the message again; a new PIN is issued and a new link mailed. There is no “resend the PIN”, because the PIN exists nowhere but in the correspondents’ hands.
95.1.56.1.5. Commands¶
- list
Outstanding messages, newest first: token, sender, recipient, expiry, read count, failed-PIN count and any lockout.
--expiredalso shows messages that have run out but have not been pruned yet.--limitcaps the listing (50 by default) and--jsonprints the same fields as JSON.- show TOKEN
One message’s metadata plus its access log: when each attempt happened, from which address, and how it ended (
read,bad-pin,locked,reply). The log is capped per message by[pepsi-secure-link] ACCESS_LOG_ROWS, which is also how many rowsshowprints, and is deleted with the message.- revoke TOKEN
Destroy one message. This does not put the mail back in the queue; it withdraws it, and the recipient’s link stops working. If revoking it was a mistake, the sender re-sends.
- prune
Delete every message past its expiry, together with its access log; the stored message is the only copy. The command is intended for a daily cron job or systemd timer, like
pepsi-tlsrpt prune; the Debian package shipspepsi-secure-link-prune.timer, which runs it daily asroot(the tool then adopts thepepsiaccount).--grace-hourskeeps expired messages a little longer. A deployment that never prunes keeps unreadable ciphertext in the database for ever: the portal already refuses an expired token, so this is a problem of database size rather than of confidentiality, but it is still a problem.
95.1.56.1.6. Privileges¶
The tool runs as the pepsi database role, which is granted INSERT and
DELETE on pepsi.secure_message and SELECT on every column of it
except ciphertext, plus SELECT and DELETE on the access log
(pepsi.secure_access). Only the pepsi-httpd role, which serves the
portal, can read the ciphertext. That is why list and show work and why nothing here can
print a message even by accident; pepsi-setup verifies the boundary against
the live database on every run.
95.1.56.1.7. Exit status¶
0 on success, non-zero on error (including show/revoke for a token
that does not exist).
95.1.56.1.8. See also¶
pepsi-stage-secure-link(1), pepsi-stage-encrypt(1), pepsi-httpd(1), pepsi-setup(1), pepsi.conf(5)
The Pepsi manual: “The secure-link fallback portal” (the construction and its consequences), “Security” (the secure-link portal mechanisms) and “Threat model” (the stored-message asset and the database thief).