77. pepsi-keydisc¶
Find a correspondent’s public key or certificate, and record how much its source is worth.
77.1. Role¶
pepsi-keydisc is the key-discovery layer: given an e-mail address it
finds the correspondent’s OpenPGP key or S/MIME certificate, records where it
came from and whether the lookup was DNSSEC-validated, and caches it in
pepsi.peer_key. It is not a stage. It connects through
[pepsi-postgres] and is configured entirely by [pepsi-keydiscovery].
Discovery is asynchronous and outside the stages. A stage that needs a key
that it does not have in its cache performs no network I/O: it commits the work it has
already done, pauses the message and enqueues a request in pepsi.key_request;
a discovery instance answers the request and, in the same round-trip that stores
the key, releases every message parked on that address. So no stage worker ever
waits on a key server, a hundred messages to one correspondent cost one lookup,
and a request that settles without a key releases its waiters just the same.
The services find keys, and the stages decide about mail.
Reference: pepsi-keydisc(1).
The chapter Key management explains the trust ranking by which these results are judged, and how the discovery layer relates to the key store as a whole.
77.2. Features¶
One process per method (
pepsi-keydisc serve <method>), from the systemd templatepepsi-keydisc@.service:@dane,@wkd-advanced,@wkd-direct,@vksand (in a build with theldapcargo feature)@ldap.SOURCESdefaults to the first four, whichpepsi.targetstarts. A hung LDAP bind cannot stall WKD. To turn a method off, runsystemctl mask --now pepsi-keydisc@vksand drop the method fromSOURCES(mask, becausepepsi.targetstarts a merely disabled instance again). An instance whose method is absent from[pepsi-keydiscovery] SOURCESrefuses to start, because the stop rule waits only for the methodsSOURCESnames.The two WKD methods are separate ranks, so they run as separate, concurrent instances rather than as a fallback chain. Running direct only “if advanced fails” would accept the weaker answer whenever the stronger one was merely slow.
DANE is AD-gated.
OPENPGPKEY(RFC 7929) andSMIMEA(RFC 8162) are refused outright without the resolver’s DNSSEC AD bit: an unvalidated DNS answer is not a weaker answer, it is no answer. The AD bit is only trusted, not checked, sopepsi-keydisc@danewarns at start when aresolv.confresolver is not on loopback or does not set the AD bit on a signed probe answer.A hardened fetch for WKD and VKS: HTTPS only, certificate validation with no insecure mode, at most one HTTPS-to-HTTPS redirect to the same host, refusal to connect to loopback/private/link-local addresses, a byte cap enforced while streaming, a deadline on every step, and IDNA A-label conversion. A returned key whose User ID does not name the queried address is discarded (Key-discovery SSRF).
Which certificate authorities vouch for a WKD or key-server answer.
[pepsi-keydiscovery] TLS_CA_BUNDLEreplaces the system root store for these fetches with the CA certificates of one PEM file (also for the key-server traffic of pepsi-keys and pepsi-stage-vks-confirm); an unreadable or empty file stops the instance from starting rather than falling back to the system roots.A lookup that fails in the DNS is not “no key”. A failed
OPENPGPKEY/SMIMEAquery, or a WKD host name that does not resolve, is classified by also asking the domain’sMXandA/AAAArecords: unreachable when nothing answers, transient when only the key records fail, and inconsistent after three such rounds each within an hour of the last. The verdict is stored on the settledkey_requestrow, and pepsi-stage-encrypt holds or reroutes the message instead of sending it in clear (A key lookup that fails in the DNS).Keys whose private half is known are not stored. A discovered key on the known-compromised list (
pepsi.compromised_key: badkeys, the Debian OpenSSL weak keys, and whatpepsi-keys peer screenfactored) or with an RSA modulus that gives its primes away (ROCA, close primes, a small factor) counts as “no key” from that method.Conflicts are decided server-side, and certificates are merged. When the same fingerprint is seen again, the row is updated in place and the certificates are merged, so a revocation that the stored copy carries survives an older copy; a different key replaces the stored one only from a strictly better-ranked source, never a pinned row (Keys of correspondents).
Refresh asks only the method that found the key. The daily
pepsi-keys peer refreshre-checks avkskey at the key server, a WKD key at the same WKD method, adanekey in DNS and anldapkey in the directory, and only while that method is inSOURCES; harvested, gossiped and hand-entered keys are never refreshed over the network, so the key server does not learn the deployment’s whole correspondent list.S/MIME revocation lists. Unless
CRL_FETCH = no, every instance also fetches intopepsi.crl_cachethe CRLs that cached S/MIME peer certificates name in theircRLDistributionPoints(http:///https://, at most two per certificate, no redirects,CRL_MAX_BYTES). UnderCA_ISSUERS_FETCH, it also fetches the CRLs that the fetched intermediate certificates name. It refetches each list at itsnextUpdatebut at least daily, and never replaces a stored list with an older one. pepsi-stage-decrypt checks signer chains against these lists; checking soft-fails to “not checked”, and there is no OCSP. A stored list retires the cached certificates that it revokes when it was signed by an enabled trust anchor of the issuer’s name, or by a fetched intermediate that path-validates to such an anchor. A retired certificate does not count as a key for pepsi-stage-encrypt.probe ADDRESS — run the whole fan-out for one address and print what each method found, storing nothing (not even a negative-cache entry), as a diagnostic.
The narrowest database role in the deployment, provisioned by pepsi-setup:
peer_key,key_request, thekeydisc_*functions andpepsi.crl_cache, and onpepsi.workqueueonlySELECTplus a column-levelUPDATE (status, timeout), which is enough to wake a parked message and nothing more. It is the only writer ofpepsi.crl_cache, so a compromised stage worker cannot delete a current list to withhold a revocation. It has no reach intopepsi.crypto_identity. It runs as its ownpepsi-keydiscaccount with no setuid or setgid bit.
77.3. See also¶
pepsi-keys, pepsi-setup, Key management, RFC Index, Keys of correspondents, A key lookup that fails in the DNS, pepsi-keydisc(1), pepsi-keys(1), pepsi.conf(5).