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 addressesThe 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 (
openpgporsmime), 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 addressesRemote correspondents’ public keys and certificates, cached however they were obtained. This is what encrypts outbound mail and verifies inbound signatures. Each row carries the
sourceit 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 anchorsThe 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://andhttps://only,[pepsi-keydiscovery] CRL_FETCHandCRL_MAX_BYTES) intopepsi.crl_cache, refetching at each list’snextUpdateand 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_FETCHis on, a chain that the signer sent without its intermediates is completed frompepsi.ca_issuer_cache, which holds the CA certificates that pepsi-keydisc fetched from the certificates’caIssuerspointers. 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’sON_NO_KEYroute 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/DELETEacross the schema, sequences, functions) plus thecrypto_identity.private_wrappedcolumn – the only role granted it, apart from the schema ownerpepsi-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) andpepsi-httpdhave their table-level grant oncrypto_identityrevoked and replaced with a column-levelSELECTof every column exceptprivate_wrapped, noINSERT, andUPDATEof only the columns their code writes: theis_primary,publishedandvks_wantedflags, plus, forpepsi, the key-server progress columns thatpepsi-stage-vks-confirmrecords;pepsi-ingressandpepsi-telemetryhave 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 ( |
An MUA key ( |
|---|---|---|
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 |
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
|
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 |
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 |
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:
Planting a key for one of our users. Harvesting and gossip learn keys from mail anybody can send, so a forged
From: alice@our-domaincan seed a cache row for Alice. For any address we hold an identity for, our own key pre-empts the whole cache (Our own users’ keys are not discovered), so the planted key is never used. For a served address with no identity it is trust-on-first-use (TOFU and key continuity miss first-contact and new-identity attacks), and Finding the users who bring their own key describes the remedy.Substituting a correspondent’s key. Only as far as the trust ladder allows: a better-ranked source always wins a conflict, a third party’s gossip can never displace what the owner advertised, and
MIN_TRUSTdecides how far down the ladder encryption is still used (Keys of correspondents).
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 = alwayscounts 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¶
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).The user is wanted. The domain’s enrolment mode and the user’s selection decide that (Who gets a certificate).
An order is planned.
pepsi-keys mpki run, whichpepsi-keys-mpki.timerstarts 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).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.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).
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.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
SMIMEArecords 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.
allEvery user in the list gets one, whether they have sent mail or not.
manualOnly 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:
headerThe display name of the first message that the user sent, split into a given name and a surname. Pepsi reads
Surname, Givenas 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.,Mrand 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.ldapA directory import (
mpki user import --ldif):givenNameandsn, orcnsplit like a display name where one of them is missing.localEntered by an administrator, with
mpki user add,mpki user setor 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 |
|---|---|---|
|
The name came from a header and the domain does not trust header names. |
|
|
The user has no given name or no surname. |
Entering both ( |
|
The domain has no CA credential file. |
|
|
The domain’s new enrolments of the last 24 hours reached
|
|
|
The CA account has no free licence for the address
( |
Adding a licence in the CA’s portal, then |
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¶
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.
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 checkorders nothing; it says whether the key is accepted, the product is available, which organisation sponsors the certificates, and whether the domain is validated.Add the users, or let their first messages register them, and confirm the names that came from headers.
pepsi-keys mpki user listmarks an unconfirmed name with?. The console’s Certificates pages offer the same settings and user actions to an administrator withkeys:write(Managed certificates); the credential and the orders stay on the command line.Watch the first orders with
pepsi-keys mpki order list --openandpepsi-keys mpki notices;pepsi-keys mpki runstarts 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 asnoreply@a domain we do not receive mail for gets no key.Cleartext is not signed. The default
SIGNbecomesencrypted-only: a signature lives inside the ciphertext, and cleartext carries the key but no signature, so recipients who do not use cryptography never see asignature.asc.[sign]orX-Pepsi-Sign: yesstill 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 theFrom:) carries a key that the address does not have yet; for the address’s very first key, an attachedapplication/pgp-keysfile naming the address also counts. This happens only when the submitter may speak for theFrom:address: a trusted relay (MYNETWORKS, a client certificate), or an authenticated account whoseFrom:matched a concrete, wildcard-freeUSERNAME_MAPentry or its defaultlogin@HOSTNAME(state.origin.from_bound). An account granted*@example.orgmay send as its colleagues but never registers a key for them;pepsi-setuplists such accounts.By the user, through the web console or by e-mail (below).
By the operator, with
pepsi-keys identity importwithout--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-keysidentity show,identity generate,identity import(without--private),identity publish --vks,identity revoke, andotpfor 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 enqueuegenerate-identity/register-client-key/revoke-identitytasks thatpepsi-setup applyre-validates and performs as thepepsi-cryptorole – 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 aspepsi-keys identity revoke. An S/MIME identity’s page adds the certificate round trip: Request a certificate enqueuesidentity-csr(the PEM request appears on the task’s page) and Install the issued certificate enqueuesidentity-certificate, which the applier performs only for a certificate over the identity’s own key that names its address – the sameidentity csr/identity importround trip, without a terminal. Without thepepsi-httpd-adminpackage those five degrade to read-only like every other applier path. See The administrative API and The administration console.A message from the user to
pepsi-keys@<their domain>([stage-encrypt] KEYS_CONTROL_LOCAL_PART) with the command in theSubject:–status,generate,register(taking the key from this message’sAutocrypt: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 butstatusalso 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 isstatus, so a command an outsider planted in a message the user merely answers changes nothing. It needsRESPONSE_STAGEto be set, and works only when the submitter may speak for theFrom:address (as above). It is handled in the encrypt stage itself, which already runs aspepsi-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 theSubject:, e.g.register 123456orretire 89ABCDEF01234567 otp=123456. A message’sAutocrypt:header or attached key file no longer registers a key for that address;registerwith 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 anotpfield (the console’s forms have one), which the setup applier checks –pepsi-httpditself 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 anExpires: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 enrollthe 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, andotp enrollstarts again. The answer repeats the advice to delete the enrolment reply.pepsi-keys otp enroll ADDRESSAt 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 CODERemoves 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 ( |
yes, immediately |
the identity’s |
Key server |
a third party |
no |
the identity’s |
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-mailgenerate– take[pepsi-keys] VKS_PUBLISHas 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}withvks_wanted, or the e-mailpublishcommand.
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 ofpepsi-keys identity publish --retry(hourly frompepsi-keys-publish-retry.timer), which retries it like an upload;the reply – the
retireanswer, 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);OPENPGPKEYandSMIMEAagainst 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 checkA
published keysgroup with one line per address; only a mismatch makes the check fail.pepsi-statusA section Published keys as served: how many addresses agree, and every channel of every address that does not.
--offlineskips it.pepsi-keys identity list --servedA SERVED column naming the channels that serve each identity’s fingerprint (
nonefor 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:
Create it at a served domain, so the Web Key Directory serves it, in the protocol your recipients’ clients check — OpenPGP by default,
--protocol smimefor an S/MIME certificate (one a public CA issues is the one most clients accept without asking;--csrwrites the request):pepsi-keys identity generate notices@example.org --protocol openpgp --name "example.org notices"
Set
NOTICE_SIGNER = notices@example.orgin the[stage-notice]section the wizard wrote (or add one:PROGRAM = pepsi-stage-encrypt,NEXT_STAGE = dkim-sign), and point everyRESPONSE_STAGE,BLOCK_RESPONSE_STAGE,[pepsi-admin] ENROL_STAGEand[pepsi-secure-link] NOTIFY_STAGEat it. Runpepsi-setup validate.Check what is served:
pepsi-keys identity list --served(above).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.orgfrom 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 comesFrom:the signer’s address. A client accepts a signature only from a key that belongs to theFrom:address, so it checks the notice’s signature as it would any other; the address the notice was composed with becomes itsReply-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:
put the new secret in
secrets.d/pepsi-crypto.secretasKEY_WRAP_SECRET, and keep the old one beside it asKEY_WRAP_SECRET_<OLD-ID>(the suffix is the oldwrap_key_id, upper-cased);point
[pepsi-crypto] KEY_WRAP_KEY_IDat the new id;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 thanENCRYPTION_ROTATION_DAYSis replaced. The new key is made the waypepsi-keys identity generatemakes 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 reasonsupersededthrough the same path asidentity 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 thepepsi-keys-publish-retry.timerjob. 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_DAYSago, 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 aspepsi-keys identity forget-privateand leaves the samekey.identity.forget-privateaudit 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 bypepsi-keys-blocklist.timerten minutes after it starts and then daily, asks[pepsi-keydiscovery] BADKEYS_URLwhether 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 bypepsi-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.rotaterow 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-statussummarises the last 30 days of them;with
RESPONSE_STAGEset on pepsi-stage-autocrypt-learn, each local recipient of the message that caused it is mailed a notice naming the correspondent and both fingerprints (thekey-rotation.<lang>.bodytemplate), 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) orgossip(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-rotationtelemetry 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
*@domainrow is consulted only when no exact row exists, andpepsi-keys peer showmarks 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 theFrom: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¶
daneDNS
OPENPGPKEY(RFC 7929) andSMIMEA(RFC 8162), under a hashed local part. Refused without the resolver’s DNSSEC AD bit — see When there is no validating resolver.wkd-advancedThe Web Key Directory at
openpgpkey.<domain>— a host the domain had to delegate deliberately. The HTTPS fetches of the two WKD methods andvksverify the server certificate against the system root store, or against the CA certificates of[pepsi-keydiscovery] TLS_CA_BUNDLEwhen it is set (see “Key-discovery certificate authorities” in Security model).wkd-directThe Web Key Directory at the domain itself,
<domain>/.well-known/openpgpkey.ldapA configured directory. Optional, and compiled in only with the
ldapcargo feature, because a deployment with no directory should not link one.vksA verifying key server (
keys.openpgp.orgby 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-signedHarvested like
inboundbelow, from a message whose DKIM signature passed at ingress, was aligned with theFrom:domain and covered the key’s carrier — theAutocrypt:header listed in itsh=, or the body for an attached key or signer certificate. The sending domain, not merely theFrom: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 aninboundfind to this rung from the verdicts ingress recorded.inboundHarvested from a message that already arrived — an
application/pgp-keyspart, an S/MIME signer certificate, or anAutocrypt:header. Only material claiming the sender’s own address is kept; that address comes from the unauthenticatedFrom:, 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 inSOURCES. Written by pepsi-stage-autocrypt-learn, not by the decrypt stage.gossipRead 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 ownTo:,Cc:orReply-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. Likeinboundit is not a service and may not appear inSOURCES; 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/apiAn 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 |
|
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 |
1 |
|
An operator who typed a fingerprint in meant it. Its |
2 |
|
The only source with cryptographic provenance: the domain published it and DNSSEC proves the answer was not rewritten in transit. |
3 |
|
Fetched over verified HTTPS from |
4 |
|
The same, from the domain itself. A weaker signal of intent than a dedicated host, hence its own rank. |
5 |
|
A directory the operator configured, and therefore semi-trusted — but still a directory somebody else runs. |
6 |
|
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 |
|
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 |
8 |
|
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 |
9 |
|
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’sAutocrypt: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
activeidentities 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.revokedis 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 |
|---|---|
|
The first usable answer wins outright. Fastest; the ranking then only arbitrates conflicts in the store, never the race. |
|
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. |
|
Every method is waited for and the ranking applies in full. Slowest and
most thorough; |
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
vksfrom[pepsi-keydiscovery] SOURCES(andsystemctl mask --now pepsi-keydisc@vks.service, which refuses to start for a methodSOURCESdoes not name). No key server is then asked anything, neither on the message path nor by the refresh (a method missing fromSOURCESrefreshes 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_TTLto refresh less often.systemctl mask pepsi-keys-refresh.timerstops the refresh altogether (mask, becausepepsi.targetwould 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_DOMAINSThe operator’s, and the recipient-side one. A non-empty
ALLOW_DOMAINSis exclusive — only those domains are ever looked up — andDENY_DOMAINSalways wins over it. This is the control to reach for when the question is “never query that domain”.[stage-encrypt] DISCOVERY = noThe per-user one, overridable per address through the
pepsi.settingslayer. 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_TIMEOUTis separately tunable. An operator who feels this delay can drop it to a few seconds without touching the outboundTIMEOUTat all.pepsi-setupwarns 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).