95.1.50. pepsi-keys

manage the end-to-end key store: identities, peer keys and anchors

Manual section:

1

95.1.50.1.1. Name

pepsi-keys - generate, import, publish and retire end-to-end key material.

95.1.50.1.2. Synopsis

pepsi-keys [GLOBAL-OPTIONS] identity list [–address ADDRESS] [–json] [–served]

pepsi-keys [GLOBAL-OPTIONS] identity show IDENTITY-ID [–json]

pepsi-keys [GLOBAL-OPTIONS] identity generate ADDRESS –protocol PROTOCOL [–name NAME] [–days N] [–no-publish] [–csr] [–shared | –split]

pepsi-keys [GLOBAL-OPTIONS] identity import ADDRESS –protocol PROTOCOL –purpose PURPOSE –public FILE [–private FILE] [–algorithm NAME] [–primary] [–no-publish]

pepsi-keys [GLOBAL-OPTIONS] identity export IDENTITY-ID [–private] [–pem]

pepsi-keys [GLOBAL-OPTIONS] identity csr IDENTITY-ID

pepsi-keys [GLOBAL-OPTIONS] identity revoke IDENTITY-ID [–reason TEXT] [–upload]

pepsi-keys [GLOBAL-OPTIONS] identity forget-private IDENTITY-ID [-y]

pepsi-keys [GLOBAL-OPTIONS] identity set-primary IDENTITY-ID

pepsi-keys [GLOBAL-OPTIONS] identity publish [IDENTITY-ID] [–wkd] [–vks] [–retry [–dry-run]] [-y]

pepsi-keys [GLOBAL-OPTIONS] identity unpublish IDENTITY-ID

pepsi-keys [GLOBAL-OPTIONS] identity delete IDENTITY-ID [-y]

pepsi-keys [GLOBAL-OPTIONS] identity retire

pepsi-keys [GLOBAL-OPTIONS] identity rotate-due [–dry-run]

pepsi-keys [GLOBAL-OPTIONS] peer list [–address ADDRESS] [–json]

pepsi-keys [GLOBAL-OPTIONS] peer show ADDRESS [–protocol PROTOCOL] [–json]

pepsi-keys [GLOBAL-OPTIONS] peer unclaimed [–address ADDRESS] [–all-sources] [–json]

pepsi-keys [GLOBAL-OPTIONS] peer import ADDRESS –protocol PROTOCOL –file FILE [–pin]

pepsi-keys [GLOBAL-OPTIONS] peer pin | unpin | remove PEER-KEY-ID

pepsi-keys [GLOBAL-OPTIONS] peer refresh [–address ADDRESS | –expire PEER-KEY-ID] [–expiring-within-days DAYS] [–limit N]

pepsi-keys [GLOBAL-OPTIONS] peer prune [–retain-days DAYS] [–dry-run]

pepsi-keys [GLOBAL-OPTIONS] peer screen [–dry-run]

pepsi-keys [GLOBAL-OPTIONS] peer capability list [–address ADDRESS] [–json]

pepsi-keys [GLOBAL-OPTIONS] peer capability set ADDRESS aead | cbc

pepsi-keys [GLOBAL-OPTIONS] peer capability unset ADDRESS

pepsi-keys [GLOBAL-OPTIONS] peer capability forget FINGERPRINT

pepsi-keys [GLOBAL-OPTIONS] blocklist update [–force]

pepsi-keys [GLOBAL-OPTIONS] blocklist status [–json]

pepsi-keys [GLOBAL-OPTIONS] blocklist dismiss | restore –import N | –list NAME

pepsi-keys [GLOBAL-OPTIONS] ct-logs update [–force]

pepsi-keys [GLOBAL-OPTIONS] ct-logs status [–json]

pepsi-keys [GLOBAL-OPTIONS] ca list [–json]

pepsi-keys [GLOBAL-OPTIONS] ca add FILE [–label TEXT] [–accept-nameless] [–domain DOMAIN]…

pepsi-keys [GLOBAL-OPTIONS] ca scope CA-ID –domain DOMAIN… | –any

pepsi-keys [GLOBAL-OPTIONS] ca accept-nameless CA-ID yes | no

pepsi-keys [GLOBAL-OPTIONS] ca enable | disable | remove CA-ID

pepsi-keys [GLOBAL-OPTIONS] identity –otp CODE COMMAND …

pepsi-keys [GLOBAL-OPTIONS] otp status [ADDRESS | –console LOGIN] [–json]

pepsi-keys [GLOBAL-OPTIONS] otp enroll | remove ADDRESS [–otp CODE]

pepsi-keys [GLOBAL-OPTIONS] otp reset ADDRESS

pepsi-keys [GLOBAL-OPTIONS] otp enroll | reset –console LOGIN

pepsi-keys [GLOBAL-OPTIONS] wrap rotate [–dry-run]

pepsi-keys [GLOBAL-OPTIONS] dns ADDRESS

pepsi-keys [GLOBAL-OPTIONS] mpki domain list [–json]

pepsi-keys [GLOBAL-OPTIONS] mpki domain show | check DOMAIN [–json]

pepsi-keys [GLOBAL-OPTIONS] mpki domain set DOMAIN [–enable | –disable] [SETTING-OPTIONS]

pepsi-keys [GLOBAL-OPTIONS] mpki credential set DOMAIN [–file FILE]

pepsi-keys [GLOBAL-OPTIONS] mpki credential remove DOMAIN

pepsi-keys [GLOBAL-OPTIONS] mpki user list [–domain DOMAIN] [–deleted] [–json]

pepsi-keys [GLOBAL-OPTIONS] mpki user add ADDRESS –given-name NAME –surname NAME [–select SELECTION]

pepsi-keys [GLOBAL-OPTIONS] mpki user set ADDRESS [–given-name NAME] [–surname NAME] [–confirm] [–select SELECTION]

pepsi-keys [GLOBAL-OPTIONS] mpki user delete ADDRESS

pepsi-keys [GLOBAL-OPTIONS] mpki user import FILE –ldif | –csv [–domain DOMAIN] [–mail-attribute ATTR] [–given-name-attribute ATTR] [–surname-attribute ATTR] [–prune] [–dry-run] [–yes] [–json]

pepsi-keys [GLOBAL-OPTIONS] mpki order list [–domain DOMAIN] [–address ADDRESS] [–open] [–limit N] [–json]

pepsi-keys [GLOBAL-OPTIONS] mpki order release | retry | cancel ORDER-ID

pepsi-keys [GLOBAL-OPTIONS] mpki notices [–domain DOMAIN] [–unread] [–read ID… | –read-all] [–json]

pepsi-keys [GLOBAL-OPTIONS] mpki run [–domain DOMAIN] [–json]

95.1.50.1.3. Description

pepsi-keys is the operator’s tool for Pepsi’s end-to-end cryptography key store — the three tables that hold every key that OpenPGP and S/MIME processing needs:

pepsi.crypto_identity

The key pairs of the addresses that we serve, private half included and wrapped at rest (custody = local, an MTA key). Used to sign outbound mail and to decrypt inbound mail. It also holds the users’ own keys, whose private half lives only in their mail client (custody = client, an MUA key; see MTA keys and MUA keys).

pepsi.peer_key

Remote correspondents’ public keys and certificates, however they were obtained, each with the source it came from, a validity verdict and a cache deadline. Used to encrypt outbound mail and to verify inbound signatures.

pepsi.ca_trust

The CA certificates that an inbound S/MIME chain must reach for its signature to count as trusted.

The tool is not a stage. It manages rows directly, in the shape of pepsi-whitelist(1) and pepsi-settings(1), connecting to the same database as the other components through the shared [pepsi-postgres] section and reading the [pepsi] CRYPTO_* options and the [pepsi-crypto] section described in pepsi.conf(5).

It is a standalone binary rather than part of the unified pepsi executable for two reasons: it is the only program in the tree that generates key material, and a site may install it setuid (see Privileges).

The mpki commands add a managed PKI: S/MIME certificates that a commercial certificate authority issues for the users of a domain, ordered, installed, renewed and revoked by Pepsi (see Managed-PKI commands).

95.1.50.1.3.1. Capability, not shape

An address’s material is stored as one row per capability, never as “the identity”. Each row’s purpose is sign, encrypt or both:

  • an OpenPGP identity is one both row — a transferable key whose sign-capable primary carries an encryption subkey, so the split is intrinsic and costs nothing;

  • an S/MIME identity is normally two rows, one certificate with digitalSignature and one with keyEncipherment/keyAgreement;

  • with [pepsi] CRYPTO_SMIME_SHARED_KEY = yes it is instead one both certificate carrying both key usages (RSA only).

That option decides only what newly created identities look like. Both shapes are supported permanently and may coexist for one address, for example an old shared certificate that is still valid alongside a freshly issued split pair. Every lookup therefore matches a capability (sign or both; encrypt or both) rather than counting rows. Listings and identity show print the purpose for exactly this reason.

95.1.50.1.3.2. Retirement is asymmetric

Pepsi delivers plaintext to the mailbox, so a private decryption key is needed only for mail still in flight and for whatever ciphertext an operator has archived — never to read one’s own mailbox. A private signing key, once retired, can do nothing legitimate at all: nothing ever re-signs old mail. So at expiry or revocation:

  • a sign row’s private half is destroyed, and only the public half is kept so old signatures can still be verified;

  • an encrypt row’s private half is retained;

  • a both row follows the decryption rule, since destroying it would take the ability to decrypt with it. That is the price of shared-certificate mode: revoking a compromised signing key there also ends the ability to receive new encrypted mail.

private_purged_at records when material was dropped, so “deliberately destroyed” stays distinguishable from “never held”; both identity list and identity show report it.

95.1.50.1.3.3. MTA keys and MUA keys

An address may hold keys of two kinds. An MTA key (custody = local) is one whose private half Pepsi holds: pepsi-stage-encrypt(1) signs with it, pepsi-stage-decrypt(1) opens mail with it, and it is advertised in Autocrypt: headers. It is created by identity generate, by an import with –private, or automatically on a user’s first submission under [stage-encrypt] ENABLE_PEP. An MUA key (custody = client) is the user’s own key from their mail client: public-only for ever, never primary. Pepsi encrypts to it and passes mail encrypted to it through unopened, but can never sign or decrypt with it. It is created by an import without –private, by the web console or API, by the e-mail register command, or automatically from the Autocrypt: header of the user’s own submitted mail.

The public face of an address is the newest active MUA key when there is one, else the primary active MTA key. It is the first key that the Web Key Directory serves, and the key to which local mail for the user is encrypted. Beside a MUA key the directory serves the user’s other active MUA keys too (newest first, at most eight; local mail is encrypted to these keys as well), never the MTA key. The MTA key is not retired when an MUA key appears; it keeps decrypting mail from correspondents who still use it. identity show prints the custody and whether the identity is the public face.

95.1.50.1.3.4. Key-server uploads are requested per identity

Each identity records whether its upload to the key server was asked for (crypto_identity.vks_wanted). Automatically generated keys and automatically registered MUA keys start with it off: Autocrypt and the deployment’s own Web Key Directory are how they are found, and an upload cannot be withdrawn. Keys made by hand (identity generate, identity import, and the web and e-mail generate) take [pepsi-keys] VKS_PUBLISH as their default, and –no-publish keeps it off. An explicit request sets it whatever VKS_PUBLISH says: identity publish –vks, the web console’s Upload to the key server, or the e-mail publish command. identity publish –retry uploads exactly the rows where it is set, so “not uploaded” is recorded state, and identity show reports it.

95.1.50.1.3.5. Ownership

An identity is keyed on the lower-cased address. When pepsi-common’s locality rules ([pepsi-crypto] LOCAL_DOMAINS, RECIPIENT_DELIMITER and TARGETS, defaulting to [pepsi-ingress] ACCEPTED_DOMAINS and the /etc/login.defs uid range) resolve that address to a local account, the passwd login is recorded in crypto_identity.login; otherwise the column is NULL — a role address, a hosted domain, an Exchange-fronted deployment.

That column is the access rule. An unprivileged caller may see and change only identities whose login is their own, resolved from the real uid’s passwd entry — not $USER, not an argument, not the effective uid. An identity with no owning account belongs to nobody in particular and is therefore operator-only: treating “unowned” as “everybody’s” would make every role address writable by every local user.

root, and the pepsi-crypto, pepsi and pepsi-owner accounts, may manage every identity. Peer keys and trust anchors have no per-user namespace: they are somebody else’s key, or deployment-wide policy. Every peer and ca subcommand, list included, is therefore operator-only, as are wrap rotate and identity retire.

95.1.50.1.3.6. Privileges

Reaching a private key takes two things, and they are guarded separately:

  • the database role pepsi-crypto, the only one granted the crypto_identity.private_wrapped column (apart from the schema owner pepsi-owner, which reads it by ownership but cannot read the key-encryption key). Every ordinary service role holds a column-level grant that omits it; this includes the pepsi account, under which every ordinary stage worker runs. A compromise elsewhere in the pipeline therefore yields the public half of every identity and nothing more (see pepsi-setup(1));

  • the key-encryption key, which lives only in the filesystem, in secrets.d/pepsi-crypto.secret.

The database alone therefore yields nothing but ciphertext, and the key-encryption key alone yields nothing at all.

pepsi-keys assumes the pepsi-crypto identity only for the duration of each database call. Run as root it becomes that account for the call (root has no database role of its own) and returns afterwards; run as pepsi-crypto or pepsi-owner it simply connects as itself; run from a setuid install it raises its effective ids to the binary’s owner. 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 — a program that must be this role has to be this account.

As shipped the binary carries no setuid bit (mode 0755): one binary able to open every private key in a deployment is a far larger prize than pepsi-whitelist(1)’s single table, so the default is that only the operator runs it. A site that wants ordinary users to manage their own identities makes it setuid pepsi-crypto.

Which authority is in force differs between the two installs. The per-identity ownership rule above applies only when the binary actually carries the setuid bit: a caller is treated as privileged when it is root, when its login is one of the privileged accounts, or when the binary is not setuid at all. On the shipped 0755 install every caller is therefore privileged as far as this program is concerned, and only PostgreSQL stands between a user and another user’s identities — the caller authenticates as themselves and the database grants decide. That is the intended design, but it means granting somebody the pepsi-crypto database role hands them every identity in the deployment, whatever this program’s ownership rule would otherwise have said. When it is setuid, the same three precautions that pepsi-whitelist(1) takes apply: the effective ids are dropped to the invoking user before anything else happens, the environment variables that steer configuration discovery (HOME, XDG_CONFIG_HOME), ${DATADIR} expansion (PATH) and libpq (PG*) are removed, and -c/–config is refused for unprivileged callers — the configuration names the database and the key-encryption key.

95.1.50.1.4. Commands

95.1.50.1.4.1. Identity commands

identity list [–address ADDRESS] [–json] [–served]

List identities as a table: id, address, protocol, purpose, status, whether the row is the primary one for its capability, whether it is published, the state of its private half (yes/no/purged, or client for the user’s own MUA key, whose private half Pepsi never held) and its expiry. An unprivileged caller sees only their own. –address restricts the listing to one address; –json emits the rows as JSON instead.

–served also asks, for every listed address with a published, active identity, what a correspondent is given: both Web Key Directory methods and the OPENPGPKEY and SMIMEA records, fetched with key discovery’s hardened clients and [pepsi-keydiscovery] settings. A SERVED column names the channels that serve each identity’s fingerprint (wkd-advanced, wkd-direct, openpgpkey, smimea; none for a published, active identity that nothing serves; - for one that is not meant to be served), and below the table every channel that disagrees with the key store is listed: MISMATCH when it serves a fingerprint that the store does not publish for that address – another web server on the domain’s apex, a DNS record left from a rotation, a key somebody else put there – INCOMPLETE, ABSENT or FAILED otherwise. With –json the output becomes an object with identities (the rows) and served (one report per address). The network is asked after the database connection is closed, as the invoking user. The answers are the ones that this host gets; a server that answers other askers differently is not detected.

identity show IDENTITY-ID [–json]

Print one identity in full, including its fingerprint, algorithm, custody (local for an MTA key, client for the user’s own MUA key), whether it is the address’s public face (the key that correspondents are given), wrap_key_id, timestamps, any revocation reason, the Web Key Directory local-part hash under which the address is served, and its key-server state: one of verified at TIME, uploaded at TIME , awaiting confirmation, upload requested, or not uploaded (not requested).

identity generate ADDRESS –protocol openpgp|smime [OPTIONS]

Create key material for ADDRESS and store it, private half wrapped. The new material becomes the primary for its capability; nothing existing is rewritten or replaced, so the previous material stays usable for decrypting what was already sent to it.

OpenPGP produces one both row using [pepsi] CRYPTO_OPENPGP_ALGORITHM (ed25519, the default, or rsa at CRYPTO_GENERATE_RSA_BITS, which must be 2048, 3072, 4096 or 8192). S/MIME produces the signing/encryption pair using CRYPTO_SMIME_ALGORITHM (p256, the default, p384 or rsa), each with a self-signed certificate for immediate use.

–name NAME

Display name for the OpenPGP User ID (Name <address>) or the certificate subject. Without it the User ID is the bare address.

–days N

Lifetime of the generated material. Defaults to [pepsi-crypto] IDENTITY_VALIDITY_DAYS (730, two years).

–no-publish

Do not serve the public half over the Web Key Directory or upload it. By default a new identity is published — a key that nobody can fetch cannot be encrypted to — and its key-server upload is requested when [pepsi-keys] VKS_PUBLISH is on.

Generation on request is always allowed, even for an address that already has the user’s own MUA key or a revoked key; only automatic creation refuses an address with any identity.

–csr

Also print a PKCS#10 certificate signing request over each generated key, so a real CA can issue a replacement certificate for the same key without re-keying. S/MIME only; OpenPGP has no such object.

–shared

Force one S/MIME certificate carrying both key usages, whatever CRYPTO_SMIME_SHARED_KEY says. Refused with an elliptic-curve CRYPTO_SMIME_ALGORITHM, the default p256 included, so it needs CRYPTO_SMIME_ALGORITHM = rsa: one EC key doing both ECDSA and ECDH is cross-algorithm key reuse that several S/MIME clients reject.

–split

Force the separate signing and encryption certificates. Mutually exclusive with –shared; with neither, the configured default applies.

identity import ADDRESS –protocol P –purpose PURPOSE –public FILE [OPTIONS]

Store material generated elsewhere. PURPOSE is sign, encrypt or both and must describe what the material can actually do, because every later lookup matches on it. The public half is an OpenPGP transferable key or an X.509 certificate (DER or PEM, detected); - reads standard input. The fingerprint is derived from the material itself: the OpenPGP fingerprint, or the SHA-256 of the certificate DER.

–private FILE

The private half — an OpenPGP transferable secret key, or a PKCS#8 key — which is wrapped before it is stored, as an MTA key (custody = local). Without it only the public half is kept. For OpenPGP the row is then recorded as the user’s own MUA key (custody = client), which is never primary (–primary is ignored for it): Pepsi can publish and encrypt to it but never sign or decrypt with it. It pre-empts automatic key creation for the address and becomes the address’s public face; mail encrypted to it is passed to the mail client unopened. A public-only S/MIME import keeps custody = local – typically a CA-issued certificate over a key already in the store (see identity csr).

–algorithm NAME

Algorithm name to record. Informational; defaults to imported.

–primary

Make this the material used for new messages of its capability.

–no-publish

Do not publish the public half. Otherwise the key-server upload is requested when [pepsi-keys] VKS_PUBLISH is on.

identity export IDENTITY-ID [–private] [–pem]

Write the material to standard output in its own binary form — OpenPGP packets or X.509 DER — so it can be piped straight into another tool. A public OpenPGP key is written without third-party certifications, as it is published.

–private

Export the private half instead of the public one, unwrapping it first. Fails when the row holds none, naming which of “never held” and “purged” applies.

–pem

Wrap X.509 material in a PEM block. OpenPGP material has no PEM form and is refused with a pointer to gpg --enarmor.

identity csr IDENTITY-ID

Print a PKCS#10 certificate signing request over an identity’s existing private key, with the key usage that its purpose implies. This is the path that matters once an identity is in service: the self-signed certificate gets the organisation going, and the same key — already published, already used to receive encrypted mail — is later presented to a real CA without re-keying. S/MIME identities only, and only while the private half is still held. The same request is available without a terminal: POST /api/v1/identities/{id}/csr and the console’s identity page ask pepsi-setup apply for it as an identity-csr task, and the issued certificate is installed with POST /api/v1/identities/{id}/certificate (identity-certificate), which checks that it is over the identity’s own key (see pepsi-httpd(1) and pepsi-setup(1)).

identity revoke IDENTITY-ID [–reason TEXT] [–upload]

Withdraw an identity. The row becomes revoked and stops being primary; the public half is kept so signatures made before the revocation can still be checked. A sign row’s private half is destroyed here and now; an encrypt or both row keeps its private half, and the command says so. TEXT is recorded with the row.

For an OpenPGP identity whose private half is still held, the command first builds a revocation certificate — signed by the key that it retires, with TEXT as its reason — and stores it as the identity’s public half, in the same statement that revokes the row (and destroys a sign row’s private half). The Web Key Directory then serves the key as revoked, after any usable key of the address, so a correspondent’s client that refreshes it learns it is dead; and when the key had been uploaded to a key server, the revocation is uploaded there at once, or by identity publish –retry if that fails. If the certificate cannot be made (no key-encryption key, say), nothing is revoked and the command fails. The e-mail retire command of pepsi-stage-encrypt(1) and the console’s revoke-identity task revoke the same way.

No certificate can be made for an S/MIME identity (its issuer revokes it), a user’s own MUA key (the private half is in their mail client) or a key whose private half was already destroyed; such an identity simply stops being served, and the command prints that correspondents who have it are not told.

–upload sends the revocation to the configured key server even when the key was never uploaded there; a key that was uploaded gets it without the flag. A key server can be told a key is revoked, never told to forget it.

identity forget-private IDENTITY-ID [-y, –yes]

Destroy an identity’s private key permanently, leaving the public half. This is the only way a decryption key leaves the store, and it is irreversible: anything still queued in pepsi.workqueue, anything in an encrypted archive and any message redelivered later from a backup becomes unreadable. Mail already delivered is unaffected. The command prints exactly that and asks for confirmation; –yes skips the question, and with no terminal and no –yes the answer is no, so an unattended run cannot destroy key material because nobody was there to object.

identity set-primary IDENTITY-ID

Make this the material used for new messages of its (address, protocol, purpose). Only an active identity may be made primary. The previous primary for the same triple is demoted.

identity publish IDENTITY-ID [–wkd] [–vks] [-y, –yes]

Serve the identity’s public half over the Web Key Directory. This is the reversible channel — our own server, our own domain — and it is what –wkd names; it is also the default, so the flag exists only to make the channel explicit. The material stays usable either way.

–vks additionally records the upload request (vks_wanted), uploads the key to the configured key server and asks it to mail the confirmation link to the address. Because the request is recorded before the attempt, a failed upload is retried by identity publish –retry rather than forgotten. That is irreversible: a key server can later be told the key is revoked, but never told to forget it, and the address becomes a permanent public record. The command prints exactly what cannot be taken back and asks for confirmation; –yes skips the question, and with no terminal and no –yes the answer is no. OpenPGP only — there is no key server for S/MIME, whose publication channel is the SMIMEA record that dns prints.

identity publish –retry [–dry-run]

Work through every published, active OpenPGP identity whose upload was requested (vks_wanted) and that is not verified on the key server yet, instead of one. This is the form to run periodically: pepsi-keys-publish-retry.timer runs it hourly. It is not gated by [pepsi-keys] VKS_PUBLISH: that option only decides whether keys made by hand start out requested, and a user’s own request is honoured whatever it says. An automatically created key is never on the list unless its owner asked.

It exists because publication is a two-step protocol: an upload returns a token, only the token authorises the confirmation mail, and only a followed link makes the server serve the key by address. A key uploaded but never confirmed is stored yet unfindable. Each round first asks the key server whether the address is already served, and otherwise uploads and requests verification. A confirmation link followed by pepsi-stage-vks-confirm(1), by a human, or on an earlier run whose database write did not land therefore ends the loop all the same. Identities are spaced by VKS_RETRY_INTERVAL, at most VKS_BATCH per run, and abandoned after VKS_MAX_ATTEMPTS with the reason left on the row for identity show. –dry-run lists what would be published and changes nothing. Operator-only.

Its second work list is the revocations: every revoked OpenPGP identity whose key had been uploaded and whose revocation certificate the key server has not accepted yet (vks_revoked_at), spaced and capped on the same counters. However the key was revoked — this command, the retire e-mail command or the console — this job is how its revocation reaches the key server.

identity unpublish IDENTITY-ID

Stop serving the identity over the Web Key Directory, and forget its key-server bookkeeping so the retry job leaves it alone and a later re-publication starts from a clean slate.

It does not remove anything from a key server, because nothing can. When the identity had been uploaded the command says so and points at identity revoke –upload, which is the only way to tell the world the key is dead (the bookkeeping that it forgets is what would otherwise send the revocation there without the flag).

identity delete IDENTITY-ID [-y, –yes]

Remove the row outright, public half included. Confirmed like forget-private. Prefer revoke, which keeps the public half so old signatures remain checkable; a deleted identity leaves nothing behind at all.

identity retire

Run the retirement sweep over every identity: everything past its expires_at becomes expired, private signing material is destroyed and stamped, and decryption material (including a shared both row’s) is left alone. pepsi-keys-retire.timer runs it daily; identity revoke applies the same rule inline for one identity. Operator-only.

identity rotate-due [–dry-run]

The forward-secrecy profile’s scheduled run, off unless [pepsi-crypto] ENCRYPTION_ROTATION_DAYS is set (see pepsi.conf(5) and the manual’s key-management chapter). First, every server-held (custody = local) key able to decrypt that is older than that many days is replaced: a new key is generated as identity generate would and becomes the primary, published over WKD when the old one was and queued for the key server when the old one was; the old key is revoked (reason superseded) through the same path as identity revoke, so an OpenPGP key gets its revocation certificate and the Web Key Directory serves it as revoked; unlike a key revoked by hand, it keeps opening mail encrypted to it until its private half is destroyed. An OpenPGP key is replaced whole (one key signs and decrypts); of a split S/MIME pair only the encryption certificate is replaced, and new SMIMEA records are due (dns). Audited as key.identity.rotate. Second, the private half of every retired (revoked or expired) server-held decryption key retired more than RETIRED_PRIVATE_GRACE_DAYS ago (30 by default) is destroyed – unless a message still in the queue, in any stage or status (waiting, parked, failed), is encrypted to it, judged from the recipient identifiers of the stored message’s outermost ciphertext; such a key is kept, with the queue ids named, and tried again at the next run. Destroying is the same operation as identity forget-private and audited as key.identity.forget-private. A user’s own (client-custody) key is never rotated or purged, and a signing-only key is never purged by it. Idempotent; --dry-run reports what is due and changes nothing. pepsi-keys-rotate.timer runs it daily. Operator-only.

95.1.50.1.4.2. Peer commands

peer list [–address ADDRESS] [–json]

List cached peer keys: id, address, protocol, source, validity, whether the lookup that produced it was DNSSEC-validated, whether it is pinned, and the fingerprint. A row that pepsi-keydisc(1) retired because its issuer’s revocation list named it reads revoked and ends in -- revoked DATE: REASON (which distribution point listed it, the entry’s reason code and date; revoked_at and revoked_reason in the JSON). Such a row is no key for anybody – pepsi-stage-encrypt(1) treats the address as one without a key – and stays listed until a discovery replaces it (a re-issued certificate from the same source may) or peer remove drops it.

peer show ADDRESS [–protocol PROTOCOL] [–json]

Show the keys cached for ADDRESS, after the matching rule: an exact address match always wins, and a *@domain row is consulted only when there is no exact one (it is flagged as a domain-wide fallback in the output). PROTOCOL defaults to openpgp. A revoked row is shown with the same -- revoked note as in peer list; it is listed, not used.

peer unclaimed [–address ADDRESS] [–all-sources] [–json]

List the addresses that this deployment serves and that hold no identity of ours, yet have a harvested or gossiped peer key — the keys that a stranger can plant by sending us a message with a forged From:. Keys are harvested on the From: header, which the sender writes, and inbound authentication is fail-open, so on a deployment that does not enforce DMARC on its own domain such a row can name one of our own users. Where we hold an identity the row is inert (our own key pre-empts it); where we do not, it decides what mail to that user is encrypted with. That is deliberate, since it is also the only way for a user who runs GnuPG in their own client to get their real key here. This is therefore a worklist, not an alarm: confirm each key with its owner, then import it as an identity (identity import without –private), after which it is inert, or remove it (peer remove).

Served means the domain is one of [pepsi-ingress] ACCEPTED_DOMAINS or [pepsi-crypto] LOCAL_DOMAINS; no passwd account is required. No identity means no active identity able to encrypt, the same rule that the encryption stage’s pre-emption applies, so an address whose only identity expired, was revoked or can only sign is listed; the IDS column counts its identities in any state. Harvested is source inbound or inbound-signed (the sender’s own Autocrypt: header or attached key, the latter from a message their domain’s DKIM signature covered) or gossip (a third party’s Autocrypt-Gossip:); –all-sources includes discovered, manual and API keys as well, which is the set GET /api/v1/peers/unclaimed reports. A *@domain row is never listed. Read-only and operator-only. The exit status is 0 whether or not anything was found; with –json an empty report is [], which is what a periodic check should test for.

peer import ADDRESS –protocol P –file FILE [–pin]

Store a correspondent’s key by hand (- reads standard input). The row is recorded with source manual, which outranks every discovery mechanism, and is the only source permitted to carry a *@domain address — a database constraint, not a convention, so no discovery answer for one address can ever be generalised to a whole domain. A *@domain key authenticates the domain (in practice its gateway), not an individual sender: a signature that verifies against it shows that the domain’s key holder signed, not which user at the domain wrote the message, and encrypting to it reaches the gateway rather than the person. When the certificate names no address at all, the command says so as it stores it: a signature made with such a key is reported valid for every From: address at the domain. Enter one only for a partner gateway that you trust to sign for each of its users.

A key that conflicts with one already stored replaces it only if it outranks everything there; a pinned row is never displaced, and the command says which of stored, refreshed, replaced and kept happened. (The single exception to “only if it outranks” is the Autocrypt tier’s newest-wins rule, which never involves a manual key in either direction — see pepsi-keydisc(1).)

Importing a key that is already stored (same fingerprint) merges the file into the stored certificate rather than replacing it, so an older export cannot undo a revocation that the stored copy carries.

A key whose private half is known is refused: one on the known-compromised list (Known-compromised-key commands: badkeys, the Debian OpenSSL weak keys, and the moduli that an earlier peer screen factored), or an RSA key whose modulus gives its primes away (ROCA, close primes, a small factor).

–pin

Pin the imported key, so discovery never replaces it.

peer pin PEER-KEY-ID, peer unpin PEER-KEY-ID

Set or clear the pin on one stored key.

peer refresh [–address ADDRESS] [–expire PEER-KEY-ID] [–expiring-within-days DAYS] [–limit N]

Re-validate cached peer keys. It only ever refreshes keys that already exist: it never discovers a key for an address that has none. Pepsi looks an address up when it has mail for it, which is why discovery is driven by the pipeline (pepsi-keydisc(1)) rather than by this command.

Three shapes, selected by the flags:

–address ADDRESS

Run the whole discovery fan-out for one address in this process — every method in [pepsi-keydiscovery] SOURCES at once, with the rank-grace stop rule — and store what it finds with the right source and DNSSEC flag. One line per method is printed: the protocol and fingerprint (marked (dnssec) for an AD-validated DANE answer), no key, or the error. This also settles the address’s discovery request, so it releases any message parked on it. An address excluded by ALLOW_DOMAINS/DENY_DOMAINS is refused rather than queried.

–expire PEER-KEY-ID

Clear one row’s cache deadline so the next message for that address re-fetches. No network I/O at all, and mutually exclusive with –address.

(neither flag)

Sweep: every key that is due — its refresh_after has passed, or its own expiry falls within –expiring-within-days (default 7) — is re-checked, up to –limit keys (default 100), only through the method from which it was learnt: a vks key at the key server, a wkd or wkd-direct key at the same Web Key Directory method, a dane key in DNS, an ldap key in the directory — and only while that method is still in SOURCES. Keys that came from no network method (inbound, inbound-signed and gossip, harvested from mail; manual/api, entered by hand) are never refreshed over the network, and neither are pinned keys or *@domain rows; such keys are not even selected, so they never use up –limit. The number re-validated is printed. This is the natural body of a periodic timer, and pepsi-keys-refresh.timer runs it daily (with --limit 200). The key server is therefore told only about correspondents whose keys it supplied in the first place, once per CACHE_TTL; ALLOW_DOMAINS/DENY_DOMAINS apply, [stage-encrypt] DISCOVERY does not.

peer prune [–retain-days DAYS] [–dry-run]

Delete expired peer keys and aged-out discovery requests — two tables, one job. A peer key that expired more than DAYS (default 7) ago is removed unless it is pinned. The expiry is the one that the key itself states — an OpenPGP primary key’s current self-signature, an X.509 notAfter — recorded whenever a key is learnt, whether by discovery, harvesting or gossip (a key imported by hand records none, and a key that states none is never pruned); on the pepsi.key_request side both a settled row whose negative entry has aged out past the same window and a pending row abandoned that long past its deadline have nothing left to say and go too. –dry-run reports how many keys carry an expiry and are unpinned, and removes nothing.

peer screen [–dry-run]

Find stored keys whose private half is known, and remove them from the cache. Two tests run over every peer key and the public half of every identity that is not revoked:

  • batch GCD over all their RSA moduli (Bernstein’s product and remainder trees): two keys made by a generator short of entropy can share a prime, and then one gcd factors both. No test of a single key can see this; it is a property of the pair. A factored modulus is recorded in the known-compromised list (pepsi.compromised_key, list screen), so the same key is refused at use and is not stored again, by key discovery or when a message carries it (pepsi-stage-autocrypt-learn(1));

  • the known-compromised list itself (Known-compromised-key commands), for keys stored before the list knew them.

A peer key that fails either is deleted, a pinned one too (a pin says whose key it is, and a factored key is anybody’s), and each is recorded in the audit log as key.peer.compromised (severity warning). Our own identities are reported, never changed: a factored identity’s private key is computable, the remedy (revoke it, create a new one) is the operator’s, and the screen writes a key.identity.compromised row with severity error and says so on standard output. –dry-run reports and changes nothing. Exact duplicates (one key stored under two addresses) are not a shared factor. The arithmetic takes time quadratic in the total size of the moduli: seconds for thousands of keys, minutes for tens of thousands. pepsi-keys-refresh.service runs it daily, after peer refresh and peer prune.

peer remove PEER-KEY-ID

Delete one stored key. This is also how an operator lets through a correspondent’s newer Autocrypt key that ACCEPT_ROTATION = expired held (a key.peer.rotate.held audit row; see pepsi-stage-autocrypt-learn(1)): with the old row gone, the next message carrying the new key stores it as a first key.

95.1.50.1.4.3. S/MIME capability records

Whether a correspondent’s S/MIME client reads CMS AuthEnvelopedData (AES-256-GCM) is kept per peer in pepsi.smime_capability, because an X.509 certificate states no content-encryption capability of its own. pepsi-stage-encrypt(1) and pepsi-stage-reencrypt(1) choose the container from it: under the default [pepsi] CRYPTO_ALLOW_DOWNGRADE = negotiate a recipient recorded as cbc gets AES-256-CBC EnvelopedData, and every other recipient — including one with no record — gets AuthEnvelopedData. Records come from two places:

  • learnt — pepsi-stage-autocrypt-learn(1) reads the RFC 8551 SMIMECapabilities attribute of a correspondent’s signed mail and records it against the certificate that made the signature (only when that signature verifies), so a claim describes nobody but the key holder;

  • configured — with the commands below, against an address or *@domain. A configured record wins over a learnt one.

Thunderbird cannot read AuthEnvelopedData and shows a blank message when it gets one. Its signatures advertise no AES-GCM, so a Thunderbird correspondent who has sent a signed message is recorded automatically. One who has never sent a signed message gets, with the first message encrypted to their certificate, a plaintext notice beside the ciphertext asking them to report an empty message and to reply signed (pepsi-stage-encrypt(1), “The first-message notice”); peer capability set ADDRESS cbc settles it at once. The notice is sent once per certificate, and the table records that too: a notice row carries the fingerprint and notice_sent_at but no capability. A correspondent who signs with one certificate and encrypts to another also needs a configured record, since a learnt record covers the signing certificate only. All four commands are operator-only.

peer capability list [–address ADDRESS] [–json]

List the records, or those bearing on ADDRESS: its configured record, its domain’s *@domain record, and the learnt and notice records of the certificates cached for it. A learnt or notice record shows the addresses whose cached keys are that certificate; the READS column says aead, cbc or, for a notice row, told.

peer capability set ADDRESS aead | cbc

Configure the record for ADDRESS (or *@domain), replacing any. Audited as key.peer.capability.

peer capability unset ADDRESS

Remove the configured record; a learnt one, if any, applies again. Audited.

peer capability forget FINGERPRINT

Remove the record learnt for a certificate (hex SHA-256, colons allowed). The next signed message from its holder records it again. Audited.

95.1.50.1.4.4. Known-compromised-key commands

Pepsi looks up every key that it judges in pepsi.compromised_key: a key to encrypt to, a key to verify with, a key in an S/MIME chain, and a key before key discovery or a message stores it. A key found there is refused like one below [pepsi] CRYPTO_MIN_RSA_BITS: anybody can sign with it and read what is encrypted to it. The table holds two lists, told apart by a source name:

  • the badkeys blocklist (https://badkeys.info): every RSA and EC key that the Debian OpenSSL bug (CVE-2008-0166) could produce, keys published in RFCs, test suites and documentation, and keys extracted from firmware and software packages, as truncated SHA-256 hashes of each key’s public value (no key material). Its source lists keep badkeys’ names (debianssl, forti, rfc, …). badkeys’ ransomware list, keys of ransomware operators that no correspondent uses, is left out;

  • screen: the RSA moduli that peer screen factored here.

The list only grows. An update adds what is new and removes nothing, since a key whose private half was once published stays compromised. An entry found to be wrong is dismissed: it refuses nothing any more, and the next update does not add it back. All four commands are operator-only.

blocklist update [–force]

Ask [pepsi-keydiscovery] BADKEYS_URL/badkeysdata.json (default https://update.badkeys.info/v0) whether the list changed, sending back the ETag and Last-Modified of the last run; an unchanged list costs that one request. A new list is downloaded (about 50 MB in 2026), only from below BADKEYS_URL, checked against the SHA-256 the metadata names and for order, and its new entries are added in one transaction. The first import writes about three million rows (about 240 MB with the index) and takes under a minute. Two checks stand in for the signature that the metadata does not carry; they refuse the list when it has fewer records than the last one, or when it would add more than a quarter of what is there (beyond 50 000 entries; the first import excepted). –force imports such a list anyway, and re-fetches an unchanged one. Every run, its outcome (imported, unchanged, refused, failed) and what it added from which source list is recorded in pepsi.compromised_key_import. pepsi-keys-blocklist.timer runs it ten minutes after it starts and then daily; systemctl mask --now pepsi-keys-blocklist.timer stops that (pepsi.target’s Wants= starts a merely disabled timer again).

blocklist status [–json]

When the list was last checked and the date of the list it holds, the entries per source list (and how many are dismissed), and the last ten runs with what each added. pepsi-status(1) warns when the last check is more than three days old or the last run failed or was refused.

blocklist dismiss –import N | –list NAME

Take entries out of service: those that one run added (N from blocklist status), or those of one source list (a badkeys list name, its number, or screen). Audited (key.blocklist.dismiss). A dismissed entry stays in the table, so an update cannot add it back.

blocklist restore –import N | –list NAME

Undo dismiss. Audited (key.blocklist.restore).

95.1.50.1.4.5. Certificate Transparency log list

For every TLS client connection that Pepsi verifies against the public roots, it checks the Signed Certificate Timestamps of the server certificate against a list of Certificate Transparency logs, and it warns about a certificate that was not logged ([pepsi] CT_CHECK, pepsi.conf(5)). The list is a public file, [pepsi] CT_LOG_LIST (default /var/lib/pepsi/ct-log-list.json), in the format of Google’s v3 log list; no database is involved. Both commands are operator-only.

ct-logs update [–force]

Fetch [pepsi] CT_LOG_LIST_URL (default https://www.gstatic.com/ct/log_list/v3/log_list.json), sending back the ETag and Last-Modified of the last run (kept in CT_LOG_LIST.meta), so an unchanged list costs one request. A new list is parsed before anything is written, refused if it names usable logs of fewer than two operators or is older than the list in place, and otherwise replaces the file atomically (mode 0644). –force re-fetches an unchanged list and installs an older one. pepsi-keys-ct-logs.timer runs it five minutes after it starts and then daily; systemctl mask --now pepsi-keys-ct-logs.timer stops that, and certificates are no longer checked once the list is more than 70 days old.

ct-logs status [–json]

The list’s path, date, age and number of logs, and whether it is too old to be used.

95.1.50.1.4.6. Trust-anchor commands

ca list [–json]

List the trust anchors with their id, whether they are enabled, whether they vouch for a leaf that names no mailbox (NAMELESS), their label, their scope (SCOPE: the domains, (constrained) for an unscoped anchor whose certificate carries nameConstraints, any otherwise) and their subject; then a warning naming every enabled anchor that vouches for every mail domain. The JSON carries permitted_domains and constrained.

ca add FILE [–label TEXT] [–accept-nameless]

Add a CA certificate (DER or PEM; - reads standard input) as a trust anchor. A certificate without basicConstraints CA:TRUE is refused: no chain could ever end at it. Idempotent on the certificate’s SHA-256 — adding the same anchor twice only updates the label. --accept-nameless sets the opt-in below on a new anchor, --domain (repeatable) its scope (see ca scope); an existing anchor’s scope is changed with ca scope only.

ca scope CA-ID –domain DOMAIN… | –any

Limit the mail domains for which an anchor is trusted, or (--any) lift the limit. Each DOMAIN covers itself and every subdomain (example.org covers alice@example.org and bob@sub.example.org, never example.net); it is stored as lower-case A-labels, and a leading dot is refused. The scope is applied during path validation as an RFC 5937 trust-anchor name constraint – an rfc822Name permitted subtree per domain – to every mailbox (rfc822Name, SmtpUTF8Mailbox, subject emailAddress) of every certificate under the anchor and to the From: address being verified, in addition to any nameConstraints the anchor certificate carries itself (a name must satisfy both). A signer outside it does not chain to this anchor: its signature reads valid-untrusted unless another anchor vouches for it. A revocation list that the anchor (or an intermediate under it) signed retires only certificates inside its scope. An anchor added for one partner CA should carry that partner’s domains; an enabled anchor with neither a scope nor nameConstraints of its own is warned about by ca list, pepsi-status(1) and pepsi-setup check. Audited as key.ca.scope.

ca accept-nameless CA-ID yes | no

Whether a leaf under this anchor that names no mailbox — no rfc822Name, no RFC 9598 SmtpUTF8Mailbox, no emailAddress — may still make a signature valid for the From: it arrived under. Off by default: such a certificate contradicts no From: line, so the binding cannot fail it, but it vouches for no address either, and pepsi-stage-decrypt(1) therefore reports a signature under it valid-untrusted (withheld=no-identity) rather than letting one certificate verify as every sender. Turn it on for a CA whose own issuance process binds each leaf to its holder’s mailbox out of band. Audited as key.ca.accept-nameless.

An anchor is accepted here on its basicConstraints alone, but path building applies its constraints like any other CA’s (RFC 5937): a name-constrained anchor vouches only for names inside its nameConstraints, a CA that said pathlen:0 will not have a sub-CA accepted below it, and a requireExplicitPolicy or inhibitAnyPolicy it carries is honoured. A chain that breaks one fails with policy-rejected. So does one through a CA carrying a critical extension Pepsi cannot process at all (RFC 5280 §4.2) — such a CA is never used as an issuer.

ca enable CA-ID, ca disable CA-ID

Hand an anchor to the verifier, or stop doing so while keeping the row for the record.

ca remove CA-ID

Delete an anchor.

Pepsi ships no default anchor set, deliberately. A signature that chains to a CA that nobody chose is reported untrusted rather than bad, so an empty store degrades to “we cannot vouch for this” — and an operator who adds an anchor is making a decision rather than inheriting one.

95.1.50.1.4.7. Second-factor commands

An address may have a second factor: a TOTP secret (RFC 6238, SHA-1, six digits, 30-second steps) that its owner keeps in an authenticator app. Once it exists, an unprivileged caller (a setuid install) must present a current code for every change to that address’s identities – identity generate, import, revoke, forget-private, set-primary, publish, unpublish, delete – and for identity export --private and identity csr, as the option –otp CODE of the identity group (pepsi-keys identity --otp 123456 revoke 7). Ownership is checked before the code, so a user cannot count failures against another user’s enrolment. The operator (root, pepsi-crypto, a non-setuid install) is never asked. The same second factor guards the e-mail key commands and the web console; see pepsi-stage-encrypt(1) and the key-management chapter of the manual.

A code is accepted once (a replay within its own 30 seconds is refused), one step of clock skew either way is tolerated, a wrong or replayed code counts as a failure and a right one resets the count, and ten failures in a row lock the second factor until the operator resets it.

otp status [ADDRESS] [–json]

Show an address’s enrolment: when it was enrolled and last used, and the consecutive failures (or LOCKED). The operator may omit ADDRESS to list every enrolment. Never shows a secret.

otp enroll ADDRESS [–otp CODE]

Create a fresh secret for ADDRESS and print it once, as base32 and as an otpauth:// URI (qrencode -t ansiutf8 turns that into a QR code to scan). Replaces an existing enrolment, starting again at zero failures; the owner needs a current code of the old one for that, the operator does not – which is how the operator hands a locked-out user a new secret.

otp remove ADDRESS [–otp CODE]

Remove the second factor; the owner needs a current code.

otp reset ADDRESS

Operator only: remove the second factor whatever its state, unlocking the address. Its owner enrols again (by e-mail, or with otp enroll).

otp status –console LOGIN [–json], otp enroll –console LOGIN, otp reset –console LOGIN

Operator only: the same for the administration console’s account LOGIN (an account of POST /api/v1/accounts, not an address). Once enrolled, every password sign-in to the account (POST /api/v1/auth/login, the console’s sign-in form) needs a current code beside the password, which pepsi-setup apply checks for pepsi-httpd(1) in a confirm-login task, so the applier must be installed. The secret is kept under the subject console LOGIN; reset is how the operator lets an administrator whose second factor is locked or lost back in.

The secret is stored wrapped under the key-encryption key, like a private key, in a table that only the pepsi-crypto role may read; wrap rotate re-wraps it too.

95.1.50.1.4.8. Key-encryption-key commands

wrap rotate [–dry-run]

Re-wrap every stored private key, and every second-factor secret, under the current [pepsi-crypto] KEY_WRAP_KEY_ID. Rotation is incremental by construction, because each row records the key that sealed it: configure the new secret as KEY_WRAP_SECRET and keep the old one beside it as KEY_WRAP_SECRET_<OLD-ID>, point KEY_WRAP_KEY_ID at the new id, and run this. Between the configuration change and the sweep the deployment keeps working — new material is sealed under the new key, old material still opens under the retired one — and only afterwards may the retired secret be removed.

The same sweep re-wraps a private key that is already under the current key but in wrapping format 0x01, whose associated data does not bind the key’s fingerprint (such a key still opens, but is never written that way); run it once on a database that holds any, even when the key-encryption key is unchanged.

Rows whose key-encryption key has no configured secret are reported and left untouched rather than failing the run; so are rows re-wrapped concurrently (each update is guarded on the old key id and the old blob, so a newer wrap is never written over).

–dry-run

List what would be re-wrapped, and change nothing.

95.1.50.1.4.9. DNS publication

dns ADDRESS

Print, in zone-file format, the DNS records that publish every published, active identity of ADDRESS: an OPENPGPKEY record (RFC 7929) for OpenPGP material and an SMIMEA record (RFC 8162, in the TLSA 3 0 0 — domain-issued certificate, full certificate, exact match — form) for S/MIME. Both are published under a hashed owner name, the hex of the first 28 octets of the SHA-256 of the local part. The hash does not hide the address: in an NSEC-signed zone the owner names can be listed by walking the zone, under NSEC3 they can be recovered by an offline dictionary attack, and either way a table of common local parts turns them back into addresses. The output says so in a comment: online signing with minimally covering records (RFC 4470/7129) resists the walk, and an address list that must stay private is published by WKD only.

An OPENPGPKEY record carries the key without third-party certifications, also when the stored identity was imported carrying some.

Publish these only in a DNSSEC-signed zone, which the output repeats as a comment: an unsigned key record is a key from whoever can answer for the zone, which is no improvement on having no key at all.

The DNS owner-name hash is case-sensitive (RFC 7929 §3), unlike the Web Key Directory hash of the same local part, which lower-cases. The two are computed by different functions on purpose.

pepsi-setup(1) prints the same records for every published identity as part of its DNS output, capped at a readable number; this command is how to get one specific address in a large deployment.

95.1.50.1.4.10. Managed-PKI commands

With a managed PKI, a commercial certificate authority issues an S/MIME certificate to each user of a domain, and nobody has to carry a certificate request to the CA and the certificate back by hand. Pepsi orders through the DigiCert CertCentral Services API, by default the product Secure Email for Employee (secure_email_sponsor). Such a certificate is sponsor-validated: it names the person (given name and surname) and the mail address, and the organisation that owns the CA account vouches for the person and pays for the certificate.

Pepsi generates every key itself and sends the CA only a certificate request, so no private key leaves the host. Before it is installed, the certificate that comes back must name the address, allow e-mail protection, carry the key usages that the order needs and be over the order’s own key. It then becomes an ordinary S/MIME identity (custody = local), and the CA’s intermediate certificates are stored with it, so that every signature it makes carries them. The manual’s key-management chapter describes the whole process.

Each managed domain has its own settings and its own CA account, and nothing is ordered for a domain until it is enabled and its credential is stored. The settings, the users and the orders are kept in the database (pepsi.mpki_domain, mpki_user and mpki_order); the credential is a file (Files). Every mpki command is operator-only (root or pepsi-crypto), because the settings decide what the organisation is billed for and whose name a certificate carries. The commands that change settings, users or orders, the credential or the notices are recorded in the audit log (mpki.domain.set, mpki.credential.set, mpki.credential.remove, mpki.user.add, mpki.user.set, mpki.user.delete, mpki.user.import, mpki.order.release, mpki.order.retry, mpki.order.cancel, mpki.notice.read).

mpki domain list [–json]

One line per managed domain: whether it is enabled, its enrolment mode and header-name policy, the renewal window, one or two certificates, the key algorithm, the daily limit, and whether its credential file is present.

mpki domain show DOMAIN [–json]

Every setting of one domain, the path of its credential file and whether that file exists, and who changed the settings last.

mpki domain set DOMAIN [OPTIONS]

Create a domain’s settings or change them. An option that is left out keeps its current value, or its default for a new domain. A new domain starts disabled. When the command enables a domain that has no credential yet, it says so.

–enable, –disable

Switch the managed PKI of the domain on or off (default off). While a domain is disabled, nothing is ordered, renewed or revoked for it. That includes the certificates of users who are deleted or opt out meanwhile: they are revoked once the domain is enabled again.

–api-url URL

The base URL of the CA’s API, by default https://www.digicert.com/services/v2. It must be https://; plain http:// is accepted only for localhost and 127.0.0.1, for a stand-in during tests.

–organization-id ID, –any-organization

The CA’s id of the validated organisation that sponsors the certificates. Without one (the default, or after –any-organization) the account’s only active organisation is used, and an account with several organisations refuses the order and lists them.

–product NAME

The CA’s product name. Default secure_email_sponsor.

–validity-years YEARS

The lifetime to order, 1 to 3 years (default 1). The product may accept fewer.

–enrolment MODE

Who gets a certificate. first-send (the default): a user, once they have sent mail through Pepsi. all: every user in the list. manual: only the users an administrator selects (--select yes). In every mode, a user whose selection is no gets none.

–header-names POLICY

What happens to a name that Pepsi took from the display name of a user’s first message. approve (the default): the order waits until an administrator confirms the name. trust: it is ordered at once. A display name is whatever the sender typed, and the organisation vouches for the name that the certificate carries, so change this only where every sender’s display name is set by an administrator.

–renew-days DAYS

Order the replacement this many days before the current certificate expires, 1 to 365. Default 90.

–certificates N

one (the default): one certificate for signing and encryption. two: a signing and an encryption certificate, ordered separately. One certificate needs an RSA key.

–key-algorithm ALG

The key generated for each order: rsa2048, rsa3072 (the default), rsa4096, p256 or p384. The elliptic curves need --certificates two.

–daily-limit N

At most this many new enrolments of the domain go to the CA in any 24 hours (default 20). An order beyond it is held (daily-limit) and an administrator is told; 0 holds every new enrolment. Renewals do not count and are never held by the limit.

–notify ADDRESS, –no-notify

Mail the domain’s notices to ADDRESS, or stop mailing them (the default: notices are only listed by mpki notices). The mail also needs [pepsi-mpki] NOTIFY_STAGE (Managed-PKI configuration).

mpki domain check DOMAIN [–json]

Ask the CA whether the domain can order, and order nothing: whether the credential is accepted, whether the product is available, which organisation sponsors the certificates, and whether the domain is listed and validated in the account (the CA validates the domain of every order). Each problem is printed on a line of its own, and the command exits with status 1 when there is one.

mpki credential set DOMAIN [–file FILE]

Store the domain’s API key, read from FILE or from standard input, which keeps it out of the shell history and the process list. It must be one word: the CertCentral API key, which Pepsi sends in the X-DC-DEVKEY header. The key is written to mpki-DOMAIN.secret in [pepsi-mpki] CREDENTIAL_DIR with mode 0640, through a temporary file and a rename; run as root, the command gives the file to group pepsi-crypto.

mpki credential remove DOMAIN

Delete the credential file. The domain’s waiting orders are then held (no-credential) until a credential is stored again.

mpki user list [–domain DOMAIN] [–deleted] [–json]

One line per user: the address, the name, where the name came from (header, ldap or local; a ? after it means that nobody has confirmed the name yet), the selection, wanted when the user is to have a certificate, and the newest order with its state and, for a held order, the reason. –deleted includes deleted users; –json gives each user with their five newest orders.

mpki user add ADDRESS –given-name NAME –surname NAME [–select SELECTION]

Create a user under a name that the administrator vouches for (source local, confirmed), or bring back a deleted user. SELECTION is default (the domain’s enrolment mode decides), yes (always enrolled, in manual mode too) or no (opted out). An existing user keeps their selection unless –select names another one. The address’s domain must be configured first (mpki domain set).

mpki user set ADDRESS [–given-name NAME] [–surname NAME] [–confirm] [–select SELECTION]

Change one user. A new given name or surname confirms the name, since the administrator who typed it vouches for it; –confirm approves the name as it is. Either releases an order that waits for the name at the next run. A certificate that is already installed keeps the old name until it is renewed. –select no opts the user out: the next run cancels the user’s waiting orders and revokes their installed certificates, here and at the CA.

mpki user delete ADDRESS

Delete a user. The next run revokes their certificates. Their next message does not create them again; only mpki user add brings them back. The row is kept, marked deleted.

mpki user import FILE –ldif | –csv [OPTIONS]

Create or update users from a directory export; - reads standard input. There is no LDAP connection: a directory reaches Pepsi as a file, such as the output of ldapsearch -LLL … mail givenName sn.

–ldif reads LDIF content records (RFC 2849) with plain and base64 values, folded lines and comments. The names come from givenName and sn, or, where one of them is missing, from cn, split like a display name. An entry with several mail values gives one user per address. A name from the directory counts as confirmed (source ldap).

–csv reads one address,given name,surname per line. Fields may be double-quoted ("" is a quote), blank lines and lines that start with # are skipped, and a first line whose first field holds no @ is taken as a header. The names count as entered by an administrator (source local).

The import never changes a user’s selection, and it never brings back a user whom an administrator deleted; it reports both. A known user whose name differs, or is not confirmed yet, gets the name from the file, confirmed. Addresses outside the managed domains are reported and skipped. A record without a complete name creates a user whose order waits for one (name-missing).

–domain DOMAIN

Import only the addresses of DOMAIN.

–mail-attribute ATTR, –given-name-attribute ATTR, –surname-attribute ATTR

The LDIF attributes that hold the addresses, the given name and the surname. Defaults mail, givenName and sn.

–prune

Also delete the users of –domain who came from a directory import (source ldap) and whom the file no longer lists, which revokes their certificates. It needs –domain and –ldif. The command lists those users and asks first; –yes skips the question, and with no terminal and no –yes nothing is imported at all.

–dry-run

Print what would change, and change nothing.

–json

Print the plan and the counts as JSON.

The output has one line per address that changes: add, update (with the old name), skip (deleted here, outside the managed domains, or not a mail address) and delete, then the counts.

mpki order list [–domain DOMAIN] [–address ADDRESS] [–open] [–limit N] [–json]

Orders, newest first, at most N (default 50): the id, when it was created, the address, the kind (new, renew or revoke), the purpose (sign, encrypt or both), the state, the reason for a hold, the CA’s order id and the last error. An order is queued (waits to be submitted), held (waits for an administrator or for its cause to go away), submitted (the CA has it), issued (downloaded, being installed), installed or revoked (done), failed (given up, with the reason) or cancelled. –open lists only the orders that are still under way: queued, held, submitted and issued.

mpki order release ORDER-ID

Let a held order go ahead; the next run submits it. This is how an order passes the daily limit (daily-limit) and how it continues after a licence was added to the CA account (no-licence): those two holds wait for an administrator. The holds that the run releases by itself (name-missing, name-unconfirmed, no-credential) come back at once while their cause remains.

mpki order retry ORDER-ID

Try a failed order again at the next run, without waiting a day for the replacement order. An order that the CA has and whose key is still stored is followed at the CA again. Otherwise the order is submitted afresh, as a new order at the CA over a new key; that is the usual case, since a failed order gives up its key. A failed revocation is sent again.

mpki order cancel ORDER-ID

Drop an order that is queued, held, submitted or failed, and discard its key. An order that had reached the CA is cancelled only here, and the command says to cancel it in the CA’s portal as well. While the user is still to have a certificate, the next run creates a new order; to stop for good, opt the user out (mpki user set ADDRESS –select no). An installed certificate is not cancelled but revoked, by the same opt-out.

mpki notices [–domain DOMAIN] [–unread] [–read ID… | –read-all] [–json]

The notices for administrators, newest first (at most 200): the time, the severity and one sentence, marked [unread] until somebody reads it. A notice is written when an order is submitted, installed, held (with the reason and what to do), retried for the third time, failed or revoked, and when a revocation waits for approval at the CA. –read marks the given notices read and –read-all every unread one (of –domain, when it is given); a notice marked read is read for every administrator, including in the console’s Notices page (see pepsi-httpd(1)).

mpki run [–domain DOMAIN] [–json]

One pass over every enabled domain, or over –domain only. This is what pepsi-keys-mpki.timer runs every five minutes. On a host without an enabled domain the pass is one query. A pass has four steps:

  1. Plan. Every user who is to have a certificate and has no current one gets a new order for each purpose; a certificate that expires within the renewal window gets a renew order. An order of the same user and purpose that failed within the last 24 hours holds the next one back, so a failure is tried again once a day. A new order is created held when the name is missing or unconfirmed, or when the daily limit is reached, and a notice says why. A user who is deleted or opts out has their waiting orders cancelled and their installed certificates revoked: here at once, and at the CA by a revoke order. A user who is merely no longer selected (in manual or first-send mode) keeps their certificate until it expires, and it is not renewed.

  2. Release the held orders whose cause has gone: a name that is now complete and confirmed, or a credential that now exists.

  3. Work every order that is due. For a queued order, generate the key, store it wrapped in the order row, then send the request; the order carries pepsi-ORDER-ID as its reference in the CA’s portal. Ask the CA about a submitted order every minute at first, slowing down to once an hour. Download an issued certificate with its chain, check it, and install it; the identities that it supersedes (a self-signed certificate, the one a renewal replaces) are retired as a key rotation retires them, so that mail already encrypted to them still opens. Send the queued revocations.

  4. Mail the notices of the pass to each domain’s notify address.

A failure of one order does not stop the pass. A temporary failure (the network, a timeout, a server error at the CA) of an order that the CA does not have yet is retried after 5 minutes, doubling to 6 hours, with a notice at the third attempt; the order fails after 40 attempts, about a week. A refusal by the CA fails such an order at once, and an account without a free licence for the address holds it (no-licence). A failed order is replaced by a new one a day later, or tried again at the next run after mpki order retry. An order that the CA already has is never given up on: a failed status query or download, a refused one included (after a credential was replaced, for example), is retried at most 40 minutes apart, and the order keeps its key. Only the order’s own status at the CA (rejected, cancelled, expired or revoked) fails it. The command prints a summary of the pass and exits with status 1 when an error occurred. Passes never overlap: a run that starts while another is under way prints that and does nothing.

95.1.50.1.5. Key-server configuration

Web Key Directory publication needs no configuration: it follows each identity’s published flag and is served by pepsi-httpd(1). Key-server publication does, because it cannot be undone, and its options live in [pepsi-keys]:

VKS_PUBLISH (default no)

Whether identities created or imported by hand start with their key-server upload requested, so that identity publish –retry uploads them and keeps retrying until the address is verified. An upload can be revoked but never withdrawn, so the default stays an operator’s decision. It does not gate the retry job, and it never applies to automatically created or registered keys; see Key-server uploads are requested per identity. With it off, identity publish –vks (or a user’s own request through the web console or by e-mail) remains available.

VKS_SERVER (default: the first [pepsi-keydiscovery] VKS_SERVERS entry)

Where uploads go; https:// only. One server, not a list: publishing the same key to several multiplies an irreversible act, and each then has to be kept up to date with revocations.

VKS_MAX_ATTEMPTS (default 5), VKS_RETRY_INTERVAL (default 6 h), VKS_BATCH (default 50)

How hard, how often and how many at a time identity publish –retry tries. Note that durations reject calendar units: 6 h parses, 1 d does not.

95.1.50.1.6. Managed-PKI configuration

The per-domain settings are in the database (mpki domain set). What the mpki commands read from the configuration file is in [pepsi-mpki], described in pepsi.conf(5); every option has a default:

CREDENTIAL_DIR (default: secrets.d beside the configuration file)

Where the mpki-DOMAIN.secret files are.

TIMEOUT (default 60 s)

The deadline of one request to the CA.

NOTIFY_STAGE (default: none)

The stage at which notice mail enters the pipeline, for example the stage that DKIM-signs outbound mail. Without it no notice is mailed.

NOTIFY_FROM (default postmaster@DOMAIN)

The From: of a notice mail.

95.1.50.1.7. 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. Rejected for unprivileged callers when this program is installed setuid: the configuration names the database connection, every ${…}-expanded path and the key-encryption key itself.

-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.50.1.8. Exit Status

0

Successful completion. A destructive command that was declined at its confirmation prompt also exits 0, having changed nothing.

1

An error occurred: a malformed configuration file, an inadmissible option combination, an address that resolves to another user’s account, key material that cannot be parsed, a key-encryption key that is missing or does not open a row, or a failed database connection or query. The reason is written to the log.

78

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

95.1.50.1.9. Files

When –config is not given, the first existing file from the following list is used:

  • $XDG_CONFIG_HOME/pepsi.conf

  • $HOME/.config/pepsi.conf

  • /etc/pepsi/pepsi.conf

  • /etc/pepsi.conf

secrets.d/pepsi-crypto.secret

The key-encryption key, beside the configuration file and pulled into the [pepsi-crypto] section with an @inline-secret@ directive. It is kept out of the world-readable configuration because it is the one secret that opens every stored private key; pepsi-setup(1) gives it mode 0640 and hands it to the pepsi-crypto account on every run. Back it up separately — see the Key management chapter of the manual for what its loss costs.

/run/pepsi-vmgenid-changed

Touched by Pepsi’s udev rule when the virtual machine’s generation ID changes (a clone, or a restore from a snapshot). identity generate, otp enroll and wrap rotate only look at its time: within ten minutes of a change they log a warning naming what they generate, since a process that ran before the snapshot may repeat random numbers. See the Operations chapter of the manual, Cloned and restored virtual machines.

secrets.d/mpki-DOMAIN.secret

The API key of a managed domain’s CA account, one file per domain, in [pepsi-mpki] CREDENTIAL_DIR. The first line that is neither empty nor a # comment is the key. mpki credential set writes it with mode 0640 and group pepsi-crypto; only pepsi-keys reads it, and the key goes nowhere but to the CA. Whoever holds the file can order certificates that the organisation pays for, and revoke them. Back it up with the rest of secrets.d.

No other file is read or written: all key material lives in the database.

95.1.50.1.10. Examples

Find the served addresses whose encryption is decided by a key that somebody else supplied, and make a confirmed one the user’s own (an MUA key: no –private):

pepsi-keys -c /etc/pepsi/pepsi.conf peer unclaimed
pepsi-keys -c /etc/pepsi/pepsi.conf peer show bob@example.org
gpg --export bob@example.org > bob.pgp    # the key bob confirmed to you
pepsi-keys -c /etc/pepsi/pepsi.conf identity import bob@example.org \
    --protocol openpgp --purpose both --public bob.pgp

Generate an OpenPGP identity and check that GnuPG accepts the public half:

pepsi-keys -c /etc/pepsi/pepsi.conf identity generate alice@example.org \
    --protocol openpgp --name 'Alice Example'
pepsi-keys -c /etc/pepsi/pepsi.conf identity list --address alice@example.org
pepsi-keys -c /etc/pepsi/pepsi.conf identity export 1 | gpg --import

Generate the S/MIME pair, printing a certificate request over each key for a real CA:

pepsi-keys -c /etc/pepsi/pepsi.conf identity generate alice@example.org \
    --protocol smime --csr

Install the certificate that CA issued, over the key that is already in the store:

pepsi-keys -c /etc/pepsi/pepsi.conf identity import alice@example.org \
    --protocol smime --purpose sign --public /tmp/alice-sign.pem --primary

Publish the address in DNS (signed zone only):

pepsi-keys -c /etc/pepsi/pepsi.conf dns alice@example.org >> example.org.zone

Withdraw a compromised signing key, then confirm the private half is gone:

pepsi-keys -c /etc/pepsi/pepsi.conf identity revoke 1 --reason 'laptop stolen'
pepsi-keys -c /etc/pepsi/pepsi.conf identity show 1

Trust a correspondent’s key by hand and pin it against later discovery:

pepsi-keys -c /etc/pepsi/pepsi.conf peer import bob@example.com \
    --protocol openpgp --file bob.pgp --pin

Look one correspondent up with every enabled method and store the result:

pepsi-keys -c /etc/pepsi/pepsi.conf peer refresh --address bob@example.com

Keep the cache honest from a periodic timer: re-validate what is due, then drop what has aged out:

pepsi-keys -c /etc/pepsi/pepsi.conf peer refresh
pepsi-keys -c /etc/pepsi/pepsi.conf peer prune
pepsi-keys -c /etc/pepsi/pepsi.conf peer screen

See how current the known-compromised-key list is, and take one source list out of service (should its entries prove wrong):

pepsi-keys -c /etc/pepsi/pepsi.conf blocklist status
pepsi-keys -c /etc/pepsi/pepsi.conf blocklist dismiss --list forti

Add an S/MIME trust anchor and see what is trusted:

pepsi-keys -c /etc/pepsi/pepsi.conf ca add /etc/ssl/certs/our-ca.pem --label 'Our CA'
pepsi-keys -c /etc/pepsi/pepsi.conf ca list

Trust a partner’s CA for the partner’s own domain only:

pepsi-keys -c /etc/pepsi/pepsi.conf ca add partner-ca.pem --label Partner --domain partner.example
pepsi-keys -c /etc/pepsi/pepsi.conf ca scope 2 --domain partner.example --domain partner.example.net

See what the forward-secrecy profile would rotate and destroy today:

pepsi-keys -c /etc/pepsi/pepsi.conf identity rotate-due --dry-run

Rotate the key-encryption key, looking first:

pepsi-keys -c /etc/pepsi/pepsi.conf wrap rotate --dry-run
pepsi-keys -c /etc/pepsi/pepsi.conf wrap rotate

Expire everything that is past its validity (from a periodic timer):

pepsi-keys -c /etc/pepsi/pepsi.conf identity retire

Publish one key to the key server, then check it arrived:

pepsi-keys -c /etc/pepsi/pepsi.conf identity publish 1 --vks
pepsi-keys -c /etc/pepsi/pepsi.conf identity show 1

Drive every pending key-server verification to completion (what the hourly timer runs):

pepsi-keys -c /etc/pepsi/pepsi.conf identity publish --retry

Stop publishing a key, and tell the world the uploaded one is dead:

pepsi-keys -c /etc/pepsi/pepsi.conf identity unpublish 1
pepsi-keys -c /etc/pepsi/pepsi.conf identity revoke 1 --upload \
    --reason 'address closed'

Set up a managed PKI for a domain: configure it, store the CA account’s API key from standard input, and ask the CA whether it can order:

pepsi-keys -c /etc/pepsi/pepsi.conf mpki domain set example.org \
    --enable --notify it@example.org
pepsi-keys -c /etc/pepsi/pepsi.conf mpki credential set example.org < api-key.txt
pepsi-keys -c /etc/pepsi/pepsi.conf mpki domain check example.org

Import the users from the directory, looking first:

ldapsearch -LLL -H ldap://ldap.example.org -b ou=people,dc=example,dc=org \
    '(mail=*@example.org)' mail givenName sn > people.ldif
pepsi-keys -c /etc/pepsi/pepsi.conf mpki user import people.ldif --ldif \
    --domain example.org --dry-run
pepsi-keys -c /etc/pepsi/pepsi.conf mpki user import people.ldif --ldif \
    --domain example.org

Approve a name that was taken from a user’s first message, then run a pass instead of waiting for the timer:

pepsi-keys -c /etc/pepsi/pepsi.conf mpki user list --domain example.org
pepsi-keys -c /etc/pepsi/pepsi.conf mpki user set alice@example.org --confirm
pepsi-keys -c /etc/pepsi/pepsi.conf mpki run --domain example.org

Correct a name and approve it in one step, or decline a role address that registered itself:

pepsi-keys -c /etc/pepsi/pepsi.conf mpki user set bob@example.org \
    --given-name Robert --surname Example
pepsi-keys -c /etc/pepsi/pepsi.conf mpki user set noreply@example.org --select no

See what waits, and let an order held by the daily limit go ahead:

pepsi-keys -c /etc/pepsi/pepsi.conf mpki notices --unread
pepsi-keys -c /etc/pepsi/pepsi.conf mpki order list --open
pepsi-keys -c /etc/pepsi/pepsi.conf mpki order release 17

95.1.50.1.11. See Also

pepsi-keydisc(1), pepsi-httpd(1), pepsi-stage-vks-confirm(1), pepsi-setup(1), pepsi-config(1), pepsi-whitelist(1), pepsi-settings(1), pepsi.conf(5), pepsi.state(7)

The manual’s Security chapter states the mechanisms this program relies on (The private-key custody boundary, A second factor for key management, What an S/MIME trust anchor vouches for, Which S/MIME container a correspondent gets, A correspondent’s key changing, Certificates from a commercial CA); its Threat model chapter states what they promise (End-to-end encryption: two custody modes, Keys of correspondents, Somebody holding a copy of the database).

95.1.50.1.12. Bugs

Report bugs to the Pepsi issue tracker.