13. Key management

End-to-end cryptography — OpenPGP and S/MIME — needs somewhere to keep keys. Pepsi keeps them in the database, in three tables that together are the key store, and manages them with one program, pepsi-keys. This chapter covers what is stored, how the private half is protected, who may reach it, and the two decisions that most often surprise people: why signing and encryption material are separate, and why an address that only ever receives mail ends up with no key at all.

The key store is not the DKIM/ARC key store. Those are per-domain keys, held by the signing daemon pepsi-dkim as files of its own account, and the signing stages ask it for signatures. What follows is about per-address end-to-end material, which has an entirely different lifecycle.

13.1. Three kinds of material

pepsi.crypto_identity — our own addresses

The key pairs of the addresses this deployment serves, private half included, wrapped at rest. This is what signs outbound mail and decrypts inbound mail. Each row records the address, the protocol (openpgp or smime), what the material is capable of, its algorithm and fingerprint, the public material itself, the wrapped private material and the id of the key that wrapped it, plus the lifecycle columns (status, is_primary, published, expires_at, revoked_at, private_purged_at, vks_wanted). It also holds the users’ own keys – public-only rows whose private half lives in their mail client (custody = client; see Two keys per user).

pepsi.peer_key — other people’s addresses

Remote correspondents’ public keys and certificates, cached however they were obtained. This is what encrypts outbound mail and verifies inbound signatures. Each row carries the source it came from, whether the lookup that produced it was DNSSEC-validated, the last validity verdict reached about it, and a cache deadline.

pepsi.ca_trust — trust anchors

The CA certificates an inbound S/MIME chain must reach for its signature to count as trusted. Pepsi ships no default anchor set: a signature that chains to a CA nobody chose is reported untrusted rather than bad, so an empty store degrades to “we cannot vouch for this” instead of to “this is forged”, and an operator who adds an anchor is making a decision rather than inheriting one. A certificate collected from mail or discovery never becomes an anchor by itself (Keys and certificates imported or trusted without verification).

Revocation of a chain is checked against certificate revocation lists: pepsi-keydisc fetches the CRLs that cached S/MIME peer certificates name in their cRLDistributionPoints (http:// and https:// only, [pepsi-keydiscovery] CRL_FETCH and CRL_MAX_BYTES) into pepsi.crl_cache, refetching at each list’s nextUpdate and at least daily, and only that service’s role writes the table. A list counts only if the issuer’s key signed it, it is current and its scope covers the certificate; a listed certificate makes the signature invalid (revoked). A list also retires the cached certificates that it lists when an enabled anchor of the issuer’s name signed it, or a fetched intermediate (below) that path-validates to one; those certificates are then no key for the encrypt stage. Checking soft-fails: an unobtainable, stale or unusable list leaves revocation not checked. There is no OCSP, so a CA learns at most daily that this host holds some certificate it issued, never which one or when it was used.

When [pepsi-keydiscovery] CA_ISSUERS_FETCH is on, a chain that the signer sent without its intermediates is completed from pepsi.ca_issuer_cache, which holds the CA certificates that pepsi-keydisc fetched from the certificates’ caIssuers pointers. Such a certificate is never an anchor, and the CRLs it names are fetched like a peer certificate’s. An expired peer certificate is no key: the encrypt stage takes the recipient’s ON_NO_KEY route rather than seal to it.

13.2. Custody: how a private key is stored

The private half of an identity lives in the database, but never in the clear. It is sealed with AES-256-GCM under a key-encryption key (KEK) derived from a secret that lives only in the filesystem, in a secrets.d fragment named by [pepsi-crypto] KEY_WRAP_SECRET.

The property this buys:

The database alone never yields a private key. A stolen dump, a replica, a backup tape or an SQL-injection foothold in an unrelated component produces ciphertext and nothing else. The key that opens it is a second, differently guarded artefact and is never a database value.

The stored blob is a version octet, a 96-bit random nonce and the AES-GCM ciphertext. The version octet lets constructions coexist; an unrecognised version is an error, never a silent fallback.

The additional authenticated data binds the ciphertext to the row it belongs to — the address, the protocol, the purpose and the key’s fingerprint, length-prefixed. Without that binding, an attacker with write access to the table but not the KEK could move Alice’s wrapped signing key into Bob’s row and have the pipeline sign Bob’s mail with it. The fingerprint matters because an address keeps its retired and revoked identities beside the active one, all with the same address, protocol and purpose: without it, a retired key’s blob could be put back into its successor’s row. The AAD is authenticated but not stored, so such a blob simply fails to open in the wrong place, exactly as a tampered one does.

Version 2 is the format with the fingerprint in the AAD, and every new wrap writes it. Version 1, whose AAD stops at the purpose, still opens, and pepsi-keys wrap rotate re-wraps every version-1 blob into version 2 even when the key-encryption key is unchanged, so one run after upgrading closes the gap. (The second-factor secrets have no fingerprint and stay version 1; their address and their own protocol label already name a single row.) Because the whole private key, public parameters included, is inside the authenticated ciphertext, a mauled or overwritten key never reaches a private-key operation (Unauthenticated private-key encryption lets the storage holder maul keys, Unauthenticated private-key encryption lets the storage holder maul keys).

The KEK itself is derived from the configured secret with HMAC-SHA-256 under a fixed label, mixing in the key id. Two consequences follow: the secret may be any string (a passphrase, base64, hex — the derivation does not care), and every distinct KEY_WRAP_KEY_ID yields an independent 256-bit key. There is deliberately no start-up passphrase: unattended restart and socket activation have to keep working.

Warning

pepsi-setup refuses a KEY_WRAP_SECRET shorter than 16 characters. It is the single key that opens every stored private key in the deployment; generate it from a real entropy source rather than typing one.

13.3. The privilege boundary

Wrapping is one half of the custody model. The other half is a database privilege boundary, provisioned by pepsi-setup and re-asserted on every pepsi-setup run:

  • a login role pepsi-crypto is created with the ordinary pipeline access (SELECT/INSERT/UPDATE/DELETE across the schema, sequences, functions) plus the crypto_identity.private_wrapped column – the only role granted it, apart from the schema owner pepsi-owner, which can read it by ownership but cannot read the key-encryption key, so nothing else holds both;

  • pepsi (the dispatcher and every stage worker) and pepsi-httpd have their table-level grant on crypto_identity revoked and replaced with a column-level SELECT of every column except private_wrapped, no INSERT, and UPDATE of only the columns their code writes: the is_primary, published and vks_wanted flags, plus, for pepsi, the key-server progress columns that pepsi-stage-vks-confirm records; pepsi-ingress and pepsi-telemetry have no access to the table at all (see The privilege split).

So an attacker who compromises an unrelated stage (relay, bounce, aliases) gets the public half of every identity and nothing more, even with full database access under that role. They cannot replace that public half or its fingerprint either: those are what the Web Key Directory, Autocrypt: and the DNS records hand out as ours. pepsi-setup checks the narrowed grant against PostgreSQL and refuses to finish if any of those roles can still INSERT or rewrite another column. The column list is read back from information_schema rather than hard-coded, so a column that a later change adds is covered automatically, and the grant cannot silently fall out of step with the schema.

DELETE has no column granularity in PostgreSQL and stays whole: a stage that can delete an identity row can deny service, but it still cannot read a key.

Important

PostgreSQL peer authentication keys off the effective uid, not the gid. A setgid bit grants group membership — which is what the mode of the KEK fragment tests — but not a database identity. A program that must be the pepsi-crypto role has to be that account: run as it, or setuid to it. pepsi-keys does exactly that, assuming the identity for the duration of each database call and giving it back afterwards, in the same way that pepsi-whitelist does for its own account.

Reaching a private key therefore takes both things: the database role and the key-encryption key. Neither alone is enough, and they are guarded by different mechanisms — a PostgreSQL grant and a file mode. This limits who can reach the store, but the two crypto stages hold both while they parse hostile input, so a flaw there still exposes every server-held key (Mail appliances store secrets world-readable or unprotected).

13.3.1. Who may manage what

An identity is keyed on the lower-cased address, and the passwd login that owns that address is recorded alongside it when the locality rules ([pepsi-crypto] LOCAL_DOMAINS, RECIPIENT_DELIMITER, TARGETS, named and defaulted like local delivery’s options) resolve one. They are the only options that decide it: pepsi-keys, the setup applier and the encrypt stage’s automatic creation and key registration all read [pepsi-crypto], so an identity has the same owner whichever of them made it. That column is the access rule: an unprivileged caller of pepsi-keys may see and change only identities whose login is their own, taken from the real uid’s passwd entry. An identity with no owning account — a role address, a hosted domain, an Exchange-fronted deployment — belongs to nobody in particular and is operator-only; treating “unowned” as “everybody’s” would make every role address writable by every local user.

Peer keys and trust anchors have no per-user namespace at all. A peer key is somebody else’s key, cached for the whole deployment, and the trust store is policy; both are operator-only, listing included.

pepsi-keys ships without a setuid bit, unlike pepsi-whitelist. One binary able to open every private key in a deployment is a far larger prize than a single whitelist table, so by default only the operator runs it. A site that wants users to manage their own identities installs it setuid pepsi-crypto, and the ownership rule above takes effect as soon as it is, so that is a site decision and not a code change. (Without the bit every caller connects as themselves and PostgreSQL’s grants are the only authority; see pepsi-keys(1).)

13.4. What custody protects against

The threat model states the claims per custody mode (Gateway custody (custody = local, the MTA key), Client custody (custody = client, the MUA key)); this is how they map onto the key store.

Somebody who has…

An MTA key (custody = local)

An MUA key (custody = client)

a copy of the database or a backup

Wrapped ciphertext only; the KEK is not in it.

A public key; there is no private half anywhere on the server.

the secrets.d KEK fragment alone

Nothing: the blobs are in the database.

Nothing.

code execution in an ordinary stage

Not the key. But the use of it: rewriting a queued submission’s From: gets a message signed as that user (A compromised component).

Nothing it can sign or open. It can still read mail that arrived in cleartext before it was encrypted to the user.

code execution in pepsi-stage-encrypt/-decrypt

Every MTA key, in the clear, and the ability to carry them away. Rotate the KEK and re-key after such a compromise.

Nothing: mail encrypted to an MUA key passes through unopened, and a copy already filed re-sealed to it (pepsi-stage-reencrypt) cannot be opened either.

write access to crypto_identity without the KEK

Cannot move a wrapped key to another address: the ciphertext is bound to its row. Can delete rows (denial of service).

Can replace the public key, redirecting future mail to a key of the attacker’s choosing — the same power a malicious operator has. Only a correspondent who verified the fingerprint out of band is protected.

Two further attacks concern which key is used rather than who holds it:

13.5. Signing and encryption are separate

The store splits signing material from encryption material wherever the protocol allows it. The reason is an asymmetry:

Pepsi delivers plaintext to the mailbox. A private decryption key is therefore 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 whatever: no honest process ever re-signs old mail. Keeping it is pure forgery liability.

So retirement — at expiry, and identically at revocation — does two different things:

  • a signing row’s private half is destroyed, leaving the public half so signatures made while the key was valid can still be verified;

  • an encryption row’s private half is retained, so in-flight and archived ciphertext stays readable.

private_purged_at records when material was dropped, which keeps “deliberately destroyed” distinguishable from “never held”.

For OpenPGP the split is intrinsic and free: a transferable key is a sign-capable primary with an encryption subkey, so one row of purpose both represents it. For S/MIME it means two certificates, one with digitalSignature and one with keyEncipherment/keyAgreement. Both the self-signed and the certificate-request paths handle the pair naturally — identity generate creates both, and --csr emits a request over each. Separate S/MIME keys also mean a PKCS#1 v1.5 decryption oracle on the encryption key cannot be used to forge signatures (RSA key reuse across encryption and signature schemes enables cross-attacks).

13.5.1. Single-certificate S/MIME, and what it costs

Two certificates per identity is a real expense when certificates are bought from a CA per address. [pepsi] CRYPTO_SMIME_SHARED_KEY = yes therefore issues one certificate carrying both key usages instead. It is an administrator-only INI option — a security/cost trade, not a per-user preference, and structurally out of reach of the per-address override layer.

The trade:

  • the forgery-liability benefit is given up, and so is the separation that keeps a decryption oracle from forging signatures (RSA key reuse across encryption and signature schemes enables cross-attacks). A shared certificate’s private half follows the decryption rule at retirement, because destroying it would take the ability to decrypt with it; it leaves the store only through an explicit pepsi-keys identity forget-private;

  • revocation becomes all-or-nothing. Revoking a compromised signing key also ends the ability to receive new encrypted mail at that certificate.

Shared mode is RSA only. pepsi-setup refuses it together with an elliptic-curve CRYPTO_SMIME_ALGORITHM, because one EC key that does both ECDSA and ECDH is cross-algorithm key reuse, and several S/MIME clients reject such a certificate outright. Since the default algorithm is P-256, turning shared mode on means also setting CRYPTO_SMIME_ALGORITHM = rsa.

13.5.2. Capability, never shape

CRYPTO_SMIME_SHARED_KEY decides only what newly created identities look like. Toggling it never rewrites, re-keys or invalidates anything already issued, so at any moment the table may legitimately hold split identities, shared identities, and both for the same address — an old shared certificate still valid while new split ones are in use.

Every lookup therefore resolves by capability:

signing      ->  purpose IN ('sign',    'both')
encryption   ->  purpose IN ('encrypt', 'both')

and there is deliberately no query that returns “the identity” for an address. Code that assumed there were exactly two rows, or exactly one, would become a bug the moment an operator flipped the switch. When reading pepsi-keys identity list output, read the PURPOSE column the same way.

13.6. Creating identities

There are five ways material enters crypto_identity: the four below, and a certificate that a commercial CA issues through the managed PKI (Certificates from a commercial CA: the managed PKI).

Generation. pepsi-keys identity generate creates the key pair here. OpenPGP defaults to Ed25519 ([pepsi] CRYPTO_OPENPGP_ALGORITHM), which is instantaneous to generate; RSA is available at 2048, 3072 or 4096 bits. S/MIME defaults to NIST P-256 (CRYPTO_SMIME_ALGORITHM), so that mail to the identity arrives as ECDH key agreement rather than RSA key transport (Security model); P-384 and RSA at CRYPTO_GENERATE_RSA_BITS are available, and every S/MIME key, elliptic-curve or RSA, is generated by AWS-LC, in constant time. The option shapes new identities only; an RSA identity generated earlier keeps working, since lookups resolve by capability. CRYPTO_GENERATE_RSA_BITS accepts only 2048 (the default), 3072, 4096 and 8192, the sizes AWS-LC generates, and any other value fails configuration parsing; 8192 is for S/MIME only, since OpenPGP generation stops at 4096 (see The private-key custody boundary for where each private-key operation runs). Each generated certificate is self-signed, which is enough to start immediately, and --csr additionally emits a PKCS#10 request over the same key so a real CA can issue a replacement without re-keying.

Pepsi does not run a certificate authority of its own: that would make it hold a key far more valuable than any single user’s, with its own custody and revocation problem.

Import. pepsi-keys identity import stores material generated elsewhere — the certificate a CA issued over an existing key, or a key pair a user already had. The declared --purpose is what every later lookup matches on, so it must describe what the material can actually do. Carrying the request to the CA and the certificate back is a manual round trip for each identity; the managed PKI below does it for every user of a domain.

Automatic creation. [pepsi-crypto] AUTO_CREATE_IDENTITY (on by default) permits an identity to be generated for a served address without an operator asking. When it fires is the encrypt stage’s ENABLE_PEP:

  • Eagerly, under ENABLE_PEP = yes (the default): on a sender’s first locally submitted message, whether or not it asked for protection. See pEp-style automatic keys below, which also covers what that costs.

  • Lazily, under ENABLE_PEP = no: the first time a local sender explicitly asks for protection — a marker in the subject, or the equivalent header from a mail client add-in, whether it asks for a signature or only for encryption — and never merely because an address appeared in an envelope. A user who never uses the feature therefore never has key material and is never exposed by it. SIGN = always counts as such a request on every message, so under it a sender gets a key on their first submission as under the preset.

Either way, automatic creation happens only for an address at a [pepsi-ingress] ACCEPTED_DOMAINS domain that has no identity row of any kind – not a revoked one, and not the user’s own key registered from their mail client. If somebody revoked a key, Pepsi does not quietly mint a replacement; and a user who brought their own key does not get a second one behind their back. Creation on request (pepsi-keys identity generate, the web console, the e-mail generate command) is not guarded this way. Rows created automatically are marked auto_created.

Warning

The one surprising consequence. The trigger is on the outbound path. An address that only ever receives mail therefore stays keyless, gets no Web Key Directory entry and publishes no DNS record — so outsiders have nothing to encrypt to it with, and never will, however long they wait.

An operator who wants inbound coverage must pre-provision those addresses:

pepsi-keys identity generate role@example.org --protocol openpgp

Creation for every address ever seen would mint and publish key material for people who never sent anything through this server.

Registration of the user’s own key. A public key with no private half – pepsi-keys identity import without --private, a key registered through the web console or by e-mail, or one learnt from the Autocrypt: header of the user’s own submitted mail – is stored as the user’s MUA key; see Two keys per user.

13.7. Certificates from a commercial CA: the managed PKI

A self-signed certificate encrypts as well as a CA-issued one, but a recipient’s S/MIME client cannot tell who stands behind it: most clients show a warning for it, and some refuse to encrypt to it. A managed PKI gives every user of a domain a certificate from a commercial certificate authority without anybody carrying requests and certificates by hand: Pepsi orders the certificate when the user starts sending mail, installs it, renews it before it expires and revokes it when the user leaves. The CA bills the organisation that owns the CA account.

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, which the CA has validated, sponsors the person: it vouches to the CA that this person holds this address. The CA also checks that the address’s domain is validated in the account. That is why a domain takes part only when an administrator switches it on, and why the name that a certificate carries is one that somebody vouches for (Whose name a certificate carries).

The managed PKI is configured per domain, and each domain has its own CA account, with its own API key and its own bill. It is off for every domain until pepsi-keys mpki domain set DOMAIN --enable. The commands are in pepsi-keys(1) (Managed-PKI commands), the mechanisms in Certificates from a commercial CA.

13.7.1. How a certificate is ordered

  1. A user exists. Users come from three places: the encrypt stage registers the author of a locally submitted message at a managed domain the first time it sees them (Whose name a certificate carries); an administrator adds them (mpki user add); or a directory export is imported (mpki user import --ldif, or --csv).

  2. The user is wanted. The domain’s enrolment mode and the user’s selection decide that (Who gets a certificate).

  3. An order is planned. pepsi-keys mpki run, which pepsi-keys-mpki.timer starts every five minutes, creates an order for every wanted user without a current certificate: one order for a certificate that both signs and decrypts, or two with separate signing and encryption certificates (--certificates two). An order that cannot go to the CA yet is held, and an administrator is told why (Held orders).

  4. The key is made here. Before the request leaves, Pepsi generates the key (RSA 3072 by default, --key-algorithm), wraps it under the key-encryption key and stores it in the order row. Only the certificate request goes to the CA, together with the address and the person’s name. No private key leaves the host, and there is no copy of one at the CA.

  5. The CA issues. Pepsi asks about the order every minute at first, slowing down to once an hour, and downloads the certificate with its intermediate CA certificates (the root is left out: a recipient has to trust it already).

  6. The certificate is checked and installed. It must name the address in its subject alternative name, allow e-mail protection, carry the key usages of its purpose, not have expired, and be over the order’s own key. A certificate that fails is not installed, and the order fails with the reason. One that passes becomes the address’s primary S/MIME identity (custody = local), published, with its intermediates stored beside it (crypto_identity_chain). Every signature that it makes carries them, so a recipient can build the path to the CA’s root. A certificate installed by hand (identity import, or the console’s Install the issued certificate) has no stored chain.

  7. What it replaces is retired. The address’s other active S/MIME identities of an overlapping purpose (a self-signed certificate, or the certificate that a renewal replaces) are retired the way a scheduled key rotation retires them: a signing key’s private half is destroyed, and a decryption key keeps opening mail that was encrypted to it before. With two certificates, one half never retires the other. Publish the new SMIMEA records if the domain uses them (pepsi-keys dns ADDRESS).

The user’s mail does not wait for any of this. A message goes out at once as it would without the managed PKI, unsigned or signed with the key that the server already holds for the user, and the certificate is used from the first message after it is installed.

Note

The certificate is used where the encrypt stage signs in S/MIME. A message encrypted to an S/MIME recipient is signed with it. Whether cleartext mail is signed at all, and in which format, is decided by [stage-encrypt] SIGN and PREFER. Under ENABLE_PEP (the default), SIGN is encrypted-only, so cleartext mail is signed only when the sender asks, and a user who also has an OpenPGP key gets OpenPGP signatures on cleartext mail, since PREFER defaults to openpgp. For the organisation’s certificate on every message, set SIGN = opportunistic and PREFER = smime (pepsi-stage-encrypt).

13.7.2. Who gets a certificate

Each domain has one of three enrolment modes (--enrolment):

first-send (the default)

A user gets a certificate once they have sent mail through Pepsi. A user imported from the directory therefore costs nothing until they use the address.

all

Every user in the list gets one, whether they have sent mail or not.

manual

Only the users that an administrator selects get one.

Each user also has a selection that overrides the mode: default lets the mode decide, yes always enrols the user (in manual mode, this is how an administrator selects them), and no opts the user out, in every mode. Users cannot opt out themselves; an administrator sets --select no for them.

13.7.3. Whose name a certificate carries

A user’s name comes from one of three sources, and the source decides whether anybody has vouched for it:

header

The display name of the first message that the user sent, split into a given name and a surname. Pepsi reads Surname, Given as written; otherwise the last word is the surname, together with the lower-case particles before it (Ludwig van Beethoven). Titles at the front (Dr., Prof., Mr and the like) and remarks in parentheses are dropped. A single word, an address or no display name at all gives no name. Only a locally submitted message counts (state.local_origin: ingress accepted it from an authenticated or trusted submitter), so no outsider can create a user. But the display name is whatever the sender typed.

ldap

A directory import (mpki user import --ldif): givenName and sn, or cn split like a display name where one of them is missing.

local

Entered by an administrator, with mpki user add, mpki user set or a CSV import.

A name from a directory or from an administrator counts as confirmed. A name from a header does not, because the organisation vouches for the name that the certificate carries, and a user could otherwise have it sponsor Erika Mustermann by typing that name into their mail program. So under the default --header-names approve an order for such a name waits (name-unconfirmed) until an administrator approves it (mpki user set ADDRESS --confirm) or corrects it (a new --given-name or --surname confirms the name too). --header-names trust orders at once; it is meant for a domain where every sender’s display name is set by an administrator.

A program that sends as a role address of the domain from a trusted network registers that address too, with whatever name its display name splits into (Example Shop <noreply@example.org> gives Example Shop). Under approve nothing is ordered for it; decline it with mpki user set ADDRESS --select no, or delete it, so that its next message does not bring it back either.

Names are stored trimmed, without control characters, and at most 64 characters long, the X.520 limit for a given name or a surname. A certificate that is already installed keeps the name it was issued with until it is renewed.

13.7.4. Held orders

A held order waits for one of five things. Three of them the next run releases by itself once the cause has gone; the other two wait for an administrator’s mpki order release:

Reason

Why the order waits

What releases it

name-unconfirmed

The name came from a header and the domain does not trust header names.

mpki user set ADDRESS --confirm, or a corrected name.

name-missing

The user has no given name or no surname.

Entering both (mpki user set, a directory import).

no-credential

The domain has no CA credential file.

mpki credential set DOMAIN.

daily-limit

The domain’s new enrolments of the last 24 hours reached --daily-limit (20 by default).

mpki order release ID, by an administrator.

no-licence

The CA account has no free licence for the address (insufficient_subscription).

Adding a licence in the CA’s portal, then mpki order release ID.

The daily limit is a limit on spending: the organisation pays for every certificate, and a mistake (an import of the wrong file, --enrolment all on a large domain, a script that sends as many addresses) should cost at most a day’s worth before a person looks at it. It counts new enrolments only; a renewal is never held by it. Pepsi never buys a licence or names a payment method: on an account under a CertCentral subscription, an order consumes a licence that the account already has, and an order beyond them is refused by the CA and held here.

13.7.5. Renewal

A certificate is renewed --renew-days days (90 by default) before it expires: the run orders a replacement over a new key, under the user’s current name, and installs it as above, which retires the old certificate. A renewal waits for a confirmed name like a new order, but not for the daily limit. A user who is no longer wanted (in manual or first-send mode) keeps the certificate they have until it expires, and it is not renewed.

13.7.6. One certificate or two

--certificates one (the default) orders one certificate for signing and encryption, which needs an RSA key; two orders a signing and an encryption certificate, as two orders, and works with every key algorithm. The trade-off is the one of Single-certificate S/MIME, and what it costs: one certificate gives up the separation between the signing and the decryption key, and two cost two orders.

13.7.7. Leaving: revocation

When a user is deleted (mpki user delete, or a directory import with --prune that no longer lists them) or opts out (--select no), the next run cancels their waiting orders and revokes every installed certificate in two places. Pepsi retires the identity at once, as superseded, so it no longer signs and is no longer served, but its private key is kept and mail encrypted to it still opens (under the forward-secrecy profile it is destroyed after RETIRED_PRIVATE_GRACE_DAYS, The forward-secrecy profile). The CA is asked to revoke the certificate with the reason affiliationChanged; where the account requires an approval for revocations, the order waits until somebody approves it in the CA’s portal, and a notice says so. A revocation does not free the address’s subscription licence: remove the address from the subscription in the portal for that. A deleted user’s next message does not create them again; mpki user add does.

While a domain is disabled, nothing at all happens for it: no order, no renewal and no revocation. A user deleted meanwhile keeps a working certificate until the domain is enabled again, and is revoked then.

13.7.8. Notices

Every step that an administrator may want to know about writes a notice: an order submitted, installed, held (with the reason and the command that releases it), retried for the third time, failed, or revoked, and a revocation that waits for approval at the CA. pepsi-keys mpki notices lists them, and the console shows the same notices, with a bell in its page header that counts the unread ones (Managed certificates). With a notify address (--notify) and [pepsi-mpki] NOTIFY_STAGE, each run also mails that domain’s new notices as one message, at most 100 to a message.

13.7.9. When something goes wrong

A run takes an advisory lock, so two runs never overlap. A failure of one order does not stop the others. A temporary failure of an order that the CA does not have yet is retried with a growing delay and gives up after about a week; a refusal by the CA fails it at once, with the CA’s message in mpki order list. A user who is still to have a certificate gets a new order a day after a failed one, so a cause that is not fixed costs one failed order a day; mpki order retry ID tries again sooner. An order that the CA already has is never given up on: Pepsi keeps asking, at most 40 minutes apart, and keeps its key until the CA either issues the certificate or reports the order rejected, cancelled, expired or revoked.

Because the key is stored before the request is sent, a crash at any point loses nothing that the next run cannot finish. The one case a run repeats is an order that the CA accepted while its answer was lost; the second request carries the same reference (pepsi-<order id>), which shows the duplicate in the CA’s portal. The wrapped key of a waiting order is readable only by the pepsi-crypto role, and it is deleted from the order row once the certificate is installed, or the order fails or is cancelled.

13.7.10. Setting it up

  1. In the CA’s portal: validate the organisation and the domain, add the product to the account (for a subscription, with enough licences), and create an API key for the account.

  2. On the host:

    pepsi-keys mpki domain set example.org --enable --notify it@example.org
    pepsi-keys mpki credential set example.org < api-key.txt
    pepsi-keys mpki domain check example.org
    

    domain check orders nothing; it says whether the key is accepted, the product is available, which organisation sponsors the certificates, and whether the domain is validated.

  3. Add the users, or let their first messages register them, and confirm the names that came from headers. pepsi-keys mpki user list marks an unconfirmed name with ?. The console’s Certificates pages offer the same settings and user actions to an administrator with keys:write (Managed certificates); the credential and the orders stay on the command line.

  4. Watch the first orders with pepsi-keys mpki order list --open and pepsi-keys mpki notices; pepsi-keys mpki run starts a pass at once instead of waiting for the timer.

13.8. pEp-style automatic keys

[stage-encrypt] ENABLE_PEP (default yes) makes Pepsi behave like the pretty Easy privacy (pEp) project: every local sender gets a key, mail is encrypted whenever a recipient’s key is known or discoverable, and the sender’s public key goes out with every message – in an Autocrypt: header by default, and additionally as an attached file with ATTACH_KEYS_AS_FILES (see Microsoft Exchange as a gateway). It is a preset of defaults for the encrypt stage, not a forcing mode; the full table is in pepsi-stage-encrypt(1). What it changes:

  • Eager key creation. The first locally submitted message from an address at a served domain generates an OpenPGP key for it, on every submission route including trusted relays (MYNETWORKS, client certificates), so a Pepsi deployed as a proxy behind an MTA that authenticates the users works the same. The domain test is what makes a key that we mint useful: mail for that domain comes in through us, so the decrypt stage can open replies encrypted to it. A web application sending as noreply@ a domain we do not receive mail for gets no key.

  • Cleartext is not signed. The default SIGN becomes encrypted-only: a signature lives inside the ciphertext, and cleartext carries the key but no signature, so recipients who do not use cryptography never see a signature.asc. [sign] or X-Pepsi-Sign: yes still signs cleartext.

  • No key-server upload. Automatic keys are served by our own Web Key Directory and advertised by Autocrypt; they are never uploaded to a key server unless their owner asks (Key-server uploads happen on request).

Nothing else changes: discovery still parks the first message to a new correspondent for up to its timeout, the messages are standard PGP/MIME and Autocrypt, and there is no pEp wire format (no X-pEp-Version header, no pEp 2.x wrapping, no trustwords or handshake, no key synchronisation). The preset concerns only mail that users send – cleartext goes out unsigned, and senders get keys they did not ask for; nothing about what anyone can receive depends on it.

Warning

Eager creation widens exposure, and it is the default. Under lazy creation a user who never uses cryptography has no key material on the server. Under ENABLE_PEP, every sender at a served domain has a wrapped private key in the database and a public key in the deployment’s Web Key Directory after their first message. The wrapping and the privilege boundary above still apply, but a compromise of the key-encryption key would then expose the keys of everybody who sends mail, not just of those who asked.

The site vetoes are [pepsi-crypto] AUTO_CREATE_IDENTITY = no (an administrator-only section, so no per-user setting can override it) and [stage-encrypt] ENABLE_PEP = no. A user opts out by registering their own key before sending (an address with any identity never gets an automatic one), or by setting ENABLE_PEP = no in their own pepsi.settings where the operator’s EDITABLE_STAGES allows it (pepsi-stage-edit-settings). pepsi-setup warns when the preset is on but AUTO_CREATE_IDENTITY is off or no KEY_WRAP_SECRET is configured, since the preset then silently does less than its name suggests.

The setup wizard (and the browser setup, which asks the same question) puts this to the operator explicitly, stating the exposure before asking, and writes the answer – yes as well as no – into the encrypt stage’s section of pepsi.conf, where it takes effect; no config.d file sets it.

13.9. Two keys per user

An address may hold two kinds of key:

MTA key (custody = local)

Pepsi holds the private half. The encrypt stage signs with it, the decrypt stage opens mail with it, and it is advertised in Autocrypt: headers. Generated automatically or on request, or imported with its private half.

MUA key (custody = client)

The user’s own key, whose private half lives only in their mail client. The row is public-only for ever and never primary. Pepsi encrypts to it and recognises mail encrypted to it, but can never open, sign with or advertise it.

The public face of an address is the key a correspondent should use: the newest active MUA key when there is one, otherwise the primary active MTA key. The Web Key Directory, the Autocrypt: header, the key file and local encryption all read it through one ordering, so they cannot disagree:

  • the Web Key Directory serves only MUA keys once there is one — every active one, newest first, at most eight (MAX_CLIENT_KEYS) — and never the MTA key beside them;

  • mail from one local user to another is encrypted to it — and to the user’s other MUA keys of the same protocol as well, the same set and order the directory serves, so a backup token opens it too;

  • Pepsi adds no Autocrypt: header and attaches no key file when it is an MUA key: the mail client advertises its own key, and Pepsi advertising a different one on some of the user’s messages would make correspondents’ key state flip under Autocrypt’s newest-wins rule.

The MTA key is not retired when an MUA key appears. It keeps decrypting mail from correspondents who still use it, and it still signs, inside the ciphertext, cleartext mail that Pepsi encrypts on the user’s behalf (a correspondent who lacks it sees an unverifiable signature, which is harmless).

Mail encrypted to an MUA key is passed to the mail client unopened, even when an MTA key is among its recipients too: the user registered their own key to get end-to-end protection, and a plaintext copy in the mailbox would silently undo that. It is not a decryption failure (ON_DECRYPT_FAILURE does not apply) and it flows on down the pipeline, so the spam and whitelist stages still decide its fate. See pepsi-stage-decrypt(1). Mail that arrived encrypted to the MTA key instead is opened, read by those stages, and then — with pepsi-stage-reencrypt in the pipeline — sealed to the MUA key before it is filed, so the mailbox copy is protected the same way.

Note

Server-side features cannot see into end-to-end mail. A message passed through to an MUA key is ciphertext to every later stage: language detection cannot read it, nothing was verified so state.signature_verified is never set, and a whitelist entry with signature_required does not match it. That is the direct consequence of not opening it.

Likewise, a message the user’s mail client already encrypted is left alone on the way out – no second encryption, no signature, no Autocrypt: header or key file of Pepsi’s – and one it already signed may be encrypted but gets no second signature.

13.9.1. Registering the user’s own key

An MUA key arrives in one of these ways:

  • Automatically, from the user’s own mail. A key is registered from a submitted message whose Autocrypt: header (addr= equal to the From:) carries a key that the address does not have yet; for the address’s very first key, an attached application/pgp-keys file naming the address also counts. This happens only when the submitter may speak for the From: address: a trusted relay (MYNETWORKS, a client certificate), or an authenticated account whose From: matched a concrete, wildcard-free USERNAME_MAP entry or its default login@HOSTNAME (state.origin.from_bound). An account granted *@example.org may send as its colleagues but never registers a key for them; pepsi-setup lists such accounts.

  • By the user, through the web console or by e-mail (below).

  • By the operator, with pepsi-keys identity import without --private.

A fingerprint the address already has, retired or not, is never registered again, so a retired key does not come back because an old device still sends it. A user with two devices that each hold a key, or with a hardware token and its backup, ends up with two MUA keys: the newest is the public face, both are recognised on inbound mail, and mail the gateway opened is re-sealed to all of them before it is filed (pepsi-stage-reencrypt), so either key opens the mailbox copy. Mail a correspondent encrypted to only one of them passes through unopened as it arrived, and Pepsi cannot make the other key open it: it never holds the private half.

When a key is registered automatically for an address that already had another identity, the user is sent a notice (“a new encryption key was registered for your address”, with its fingerprint and how to retire it; template key-registered.<lang>.body) at the encrypt stage’s RESPONSE_STAGE.

Warning

A stolen password can register a key. Anybody who can submit mail as a user can make their own key that user’s public face. The notice is the mitigation, and a partial one: an attacker who can submit mail can often read the mailbox over IMAP and delete the notice too. The damage is bounded: mail encrypted to the planted key is still delivered only to the victim’s mailbox, so the attacker gains the ability to read future mail that they can already reach, plus signatures that verify as the user. The remedy is retire, available by e-mail as well. A deployment with no RESPONSE_STAGE sends no notice at all; pepsi-setup warns about it.

A user closes this road by enrolling a second factor (below): from then on a key is registered only by a command that carries a current code, and an ordinary message’s Autocrypt: header registers nothing.

13.9.2. Self-service on three surfaces

One set of operations – status, generate (a server-managed key, always allowed on request), register (the user’s own key), publish (request a key-server upload) and retire – is available on three surfaces, each confining a user to their own address the way it already does:

pepsi-keys

identity show, identity generate, identity import (without --private), identity publish --vks, identity revoke, and otp for the second factor. See pepsi-keys(1); an unprivileged user reaches only their own identities on a setuid install.

The web console and the API

For an operator or a principal holding own:<address>: the identities page offers Generate a server-managed key and Register my own key (paste an armoured public key), and an identity’s page Upload to the key server and revoke. The web tier still never acts on key material: generating, registering and revoking enqueue generate-identity / register-client-key / revoke-identity tasks that pepsi-setup apply re-validates and performs as the pepsi-crypto role – revoking too, because it destroys a signing-only key’s private half. A revocation requested there therefore takes effect when the applier has run, with the same retirement rule as pepsi-keys identity revoke. An S/MIME identity’s page adds the certificate round trip: Request a certificate enqueues identity-csr (the PEM request appears on the task’s page) and Install the issued certificate enqueues identity-certificate, which the applier performs only for a certificate over the identity’s own key that names its address – the same identity csr / identity import round trip, without a terminal. Without the pepsi-httpd-admin package those five degrade to read-only like every other applier path. See The administrative API and The administration console.

E-mail

A message from the user to pepsi-keys@<their domain> ([stage-encrypt] KEYS_CONTROL_LOCAL_PART) with the command in the Subject: – status, generate, register (taking the key from this message’s Autocrypt: header or attachment), publish [FPR], retire FPR, pin FPR (a correspondent’s key, e-mail only and only under a second factor, A user’s own pin), otp enroll, otp remove – is consumed rather than relayed and answered with the list of the address’s keys. With a second factor enrolled, every command but status also carries the current code (A second factor for key changes). A command whose subject starts with a reply or forward prefix (Re:, Fwd:, AW:, …) is refused unless it is status, so a command an outsider planted in a message the user merely answers changes nothing. It needs RESPONSE_STAGE to be set, and works only when the submitter may speak for the From: address (as above). It is handled in the encrypt stage itself, which already runs as pepsi-crypto; a stage worker must never be able to enqueue work for the root applier.

13.9.3. A second factor for key changes

A user can protect everything above with a second factor: a TOTP secret (RFC 6238 – six digits, a new code every 30 seconds, SHA-1, which is what every authenticator app implements) enrolled for their address. Once it exists, every change to the address’s keys that a user can make needs the app’s current code. That also stops a command an outsider planted in a message the user merely replies to (Forged security tags in the Subject bypass gateway sanitisation):

  • by e-mail, every command but status – the code is a six-digit word anywhere in the Subject:, e.g. register 123456 or retire 89ABCDEF01234567 otp=123456. A message’s Autocrypt: header or attached key file no longer registers a key for that address; register with a code does;

  • in the web console or the API, generating, registering, revoking and changing an identity’s flags (publication, key-server upload, which key is primary) under own:<address> take the code in an otp field (the console’s forms have one), which the setup applier checks – pepsi-httpd itself can neither read nor check a second factor, so these changes are asked of the applier and take effect when its task is done;

  • with an unprivileged pepsi-keys, pepsi-keys identity --otp CODE <command>.

Enrolling, replacing and removing it are commands of their own, and replacing or removing one needs a code too:

otp enroll (e-mail)

Creates a fresh secret and answers with it once: an otpauth:// URI, the secret in base32 for typing in by hand, and a QR code to scan. The secret is not in force yet: a second factor the address already has stays as it is until the new one is confirmed. When the address has a key of its own (a key registered from the user’s mail client), the reply is encrypted to that key, so only the client that holds it can read the secret; otherwise it is sent in clear. The reply carries an Expires: header at the end of the confirmation window, which mail clients that honour it use to hide or remove the message. Delete that reply once the secret is in the app: anybody who can read it can produce the codes.

otp confirm CODE (e-mail)

Makes the secret from otp enroll the second factor, with a current code from the app, within [stage-encrypt] OTP_CONFIRM_WINDOW (one hour by default). That code counts as used. A wrong code counts against the new secret only, never against the second factor in force, and ten of them discard it; a secret not confirmed in time lapses, and otp enroll starts again. The answer repeats the advice to delete the enrolment reply.

pepsi-keys otp enroll ADDRESS

At a terminal: creates the secret and enrols it at once, since it never passes through a mailbox.

otp remove CODE / pepsi-keys otp remove ADDRESS --otp CODE

Removes it.

status shows whether the address has one, and whether it is locked.

Wrong codes and replays. A code is accepted once: the same code again, even within its 30 seconds, is refused as a replay. Clocks may differ by one step either way. A wrong or replayed code counts as a failure, a right one resets the count, and ten failures in a row lock the second factor – every later attempt is refused without being checked, so parallel or repeated guesses during a lock reveal nothing (Login and recovery rate limits defeated by races and logic errors, Login and recovery rate limits defeated by races and logic errors). A command that carries no code at all is refused without being counted.

The operator can always let a user back in: pepsi-keys otp reset ADDRESS (or DELETE /api/v1/otp/{address} with keys:write, which asks the setup applier) removes the enrolment whatever its state, and pepsi-keys otp enroll ADDRESS run by the operator replaces it without a code. A new enrolment always starts at zero failures. pepsi-keys otp status lists every enrolment. An operator is never asked for a code: they can reset it anyway.

What it does not cover, stated in Threat model: the first enrolment needs no code, so somebody who has the password first can enrol their own (the operator’s reset is then the remedy); the lock can be triggered by anybody who can send as the user; and a user without a key of their own receives the enrolment reply in clear, so the secret is in their mailbox until they delete it (Authentication bypass in gateway, list and portal web interfaces). The secret is wrapped under the key store’s key-encryption key like a private key, the table is readable by the pepsi-crypto role only, and pepsi-keys wrap rotate re-wraps it with the keys.

A generated or imported identity is published by default (--no-publish opts out, and identity unpublish clears the flag later). A key nobody can fetch cannot be encrypted to, so publication is the useful default; the flag is the per-address escape hatch.

13.10. Publishing our users’ keys

The mirror image of “Finding a correspondent’s key” below: how other people find our users’ keys. There are three channels, and they behave so differently that treating them as one setting would be a mistake.

Channel

Who serves it

Reversible?

Turned on by

Web Key Directory

us (pepsi-httpd)

yes, immediately

the identity’s published flag — on by default

Key server

a third party

no

the identity’s vks_wanted flag, set by an explicit request or, for keys made by hand, by [pepsi-keys] VKS_PUBLISH – off by default

DNS (OPENPGPKEY / SMIMEA)

us (our zone)

yes, on the next zone push

publishing the record by hand

Every identity is published by default, however it was created. The opt-out is per address, not per identity, because that is the unit a user reasons about (“am I discoverable?”) — and because a per-identity opt-out permits a useless half-state in which the signing certificate is published and the encryption certificate is not, so correspondents can verify but cannot encrypt.

An OpenPGP key is published on all three channels without third-party certifications: only the key holder’s own signatures (and a designated revoker’s revocation) are kept. A user’s own key that has been through a key server can carry anybody’s certifications, which would disclose the user’s social graph and, on a flooded key, make the published copy unusable; the same rule applies to every correspondent’s key Pepsi stores. The rule is applied when a key is published, not only when it is stored, so an identity whose stored copy still carries certifications is published stripped too, both by the Web Key Directory and in the OPENPGPKEY records pepsi-keys dns and pepsi-setup print, and by pepsi-keys identity export; the stored row itself is not rewritten.

13.10.1. The Web Key Directory

pepsi-httpd answers the four Web Key Directory paths for every domain in [pepsi-ingress] ACCEPTED_DOMAINS:

GET /.well-known/openpgpkey/hu/<hash>              direct   (on <domain>)
GET /.well-known/openpgpkey/policy                 direct
GET /.well-known/openpgpkey/<domain>/hu/<hash>     advanced (on openpgpkey.<domain>)
GET /.well-known/openpgpkey/<domain>/policy        advanced

Each identity carries the WKD local-part hash of its address (z-base-32 of the SHA-1 of the lower-cased local part), stored and indexed together with the domain, so a request is answered with one lookup rather than by hashing every candidate row. The SHA-1 there is a naming function fixed by the specification, not a security one, so it is not gated by CRYPTO_ALLOW_WEAK_DIGESTS.

The response is the binary transferable public key — not armor — with Content-Type: application/octet-stream and Access-Control-Allow-Origin: *, which the specification requires so a browser-based client can fetch a key from a domain other than its own origin. The policy file is a zero-length 200: it carries no flags, but it has to exist, because GnuPG reads its absence as “this domain runs no Web Key Directory” and gives up before asking for a key.

The ?l=<local-part> parameter that a client may send is read and thrown away. Honouring it would turn the endpoint into a lookup by caller-supplied address, which is a much broader thing than answering a hash the caller already had to know.

An answer may carry several certificates, concatenated, as the specification allows, and which ones follows the address’s public face. Once the user has registered a MUA key, every active MUA key of the address is served, newest first and at most eight (MAX_CLIENT_KEYS): the set, order and cap the encrypt and reencrypt stages seal to, so what a correspondent fetches from the directory and what a local sender encrypts to agree, and a user’s backup token opens mail from either. The MTA key is never served beside a MUA key – offering it would invite correspondents to keep encrypting to a key the user did not choose, and to one Pepsi can open. Without a MUA key the active MTA keys are served, at most three, so that during a rollover the new key and the one correspondents still encrypt to are both findable. The specification has a client use every certificate the answer carries for the address it asked about; gpg imports them all (measured, Several certificates in one Web Key Directory answer), and a client that takes only the first certificate gets the newest key. Mail a correspondent encrypted to only one of the keys stays openable by that key only: Pepsi never holds the private half of a MUA key and cannot re-seal it.

Deployment takes one DNS record and one certificate name per served domain. The advanced method — the one every current client tries first — is fetched from openpgpkey.<domain>, so that name must resolve to the pepsi-httpd host and the certificate it serves must cover it. Both are the same listener: openpgpkey.<domain> and the apex are two SNI names on one HTTPS listener, not two listeners. pepsi-setup run adds openpgpkey.<domain> to the names it asks certbot for and reminds you about any that does not resolve; a domain that already publishes keys is flagged, because for it the advanced lookup is failing today rather than merely unconfigured. The direct method on the apex works without any of this, so a missing openpgpkey host is a degradation, not a breakage.

Important

The endpoint serves our own published identities only. It reads crypto_identity, the table of addresses we hold key material for, and never peer_key, the cache of correspondents’ keys that discovery filled in. Serving those would make Pepsi a key server for material it never verified and does not vouch for, published under its own domain name. There is no configuration option that changes this.

Note

A Web Key Directory answers an unlimited number of guesses, and Pepsi does not pretend otherwise. There is no rate limiter on the endpoint and no uniform-404 shaping: a request for an address that publishes a key gets the key, and a request for one that does not gets a 404, promptly and as often as anybody cares to ask.

The protocol is a public oracle by construction — its whole purpose is that anybody may ask whether an address publishes a key — the hash covers only the local part, so it answers guesses rather than enumerating a list, and the addresses are on the outside of every message the domain sends anyway. Shaping the 404s would take from a client the ability to tell “no key” from “server broken”, and in return would add only an obstacle that an attacker with a wordlist gets straight past. If you need the addresses to be secret, a key directory is the wrong thing to be running.

13.10.2. Key-server uploads happen on request

keys.openpgp.org and the servers that speak its protocol accept a key permanently. They can later be told the key is revoked; they can never be told to forget it, and neither can the address it was uploaded for.

That is why nothing is uploaded unless somebody asked, and why the request is recorded: each identity carries vks_wanted, and “not uploaded” is state, shown by pepsi-keys identity show, the web console and the e-mail status reply, rather than an absence.

  • Automatically created keys and automatically registered MUA keys start with it off. Autocrypt and our own Web Key Directory (which is not an upload) are how they are found.

  • Keys made by hand – pepsi-keys identity generate/import, the web and e-mail generate – take [pepsi-keys] VKS_PUBLISH as their default, an operator-level switch that is off by default: the person who understands that an upload cannot be withdrawn is the operator, not whoever happened to generate a key.

  • An explicit request is honoured whatever VKS_PUBLISH says: pepsi-keys identity publish 42 --vks (which prints a confirmation naming exactly what cannot be taken back), the web console’s Upload to the key server, PATCH /api/v1/identities/{id} with vks_wanted, or the e-mail publish command.

Publication is a two-step protocol, and that is why there is a retry job. The upload returns a token; only the token authorises asking the server to mail a confirmation link to the address; and only after that link is followed does the server serve the key by address. A key that was uploaded but never confirmed is stored yet unfindable — the failure that looks like success. So:

pepsi-keys identity publish --retry      # pepsi-keys-publish-retry.timer, hourly

works through every published, active OpenPGP identity whose upload was requested and that is not verified yet, spacing its attempts by VKS_RETRY_INTERVAL and giving up after VKS_MAX_ATTEMPTS with the reason left in the row for you to read (pepsi-keys identity show). It is not gated by VKS_PUBLISH, so a user’s request takes effect on the job’s next run. Each round asks the key server whether the address is already served before uploading again, so a confirmation followed by anybody — the stage below, a human reading the mailbox, an earlier run whose database write did not land — ends the loop.

The confirmation mail itself is followed by pepsi-stage-vks-confirm, a small stage on the inbound path. It is a separate program because what it does — fetch a URL found in inbound mail — is a genuinely dangerous primitive, and isolating it means the restrictions are in one small place whose position in the pipeline is visible in the configuration. That program’s page lists them; the short version is that the mail must come from the configured key-server host, be authenticated by SPF or DMARC, link only to that host, be addressed to somebody we are actually waiting for a confirmation for, and name the fingerprint of the key we uploaded for them. Anything else is delivered to the user, who can click the link themselves. So is a mail whose links were followed but after which the key server still does not serve our key: it is discarded only once at least one identity is verified as published.

13.10.3. Unpublishing, and what it cannot do

pepsi-keys identity unpublish 42

stops the Web Key Directory serving the identity at once, and clears its key-server bookkeeping so the retry job forgets it.

It does not remove anything from a key server, because nothing can. If the key was uploaded, the command says so and points at the only real remedy:

pepsi-keys identity revoke 42 --upload

which publishes the revocation certificate on top of the uploaded key (--upload is needed here only because unpublish forgot the upload).

13.10.4. A user’s own pin

A user who compared a correspondent’s fingerprint – in person, or by reading the words of the key-change notice to each other – can record the result by e-mail: pin FPR CODE to the key-command address (pepsi-stage-encrypt). Every live cached key with exactly that fingerprint is pinned and raised to the manual source, the rung of an operator’s own entry: it is used for that correspondent whatever later messages offer, nothing displaces it, discovery does not refresh it away, and its signatures verify as valid, so they can earn [verified]. The cache is shared, so that holds for every user of the deployment, which is why the command needs an enrolled second factor (a stolen password is not enough), the whole fingerprint (a 64-bit key ID can be collided) and leaves a key.peer.pin audit row naming the user and each row’s previous source. Unpinning is the operator’s (pepsi-keys peer unpin).

13.10.5. Revocation publishes what it can

Every way of revoking an identity – pepsi-keys identity revoke, the retire e-mail command, the console’s or API’s revoke-identity task – goes through one function (pepsi_keymat::revoke). For an OpenPGP key whose private half the gateway holds, it first signs a revocation certificate with the key itself and stores it as the key’s public half, in the same statement that revokes the row. The order matters: revoking a signing identity destroys its private half, after which no certificate could ever be signed. If the certificate cannot be made, nothing is revoked and the request is retried or fails visibly.

From then on:

  • the Web Key Directory serves the key as revoked, after any usable key of the address, instead of falling silent – silence would leave every correspondent’s client with the key it already had;

  • a key that had been uploaded to a key server has the revocation uploaded there as well: at once by pepsi-keys identity revoke, otherwise by the next run of pepsi-keys identity publish --retry (hourly from pepsi-keys-publish-retry.timer), which retries it like an upload;

  • the reply – the retire answer, the task’s result, the command’s output – says exactly which of the two happened.

No certificate can be made for an S/MIME certificate (its issuer revokes it), for a user’s own MUA key (only their mail client holds the private half, so only it can sign the revocation) or for a key whose private half is already gone; such a key just stops being used and served, and the reply says that correspondents who have it are not told (Key management too hard: end-to-end mail clients error-prone or unused).

13.10.6. Losing a client key

A user who registers their own MUA key takes custody of their mail: mail encrypted to that key is delivered unopened, and pepsi-stage-reencrypt seals inbound mail the gateway decrypted to the user’s registered keys before it is filed. The gateway keeps no escrow or gateway key that could open that mail later; that is a decision, not a gap, since such a key would be a standing way into every mailbox it covers. The recovery path is a second or third registered client key – another device, a backup token – registered the same way as the first (register by e-mail, pepsi-keys identity import, or simply mail sent from that client): pepsi-stage-reencrypt seals to every registered key (up to MAX_CLIENT_KEYS), the Web Key Directory serves them all, and any one of them opens what was filed. The key-registered notice and the reply to register say this to the user; a user with a single key who loses it loses the mail filed under it.

13.10.7. DNS: OPENPGPKEY and SMIMEA

pepsi-keys dns <address> prints the DNS records that publish an address’s published, active identities: OPENPGPKEY (RFC 7929) for OpenPGP material and SMIMEA (RFC 8162) for S/MIME certificates, both under the hashed owner name those standards define. pepsi-setup run prints the same records for every published identity, alongside the DKIM, SPF and MTA-STS ones (capped at a readable number — for a large deployment, ask per address).

S/MIME has no Web Key Directory equivalent and no key server, so SMIMEA is its publication channel.

Warning

Publish key records only in a DNSSEC-signed zone. An unsigned OPENPGPKEY record is a key handed out by whoever can answer for the zone, which is not an improvement on having no key at all — and unlike a WKD answer, a DNS answer carries no other evidence. Both commands repeat this as a comment in their own output.

The DNS owner name and the WKD hash are not interchangeable: the DNS one is SHA-256 truncated to 28 octets, hex-encoded, over the case-sensitive local part (RFC 7929 §3), while the WKD one is z-base-32 of SHA-1 over the lower-cased local part. Confusing them produces records that nothing ever queries, which is why they are separate functions with a test asserting they differ.

The hash does not hide which addresses have keys, and both RFCs say as much. In a zone signed with NSEC, walking the chain of denial records lists every owner name, and since the domain is not part of the hash, one precomputed table of common local parts turns those names back into addresses for every domain at once. NSEC3 hashes the names again, but they still fall to an offline dictionary attack. Only a zone signed online with minimally covering denial records (the “white lies” most signing DNS providers use) resists enumeration. Publishing a key record therefore discloses that the address exists; that is the same disclosure a Web Key Directory makes to anyone who guesses the address. pepsi-keys dns and pepsi-setup run print this beside the records, with the advice that follows from it: if the list of addresses must stay private, sign the zone online with minimally covering records, or publish keys by WKD only. Pepsi does not sign the zone and does not check its signing mode.

13.10.8. Checking what is actually served

A correspondent believes what the Web Key Directory and the DNS answer, not what crypto_identity holds, and the two can differ: the WKD direct method is answered by whatever serves the domain’s apex web site, which is often not Pepsi; a zone can keep an OPENPGPKEY or SMIMEA record after the identity behind it was rotated; and whoever can write to the zone, to a web server on the domain or to the key store can publish another key for a user and so receive their future mail. Pepsi therefore asks every channel from the outside, the way a correspondent would, with the hardened HTTPS and DNS clients of key discovery, and compares the fingerprints that name the address – the only ones a client accepts – with the store:

  • both WKD methods (openpgpkey.<domain> and the domain itself) against exactly the set the endpoint is meant to serve (every MUA key when the user registered one, otherwise up to three MTA keys);

  • OPENPGPKEY and SMIMEA against every published, active identity of that protocol, record by record, whether or not the answer is DNSSEC-validated (an unvalidated one is marked: DANE clients ignore it).

Each channel gets one of five verdicts. mismatch – a fingerprint the store does not publish for that address is served – is the finding the check exists for. incomplete means only stored keys are served but not all of them, absent that nothing is served (for a DNS record, publishing it is your choice, so absence is not a fault there), failed that the channel could not be asked, and ok that exactly the stored keys are served. Four places run the check live and store nothing:

pepsi-setup check

A published keys group with one line per address; only a mismatch makes the check fail.

pepsi-status

A section Published keys as served: how many addresses agree, and every channel of every address that does not. --offline skips it.

pepsi-keys identity list --served

A SERVED column naming the channels that serve each identity’s fingerprint (none for a published identity nothing serves), and every disagreeing channel below the table. An unprivileged caller sees only their own addresses, as with the plain listing.

The console

The identity listing, filtered to one address – which is always the case for a user logged in with own:<address> – shows the channels and the fingerprints they serve, a foreign one marked, so the user can compare them with the key in their own mail client. That comparison is the only thing that reveals a key substituted in the store itself: the operator’s check compares the served keys with the store, so it agrees with a substituted row.

What the check cannot see: it asks from this host, at one moment. A server that answers this host truthfully and a chosen correspondent with another key – an on-path attacker near the correspondent, a resolver or web server answering by client address – is not detected, and neither is a substitution that was undone before the check ran. A NATed host that cannot reach its own public address, or a name that resolves to a private address (which the client refuses, as it does for every key fetch), makes the WKD channels failed. There is no signed or append-only log of what was published; see the threat model (Client custody (custody = client, the MUA key)).

13.10.9. The notice signer

The mail Pepsi writes itself — sign-in links, portal notifications, secretary challenges, payment requests, command replies, key-change and out-of-office notices — can be signed by one identity of the deployment, so that a recipient whose client verifies signatures can tell a genuine notice from a forged one (Forged notices). It is an ordinary identity, held and published like a user’s:

  1. Create it at a served domain, so the Web Key Directory serves it, in the protocol your recipients’ clients check — OpenPGP by default, --protocol smime for an S/MIME certificate (one a public CA issues is the one most clients accept without asking; --csr writes the request):

    pepsi-keys identity generate notices@example.org --protocol openpgp --name "example.org notices"
    
  2. Set NOTICE_SIGNER = notices@example.org in the [stage-notice] section the wizard wrote (or add one: PROGRAM = pepsi-stage-encrypt, NEXT_STAGE = dkim-sign), and point every RESPONSE_STAGE, BLOCK_RESPONSE_STAGE, [pepsi-admin] ENROL_STAGE and [pepsi-secure-link] NOTIFY_STAGE at it. Run pepsi-setup validate.

  3. Check what is served: pepsi-keys identity list --served (above).

  4. Tell your users and correspondents the fingerprint, and that the deployment’s notices are signed by it. A recipient checks a notice by fetching notices@example.org from the Web Key Directory (gpg --locate-keys notices@example.org; Thunderbird’s key discovery does the same) and comparing the fingerprint with the one you published, then looks at the notice’s signature status. A signed notice comes From: the signer’s address. A client accepts a signature only from a key that belongs to the From: address, so it checks the notice’s signature as it would any other; the address the notice was composed with becomes its Reply-To:, unless it already has one.

The key is rotated like any other identity (pepsi-keys identity generate again, then retire the old one once the new one is served); the stage always signs with the newest active signing identity of the address. With the key store unreadable or the identity missing, notices wait and are retried rather than leave unsigned. What is signed and what is deliberately not is in Signed notices.

13.11. Backing up and rotating the key-encryption key

Danger

If the key-encryption key is lost, every stored private key is gone. Back up secrets.d/pepsi-crypto.secret separately from the database, and treat it with the care its contents deserve.

The blow is softened by the same asymmetry that governs retirement: mailboxes hold plaintext, so losing the KEK does not make anybody’s mail unreadable. What is lost is any ciphertext still in flight or archived — and, far more disruptively, every published identity is invalidated at once. Correspondents still hold public keys the deployment can no longer use, so the whole organisation has to re-key and re-publish. Plan for that as a disaster-recovery scenario, not as an inconvenience.

Rotation, by contrast, is routine and incremental by construction, because each row records the id of the key that sealed it:

  1. put the new secret in secrets.d/pepsi-crypto.secret as KEY_WRAP_SECRET, and keep the old one beside it as KEY_WRAP_SECRET_<OLD-ID> (the suffix is the old wrap_key_id, upper-cased);

  2. point [pepsi-crypto] KEY_WRAP_KEY_ID at the new id;

  3. run pepsi-keys wrap rotate.

Between steps 2 and 3 the deployment keeps working: new material is sealed under the new key while old material still opens under the retired one. Only after step 3 reports everything rotated may the retired secret be removed. Each re-wrap is a guarded update keyed on the old id, so a concurrent rotation — or a key re-generated while the sweep ran — is never written over; rows whose key has no configured secret are reported and skipped rather than failing the run. --dry-run lists the work first. The same sweep re-wraps a blob that is already under the current key but still in format version 1 (no fingerprint in its associated data, see above), so run it once after upgrading even when the key-encryption key stays the same.

13.12. The forward-secrecy profile

OpenPGP and S/MIME have no forward secrecy: a message stays encrypted to the recipient’s long-term key, so whoever obtains that key later – from a stolen backup of the database and the key-encryption key, a compromised host, a legal order – reads every message ever encrypted to it that they recorded on the way (No forward secrecy for long-term mail encryption keys). Pepsi cannot change the protocols, but for the keys it holds itself it can shorten that window: replace them on a schedule, and destroy a replaced key’s private half once mail encrypted to it is no longer expected. That is the forward-secrecy profile, off by default:

[pepsi-crypto]
ENCRYPTION_ROTATION_DAYS = 90
RETIRED_PRIVATE_GRACE_DAYS = 30

pepsi-keys identity rotate-due, run daily by pepsi-keys-rotate.timer, does both halves:

  • Rotation. Every server-held (custody = local) key that can decrypt and is older than ENCRYPTION_ROTATION_DAYS is replaced. The new key is made the way pepsi-keys identity generate makes one and becomes the primary; it is served over the Web Key Directory when the old key was, and queued for the key server when the old key had been. The old key is revoked with the reason superseded through the same path as identity revoke, so an OpenPGP key carries its revocation certificate and WKD serves it as revoked beside the new one, and a key server that had it is told by the pepsi-keys-publish-retry.timer job. Unlike a key revoked by hand, a key revoked by the rotation still opens mail encrypted to it until its private half is destroyed (below): it is retired, not distrusted. An OpenPGP key is replaced whole (one key signs and decrypts, so the signing key changes too); a split S/MIME pair has only its encryption certificate replaced, and the address’s SMIMEA records (pepsi-keys dns) have to be republished.

  • Destruction. The private half of a retired server-held decryption key – revoked by a rotation or by hand, or expired – is destroyed once it was retired more than RETIRED_PRIVATE_GRACE_DAYS ago, unless a message still in the queue is encrypted to it. The queue check reads every queued message that could carry ciphertext, in any stage and any status (waiting, parked for a key, failed), and asks whether its outermost ciphertext names the key among its recipients (the OpenPGP key IDs, the CMS recipient identifiers) – without decrypting anything. A message that has already been decrypted carries no ciphertext any more and does not hold a key back. Destroying is the same operation as pepsi-keys identity forget-private and leaves the same key.identity.forget-private audit record.

A user’s own MUA key (custody = client) is never touched: Pepsi holds no private half of it, and its owner decides when to replace it. Signing-only keys are not destroyed by this job either; the retirement sweep and identity revoke already destroy them at retirement. --dry-run shows what is due.

What the profile costs, and why it is off by default:

  • Archived ciphertext becomes unreadable. Mailboxes hold plaintext, so delivered mail is unaffected; but anything still encrypted to a destroyed key – a ciphertext archive, a message redelivered later from a backup, a copy that was delivered encrypted because it could not be opened – can never be opened again.

  • Late mail to a stale key is lost to the reader. A correspondent who cached the old key keeps encrypting to it until they fetch the new one. Within the grace period such mail still opens; after it, it does not. Correspondents have to refresh: Autocrypt headers on our outbound mail and the Web Key Directory carry the new key, a key server carries it once confirmed, but a client that pinned the old key by hand or never refreshes keeps using the dead one. Choose the grace period to cover how long correspondents take to notice.

  • Churn. Every rotation is a new fingerprint for correspondents who verify fingerprints, and new DNS records where OPENPGPKEY or SMIMEA records are published.

The profile limits what a later compromise of the key store yields; it does nothing against an attacker who already holds the current key, and nothing for the user’s own client keys.

13.13. Peer keys

A peer key is cached with the source it came from, and the source decides what happens when a newly discovered key contradicts a stored one. The order of those sources is the trust ladder tabulated in Finding a correspondent’s key below; it lives in a database function so it can be re-ordered by re-running the procedures file rather than by a schema patch, and the conflict rule is applied server-side, in the same statement that stores the key, so no client can skip it.

A key that outranks everything stored for an address replaces it; at equal or lower rank the stored key is kept and the new one is not inserted, so a weak source can never quietly displace a better-attested one. The comparison is made per protocol, so a key of the preferred protocol can still be chosen over a better-ranked key of the other (Keys and certificates imported or trusted without verification). A pinned row is never displaced, whatever the rank — pinning is how an operator makes a trust-on-first-use decision permanent.

The rank comparison has one exception. It never displaces a pinned row, and it is confined to the Autocrypt tier (the inbound-signed, inbound and gossip rungs). The stored key is replaced at equal rank when all of these hold: the incoming key comes from that tier, every stored row for the address and protocol is from that tier too, the incoming rank is no worse than the stored one, and the message’s Autocrypt effective date is strictly newer than the newest one stored at the best rank. That is Autocrypt Level 1’s own youngest-wins peer-state update: without it the second Autocrypt: key ever seen for an address would be refused for ever, and a correspondent who reinstalls their client or rotates their key would go on receiving mail encrypted to a key they cannot read. The test is on the source name, not the rank number, and the no worse than term keeps the exception inside the tier in both directions — gossip still never displaces what an address’s owner said about themselves, a key from an unsigned message never displaces one a DKIM-signed message brought, however new the unsigned message claims to be, and neither ever displaces a harvested-or-better-attested key from outside the tier. A signed key arriving over an unsigned one replaces it whatever its date, and because both are the correspondent’s own claims that replacement is treated as a rotation (audited, announced, and held under ACCEPT_ROTATION = expired) rather than as the silent replacement a discovery answer earns.

A known-compromised key is never stored

A key of any type on the known-compromised list is refused wherever a key below CRYPTO_MIN_RSA_BITS is, and discovery, harvesting and pepsi-keys peer import do not store it; so is an RSA modulus that gives its private key away (the ROCA fingerprint, primes close enough for Fermat’s method, a small factor). The list lives in the database, pepsi.compromised_key, and holds two sources:

  • the badkeys blocklist (https://badkeys.info), about three million keys, among them the Debian OpenSSL weak keys of the usual key types and sizes. pepsi-keys blocklist update, run by pepsi-keys-blocklist.timer ten minutes after it starts and then daily, asks [pepsi-keydiscovery] BADKEYS_URL whether the list changed (a conditional request: an unchanged list costs one small answer) and adds what is new. Nothing is ever removed, since a published private key stays published. A list that shrank, or that would grow the table by more than a quarter, is refused until --force, because the list’s metadata is not signed and such a change is the sign of a tampered one. The first import writes about 240 MB (with the index); a lookup is one primary-key probe.

  • the screen: pepsi-keys peer screen, run daily by pepsi-keys-refresh.service, deletes cached keys that have since appeared on the list and runs a batch GCD over every cached RSA modulus and our identities’ public halves: a peer key sharing a prime with another is deleted and its modulus added to the list, so a rediscovered copy is refused too, and an identity of ours is reported as an error in the audit log (see “What an S/MIME trust anchor vouches for” in Security model).

pepsi-keys blocklist status (and pepsi-status) say when the list was last checked. An entry that proves wrong is dismissed – by the run that added it or by its source list, pepsi-keys blocklist dismiss – which stops it refusing keys and keeps the next update from adding it back. To stop the updates, systemctl mask --now pepsi-keys-blocklist.timer; the screen’s findings still apply, and pointing BADKEYS_URL at a mirror of one’s own (or at a copy that never changes) replaces badkeys’ server.

Which S/MIME container a correspondent gets

S/MIME mail is sent as authenticated encryption (AES-256-GCM AuthEnvelopedData) unless the recipient is recorded as unable to read it, in which case it gets AES-256-CBC EnvelopedData. The record is pepsi.smime_capability: pepsi-stage-autocrypt-learn learns it from the RFC 8551 SMIMECapabilities a correspondent’s verified signature carries, keyed on the signing certificate rather than on the address, and pepsi-keys peer capability set ADDRESS aead|cbc configures one by hand (also for *@domain), which wins over a learnt record. A recipient with no record gets AEAD, and the first message to each such certificate carries a plaintext notice beside the ciphertext asking the recipient to report an unreadable message and to reply signed (What a correspondent on an unmeasured client sees); a correspondent whose client reads only CBC is thus learnt from their first signed reply, or the operator configures a cbc record at once. [pepsi] CRYPTO_ALLOW_DOWNGRADE sets the policy around it (Which S/MIME container a correspondent gets).

A gossiped key its owner confirms is promoted

A gossiped key does not stay on the bottom rung for ever. When the address’s owner later advertises the same key themselves — in their own Autocrypt: header, or as an attached key naming them — the row is promoted to the inbound rung, or straight to inbound-signed when an aligned DKIM signature covered that message (Autocrypt Level 1 §5.3’s move from gossip to the peer’s own state). The key has not changed, so this is not a rotation: no key.peer.rotate row and no notice to anybody, but one key.peer.promote row (severity info) in the audit log, written by the same statement. The row then defends itself at the owner’s rank, so a later gossip of a different key is refused against it, and MIN_TRUST = harvested now admits it. Its effective date becomes the owner’s own, not the gossiping message’s, so a later rotation by the owner is judged against what the owner said. The verdict that a signature checked against it can reach does not change: it is still trust on first use, reported valid-untrusted at best. A different key from the owner is not a promotion either; it simply outranks the gossip and replaces it. A network source (WKD, DANE, …) or an operator that re-sees a gossiped key takes the row over as an ordinary refresh.

Seeing a key again only adds to it

Whenever a key is stored again under the same fingerprint – a refresh, a re-harvested header, a re-import – the copy already stored and the incoming one are merged before the row is written, and the merge keeps every revocation and every self-signature either carries (sequoia then uses the newest). So a copy taken before its owner revoked the key, replayed in a forged message’s Autocrypt: header or served by a stale directory, cannot roll the revocation back. This holds in the other direction too, and regardless of rank: when the incoming copy is the one carrying a revocation (or a newer self-signature) and comes from a source ranked below the stored row – the owner’s own mail repeating a key first found by WKD or imported by hand – the merged copy is still written, and the row is marked revoked if the merged certificate is. The row keeps its source and rank, and a different key from the weaker source is still refused. The merged certificate is pruned of signatures that do not verify, of User IDs, User Attributes and subkeys that nothing binds, and of third-party certifications, so a stranger cannot make it grow message after message.

Only User IDs the key’s owner has self-signed, and not revoked, count as the addresses a certificate names – for harvesting, for the Web Key Directory’s choice of certificate, for pepsi-keys peer import and for the signer binding (see Security model).

A rotation is never silent

The Autocrypt exception above is keyed on the From: header, which the sender writes, and inbound authentication is fail-open, so a message that merely claims to come from a correspondent can change the key we encrypt to them with. Autocrypt accepts that trade (it defends against passive collection, not an active attacker on the path) and so does Pepsi, but it leaves three traces, which limit rather than prevent the substitution (Undetectable key substitution or equivocation by key directories and CAs):

  • the same statement that replaces the key writes a key.peer.rotate row to the audit log — the address, the protocol, the displaced and the new fingerprints and both effective dates — so there is no rotation without its record; pepsi-status summarises the last 30 days of them;

  • with RESPONSE_STAGE set on pepsi-stage-autocrypt-learn, each local recipient of the message that caused it is mailed a notice naming the correspondent and both fingerprints (the key-rotation.<lang>.body template), so the person about to reply knows to check before sending anything confidential. Each fingerprint is shown as hex and in the PGP word list (pepsi_common::keystore::words: one word per byte, alternating two- and three-syllable words so a swapped or dropped word is audible), because hex, above all read aloud, is the comparison the studies found most error-prone (Users skip, botch or cannot use key fingerprint verification). The notice names the new key’s trust rung – inbound-signed (the correspondent’s domain signed the message), inbound (nothing did) or gossip (a third party passed it on) – since its reader is the person whose next message is encrypted to it. When the encrypt stage answers key commands it also prints the subject that pins the key once compared, pin FPR CODE (A user’s own pin);

  • an autocrypt-rotation telemetry count and a log line.

An operator who would rather refuse a genuine rotation than accept a forged one sets ACCEPT_ROTATION = expired on that stage: the newer key is then taken only when every stored key for the address is dead — recorded as revoked or expired, or past its expires_at. Otherwise the offer is held: nothing changes, a key.peer.rotate.held warning row is written, and the recipients are told the new key was not accepted — which matters, because a correspondent who really did change keys cannot read what they are sent until an operator removes the old row (pepsi-keys peer remove) or imports the new key by hand. A learnt key is stored with the expiry that its own material states (an OpenPGP primary key’s self-signature, an X.509 notAfter), so a key that has lapsed counts as dead without anything marking it; a key that states no expiry is displaced only once it is marked revoked or expired, or by hand.

Two rules bound how broad an entry can be:

  • an entry may name a whole domain (*@domain), but only when it was entered by hand. That is enforced by a database constraint, not by convention, so no discovery mechanism can generalise one address’s answer to a domain;

  • an exact address match always wins. A *@domain row is consulted only when no exact row exists, and pepsi-keys peer show marks it as the fallback it is. Such a key vouches for the domain, not for one sender at it (LDAP filter and regex injection in key lookup selects another user’s key): it is normally held by the correspondent’s gateway, which signs for everybody there, so a signature that verifies against it authenticates that domain (or its gateway) and says nothing about which user at the domain wrote the message – the local part of the From: is whatever the gateway, or any user it relays for, put there. Encrypting to it likewise reaches the gateway, not the person.

13.14. Finding a correspondent’s key

Everything above is about keys once they are in the store. Getting them there for someone else’s address is key discovery: given an e-mail address, find the public key or certificate, record where it came from and how much that source is worth, and cache it. The program is pepsi-keydisc, and the whole feature is configured by [pepsi-keydiscovery].

Finding a key is easy. Knowing whether to believe it is the entire problem, which is why the source and the DNSSEC flag are stored with every key.

13.14.1. Where a key can come from

dane

DNS OPENPGPKEY (RFC 7929) and SMIMEA (RFC 8162), under a hashed local part. Refused without the resolver’s DNSSEC AD bit — see When there is no validating resolver.

wkd-advanced

The Web Key Directory at openpgpkey.<domain> — a host the domain had to delegate deliberately. The HTTPS fetches of the two WKD methods and vks verify the server certificate against the system root store, or against the CA certificates of [pepsi-keydiscovery] TLS_CA_BUNDLE when it is set (see “Key-discovery certificate authorities” in Security model).

wkd-direct

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

ldap

A configured directory. Optional, and compiled in only with the ldap cargo feature, because a deployment with no directory should not link one.

vks

A verifying key server (keys.openpgp.org by default, or any server speaking the same paths). Note that this is VKS, not the older unverified HKP: an HKP server will serve a key anybody uploaded for anybody’s address.

inbound-signed

Harvested like inbound below, from a message whose DKIM signature passed at ingress, was aligned with the From: domain and covered the key’s carrier — the Autocrypt: header listed in its h=, or the body for an attached key or signer certificate. The sending domain, not merely the From: line, stands behind the claim, so the key sits one rung above an unsigned one and nothing unsigned can displace it. Not a discovery service either; the learn stage lifts an inbound find to this rung from the verdicts ingress recorded.

inbound

Harvested from a message that already arrived — an application/pgp-keys part, an S/MIME signer certificate, or an Autocrypt: header. Only material claiming the sender’s own address is kept; that address comes from the unauthenticated From:, so this limits but does not prevent a planted key (Weak binding between signer certificate or key and the From address). Not a discovery service: it runs where the message already is and costs no network I/O, which is why it may not appear in SOURCES. Written by pepsi-stage-autocrypt-learn, not by the decrypt stage.

gossip

Read out of the Autocrypt-Gossip: fields inside a message pepsi-stage-decrypt decrypted: the other recipients’ keys, which the sender attached so that a reply-all can be encrypted to somebody one has never had direct mail from (Autocrypt Level 1 §5.3). A field counts only for an address the message’s own To:, Cc: or Reply-To: names — §5.3’s own receiver rule. The only route by which one correspondent may speak about another, and hence its own rung at the bottom of the ladder. Like inbound it is not a service and may not appear in SOURCES; see pepsi-stage-autocrypt-learn, which is where both inline rungs are written, for the rest of the rules that decide whether a field counts.

manual / api

An operator running pepsi-keys peer import, or an authenticated submission. Not discovered at all; listed here because it is the top of the same ladder.

13.14.2. The trust ladder

This is the order everything is judged by — best first. It decides which key wins a conflict, what MIN_TRUST compares against, and how much extra time a still-running method is granted by the stop rule below.

Rank

Source

Why there

0

own

Not discovered at all, and not really a rung: the public half of an identity this deployment holds for the address. It pre-empts the ladder rather than topping it — see Our own users’ keys are not discovered — so it clears every floor and no peer_key row for that address is consulted.

1

manual / api

An operator who typed a fingerprint in meant it. Its manual spelling is also the only source the database constraint permits to enter a *@domain row.

2

dane with the AD bit

The only source with cryptographic provenance: the domain published it and DNSSEC proves the answer was not rewritten in transit.

3

wkd (advanced)

Fetched over verified HTTPS from openpgpkey.<domain>, a host the domain set up on purpose.

4

wkd-direct

The same, from the domain itself. A weaker signal of intent than a dedicated host, hence its own rank.

5

ldap

A directory the operator configured, and therefore semi-trusted — but still a directory somebody else runs.

6

vks

Proves only that somebody controlling that mailbox uploaded it: the server sent a confirmation mail and somebody clicked it. A real check, and a much weaker one than “the domain publishes this”.

7

inbound-signed (harvested, DKIM-signed)

What the address’s owner said about their own address, in a message their domain signed for: an aligned DKIM signature that passed at ingress covers the Autocrypt: header or the attached key. Still trust on first use — nobody published the key — but a forger without the domain’s signing key can neither plant nor replace it, which is what separates it from the rung below.

8

inbound (harvested, Autocrypt)

Trust on first use, of what the address’s owner said about their own address, in a message nothing signed for. Also the weight a dane row carries without the AD bit: a DNS record nobody signed is worth no more than a scrape. Discovery refuses such an answer outright (When there is no validating resolver), so this only applies to a row that entered another way — and such a row can never make a signature valid either.

9

gossip (Autocrypt-Gossip)

One correspondent’s introduction of another (Autocrypt Level 1 §5.3), read out of the ciphertext of a message this host decrypted. The same material as ranks 7 and 8 and a different claim: not “this is my key” but “this is somebody else’s”. §5.3 keeps the two in separate peer states precisely so that a third party’s introduction can never displace what an owner vouched for, and that is what a rung of its own buys.

[pepsi-keydiscovery] MIN_TRUST is the floor, and it defaults to any — the bottom rung, whatever the bottom currently is, so gossiped, harvested and Autocrypt keys are all accepted. The alternative to encrypting to a trust-on-first-use key is not encrypting to a better key, it is sending cleartext. Opportunistic encryption to an unauthenticated key still defeats passive interception, which is the threat most mail actually faces. The ranking is not thereby pointless — it arbitrates conflicts, it is recorded per key, and an operator who would rather send nothing than send to an unauthenticated key has one option to raise. The cost of the default is that users are not told when their mail went to an unverified key (Users skip, botch or cannot use key fingerprint verification).

The default tracks the bottom rather than naming a number. MIN_TRUST = harvested names rank 8 exactly, so it accepts what a correspondent advertised about themselves, signed or not, and refuses a stranger’s introduction of them; MIN_TRUST = inbound-signed accepts only what their domain signed for. The introductions are still stored either way; the floor decides only whether they may be encrypted to.

Every rung’s name is accepted as a floor (own, manual, dane, wkd, wkd-direct, ldap, vks, inbound-signed, inbound, gossip), together with the aliases any/none for the bottom, harvested/autocrypt for rank 8, autocrypt-signed/signed for rank 7, and owner-confirmed — which names rank 6 by what the evidence means rather than by the method that produced it: at vks and above, somebody who could prove control of the mailbox or the domain published the key on purpose; below it, nobody proved anything.

A key on either inbound rung or on gossip is one nobody published. When pepsi-stage-encrypt encrypts to such a key, it also asks discovery, in the background and at most once per NEGATIVE_TTL for the address, whether the owner published one: a WKD, DANE or key-server answer outranks the harvested key and replaces it for the next message. The message in hand is not held up by that; it goes out to the harvested key, which is still better than cleartext.

13.14.3. Our own users’ keys are not discovered

There is one address for which the whole ladder is the wrong question: one this deployment made the keys for. If pepsi-keys issued an identity for alice@example.org, then Alice’s key is not something to be found, weighed and compared. It is already in the store, and of all the keys that her mail could be encrypted to, it is the only one that she will be able to open.

That matters because peer_key is not a trusted table. Part of what fills it is harvesting from inbound mail, and harvesting keys on the From: header, which the sender writes. Inbound authentication is deliberately fail-open — only a definite DMARC failure under DMARC_ENFORCE rejects — so on a deployment that does not enforce DMARC on its own domain, a message claiming From: alice@example.org and carrying an Autocrypt: header will seed a peer key for Alice with a stranger’s key in it. Two things then go wrong, and they are the reason this is a defence and not a tidiness rule: mail from one of our users to another would be encrypted to the planted key, and a signature made with it would verify, setting state.signature_verified for an outsider.

So both crypto stages ask “is this one of ours” before they ask “what did discovery find”. When the answer is yes, our own key is the answer: the correspondent’s peer_key rows are not consulted for that address at all, whatever their rank and however they arrived. state.crypto records it as own. We do this to keep a key harvested from a forged From: from ever being used for one of our users (TOFU and key continuity miss first-contact and new-identity attacks).

Important

The rule is conditional on holding a key, not on serving the address, and the difference matters in practice, not only in theory. A user who runs GnuPG in their own client, has never asked Pepsi to encrypt anything and has never uploaded a key to us has no identity here, and this host can only ever learn their real key from discovery, harvesting or gossip. A blanket “never believe a discovered key for an address we serve” rule would send that user cleartext for ever. So: if we made the keys, they are the ones that get used; if we did not, the address is treated like any other correspondent’s, trust-on-first-use exposure included.

The corollary is the cost: for an address we do hold an identity for, a signature made with the user’s own separate key does not verify, however well-attested that key is – until that key is itself registered as the user’s MUA key (Two keys per user). Registering it (pepsi-keys identity import without --private, the web console, the e-mail register command, or automatically from the user’s own Autocrypt: header) is how it becomes believed, and also how the user starts receiving mail encrypted to it.

13.14.3.1. Finding the users who bring their own key

The rule above leaves a residue by design: a served address we hold no identity for is still trust-on-first-use, because that is the only channel by which a bring-your-own-GnuPG user’s real key can reach this host. What an operator can do about it is not a setting — it is an introduction. Import that user’s public key as an identity and the exposure is over for that address: from then on our own row pre-empts whatever the cache holds.

So the deployment needs a way to notice them, and that is pepsi-keys peer unclaimed at the terminal, or GET /api/v1/peers/unclaimed (see The administrative API): the addresses that are

  • served by this deployment (their domain is one of [pepsi-ingress] ACCEPTED_DOMAINS; the command also counts [pepsi-crypto] LOCAL_DOMAINS),

  • held by no active encryption identity of ours, and

  • nevertheless present in peer_key — usually harvested from their own outbound mail’s Autocrypt: header, which is exactly what a user running GnuPG in their own client produces.

Each row names the cached keys with their fingerprint and source, so an operator can tell a key the user themselves advertised (inbound) from a third party’s gossiped introduction (gossip) before acting on it, plus a count of how many identities — of any purpose or lifecycle state — the address does have. The report is read-only and changes nothing; it is a worklist, not an alarm, and an empty one is the ordinary state of a deployment whose users all hold identities here. The console’s Correspondent keys page (/ui/peers) lists the whole peer_key cache, not this subset.

The two differ in one default. The command lists only harvested keys — source inbound, inbound-signed or gossip, the keys learnt from mail itself, which is how a stranger plants one with a forged From: — because that is the exposure the report exists for; --all-sources widens it to discovered, manual and API keys, which is what the endpoint always returns:

pepsi-keys peer unclaimed                  # harvested and gossiped keys
pepsi-keys peer unclaimed --all-sources    # every cached key
pepsi-keys peer unclaimed --json           # [] when there is nothing to do

For each entry, confirm the key with its owner and then either register it as theirs (pepsi-keys identity import ADDRESS --protocol P --purpose U --public FILE, no --private) or drop it (pepsi-keys peer remove ID).

Note

Ask the user before importing. The key in the cache is one somebody advertised; confirming out of band that it is really theirs is what turns a trust-on-first-use row into a trusted one, and is the entire value of the exercise.

Which lifecycle states count differs between the two uses, for the reason expiry exists:

  • Encrypting to the address counts active identities only. A retired key must not receive new mail, and a deployment that retired a user’s key without issuing another is in the same position as one that never held a key for them — so discovery takes over.

  • Verifying a signature from the address counts everything but revoked. A signature made last year was made with last year’s key; refusing to look at it would report our own users’ mail as unverifiable every time a key rolled over. revoked is excluded because that is the operator saying the material must not be used at all.

13.14.4. The pipeline never blocks on a key server

Discovery is asynchronous and outside the stages. A stage that needs a key it does not have does no network I/O at all: it commits whatever it has already produced, pauses the message, and enqueues a request keyed on the address. A pepsi-keydisc instance answers the request and, in the same round-trip that stores the key, releases every message parked on that address.

Three consequences follow, each intended rather than a side effect:

  • A slow key server cannot hold a stage worker. That problem is removed rather than bounded — there is no worker waiting on it to bound.

  • A hundred messages to one correspondent cost one lookup. The request is keyed on the address, so they deduplicate onto it and are released together.

  • A request that settles without finding a key still releases its waiters. The services find keys; the stages decide about mail. Nothing in the discovery layer ever decides a message’s fate.

The methods run in parallel: every method in SOURCES starts at once, each as its own process (pepsi-keydisc@dane, @wkd-advanced, @wkd-direct, @vks, @ldap). The two Web Key Directory methods are separate ranks and therefore genuinely concurrent, not a fallback chain — running direct only “if advanced fails” would silently accept the weaker answer whenever the stronger one was merely slow. One process per method also means a hung LDAP bind cannot stall WKD, and that turning a method off is systemctl mask --now pepsi-keydisc@<method> (mask, because pepsi.target starts the four default instances and would start a merely disabled one again).

Keep SOURCES and the enabled units in step. SOURCES is the roster the stop rule waits for, so an instance whose method it does not list refuses to start, and a method it lists with nothing running costs every request the full TIMEOUT before it gives up.

13.14.5. RANK_GRACE: the speed-versus-thoroughness dial

Running everything at once raises one question: an answer has arrived from a mediocre source, and a better one is still running. Wait, or go?

RANK_GRACE is the single knob that answers it. When a lookup succeeds, every still-running method that ranks better is granted

RANK_GRACE × (how many ranks better it is)

of additional time, measured from the moment the answer in hand arrived. When that window expires, the best result in hand wins. The knob spans the whole range of reasonable policies:

Setting

Behaviour

0

The first usable answer wins outright. Fastest; the ranking then only arbitrates conflicts in the store, never the race.

5 s (default)

One rank up gets 5 s, three ranks up gets 15 s. A slow WKD-advanced server cannot hold a message behind a key-server hit that already arrived, but a nearly-as-fast better source still gets to win.

≥ TIMEOUT

Every method is waited for and the ranking applies in full. Slowest and most thorough; pepsi-setup notes this configuration rather than objecting to it, because it is a legitimate choice.

Two other deadlines bound the same fan-out: METHOD_TIMEOUT (15 s) is one method’s own network budget, and TIMEOUT (60 s) ends the whole request whatever is still running. A request that ends with nothing is not an error; it is a correspondent with no key.

13.14.6. The negative cache

When a request settles without a key, that outcome is remembered: for NEGATIVE_TTL (24 h) after an authoritative “there is no key here”, and for the much shorter ERROR_TTL (1 h) after a network failure — “the server was down” is worth re-trying sooner than “there is no key”.

The rule that follows:

A message for an address with a fresh negative entry never pauses. It takes the stage’s no-key path immediately.

Without that, every message to a correspondent who simply has no key would pause for the full TIMEOUT to re-learn an answer already known — turning one absent key into a permanent per-message delay for that whole correspondence. The accepted cost is the other direction: a key published five minutes ago stays invisible until the entry ages out. Lower NEGATIVE_TTL if that trade is wrong for your deployment; that is exactly what the option is for.

The same short-circuit fires when the deadline of an outstanding request has passed with nobody answering it — the signature of a deployment running no discovery service at all. The message takes the no-key path rather than parking again, which is what stops it parking for ever.

A lookup that fails in the DNS is not “no key”. pepsi-keydisc classifies a SERVFAIL, timeout or DNSSEC-bogus answer to an OPENPGPKEY/SMIMEA query, or a WKD host name that does not resolve, by also asking the domain’s MX and A/AAAA records, and records the verdict on the settled request. Where the no-key path would have been cleartext, pepsi-stage-encrypt defers a recipient whose domain does not answer at all. A recipient whose mail servers answer while its key records keep failing goes to the secure-link portal or is bounced, and the sender is told why; a local sender accepts cleartext with the [clear-ok] subject keyword or CLEAR_ON_DNS_FAILURE. A WKD fetch that fails over HTTPS, and a forged NXDOMAIN without DNSSEC, still read as “no key” (A key lookup that fails in the DNS).

13.14.7. Lookup privacy

Looking an address up tells somebody that you are about to write to it. Which somebody depends on the method: DNS tells the domain’s authoritative servers and your resolver’s path, WKD tells the correspondent’s own domain, and a key server tells its operator.

Lookups also happen without any mail being sent. The daily pepsi-keys-refresh.timer (pepsi-keys peer refresh) re-validates every cached peer key whose CACHE_TTL (24 h) has run out, and does so only through the method that found the key: a key from the key server (VKS_SERVERS, by default keys.openpgp.org) is re-checked there, a WKD key at the correspondent’s own Web Key Directory, a DANE key in DNS, an LDAP key in the directory. The key server is therefore asked, once a day, about the correspondents whose keys it supplied – not about every correspondent in the cache. Keys learnt from Autocrypt headers, gossip or attached keys, and keys entered by hand, are never refreshed over the network at all: their owner’s next message is what updates a harvested key, and a revocation published only on a key server for such a key is not seen. The refresh is what picks up a revocation, so switching it off has a cost. (The same service also runs pepsi-keys peer prune and the peer screen described under Peer keys.) The levers:

  • Remove vks from [pepsi-keydiscovery] SOURCES (and systemctl mask --now pepsi-keydisc@vks.service, which refuses to start for a method SOURCES does not name). No key server is then asked anything, neither on the message path nor by the refresh (a method missing from SOURCES refreshes nothing, not even the keys it once found); WKD and DANE still go only to the correspondent’s own domain.

  • ALLOW_DOMAINS / DENY_DOMAINS (below) apply to the refresh as well.

  • Raise CACHE_TTL to refresh less often.

  • systemctl mask pepsi-keys-refresh.timer stops the refresh altogether (mask, because pepsi.target would start a merely disabled timer again); cached keys are then never re-checked for revocation.

[stage-encrypt] DISCOVERY = no does not stop the refresh, which is not driven by any user’s mail.

Two controls limit the message-driven lookups, and they are not interchangeable:

[pepsi-keydiscovery] ALLOW_DOMAINS / DENY_DOMAINS

The operator’s, and the recipient-side one. A non-empty ALLOW_DOMAINS is exclusive — only those domains are ever looked up — and DENY_DOMAINS always wins over it. This is the control to reach for when the question is “never query that domain”.

[stage-encrypt] DISCOVERY = no

The per-user one, overridable per address through the pepsi.settings layer. Cached keys are still used; a cache miss goes straight to the no-key path instead of parking.

Important

The option’s name invites the wrong reading. The per-address settings layer resolves an outbound message on its envelope sender. So setting DISCOVERY = no for an address means

  • “this user’s mail never triggers a lookup” —

and not

  • “never look this correspondent up”.

There is deliberately no per-address recipient denylist: it would need a new column and a second list to stay consistent with DENY_DOMAINS, and two overlapping denylists that can disagree are worse than one that cannot. The recipient-side control is the operator’s, above.

13.14.8. When there is no validating resolver

DANE discovery is AD-gated: an OPENPGPKEY or SMIMEA answer the resolver did not DNSSEC-validate is refused outright. This is not the same policy as TLS Reporting, where a forged rua costs an attacker a copy of a report. An unvalidated key record is a key from whoever can answer for the zone, which is not an improvement on having no key at all — so an unvalidated answer is not a weaker answer, it is no answer.

Pepsi trusts a validating resolver rather than validating DNSSEC itself, the same operational model its DANE/TLSA support uses for transport security. The consequence:

Warning

A deployment without a validating resolver gets no DANE results at all — silently, because the method dutifully answers “no key” for every address, and the best-ranked source simply never wins. pepsi-setup probes for this and reports it, but the fix is yours: point Pepsi at a validating resolver (unbound, or systemd-resolved with DNSSEC=yes over a trusted path), or drop dane from SOURCES so nothing waits for it.

13.14.9. Inbound mail waits too

Verification pauses on the same mechanism as encryption: when an inbound signature is from a signer whose key is not cached, the message parks while discovery runs, so the first message from a new correspondent gets a real verdict instead of unverifiable.

That costs a real delay, on exactly the mail somebody is waiting for. Three things blunt it, and the first is the one to reach for:

  • INBOUND_TIMEOUT is separately tunable. An operator who feels this delay can drop it to a few seconds without touching the outbound TIMEOUT at all. pepsi-setup warns above five minutes.

  • The negative cache means the second and later messages from an unknown signer never pause — only the first pays.

  • Requests deduplicate per address, so a flood from one signer costs one lookup rather than one per message.

Whether the parked row holds plaintext depends on the protocol. Under the layering rules an inbound signature is inside the ciphertext, so the decryption has to happen before the signer — and therefore the missing key — is even known. What may then be committed differs:

  • An S/MIME signature nested inside an envelope survives decryption as an ordinary MIME layer, so the message is parked with the plaintext committed and is decrypted exactly once.

  • An OpenPGP signature lives only inside the packet stream and is gone the moment the plaintext is out. Committing the plaintext would destroy the very evidence the key is being fetched to check, so such a message is parked unchanged and decrypted again on resume. The second decryption is the price of a correct verdict.

Note

One exposure. A message parked with its plaintext committed — the S/MIME case above — sits in pepsi.workqueue decrypted for up to INBOUND_TIMEOUT.

This is the same exposure delivery would create a moment later anyway: the mailbox gets plaintext. It is a longer window, not a new one. If that window matters to you, it is INBOUND_TIMEOUT that sets its length (Decrypted mail, keys or subjects persisted to logs and local storage). See pepsi-stage-decrypt for the rule as the stage applies it.

13.14.10. Who uses the store

pepsi-keys peer refresh --address exercises the whole discovery fan-out — the sources, the ranking, the request queue and the negative cache — end to end.

pepsi-stage-encrypt signs locally submitted mail as its From: author and encrypts it per recipient, parking a message whose recipient key is not cached until a discovery service settles the request. pepsi-stage-decrypt is its inbound counterpart: it opens mail addressed to recipients this host serves — trying every non-revoked identity of theirs, including expired ones, because old mail must stay readable — verifies the signature against the peer_key cache and the ca_trust anchors, and reads whatever key material the message itself carries. It parks on the signer’s key the same way, so even the first message from a new correspondent gets a real verdict rather than unverifiable. What it does not do is write to the store: the certificates and Autocrypt: headers a message carries are used in memory to check that message’s own signature and then dropped. pepsi-stage-autocrypt-learn is the stage that learns them.

Re-encryption for storage. A message Pepsi decrypts is filed in the mailbox as plaintext by default, which is what makes server-side decryption useful at all – the gateway model assumes the mail store is trusted. For a user who registered their own MUA key, pepsi-stage-reencrypt closes that gap: placed immediately before local delivery, after every stage that reads the content, it seals a message that the decrypt stage opened with the MTA key to the user’s active MUA keys (every one of the newest key’s protocol, at most MAX_CLIENT_KEYS), so the mailbox holds ciphertext only their clients can open. It adds no signature (the decrypt stage’s verdict stays in X-Pepsi-Crypto), needs no privilege (the key is public), and leaves mail that arrived in cleartext alone. For a user without an MUA key, [stage-reencrypt] ON_NO_CLIENT_KEY chooses: plaintext (the default) files it unencrypted; bounce refuses it with a DSN that returns neither body nor subject, so the refusal cannot return the plaintext to whoever sent the ciphertext (Bounces after gateway decryption reveal decrypted content). The option is per recipient through pepsi-settings, so one user can insist on it while the site default stays lenient:

pepsi-settings set bob@example.org reencrypt ON_NO_CLIENT_KEY bounce

13.15. A CLI walk-through

Give an address an OpenPGP identity, look at it, and check that GnuPG agrees the public half is a key:

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

Give the same address S/MIME material — a signing and an encryption certificate, each self-signed for immediate use, with a certificate request over each key to send to a CA:

pepsi-keys identity generate alice@example.org --protocol smime --csr

When the CA answers, store its certificate over the key that is already in the store and make it the primary signing material. Nothing is re-keyed and nothing already sent stops being readable:

pepsi-keys identity import alice@example.org \
    --protocol smime --purpose sign --public alice-sign.pem --primary

Publish the address in a signed zone:

pepsi-keys dns alice@example.org >> example.org.zone

Withdraw a signing key after a laptop is stolen. The private half is destroyed at once; the public half stays so last month’s signatures still verify:

pepsi-keys identity revoke 1 --reason 'laptop stolen'
pepsi-keys identity show 1        # private material: purged at …

Retire everything that has passed its validity — the same rule, applied in bulk, and what the packaged pepsi-keys-retire.timer runs daily:

pepsi-keys identity retire

Trust a correspondent’s key by hand and pin it, so a later discovery answer cannot replace it:

pepsi-keys peer import bob@example.com --protocol openpgp --file bob.pgp --pin
pepsi-keys peer show bob@example.com

Decide which CAs an inbound S/MIME signature may chain to, and for which mail domains each one may vouch – an anchor added for one partner should not make a signature from any other domain read valid:

pepsi-keys ca add /etc/ssl/certs/our-ca.pem --label 'Our CA' --domain example.org
pepsi-keys ca scope 2 --domain partner.example
pepsi-keys ca list

See which keys the forward-secrecy profile would replace or destroy today:

pepsi-keys identity rotate-due --dry-run

And, once a year or after an incident, roll the key-encryption key:

pepsi-keys wrap rotate --dry-run
pepsi-keys wrap rotate

13.16. Configuration summary

The algorithm and security policy live in [pepsi] and are administrator-only: they are security decisions with secure defaults, not preferences, and because the per-address override layer only overrides [stage-<name>] sections they are structurally out of reach of pepsi-stage-edit-settings and any web-admin surface.

Those options are CRYPTO_ALLOW_DOWNGRADE, CRYPTO_ALLOW_WEAK_DIGESTS, CRYPTO_MIN_RSA_BITS, CRYPTO_GENERATE_RSA_BITS, CRYPTO_INLINE_PGP, CRYPTO_OPENPGP_ALGORITHM, CRYPTO_SMIME_ALGORITHM, and CRYPTO_SMIME_SHARED_KEY. By default they refuse SHA-1 signatures, and MD5 ones under every setting (SHA-1 collisions; weak signature digests still produced or accepted), and RSA keys below 2048 bits (Short keys and weak digests in deployed certificates and keyrings). RSA keys whose private half can be computed from the modulus are refused at any size, with no option to accept them: the ROCA fingerprint of Infineon’s RSALib, and primes close enough for Fermat’s method. So is a key of any type on the known-compromised list (pepsi.compromised_key: the badkeys list, including the Debian OpenSSL weak keys, which pepsi-keys blocklist update keeps current, and what the daily pepsi-keys peer screen factored; Security model). CRYPTO_GENERATE_RSA_BITS accepts 2048, 3072, 4096 or 8192 only, the sizes generated in constant time; CRYPTO_ALLOW_DOWNGRADE decides when S/MIME gives up authenticated encryption: negotiate (the default) only for a recipient recorded as unable to read it, yes for every recipient, no never, refusing such a recipient instead (EFAIL: CBC/CFB malleability gadgets exfiltrate decrypted mail, Which S/MIME container a correspondent gets).

The key store’s own custody and lifecycle settings live in [pepsi-crypto]: KEY_WRAP_SECRET and KEY_WRAP_KEY_ID (plus KEY_WRAP_SECRET_<ID> for a retired key), AUTO_CREATE_IDENTITY, IDENTITY_VALIDITY_DAYS (730 by default), the forward-secrecy profile’s ENCRYPTION_ROTATION_DAYS (0, off) and RETIRED_PRIVATE_GRACE_DAYS (30; The forward-secrecy profile), and the locality options LOCAL_DOMAINS / RECIPIENT_DELIMITER / TARGETS that decide which account an address belongs to. A deployment that does no end-to-end cryptography can omit the section entirely; as soon as it says anything, pepsi-setup insists on a usable KEY_WRAP_SECRET, since a key store that cannot store keys is a configuration mistake rather than a preference. The exhaustive reference is pepsi.conf(5).

The pEp-style behaviour and the self-service are [stage-encrypt] options, per-address overridable: ENABLE_PEP (default yes), ATTACH_KEYS_AS_FILES (default no), KEYS_CONTROL_LOCAL_PART (default pepsi-keys) and RESPONSE_STAGE (unset means no notices and no e-mail commands).

Key-server publication has its own section, [pepsi-keys]: VKS_PUBLISH (off by default; whether keys made by hand start with their upload requested), VKS_SERVER (defaulting to the first [pepsi-keydiscovery] VKS_SERVERS entry, so a deployment that already chose a key server to read from does not name it twice), and the retry knobs VKS_MAX_ATTEMPTS, VKS_RETRY_INTERVAL and VKS_BATCH. Web Key Directory publication needs no configuration at all: it follows each identity’s published flag.

The managed PKI is configured per domain in the database (pepsi-keys mpki domain set, Certificates from a commercial CA: the managed PKI). Its section in the file, [pepsi-mpki], names only where the CA credentials are (CREDENTIAL_DIR), the deadline of a request to the CA (TIMEOUT), and where and from whom notice mail is sent (NOTIFY_STAGE, NOTIFY_FROM).

13.17. See also

The two stages that use this store are pepsi-stage-encrypt (outbound) and pepsi-stage-decrypt (inbound); The secure-link fallback portal is what happens when a correspondent has no key at all, and Client interoperability records which third-party clients have actually been measured against what those stages emit. pepsi-keydisc is the discovery service, pepsi-keys the operator CLI and pepsi-stage-vks-confirm the key-server confirmation follow-up. RFC Index maps each standard named here to the module that realises it, and Microsoft Exchange as a gateway is the deployment shape that this store is designed for.

pepsi-keys, pepsi-setup, Architecture, Configuration, pepsi-keys(1), pepsi.conf(5), pepsi-setup(1).