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@daneDNS
OPENPGPKEY(RFC 7929) andSMIMEA(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)), elseresolv.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 signedietf.orgSOAthat comes back without the AD bit means every lookup finds nothing.pepsi-keydisc@wkd-advancedThe Web Key Directory at
openpgpkey.<domain>, under/.well-known/openpgpkey/<domain>/hu/<hash>.pepsi-keydisc@wkd-directThe Web Key Directory at the domain itself, under
/.well-known/openpgpkey/hu/<hash>.pepsi-keydisc@vksThe
VKS_SERVERSverifying key servers, at/vks/v1/by-email/<address>.pepsi-keydisc@ldapThe configured LDAP directory; only in a build with the
ldapfeature.
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:
a pinned row is never displaced, whatever arrives;
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-signedoverinbound, and that one replacement is reported and audited as a rotation (below), since both are the correspondent’s own claims;newest-wins inside the Autocrypt tier (below);
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,inboundorgossip; andevery 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
inboundreplacesinboundandgossipreplacesgossip, 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; andthe 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 theOPENPGPKEYorSMIMEAquery itself; forwkd-advancedandwkd-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,AandAAAArecords. 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.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 thehttp://andhttps://URIs of itscRLDistributionPointsextension – at most two per certificate – inpepsi.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), throughcrl_cache_register, the one write that role may make here. UnderCA_ISSUERS_FETCHthe points of every intermediate certificate fetched for acaIssuerspointer (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 acRLIssueror 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 ofCRL_MAX_BYTES(default 1 MiB) enforced while streaming. This fetch, however, follows no redirects, and it uses plainhttp://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 whosenextUpdateis present and in the future and whosethisUpdateis 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 itsnextUpdatearrives, but at least daily and at most hourly; a failed fetch is retried afterERROR_TTLand 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 acaIssuerspointer 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 rowrevokedinpepsi.peer_key(check_method = crl,revoked_at,revoked_reasonnaming 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’sON_NO_KEYroute 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 plainhttp://, 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://andhttps://caIssuersURIs of every cached S/MIME peer certificate – at most two per certificate, never anldap://one – inpepsi.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, plainhttp://where the certificate names it), under a fixed byte cap of 64 KiB. The answer may be one DER certificate, acerts-onlyCMS bundle or PEM; its CA certificates are stored, at most four, and anything else is refused and recorded inlast_error. A stored answer is fetched again after a week, a failed one afterERROR_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,vksorldap— the systemd template’s instance name — and must appear in[pepsi-keydiscovery] SOURCES.The instance
LISTENs on thekey_requestchannel, 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 shortERROR_TTLover the longNEGATIVE_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
dnssecfor 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_DOMAINSis 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/DELETEonpepsi.peer_key— the cache filling it is its whole job, and the conflict rule has to be able to replace a row;SELECT/INSERT/UPDATEonpepsi.key_request— the work queue it answers;EXECUTEon thekeydisc_*functions and the twocrypto_*helpers they call;on
pepsi.workqueue,SELECTplus a column-levelUPDATE (status, timeout);SELECT/INSERT/UPDATE/DELETEonpepsi.crl_cache, the revocation lists it fetches. It is the cache’s only writer; thepepsiandpepsi-cryptoroles may only read it, so a compromised stage worker cannot delete a current list to withhold a revocation;SELECT/INSERT/UPDATE/DELETEonpepsi.ca_issuer_cache, the intermediate certificates it fetches, of which it is likewise the only writer;SELECTonpepsi.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,debugortrace(default:[pepsi] LOG, elseinfo).- -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
pendinginpepsi.key_requestand 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] SOURCESdoes not list,ldapin 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.