14. The secure-link fallback portal¶

End-to-end encryption stops at the first correspondent who publishes no key, and most of them do not. A policy of ENCRYPT = required then leaves an operator with two bad answers: bounce the message, or send it in the clear anyway. The secure-link portal is the third: hold the message on the server, encrypted, and let the recipient read it in a browser after entering a PIN that reached them by another route.

It is the third branch of pepsi-stage-encrypt’s ON_NO_KEY policy (and of ON_OVERSIZE, for a message over MAX_SIZE). Key management describes the other two branches and the key store that decides which branch is taken. Under ENCRYPT = required both policies default to secure-link as soon as SECURE_LINK_STAGE names the stage, so the example below needs no ON_NO_KEY line. The encryption stage also routes a recipient here when the key lookup for that recipient keeps failing in the DNS while the domain’s mail servers answer, because that is what suppressing a key looks like (A key lookup that fails in the DNS).

On this page

  • The flow

  • What this protects, and what it does not

  • Replying

  • Where to put the portal

  • Storage and sizing

  • Operating it

  • Branding

  • Languages

  • See also

14.1. The flow¶

  1. A local user sends a confidential message. pepsi-stage-encrypt finds no usable key for the recipient and, because ON_NO_KEY is secure-link, routes it to pepsi-stage-secure-link instead of relaying it.

  2. That stage generates a PIN and derives a 192-bit URL token from the queue row (see pepsi-stage-secure-link(1)). It derives a content key from the PIN, a per-message salt and the server pepper; the token is not an input to that derivation but the AEAD’s associated data. The stage then stores only the ciphertext and deletes the queue row.

  3. The recipient receives a notification mail with a link. The sender receives the PIN (the default PIN_DELIVERY = sender) and passes it on by telephone, text message or in person.

  4. The recipient opens the link, enters the PIN, and reads the message. Attachments can be downloaded; if REPLY_STAGE is configured, a reply can be written and sent back to the sender.

  5. After EXPIRY_DAYS (7 by default) the message stops being readable, and pepsi-secure-link prune (run daily by pepsi-secure-link-prune.timer) deletes it.

The pipeline looks like this:

[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
ORGANIZATION = Example Ltd
# PEPPER is written to secrets.d/pepsi-secure-link.secret by pepsi-setup.

NOTIFY_STAGE is on the outbound path, because the notification and PIN mails are messages that the deployment originates and must sign and relay normally. Each is stamped with a recipient-bound Pepsi-Origin header, so when one reaches a mailbox on the same deployment the pay-to-send gate lets it through; a reply written in the portal passes the gate too (pepsi-stage-anti-spam).

14.2. What this protects, and what it does not¶

The claims below make up the threat model’s entry for the stored message in its list of assets (Assets) and its section on the database thief (Somebody holding a copy of the database). The mechanisms are summarised under “The secure-link portal” in Security model, and the portal’s resource bounds in Availability.

14.2.1. The stored message¶

The content key is derived with Argon2id (RFC 9106) from three inputs kept in three different places. Pepsi uses Argon2id rather than a plain hash or PBKDF2 because the secret being stretched is a short PIN (by default ten characters from a 31-symbol alphabet that leaves out look-alikes). What has to be made expensive is a parallel offline search, and only a memory-hard function raises the cost of the hardware that an attacker would use, rather than merely the time.

The three inputs:

  • the PIN, which reaches the recipient out of band and is stored nowhere;

  • a per-message salt, which is a database column (a salt is not a secret — it is what stops one precomputation covering every message, see Offline guessing of weak password hashes, key passphrases and derived keys);

  • a server-side pepper, which lives only in secrets.d/pepsi-secure-link.secret.

Only the ciphertext is stored. The cipher is AES-256-GCM, an AEAD, so the stored message is authenticated as well as confidential, and a tampered ciphertext fails to open rather than decrypting to something that an attacker chose. We do this to avoid malleable stored messages (OpenPGP integrity protection (MDC) missing, strippable or not enforced). Consequently:

  • A stolen database is not a mailbox. A dump, a replica or a backup tape yields ciphertext and a salt, and neither the PIN nor the pepper is in it.

  • A server compromised after the fact is not a mailbox either. For the messages stored before they arrived, an attacker who also takes the pepper still has to find the PIN, and a 10-character PIN under Argon2id is too costly to search. An attacker who stays in control of the pipeline sees every new message in the clear as it is submitted, like any other queued mail.

  • There is no password verifier. Verifying a PIN and decrypting with it are the same operation, because the AEAD tag is the check, so nothing stored can be cracked offline into a PIN (Offline guessing of weak password hashes, key passphrases and derived keys, Offline guessing of weak password hashes, key passphrases and derived keys).

  • The administrator cannot read a stored message. The database is not enough, the pepper is not enough, and both together are not enough either. There is no pepsi-secure-link read, no --decrypt and no escrow key. This is a property of the stored message: the operator is trusted with mail in transit (Threat model), and an operator who modifies the server can capture a message before it is sealed.

The cost of that last property: a lost PIN is a lost message. The recovery path is that the sender sends it again, which issues a new PIN and a new link. Expect to be asked for an escrow key; adding one would give back exactly the capability that this design exists to remove.

Losing the pepper has the same effect on a larger scale: every stored message becomes unreadable at once. Back it up with the rest of secrets.d, and remember that rotating it invalidates every outstanding link.

14.2.2. What is not protected: the metadata¶

The following is deliberately stored in the clear, as ordinary database columns:

  • the sender and the recipient, because the notification and the second factor have to be delivered, and “did this reach them?” has to be answerable;

  • timestamps — created, expires, first read;

  • lifecycle counters — read count, failed PIN attempts, lockouts, replies;

  • the access log — when each attempt happened, from which address, and how it ended.

The subject is not in that list. It is usually the single most revealing field, and often it is the message (“Biopsy results”, “Termination letter”). Nothing in routing or expiry needs it, so it is stored inside the ciphertext along with the body.

So an operator console lists who and when, never what, and so does the read receipt. Support is correspondingly harder: “the message you sent to Bob at 09:14 was read at 11:02” is the most anyone here can say, and there is no way to confirm what was in it.

The access log records the peer address and nothing else — no user agent, and no geolocation.

14.2.3. The second factor¶

The whole construction rests on the PIN travelling by a channel that the recipient’s mailbox does not control. PIN_DELIVERY chooses it:

sender (default)

The PIN is mailed to the sender, who relays it. This needs no external service, works everywhere, and uses a channel that the two correspondents already trust. It does depend on the sender actually using a second channel: mailing the PIN on to the same address would defeat it, and the PIN mail says so.

command

A configured program (an SMS gateway, a corporate messaging hook) receives the PIN on standard input and the recipient address as its argument. The address comes after a --, so that an address beginning with - cannot pose as an option. This is the strongest choice when a real second channel exists.

none

This is materially weaker, and you should choose it deliberately. The link itself carries the PIN, so anybody who can read the recipient’s mailbox can read the message, and preventing exactly that is what the feature exists for. It also puts the PIN in a URL, and therefore potentially in a browser history or an intermediary’s logs. Use it only where the mailbox genuinely is the factor.

14.2.4. Brute force¶

A PIN short enough to read aloud is short enough to guess, so guessing is bounded twice. Per token, MAX_ATTEMPTS wrong PINs (10 by default) lock it for LOCKOUT (15 minutes), and the window doubles with each further lockout, up to 64 times the base; during a lockout even the correct PIN is refused. The failure counter is reset when a lockout starts, so the next window is a fresh budget rather than an instant re-lock. Per source, RATE_LIMIT caps requests per minute across every portal route, which also keeps the deliberately expensive key derivation from becoming a way to spend the server’s memory.

During a lockout no guess is evaluated at all, so nothing is learnt from guessing through it (Login and recovery rate limits defeated by races and logic errors). Guesses submitted in parallel cannot exceed the budget either (Login and recovery rate limits defeated by races and logic errors): each attempt is charged as a failure before its key derivation. A single database statement does this, holding the token’s row lock while it checks for a lockout and counts the attempt. Of any number of concurrent guesses, at most MAX_ATTEMPTS are therefore tested, and the guess that spends the budget starts the lockout that refuses the rest. A correct PIN then clears the charge (and any lockout) when the result is recorded.

Only an actual guess is counted. A form whose PIN field is empty, or holds nothing that normalisation keeps, is refused without touching the counter and without running the derivation. Such a form tells an attacker nothing that they did not already know, and counting it would let any client that re-submits the form empty (a double submit, a prefetch, a redirect follower that keeps the method) lock a legitimate recipient out of their own message.

A held session is not subject to the lockout, so a third party guessing at the same token cannot lock a legitimate reader out mid-read.

14.2.5. The browser¶

Rendering attacker-controlled mail in a browser is the largest risk that this feature carries, and it is addressed by not doing it:

  • The message is rendered as text, never as HTML. An HTML-only message is folded to text; markup does not survive. There is therefore no HTML sanitiser that could be bypassed, and no remote content: the policy says img-src 'none' (img-src data: when a LOGO_FILE is inlined) and means it, so a tracking pixel cannot report that the message was opened. Formatting and inline images are lost; a recipient who needs the original can download the parts. We do this to avoid sanitiser bypasses and injected forms (Hand-written or single-pass HTML sanitisers let active content survive, Hand-written or single-pass HTML sanitisers let active content survive).

  • Every dynamic value on a page — subject, sender, date, filename, organisation name — is HTML-escaped at the point it is written into the page (Reflected and stored XSS or HTML injection in portals and admin mails).

  • Every response carries Content-Security-Policy: default-src 'none' with a per-response nonce for the one inline stylesheet and no script source named at all, plus Referrer-Policy: no-referrer, X-Content-Type-Options: nosniff, X-Frame-Options: DENY and Cache-Control: no-store (Missing HTTPS and HTTP security-header hardening on webmail).

  • An attachment is always served application/octet-stream as an attachment with a sandboxing policy, whatever type the message claimed, so it cannot run as script on the portal’s origin (Attachments served same-origin with an active content type).

  • An attachment’s file name is shown and offered without bidirectional formatting characters (U+202A to U+202E, U+2066 to U+2069, U+200E, U+200F, U+061C), so a right-to-left override cannot make invoice<RLO>fdp.exe read as invoiceexe.pdf. A name longer than 120 characters has its stem cut, keeping its extension, so padding cannot push the real extension out of sight. The mailing-list archive and digests treat file names the same way.

  • The subject, the sender and each file name are wrapped in an HTML <bdi> element. Subjects and display names keep bidirectional characters, because right-to-left text needs them; the element ensures that an override in them reorders only its own text and cannot rearrange the labels and values around it.

14.3. Replying¶

In a read-only portal the recipient can read confidentially but must answer in the clear, giving back much of what the feature bought. So replying is supported. A reply injects a message from the public web, so its constraints are built into the code rather than left to procedure:

  • The reply goes only to the original sender, and its envelope sender is forced to the stored recipient. Neither is an input, so there is nothing to abuse. This keeps the portal from being an open relay, and it is why no field of the delivered mail can redirect a reply (Portal binding data kept in unauthenticated ciphertext fields).

  • The injected message does not carry state.local_origin. It enters at REPLY_STAGE as what it is: inbound mail that happens to have originated at our own web server. It therefore cannot take the submission path: it is not relayed as our own mail, it does not add its sender to the whitelist, and SRS does not treat it as mail of local origin.

  • It is not DKIM-signed as one of your domains. The author is an external party; pepsi-setup warns if REPLY_STAGE resolves to a signing stage. The reply carries an X-Pepsi-Secure-Link-Reply: …; author-unverified header so the recipient can tell how it arrived.

  • The body is text/plain, whatever was typed. Composing HTML would mean sanitising outbound HTML as well as inbound.

  • Attachments are allowed, with caps on the total size, the number of files and the replies per message. The size cap is enforced while the upload streams, so a client that misstates Content-Length gains nothing. Uploads are never written to disk but go straight into the injected message. There is therefore no second storage lifetime, nothing is left behind if the injection fails, and no file name that a sender chose ever becomes a path (Path traversal when extracting or serving archive members).

  • Every reply is recorded in the message’s access log.

Replying is off unless REPLY_STAGE is set.

14.4. Where to put the portal¶

A dedicated hostname is recommended: one DNS record and one certbot SAN buy a real separation of origins. It is not required, though, and a shared origin is safe by construction rather than by discipline:

  • the session cookie is Path=/secure/-scoped, so it is never sent to /metrics, /resume or the Web Key Directory even on one host;

  • its value is an AEAD sealed under the server pepper, so a cookie planted by a sibling subdomain does not open. Without the seal, the cookie would need a __Host- prefix, which RFC 6265bis makes incompatible with path scoping because the prefix requires Path=/;

  • it is HttpOnly, Secure, SameSite=Strict and host-only (no Domain), and no session token ever travels in a URL (Reflected and stored XSS or HTML injection in portals and admin mails);

  • the security headers are set per route, not per host, so the portal’s tight policy applies wherever it is mounted.

The portal must be reachable over HTTPS from the browser: the session cookie carries Secure. A TLS-terminating reverse proxy in front is fine.

14.5. Storage and sizing¶

The ciphertext lives in the database as BYTEA. That keeps everything transactional — creating a secure message is one insert, pruning is a DELETE, and backup and restore cover the content automatically, with no orphaned files and no second place whose permissions have to be right.

The cost is a larger database and more WAL traffic, in proportion to the traffic on the portal. A message is stored once per keyless recipient (each with its own PIN and ciphertext, so one recipient’s PIN never opens another’s copy), and [stage-encrypt] MAX_SIZE (25 MB by default) bounds each one. Size a deployment accordingly, and keep pepsi-secure-link prune running daily (the Debian package ships pepsi-secure-link-prune.timer for it). The portal refuses an expired token anyway, but nothing deletes the bytes until the job runs.

14.6. Operating it¶

pepsi-secure-link list shows what is outstanding; show adds one message’s access log; revoke destroys a message, withdrawing it rather than putting the mail back in the queue; prune deletes what has expired. See pepsi-secure-link(1).

The database boundary is narrower than the rest of the schema and is verified on every pepsi-setup run: only the pepsi-httpd role can read secure_message.ciphertext. Every stage worker runs under the pepsi role, including the ones that parse hostile mail; that role can create a message, list the metadata and delete a row, but cannot read a message back. pepsi-ingress, pepsi-telemetry, pepsi-crypto, pepsi-keydisc, pepsi-whitelist and pepsi-config cannot touch the tables at all (The privilege split).

14.7. Branding¶

ORGANIZATION, BRAND_COLOR and LOGO_FILE set the appearance of the pages; ORGANIZATION is also named in the notification mails. The colour must be a hexadecimal colour and the logo must be a local raster image, both for the same reason: they are interpolated into a page, and a value that could be arbitrary text or an SVG would widen the page’s attack surface. The three notification mails themselves are Mustache templates (secure-link, secure-pin, secure-receipt) under [pepsi] TEMPLATE_DIR and can be rewritten wholesale.

14.8. Languages¶

The secure-link mails and pages reach people who never chose Pepsi, so they are not English-only. The three mails ship in the same ten languages as the mailing-list notices (English, German, Spanish, French, Hungarian, Italian, Russian, Swedish, Turkish and Ukrainian), as secure-link.<lang>.body and so on, and the pages of the portal are translated into the same ten.

The mails are written in the language of the message that they announce. When pepsi-stage-detect-language ran earlier in the pipeline, it stored a string in the style of Accept-Language on the message, and that string chooses the template: in q order, with the usual regional fallback (de-CH → de) and English last. A pipeline without that stage sends English. The subject line is translated along with the body, but from a catalogue inside the binary rather than from the template file. An operator who adds an eleventh language to TEMPLATE_DIR therefore gets that body under an English subject; this is the documented limit of overriding the templates through files. A subject that is not ASCII is RFC 2047-encoded on the way out.

The pages are written in the language the browser asks for. The portal reads the request’s Accept-Language and nothing else, and it does so before it looks up the token, so that a throttled or refused visitor is told so in their own language too. The rules are the ones that every page of pepsi-httpd follows (see The administration console): languages are tried in q order, a regional tag is served its base language, q=0 refuses a language, and English is used when the browser names none of the server’s languages. Here the recipient’s browser preference, not the detected language of the mail, deliberately decides: the browser states its user’s own preference with every request, and a message in a language that the recipient reads is no evidence of which language they read best.

14.9. See also¶

Key management (the store and the discovery layer that decide whether a recipient needs this fallback at all), pepsi-stage-encrypt (ON_NO_KEY = secure-link), pepsi-stage-secure-link, pepsi-secure-link (the operator CLI), pepsi-httpd (which serves the portal), pepsi.conf(5).

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
    • 14.1. The flow
    • 14.2. What this protects, and what it does not
    • 14.3. Replying
    • 14.4. Where to put the portal
    • 14.5. Storage and sizing
    • 14.6. Operating it
    • 14.7. Branding
    • 14.8. Languages
    • 14.9. See also
  • 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
  • 96. Vulnerabilities in E-mail implementations
  • 97. RFC Index
  • 98. Bibliography

Related Topics

  • Documentation overview
    • Previous: 13. Key management
    • Next: 15. Client interoperability

Quick search

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