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).
14.1. The flow¶
A local user sends a confidential message.
pepsi-stage-encryptfinds no usable key for the recipient and, becauseON_NO_KEYissecure-link, routes it topepsi-stage-secure-linkinstead of relaying it.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.
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.The recipient opens the link, enters the PIN, and reads the message. Attachments can be downloaded; if
REPLY_STAGEis configured, a reply can be written and sent back to the sender.After
EXPIRY_DAYS(7 by default) the message stops being readable, andpepsi-secure-link prune(run daily bypepsi-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--decryptand 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.
commandA 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.noneThis 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 aLOGO_FILEis 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, plusReferrer-Policy: no-referrer,X-Content-Type-Options: nosniff,X-Frame-Options: DENYandCache-Control: no-store(Missing HTTPS and HTTP security-header hardening on webmail).An attachment is always served
application/octet-streamas anattachmentwith 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.exeread asinvoiceexe.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 atREPLY_STAGEas 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-setupwarns ifREPLY_STAGEresolves to a signing stage. The reply carries anX-Pepsi-Secure-Link-Reply: …; author-unverifiedheader 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-Lengthgains 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,/resumeor 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 requiresPath=/;it is
HttpOnly,Secure,SameSite=Strictand host-only (noDomain), 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).