76. pepsi-keys¶
Manage the end-to-end key store.
76.1. Role¶
pepsi-keys is the operator’s tool for the store of Pepsi’s end-to-end
cryptography keys: pepsi.crypto_identity (the key pairs of the addresses we serve,
private half included and wrapped at rest), pepsi.peer_key (remote
correspondents’ cached public keys and certificates) and pepsi.ca_trust (the
CA certificates against which inbound S/MIME chains are validated). It connects
through the shared [pepsi-postgres] section and reads the [pepsi]
CRYPTO_* options and the [pepsi-crypto] section. It is not a stage.
Reference: pepsi-keys(1); the design is explained in
Key management.
It is one of the standalone binaries, outside the unified pepsi executable,
for two reasons: it is the only program that generates key material (folding it
in would link key generation and certificate issuance into every stage worker),
and a site may install it setuid so that users can manage their own
identities, and a shared multi-call binary cannot carry that bit.
76.2. Features¶
identity list / show — what material exists for an address: protocol, purpose, status, whether it is the primary for its capability, whether it is published, whether the private half is present, purged or was never held (
clientfor the user’s own MUA key, whose private half lives in their mail client), and, inshow, the custody, whether it is the address’s public face and its key-server state.list --servedadds what the Web Key Directory and theOPENPGPKEY/SMIMEArecords actually serve for each listed address, fetched as a correspondent would, and reports a fingerprint that the store does not publish (Checking what is actually served).identity generate — create key material and store it. OpenPGP produces one transferable key (Ed25519 by default, RSA optional); S/MIME produces a signing and an encryption certificate, each self-signed for immediate use, or one certificate with both key usages under
CRYPTO_SMIME_SHARED_KEY.--csradditionally emits a PKCS#10 request over each key, so a real CA can issue a replacement without re-keying.identity import / export / csr — store material generated elsewhere (an OpenPGP public key imported without
--privateis registered as the user’s own MUA key), write material back out in its own binary form (--pemfor X.509), or build a certificate request over an identity’s existing key.identity revoke / retire / forget-private — the lifecycle. Revocation and the periodic
retiresweep destroy private signing material and retain decryption material;revokesigns a revocation certificate first while the private key still exists, which the Web Key Directory then serves and which goes to the key server whenever the key had been uploaded there (--uploadsends it to one that never had it).forget-privateis the explicit, confirmed (-yto skip the prompt) way to destroy a decryption key.rotate-due(pepsi-keys-rotate.timer, daily) replaces every server-held encryption key older than[pepsi-crypto] ENCRYPTION_ROTATION_DAYS. It also destroys retired private halves onceRETIRED_PRIVATE_GRACE_DAYShave passed, unless a queued message is still encrypted to them.identity set-primary / publish / unpublish / delete — choose the material used for new messages, opt an address in or out of publication (
publishcan also upload to a key server), or remove a row outright.peer list / show / import / pin / unpin / refresh / prune / remove — the cached peer keys.
refreshre-validates keys that already exist and never discovers one for an address that has none. Each key is re-checked only through the method that it was learnt from (harvested, gossiped and hand-entered keys are never re-checked over the network), so the key server hears only about the correspondents whose keys it supplied.prunedeletes expired keys and aged-out discovery requests (--dry-runto look first).showapplies the matching rule (an exact address always beats a hand-entered*@domainfallback).importstores a key with sourcemanual, the only source permitted to name a whole domain; for a*@domainkey that names no address, it notes that a signature made with that key is reportedvalidfor everyFrom:at the domain.importalso merges the key into an already stored copy of the same key (so an older export cannot undo a revocation), and it refuses a key whose private half is known.pepsi-keys-refresh.timerrunsrefresh,pruneandscreendaily.peer unclaimed — list the served addresses that have no identity of ours but whose encryption is nevertheless decided by a harvested or gossiped key, that is, a key that a stranger could have planted with a forged
From:. The output is a worklist to confirm with each owner (Finding the users who bring their own key).peer screen — find stored keys whose private half is known: a batch GCD over every cached RSA modulus and our identities’ public halves, plus the known-compromised list (
pepsi.compromised_key: badkeys, the Debian OpenSSL weak keys). A failing peer key is deleted, pinned or not, and a factored modulus is added to that list, so every key check refuses it; a failing identity of ours is reported (audit severityerror), never changed.blocklist update / status / dismiss / restore — the known-compromised-key list in the database.
update(pepsi-keys-blocklist.timer, daily) asks[pepsi-keydiscovery] BADKEYS_URLconditionally whether the badkeys list changed and adds only what is new; nothing is ever removed. A list with fewer records than the last, or one that would grow the table by more than a quarter, is refused unless--force.statussays when the list was last checked;dismisstakes the entries of one run or one source list out of service without letting the next update add them back (see “A known-compromised key is never stored” in Key management).ct-logs update / status — the list of Certificate Transparency logs against which every TLS client checks the SCTs of server certificates (
[pepsi] CT_LOG_LIST, a file, not a table).update(pepsi-keys-ct-logs.timer, daily) fetches[pepsi] CT_LOG_LIST_URLconditionally and replaces the file atomically, refusing a list older than the one in place unless--force;statussays how old the list is.peer capability list / set / unset / forget — the per-correspondent S/MIME capability record (
pepsi.smime_capability) that decides whether a recipient getsAuthEnvelopedData(AES-256-GCM, also when there is no record) or CBCEnvelopedData. Records are learnt from a correspondent’s verified signature by pepsi-stage-autocrypt-learn or configured per address or*@domain; a configured one wins (Which S/MIME container a correspondent gets).ca list / add / scope / accept-nameless / enable / disable / remove — the S/MIME trust anchors (
scopelimits the mail domains an anchor vouches for). A certificate withoutbasicConstraints CA:TRUEis refused, since no chain could ever end at it. Being accepted here is not the same as being usable: an anchor’s ownnameConstraints,pathLenConstraintand policy constraints bind every chain through it (RFC 5937), and a CA carrying a critical extension that Pepsi cannot process is skipped during path building (RFC 5280 §4.2).wrap rotate — re-wrap every stored private key, and every second-factor secret, under a new key-encryption key, incrementally and with
--dry-runto look first; it also re-wraps a key in format0x01, whose wrapping does not bind the key’s fingerprint.otp status / enroll / remove / reset — the per-address TOTP second factor. Once enrolled, an unprivileged caller of a setuid install must pass
identity --otp CODEfor every change to that address’s identities and forexport --privateandcsr; ten consecutive failures lock it until the operator resets it (A second factor for key management). With--console LOGINthe operator enrols, shows or resets the second factor of a console account, whose password sign-ins then need a current code as well.dns — print the
OPENPGPKEY(RFC 7929) andSMIMEA(RFC 8162) records that publish an address, under the hashed owner names those standards define. The records are only worth publishing in a DNSSEC-signed zone, and the output says so.mpki domain / credential / user / order / notices / run — the managed PKI: S/MIME certificates that a commercial CA (DigiCert CertCentral) issues for the users of a domain.
domainholds each domain’s settings,credentialits CA account’s API key (asecrets.dfile),userthe people and the names that their certificates carry (importreads an LDIF or CSV export of a directory),orderandnoticeswhat is under way and what waits for an administrator.run(pepsi-keys-mpki.timer, every five minutes) orders, installs, renews and revokes; the key is always generated here, and the CA receives only a certificate request (Certificates from a commercial CA: the managed PKI).
76.3. Privilege model¶
Reaching a private key takes two independently guarded things: the
pepsi-crypto database role and the key-encryption key. The role is the only
one granted the crypto_identity.private_wrapped column; every other service
role holds a column-level grant that omits it. The key-encryption key lives only
in secrets.d/pepsi-crypto.secret. A stolen database yields ciphertext; the
secret alone yields nothing.
pepsi-keys assumes that role only for the duration of each database call:
started as root, it becomes the account (root has no database role of
its own) and returns afterwards. PostgreSQL peer authentication keys off the
effective uid, not the gid, so a setgid bit would grant the group that guards
the secret fragment but not the database identity.
The binary ships without a setuid bit, unlike pepsi-whitelist: a
program that can open every private key in a deployment is a much larger prize
than a single whitelist table. A site that wants users to manage their own
identities installs it setuid pepsi-crypto; identities are owned by the
passwd login that their address resolves to, and an unprivileged caller of the setuid
binary may see and change only their own. Without the bit every caller connects
as themselves and the database grants alone decide, so making it setuid is a
site decision rather than a code change. A setuid install drops to the
invoking user before anything else, removes the environment variables that
steer configuration discovery and libpq, and refuses -c to unprivileged
callers, since the configuration names the key-encryption key. Peer keys and
trust anchors are deployment-wide and operator-only, listing included.
Every key operation, and every read of private material (identity export
--private, identity csr), is recorded in the shared audit log
(pepsi.event_log), the same one that the administrative API writes.
76.4. See also¶
Key management, The private-key custody boundary, A second factor for key management, Gateway custody (custody = local, the MTA key), Keys of correspondents, pepsi-keydisc, pepsi-setup, pepsi-whitelist, pepsi-settings, Architecture, pepsi-keys(1), pepsi.conf(5).