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¶

pepsi-secure-link [GLOBAL-OPTIONS] list [–limit N] [–expired] [–json]
pepsi-secure-link [GLOBAL-OPTIONS] show TOKEN [–json]
pepsi-secure-link [GLOBAL-OPTIONS] revoke TOKEN
pepsi-secure-link [GLOBAL-OPTIONS] prune [–grace-hours N]

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. --expired also shows messages that have run out but have not been pruned yet. --limit caps the listing (50 by default) and --json prints 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 rows show prints, 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 ships pepsi-secure-link-prune.timer, which runs it daily as root (the tool then adopts the pepsi account). --grace-hours keeps 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).

Logo

Pepsi 0.1.2

Languages

  • English
  • Deutsch
  • français

Navigation

Contents

  • 1. Introduction
  • 2. Design principles
  • 3. Getting started on a cheap VPS
  • 4. Installation
  • 5. Debian packages
  • 6. The Wizard
  • 7. Configuration
  • 8. Operating Pepsi
  • 9. Using Pepsi: a guide for users
  • 10. Troubleshooting
  • 11. Supported Features
  • 12. SMTP Protocol Extensions
  • 13. Key management
  • 14. The secure-link fallback portal
  • 15. Client interoperability
  • 16. Threat model
  • 17. Security model
  • 18. Dependencies
  • 19. Microsoft Exchange as a gateway
  • 20. Mail client extensions
  • 21. Mailing lists
  • 22. Archives
  • 23. The GNU Mailman 3 REST API
  • 24. The administrative API
  • 25. The administration console
  • 26. Architecture
  • 27. The message state
  • 28. Extending the Pipeline
  • 29. Test Suite
  • 30. Benchmark Suite
  • 31. Performance
  • 32. pepsi-ingress
  • 33. pepsi-dispatch
  • 34. pepsi-httpd
  • 35. pepsi-stage-arc
  • 36. pepsi-stage-srs
  • 37. pepsi-stage-encrypt
  • 38. pepsi-stage-decrypt
  • 39. pepsi-stage-dkim-sign
  • 40. pepsi-stage-bounce
  • 41. pepsi-stage-aliases
  • 42. pepsi-stage-relay-to-internet
  • 43. pepsi-stage-relay-to-smarthost
  • 44. pepsi-stage-relay-to-maildir
  • 45. pepsi-stage-dot-forward
  • 46. pepsi-stage-relay-to-lmtp
  • 47. pepsi-stage-discard
  • 48. pepsi-stage-anti-spam
  • 49. pepsi-stage-auto-pay
  • 50. pepsi-stage-check-whitelist
  • 51. pepsi-stage-auto-whitelist
  • 52. pepsi-stage-autocrypt-learn
  • 53. pepsi-stage-reencrypt
  • 54. pepsi-stage-detect-language
  • 55. pepsi-detect-language
  • 56. pepsi-stage-block-language
  • 57. pepsi-stage-vacation
  • 58. pepsi-stage-secretary
  • 59. pepsi-stage-edit-settings
  • 60. pepsi-stage-if
  • 61. pepsi-stage-milter
  • 62. pepsi-stage-quarantine
  • 63. pepsi-stage-route
  • 64. pepsi-stage-vks-confirm
  • 65. pepsi-stage-dmarc-report
  • 66. pepsi-stage-defang
  • 67. pepsi-stage-secure-link
  • 68. pepsi-setup
  • 69. pepsi-queue
  • 70. pepsi-status
  • 71. pepsi-reputation
  • 72. pepsi-greylist
  • 73. pepsi-dkim
  • 74. pepsi-sendmail
  • 75. pepsi-whitelist
  • 76. pepsi-keys
  • 77. pepsi-keydisc
  • 78. pepsi-settings
  • 79. pepsi-list
  • 80. pepsi-archive
  • 81. pepsi-stage-list
  • 82. pepsi-stage-list-post
  • 83. pepsi-stage-list-deliver
  • 84. pepsi-stage-list-command
  • 85. pepsi-stage-list-bounce
  • 86. pepsi-tlsrpt
  • 87. pepsi-secure-link
  • 88. pepsi-failure-bouncer
  • 89. pepsi-quota
  • 90. pepsi-helper-token-refresh
  • 91. pepsi-telemetry
  • 92. pepsi-telemetry-client
  • 93. pepsi-config
  • 94. Feature stability
  • 95. Manual pages
    • 95.1. Commands (section 1)
    • 95.2. Configuration file (section 5)
    • 95.3. Message state (section 7)
  • 96. Vulnerabilities in E-mail implementations
  • 97. RFC Index
  • 98. Bibliography

Related Topics

  • Documentation overview
    • 95. Manual pages
      • Previous: 95.1.55. pepsi-tlsrpt
      • Next: 95.1.57. pepsi-failure-bouncer

Quick search

©2026, GNUnet e.V.. | Powered by Sphinx 9.1.0 & Alabaster 0.7.16 | Page source