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 (client for the user’s own MUA key, whose private half lives in their mail client), and, in show, the custody, whether it is the address’s public face and its key-server state. list --served adds what the Web Key Directory and the OPENPGPKEY/SMIMEA records 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. --csr additionally 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 --private is registered as the user’s own MUA key), write material back out in its own binary form (--pem for X.509), or build a certificate request over an identity’s existing key.

  • identity revoke / retire / forget-private — the lifecycle. Revocation and the periodic retire sweep destroy private signing material and retain decryption material; revoke signs 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 (--upload sends it to one that never had it). forget-private is the explicit, confirmed (-y to 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 once RETIRED_PRIVATE_GRACE_DAYS have 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 (publish can also upload to a key server), or remove a row outright.

  • peer list / show / import / pin / unpin / refresh / prune / remove — the cached peer keys. refresh re-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. prune deletes expired keys and aged-out discovery requests (--dry-run to look first). show applies the matching rule (an exact address always beats a hand-entered *@domain fallback). import stores a key with source manual, the only source permitted to name a whole domain; for a *@domain key that names no address, it notes that a signature made with that key is reported valid for every From: at the domain. import also 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.timer runs refresh, prune and screen daily.

  • 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 severity error), 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_URL conditionally 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. status says when the list was last checked; dismiss takes 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_URL conditionally and replaces the file atomically, refusing a list older than the one in place unless --force; status says 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 gets AuthEnvelopedData (AES-256-GCM, also when there is no record) or CBC EnvelopedData. 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 (scope limits the mail domains an anchor vouches for). A certificate without basicConstraints CA:TRUE is refused, since no chain could ever end at it. Being accepted here is not the same as being usable: an anchor’s own nameConstraints, pathLenConstraint and 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-run to look first; it also re-wraps a key in format 0x01, 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 CODE for every change to that address’s identities and for export --private and csr; ten consecutive failures lock it until the operator resets it (A second factor for key management). With --console LOGIN the 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) and SMIMEA (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. domain holds each domain’s settings, credential its CA account’s API key (a secrets.d file), user the people and the names that their certificates carry (import reads an LDIF or CSV export of a directory), order and notices what 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).