95.1.51. pepsi-keydisc

find a correspondent’s public key or certificate

Manual section:

1

95.1.51.1.1. Name

pepsi-keydisc - asynchronous key discovery, one service per method.

95.1.51.1.2. Synopsis

pepsi-keydisc [GLOBAL-OPTIONS] serve METHOD

pepsi-keydisc [GLOBAL-OPTIONS] probe ADDRESS

95.1.51.1.3. Description

pepsi-keydisc finds a correspondent’s OpenPGP key or S/MIME certificate, records where it came from and how much that source is worth, and caches it in pepsi.peer_key (see pepsi-keys(1)). Finding a key is easy; the hard part is knowing whether to believe it. So every result carries its source and whether the lookup that produced it was DNSSEC-validated, and the policy of the stage that uses the key decides what is good enough.

Discovery is asynchronous and lives outside the stages. A stage that needs a key that is not in its cache never performs network I/O of its own: it commits whatever work it may keep, pauses the message and enqueues a request in pepsi.key_request; a pepsi-keydisc instance answers the request and, in the same round-trip that stores the key, releases every message parked on that address:

stage                cache hit         -> use the key
                     fresh negative    -> the no-key path, at once
                     cache miss        -> park: commit, pause, enqueue

pepsi-keydisc@...    LISTEN key_request -> look up -> store the key AND
                                           release every parked message

What the park commits is the stage’s decision, not this program’s. In particular, pepsi-stage-decrypt(1) parks an S/MIME message with the decrypted plaintext committed, because the nested signature survives as an ordinary MIME layer. It parks an OpenPGP message unchanged: an OpenPGP signature lives only inside the packet stream, and committing the plaintext would destroy the evidence that the key is being fetched to check.

So a slow key server never holds up a stage worker; the problem is removed, not merely bounded. The request is keyed on the address, so a hundred messages to one correspondent cost one lookup and are released together. A request that settles without a key releases its waiters exactly like one that found a key: the services find keys, the stages decide about mail.

It is not a stage. It connects to the shared database through the [pepsi-postgres] section and is configured entirely by [pepsi-keydiscovery] (see pepsi.conf(5)).

95.1.51.1.4. One instance per method

There is one binary and one configuration section, but one process per discovery method, started from the systemd template unit pepsi-keydisc@.service:

pepsi-keydisc@dane

DNS OPENPGPKEY (RFC 7929) and SMIMEA (RFC 8162), under a hashed local part. Both are refused without the resolver’s DNSSEC AD bit. The resolvers are [pepsi] DNS_SERVERS (see pepsi.conf(5)), else resolv.conf’s, and since Pepsi trusts their AD bit rather than validating DNSSEC itself, the instance logs a warning at start when one of them is neither on this host nor reached over DNS over TLS or HTTPS (anyone on the path to it could forge a validated answer), and when they do not validate: a probe for the signed ietf.org SOA that comes back without the AD bit means every lookup finds nothing.

pepsi-keydisc@wkd-advanced

The Web Key Directory at openpgpkey.<domain>, under /.well-known/openpgpkey/<domain>/hu/<hash>.

pepsi-keydisc@wkd-direct

The Web Key Directory at the domain itself, under /.well-known/openpgpkey/hu/<hash>.

pepsi-keydisc@vks

The VKS_SERVERS verifying key servers, at /vks/v1/by-email/<address>.

pepsi-keydisc@ldap

The configured LDAP directory; only in a build with the ldap feature.

pepsi.target starts the first four, which are the default SOURCES.

The split isolates the methods from each other: a hung LDAP bind cannot stall WKD, and to turn a method off you run systemctl mask --now pepsi-keydisc@vks (and drop it from SOURCES) rather than restart something shared. The two Web Key Directory methods have separate ranks, so they run as separate instances at the same time. They do not form a fallback chain: trying the direct method only “if advanced fails” would silently accept the weaker answer whenever the stronger one was merely slow.

This is a deliberate deviation from draft-koch-openpgp-webkey-service §3.1, which requires the advanced method to be tried first and the direct one to be used only where the openpgpkey sub-domain does not exist at all. The draft’s ordering is about trust rather than speed: the apex /.well-known/openpgpkey/ is served by whatever runs the domain’s website, often a different party from its mail operator. So a domain that publishes correctly under openpgpkey.<domain> still has its apex consulted here, and an answer from the apex is stored at the wkd-direct rank, above LDAP, VKS and anything harvested from mail. Where that matters, SOURCES can list wkd-advanced without wkd-direct.

An instance whose method does not appear in [pepsi-keydiscovery] SOURCES refuses to start, with a message naming what SOURCES does list. That is not pedantry: the rank-grace stop rule waits only for the methods SOURCES names, so an unlisted instance would be answering a request nobody is waiting for.

Harvesting keys from inbound mail (application/pgp-keys parts, S/MIME signer certificates, the Autocrypt: header) is not a discovery service and has no instance. It runs inline where the message already is, in pepsi-stage-autocrypt-learn(1), costs no network I/O, and writes through the same path, so a harvested key also releases anything parked on that address. inbound is consequently rejected in SOURCES, and so is inbound-signed, the rung to which the same stage lifts a key when an aligned DKIM signature that passed at ingress covered it.

The same goes for gossip, the keys that the same stage reads out of the Autocrypt-Gossip: fields inside a message that arrived encrypted (Autocrypt Level 1 §5.3). It is a second inline rung rather than a variant of inbound, because those keys are third parties’ rather than the sender’s own, and the ladder has to be able to tell them apart.

Note where “inline” is: pepsi-stage-decrypt(1) extracts the certificates that a message carries in order to check its signature, and then drops them; it stores nothing. A pipeline with no pepsi-stage-autocrypt-learn stage never learns a key from mail at all, however much material arrives, and no amount of [stage-decrypt] configuration changes that.

95.1.51.1.5. Which key wins a conflict

A key whose fingerprint is already stored for the same address and protocol is not a conflict at all: the row is updated in place (its source, validity, expiry and Autocrypt effective date are carried forward, the source only ever improving) and the answer is refreshed. That happens before every test below, so re-seeing a pinned key still refreshes what is known about it. The stored and the incoming OpenPGP certificates are merged, not swapped, so a revocation or a newer self-signature that the stored copy carries survives when an older copy arrives later; the merge drops signatures that do not verify and components that nothing binds. The merge happens whatever the incoming source’s rank: a revocation or a newer self-signature that only a weaker copy carries (a correspondent’s own mail repeating a key first found by WKD or imported by hand) is written into the stored row, which is then marked revoked if the merged certificate is, while its source, rank and pinning stay as they were. That is safe because the merge keeps only signatures made by the key itself (or a revoker it designates); a weaker source still cannot replace a different key.

When a discovered key differs from everything stored for that address and protocol, the store decides in one server-side step, in this order:

  1. a pinned row is never displaced, whatever arrives;

  2. a strictly better-ranked source replaces everything stored — so WKD displaces a harvested key, an operator entry displaces WKD, and a gossiped key displaces nothing at all; inside the Autocrypt tier the better rung is inbound-signed over inbound, and that one replacement is reported and audited as a rotation (below), since both are the correspondent’s own claims;

  3. newest-wins inside the Autocrypt tier (below);

  4. otherwise the stored key is kept and the new one is not stored, and the answer is reported as rejected.

95.1.51.1.5.1. Newest-wins in the Autocrypt tier

Autocrypt Level 1’s peer-state update is youngest-wins: a client stores the key from the youngest message it has seen carrying an Autocrypt: header. Rule 2 alone cannot express that — it would refuse the second Autocrypt key ever seen for an address and keep the first for ever, so a correspondent who reinstalls their client, changes device or rotates their key would go on receiving mail encrypted to a key they no longer hold. Unreadable mail of this kind is exactly the failure that Autocrypt exists to avoid.

So rule 3 lets a newer key win, and it is confined so that it can only ever decide between claims of the same kind. It applies when all of:

  • the incoming source is inbound-signed, inbound or gossip; and

  • every key currently stored for that address and protocol is on one of those rungs too — nothing an owner or an operator published is ever at stake; and

  • the incoming source ranks at least as high as the stored one, so inbound replaces inbound and gossip replaces gossip, but a third party’s introduction can never take the row off what the address’s owner said about themselves, and a key from an unsigned message can never take it off a key that a DKIM-signed message brought (inbound-signed), however new the unsigned message claims to be; and

  • the incoming message’s effective date is strictly newer than the stored one.

The effective date is the message’s Date: header, clamped so that it can never be in the future, and the time of receipt when the header is absent or unparseable — Level 1’s own definition. Equal dates are therefore first-wins (a redelivered message cannot flip the row), and a key that carries no effective date at all — every network method — never displaces anything.

The rule has a price, because an attacker can use it. Harvesting is keyed on the From: header, which the sender writes, and inbound authentication is fail-open, so a forged From: can displace a key that was itself only ever trust-on-first-use. That is Autocrypt’s own trade-off: it defends against passive collection, not against an active attacker on the path. The rule is bounded on all four sides above: nothing published by the domain (WKD, DANE), by a key server, by a directory or by the operator can be touched, and neither can a pinned row. An operator who does not want the rule sets [pepsi-keydiscovery] MIN_TRUST above the tier, or pins the keys that matter with pepsi-keys peer pin (see pepsi-keys(1)). Note that an address for which this deployment holds an identity is answered from that identity and never from the peer cache at all.

A rule-3 replacement is reported as rotated rather than replaced and writes a key.peer.rotate row to the audit log in the same statement, so a rotation cannot happen without its record. Only inbound learning (pepsi-stage-autocrypt-learn(1)) can trigger one. That stage also mails the local recipients of the message, and it can restrict the rule with ACCEPT_ROTATION = expired (every stored key must be recorded revoked or expired), under which a refused rotation is reported as held and audited as key.peer.rotate.held. The network methods never reach rule 3.

An inbound-signed key arriving over a stored inbound one is rule 2 by rank, but it is reported and audited as a rotation all the same, and ACCEPT_ROTATION = expired holds it like any other. When the sending domain vouches for a different key from the one that its user’s unsigned mail carried, that is exactly the change the recipients should hear about. The owner’s own key arriving over a gossiped one stays an ordinary rule-2 replacement.

The same fingerprint re-seen is a refresh, not a conflict, and the row takes over the better of the two sources — so a key first seen unsigned moves to inbound-signed the first time a signed message carries it, and never back. One such refresh is reported separately: a key stored from gossip that its owner’s own message (source inbound or inbound-signed) now carries is reported as promoted and audited as key.peer.promote, never as a rotation — Autocrypt Level 1 §5.3’s promotion out of gossip.

95.1.51.1.6. Keys whose private half is known

A discovered key is not stored if it is on the known-compromised list, or if its RSA modulus gives its primes away (ROCA, close primes, a small factor). The list is pepsi.compromised_key: the badkeys blocklist with the Debian OpenSSL weak keys, which pepsi-keys blocklist update keeps current, and the moduli that this deployment’s own pepsi-keys peer screen factored (see pepsi-keys(1)). For such a key, the method reports that it found nothing, with a warning naming the address, and the request settles on the other methods’ answers. Harvesting in pepsi-stage-autocrypt-learn(1) applies the same test. This role may read the list and nothing more; only pepsi-crypto writes it.

95.1.51.1.7. A lookup that fails in the DNS

A request that settles without a key would read as “no key” whatever the reason, and opportunistic encryption would then send in clear. An attacker who can make the recipient’s key records fail (a forged SERVFAIL, dropped responses, a DNSSEC-bogus answer) would thus get a downgrade. Each instance therefore classifies a failed lookup before reporting it:

  • For dane, a failure of the OPENPGPKEY or SMIMEA query itself; for wkd-advanced and wkd-direct, a failure to resolve the WKD host name (openpgpkey.domain, or the domain), which the instance re-asks because the HTTPS client’s error does not say which layer failed.

  • The instance then asks the domain’s MX, A and AAAA records. If none answers with a record the failure is unreachable; if any does, the key records are failing while the domain answers (key-records).

The strongest report of a round is kept on the request (dns_report). When the request settles without a key, that report becomes a verdict (key_request.dns_failure): unreachable; transient for key records failing while the domain answers; and inconsistent once that has happened in three consecutive rounds, each within an hour of the previous one — so one lost packet, or a server that drops an unusual record type once, is a retry and not a verdict. A request settling on a DNS failure stays fresh for only 15 minutes rather than ERROR_TTL, because the messages waiting on it are held, not sent (see pepsi-stage-encrypt(1), “Recipient DNS failures”); a round that finds a key, or fails for any other reason, clears the count.

What is deliberately not classified, and so stays “no key”: a WKD failure whose host name resolves (an HTTPS, TLS or 5xx error — common and harmless), a key server or LDAP failure, and an NXDOMAIN or empty answer. Without DNSSEC a forged NXDOMAIN or empty answer is indistinguishable from a real one, and still reads as “no key”.

95.1.51.1.8. Refreshing cached keys

A stored key is used for CACHE_TTL and then re-checked by the daily pepsi-keys-refresh.timer (pepsi-keys peer refresh, see pepsi-keys(1)). The refresh asks again only the method that found the key, and only if that method is still in SOURCES: a vks key is re-fetched from the key servers, a wkd key from the advanced Web Key Directory and a wkd-direct key from the direct one, a dane key from DNS and an ldap key from the directory. Keys that no network method produced are never refreshed over the network: the inbound-signed, inbound and gossip keys harvested from mail, and the manual and api keys that an operator entered. A harvested key is updated by its owner’s next message. Pinned keys and *@domain rows are not refreshed either. A harvested key is, however, a reason to look: pepsi-stage-encrypt(1) raises an ordinary discovery request, at most once per NEGATIVE_TTL, whenever it encrypts to a key on one of those three rungs, so that a key the owner published can take over.

That is a privacy choice. Running the whole fan-out for every due key would tell the key server the deployment’s entire set of correspondents, once a day, whatever method had actually found their keys; restricted to the original method, the key server hears only about the correspondents whose keys it supplied, and the correspondents’ own domains only about their own addresses. The cost is freshness: a revocation published only on a key server is not seen for a key that came from WKD, DANE or a message. pepsi-keys peer refresh --address still runs the whole fan-out for one address when an operator asks for it.

95.1.51.1.9. Which certificate authorities are trusted

The WKD and VKS fetches use HTTPS with certificate verification always on, by default against the system root store. [pepsi-keydiscovery] TLS_CA_BUNDLE names a PEM file of CA certificates that replaces that store for these fetches. It does the same for the key-server traffic of pepsi-keys(1) and pepsi-stage-vks-confirm(1), but not for the https:// revocation-list fetches below, which keep the system roots because a CRL is authenticated by its issuer’s signature. A deployment that knows which CAs its correspondents’ WKD hosts and its key servers use can thus stop trusting every other one. Any CA in the store can issue a certificate for a correspondent’s WKD host, and a WKD answer ranks above everything but DANE, so this shrinks the set of parties that can plant a key. The price is that a correspondent whose WKD host uses a CA not in the file gets no WKD key at all. The file is loaded at start: an unreadable file, or one holding no PEM certificate, makes the instance refuse to start rather than fall back to the system roots. LDAP (ldaps://) and DANE are not affected. The SCTs of the server certificate are checked for Certificate Transparency against the system roots and under TLS_CA_BUNDLE alike, softly: a certificate that was not logged is reported with a warning and the fetch goes ahead ([pepsi] CT_CHECK, see pepsi.conf(5)).

95.1.51.1.10. Revocation lists

The stages that verify S/MIME signatures are network-free, so the revocation data they check against has to be fetched ahead of time, and this is the one process that fetches anything for keys. Unless [pepsi-keydiscovery] CRL_FETCH = no, every instance runs a second loop beside its discovery loop:

  • Harvest. Hourly, it reads every cached S/MIME peer certificate in pepsi.peer_key (revoked ones excepted) and registers the http:// and https:// URIs of its cRLDistributionPoints extension – at most two per certificate – in pepsi.crl_cache. A certificate that a discovery method has just stored is registered at once, and so are the points of every chain of TLS client certificates that pepsi-ingress(1) validates (TLS_AUTH_CLIENT_CA), through crl_cache_register, the one write that role may make here. Under CA_ISSUERS_FETCH the points of every intermediate certificate fetched for a caIssuers pointer (below) are registered too, so a chain through such an intermediate can be covered whole; that tells the CA nothing that the fetch of its certificate did not. A distribution point that names a cRLIssuer or only some revocation reasons is skipped, as are LDAP URIs. A point that no cached certificate has named for 30 days is forgotten.

  • Fetch. Every five minutes, it claims the points that are due (each is fetched by one instance only) and fetches each with the same hardened client that the WKD and VKS lookups use: the SSRF address check, the whole-response deadline METHOD_TIMEOUT, and a byte cap of CRL_MAX_BYTES (default 1 MiB) enforced while streaming. This fetch, however, follows no redirects, and it uses plain http:// when that is what the certificate names: a CRL is signed by its issuer, and RFC 5280 has distribution points serve it over HTTP. A response is stored only if it is one DER-encoded CRL whose nextUpdate is present and in the future and whose thisUpdate is at most an hour in the future (clock skew), and only if it is not older than the list already stored (a replayed old list would “un-revoke” a certificate). The point is fetched again when its nextUpdate arrives, but at least daily and at most hourly; a failed fetch is retried after ERROR_TTL and leaves the stored list in place.

  • Retire. After each store, the instance checks whether the list can be believed here. That is the case when the list is current and one of two certificates signed it: an enabled trust anchor (pepsi-keys(1) ca) of the issuer’s name that is permitted to sign CRLs, or an intermediate CA certificate of that name that was fetched for a caIssuers pointer and path-validates up to an enabled anchor (every signature on the path verified, inside its validity, a CA permitted to sign CRLs, every path constraint honoured, through other fetched intermediates if need be). If the list can be believed, every cached certificate that names this point, has that issuer and lies in the list’s scope is looked up on it. A listed serial marks the row revoked in pepsi.peer_key (check_method = crl, revoked_at, revoked_reason naming the point, the entry’s reason code and its date), and the journal says which certificate of which address was retired. The row is not deleted: pepsi-keys peer list and peer show keep showing it with the reason, its fingerprint stays known as revoked so a directory still serving the old certificate cannot bring it back, and a re-issued certificate found later replaces it (from the same source too, which a live row would refuse at equal rank; a weaker source still cannot). From that moment the row is no key for anybody: every lookup skips it, so pepsi-stage-encrypt(1) takes the recipient’s ON_NO_KEY route and records “revoked” as the reason, with no revocation code of its own. A list that neither of them signed is stored for the verifier below, but nothing acts on it: a distribution point is usually plain http://, and retiring keys on the say-so of an unverified list would let whoever is on that path send a correspondent’s mail in the clear. The anchor set is the operator’s: an intermediate CA that publishes its own list retires something only when its certificate was fetched (CA_ISSUERS_FETCH) and chains to an enabled anchor, or when it is itself added with pepsi-keys ca add. A certificate stored after a list was fetched is checked at the next refetch, within a day.

Storing verifies nothing. When a list is used, the issuer certificate that its signature is checked against arrives with the message being verified. pepsi-stage-decrypt(1) reads the current lists from the cache (behind its TRUST_ANCHOR_TTL), and the verifier uses a list for a certificate only if the issuer’s key signed it, it is current, and its scope covers the certificate (a partitioned list for another distribution point, a delta, an indirect or a reason-limited list does not; nor does one with a critical extension the verifier does not process). A listed serial makes the signature bad with reason revoked.

Revocation checking soft-fails for mail: a point that cannot be reached, a list that is stale, unverifiable or out of scope, or a cache that cannot be read leaves the verdict at “not checked” and every cached key in use, exactly as when nothing was fetched. The one hard consumer is pepsi-ingress(1): a TLS client certificate whose path names a distribution point is not accepted until a current list from this cache covers it. There is no OCSP query: a CRL fetch tells the CA, at most daily, that this host holds some certificate it issued; an OCSP query would tell it which one, at the moment a message signed with it arrives. (A response a TLS server staples costs no query and is evaluated on that session, pepsi-stage-relay-to-internet(1).)

95.1.51.1.11. Intermediate certificates

Many signers send their S/MIME certificate without the intermediate CA certificates between it and the root, and a path the verifier cannot build leaves the signature untrusted even when the root is a configured anchor. The certificate itself says where its issuer’s certificate is published (the caIssuers entry of its authorityInfoAccess extension, RFC 5280 §4.2.2.1). With [pepsi-keydiscovery] CA_ISSUERS_FETCH = yes (default no), every instance runs a third loop on the CRL loop’s schedule:

  • Harvest. Hourly, it registers the http:// and https:// caIssuers URIs of every cached S/MIME peer certificate – at most two per certificate, never an ldap:// one – in pepsi.ca_issuer_cache, and those of every certificate already fetched, one level further up, at most three levels above a peer certificate. A URL that no certificate has named for 30 days is forgotten.

  • Fetch. Every five minutes, it claims the URLs that are due and fetches each with the hardened client and the rules of the CRL fetch (the SSRF address check, the whole-response deadline METHOD_TIMEOUT, no redirects, plain http:// where the certificate names it), under a fixed byte cap of 64 KiB. The answer may be one DER certificate, a certs-only CMS bundle or PEM; its CA certificates are stored, at most four, and anything else is refused and recorded in last_error. A stored answer is fetched again after a week, a failed one after ERROR_TTL.

pepsi-stage-decrypt(1) reads the stored certificates (behind its TRUST_ANCHOR_TTL) and hands them to the verifier as intermediates a path may pass through. They are never anchors and never name a signer: a path through one counts only if every signature on it verifies up to an enabled pepsi-keys(1) ca anchor, so a forged answer can fail to help but cannot make a signature valid. The option is off by default because each fetch tells a CA that this host corresponds with one of its subscribers; with it off, a signer who sends no intermediates reads untrusted.

95.1.51.1.12. Commands

serve METHOD

Run one method’s service instance until interrupted. METHOD is one of dane, wkd-advanced, wkd-direct, vks or ldap — the systemd template’s instance name — and must appear in [pepsi-keydiscovery] SOURCES.

The instance LISTENs on the key_request channel, whose payload is the request id, answers each request this method still owes, and sweeps once on start-up and on every listener reconnect so nothing raised while it was away is lost. Between notifications it ticks a short settle sweep: a rank-grace window is a point in time, so something has to look at the clock, and a deployment running any instance at all therefore has the sweep. A single failing lookup is recorded on the request (which is what selects the short ERROR_TTL over the long NEGATIVE_TTL) and never tears the listener down.

probe ADDRESS

Run the whole fan-out for one address once and print what each method found — the protocol, the fingerprint, the size, and dnssec for an AD-validated DANE answer — or the error it hit, or that it found nothing.

Deliberately read-only: it stores nothing, neither the key nor a negative-cache entry. An operator diagnosing “why does this correspondent have no key” wants to see each method’s answer, not to have a diagnostic write a negative entry that then suppresses the real lookup for a day. To look an address up and store the result, use pepsi-keys peer refresh --address (see pepsi-keys(1)).

An address excluded by ALLOW_DOMAINS/DENY_DOMAINS is reported as such and not queried.

95.1.51.1.13. Privileges

The services run as their own unprivileged account, pepsi-keydisc — not the pepsi service user and not pepsi-crypto. This daemon parses key material fetched from the open internet (a hostile WKD body, a key-server answer, a DNS record), which makes it the likeliest process here to be broken into, so pepsi-setup(1) gives it the narrowest database role in the deployment:

  • SELECT/INSERT/UPDATE/DELETE on pepsi.peer_key — the cache filling it is its whole job, and the conflict rule has to be able to replace a row;

  • SELECT/INSERT/UPDATE on pepsi.key_request — the work queue it answers;

  • EXECUTE on the keydisc_* functions and the two crypto_* helpers they call;

  • on pepsi.workqueue, SELECT plus a column-level UPDATE (status, timeout);

  • SELECT/INSERT/UPDATE/DELETE on pepsi.crl_cache, the revocation lists it fetches. It is the cache’s only writer; the pepsi and pepsi-crypto roles may only read it, so a compromised stage worker cannot delete a current list to withhold a revocation;

  • SELECT/INSERT/UPDATE/DELETE on pepsi.ca_issuer_cache, the intermediate certificates it fetches, of which it is likewise the only writer;

  • SELECT on pepsi.ca_trust, the enabled anchors a fetched list’s signature is checked against before the certificates it lists are retired.

Nothing else.

Those two columns are exactly enough to move a parked row from paused back to pending, which happens inside keydisc_resolve/keydisc_sweep. With a table-level grant this account could rewrite a message’s recipients or its body; with these two columns it can only wake a message up. It has no reach into pepsi.crypto_identity at all, and therefore none into any private key.

The program carries no setuid or setgid bit and is folded into the multi-call pepsi binary. Started as root it becomes the pepsi-keydisc account before connecting (the configuration, and any @inline-secret@ fragment, is read first, as the invoking user), so it can be launched from a root shell for testing without sudo -u.

95.1.51.1.14. LDAP is a compile-time feature

The LDAP client is behind the ldap cargo feature and is off by default: it adds a dependency, and a deployment with no directory should not link one. A build without the feature refuses to start pepsi-keydisc@ldap with a message saying so, rather than silently answering “no key” for ever, and pepsi-setup(1) rejects a configuration that lists ldap in SOURCES on such a build — as it does one that lists ldap without LDAP_URL and LDAP_BASE.

95.1.51.1.15. Global Options

These global options precede the subcommand (a trailing flag is rejected).

-c FILE, –config FILE

Read the configuration from FILE instead of searching the default locations.

-L LOGLEVEL, –log LOGLEVEL

Set the logging verbosity. LOGLEVEL is one of error, warn, info, debug or trace (default: [pepsi] LOG, else info).

-v, –verbose

Show log messages from all sources, including third-party libraries.

-h, –help

Print a usage summary and exit.

-V, –version

Print the version and exit.

95.1.51.1.16. Signals

SIGINT, SIGTERM

Stop taking new requests and exit. Nothing is lost: an unanswered request stays pending in pepsi.key_request and is picked up by the next instance’s start-up sweep, or settles on its own deadline.

95.1.51.1.17. Exit Status

0

Clean shutdown, or a completed probe.

1

An error occurred: a malformed configuration, a method that [pepsi-keydiscovery] SOURCES does not list, ldap in a build without the feature, or a failed database connection. Individual lookup failures are not errors — they are recorded on the request and the service keeps running.

78

The database schema is not the one this build expects (not installed, older, newer or modified): run pepsi-setup(1) schema.

95.1.51.1.18. Examples

pepsi.target starts the default set of methods (dane wkd-advanced wkd-direct vks). Without the target, start them by hand:

systemctl enable --now pepsi-keydisc@dane pepsi-keydisc@wkd-advanced \
                       pepsi-keydisc@wkd-direct pepsi-keydisc@vks

Turn one method off without touching the configuration of the others:

systemctl mask --now pepsi-keydisc@vks

(then set [pepsi-keydiscovery] SOURCES = dane wkd-advanced wkd-direct, so the stop rule stops waiting for an answer that will never come). mask rather than disable: pepsi.target starts a merely disabled instance again.

Find out what each method says about one address, changing nothing:

pepsi-keydisc -c /etc/pepsi/pepsi.conf probe bob@example.com

Run one instance in the foreground, with full logging, to see why an address yields no key:

pepsi-keydisc -c /etc/pepsi/pepsi.conf -L debug serve wkd-advanced

95.1.51.1.19. See Also

pepsi-keys(1), pepsi-setup(1), pepsi.conf(5), pepsi.state(7), pepsi-dispatch(1), pepsi-config(1)

The manual’s Security chapter states the mechanisms this program implements (A correspondent’s key changing, A key lookup that fails in the DNS, Key-discovery SSRF, Key-discovery certificate authorities); its Threat model chapter states what they promise (Keys of correspondents).

95.1.51.1.20. Bugs

Report bugs to the Pepsi issue tracker.