95.1.39. pepsi-stage-vks-confirm¶
follow a key server’s address-verification link, safely
- Manual section:
1
95.1.39.1.1. Name¶
pepsi-stage-vks-confirm - the key-server confirmation stage of the Pepsi pipeline.
95.1.39.1.2. Synopsis¶
pepsi-stage-vks-confirm [GLOBAL-OPTIONS] worker
95.1.39.1.3. Description¶
pepsi-stage-vks-confirm is a stage program run by pepsi-dispatch(1) as a persistent worker reading message ids on standard input.
A key uploaded to a verifying key server is stored but not findable by address until somebody follows a link in a mail the server sends to that address. Doing that by hand for every user’s key does not scale, so this stage does it. Because “fetch a URL found in inbound mail” is a genuinely dangerous primitive, the stage is a separate program rather than behaviour added to pepsi-keys(1) or a cryptography stage. The dangerous part thus sits in one small, unprivileged program whose position in the pipeline is visible in the configuration.
Place it on the inbound path, anywhere before local delivery. Placement is
forgiving: everything the stage does not act on is advanced to NEXT_STAGE
untouched, which is nearly all mail.
95.1.39.1.4. What it refuses to act on¶
Every condition below must hold before a single byte is fetched. A message that fails any of them is advanced untouched, so the failure mode is that the user receives the mail and can click the link themselves. That is why the conditions can afford to be strict.
The envelope sender’s domain is exactly
VKS_HOST. Not a substring, not a subdomain, and not theFrom:header:keys.example.org.evil.testends with the right string,notkeys.example.orgcontains it, and neither is the key server.SPF or DMARC passed (
REQUIRE_AUTHENTICATION, on by default). AMAIL FROMis a claim; this is what makes it evidence. Note thatdkim=passdeliberately does not count: it says that a signature verified, not whose, and an attacker signing with their own domain gets one for free.Every
http(s)link in the body ishttpsto that same host, on the default port. A message naming any other host (or a plainhttplink, or another port) is refused entirely rather than having the foreign link skipped, and one carrying no link at all is simply delivered. A genuine verification mail links to the key server and nowhere else, so a foreign link means either the mail is not what it claims or the key server changed its mail in a way worth looking at before acting on it automatically. The host is read after any userinfo, becausehttps://keys.example.org@evil.test/is a request toevil.testand reads at a glance as the opposite.A recipient is an address we are actually waiting on: a published, active OpenPGP identity that has been uploaded and is not verified yet. An unsolicited verification mail, for an address that we never uploaded or one whose confirmation already arrived, is delivered, not clicked. This is also what stops a stranger making Pepsi issue requests by mailing a served address.
The mail names that identity’s key. The key server states the fingerprint of the key that a confirmation is for, and an identity counts only if its own fingerprint appears in the text (case and spacing ignored). A confirmation for some other key, such as one that a third party uploaded under our user’s address, is delivered, not clicked, since clicking it would publish that key for the address. This is checked before anything is fetched, and only the identities named are re-checked afterwards.
At most
MAX_LINKSlinks are followed per message.The fetch itself goes through the same hardened client that key discovery uses: HTTPS only, certificates verified (against the system roots, or only the
[pepsi-keydiscovery] TLS_CA_BUNDLEfile when one is set), the peer address resolved here and vetted (so a name resolving to loopback, a private range, link-local or the cloud metadata address is refused), the body capped while streaming, and at most one same-host redirect.
95.1.39.1.5. Confirming is not assumed¶
A 200 from the confirmation URL is the server’s answer to a request, not a
statement that the address is now published. So after following the links the
stage asks the key server whether it now serves our key for the address, and
only a fingerprint match records the identity as verified. Marking it on the
200 alone would stop pepsi-keys(1)’s retry job from ever trying again.
The same check decides the mail’s fate: it is discarded (DISCARD_CONFIRMED)
only when at least one identity was verified, and delivered otherwise.
A key server may serve another key for the address: somebody else’s key,
uploaded and confirmed under one of this site’s addresses. The stage logs this
at warn, naming the address, the server, the fingerprint served and the one
that this site publishes, and the identity is not marked verified. That is not a
slow server: either the confirmation mail for that key reached a mailbox here,
or an account that can read it, or the key server confirmed it some other way,
and correspondents who look the address up there now find that key. Have it
removed at the key server and check who can read the address’s mail.
95.1.39.1.6. Audit trail¶
Every decision is logged at info on the vks-confirm target: whether the
message was accepted or refused and why, each link followed and the status that
it returned, and the resulting verdict. Another key served for one of the
addresses is logged at warn. That is deliberately complete rather than sampled: a
program that fetches URLs found in mail must leave a record of every fetch it
made.
95.1.39.1.7. Configuration¶
[stage-<name>] with PROGRAM = pepsi-stage-vks-confirm:
- NEXT_STAGE (required)
Where every message that this stage does not consume goes, which is nearly all of them. Required precisely because of that: a stage on the inbound path that silently dropped what it did not recognise would lose ordinary mail. pepsi-setup(1) checks that the target resolves.
- VKS_HOST (default: the host of
[pepsi-keys] VKS_SERVER) The one host that this stage will accept a verification mail from and follow a link to. It must be the host of
[pepsi-keys] VKS_SERVER(which itself defaults to the first[pepsi-keydiscovery] VKS_SERVERSentry), compared case-insensitively and without port or path: that server receives the uploads, so its verification mail is the mail that this stage waits for. pepsi-setup(1) refuses a configuration in which the two name different hosts, since the stage would then ignore every confirmation. Setting it is therefore only ever a restatement; leave it out.- MAX_LINKS (default 3)
How many links one message may cost. A genuine verification mail carries one; the bound is what stops a message that got past every other check from becoming an arbitrary number of requests.
- DISCARD_CONFIRMED (default
yes) Delete a confirmation mail the stage has acted on instead of delivering it. It is machine mail about an action Pepsi took, addressed to a mailbox whose owner did not ask for it, and it has already been acted on by the time it would arrive. Only a mail after which the key server was seen serving our key for at least one identity is deleted: when following its links verified nothing, the mail is delivered whatever this option says, since it is then the one way left to finish the confirmation by hand. Set it to
noto deliver every confirmation mail.- REQUIRE_AUTHENTICATION (default
yes) Require SPF or DMARC
pass, not merely the right envelope sender.
There is no BOUNCE_STAGE: the stage never fails a message. A fault of this
host fails open too. It is logged at warn and the mail is delivered
untouched, since waiting would hold ordinary mail for something that the user
can do by hand. Such faults are a section that does not parse for this message
(a per-address override can break it), a database that cannot say which
confirmations are pending, and an HTTP client that cannot be built. A failure to record a confirmed
identity is logged the same way, and the mail is then delivered rather than
discarded. The base configuration (this section, [pepsi-keys] and
[pepsi-keydiscovery]) is checked when the worker starts instead: a broken
one makes the worker refuse to start (exit 78), so the dispatcher holds the
queue rather than let the stage become a silent pass-through.
95.1.39.1.8. Message data¶
The stage loads the full message (Load::Full) because the links are in the
body. It never rewrites the message, never pauses or fails it, and leaves
state untouched, so state.dsn and every other verdict survive.
95.1.39.1.9. Commands¶
- worker
Read message ids on standard input and process each. The only run mode; the dispatcher starts and stops these workers.
95.1.39.1.10. Global Options¶
- -c FILE, –config FILE
Read the configuration from FILE instead of searching the default locations. Must come before the subcommand.
- -L LOGLEVEL, –log LOGLEVEL
Set the logging verbosity (default
[pepsi] LOG, elseinfo).- -v, –verbose
Show log messages from all sources.
- -h, –help; -V, –version
Print a usage summary / the version and exit.
95.1.39.1.11. Exit Status¶
- 0
The worker exited cleanly.
- 1
An error occurred (a malformed configuration file, an unresolvable stage section, or a failed database connection). The reason is written to the log.
- 78
The worker refused to start: its section,
[pepsi-keys]or[pepsi-keydiscovery]does not parse. The dispatcher requeues what it handed over and retries the stage later.
95.1.39.1.12. Examples¶
An inbound pipeline that confirms key-server mail before local delivery:
[pepsi-keys]
VKS_SERVER = https://keys.openpgp.org
[stage-vks-confirm]
PROGRAM = pepsi-stage-vks-confirm
NEXT_STAGE = local
Process one message by hand:
echo 4711 | pepsi-stage-vks-confirm -c /etc/pepsi/pepsi.conf worker
95.1.39.1.13. See Also¶
pepsi-keys(1), pepsi-httpd(1), pepsi-keydisc(1), pepsi-dispatch(1), pepsi.conf(5), pepsi.state(7)
The manual’s Security chapter (Key-discovery SSRF, Key-discovery certificate authorities) describes the fetch hardening this stage shares with key discovery.
95.1.39.1.14. Bugs¶
Report bugs to the Pepsi issue tracker.