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 template pepsi-keydisc@.service: @dane, @wkd-advanced, @wkd-direct, @vks and (in a build with the ldap cargo feature) @ldap. SOURCES defaults to the first four, which pepsi.target starts. A hung LDAP bind cannot stall WKD. To turn a method off, run systemctl mask --now pepsi-keydisc@vks and drop the method from SOURCES (mask, because pepsi.target starts a merely disabled instance again). An instance whose method is absent from [pepsi-keydiscovery] SOURCES refuses to start, because the stop rule waits only for the methods SOURCES names.

  • 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) and SMIMEA (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, so pepsi-keydisc@dane warns at start when a resolv.conf resolver 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_BUNDLE replaces 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/SMIMEA query, or a WKD host name that does not resolve, is classified by also asking the domain’s MX and A/AAAA records: 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 settled key_request row, 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 what pepsi-keys peer screen factored) 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 refresh re-checks a vks key at the key server, a WKD key at the same WKD method, a dane key in DNS and an ldap key in the directory, and only while that method is in SOURCES; 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 into pepsi.crl_cache the CRLs that cached S/MIME peer certificates name in their cRLDistributionPoints (http:///https://, at most two per certificate, no redirects, CRL_MAX_BYTES). Under CA_ISSUERS_FETCH, it also fetches the CRLs that the fetched intermediate certificates name. It refetches each list at its nextUpdate but 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, the keydisc_* functions and pepsi.crl_cache, and on pepsi.workqueue only SELECT plus a column-level UPDATE (status, timeout), which is enough to wake a parked message and nothing more. It is the only writer of pepsi.crl_cache, so a compromised stage worker cannot delete a current list to withhold a revocation. It has no reach into pepsi.crypto_identity. It runs as its own pepsi-keydisc account 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).