17. Security model

This chapter says what Pepsi defends against, what it does not, and what an attacker gets from each thing they might have taken — so it is as useful after a compromise as before one.

Pepsi is an MTA that holds private keys and can read mail, which makes it worth attacking. The design keeps asking one question: when this component is compromised, what is still out of reach? Where the answer is “nothing”, that is said here rather than left to be discovered.

The claims are stated in Threat model: which assets, against which adversaries, in which custody mode. This chapter describes the mechanisms behind them.

17.1. What Pepsi assumes

If one of these is false, the guarantees below do not hold:

  • The host is not already compromised. Nothing here defends against root on the machine. Root can read every key, every secret and every message.

  • PostgreSQL authenticates by peer credentials over a local socket. Each component connects as its own operating-system user, and the database grants that role only what the component needs. A deployment that switches to password authentication with one shared account throws away most of An attacker who has the database.

  • The operating system enforces file ownership and the setuid bit. The private-key boundary is a database GRANT keyed on the effective uid; a nosuid mount or a shared account collapses it.

  • A validating DNS resolver on loopback, or one reached over an authenticated channel. Pepsi trusts the AD bit rather than validating DNSSEC itself (see pepsi-stage-relay-to-internet and The path to the resolver). A lying resolver, or anyone on the plain-DNS path to a resolver across a network, defeats DANE and downgrades MTA-STS to trust-on-first-use. DNS setup is outside Pepsi’s scope; the recommended setup is a validating recursive resolver of one’s own on the host, such as unbound, and the alternative is a validating resolver that the operator trusts, named in [pepsi] DNS_SERVERS as DNS over TLS or HTTPS. When DANE is in use, pepsi-setup warns if a resolver that it relies on does not set the AD bit, and states plainly, by IP address, every resolver off this host that the installation thereby trusts with DNSSEC validation. Every relay worker with DANE on, and the pepsi-keydisc@dane discovery service, logs a warning when it starts if a resolver is reached over plain DNS from another host, and if a resolver does not validate. The second check is a probe for the signed ietf.org SOA: an answer without the AD bit leaves DANE configured but inert. pepsi-status reports both in its “DNSSEC resolver” section, so a resolver changed after setup is noticed. None of them refuses such a resolver: choosing it is the operator’s decision. What the AD bit gates is enforced as RFC 7672 requires: both relay stages default to DANE = strict, so a peer with DNSSEC-signed TLSA records gets mandatory TLS and a certificate that matches none of them defers the message (DANE = warn is an explicit opt-out that only logs the mismatch).

  • TLS certificate material is not attacker-supplied. Certbot integration writes into /etc/letsencrypt; an attacker who can write there can impersonate the server.

17.2. The privilege split

Upholds

A compromised component (what each compromised account reaches), A local shell user (no role reachable from an ordinary account) and Somebody holding a copy of the database (what a service role can write).

Pepsi is not one program. Each component runs as its own account, and the separation is enforced by the database as much as by the filesystem.

The database side draws two kinds of line, and it is worth being exact about both.

The pipeline role is broad on purpose. pepsi (the dispatcher and every ordinary stage) and pepsi-crypto hold one blanket grant: SELECT, INSERT, UPDATE and DELETE on every table in the pepsi schema, use of every sequence, EXECUTE on every function, and the same as default privileges for objects created later. Every stage reads and writes the queue, and between them the stages use every pipeline table, so least privilege per stage would need an account per stage; the consequence is stated in Threat model rather than hidden. The grant is then taken back where the pipeline has no business:

  • crypto_identity: SELECT only on the columns other than private_wrapped, no INSERT, and UPDATE only of the use flags (is_primary, published, vks_wanted) and the key-server progress columns that pepsi-stage-vks-confirm records (DELETE has no column granularity and stays); pepsi-crypto alone holds private_wrapped and may write what an identity is – its address, protocol, purpose, fingerprint and public half;

  • config_override: SELECT only — writing it is the pepsi-config role’s (pepsi-httpd writes through a [pepsi-admin] CONFIG_DB connection that authenticates as that role);

  • setup_task and setup_task_log: nothing; only pepsi-config may INSERT a task;

  • secure_message and secure_access: INSERT, DELETE and SELECT of every column but ciphertext on secure_message; SELECT and DELETE on secure_access;

  • admin_account, admin_session, api_token, own_enrolment and own_session: nothing;

  • otp_key and otp_pending: nothing (pepsi-crypto alone holds them, see A second factor for key management);

  • crl_cache and ca_issuer_cache: SELECT only — only pepsi-keydisc writes the CRL cache and the fetched intermediates;

  • compromised_key and compromised_key_import: SELECT only for pepsi — pepsi-crypto alone writes the known-compromised-key list;

  • the managed-PKI tables mpki_domain, mpki_user, mpki_order, admin_notification and crypto_identity_chain: nothing for pepsi. pepsi-crypto (pepsi-keys mpki and the encrypt stage) holds them, and is the only role that may read mpki_order.key_wrapped (Certificates from a commercial CA);

  • schema_file: SELECT only, for every service role;

  • event_log and mail_log: append-only (no UPDATE/DELETE).

The services that are not the pipeline get what they use. Their grants come from an audit of every statement that each of them can issue, in its own crate and in every library that it links, following calls into stored functions. pepsi-setup refuses to finish if PostgreSQL disagrees:

Role

Granted

Notably not

pepsi-ingress

INSERT into workqueue and workqueue_body (through workqueue_add) and SELECT of the new ids; SELECT of the two generated size columns (header_octets, octets) that the queue admission check sums; SELECT on config_override, mailbox_quota, login_assignment, crl_cache (the revocation lists that client certificates are checked against; it may only register a distribution point, through crl_cache_register) and the downloaded IP blocklists (ip_blocklist, ip_blocklist_source, written by pepsi-reputation as pepsi); SELECT of mailing_list’s list_name and mail_host (a list’s address, for the recipient check); INSERT on the two append-only logs.

Any other message in the queue, settings, whitelists, keys, anything about a list beyond its address. A parser bug in the process listening on port 25 reaches one table, to add to it.

pepsi-telemetry

Its telemetry table.

Everything else, so a collector sharing a database with a pipeline cannot reach the mail.

pepsi-httpd

The administrative credential tables (with the end users’ own_enrolment/own_session), the portal, the key tables (not private_wrapped; on crypto_identity only DELETE and the is_primary/published/vks_wanted flags are writable), the list and archive tables, event_log/mail_log for appending and pruning but not UPDATE, so not even the web tier rewrites a record (pepsi-httpd prune, run by pepsi-log-prune.timer, prunes them); on workqueue the envelope, state and routing columns, INSERT (mail the web forms send) and DELETE; on workqueue_body INSERT and DELETE (a body goes with the last message carrying it; the foreign key refuses any other) and the id and size columns only; read-only statistics, dns_address, tls_session, mailbox_quota, the DMARC aggregate reports (dmarc_report, dmarc_report_record: a console that could write them could make p=reject look safe) and telemetry_client (the telemetry daemon’s liveness row); SELECT on setup_task; the managed PKI’s settings and users (mpki_domain, mpki_user: SELECT, INSERT, UPDATE), its orders (every column but key_wrapped) and the stored CA chains, read-only, and the administrators’ notices, read-only but for marking them read.

A queued message’s headers or body — the console lists envelopes and has no read path to content, nor can it repoint a message’s body_id at another message’s body; settings, whitelist, vacation_reply, payment_request_reply, the secretary tables, telemetry, origin_nonce, auto_pay_spend, list_post_rate, archive_category, archive_tag, mta_sts_policy, list_confirmation, crl_cache, ca_issuer_cache, smime_capability, compromised_key, compromised_key_import, login_assignment, ip_blocklist, ip_blocklist_source, reputation_check, signed_sender, otp_key, otp_pending, mpki_order.key_wrapped (the keys of orders that wait for their certificate), writing or deleting an order, a chain or a notice; writing statistics, quota or the telemetry daemon’s liveness row; config_override and setup_task except through its pepsi-config connection.

A table that a later schema patch adds is not in pepsi-ingress’s or pepsi-telemetry’s reach until a patch grants it: their default privileges are revoked too.

The roles outside this set are narrower still: pepsi-keydisc, pepsi-whitelist and pepsi-config each hold grants on a few named tables only. pepsi-crypto holds the blanket grant plus private_wrapped. The schema owner, pepsi-owner, which pepsi-setup itself connects as, holds everything by ownership.

Component

Runs as

What it can reach

pepsi-ingress

pepsi-ingress

INSERT into the queue and the two reads above; the SRS secret; TLS material. No other message, no private key material, no setting, no whitelist.

pepsi-dispatch and most stages

pepsi

The pipeline grant above: the queue, settings, statistics, whitelist, and the secure-link tables without their ciphertext; the signing socket of pepsi-dkim. Not crypto_identity.private_wrapped, not a DKIM or ARC private key.

pepsi-stage-encrypt / -decrypt

pepsi-crypto (setuid, mode 4750 pepsi-crypto:pepsi)

The ordinary pipeline access every stage has, plus the wrapped private key material and the key-encryption key. Nothing else holds both: the schema owner pepsi-owner can read the column too, but not the key-encryption key.

pepsi-keys

the invoking operator

Installed 0755, with no setuid bit: one binary able to open every private key in a deployment is a far larger prize than pepsi-whitelist’s single table, so by default only root or the pepsi-crypto account can use it, and the PostgreSQL grants are the authority. A site that wants users to manage their own identities may deliberately make it setuid pepsi-crypto (chmod 4755), at which point the program’s own per-identity ownership rule starts applying — see Key management.

pepsi-httpd

pepsi-httpd

The tables in the second table above — read and write, not read-mostly: its handlers change queue routing and key metadata directly. No message headers or bodies, no private key material, no settings or whitelists; no ability to write the configuration overlay or enqueue a setup task except through its pepsi-config connection.

pepsi-keydisc

pepsi-keydisc

The discovery request queue, peer_key, the S/MIME CRL cache crl_cache and the fetched intermediates ca_issuer_cache (the only writer of both). Never a general UPDATE on pepsi.workqueue: two columns (status, timeout), to release a parked message, and SELECT on the four it needs to find one (workqueue_id, status, state, timeout) – not the envelope, the headers or the body.

pepsi-dkim

pepsi-dkim

No database role. The DKIM and ARC private keys in its own 0700 state directory, and secrets.d/pepsi-dkim.secret (the TSIG key of DNS_UPDATE = rfc2136). See The DKIM signing daemon.

pepsi-whitelist

invoking user (setuid)

SELECT/INSERT/DELETE on pepsi.whitelist only.

pepsi-quota

pepsi (setgid pepsi-maildir, mode 2550)

pepsi.mailbox_quota, and — through the group — the setuid-root helper that measures a mailbox.

Mailbox quota keeps its measuring and its refusing apart. Only pepsi-helper-maildir-writer can look inside a Maildir (mode 0700; it is the one program that becomes the user), and only members of pepsi-maildir may run it. pepsi-ingress is deliberately not in that group, and pepsi-setup warns if anyone adds it. So the process listening on port 25 can read a measurement that somebody else took and refuse a recipient on it, and can do nothing else: pepsi-setup revokes its write access to pepsi.mailbox_quota, leaving SELECT. Both roads to the accounting are closed to it, and neither closure relies on the other.

The crypto stages are setuid, not setgid: PostgreSQL peer authentication keys off the effective uid, so a stage that merely gained a group would still connect as pepsi and be refused the key column. It has to be pepsi-crypto.

17.2.1. Every program carrying a bit

Upholds

A local shell user: a local account gains no Pepsi role, and each helper acts with the target user’s authority only (boundary B4).

A multi-call binary cannot carry a per-program setuid or setgid bit, so each of these is installed as its own executable rather than as a symlink into the shared pepsi binary (the authoritative list is STANDALONE_BINARIES in the Makefile; the modes are applied by make install and, on Debian, by dpkg-statoverride from the postinst). Everything not listed here is unprivileged.

Program

Owner and mode

Why

pepsi-helper-maildir-writer

root:pepsi-maildir 4750

Becomes the recipient to write into a 0700 Maildir.

pepsi-stage-relay-to-maildir

pepsi:pepsi-maildir 2550

The setgid bit is the sole gate on exec’ing that helper, so the mode is 2550 and not 2755: world-execute would hand every local account egid=pepsi-maildir. The pepsi user is deliberately not a group member and gets the exec right by owning the file.

pepsi-quota

pepsi:pepsi-maildir 2550

Same helper, so a reconcile sweep can re-measure from a timer without being root.

pepsi-helper-dot-forward

root:pepsi-forward 4750

Drops fully to the user before reading their ~/.forward, and runs a |command with an environment built from the user’s passwd entry, inheriting nothing from its caller.

pepsi-stage-dot-forward

pepsi:pepsi-forward 2550

The same gate, for that helper.

pepsi-helper-auto-pay

root:pepsi-wallets 4750

Drives the wallet as the account that owns it: a local user at or above UID_MIN, or an account whose primary group is pepsi-wallets. Runs only the system-wide taler-wallet-cli fixed at build time (TALER_WALLET_CLI), and only while that file and every directory above it are owned by root and writable by nobody else; the caller cannot name another program.

pepsi-stage-auto-pay

pepsi:pepsi-wallets 2550

The same gate, for that helper.

pepsi-stage-relay-to-smarthost

pepsi:pepsi-token 2550

Reads the group-restricted OAuth token files that pepsi-helper-token-refresh writes, the mutual-TLS client key and the Kerberos credential cache. 2550 for the same reason as the stages above: the stage accepts -c, so world-execute would let any local account point it at a server of its own and send it those credentials.

pepsi-whitelist

pepsi-whitelist:pepsi-whitelist 4755

World-executable on purpose: any local user may manage their own namespace, and what stops them touching another’s is the rule inside the program, not the file mode.

pepsi-stage-encrypt, pepsi-stage-decrypt

pepsi-crypto:pepsi 4750

Peer authentication keys off the effective uid, so the stage has to be the role granted crypto_identity.private_wrapped. Group pepsi and no world-execute: unlike pepsi-whitelist these are not user commands.

pepsi-keys

0755, no bit

See the table above. A site may make it setuid pepsi-crypto.

pepsi-helper-mailbox-scan

0755, no bit

The unprivileged half of the pepsi-whitelist pair: it parses hostile mailbox files, so it is spawned with setresuid to the invoking user — all three ids, so it can never regain the owner.

17.2.2. The runtime directory is an ACL, not a shared group

Upholds

A local shell user and A compromised component: a socket is reachable by the accounts meant to reach it, and creating one grants no unrelated authority.

/run/pepsi holds sockets that belong to several different accounts: pepsi-ingress’s local submission socket, pepsi-httpd’s admin socket, the reverse-proxy socket that the front web server connects to, and the applier doorbell. The directory is owned by root, with a POSIX ACL that grants pepsi-ingress and pepsi-httpd write access by name (debian/pepsi.tmpfiles). A shared group would not do: it would have to be a group that both are in, and every candidate carries something that neither should gain. Group pepsi reaches the DKIM signing socket, and group pepsi-admin is the administrative API’s access control. pepsi-httpd.service alone runs with pepsi-admin as a supplementary group, so that it can hand its admin socket to that group: the group owns no file and grants nothing but administrator status on that socket, which the process that serves it has anyway. pepsi-ingress never gets it.

Mode 0775 on that directory is therefore load-bearing rather than a widening: on a directory carrying an ACL the group bits are the ACL mask, so 0755 silently caps every named grant at r-x and the next restart cannot create its socket.

17.2.2.1. No unit may claim it as a RuntimeDirectory

The tmpfiles.d snippet is the directory’s only owner, and that is a rule rather than a preference. systemd gives a RuntimeDirectory= to the declaring unit’s own User= and chowns it — and everything inside it — on every start. In a directory with four tenants under three accounts, that recursive chown does not merely decide who owns the directory: it rewrites the ownership of sockets that other units have already bound.

For example, pepsi-httpd.socket binds /run/pepsi/httpd.sock as 0660 root:www-data so the front web server can reach it in reverse-proxy mode. A RuntimeDirectory=pepsi in pepsi-httpd.service would chown that socket to pepsi-httpd:pepsi-httpd on every start, the front server would get EACCES on connect, and every MTA-STS policy fetch would get a 502 — with every unit active and nothing logged, because nothing had failed. The same chown would replace the directory’s root ownership and its ACL outright and hand the other tenants’ sockets to whichever unit started last, and without RuntimeDirectoryPreserve=yes a service stopping would delete the directory, live sockets and all.

What those units actually need from RuntimeDirectory= is one thing: /run is read-only under ProtectSystem=strict. So pepsi-httpd.service and pepsi-ingress.service say ReadWritePaths=/run/pepsi instead and take their permission from the ACL; pepsi-setup-apply.service needs neither, running as root without ProtectSystem=strict. The .socket units keep DirectoryMode=0775 so the directory still appears if one of them binds before systemd-tmpfiles has run, and nothing deletes it, because nothing claims it. tests/check-systemd-units.sh (run by make check) fails the build if a RuntimeDirectory=pepsi appears in a shipped unit or in the reverse-proxy drop-in that pepsi-setup writes.

The front web server’s access is granted the same way, and separately. Reaching httpd.sock needs two permissions: the socket’s own SocketGroup=, and traversal of the directory it sits in. The directory’s other r-x bits would provide the second, but they exist for an unrelated reason (any local account may submit mail through the submission socket), and relying on them would make policy delivery depend on a permission granted for something else. pepsi-setup therefore writes an explicit grant to /etc/tmpfiles.d/pepsi-reverse-proxy.conf when it configures reverse-proxy mode, naming the account that it actually detected (www-data on Debian, nginx/apache elsewhere) with r-x and nothing more, and removes it again with the socket drop-in. It is a separate file from the shipped snippet because it is discovered rather than shipped, and conditional rather than always.

The telemetry collector is deliberately not a tenant here at all and lives in /run/pepsi-collector instead. That is its own directory, shared with no other unit, which also keeps it clear of /run/pepsi-telemetry, the telemetry client’s directory.

17.3. The private-key custody boundary

Upholds

Gateway custody (custody = local, the MTA key) (keys never disclosed to a passive reader or an ordinary stage; boundary B5).

Private key material lives in crypto_identity.private_wrapped, and is protected twice over:

By grant. pepsi-setup grants that one column to the pepsi-crypto role and revokes it from every service account, pepsi-httpd included; apart from pepsi-crypto, only the schema owner pepsi-owner can read it, by ownership. This is column-level and it is absolute: PostgreSQL refuses a statement that so much as names the column, even inside an IS NULL test, so there is no read path to narrow later.

Note

That absoluteness has a practical edge. A listing query cannot report “does this identity have a private half?” as private_wrapped IS NOT NULL: that is refused for every role but pepsi-crypto, and PostgreSQL’s error, permission denied for table crypto_identity, names no column. The listing derives the flag from wrap_key_id instead, which a table CHECK keeps exactly in step.

By wrapping. What is stored is not a private key but an AEAD ciphertext under a key-encryption key that lives outside the database. The ciphertext is bound, as associated data, to that row’s (address, protocol, purpose) and to the key’s fingerprint. The key-encryption key sits in a secrets.d/*.secret fragment that only pepsi-crypto can read, and not pepsi-owner, so the one other role that can read the column still holds nothing that it can open. Moving a blob between rows fails to authenticate. That includes moving it between the identities that one address has had, which share address, protocol and purpose and differ only in the fingerprint, so a retired key’s blob cannot be put back into the row of its successor. Blobs in format version 1, which does not bind the fingerprint, still open; pepsi-keys wrap rotate re-wraps them into the bound format (version 2), also when the key-encryption key has not changed. Because the whole secret key, public parameters included, sits inside the AEAD, a tampered blob never opens and cannot fault a key operation; we do this to avoid key recovery from mauled wrapped keys (Unauthenticated private-key encryption lets the storage holder maul keys, Unauthenticated private-key encryption lets the storage holder maul keys).

Against its own public half. The public half (public_material) and the fingerprint sit in the clear beside the blob. No ordinary service role may write them (see above), but the key-custody role and the schema owner can. Every time a stage unwraps a private key (pepsi_keymat::open, the one place both pepsi-stage-encrypt and pepsi-stage-decrypt go through), it first checks that the stored public half belongs to it: for OpenPGP the fingerprint and the certificate’s primary key must be the secret key’s, and the certificate may carry no key that the secret key does not hold; for S/MIME the certificate’s public key must be the private key’s (compared as a key, so a CA-issued certificate over the same key is fine) and the fingerprint must be that certificate’s. A row that fails is not used – nothing is signed or decrypted with it – and the refusal is logged at error, since it means something other than Pepsi’s key management wrote the key store. The Web Key Directory, which cannot unwrap anything, makes the half of the check that it can: it withholds (and logs at error) a key whose public half is not the key its recorded fingerprint names. A writer that replaces the public half and the fingerprint together can still have the replacement served by WKD and printed by pepsi-keys dns until it is noticed, but the identity stops working at once, because the fingerprint no longer matches the one that the blob is bound to, and that makes the replacement visible (Unauthenticated stored encrypt-to-self key replaced to read sent mail).

In use. Every S/MIME RSA operation is done by AWS-LC (through aws-lc-rs, the library that already provides TLS): decrypting a key transport block, making a CMS signature, self-signing a generated certificate or certificate request, encrypting to a correspondent’s key and verifying a signature. Its RSA arithmetic is blinded and constant time. Blinding randomises the value that is actually exponentiated, so the cache and timing footprint of the private exponent does not correlate with a value that an attacker chose. Pepsi links no second RSA implementation: the rsa crate, whose arithmetic is not constant time (the Marvin attack, RUSTSEC-2023-0071), is refused by deny.toml even as an indirect dependency. AWS-LC does not offer a way to read the modulus and the private exponent out of a key’s encoding, so Pepsi does that in a few lines over the der parser. DKIM and ARC signatures are made by AWS-LC too. RSA keys are also generated by AWS-LC: DKIM keys ([pepsi-dkim] RSA_BITS, 2048, 3072 or 4096) and S/MIME keys at the CRYPTO_GENERATE_RSA_BITS of 2048, 3072, 4096 or 8192. Those are the sizes that AWS-LC can generate and the only values that the option accepts.

The same holds for S/MIME elliptic-curve keys (P-256, the default, and P-384). AWS-LC, whose scalar arithmetic is constant time, generates them and computes the ECDSA signature of a CMS message and of a generated certificate or certificate request, the static-key ECDH that opens inbound key agreement and the ephemeral ECDH that builds outbound key agreement. The RustCrypto p256/p384 crates do none of this, because their big-integer arithmetic (crypto-bigint 0.5) is not constant time (RUSTSEC-2026-0387). Opening inbound key agreement is the exposed case: the sender chooses the ephemeral point that meets our private key, and can submit as many points as it likes. The public-key side is AWS-LC’s as well, and neither crate is linked. AWS-LC parses certificate and originator public points (uncompressed or compressed SEC1, as RFC 5480 allows) and checks that each point is on the curve; it verifies ECDSA signatures (S/MIME, and the ES256 WebAuthn assertions of the admin console) and encodes public keys. An S/MIME ECDSA signature is verified with the digest that its SignerInfo declares, on either curve, except P-384 with SHA-1, which AWS-LC does not offer: such a signature (possible only under CRYPTO_ALLOW_WEAK_DIGESTS) is reported as unsupported. Stored keys keep their PKCS#8 (or imported SEC1) encoding, so existing identities keep working unchanged. Ed25519 (DKIM and ARC keys, WebAuthn EdDSA assertions) is AWS-LC’s too. A WebAuthn Ed25519 assertion is refused when the credential key or the signature’s R is a point of small order, as a strict verifier does, since such a signature can be made without the private key. OpenPGP keys are generated and used by Sequoia’s cryptographic backend (Nettle in Pepsi’s own builds), not by either library.

Decrypting a key transport block is the one operation that is applied to a value which an attacker chose and can submit at will. AWS-LC checks PKCS#1 v1.5 and OAEP padding in constant time but reports the verdict as a return code, so one branch on it remains. Everything after that branch is constant time (see below), and the unwrap is in addition held to a randomised deadline. An elliptic-curve identity, which is what CRYPTO_SMIME_ALGORITHM generates by default (p256), receives mail as ECDH key agreement, done in constant time by AWS-LC, and avoids RSA private-key operations altogether. The branch therefore concerns the RSA identities that a site has: those generated under rsa (the only algorithm that shared-certificate mode allows) and imported ones. An S/MIME RSA key outside the 2048 to 8192 bit range that AWS-LC accepts does not decrypt, sign or get encrypted to at all: the operation fails, with a warning in the log. Smaller keys are possible only under a lowered CRYPTO_MIN_RSA_BITS. Signatures by such a key are verified with SHA-1, SHA-256 and SHA-512 down to 1024 bits, which is as far as AWS-LC goes; a SHA-384 one is reported as unsupported. Only SHA-256, SHA-384 and SHA-512 RSA signatures are made. CRYPTO_ALLOW_WEAK_DIGESTS governs verification only, and only of SHA-1 signatures: an MD5 signature is refused whatever the option says. A key transport block that does not unpad, PKCS#1 v1.5 or OAEP alike, is not reported as such. It yields a substitute content key (RFC 8017 implicit rejection), and the content decryption then fails exactly as it would with a wrong key. The substitute is derived from the ciphertext under a secret that only the private key’s holder can compute (HMAC-SHA256 keyed with a hash of the private exponent, the construction that OpenSSL 3.2 uses). Sending the same ciphertext twice therefore gives the same answer twice and teaches the sender nothing that a single attempt did not.

An OpenPGP message is offered only to the keys that our certificate binds for encryption: a signing key is never tried on a PKESK, even when its algorithm (RSA) could decrypt one, so a key that signs cannot be probed as a decryption oracle. Private key material handed to pepsi-crypto is overwritten when it is dropped, rather than left in freed memory.

17.4. Certificates from a commercial CA

Upholds

Gateway custody (custody = local, the MTA key) (no private key leaves the host, also for a CA-issued certificate), Somebody holding the configuration or a secret (each CA credential is one domain’s capability), A compromised component and A delegated administrator (who decides what the organisation pays for and whose name it sponsors), and A mail-only user (a user cannot have the organisation sponsor a name that they typed).

The managed PKI (Certificates from a commercial CA: the managed PKI) orders S/MIME certificates for the users of a domain from DigiCert CertCentral. Five things are guarded.

The key never leaves the host. pepsi-keys mpki run generates the key of each order with the same code as pepsi-keys identity generate (AWS-LC, for RSA and for the curves) and wraps it under the key-encryption key before the request is sent. The AEAD binds it to the address, the protocol and the purpose; there is no fingerprint to bind yet. It waits in mpki_order.key_wrapped, a column that only the pepsi-crypto role may read: pepsi-setup revokes it from every other role and refuses to finish when PostgreSQL disagrees. Once the certificate is installed, the key is wrapped again as an ordinary identity, bound to the certificate’s fingerprint, and the order’s copy is deleted; a failed or cancelled order loses its copy as well. The CA receives the PKCS#10 request, the address and the person’s given name and surname, never a private key, and Pepsi keeps no escrow copy for anybody.

What comes back is checked before it is used. The issued certificate goes through the rules that also guard a certificate installed by hand (pepsi_keymat::issued): it must parse and break no RFC 5280 encoding rule, carry no critical extension that Pepsi does not understand, be an end-entity certificate, name the order’s address in its subject alternative name, allow emailProtection, carry the key usages of its purpose, not have expired, and be over the order’s own key. A CA that answers with somebody else’s certificate, or with one over another key, installs nothing, and the order fails with the reason. The intermediate certificates are stored and sent with every signature, but they are only advice to the recipient: a damaged chain means a signature without it, never no signature. Nothing about the CA enters the trust anchors (ca_trust), so the managed PKI changes nothing about how inbound signatures are judged.

The credential is one file per domain, and the web tier never sees it. Each domain’s CA account is reached with its API key, which Pepsi sends in the X-DC-DEVKEY header; Pepsi authenticates with nothing else. The key is the file secrets.d/mpki-<domain>.secret, mode 0640, group pepsi-crypto, which pepsi-keys mpki credential set writes. It is not in the database, so a copy of the database cannot reach the CA, and it is not readable by pepsi-httpd: the console can change what is ordered, but it cannot talk to the CA itself. Root and the pepsi-crypto account can read it, and that account includes the crypto stages. Each file opens one domain’s account, and the organisation can revoke the key in the CA’s portal.

Outbound requests go to one URL per domain. A pass runs as the pepsi-crypto identity, its requests to the CA included, under a unit without core files (LimitCORE=0) and with a read-only file system (ProtectSystem=strict). It connects only to the domain’s API URL, which must be https:// (plain HTTP only to localhost for a stand-in in tests). The connection uses Pepsi’s one HTTP client with the system’s roots, follows no redirect, reads at most 4 MiB of an answer and gives up after [pepsi-mpki] TIMEOUT. What the CA learns is what the order states: the addresses and names of the users who are enrolled, and the address and reason of each revocation.

Only the operator and the console decide what is ordered. The domain settings and the user list decide what the organisation is billed for and whose name it sponsors. pepsi-crypto writes them (pepsi-keys mpki, and the encrypt stage, which registers a sender of a managed domain that it sees for the first time), and so does pepsi-httpd (the console and the API, for an administrator whose scope includes keys:write; an address-confined own: principal sees none of it, Managed certificates). The console cannot write an order or read the credential, so it changes what the next pass orders but never talks to the CA itself. The pipeline role pepsi and every other role hold no grant on these tables, and pepsi-setup refuses to finish when another role may change them or may write an order, a chain or a notice. A compromised ordinary stage can still have the encrypt stage register a sender, by rewriting the From: of a queued submission, just as it can have that stage sign (A compromised component). The next two rules bound what that costs.

  • A sponsored name needs an approval by default. The encrypt stage registers only the author of locally submitted mail, and takes the name from the From: display name, which the sender types. Under header_names = approve, the default, such a name is unconfirmed and the order waits (name-unconfirmed) until an administrator confirms or corrects it. A name from a directory import or from an administrator counts as confirmed, because a person vouches for it. A deleted user is not created again by their next message.

  • The daily limit is a limit on spending. At most daily_limit new enrolments of a domain (20 by default) go to the CA in any 24 hours; the rest are held until an administrator releases them, and a notice says so. Renewals are not counted, since each one replaces a certificate that is already paid for. The limit protects against a mistake or a flood of registrations, not against somebody who may change the settings, since that person can raise it. Pepsi never names a payment method in an order, and the API cannot buy a subscription licence: an order beyond the licences that the account holds is refused by the CA and held here (no-licence).

When a user is deleted or opts out, the certificate is revoked at the CA and retired here as superseded: it stops signing and is no longer served, but its private key is kept, so mail that correspondents encrypted to it still opens. The notices that a pass mails to a domain’s notify address go out with the null sender and Auto-Submitted: auto-generated, and a line break in an address or a notice cannot add a header.

17.5. The DKIM signing daemon

Upholds

A compromised component (a compromised stage cannot carry a domain signing key away; boundary B5) and Somebody holding the configuration or a secret (no DKIM key in a backup).

The DKIM and ARC private keys are held by one long-lived service, pepsi-dkim, running as its own account pepsi-dkim. The keys are PKCS#8 files of mode 0600 in 0700 directories under /var/lib/pepsi-dkim; the unit sets UMask=0077 and LimitCORE=0 and runs with the full systemd sandbox (ProtectSystem=strict, NoNewPrivileges, PrivateDevices, restricted address families). No other account reads a key, pepsi-setup included: it hands the daemon the set of signing domains (pepsi-dkim sync-domains) and takes the DNS records from the daemon’s public status document. The keys are not in the database and are left out of backups; a host restored without them gets fresh keys under new selectors, which is a rotation.

The socket. /run/pepsi-dkim/sign.sock is 0660, group pepsi, in a directory of the daemon’s own that anyone may traverse but nobody else may list (0711): the dispatcher and every stage worker can connect, no other local account can. The daemon is a member of pepsi only to hand the socket to that group. The administrative requests (reload, rotate) are accepted from root and the daemon’s own account alone, checked with SO_PEERCRED.

What it signs. A signing stage hashes the body and builds the signature field itself, and sends the daemon the exact bytes to sign: the canonicalised header fields that the signature covers, followed by the signature field with an empty b=. The daemon parses that block (one line of at most 256 KiB, at most 512 fields) and signs only when

  • the domain is one it serves, and the selector is that domain’s current one (or was, within the last ten minutes, for messages in flight across a key switch);

  • the last field is the signature field of the requested kind, its d=, s= and a= are the request’s, its b= is empty and no tag is repeated;

  • for DKIM: h= names from, there is a From: field, and every mailbox of every From: field is in the same organisational domain as d=;

  • for ARC: d= is [pepsi] ARC_DOMAIN.

Every signature and every refusal is logged with the requesting process id, so after a compromise the journal shows what was signed. A stage that cannot reach the daemon treats the error as temporary: the message waits and is retried, never sent unsigned.

What it does not protect. The policy keeps the keys from signing for a domain they do not belong to and keeps a DKIM signature from vouching for a From: of another organisation. It does not keep a pepsi process from having a message of a served domain signed: key use stays reachable by the whole pipeline (A compromised component). What the daemon bounds is key disclosure - a compromised stage signs while it runs and loses that power when it is fixed, without a rotation.

Rotation and retired keys. Keys rotate only when the operator asks (ROTATION_DAYS, pepsi-dkim rotate), each generation under selectors of its own; a switch waits by default until every authoritative server serves the new records, and a retired generation’s records stay RETIRE_AFTER_DAYS beyond the expiry of the last signature that it made. With PUBLISH_RETIRED_KEYS the retired private key is published (pepsi-httpd serves /.well-known/pepsi-dkim-retired/<domain>/<selector>.pem) instead of deleted, so old signatures no longer prove who made them (DKIM signatures make stolen mail verifiably attributable). The key is published only once every authoritative server has stopped serving its records, and is deleted instead if they are still served 90 days after it retired; resolver caches can still hold a removed record for its TTL (Rotating DKIM keys). The web server serves only regular files of at most 64 KiB under names that the daemon could have written.

DNS updates. With DNS_UPDATE = rfc2136 the daemon adds and removes its own records by RFC 2136 UPDATE, authenticated with TSIG (HMAC-SHA-256, -384 or -512). The TSIG key is [pepsi-dkim] TSIG_SECRET, which pepsi-setup keeps in secrets.d/pepsi-dkim.secret, readable by pepsi-dkim alone. Its holder can change whatever the DNS server lets the key update, so the server’s policy should confine it to TXT records under _domainkey.

17.6. A second factor for key management

Upholds

Someone holding a user’s mail password (a stolen mail password cannot register a key for a user who enrolled a second factor, and a stolen console password does not open an account that enrolled one).

A user may enrol a TOTP secret (RFC 6238: HMAC-SHA-1, six digits, 30-second steps — what every authenticator app implements) for their address; from then on every change to their keys that they can make needs a current code:

  • By e-mail, every key command but status takes the code as a six-digit word in the Subject:: generate, register, publish, retire, pin and otp enroll/otp remove themselves. otp confirm takes a code from the new secret instead (see below). An ordinary message’s Autocrypt: header or attached key then registers nothing for that address. pin is refused outright for an address with no second factor: it is the one command that changes what other users’ mail trusts (What a security indicator means).

  • In the web console and the API, an own:<address> principal’s generate-identity, register-client-key, revoke-identity, set-identity-flags (publication, key-server upload, primary key), identity-csr and identity-certificate requests carry an otp field. pepsi-httpd holds no grant on the table at all, so it cannot check the field and passes it through; pepsi-setup apply checks it before acting, for a task admitted on own:<address> alone. An operator holding keys:write is not asked.

  • Signing in to the console by e-mail (Signing in to the console by e-mail) needs the code before the own:<address> session is opened, checked the same way.

  • An unprivileged pepsi-keys (a setuid install) needs --otp CODE for every identity change and private-key export; ownership is checked first, so one user can never count failures against another’s enrolment.

Enrolment by e-mail has two steps. otp enroll keeps the new secret in pepsi.otp_pending, and a second factor already in force stays in force; only otp confirm CODE with a current code from the new secret, within [stage-encrypt] OTP_CONFIRM_WINDOW (one hour by default), makes it the enrolment (otp_pending_confirm, under the row lock), with that code’s time step as its replay floor. Wrong confirmation codes count against the pending secret only, which is discarded at ten; a lapsed one is deleted when the address is next touched and by the hourly pepsi-queue gc (through otp_pending_expire, which can delete nothing else). So a secret that never reached an app, or reached it mistyped, cannot lock its owner out of their key commands. The reply that carries the secret is sealed to the user’s own (MUA) keys when they registered any, in the encrypt stage before it is queued, so a reader of the mailbox without the client’s key gets nothing; it carries an Expires: header (RFC 4021) at the end of the window, and the notice signer passes a sealed reply on unsigned rather than wrap the ciphertext. pepsi-keys otp enroll at a terminal stays one step: the secret never passes through a mailbox.

Custody. The secret is wrapped exactly like a private key — AES-256-GCM under the key store’s KEK, bound to (address, totp, second-factor) — and the otp_key and otp_pending tables are granted to the pepsi-crypto role alone: pepsi-setup revokes it from every other role, the pipeline’s pepsi included, and verifies that against PostgreSQL. A stage that parses hostile mail can therefore neither read a secret nor reset a counter nor delete an enrolment (which would switch the protection off). pepsi-keys wrap rotate re-wraps the secrets with the private keys.

Attempts. The code is checked by the process that can unwrap the secret; the decision is the otp_attempt SQL function’s, under the row lock. A code matching a time step later than the last accepted one is accepted and resets the failure counter to zero; the same code again, or an older one, is a replay and counts as a failure, as does a wrong code. At ten consecutive failures the enrolment is locked and every attempt is refused unchecked. A command with no code at all is refused without being counted. Each enrolment has a never-reused serial, so an attempt checked against a secret that was replaced meanwhile is discarded rather than recorded against the new one. Deciding under the row lock, and refusing a locked enrolment without consulting the submitted code, keeps parallel guesses from overshooting the limit (Login and recovery rate limits defeated by races and logic errors, Login and recovery rate limits defeated by races and logic errors).

The operator clears a lock by removing the enrolment (pepsi-keys otp reset, or DELETE /api/v1/otp/{address}, which queues a reset-otp task that only keys:write may ask for) or replacing it (pepsi-keys otp enroll as the operator needs no code); a new enrolment always starts at zero failures.

What it does not do. It does not protect the first enrolment (there is no code to ask for yet), nor an enrolment reply sent in clear (the user had no key of their own) that the user left in the mailbox. And it adds nothing against the operator, who can reset it. An owner’s flag changes in the web console and the API (WKD publication, a key-server upload request, the primary MTA key) are set-identity-flags tasks that the applier performs after checking the code, like every other owner’s key task (Authentication bypass in gateway, list and portal web interfaces).

Console accounts. The same machinery is the optional second factor of an administrator’s password sign-in. pepsi-keys otp enroll --console LOGIN (operator only) keeps the account’s secret in otp_key under the subject console <login>, with the same custody, replay floor and ten-failure lock. A space never occurs in an address, so this subject cannot collide with one. From then on POST /api/v1/auth/login and the console’s sign-in form need the current code beside the password. pepsi-httpd learns only whether the account has one, through the SECURITY DEFINER function console_second_factor (EXECUTE granted to pepsi-httpd alone, verified by pepsi-setup); after the password checks out it queues a confirm-login task carrying the code and opens the session only when the applier reports it done. A code is never checked, nor counted towards the lock, before the password is right. A missing, wrong, replayed or locked code, and an applier that is not installed or does not answer, give the same uniform failure as a wrong password, charged to the account’s daily ceiling. Clearing a lock is pepsi-keys otp reset --console LOGIN; the local socket needs no password and so no code, which is what lets the operator do that from the console as well.

17.7. Security keys (WebAuthn)

Upholds

A phishing proxy (adversary in the middle) (an assertion made on another origin verifies nowhere), A delegated administrator (a guessed password is not a session), Someone who can read a user’s mailbox.

Console accounts, end users who sign in by e-mail and mailing-list members may register WebAuthn credentials as a second factor (Security keys). Either factor satisfies it: a key, or a TOTP code where the account has one and [pepsi-httpd] REQUIRE_WEBAUTHN does not cover its kind. Neither replaces the first factor. The mechanisms:

  • An in-tree verifier (pepsi_common::webauthn), so that what is checked is short enough to read: clientDataJSON must name the ceremony, carry the issued challenge (compared in constant time), name exactly the configured origin ([pepsi-admin] CONSOLE_URL, default ENROL_URL, for the console; the origin of [pepsi-list] BASE_URL for the member pages; both https:// only) and not have run in a cross-origin frame (crossOrigin true or a topOrigin is refused). The authenticator data must carry the SHA-256 of the RP id (the origin’s host), the user-present flag and consistent backup flags; user verification is not required, since the password is the knowledge factor. Signatures are ES256 (P-256, DER) or Ed25519 (strict verification); nothing else is offered or accepted.

  • Attestation format none only. The pages ask for no attestation, Pepsi does not judge authenticator models, and code that parsed attestation statements would be code that could be wrong; any other format is refused.

  • A strict CBOR reader, written for the three structures involved: definite lengths only, integers, byte and text strings (valid UTF-8), arrays, maps and booleans, nothing else (no tags, floats or null), nesting at most 8 deep, at most 64 entries a container and 16 KiB an input, no duplicate map keys and no trailing bytes. It has a fuzz target (fuzz/fuzz_targets/ webauthn.rs) and is tested against the W3C specification’s own vectors.

  • Challenges are 32 random bytes, stored only as their SHA-256 in pepsi.webauthn_challenge, taken by DELETE … RETURNING so each works once, valid for five minutes, and bound to one owner, one purpose (sign-in, registration at sign-in, registration, confirming a removal) and to what issued it: the pending sign-in, the enrolment link, or the session. A pending sign-in’s challenge is the proof that the password checked out, so it is issued only then and handled like a session token.

  • Credentials (pepsi.webauthn_credential) hold a credential id, the COSE public key and the signature counter — public material only. Each has exactly one owner (a CHECK constraint), is looked up by owner and id, so another account’s key is never even verified, and its id is unique across owners. The counter must grow whenever the stored or the presented value is non-zero (a cloned authenticator, or a replay), and is advanced by a compare-and-set. An owner may have at most ten. Deleting a console or member account deletes its keys; a login that changes owner loses its end-user keys with its sessions (login_assignment_reset_console).

  • Changing the keys. A session alone never adds a factor to an owner that has one. The first key needs the session and, for a console account or a member, the password again. A further key, and the removal of one, also need an assertion by one of the owner’s existing keys (a console account may give its TOTP code instead where TOTP may stand in); an addition then takes a second page, whose registration challenge is bound to that confirmation and to the session, so neither half can be replayed into the other. Under REQUIRE_WEBAUTHN the last key cannot be removed, and an account without one registers one as the last step of its next sign-in. The operator removes a lost key through the API (DELETE /api/v1/accounts/{id}/webauthn, /api/v1/webauthn/{address}, /api/v1/webauthn/members/{address}). A TOTP code stands in for an end user’s key only when the applier reports that it actually checked one, since it also passes an address that has no TOTP at all.

  • One script. The ceremony is a script interface, so the pages that run one load webauthn.js, a static file compiled into pepsi-httpd. Those pages’ Content-Security-Policy allows it by its SHA-256 and by its exact URL on the configured origin, and by nothing else. The policy does not allow 'self', because the list archive serves other people’s attachments from that origin. Every other page keeps a policy without script-src.

  • Both tables are credentials: granted to pepsi-httpd alone, revoked from every other role and verified by pepsi-setup, like the session tables.

What it does not do. It does not protect an account that has no key, nor one whose TOTP code may stand in for its key, from a proxy that relays the code; it does not protect the secure-link portal, whose recipient has no account; and the second step of a sign-in tells whoever typed the password that it was right. It adds nothing against a compromised pepsi-httpd, which can write sessions directly.

17.8. Signing in to the console by e-mail

Upholds

Someone who can read a user’s mailbox (a mailbox is worth exactly own:<address>, and with a second factor not even that), Principals and how far each is trusted.

With [pepsi-admin] ENROL_STAGE set, an end user obtains an own:<address> principal by following a link mailed to the address (Signing in by e-mail). The mechanisms:

  • The link carries 256 random bits; pepsi.own_enrolment stores only their SHA-256, with the address, an expiry (ENROL_LIFETIME, 30 minutes) and an attempt counter. Each submission is counted in the same UPDATE that checks the expiry, so concurrent submissions cannot exceed five; the session is minted only after a DELETE ... RETURNING of the row has succeeded, which happens once. A new link for an address replaces the old one. Opening the link changes nothing; only the form that it shows does, so a link scanner cannot use it up or sign anybody in.

  • The link’s origin is ENROL_URL, an https:// origin that the operator configures. It is never taken from the request: a Host header chosen by whoever asked for the link would otherwise decide where the victim’s click sends the token.

  • No address enumeration. The address form answers the same page for every well-formed address, and does the lookup (a non-revoked key-store identity, or a local account of a Maildir or .forward stage) and the mail after the answer has been sent, so neither the text nor its timing says which addresses exist. Enrolment being unavailable (no applier) is said for every address alike.

  • Budgets. Two budgets apply, on top of the console’s general per-minute limit: links per target address per hour (ENROL_MAIL_PER_HOUR, 3) and requests per client address per hour (ENROL_RATE_LIMIT, 20). The first is per target because the form makes the server mail an address that nobody has proved they control. The link mail goes out from the null sender with Auto-Submitted: auto-generated.

  • The second factor is the applier’s. otp_key is granted to pepsi-crypto alone and its secrets are wrapped under a KEK outside the database, so no grant to pepsi-httpd could let the web tier check a code. Not even a SECURITY DEFINER function could, because it would still lack the KEK, and giving the web tier the KEK would hand it every private key. The confirmation therefore queues a confirm-enrolment task carrying the code, under the address’s own scope and through the configuration role, like every other request to the applier; pepsi-setup apply checks the code with the replay protection and lock of A second factor for key management, and the session is opened only when the task ends done. The web tier does not learn whether the address has a second factor at all: the applier passes one that has none. Without the applier, enrolment is refused rather than completed unchecked.

  • The session is a row in pepsi.own_session that holds the SHA-256 of the cookie, the SHA-256 of a CSRF token, the address, and an idle and an absolute expiry (SESSION_IDLE/SESSION_LIFETIME). It sits behind the same HttpOnly, SameSite=Strict, __Host--prefixed cookies and CSRF check as an administrator’s session. It stores an address, not a scope list, so it can hold own:<address> and nothing else by construction. Both tables are credentials: pepsi-setup grants them to pepsi-httpd alone and verifies that no other role reaches them.

What it does not do. It does not authenticate the person, only the mailbox: whoever reads the mailbox can sign in, unless a second factor (a TOTP code, or a security key, Security keys (WebAuthn)) is enrolled. It does not make the console’s pages writable for settings (users still change those by e-mail), and it adds nothing against a compromised pepsi-httpd, which can write sessions of either kind directly.

17.9. An attacker who has the database

Upholds

Somebody holding a copy of the database.

Assume a full dump — a stolen backup, a replica, SQL injection into a read-only path.

They get:

  • every message currently in the queue, in the clear: pepsi.workqueue holds the headers and pepsi.workqueue_body the body, unencrypted. Pepsi is a pipeline; a message in flight has to be readable by the stage that will process it. Delivered messages are deleted, so this is the backlog, not the history. What stays longest is bounded too: a failed row is bounced by pepsi-failure-bouncer after MIN_AGE (an hour), a message held at a quarantine stage by pepsi-queue gc after [pepsi-queue] QUARANTINE_MAX_AGE_DAYS or by the stage’s own MAX_HOLD (Quarantined mail; 14 days by default; the DSN returns no content, whatever RET asked, and a message from an AES-CBC EnvelopedData is dropped rather than bounced, Bounces and replies to encrypted mail), and pepsi-setup schema --backup-dir keeps only the newest two of the dumps that it takes before an upgrade (--backup-keep).

  • the full correspondence graph: senders, recipients, timestamps, per-address settings, whitelists, the origin_nonce, auto_pay_spend, payment_request_reply, dns_address, mta_sts_policy, list_confirmation (which list confirmation requests users received), smime_capability (which correspondents’ clients cannot read authenticated S/MIME), crl_cache and ca_issuer_cache (which CAs correspondents use) and login_assignment (when each login changed owner) tables.

  • every public key and certificate, and all key metadata.

  • the managed PKI’s users, with the given name and surname that each one’s certificate carries, and its orders (mpki_user, mpki_order).

  • the ARC/DKIM/DMARC verdicts and TLS session outcomes.

They do not get:

  • any private key, nor any second-factor secret. The wrapped blobs are AEAD ciphertext and the key-encryption key is not in the database. That includes the key of a managed-PKI order that waits for its certificate.

  • the managed PKI’s CA credentials, which are files in secrets.d, so a copy of the database cannot be used to order or revoke a certificate.

  • any secure-link message body. secure_message.ciphertext is AES-256-GCM under a key derived by Argon2id from the recipient’s PIN, a per-message salt and a server-side pepper held in the configuration, not the database. The PIN itself is never stored in any form — not even a hash. A database thief must brute-force a PIN that they cannot verify offline without also having the pepper (Offline guessing of weak password hashes, key passphrases and derived keys).

  • any usable credential. Admin and mailing-list passwords are Argon2id hashes (64 MiB, three passes, one lane: RFC 9106’s second recommended setting, the one that pepsi-config export uses too); a hash stored with weaker parameters keeps verifying and is replaced with a current one at its owner’s next successful sign-in, the only moment the plaintext is at hand. API tokens are stored as digests, so a token cannot be recovered from a backup and is shown exactly once. Every stored password derivative is salted, so precomputed tables have nothing to target (Offline guessing of weak password hashes, key passphrases and derived keys).

  • the DKIM signing keys, which live in the signing daemon’s state directory, and the SRS and Pepsi-Origin secrets, which live in secrets.d.

Warning

The queue is the exposure. An operator who considers mail-in-flight confidentiality important should encrypt the database at rest and keep backups accordingly — Pepsi cannot encrypt the queue to itself, because every stage would need the key, which is the same as not having one.

17.10. An attacker who has the configuration file

Upholds

Somebody holding the configuration or a secret.

/etc/pepsi/pepsi.conf is mode 0644 on purpose: unprivileged stages read it. It therefore must contain no secrets, and does not — each secret lives in a secrets.d/<reader>.secret fragment pulled in by an @inline-secret@ directive and owned by the one account that needs it.

Read access to the config file yields the topology: hostnames, served domains, the pipeline graph, smarthost addresses, file paths, which features are on. That is reconnaissance, not compromise.

Read access to a ``secrets.d`` fragment yields exactly what its one reader holds, and no more — the SRS key, or the smarthost password, or the key-encryption key, or the secure-link pepper, or the list unsubscribe key, or the LDAP bind password of key discovery (pepsi-keydisc.secret), or the OAuth client credentials of the token refresher (pepsi-helper-token-refresh.secret). That is why they are split: there is no single file whose disclosure is total. The split covers every credential option Pepsi defines, whether pepsi-setup generated it or the operator wrote it into pepsi.conf by hand: pepsi-setup run moves a hand-written one (LDAP_BIND_PASSWORD, the list API_PASS, CLIENT_ID/CLIENT_SECRET/REFRESH_TOKEN, a PASSWORD) into its reader’s fragment and leaves an @inline-secret@ directive behind. A credential-shaped option for which it knows no reader stays where it is and is reported on every run (Mail appliances store secrets world-readable or unprotected). A retired SRS key named by [pepsi-srs] PREVIOUS_SECRET_FILE gets the ownership and mode of the current one.

Write access to the config file is equivalent to root. It names the programs that each stage runs. Treat it as a root-owned file, because it is one. The database configuration overlay cannot name programs: it refuses every option naming an executable (a delivery stage’s HELPER among them) and accepts a stage’s PROGRAM only as a bare pepsi-stage-* command. config:write on the administrative API still controls the pipeline graph and every stage’s options, so it remains an operator-level grant (Command injection and XXE in mail gateway management interfaces, Mail appliances store secrets world-readable or unprotected).

Warning

Two traps around @inline-secret@, both of which look like a working configuration:

  • the directive ends its section — anything written after it lands in no section at all;

  • an unreadable fragment only warns. The option then reads as unset, and a feature silently runs without its secret. Verify by stat-ing the fragment as the reader account, not by reading the log.

17.11. A process of the same account

Upholds

A compromised component, Somebody holding the configuration or a secret.

The programs that hold long-lived secrets in memory clear the kernel’s dumpable flag before they load them (prctl(PR_SET_DUMPABLE, 0), in pepsi_common::process::forbid_core_dumps): pepsi-httpd (the secure-link pepper, administrator and end-user password checks, second factors), pepsi-keys (the key-encryption key and the private keys that it unwraps), pepsi-config export/import (every secrets.d fragment and the archive password), pepsi-setup apply (the key-encryption key and the fragments that it writes) and pepsi-dkim (the DKIM and ARC private keys). pepsi-stage-encrypt and pepsi-stage-decrypt are non-dumpable already, because the kernel clears the flag on a set-user-ID exec. A non-dumpable process writes no core file when it crashes, and no other process of the same uid can attach to it with ptrace or read its /proc/<pid>/mem, whatever Yama’s ptrace_scope says. So code running under pepsi-httpd in the log-pruning timer, or a debugger started by whoever reaches that account, cannot lift the pepper out of the server. Their systemd units also set LimitCORE=0, so a core file is refused even if the call were lost; tests/check-systemd-units.sh checks every unit that runs one of these programs for it.

There is no option to turn this off: confidentiality of key material ranks above the convenience of a core file (Design principles). A crash still leaves its panic message in the journal. Root can attach a debugger regardless.

What this does not cover: copies that a Vec or String leaves behind when it grows, Clones of secrets, and decrypted plaintexts, which are freed without wiping. A plaintext is stored in the queue database in clear anyway (Somebody holding a copy of the database), so wiping the in-process copy would protect nothing; the rest needs a memory disclosure inside the process itself (Secret handling defects: variable-time compares, lost zeroisation, spills).

17.12. Addresses are compared in one form

Upholds

Per-address settings are a trust boundary.

An address can be written several ways that name one mailbox: a precomposed é or e followed by a combining accent, upper or lower case, the U-label bücher.example or the A-label xn--bcher-kva.example. A per-address record looked up under another spelling than it was stored under does not apply, and with SMTPUTF8 the sender chooses the spelling – so a whitelist row, a settings override or a sender’s rate count could otherwise be evaded by writing the same address differently.

Every address that is a database key is therefore stored and compared in one canonical form (pepsi_common::address::canonical): surrounding white space removed, Unicode Normalization Form C, the local part case-folded with Unicode simple case folding (CaseFolding.txt; U+0130 İ takes its full folding i + U+0307), and the domain in A-label form (UTS #46). That covers pepsi.settings, the address: and domain: scopes of the configuration overlay, whitelist rows and the From: address they are matched against, the vacation, payment-request and confirm-to-send logs, mailing-list addresses, members, bans and rate counters, the archive’s posters, the key store and key discovery, list confirmation requests, TOTP and console enrolment rows and the console’s own: scopes. Delivery folds a local part the same way to find the mailbox (pepsi_common::local::fold_local_part), as does the recipient check at RCPT, so the same rule chooses the mailbox that mail reaches and the records that apply to it.

The database computes the same keys. pepsi.canonical_address() is an IMMUTABLE SQL function returning byte-identical output; it applies the same generated folding table with translate() and normalize(), so it does not depend on the database’s collation as lower() does (under C, lower() folds ASCII only). The SQL functions that receive an address (the list procedures, key discovery, the login-reassignment cleanup, the settings lookup made with every queued message) canonicalise it themselves, and the key columns that have a CHECK require the canonical form. A test compares the two implementations, under the database’s collation and under C, on a corpus of the hard cases and on every character that the folding table touches. The hard cases are Turkish dotted and dotless i, ß and ẞ, Greek final sigma, combining accents, and U-label and A-label domains. UTS #46 also maps compatibility characters in a domain (a full-width letter, an ideographic full stop), which only the Rust side does; addresses reach the database through Rust, so stored keys are its output.

Simple folding is deliberate. It maps one character to one, which is what lets SQL reproduce it exactly; full folding would also equate ß with ss and fi with fi. A local part’s meaning belongs to its receiving host (RFC 6531), and treating two strings as one mailbox that the host may keep apart would let one correspondent’s record apply to another. Quoting is not interpreted either: "alice"@example.org and alice@example.org are two keys. A hand-written whitelist expression is matched against the canonical form, so it names an internationalised domain by its A-label.

The upgrade re-keys. Existing rows are rewritten into the canonical form when the schema is upgraded. Rows that collapse into one are merged: a whitelist keeps the newest row with the union of the requirements (dkim_required, signature_required and a sealer domain), settings keep the canonically spelt row and overrides the newest, reply logs the latest notice, rate counters the larger count, and a mailing-list address the verified one with its memberships. Every merge is written to the event log (kind address.key.merged, with the dropped row less any secret) and printed as a notice. A key-store identity holding a wrapped private key, a primary identity, and a TOTP secret keep their spelling: the address is part of the associated data that a wrapped secret is bound to, so re-keying the row would make the secret unopenable. They are logged as address.key.kept for the operator to re-issue under the canonical address; until then a lookup by the canonical address does not find them.

17.13. A login that changes owner

Upholds

Per-address settings are a trust boundary.

Logins come from passwd, and an operator may delete one and create the same name for somebody else. pepsi.login_assignment records, per login, the uid that it has and when that assignment was first seen. Local delivery records every login that it delivers to: Maildir delivery before it writes, and LMTP delivery for every recipient that the MDA accepted and that resolves, by the same rules, to a passwd login. ~/.forward processing records the logins that an RFC 7293 check looks up, and pepsi-setup run and the hourly pepsi-queue gc look every recorded login up again. A virtual user that exists only in the MDA’s own user database has no passwd entry, so LMTP delivery records nothing for it and no change of its owner is noticed. A login seen under another uid, or seen again after a check found no passwd entry, has a new owner. In the same database function call that records it, the previous owner’s per-address state is deleted: pepsi.settings rows of the login’s addresses, its <login>/... whitelists and their pending challenges, its mailbox quota row and the vacation and payment-request reply logs, pending mailing-list confirmation requests, and console enrolment links and end-user sessions, so the previous owner’s browser session ends. The pipeline role has no grant on those two tables, so that one step runs with the schema owner’s rights, in login_assignment_reset_console, which can do nothing but these deletes. An account.reassigned warning goes to the event log. Without this, the new owner would inherit whitelists that let the previous owner’s correspondents past the spam gates, and per-address overrides that the previous owner chose.

Mailing-list state is suspended, not deleted. The same call takes away the login’s mailing-list addresses’ proof of control (verified_on) and their link to the previous owner’s list account, so a password reset mailed to the address cannot reach that account and the roles it holds; and it turns delivery off (delivery_status unknown) for every plain membership of those addresses, so the new owner does not receive the previous owner’s lists, private ones included. A list owner can turn delivery back on, and the new owner can subscribe afresh. Owner and moderator roles held by those addresses stay, because removing one may leave a list without an owner; the event names their count and the lists (list_roles_kept, list_roles_kept_lists) for the operator to review.

Key material is reported, not deleted. A key-store identity, a cached peer key or a TOTP second factor older than the current assignment is listed by pepsi-setup run and check with the command that disposes of it. Under gateway custody such an identity still decrypts mail sent to the address, which now belongs to the new owner, so the warning repeats until the operator acts; deleting it automatically would destroy what may be the only key to the previous owner’s archived mail.

Senders can refuse a later owner (RFC 7293). Ingress advertises RRVS; a RRVS=<date> request for a recipient whose login has a recorded change of owner after that date is refused at RCPT with 550 5.7.17. Local delivery and ~/.forward processing re-check the request and the Require-Recipient-Valid-Since header field with a fresh passwd lookup, and bounce with 5.7.17. Only a recorded reassignment fails the test, so the reply discloses nothing about an address that was never recycled, and the refusals count towards MAX_INVALID_RECIPIENTS against probing for mailbox history.

A directory outage cannot reset users. A passwd lookup that fails decides nothing, and a check in which more than half of the recorded logins look gone marks none of them – otherwise a broken nsswitch.conf would make every user look recycled on their return.

17.14. An attacker who compromises a stage worker

Upholds

A compromised component, including its signing residual.

Say a parser bug gives code execution inside a stage — the realistic case, since stages parse hostile input for a living.

A ``pepsi``-user stage (most of them) gets the queue: read, modify, redirect or delete any message in flight, and read the whitelist and settings. It does not get the wrapped end-to-end private keys, and it cannot become another account.

It does, however, get the ability to have mail signed, and this is worth being blunt about because it is the largest residual in the design:

  • pepsi-stage-dkim-sign runs as pepsi and has its signatures made by pepsi-dkim over a socket open to group pepsi, so any pepsi process can have mail signed as every served domain — by asking the socket directly, within the daemon’s policy (The DKIM signing daemon), or by editing a queued row before the signing stage sees it.

  • pepsi-stage-encrypt signs as the row’s From: author. Ingress enforces USERNAME_MAP at submission, but the queue row is writable by every pepsi stage afterwards and nothing downstream can tell whether ingress made that decision. A compromised pepsi stage can therefore rewrite a queued submission’s From: (or inject a message with workqueue_inject) and have it signed with any local user’s end-to-end key.

So whether Pepsi makes a DKIM signature or a per-user OpenPGP or S/MIME one, its integrity is only as strong as the whole pepsi pipeline role, not as strong as pepsi-crypto. What the split does bound is key disclosure: a compromised language detector can get messages signed while it is running, but it cannot carry a private key away, so the damage ends when the stage is fixed and does not require re-keying. See Threat model for where this sits among the other guarantees. This is the framing weakness of server-side custody (Unauthenticated private-key encryption lets the storage holder maul keys); a key kept in the user’s own client (custody = client) does not have it.

A ``pepsi-crypto`` stage gets everything that account has: it can decrypt inbound mail addressed to the deployment and sign as any local identity. This is the highest-value target in the system, which is why the two crypto stages are small, do no network I/O at all (discovery is a separate program), and are the subject of the fuzzing in Test Suite. It is inherent to gateway custody that the process parsing hostile ciphertext holds every server-held key (Mail appliances store secrets world-readable or unprotected).

``pepsi-ingress`` sees every message as it arrives and decides who submitted it, so it can admit mail as any local user. Its database role can add to the queue and read nothing of it, so what is already queued, the settings, the whitelists and the keys stay out of its reach.

``pepsi-httpd`` gets the web surface and its database grants — envelopes and routing of the queue, never a message’s headers or body. It notably cannot write configuration or run privileged setup steps: the browser wizard does not act, it inserts a row into pepsi.setup_task describing what should be true, and the separately-started, root-running pepsi-setup apply decides whether to do it. A compromised web tier can therefore request a reconfiguration but not perform one — and the applier validates each task rather than trusting its description. We do this so that a flaw in the web tier does not become command execution as root (Command injection and XXE in mail gateway management interfaces).

That last defence can be made absolute, which is the right posture on any deployment administered from a terminal. The applier’s two systemd units are their own Debian package, pepsi-httpd-admin (pepsi only Recommends it, so apt remove pepsi-httpd-admin succeeds and leaves the mail server running); a source install gets the same lever from make install INSTALL_ADMIN_UNITS=no. With them gone nothing drains pepsi.setup_task, so an insert into it is inert whatever happens to pepsi-httpd — the loop is broken at the mechanism rather than at the interface, and no code path in the web tier can start a root process. The console detects this, fails closed if it cannot tell, and serves its setup pages read-only. pepsi-setup stays in the base package, so administering the host by hand is unaffected. See The split as a hardening lever.

17.15. Specific defences

17.15.1. The submission identity

Upholds

A local shell user and A mail-only user (boundary B2): a submitter sends only as the identities the operator mapped to them.

Ingress decides who submitted a message by one of four means — SASL through the configured backend, a TLS client certificate, an address in MYNETWORKS, or the SO_PEERCRED credentials of the local submission socket, which is how sendmail authenticates without a password and why that socket may be world-writable. For a SASL login and a SO_PEERCRED caller, USERNAME_MAP then decides which From: and envelope addresses that identity may use (RFC 6409 §6/§8.1), and an identity mapped to nothing may authenticate but not send. A TLS client certificate and an address in MYNETWORKS identify a key or a host, not an account, and USERNAME_MAP does not apply to them. The optional SENDER_MAP file names, for each network (most specific match) or certificate (the pinned key, or the CA that the certificate chains to), the addresses that it may use. A session that the file binds passes the same envelope and From: checks as a mapped account, with the same 550 5.7.1; an address that one line names exactly is out of reach of every other line’s wildcard. A MYNETWORKS entry outside loopback that the file does not cover is a configuration that ingress refuses to start on, and pepsi-setup validate refuses as well: every host in it could otherwise send as any address and have pepsi-stage-dkim-sign sign the result for every served domain, which is how a relay that admits a shared cloud range becomes a forgery service. A bare * binding states that intent explicitly; loopback is this host and is exempt. A * that covers a network wider than one host is the EchoSpoofing shape kept as a decision, so ingress warns about it at every start and pepsi-setup validate does too (SenderMap::wide_unrestricted_networks). A client certificate that the file does not list authenticates nothing. An Exchange Online tenant ([pepsi-ingress-exchange-online-*]) is admitted neither by address nor by certificate, because its outbound connector offers neither an account nor a certificate of its own and every tenant sends from the same Microsoft addresses. On an MX listener, a client in the section’s SENDER_NETWORKS (by default the addresses Microsoft publishes in spf.protection.outlook.com) with an envelope sender at one of its DOMAINS may name outside recipients, and the message is refused at the end of the data unless it carries exactly one X-MS-Exchange-CrossTenant-Id field with the configured TENANT_ID, one From: mailbox at one of the DOMAINS and a verified DKIM signature by that domain (pepsi_ingress::exchange_tenant::proof). Exchange Online keeps a copy of that field that the sender wrote and adds its own below it, so a claim by another tenant shows up as two fields; DKIM does not cover the recipients, so the signature alone would let a signed message be sent again, and the single field is what refuses that. A proven message is local origin with auth_method = exchange-online, which never speaks for its From:. A certificate is requested only from a client that negotiates TLS 1.3: TLS 1.2 sends it in the clear, together with the person that it names, so a TLS 1.2 client is served without a request unless the listener sets TLS_AUTH_CLIENT_TLS12. A certificate is accepted only as a pinned key, or on a full RFC 5280 path to a CA given as a certificate. The path check covers path length, key usage, name and policy constraints, id-kp-clientAuth and revocation against the cached lists, which fails closed. A CA-issued certificate that names a mailbox may send as that mailbox alone. pepsi-ingress reads the file once and refuses to start on an error in it, since a skipped line would leave its network unbound. Speaking for an address needs more than being permitted to send as it. To register a key for it, or to operate its keys by e-mail, the From: must be exactly one mailbox named by a concrete (wildcard-free) entry of the map (state.origin.from_bound). A *@example.org grant lets an account send as every colleague, never plant a key for them.

Every From: mailbox is checked as a mail client reads it: quoted strings and RFC 5322 comments are skipped while the <...> address is located. We do this to avoid the address-parsing confusion of Ambiguous From headers checked as one address and displayed as another, where a gate that takes the last <...> in the field accepts ceo@example.com (<me@example.org>) as me@example.org while every client shows ceo@example.com. The decrypt, encrypt, key-learning and DKIM signing stages and the signer binding in pepsi-crypto use the same rule, so the address that a decision is made about is the address that the recipient sees. A message whose From: is missing, is a pure group, or holds a mailbox that cannot be read as an address is refused (550 5.6.0) for any session that USERNAME_MAP applies to, because there would be nothing, or not everything, to check.

Skipping comments settles only the shapes that every client agrees on. Where clients disagree, reading the first <...> would let the gate approve one address while the recipient is shown another, and the message would then be DKIM-signed as ours (CERT/CC VU#517845). So the gate also requires every mailbox to parse strictly as an RFC 5322 mailbox, and refuses (550 5.6.0) text other than comments and whitespace after the <...> address (<me@example.org>:<ceo@example.com>), a second <...> address in one mailbox, a display name that is not a phrase (ceo@example.com <me@example.org>), group syntax and source routes, and an RFC 2047 encoded-word inside the address. pepsi-stage-dkim-sign applies the same strict reading when it takes the signing domain from From:, and treats a field that fails it as having no usable From:, so it does not sign such a message as ours even when it arrived by another path.

A well-formed mailbox can still show the reader somebody else’s address: "ceo@example.com" <me@example.org> is a legal phrase, and many clients display only the name. The gate therefore also refuses (550 5.6.0) a mailbox whose display name or comments contain an address other than its own. The comparison is case-insensitive and judges the text as it is rendered: RFC 2047 encoded-words are decoded, the text is NFKC-normalised so that the full-width and small commercial at read as @, and invisible and bidirectional controls are removed. So "me@example.org" <me@example.org> stays allowed (pepsi_common::indicator::display_name_claim). Inbound mail with such a From: is not refused, since the receiving side cannot tell a whimsical name from a forgery, but marked: ingress removes any X-Pepsi-Warning that the sender wrote, prepends X-Pepsi-Warning: display-name-claims-other-address and records the claimed address as state.auth.display_name_mismatch. It is the one field of the X-Pepsi-* namespace the decrypt stage keeps on the outer header block, so the reader sees it; a copy inside decrypted content is the sender’s and is removed with the rest of the namespace. The From: itself is never rewritten, which would break the sender’s signature.

Removing reordering characters is right for that comparison and blind to their effect: a right-to-left override displays a reversed address as the one that it spells, which no comparison of the stored characters finds. Ingress therefore also marks inbound mail with X-Pepsi-Warning: from-has-bidi-or-invisible-characters (pepsi_common::indicator::from_has_display_controls) when its From: (encoded-words decoded) carries a bidirectional embedding, override or isolate control, a directional mark or an invisible character. The zero-width joiner and non-joiner and the variation selectors are exempt, since scripts and emoji need them.

The same characters in an attachment’s file name disguise its type: an invoice<RLO>fdp.exe is shown as invoiceexe.pdf. Ingress reads the file name of every MIME part, attached messages included, and marks inbound mail with X-Pepsi-Warning: attachment-name-has-bidi-or-invisible-characters when a name carries such a character. It takes the name from Content-Disposition filename or Content-Type name, decoded per RFC 2231 and RFC 2047 with mail-parser, to a depth bounded by MAX_MIME_DEPTH (pepsi_common::filename::message_has_disguised_filename). A message that the parser cannot read is not marked. The name stays as it is, since renaming the part would break the sender’s signature; the pages that Pepsi itself renders strip the controls from file names (Bidi override and syntax spoofing make displayed text differ from logical text).

A From: domain that is not a served domain but renders like one earns X-Pepsi-Warning: from-domain-resembles-served-domain. Rendering like one means having the same skeleton (pepsi_common::indicator::skeleton over the U-label form, the comparison that the decrypt stage makes for signers, pepsi_common::lookalike). It is the look-alike of the organisation’s own domain writing to its staff, which authenticates its own domain and so earns no other mark. The warning is a header field only, without the [external] tag: that tag says that a claim to be one of us was not proven, and a look-alike claims no served domain; a reader sees it through a Sieve rule or the client extensions.

The decision is recorded in the message’s state (local_origin, the authenticated identity) and believed by every later stage — which is exactly why A compromised component treats a compromised pepsi stage as able to forge it.

17.15.2. The submitter’s address stays out of the message

Upholds

Assets (correspondence metadata toward recipients): a message a user submits does not tell every recipient, and every list archive, where they sat and what they ran.

RFC 5321 §4.4 has ingress record the client that it accepted a message from, and on the submission hop that clause is the user’s current IP address, their reverse name and the name that their machine announced in EHLO. RECEIVED_PRIVACY is on by default for a SUBMISSION listener and for the local submission socket. On a listener with RECEIVED_PRIVACY, ingress writes the trace header without the from clause, the convention of draft-josefsson-email-received-privacy (Received: by <HOSTNAME> (pepsi-ingress) with ESMTPSA …), and removes the client’s User-Agent and X-Mailer fields with it, since a field naming the mail client, its version and the operating system gives away much of the same. What stays is what the message needs: the by clause that MAX_SELF_HOPS counts for loop detection, the RFC 3848 keyword, the TLS parameters, the for clause and the date. The edit happens before the trace header is prepended and before authentication, so the ARC seal and our DKIM signature cover the bytes as stored. The ingress journal records the client regardless, for abuse handling; the opt-in mail_log records no client address. An MX listener keeps the full clause by default: a remote peer’s trace is what the next hop’s abuse handling needs, and RECEIVED_PRIVACY can be set either way on any listener. The client’s own Message-ID and any other field it wrote pass through unchanged.

17.15.3. Mail from outside that claims to be ours is marked

Upholds

What a security indicator means ([external] and the X-Pepsi-Warning values mean exactly what they say), A remote sender (a forgery of a served domain that is delivered is not shown like a colleague’s mail) and the inbound half of Forged notices.

Inbound authentication is fail-open, so a message from the internet with a From: at one of the served domains is delivered unless DMARC_ENFORCE and the domain’s own policy refuse it, and until it is marked nothing that a reader sees distinguishes it from a colleague’s. On every message from an unauthenticated session, after SPF/DKIM/DMARC have been verified on the bytes as they arrived, ingress asks four questions (pepsi-ingress/src/external.rs). First, can the From: be read more than one way? It can when the strict reading that the submission gate uses (pepsi_common::domain::strict_mailbox_list) refuses it, or when it names mailboxes in more than one domain, so that clients may show different authors whatever the verdicts. Second, does a From: mailbox claim a served domain with neither a DMARC pass, a DKIM pass aligned with that domain nor an SPF pass on an aligned envelope behind it? Third, does a Sender: mailbox, the delegate that a client shows as “on behalf of”, claim a served domain with neither a passing DKIM signature nor an SPF pass organisationally aligned with it (Verdicts::dkim_pass_domains lists every passing signature’s d=)? Fourth, did DMARC evaluate to fail without the configuration acting on it, because DMARC_ENFORCE is off or the policy is none? A failure that a sealer in ARC_TRUSTED_SEALERS vouched for does not count. Each yes prepends an X-Pepsi-Warning (from-ambiguous, served-domain-not-authenticated, served-sender-not-authenticated, dmarc-fail-not-enforced), for Sieve rules and client plug-ins, and any of them puts [external] (TAG_EXTERNAL) at the front of the Subject, for the reader. Every value written is listed in state.auth.warnings.

A tag is worth something only if a sender cannot write it. Every message from outside therefore first has copies of the tag removed from the front of its subject, judged as a mail client renders it — RFC 2047 encoded-words decoded, look-alike characters folded, invisible and bidirectional controls removed, the longest matching tag taken whole (pepsi_common::indicator::strip_own_tags, the own-tag half of what the decrypt stage does for its tags). Only the [external] vocabulary is removed here; a subject like [Signed contract] is the decrypt stage’s business and stays on mail that never reaches one. A message without a Subject gets Subject: [external], since leaving the field out would otherwise be the way around the mark. The rewrite breaks a sender’s DKIM signature over Subject. That is why it runs after verification, so that the verdict stands on the signed bytes, and before storage, so that the ARC seal that pepsi-stage-arc adds covers what the recipient sees. Submitted mail is never marked or stripped: its From: is the submission gate’s business. EXTERNAL_SUBJECT_TAG = no leaves the subject alone and keeps the header fields. None of these fields is refused or rewritten: RFC 5322 permits a mailbox list and a Sender:, and rewriting either would break the sender’s signature, so a foreign Sender: (a mailing list, a delegation service) is left unmarked and a stranger’s own domain earns nothing.

17.15.4. Forwarded forgeries of our own domain

Upholds

A remote sender (a forged From: at a served domain is not turned into one that passes DMARC elsewhere).

Mail that this host forwards (an alias expanding off-site, a ~/.forward, the pure-relay path) is DKIM-signed as our domain when SIGN_RELAYED is on and its From: is at that domain; a forwarded message from another domain goes on unsigned by us, since the signing daemon signs only a From: aligned with d=. For a forwarded message whose From: is at that domain, our signature is the aligned one that DMARC looks for, so a forgery received from anywhere would leave this host passing DMARC. pepsi-stage-dkim-sign therefore does not sign a message that arrived from outside (state.local_origin not set), whose From: aligns with the signing domain, and that ingress authenticated neither by DMARC nor by a DKIM signature aligned with its From:; it is forwarded unsigned, as any forwarder without our key would send it. Alignment errs towards aligned without a public-suffix list (a parent, a subdomain, or a shared last two labels), and a From: that cannot be read strictly counts as aligned. Mail submitted here, mail that Pepsi composes itself (DSNs, notices, mailing-list copies, none of which carry ingress verdicts) and forwards of foreign domains are signed.

That closes the DKIM half. The SPF half is the SRS-rewritten envelope sender of a forward, which is at [pepsi-srs] SRS_DOMAIN and passes SPF at the next hop from our addresses. SRS_DOMAIN must therefore be a dedicated domain that is not aligned with any served domain: pepsi-setup refuses an aligned one (the same alignment heuristic, erring towards aligned) unless [pepsi-srs] ALLOW_ALIGNED_DOMAIN = yes, and the wizard asks for a dedicated domain rather than offering the primary one. A forwarded forgery then passes SPF for a domain that does not align with its From:, and DMARC at the next hop rests on the author’s own DKIM signature. An operator who opts out keeps the SPF route; publishing a quarantine or reject DMARC policy for our domains and enforcing it at ingress (DMARC_ENFORCE, which the wizard writes for a new installation) refuses such a forgery before it is forwarded.

17.15.5. The lifetime of our DKIM signatures

Upholds

A remote sender (a message we signed is not a lasting licence to send as our domain).

A DKIM signature binds neither the envelope recipients nor a time, so whoever holds one signed message can resend it to anybody and every copy verifies as mail of our domain; a stolen key signs anything. pepsi-stage-dkim-sign therefore puts an x= expiration seven days after signing on every signature (SIGNATURE_EXPIRATION_DAYS; 0 emits none). A week outlasts every receiver’s retry schedule, so legitimate mail is unaffected, while a copy replayed later, or a signature lifted together with a message, fails at every verifier that honours x=. Within the window a replay still verifies: binding the recipients needs DKIM2, an IETF draft, and the default header list only stops a replayer from adding a To:, Cc: or any other listed field (every one is over-signed). The key itself is long-lived unless [pepsi-dkim] ROTATION_DAYS rotates it (Rotating DKIM keys); a retired key’s records are kept RETIRE_AFTER_DAYS, which pepsi-setup validate holds above SIGNATURE_EXPIRATION_DAYS, so a rotation does not break mail in transit. ARC message signatures carry no x= unless [stage-arc] SIGNATURE_EXPIRATION_DAYS asks for one.

17.15.6. Pepsi’s own mail and the payment gate

Upholds

A remote sender: nobody we write to can use our proof of origin to skip the pay-to-send gate in front of our other users.

The secure-link portal’s link and PIN notifications are mail that this deployment composes with a human envelope sender. Such mail leaves through the relay and may come back through our own MX, where pepsi-stage-anti-spam would hold it for a payment that nobody will make. Such mail is stamped at injection with a Pepsi-Origin header carrying a for= field that names its envelope recipients, covered by the HMAC (pepsi_common::origin::Origin::stamp_for), so the field can be neither added to an ordinary stamp nor removed from this one. The gate forwards a message only when its own header block carries such a stamp that verifies, names every envelope recipient of the row, and has a nonce still tracked in pepsi.origin_nonce. A recipient who lifts the header into a message of their own can therefore exempt only mail to themselves. Ordinary outbound mail is stamped without for= and never exempts, though every correspondent holds such a stamp. A reply composed in the portal needs no stamp: pepsi-httpd injects it straight into the inbound path marked in state, which nothing outside Pepsi writes. The null-sender automatic replies are not stamped this way, since a stamped payment request would hand every unknown sender the means to skip the gate.

A null-sender message cannot be asked to pay or to confirm, since a bounce must never be bounced, so both spam gates ask it for proof of origin instead: it passes pepsi-stage-anti-spam and pepsi-stage-secretary only when some Pepsi-Origin field in it (a delivery report returns our header block in its body) verifies and has a tracked nonce, i.e. when it refers to mail we sent in the last two weeks. Without one, the payment gate routes it to BOUNCE_TARGET_STAGE (the wizard’s discard-rejected sink; unset, it is forwarded, which pepsi-setup warns about) and the secretary treats it as unchallengeable (UNCHALLENGEABLE_STAGE, else deleted). The proof says which of our messages a bounce refers to, not who sent the bounce: a correspondent holding an ordinary stamp from our mail can put it on a null-sender message of their own within its two weeks. With [pepsi-origin] ENABLED = no nothing can be proven: the payment gate diverts every bounce and the secretary passes every one, and pepsi-setup warns about both.

17.15.7. Whitelist rows demand an authenticated sender

Upholds

A remote sender: a forged From: naming a correspondent does not skip the payment or confirmation gate.

pepsi-stage-check-whitelist matches the addr-spec of the first From: mailbox, and a row says what must have authenticated it: dkim_required (a DKIM signature aligned with the From: domain, or an ARC pass together with DMARC), dmarc_required (a DMARC pass on either aligned identifier — aligned DKIM or aligned SPF — or a trusted ARC sealer’s override of a DMARC failure, state.auth.arc_override), signature_required (an end-to-end signature verified against a trusted key) and sealer_domain. A row with several requirements needs all of them. dmarc_required exists for the correspondent whose domain does not DKIM-sign: without it, such a sender either never matched a dkim_required row or was written into a row with no requirement, which anyone who guesses the address can satisfy wherever ingress does not refuse the forgery. The automatic writers therefore write the strongest level that the correspondent earned: pepsi-stage-secretary under DKIM_REQUIRED = auto writes dkim_required when a held message passed DKIM and otherwise dmarc_required when one passed DMARC (secretary_challenge.dmarc_seen), and pepsi-stage-auto-whitelist writes dmarc_required on every row unless DMARC_REQUIRED = no. A row without any requirement comes only from an explicit choice (pepsi-whitelist add --no-dkim-required, DKIM_REQUIRED = no, or a secretary confirmation of a sender that passed neither).

17.15.8. Mailing lists hold posts that failed DMARC

Upholds

A remote sender: a list does not turn a forged post into mail that it authenticated.

A list re-sends every post from its own envelope and signs it with its own key, so a recipient sees list mail that its provider authenticated, however the post arrived. pepsi-stage-list-post therefore holds for a moderator every post whose ingress DMARC verdict is fail, on every list whose hold_dmarc_failures setting is on. The setting is on by default for lists that Pepsi creates, and off for lists that the importers create from GNU Mailman, which holds no such post. The rule, dmarc-failure, comes after approved, loop and banned-address and before the header-match detour, so no header that a forger writes can jump the post to accept. It holds whatever policy the From: domain publishes, p=none included, since that policy asks receivers to do nothing and does not vouch for the mail. It also holds whether or not the poster is a member, because a member’s address is the one that a forger picks. A failure that a trusted ARC sealer vouched for counts as a pass. A post submitted here by an authenticated sender is not held, whatever verdict ingress recorded beside it, since SMTP AUTH and USERNAME_MAP proved who sent it. A moderator’s Approved: password releases a held post like any other hold.

17.15.9. A moderator password hash is upgraded when it is used

Upholds

Somebody holding a copy of the database: a list’s moderator password is guessed offline against the current Argon2id cost, not the one it was first stored with.

When an Approved: header carries a list’s moderator password and it verifies against a hash made with weaker parameters than new hashes get, pepsi-stage-list-post hashes it again with the current ones (pepsi_common::password::upgraded_hash_bounded, under the same per-CPU limit that the sign-ins use) and stores the result, but only while the stored hash is still the one that it verified against, so an owner’s newer password is never overwritten. The console and member sign-ins do the same for their own passwords.

17.15.10. Learning a mailing list for the whitelist

Upholds

Per-address settings are a trust boundary, against A remote sender: getting an ordinary message answered plants no whitelist rule.

A List-Id: is a header anybody can copy out of a real posting, so a list is learnt only from a deliberate act. With [stage-check-whitelist] RECORD_LIST_CONFIRMATIONS on, an inbound message that looks like a list’s subscription confirmation request is recorded in pepsi.list_confirmation for the recipient that it was delivered to. pepsi-stage-auto-whitelist (with LIST_WHITELIST_NAME) learns the list only when all of these hold: the outgoing message is locally submitted, it comes from the user to whom that request was delivered, it is addressed to one of the request’s control addresses, and its In-Reply-To: names the request’s Message-ID:. The row is written into the sender’s own <login>/... namespace, keeps dkim_required and dmarc_required, names no ARC sealer (pinning whichever sealed the request would be trust on first use), and ages out after LIST_MAX_IDLE_DAYS without an authenticated matching posting. pepsi-whitelist import proposes a list only from the user’s own replies in the scanned mailbox, and asks for each one. The pepsi-httpd role has no grant on list_confirmation.

17.15.11. Ambiguous MIME is settled at the boundary

Upholds

A remote sender: the filter behind pepsi-stage-milter, the list content filter and the recipient’s client read one MIME structure.

A message is parsed several times on its way to the reader, and where it is malformed RFC 2045 and RFC 2046 leave the reading to the parser: one takes the first of two Content-Type fields and another the last; one treats a multipart whose boundary never matches as a leaf and another salvages it; one decodes a misspelled base-64 and another does not. A sender who knows which parser the filter uses and which one the client uses can send content that the filter never sees. Pepsi has no scanner of its own, so the differential is between an external filter and the client; the fix is to leave neither a choice.

pepsi-ingress classifies every message at DATA (pepsi_common::mime_anomaly), on the bytes as received, descending every multipart/* and message/rfc822 entity to the same depth as the 8BITMIME downgrade. The hard classes have no right reading and are refused 554 5.6.0 under MIME_ANOMALIES = enforce, the default: an empty boundary=, a NUL byte in an entity’s header block (which hides a field name from one parser and not another), two Content-Type or Content-Transfer-Encoding fields on one entity that differ, a boundary that is or contains an RFC 2047 encoded-word, and differing copies of a message-header Date, Subject, To, Reply-To or Sender field. RFC 5322 §3.6 allows each of those once; clients show one copy or the other, and RFC 6376 §5.4.2 makes a signature that names the field once cover the bottom copy, so a field added above a signed one by somebody replaying the message passes DKIM while the reader may be shown the addition. Refusing it does not depend on the signer having over-signed. Differing Cc fields are the one marked class: some clients write a second Cc: line as the user typed it, so the message is stored as received with X-Pepsi-Warning: duplicate-header-cc (What a security indicator means). Eight soft classes are shapes that the standards already say how to decode, and the message is rewritten to that reading before it is stored: an unrecognised transfer encoding makes the entity application/octet-stream with its octets as they stand (RFC 2045 §6.4), whitespace after a quoted-printable soft break is deleted (§6.7), characters outside the base64 alphabet are removed (§6.8), a multipart without a close delimiter gets one (RFC 2046 §5.1.1), an epilogue that holds another delimiter line of the same boundary is dropped (§5.1.1 says to ignore the epilogue, so the part that some readers would show there is none), and a second identical field is dropped — a MIME field of any entity, or one of the singleton fields of the message header (those above plus Message-ID, In-Reply-To and References, whose differing copies decide threading only and are left alone). A signed or encrypted entity (multipart/signed, multipart/encrypted, PGP/MIME, S/MIME) and everything inside it is never rewritten, since a signature covers the encoded octets; a hard class inside one still refuses the message, because a refusal rewrites nothing.

The order is verify, normalise, seal. A DKIM signature is judged on the bytes that it signed, so SPF, DKIM and DMARC run first and state.auth is unaffected by the rewrite; the rewritten message may then fail its own DKIM signature at the next hop, which is what the ARC seal is for, and the seal has to cover the bytes that are stored. For a message that arrived without an ARC chain, and for a submission (never sealed), ingress rewrites before storing. A message carrying a chain is stored as received and marked state.mime_normalise; pepsi-stage-arc verifies the chain over those bytes, rewrites, and seals the rewritten message, so cv= reflects the chain as it arrived and the ARC-Message-Signature covers what is forwarded (Authenticator::arc_seal takes both). The classes found are recorded as state.mime_anomalies and who rewrote as state.mime_normalised; MIME_ANOMALIES = log records and counts without refusing or rewriting, and marks every differing header field X-Pepsi-Warning: duplicate-header-<field>.

What this does not close: shapes outside those classes are stored as received, as is anything nested deeper than MAX_MIME_DEPTH (32) levels. Such shapes include a header line with no field name, an invalid quoted-printable escape, an unparseable Content-Type and a multipart whose boundary never occurs in its body. Pepsi adds no client-like second parse of its own; the external filter still parses the stored message in its own way, but a parser that honours the standards reads the same structure as the client.

17.15.12. Re-sealing decrypted mail for storage

Upholds

Client custody (custody = client, the MUA key) (mail that the gateway opened is filed readable only by the user’s own client) and The guarantees at a glance (the Filed mail column).

pepsi-stage-decrypt has to produce plaintext: the spam, language, whitelist and key-learning stages after it read the content. pepsi-stage-reencrypt runs once they have, immediately before local delivery, and seals the message to every active custody = client key of the recipient, so that a hardware token and its backup both open the filed copy. It uses one protocol per message, the newest key’s, and a key that the policy refuses is dropped alone rather than costing the user the others. The mechanism rests on four choices:

  • It needs no privilege. Sealing to a public key uses no private material, so the stage runs as pepsi, is folded into the multi-call binary, and reads only the public columns of crypto_identity under the ordinary pipeline grant. It never names private_wrapped, and gaining the pepsi-crypto identity would give it nothing it uses.

  • It signs nothing. A gateway signature would only say “the gateway sealed this”, indistinguishable in a client from authorship, and would need the setuid identity. The verdict on the sender’s signature is the one that decrypt recorded, in state.crypto.in and in X-Pepsi-Crypto. That field stays on the outer block, and decrypt strips it from every inbound message before writing its own, so it is still ours when the client reads it.

  • It acts only on what decrypt opened (state.crypto.in says encrypted and decrypted), and records state.crypto.store, which also stops it from ever sealing a row twice. Mail that arrived in cleartext is not sealed.

  • A refusal returns nothing that was encrypted. Under ON_NO_CLIENT_KEY = bounce the DSN’s header block is cut to the addressing fields, the body is emptied and RET=HDRS forced, since the sender encrypted the message and a DSN travels in clear (see Bounces after gateway decryption reveal decrypted content). It bounces rather than defers, because deferring would keep the plaintext queued longer.

The residual is the one that A compromised component already states: a compromised pepsi stage, the re-encryption stage included, sees the plaintext while it is queued and can route a message past the stage, so the guarantee is about copies already filed, which nothing on the server can open.

17.15.13. Revocation is published while the key can still sign it

Upholds

Gateway custody (custody = local, the MTA key) (a revoked MTA key is announced, not merely dropped) and Client custody (custody = client, the MUA key) (a client key’s revocation is the client’s).

A revocation that only marks a row revoked tells nobody: the Web Key Directory would stop answering, every correspondent would keep the key it has, and a key server that had the key would serve it for ever. And it cannot be repaired later, because revoking a signing key destroys the private half that a revocation certificate must be signed with. So:

  • One function revokes, on every surface. pepsi-keys identity revoke, the retire e-mail command and the revoke-identity task that the console and the API enqueue all call pepsi_keymat::revoke. For an OpenPGP key whose private half is held it unwraps the key (as the pepsi-crypto role, like every revocation, since it names private_wrapped), checks that the stored public half belongs to it, signs the revocation certificate, merges it into the public half and revokes the row — certificate, status and purge in one UPDATE (revocation_certified_at records it). If the certificate cannot be made, nothing changes and the request fails or is retried.

  • The Web Key Directory serves a revoked key with its certificate, after any usable key of the address, so a client reading only the first certificate still gets a usable one; a key revoked without a certificate (S/MIME, a client key, a private half already destroyed) is not served at all.

  • The key server gets the revocation where it got the key. A revoked key with vks_published_at set is on the second work list of pepsi-keys identity publish --retry until the key server accepts the revocation (vks_revoked_at); the upload is spaced and capped like any other. The stage and the applier never talk to a key server themselves.

  • The reply says what was published (certificate or not, WKD or not, key server or not) rather than “retired”, which a user reads as “revoked for everyone”.

No escrow or gateway key exists for client-custody mail, by decision; the recovery path is a second registered client key (Losing a client key).

17.15.14. What an S/MIME trust anchor vouches for

Upholds

What a security indicator means, against A remote sender: a CA the operator trusts for one namespace cannot make valid appear for another.

An organisation that exchanges signed mail with a partner often trusts the partner’s CA only for the partner’s own domain — by cross-signing it with nameConstraints, or by anchoring a partner sub-CA that carries them. If the bound were ignored, that partner CA could issue a certificate for one of this deployment’s users and the decrypt stage would call the signature valid. pepsi-crypto::trust therefore runs RFC 5280 §6.1’s constraint state down every chain it builds:

  • Name constraints apply to the subject DN, every subject alternative name, and every emailAddress attribute in the subject DN — the last always, because that attribute is what a message is bound to when the SAN names no mailbox. An RFC 9598 SmtpUTF8Mailbox binds From: too, so it is held to the rfc822Name subtrees by its domain (as A-labels), and a subtree naming one ASCII mailbox admits none (RFC 9598 §6). Permitted subtrees intersect down the chain (two CAs permitting disjoint domains leave no mailbox permitted, not every one); excluded subtrees accumulate. A sub-CA cannot widen what its parent delegated.

  • The anchor’s own constraints bind it (RFC 5937), so anchoring the partner’s sub-CA directly is as safe as cross-signing it.

  • The operator’s scope binds it too. Most CA certificates carry no nameConstraints at all, so a CA anchored for one partner would otherwise vouch for every domain. pepsi-keys ca add --domain / ca scope (and the console’s and API’s trust-anchor pages) store the mail domains that an anchor is trusted for in ca_trust.permitted_domains, and path validation applies them as RFC 5937 trust-anchor constraints: an rfc822Name permitted subtree per domain, covering the domain and its subdomains, checked against every mailbox of every certificate under the anchor (the same names that the certificate’s own constraints are checked against) and against the From: address being verified, so a leaf that names no mailbox does not carry the anchor outside its scope either. It is intersected with the anchor’s own constraints – a mailbox must satisfy both. A mailbox outside the scope means this anchor does not vouch for it (unknown-issuer, so valid-untrusted), and another anchor may still; a revocation list verified through a scoped anchor retires only certificates inside the scope. An enabled anchor with neither a scope nor constraints of its own is reported by pepsi-keys ca list, pepsi-status and pepsi-setup check. The scope covers S/MIME signature trust only; outbound TLS validates servers against the system’s root store (or TLS_CA_BUNDLE), which no scope limits.

  • Policy constraints (requireExplicitPolicy, inhibitPolicyMapping, inhibitAnyPolicy) are evaluated over the full policy tree, in a deduplicated form whose size is polynomial in the policies that a certificate names, and capped (64 policies or mappings per certificate). The tree that grows exponentially in the naive algorithm is the OpenSSL CVE-2023-0464 denial of service. Name checking is capped at 220 comparisons per certificate for the same reason.

  • What cannot be honoured is refused. An unprocessable constraint makes the chain policy-rejected rather than valid without the bound. Such a constraint is a subtree form that Pepsi does not match, when a name of that form appears below it; a minimum or maximum; or an undecodable extension, critical or not. Where Pepsi departs from RFC 5280 or from OpenSSL it is always in that direction: a wildcard dNSName that can stand for an excluded host is refused, and a host-less URI under a URI constraint is refused.

The bound applies to the names that a certificate carries. A signer certificate that names no mailbox at all is bound to no address and is accepted, so it verifies for any From: (Weak binding between signer certificate or key and the From address).

Two further rules close gaps between implementations:

  • Every path is tried. Several certificates can qualify as the issuer of one certificate (a CA’s old and new key, a cross-certificate beside the original), and the first that verifies may lead to no anchor, or to a chain whose constraints refuse the leaf. Path building backtracks over all of them, trust store first, so a certificate added to a message cannot hide a valid path; the search is capped at 64 candidate issuers per signature, which no real PKI approaches.

  • A certificate that RFC 5280 forbids is refused, not interpreted. An extension present twice (section 4.2), extensions in a certificate that is not version 3, or unique identifiers in a version 1 one (section 4.1.2), make the certificate policy-rejected, as a leaf and as an issuer: implementations disagree about which of two keyUsage or nameConstraints values counts, so what the issuing CA checked need not be what Pepsi would rely on.

A mailbox name binds only when it is a bare local@domain, as RFC 5280 §4.2.1.6 requires of an rfc822Name. A CA that validated only the first address might issue a value such as mallory@attacker.example <alice@example.org>, but such a value names nobody: Pepsi never searches it for an address, and a certificate whose only mailbox name is malformed is a mismatch for every From:, not an unbound certificate.

The rest of a signature check does not take the signer’s word either:

  • The chain is validated now, not at the signingTime the signature states. That attribute is chosen by the signer (RFC 5750 §5), so a backdated one would otherwise revive a certificate that has expired. It is still reported, as information.

  • The key-size floor covers the whole chain. CRYPTO_MIN_RSA_BITS applies to every intermediate as well as the leaf; only a configured anchor is exempt, being the operator’s own choice.

  • A long RSA key can still be a broken one. Three kinds of RSA modulus give away their private key whatever their length, and all are recognised from the modulus alone: the ROCA fingerprint of Infineon’s RSALib (smart cards, TPMs, YubiKey 4 tokens; CVE-2017-15361), tested exactly as the published detector does; primes so close together that Fermat’s method factors the modulus within 100 steps, as the badkeys project found devices generating; and a prime factor below 65536, found by trial division. Such a key is refused wherever a key below CRYPTO_MIN_RSA_BITS is refused, since anybody can sign with it and read what is encrypted to it: as an S/MIME leaf and intermediate (weak-key), as an OpenPGP signing key and as a recipient key of either protocol.

  • A key whose private half is known is refused too. Each deployment keeps the badkeys blocklist in its database (pepsi.compromised_key): truncated SHA-256 hashes of about three million public keys whose private halves are public. They include every RSA and EC key that the Debian OpenSSL bug (CVE-2008-0166) could produce for OpenSSL and OpenSSH, and keys published in RFCs, test suites, documentation, firmware and software packages. The hash is over the key’s public value (an RSA modulus, an EC x coordinate, a raw Ed25519/X25519 key), so a listed key matches whatever certificate or OpenPGP packet carries it, of any key type. A match is refused wherever a short key is, and key discovery, harvesting and pepsi-keys peer import refuse to store it. pepsi-keys blocklist update keeps the list current (pepsi-keys-blocklist.timer, daily): it asks [pepsi-keydiscovery] BADKEYS_URL with the last run’s ETag, downloads a changed list only from below that URL over verified TLS, checks it against the SHA-256 its metadata names, and only ever adds entries. That metadata is not signed, so TLS to the list’s server is what vouches for it. An update whose list shrank, or that would grow the table by more than a quarter, is refused until the operator forces it, and every run records what it added from which source list. Only pepsi-crypto may write the table, and not the stage workers that parse hostile mail, because a forged entry would make Pepsi refuse a correspondent’s key. A wrong entry is dismissed (pepsi-keys blocklist dismiss), never deleted, so no update brings it back. The list is defence in depth: before the first update, or when a lookup fails (it is logged), the other checks still run, and pepsi-status warns when the list has not been checked for three days.

  • Keys that share a prime are found. pepsi-keys peer screen, which pepsi-keys-refresh.service runs daily, computes a batch GCD (product and remainder trees) over every RSA modulus in the peer-key cache and our own identities’ public halves. Two keys that share a prime are the trace of a generator short of entropy. A cached key that shares a prime with another is deleted, logged as key.peer.compromised, and its modulus added to the known-compromised list (pepsi.compromised_key, source screen), so a rediscovered copy is refused as well. One of our own identities that shares a prime is reported (key.identity.compromised, severity error) for the operator to revoke, never changed automatically. A key learnt since the last screen is not covered until the next one, and a shared prime with a key that this deployment has never seen cannot be found.

  • The signed attributes are unambiguous. A SignerInfo must carry exactly one contentType (equal to the content type it signs), one messageDigest and at most one signingTime, each with a single value, and no attribute twice. When the RFC 6211 CMSAlgorithmProtection attribute is present it must repeat the SignerInfo’s digest and signature algorithm identifiers exactly (absent and NULL parameters being the same), or the signature is bad-signature: those identifiers lie outside the signature, and the attribute is what puts them under it. Its absence is accepted, because most clients omit it; every signature Pepsi makes carries it. A signature without signed attributes is refused when its content is itself a DER attribute set: such content can only be another signature’s attributes, lifted out to make that signature verify over bytes that its signer never signed as content.

  • A CRL is evidence only if it can be believed: signed by the issuer’s key, with cRLSign permitted, current (its nextUpdate not passed), and in scope for the certificate. A partitioned list for another distribution point, a delta, an indirect or a reason-limited list, or one carrying a critical extension that the verifier does not process, says nothing about a certificate outside it, and is not consulted for it.

  • Revocation lists are fetched ahead of time, outside the stages. pepsi-keydisc fetches the CRLs that the cached S/MIME peer certificates name in cRLDistributionPoints (http:// and https:// only; there is no OCSP) into pepsi.crl_cache, with the same SSRF check, deadline and byte cap as a key fetch and no redirects. It refuses a list that is stale, dated in the future or older than the one stored (a replayed old list would un-revoke a certificate), and refetches at the list’s nextUpdate but at least daily. Only the pepsi-keydisc role writes the cache; the decrypt stage reads it. Checking soft-fails: a list that cannot be fetched, is stale, does not verify or does not cover the certificate leaves the revocation verdict at “not checked”, never “not revoked”; a listed serial makes the signature bad (revoked).

  • A revoked certificate is retired from the cache, so it is no key for anybody. pepsi-keydisc acts on a stored list only when it can believe the list on its own. The list must be current, and signed either by an enabled trust anchor of the issuer’s name with cRLSign permitted, or by an intermediate CA certificate fetched under CA_ISSUERS_FETCH (below) that itself path-validates to an enabled anchor (every signature on the path verified, validity, CA flag, path constraints, cRLSign). Every cached certificate that names that distribution point, has that issuer and lies in the list’s scope is then checked against the list, and a listed one is marked revoked in pepsi.peer_key (revoked_at, revoked_reason). The shared lookup that every stage uses then withholds the row: pepsi-stage-encrypt has no key for the recipient and follows ON_NO_KEY, reporting revoked as the reason, with no revocation code of its own. The row is kept, not deleted, so the operator sees why (pepsi-keys peer list), a directory still serving the old certificate cannot bring it back (the same fingerprint is refreshed, never un-revoked), and a re-issued certificate from the same source replaces it (a revoked row does not refuse an equal-ranked key; it still refuses a weaker one, so a stranger’s Autocrypt header cannot fill the gap). The anchor requirement is the point: a distribution point is usually plain HTTP, and acting on an unverified list would let whoever is on that path send a correspondent’s mail in the clear. Such a list is stored for the verifier and acted on by nothing; so is one from an intermediate CA that was not fetched or does not chain to an enabled anchor. An intermediate that a certificate merely names is never believed on its name. The soft-fail stands: a list that cannot be fetched changes nothing.

  • An expired certificate is no key either. Before it chooses a key, pepsi-stage-encrypt sets aside a recipient’s S/MIME certificate outside its validity period, and an OpenPGP key past its expiry, so the recipient takes ON_NO_KEY with expired on and the date as the reason, and discovery is asked for a renewed one; the CMS builder refuses such a certificate for every other caller.

  • Missing intermediates are fetched, never trusted. Under [pepsi-keydiscovery] CA_ISSUERS_FETCH (off by default: a fetch tells a CA whom the site corresponds with), pepsi-keydisc follows the http:///https:// caIssuers pointers of the cached certificates and stores the CA certificates of each answer in pepsi.ca_issuer_cache, which only its role writes. It never follows LDAP, goes at most three levels up, and applies the CRL fetch’s SSRF check, deadline and no-redirect rule and a 64 KiB cap. The verifier searches them last and only for an issuer: never as a signer, never as an anchor, so a forged answer can fail to complete a path but cannot make one. Their own distribution points are harvested into the CRL cache, so a path through one can be covered, and a list that one of them signed counts for retirement only once that very certificate has been validated up to an enabled anchor. A sender’s certificate learnt from earlier mail does not stop the search either: it is validated against the anchors like one the message carried, and its learnt standing counts only when no path is found.

The NIST PKITS conformance suite (sections 4.6 and 4.8–4.13, every input setting it lists) runs in cargo test, alongside a corpus of our own for the forms PKITS does not cover (IP addresses, unimplemented forms, a name-constrained anchor).

17.15.15. What an OpenPGP certificate binds

Upholds

What a security indicator means and Keys of correspondents, against A remote sender: a certificate that somebody else assembled cannot lend a genuine signature a different author, and an old copy of a certificate cannot bring a revoked key back.

An OpenPGP certificate is a bundle of packets held together only by the primary key’s signatures, and anybody can add packets to somebody else’s bundle. Pepsi believes only what the signatures bind:

  • A User ID binds an address only when it is self-signed and not revoked. The signer binding (the From: against the certificate’s addresses), the Web Key Directory’s choice among the certificates that it is served, harvesting and pepsi-keys peer import all read the User IDs that are valid under the read policy, so a User ID packet appended without the owner’s self-signature, or one that its owner has revoked, names nobody.

  • A signing subkey must say so itself and carry its back signature. The subkey’s own binding signature must carry Key Flags with “signing”, and must embed a valid primary key binding signature made by the subkey. Otherwise a signature that it made is refused as wrong-key-usage. sequoia-openpgp 2.4.2 demands the back signature only when the binding’s own flags say signing, but treats a subkey whose binding has no flags at all as signing-capable through the primary key’s direct-key signature (CVE-2026-42784); without this check, anybody could attach a correspondent’s public signing subkey to their own certificate and have that correspondent’s signatures verify under it.

  • Seeing a key again never forgets what was known about it. When a key is stored again under the same fingerprint, the stored and the incoming copies are merged (and pruned of unverifiable signatures and of components nothing binds) before the row is written, inside the same lock as the conflict rule. A revocation, once seen, therefore stays, however old the copy that arrives next; a replayed pre-revocation Autocrypt header cannot make pepsi-stage-encrypt resume encrypting to a key that its owner gave up. The merge is written even when the incoming copy comes from a source ranked below the stored row’s (a revocation first seen in a correspondent’s own mail reaches a key imported by hand), keeping the row’s source and rank: only signatures that verify against the key itself survive the merge, so a weaker source can add the owner’s own statements about the key but cannot change which key is used or how far it is trusted.

Third-party certifications are never evaluated (trust comes from where a key was found, see Keys of correspondents) and are dropped when a certificate is stored.

17.15.16. Who a signed and encrypted message was for

Upholds

What a security indicator means, against A remote sender: a correspondent cannot pass a message that somebody signed for them on to a third party as if it had been signed for that third party.

A signature says who wrote some words, not to whom. When Alice signs and encrypts a message to Bob, Bob can decrypt it and re-encrypt the very same signed packets to Carol; nothing in the signature changes, so without more, Carol holds a valid signature from Alice on a message Alice never addressed to her (“surreptitious forwarding”). RFC 9580 section 5.2.3.36 closes this for OpenPGP with the Intended Recipient Fingerprint subpacket, which puts the recipients inside what the signature covers. S/MIME has no standard field for it, so Pepsi writes a private signed CMS attribute that does the same: a SEQUENCE OF OCTET STRING holding the SHA-256 of each recipient certificate’s DER, under the object identifier 1.3.6.1.4.1.32473.808069.1 (an arc of the RFC 5612 documentation enterprise number, provisional until the project holds an IANA enterprise number of its own, so that it cannot collide with a registered attribute).

  • Emitting. Whenever pepsi-stage-encrypt signs and encrypts, the signature names every certificate that the message is encrypted to: the primary fingerprint in an OpenPGP packet stream, the certificate digest in the S/MIME signed attributes. Since the stage encrypts each copy to one recipient (and that recipient’s own client keys), it reveals nothing that the copy’s own encryption does not reveal. A cleartext signature names nobody: it has no recipient key to name.

  • Verifying. When pepsi-stage-decrypt opens a message and the signature inside names one or more intended recipients, none of which is the certificate whose key opened it, the signature is invalid with the layer verdict wrong-recipient (a signature that would not have verified anyway stays bad-signature). For S/MIME the comparison is with the digest of the certificate of the identity that opened the EnvelopedData or AuthEnvelopedData. A signature that names no recipient is judged without this check, because most OpenPGP clients still omit the subpacket and no other S/MIME client writes the attribute; a malformed attribute names nobody.

The protection is therefore only as wide as its adoption by the signer: mail signed by a client that omits the subpacket or the attribute can still be forwarded this way undetectably. Other S/MIME clients ignore Pepsi’s attribute, as RFC 5652 section 5.3 has a verifier ignore any signed attribute that it does not recognise, so for them the defence is the protected To: and Cc: that PROTECT_HEADERS (off by default) puts inside the signature, and the RFC 8551 section 3.7 triple wrap, which signs the encrypted message again; both depend on the sender too.

17.15.17. Correspondents who usually sign

Upholds

What a security indicator means, against A remote sender: a forged From: of a correspondent whose mail is normally signed does not pass as ordinary unsigned mail.

A signature protects against impersonation only if its absence is noticed, and the missing [verified] tag is easy to overlook (No warning when a usually-signing contact sends unprotected mail). pepsi-stage-decrypt therefore remembers who signs. A signature earns valid when it is made by an anchored key bound to the From: address, and every such signature records the address, the key and the time in pepsi.signed_sender. Because only valid writes there, the record cannot be planted or refreshed by anyone who does not hold the correspondent’s anchored key. A later message from that address that carries no valid signature (unsigned, unverifiable, valid-untrusted or partial) within MISSING_SIGNATURE_WINDOW_DAYS (default 90) is handled under ON_MISSING_SIGNATURE: record (the default) writes usually-signed=<date> into X-Pepsi-Crypto and state.crypto.in.usually_signed for Sieve rules and the client extensions; tag also prepends [unsigned, usually signed] (TAG_MISSING_SIGNATURE, stripped from inbound subjects like every own tag); quarantine holds the message at QUARANTINE_STAGE. The default only records because a correspondent writing from a phone or a new client produces exactly this shape. A message that the stage could not open is not judged, an invalid signature is left to ON_BAD_SIGNATURE, and an error reading the record counts as no record: the mechanism only ever adds a mark. The table holds who signed mail to this deployment and when; the web tier, ingress and the telemetry collector have no grant on it.

17.15.18. Protected headers against the outer ones

Upholds

What a security indicator means, against A remote sender: a signature that vouches for a message from one address does not mark a message shown as coming from another as verified.

OpenPGP/MIME and S/MIME sign the body, not the RFC 5322 header block, so the From:, To: and Subject: that a reader is shown are covered by nothing. A signer who wants them covered copies them into the signed entity: RFC 9788’s injected headers (which pepsi-stage-encrypt writes under PROTECT_HEADERS), or a signed message/rfc822. pepsi-crypto reports those protected copies on the signature layer that covers them, read before the recovered entity is reduced to its Content-* fields (which is what keeps a sender from injecting a second From: into the delivered header block). pepsi-stage-decrypt then compares them with the outer fields, for every signature over the plaintext:

  • A different protected From: withholds valid. When the protected From: names another addr-spec than the outer From: (first mailbox, compared case-insensitively, as everywhere else), the verdict is valid-untrusted: no [verified] tag, no state.signature_verified. Two disagreeing protected From: fields, an illegible one, or no legible outer From: count as a difference. This is the surreptitious-forwarding shape that the intended-recipient check above cannot see without an encryption context or a cooperating signer: a signed message re-sent under the forwarder’s own From:, so that the certificate binding to the outer address passes.

  • A different, added or removed reply-steering field withholds valid the same way (withheld=reply-to). The reply-steering fields are Reply-To:, Mail-Reply-To: and Mail-Followup-To:. These are the fields that a reply-redirection attack changes (Reply-steering header parsing (Bcc on reply-all, header-name prefixes)), and the ones that PROTECT_HEADERS itself copies inside for that reason; an outer one that the signer did not protect counts as a difference, and each is reported under its own name. The one exception is a field that a mailing list added, recognised by a List-Id: with none of the three signed. Such a field keeps valid under the tag [verified (except reply-to): …], so the key fact survives and list reply-to munging keeps working, at the price of one more tag to understand, for list users only. Sender: is not compared: lists and delegates set it legitimately, and a client that replies to it is wrong regardless of any signature.

  • A Subject: that only gained bracketed segments in front is no difference: a list tag, an [external] marker, Pepsi’s own tags on a message that went round once. Both subjects are compared as a reader sees them (RFC 2047 decoded, whitespace normalised, forged indicators and Pepsi’s own tags stripped first), and the signer’s own bracketed segments must survive in order. A larger difference promotes the signed subject over the outer one when the signature is otherwise valid, so the message stays [verified] under the subject its signer wrote; a marker written without brackets, such as EXTERNAL:, is thereby removed. The difference is reported either way.

  • A protected Subject: carrying a forged indicator withholds valid. The outer subject is cleaned of forged tags before delivery, but the protected one sits inside the signed entity, which cannot be rewritten without breaking the signature, and a client that shows protected headers shows it. The same sanitiser (indicator::strip_forged_tags) is therefore run over the protected Subject. When it would change that subject (a security tag or a look-alike of one at the front, an indicator symbol, a bidi control), the verdict is valid-untrusted (withheld=protected-subject). The tags Pepsi writes are not sent on: pepsi-stage-encrypt removes them from the subject of outgoing mail before signing (see Indicator tags do not leave the deployment), so a reply to a verified message keeps valid at a receiving Pepsi deployment.

  • To: differences are only reported, in state.crypto.in.protected_mismatch and the protected-mismatch key of X-Pepsi-Crypto. Forwarders and list software change it legitimately, and header protection replaces the outer subject by design (an outer ... or [...] is not a difference).

What this does not do: it changes nothing for a sender who protects no headers (the common case), so a signed message forwarded under a spoofed From: naming its author still verifies, and a Reply-To: added to such a message is not seen; a list that rewrites the outer From: of signed mail costs that mail its valid, as does a client that protects some headers but not the reply-steering fields on a message whose sender set one; and apart from the subject promotion, protected copies are never promoted onto the delivered header block. PROTECT_HEADERS = yes in pepsi-stage-encrypt makes the mail that Pepsi signs carry its protected From:, To:, Reply-To:, Mail-Reply-To: and Mail-Followup-To:; it is off by default because a client that does not render protected headers then shows ... as the subject of every encrypted message.

17.15.19. Indicator tags do not leave the deployment

Upholds

What a security indicator means: a tag is a statement that this deployment makes to its own user, and a reply does not carry it to someone else’s.

A user who replies to [verified: a@example.org] report writes Re: [verified: a@example.org] report. Sent on, the tag would tell the recipient nothing true, and once PROTECT_HEADERS copies the subject into the signed part, a receiving decrypt stage would read it as a forged indicator and withhold valid from the reply (see Protected headers against the outer ones). pepsi-stage-encrypt therefore removes Pepsi’s own tags from the subject of every message that a local user sends, before the subject is signed or protected (pepsi_common::indicator::strip_local_tags): the built-in [decrypted], [verified …] in every shape, [decrypted, unauthenticated], [unverified signer], [bad signature], [unsigned, usually signed] and [external], plus whatever each decrypt stage’s TAG_* options and [pepsi-ingress] TAG_EXTERNAL configure. They are matched by skeleton, as the inbound strip matches them, at the front of the subject and behind Re:/Fwd: prefixes and list tags, but only in their bracketed form: a group that merely shares a word with a tag, a Verified: written as prose and the rest of the text stay exactly as the user wrote them.

17.15.20. What [verified] binds the signer to

Upholds

What a security indicator means, against A remote sender: the tag names the signer, and is granted only for the From: line as the reader sees it.

pepsi-crypto binds the signer’s key to the first mailbox of From:, and a key naming other addresses fails (identity-mismatch). The key’s address is an OpenPGP User ID address, an S/MIME rfc822Name or RFC 9598 SmtpUTF8Mailbox (the local part octet for octet, the domain as A-labels, as that RFC prescribes), or the subject’s emailAddress (an IA5String, or an ASCII-only UTF8String; a non-ASCII one binds nobody, since only SmtpUTF8Mailbox defines how such a mailbox compares). That binding is necessary and not sufficient, because a reader does not see an addr-spec; they see a line whose display name the sender writes, whose other mailboxes nothing bound, and whose domain renders as whatever it looks like. pepsi-stage-decrypt therefore writes the bound address into the tag, which sits in the one field that every client shows: [verified: alice@example.org]. It withholds valid (valid-untrusted, withheld= in X-Pepsi-Crypto) when:

  • the display name or a comment shows another address (pepsi_common::indicator::display_name_claim, the same judgement that ingress records as state.auth.display_name_mismatch): From: "Alice <alice@victim.example>" <x@attacker.example> signed with the attacker’s own anchored key is not [verified];

  • the From: names more than one mailbox: only the first was bound;

  • the certificate names no mailbox and chains to a ca_trust anchor (Binding::NoIdentity): it contradicts no From:, so the verifier does not fail it, but it vouches for no address, and would otherwise be valid for every sender and satisfy signature_required whitelist rows. The operator may opt an anchor in per anchor (pepsi-keys ca accept-nameless), for a CA whose issuance process binds each leaf to its holder out of band; a key found by looking the address up (WKD, DANE, a pin, our own identity) is bound by the lookup;

  • the signer’s domain is a look-alike of a served domain or of a domain in the key store or the from whitelist: equal skeletons (pepsi_common::indicator::skeleton: decomposition, mark stripping, Cyrillic/Greek/digit folding), different domains. Pepsi compares identities exactly everywhere else, so a homograph never matches a stored key or a whitelist row; this is the one place it is looked for, because the tag would otherwise lend the imitated name its credibility. The A-label is written to X-Pepsi-Crypto (signer-domain=);

  • the signature was made long before the message arrived: more than MAX_SIGNATURE_AGE_DAYS (default 7) before this host’s arrival time, or more than a day after it (old-signature, future-signature). A signed entity captured earlier and replayed under fresh outer headers keeps a genuine signature (Signature spoofing via partial signing and MIME/CMS wrapping, Invalid, expired or old signatures reported as valid), but the tag would claim that its signer sent this message at this time. The arrival time is this host’s record, not the Date: that the replayer writes; the claimed signing time is shown as signed-at= in X-Pepsi-Crypto. A signature without a creation time (CMS without signingTime) carries no evidence and is not judged.

A verified inline clearsigned block is partial when its delivered bytes show the reader unsigned text: armor header lines other than Hash:, which the armor reader accepts without hashing, or a block rendered as HTML. Such a block gets no tag and no state.signature_verified, and is left as it arrived for the reader’s client to re-verify (OpenPGP cleartext and detached signature parsing lets unsigned text pass).

What this does not do: a legitimate internationalised domain whose skeleton equals a known ASCII one is delivered and verified but not tagged; the look-alike list is read from the database once per TRUST_ANCHOR_TTL, so a correspondent added since is compared on the next read; a replay within the signing-time window still verifies; and the [verified] tag still says nothing about a sender that signs nothing.

17.15.21. Which S/MIME container a correspondent gets

Upholds

Keys of correspondents, against A remote sender: S/MIME mail is sent as authenticated encryption unless the recipient’s own client is recorded as unable to read it, and nobody but the holder of a certificate can make that record for it.

AES-256-CBC EnvelopedData has no integrity protection, which is what CBC gadget attacks against the recipient’s client build on (EFAIL: CBC/CFB malleability gadgets exfiltrate decrypted mail); AES-256-GCM AuthEnvelopedData has. Some clients (Thunderbird, measured) read only the former, and an X.509 certificate states no content-encryption capability, so the choice is made per recipient from the S/MIME capability record (The per-peer S/MIME capability record):

  • No record means AEAD. Under the default CRYPTO_ALLOW_DOWNGRADE = negotiate only a recipient recorded as unable to read AuthEnvelopedData gets EnvelopedData; the downgrade is recorded on the message (downgraded, smime_capability) and logged. One population’s client does not set the container for everybody else’s: nothing Pepsi ships downgrades every recipient, and yes (CBC for every S/MIME recipient) is only an explicit operator choice. Because a client that cannot read the container shows a blank message and no error, the first message to a certificate with no record carries a plaintext notice beside the ciphertext, never inside it. The notice says nothing about the message and asks the recipient to report an unreadable message and to reply signed. It is sent once per certificate (smime_capability.notice_sent_at), and any record ends it (What a correspondent on an unmeasured client sees).

  • A learnt record binds to a certificate, not to an address. pepsi-stage-autocrypt-learn reads the RFC 8551 SMIMECapabilities attribute only from a signature that verifies under a certificate that the message carries, and stores the claim against that certificate’s fingerprint. Forging a From: therefore gains nothing: a stranger who signs a “CBC only” claim with a key of their own downgrades mail to that key alone, and cannot weaken mail to anybody else, which is encrypted to some other certificate. The claim is covered by the signature, so it cannot be altered in transit; an older claim never replaces a newer one, so replaying an old signed message cannot revert a correspondent who has changed client; and a message scored as spam teaches nothing.

  • A configured record is the operator’s. pepsi-keys peer capability writes it (audited as key.peer.capability) and it takes precedence over a learnt one; it is the remedy for a correspondent who has never sent a signed message. The table is not reachable from pepsi-httpd, pepsi-ingress or pepsi-telemetry; it is not a per-address setting, so it cannot be changed by e-mail through pepsi-stage-edit-settings.

  • The key is bound to the container where the correspondent can read it. The content-encryption algorithm identifier of a CMS message is not authenticated, and AES-256-GCM and AES-256-CBC take the same 32-octet key, so a captured AuthEnvelopedData can have its RecipientInfo re-submitted under a synthetic EnvelopedData that opens with the same content key. A correspondent whose learnt record says that its own signed SMIMECapabilities name RFC 9709 id-alg-cek-hkdf-sha256 is sent a content key derived with HKDF-SHA256 over the real algorithm identifier (cipher and nonce or IV), in either container, so the delivered key under any other algorithm is another key. Every certificate that a message is sealed to must have made the claim; a configured record never turns it on. Pepsi’s own signatures advertise it, and pepsi-stage-decrypt honours it on every message whose content-encryption algorithm names it. [stage-decrypt] OPEN_ENVELOPED_DATA = no closes the inbound side for mail sent without the derivation: no EnvelopedData is opened at all, so no AES-GCM content key is ever applied to a CBC ciphertext.

The residue is stated in Keys of correspondents: a correspondent whose own client announces no AES-GCM is sent CBC, a correspondent with no record whose client cannot read AEAD receives a message they cannot open until a record exists, and a correspondent whose client does not announce RFC 9709 is sent AES-GCM whose content key opens a relabelled CBC copy wherever that copy is opened.

17.15.22. Header forgery

Upholds

What a security indicator means, against A remote sender.

X-Pepsi-Crypto tells a user’s client what Pepsi concluded about a message’s cryptography, so a forged one is a lie told with our authority. Inbound mail has the header stripped before the decrypt stage can add its own, and outbound request headers are stripped by STRIP_REQUEST_HEADERS. A remote sender cannot make one appear.

The same reasoning covers Authentication-Results and Pepsi-Origin: a header that means “the local system verified this” is only meaningful if the local system is the only thing that can write it.

The [decrypted] and [verified: …] subject tags are the indicator that most users actually see, and a sender writes the subject. The same holds for [unverified signer], [bad signature] and [verified (except reply-to): …], which a signature inside a ciphertext earns so that a replayed ciphertext does not pass as its signer’s own message. pepsi-stage-decrypt therefore removes anything at the front of an inbound subject that would display as a security indicator before adding its own tags (pepsi_common::indicator), the address form whole however long the address. We judge the subject by what a client renders, because the forgeries in Forged security tags in the Subject bypass gateway sanitisation and Security status spoofed in-band in message body or headers differ from the real tag byte for byte while looking the same: RFC 2047 encoded-words are decoded, text is compared by a skeleton that folds full-width and accented characters and every look-alike in the UTS #39 confusables data (generated from Unicode’s confusables.txt into pepsi-common/src/confusables.rs) as well as small capitals and digits standing in for letters; zero-width characters and bidirectional overrides are removed; and any leading bracketed group naming a security property ([secure], (signature OK)) is removed along with our own tags. A subject that opens with a legitimate [Signed contract] loses that prefix; we accept that cost.

What stripping cannot do is make a tag distinguishable from a look-alike in the body, since both are rendered in the message area. The result field exists for a display outside it: the Outlook add-in’s read pane and the Thunderbird extension (Mail client extensions) read X-Pepsi-Crypto and X-Pepsi-Warning inside the client and render them in a task pane or a toolbar button, where nothing that the sender writes appears. They share one parser, held to the decrypt stage’s emitter, the signature vocabulary and ingress’s warning values by tests/check-extensions.sh in make check; valid-untrusted is rendered as unsigned mail with an explanation, never as verified, and an absent field is a neutral state, not a verdict either way. The extensions trust the field because ingress and the decrypt stage make it trustworthy, and for no other reason: they are for mailboxes that receive the managed domains only through Pepsi.

17.15.23. Protected content stands alone

Upholds

What a security indicator means and Gateway custody (custody = local, the MTA key), against A remote sender.

A sender controls the MIME structure around a ciphertext or a signature. Two classes of attack use that: EFAIL direct exfiltration places a captured ciphertext between two HTML parts, so that a client which decrypts it renders the plaintext inside an image URL pointing at the attacker (EFAIL direct exfiltration: plaintext spliced into attacker content, EFAIL direct exfiltration: plaintext spliced into attacker content); and signature wrapping places a validly signed part beside the attacker’s own text, so the signature’s verdict seems to cover both (Signature spoofing via partial signing and MIME/CMS wrapping, Signature spoofing via partial signing and MIME/CMS wrapping).

pepsi-stage-decrypt reduces every message for a local recipient to its protected content before it looks up a key or decrypts anything (pepsi_crypto::mime::isolate). In a message carrying an encrypted unit next to other content, the first encrypted unit becomes the message and every other part is moved into an inert attachment: application/octet-stream, Content-Disposition: attachment, no Content-ID or Content-Location, whatever the sender labelled it (ISOLATE_ENCRYPTED). No client renders such an attachment inline, so a decrypted plaintext has nothing to be spliced into, which is the separation RFC 9787 section 6.2.2 asks of a client that decrypts an encrypted part found inside other content. A message without ciphertext carrying signed content next to unsigned content keeps only the signed content (ISOLATE_SIGNED). Both rules are applied again to every recovered plaintext. Doing it before decryption is what protects mail that the gateway does not open: a message for a user’s own MUA key, or one that no key here fits, is delivered as the bare PGP/MIME or S/MIME container at the root of the message (an inline-PGP body keeps its moved parts as attachments), so a client that is itself vulnerable to EFAIL has nothing to splice the plaintext into. An attached message (message/rfc822, message/global) is a message the client opens and decrypts on its own, so one carrying ciphertext beside other content is reduced by the same rule inside the attachment, through three levels of attached messages; one nested deeper that still carries ciphertext becomes an inert .eml file whole (nested= in X-Pepsi-Crypto).

When the stage opens the kept ciphertext it also opens the moved ciphertexts with the same keys and delivers their plaintext as attachments, which is how files encrypted one by one beside an inline-PGP body arrive. A signed plaintext must not appear to vouch for what a stranger put beside it, so when the plaintext is signed, the moved cleartext parts are dropped, and a moved ciphertext is kept only when it was signed by the same key. Unsigned content is therefore dropped only where signed and unsigned content are mixed.

The rules cost content in two cases: a mailing-list footer outside a signature or around a container this host does not open, and cleartext beside a signed encrypted message. Each rule has its own switch for a site that needs that content more than the protection.

Malleability inside one AES-CBC ciphertext is a different attack: a CBC gadget rewrites the plaintext within the single encrypted unit that isolation keeps whole (EFAIL: CBC/CFB malleability gadgets exfiltrate decrypted mail), and the rewritten HTML exfiltrates when a client renders it. The stage therefore never hands a client markup that it cannot vouch for. A plaintext from an S/MIME EnvelopedData container (AES-CBC, 3DES) that no valid signature inside the container covers is delivered with every markup part relabelled text/plain and a multipart/alternative reduced to its plain alternative (pepsi_crypto::mime::plain_text_only), tagged [decrypted, unauthenticated] in place of [decrypted], and marked unauthenticated=yes; sanitised=text in X-Pepsi-Crypto, which names the container of every opened ciphertext. A signature over the plaintext rules the rewrite out whatever its key is worth; one around the ciphertext does not, since the attacker re-signs. [stage-decrypt] UNAUTHENTICATED_PLAINTEXT = require-signature passes such a message on unopened instead, for a client with its own EFAIL defences, and open restores rendering for a site that accepts the exposure. AEAD containers and every OpenPGP container Pepsi accepts are unaffected, since a rewritten one does not open. Which way an uncovered plaintext goes is visible to the recipient alone, so the decision is no oracle for the sender.

Authenticated HTML is delivered as it came out (DECRYPTED_MARKUP = keep): nobody can have rewritten it, but its remote references still reach the sender when a client loads them, and the client cannot tell that the message was encrypted. Blocking them is the client’s setting (Remote content); DECRYPTED_MARKUP = text reduces every decrypted plaintext as above, per site or per address, for users who cannot rely on theirs. For a user who turns it on, Remote references in HTML removes the remote references from decrypted HTML as from any other, except where a signature that the client checks again covers them (RFC 9787 leaves those to the client).

17.15.24. Remote references in HTML

Upholds

Per-address settings are a trust boundary, and the reader’s side of Remote content and personalised links reveal opens, device and location and EFAIL direct exfiltration: plaintext spliced into attacker content: for a user who asks, opening a message makes no request that the sender can observe.

pepsi-stage-defang (pepsi-stage-defang) sits after every stage that verifies or reads content and after ~/.forward, before re-encryption and local delivery, with DEFANG = off; a user turns it on for their own mail through pepsi.settings. It rewrites every HTML and CSS part outside a signature: every attribute and CSS construct that loads a resource without the reader acting goes, unless it names a cid: part or an inline data: image, sound or video; links and forms stay. Relative references go too, because Content-Base and Content-Location choose their base. The HTML is tokenized by the HTML standard’s rules, not by a pattern, and where the browser’s reading depends on the tree (raw text inside <svg>, <math>, <select>, <frameset>, a <noscript>, a CDATA section) the output is changed until both readings agree. Comment bodies are rewritten too, for Outlook’s conditional comments. Character references in style attributes are decoded before the CSS is read, as the browser decodes them, and an attribute whose references cannot be decoded with certainty is dropped if either reading holds a reference. Parts in a charset whose bytes are not ASCII where ASCII is are decoded first and relabelled UTF-8. A subtree nested past 32 levels is replaced by a note rather than delivered unchecked.

What it does not do: it does not touch a multipart/signed, an application/pkcs7-mime part or an inline OpenPGP block, whose references remain for the client’s own blocking; it does not remove links, so a click still tells the sender; it does not evaluate CSS with which a stylesheet hides text, nor anything that a client fetches for a reason other than rendering. A message it changed carries X-Pepsi-Warning: remote-content-defanged; ingress removes a copy of that field from mail arriving on an unauthenticated path, as it does every other X-Pepsi-Warning. The switch is a user setting by design: it only ever removes what is shown, so the settings boundary is not widened by listing the stage in EDITABLE_STAGES.

17.15.25. The length of an encrypted message

Upholds

A passive network observer and What Pepsi does not protect: whoever sees an encrypted message in transit learns its length only to within a bucket, not to the octet.

Neither OpenPGP nor S/MIME pads beyond the cipher block, so a ciphertext’s length is its plaintext’s length plus a constant, and a length alone often identifies which of a few known documents was sent. pepsi-stage-encrypt therefore pads every message it encrypts ([stage-encrypt] PADDING, default on) to the Padmé length of pepsi_crypto::padding::padme: rounded up so that only the top ⌊log2 ⌊log2 L⌋⌋ + 1 bits below the leading one may be set, which leaks O(log log M) bits about a length below M at no more than 12 % of overhead.

  • SEIPDv2 carries an RFC 9580 padding packet (type 21), which sequoia’s Padder writes between the encryption and the signature: inside the ciphertext, so nobody sees it, and outside the signature, so a verifier that does not expect it is not disturbed.

  • SEIPDv1 and S/MIME have no packet or attribute that every reader skips, so the encrypted MIME entity grows a Pepsi-Padding: header field of filler (padding::pad_entity), folded at 78 octets. It is inside the encryption too. For S/MIME the signature is made first, so the field is outside it; under SEIPDv1 the signature covers the literal data and so the field, which costs a verifier nothing. A reader ignores a field that it does not know, and Pepsi’s own decrypt path keeps only the Content-* fields of a recovered entity.

Neither content encryption compresses, so the filler is never squeezed back out. What padding does not hide: the size class itself, the envelope and the header block, the recipient’s key identifier (each copy names only its own recipient, since the stage encrypts one recipient per row), and how many messages pass. The copy that pepsi-stage-reencrypt seals for a user’s own mailbox is not padded: the server that stores it has just seen the plaintext.

17.15.26. Bounces and replies to encrypted mail

Upholds

Gateway custody (custody = local, the MTA key) (plaintext that the gateway opened reaches only the recipient), against A remote sender.

The decrypt stage runs first on the inbound path, so a message that bounces later holds plaintext, and a DSN goes to whoever the envelope sender is. Anybody who captured a ciphertext can re-send it under their own envelope sender with RET=FULL and make it bounce (Bounces after gateway decryption reveal decrypted content, CBC padding and format oracles against unauthenticated S/MIME). pepsi-stage-bounce therefore quotes a message that arrived encrypted by its From, Sender, To, Cc, Date and Message-ID fields only, whatever RET asks for, and does so whether or not decryption succeeded, so that the DSN does not reveal the outcome either; a DSN that did would be a decryption oracle for AES-CBC S/MIME (CBC padding and format oracles against unauthenticated S/MIME). The decision reads state.crypto.in, so it holds for a per-recipient bounce, success or delay report spawned as a separate row beside the original, too: such a row inherits the original’s state under its own report record. Every DSN drops Pepsi’s X-Pepsi-* annotations, and the bounce template never sees the crypto verdicts. The vacation notice, the pay-to-send payment request and the secretary’s challenge do not quote the subject of a message that arrived encrypted, for the same reason. A plaintext copy that an alias or a ~/.forward sends off-site leaves with a forward return address, which records that the message arrived encrypted: a remote host that bounces the copy later, with whatever content its policy returns, bounces to this host, and the sender gets this host’s own DSN, which quotes nothing of the message (Forwarding addresses in delivery reports).

Further signals would tell the sender whether a modified AES-CBC ciphertext still opened, and Pepsi closes each of them:

  • A bounce for a decryption failure. The default ON_DECRYPT_FAILURE = passthrough delivers what could not be opened. The only bouncing value, bounce-if-unproblematic, bounces only when the failed ciphertext is integrity-protected, as read from its DER, and drops anything else, and its DSN’s diagnostic names no failure class (missing key, failed decryption, malformed structure), which would add a format oracle; the class is logged for the operator. The setting bounce is an alias for the longer but unambiguous bounce-if-unproblematic: no setting bounces a failed ciphertext without integrity protection.

  • A bounce for what the plaintext turned out to be. ON_BAD_SIGNATURE = bounce and pepsi-stage-reencrypt’s ON_NO_CLIENT_KEY = bounce would bounce a message only because its ciphertext opened, into something that looks signed or not. For content from an EnvelopedData container (state.crypto.in.layers) both drop the message instead (telemetry decrypt-dropped), which its sender cannot tell from a failure to open.

  • A key lookup. The decrypt stage starts no key discovery for a signature inside content from a ciphertext without integrity protection: the lookup would go to a From: domain the attacker chooses, and whether it happens would reveal whether the padding was valid. Not looking the key up removes the signal (CBC padding and format oracles against unauthenticated S/MIME).

  • The end of a quarantine. ON_DECRYPT_FAILURE = quarantine holds a failed message while one that opened is delivered, and ON_BAD_SIGNATURE = quarantine holds one that opened into a bad signature; pepsi-queue gc ends a hold after [pepsi-queue] QUARANTINE_MAX_AGE_DAYS, and pepsi-stage-quarantine after its MAX_HOLD (Quarantined mail). It bounces an expired message only when state.crypto.in shows no EnvelopedData content and no failed ciphertext without integrity protection (crypto_state::unauthenticated_ciphertext); any other expired message is dropped and logged (telemetry decrypt-dropped), so the hold’s end is as silent as the delivery it stands in for.

  • A gate after decryption. Every stage after the decrypt stage may judge content that depends on the padding, so none of them bounces a message whose content came out of, or failed to open from, a ciphertext without integrity protection (crypto_state::unauthenticated_ciphertext). pepsi-stage-milter drops it where a filter’s REJECT (or ON_FAILURE = reject) or an expired TEMPFAIL would bounce it; a stage that keeps failing on it past its MAX_LIFETIME drops it rather than rerouting it to its BOUNCE_STAGE, and pepsi-failure-bouncer drops it rather than bouncing it (telemetry decrypt-dropped throughout). pepsi-stage-block-language under ENFORCEMENT = hard marks and delivers it as soft mode does: a language filter is a convenience, not a protection worth a lost message.

  • An answer chosen by the content. Pay-to-send and confirm-to-send read no plaintext, but whether they ask the sender to pay or to confirm follows the whitelist verdict, and a signature_required whitelist entry is satisfied by a signature that verified: pepsi-stage-check-whitelist does not count a signature from such a container. Nor is any DSN, vacation notice, payment request or challenge about such a message written in the language detected in it; it uses the configured default language.

What remains is a timing measurement, which the queued pipeline keeps from the sender.

A message with more than one From: field is refused at ingress (550 5.6.0): mail clients disagree about which field they show, while DMARC alignment, the submission identity check and the signer binding read the first. One From: naming mailboxes in several domains is legal, and DMARC is evaluated for each of those domains (RFC 7489 section 6.6.1, up to 10), so a second mailbox in a domain without a policy does not exempt a forged one from its domain’s p=reject; any failing domain is a failure that DMARC_ENFORCE acts on. Under DMARC_ENFORCE, unauthenticated mail to which DMARC cannot be applied at all is refused too: no From: address (550 5.6.0), or more domains than are evaluated (550 5.7.1). When it is delivered, a field naming several domains is marked X-Pepsi-Warning: from-ambiguous with the [external] tag whatever its verdicts (Mail from outside that claims to be ours is marked).

DMARC_ENFORCE is what the wizard writes for a new installation; the compiled-in default is off, so an existing configuration keeps its behaviour until the operator changes it. pepsi-setup warns about a configuration with accepted domains that does not set the option, and, when it reads the served domains’ DMARC records, about one that has it off while a record asks receivers to quarantine or reject; pepsi-setup check notes the option when it is off. Enforcement would refuse the mail of every mailing list and forwarder, which break DMARC for what they relay, so ingress accepts a failing message when two conditions hold. Its ARC chain (RFC 8617) must validate, with cv=pass recomputed from the signatures and never taken from the chain’s own cv= tag; and the d= of the ARC-Seal with the highest instance must be listed in [pepsi-ingress] ARC_TRUSTED_SEALERS (Authenticator::arc_vouches). Only the last sealer is consulted, because validation checks the newest ARC-Message-Signature and every seal, and a seal signs the ARC fields rather than the message: the last sealer is the only ADMD that a validated chain proves to have handled these bytes. The sealer is recorded as state.auth.arc_override and state.auth.dmarc keeps reading fail. The list is empty by default and nothing fills it: an unknown sealer proves nothing, and the trust is the operator’s to place, per forwarder. What helps place it is the log: the chain of every message refused under DMARC_ENFORCE is checked whatever the list holds (Authenticator::arc_assess), and the refusal names its last sealer, as arc-sealer=<domain> when the chain validates and as an unproven claim when it does not.

A DMARC policy that two receivers could read two ways is not applied. Several DMARC records at one name are all discarded, whatever order the resolver returns them in (RFC 9989 section 4.10; the tree walk then goes on to the organizational domain), and a record naming one tag twice (p=none; p=reject) is invalid as a whole (RFC 6376 section 3.2, whose tag-list syntax DMARC records use), which makes the verdict permerror. Both rules are patches to the vendored mail_auth library, whose upstream version uses the first record that parses and the last copy of a tag.

Two rules keep the plaintext with the recipient that it was encrypted for. A ciphertext addressed to several local recipients is split one per row before any key is loaded, and each copy is opened with its own recipient’s keys only; opening the row once with all their keys would deliver what was encrypted to one of them to every other recipient the sender chose to add. And pepsi-ingress removes every Bcc: and Resent-Bcc: field from every message (after authentication, so a DKIM signature over it is still judged on what was signed): the field has no meaning to a recipient, and a client that includes it in Reply-All would quote the decrypted text back to an address the user never saw (Reply-steering header parsing (Bcc on reply-all, header-name prefixes)). Removing it from submitted mail too means that a client which leaves the field in cannot show the hidden recipients to everyone else.

17.15.27. Quarantined mail

Upholds

Somebody holding a copy of the database (how long held plaintext stays) and Principals and how far each is trusted (only the operator releases quarantined mail).

pepsi-stage-quarantine holds a message paused with no timeout, so nothing but an operator’s act (pepsi-queue quarantine release or set-stage, the administrative requeue, or a deletion) brings it back. Three rules keep it that way:

  • The payment webhook cannot release it. workqueue_resume, which POST /resume calls when a GNU Taler order is paid, answers held and changes nothing for a message whose state.quarantine records an unended hold. The bearer token of that webhook belongs to the merchant backend and proves a payment, not a decision about quarantined mail; and a paid message that a later filter quarantines keeps the token that the merchant knows.

  • A bulk reset does not release it. pepsi-queue clear-all leaves the paused rows at a quarantine stage alone.

  • An old record does not release it. A message that arrives with the record of an earlier, ended hold is held again, so a message released once and quarantined again later is not waved through. A party that sends mail to the stage writes a fresh record (pepsi_common::quarantine::request).

A hold has an end, because held mail is plaintext at rest. Every stage that runs pepsi-stage-quarantine counts as a quarantine stage for pepsi-queue gc and is bounced without content after [pepsi-queue] QUARANTINE_MAX_AGE_DAYS, unless its own MAX_HOLD ends the hold first. At the end of a MAX_HOLD the message goes to EXPIRE_STAGE, with the same marking and the same exceptions as an expiry in gc: a member’s copy of a list post and a message from a ciphertext without integrity protection are deleted instead (Bounces and replies to encrypted mail). The stage tells an expiry from a release by the clock, and a claim within a few seconds of the end counts as the expiry, so a timer is never mistaken for an operator’s release. Its options are read from the base configuration, so per-address settings cannot shorten or lengthen a hold or change where a release goes.

17.15.28. Forwarding addresses in delivery reports

Upholds

Assets (a user’s ~/.forward and alias targets are the user’s data) and Gateway custody (custody = local, the MTA key) (plaintext that the gateway opened reaches only the recipient), against A remote sender.

When pepsi-stage-aliases or pepsi-stage-dot-forward replaces a recipient by the addresses it leads to, each new recipient’s state.dsn entry records the address that the sender used (expanded_from, set by pepsi_common::dsn::rebuild_rcpt; never inferred from an ORCPT, which the sender may set). A DSN that pepsi-stage-bounce writes about such a recipient names that address as Final-Recipient, and gives a generic Diagnostic-Code of the same class (550 5.1.1 delivery to a forwarded address failed) with the enhanced Status: kept, so the sender learns the outcome but neither the target nor the reply of the host behind it (RFC 3464 section 4.2). The operator template sees no more, and the journal keeps both for the operator.

The same holds for a report the target’s own server sends about the copy (DSNs, MDNs and Delivered-To disclose addresses, readers and topology). pepsi-stage-srs gives a copy whose recipient carries expanded_from a forward return address, fwd+<sealed>=<tag>@SRS_DOMAIN, in place of an SRS address. The address seals the original envelope sender, the address that the sender used, whether the message arrived encrypted, whether its sender was authenticated, the sender’s NOTIFY and the day, with keys derived from the SRS secret under labels of their own (HMAC-SHA256 in the SIV pattern, an 80-bit tag; pepsi_common::forward_return). Nothing is stored, and nothing in the address is readable. pepsi-ingress accepts mail to such an address only from the null sender, only while the tag verifies under the current or a PREVIOUS_SECRET_FILE secret and the record is younger than [pepsi-srs] MAX_AGE_DAYS, and only as the transaction’s sole recipient; anything else is the 550 5.1.1 of a forged SRS address and counts against MAX_SRS_FAILURES. It does not deliver the report. It logs the report’s Reporting-MTA, Final-Recipient, Action, Status and Diagnostic-Code for the operator and queues a row at the bounce stage, from which pepsi-stage-bounce writes this host’s own DSN to the original sender: the address that the sender used as Final-Recipient, the generic diagnostic with the report’s status class (Action: delayed for a delay report; a success report is dropped, a message that is no report at all counts as a failure), and the sender’s From, Sender, To, Cc, Date, Message-ID and Subject from the returned header block — never its trace fields, which name the target. For a copy of a message that arrived encrypted the DSN quotes nothing at all (Bounces and replies to encrypted mail); for one whose sender was not authenticated it is subject to BOUNCE_UNAUTHENTICATED (Unknown recipients and backscatter), as is every DSN this host writes. The DSN has the null sender and is never itself bounced. The address is long: the record is stateless, and two addresses do not fit the 64 octets of a local part. Its length is not capped: a next hop that refuses it fails the delivery, and this host’s own DSN follows. Falling back to SRS for a long one would let whoever chooses a long envelope sender reopen the path; a sender that cannot be sealed at all (over 254 octets) makes the copy leave with the null sender instead. Mail relayed for any other reason keeps SRS.

17.15.29. Unknown recipients and backscatter

Upholds

Assets (sending identity and reputation), against A remote sender.

A bounce goes to whatever envelope sender a message claims, and spam forges it. An MTA that accepts mail for addresses it does not have and bounces it later therefore mails strangers on a spammer’s behalf. That is backscatter, and blocklists act on it quickly. Pepsi closes this in three layers, each a net under the one before, and a fourth measure spreads out the mail that it does reflect:

  • Refuse at RCPT. pepsi-ingress answers 550 5.1.1 for an address at a served domain that nothing on the host vouches for: a local account, an alias, a list, a service address, or the MDA or backend asked with RCPT TO. The sources are derived from the stage graph (pepsi-recipients). Every uncertainty accepts, so an outage never turns into refused mail.

  • Report only to a sender that proved itself. pepsi-stage-bounce sends a DSN for an inbound message only when SPF passed for the envelope sender’s domain or an aligned DKIM signature did (BOUNCE_UNAUTHENTICATED = drop, the default), or when a temporary DNS error about that domain stopped such a check and neither SPF nor DMARC failed outright. Errors about any other domain do not count, because a forger chooses the domain of a signature and can keep its DNS from answering. Anything else is dropped with a warning in the log. This covers the reports a delivery stage spawns per recipient as separate rows as well, which carry the original message’s authentication results.

  • Refuse a loop. A message that has already been through this host’s ingress MAX_SELF_HOPS times is refused as a routing loop. An address on our own domain relayed to our own MX therefore costs one bounce, not a trip round the pipeline for every hop the relay stages allow.

  • Reflect at a random moment. Reflected mail is what Pepsi legitimately sends because a stranger sent something: a DSN, the copy that an alias or a ~/.forward resends, every row of a list’s fan-out. A sender who controls when its own transaction completes could time such reflections from many hosts to converge on one victim’s MX in a pulse. Each reflected message is therefore held, before the next stage sees it, for a time drawn afresh and uniformly between zero and [pepsi] REFLECTION_HOLD_MAX (pepsi_common::reflection, 30 s by default): pepsi-stage-bounce and pepsi-stage-aliases hand the row on paused with that timeout (StageContext::hold_reflected), pepsi-stage-dot-forward and pepsi-stage-list-post create each forwarded sibling row the same way, and the dispatcher’s paused-retry sweep releases them. A held advance is never fused. The window flattens a pulse into a plateau as wide as the window; pepsi-ingress’s SESSION_TIMEOUT (Resource limits) bounds, on the other side, how long a transaction can be parked waiting for the chosen moment.

The mirror image is a bounce Pepsi consumes. pepsi-stage-list-bounce disables a member’s delivery on the strength of failure reports, which anyone can send, so every VERP envelope sender that the list fan-out writes carries an authentication code: <list>-bounces+<local>=<domain>=<code>@<host>. The code is eight base32 characters of an HMAC-SHA256 keyed with [pepsi-list] VERP_SECRET over the bounces mailbox, the host and the member (pepsi_list::verp, the shape of pepsi_common::srs). A bounce to a member-shaped address whose code does not verify is dropped unscored, unforwarded and unanswered. Both list stages refuse to start without the secret. BOUNCE_PROBES defaults on, so even a scored member is disabled only by the bounce of a probe whose token nobody can forge.

Answering RCPT truthfully tells a sender which addresses exist, as every MTA that rejects unknown users does. MAX_INVALID_RECIPIENTS closes a session after ten wrong guesses, so harvesting costs connections, which the connection limits meter. Probes of the MDA or backend are cached and capped at 16 in flight (beyond that the answer is “unsure”, which accepts). A flood of guesses therefore cannot be turned against the mail store either. VRFY still answers 252 for everything.

The recipient check is why pepsi-ingress holds one grant beyond the queue: the name and host columns of mailing_list, which together are a list’s public address and nothing more.

A local part with % (the percent hack) or ! (a UUCP bang path) at a served domain is refused 550 5.1.3 unless a mailbox authority vouches for the address: a back end behind an unverified domain may still rewrite such a local part into a route to a third party, to which a web application that trusts “verified” addresses at our domain would then deliver its secrets. There is no option for it.

IPREV_ACTION = reject refuses the recipients of an unauthenticated MX session whose client’s reverse DNS definitely fails (550 5.7.25, RFC 7372), <postmaster> excepted. Refusing at RCPT rather than routing on origin.iprev after DATA is what keeps such a policy from becoming a silent drop or backscatter; it is off by default, since broken reverse DNS says nothing about the message, and a temperror never refuses.

17.15.30. Milters consulted during the SMTP session

Upholds

Principals and how far each is trusted (external helpers), A remote sender and Availability.

A milter that pepsi-ingress consults while the client is connected ([pepsi-ingress-milter-*]) refuses mail as the SMTP reply, which is what keeps a filter’s rejection from becoming backscatter. The filter is trusted with what the operator gives it, and the client side of the protocol keeps it within that:

  • What it may change is negotiated. Ingress offers only the actions in ALLOW_ACTIONS (header and body edits by default), refuses a milter that asks for more at the negotiation, and checks every modification at the end of the message against what was negotiated, so a misbehaving filter cannot smuggle an envelope edit past the mask.

  • It cannot open the relay. A recipient a milter adds is held to the rule every RCPT is: an address at a served domain that something on the host would accept, or any address on an authenticated session. Anything else is dropped and logged.

  • It cannot forge the reply. A milter’s SMFIR_REPLYCODE reaches the client only if it is a 4xx or 5xx reply of the verdict’s class with printable lines, all with the same code; a 2xx, a bare CR or LF that would start a second reply line, or a code of the other class is replaced by a generic 451/550.

  • It sees only what Pepsi would accept. Pepsi’s own refusals run first, so a filter is never asked about a recipient or a message that is refused anyway; what it sees at the end is the message as it would be stored, with Pepsi’s Authentication-Results.

  • It cannot hold the session for ever. Every reply is awaited for a bounded time, and a filter that is unreachable, slow or broken takes its ON_FAILURE path: by default it is consulted no more in that session and the mail is accepted, so a crashed filter does not stop inbound mail.

  • An inbound ARC chain stays verifiable. When a filter changes a message that carries a chain, the message as received is kept beside the edited one, and pepsi-stage-arc verifies the chain over the original while sealing what is stored, so the seal does not report cv=fail for a chain that was valid on arrival.

17.15.31. What the directory serves for our users

Upholds

Client custody (custody = client, the MUA key) and Gateway custody (custody = local, the MTA key): a key published for one of our users is the one in the key store, or the difference is reported.

A correspondent encrypts to whatever the Web Key Directory and the DNS give them. The answer can differ from crypto_identity without Pepsi changing anything: the WKD direct method is answered by whatever runs the domain’s apex web site, an OPENPGPKEY or SMIMEA record stays in the zone after the identity behind it is rotated, and anybody who can write to that web server, to the zone, or to the key store can hand out a key of their own and receive the user’s future mail. pepsi_keydisc::served_check asks every channel the way a correspondent would: both WKD methods through the hardened fetcher (HTTPS only, certificate validation, no redirect off the host, SSRF refusal, byte cap, deadline), and both DANE records through the same resolver path as discovery. It keeps only the certificates that name the address, and compares their fingerprints with the published, active rows: WKD with exactly the set that the endpoint is meant to serve (keystore::wkd_served, the selection the endpoint itself uses), DNS record by record, an unvalidated answer included and marked. A served fingerprint outside that set is a mismatch; pepsi-setup check fails on it, pepsi-status prints it as a warning, and pepsi-keys identity list --served lists it under the table (Checking what is actually served).

The operator’s check compares the served keys with the store, so a key substituted in the store agrees with itself. The console therefore also shows a user logged in for their own address what every channel serves, so that they can compare it with the key in their own client: the one party who knows which key is theirs. Both views ask from this host, at the moment they run, and nothing is stored. An answer given only to a chosen correspondent is not detected; such an answer can come from an on-path attacker near them, or from a server or resolver that answers by client address. Nor is there a signed, append-only record of what was published that a correspondent could audit (Undetectable key substitution or equivocation by key directories and CAs).

17.15.32. Signed notices

Upholds

Forged notices (a recipient can tell a genuine notice from a forged one, and the signature never vouches for words the deployment did not choose).

A message that Pepsi composes itself is recognised by what composed it, not by where it travels. The component that builds it writes state.notice = {"kind": …} into the row that it injects (pepsi_common::notice::ORIGINATED_KEY). This covers httpd’s enrolment link, the secure-link stage’s and portal’s notifications, the secretary, the anti-spam payment request, auto-pay’s wallet replies, edit-settings, the encrypt stage’s key replies and notices, autocrypt-learn’s key-change notices and the vacation stage. state never comes from the wire, so no correspondent can set it. A notice to a third party is left unmarked while a per-address layer applies to the message that caused it (StageContext::overridden), because an account owner’s override can change its wording; portal replies, list mail, digests, list notices (their templates are a list owner’s to write), bounces and TLS reports are never marked.

An instance of pepsi-stage-encrypt with NOTICE_SIGNER set ([stage-notice] in the wizard’s configuration, between the emitters’ RESPONSE_STAGE and dkim-sign) signs exactly the marked rows, with the identity of that address opened through the same custody boundary as every author signature (The private-key custody boundary), by the same signing path, protected headers included, and encrypts none of them. Because a verifier holds a signature to the From: address and one identity cannot name every address that a notice comes from, the stage first sends the notice from the signer: From: becomes <NOTICE_SIGNER> and the previous value moves to Reply-To: unless one is set (own_notice::sent_by), so the protected From: and the signature agree. Every other row takes the stage’s ordinary path, which for mail without local_origin changes nothing, so a notice stage wired into the wrong path signs nothing it should not. NOTICE_SIGNER is read from the configuration file only, never through the settings layer: the recipient of a key-change notice is a local user, whose overrides would otherwise name the key. The stage refuses to start with a signer and no key store, and a missing identity or a failed signature is retried, never sent unsigned, so a recipient told that notices are signed is not taught to accept one that is not.

The key is published like any identity’s (What the directory serves for our users): pepsi-keys identity generate publishes by default, the Web Key Directory serves it for an address at a served domain (pepsi-setup warns about any other), and pepsi-keys identity list --served and pepsi-setup check compare what is served with the store.

17.15.33. A correspondent’s key changing

Upholds

Keys of correspondents, against A remote sender: a harvested key may be replaced by a newer one, but never silently.

Inside the Autocrypt tier (the inbound-signed, inbound and gossip rungs) the conflict rule is Autocrypt Level 1’s newest-wins, keyed on the From: header a sender writes and on a message that inbound authentication accepted fail-open. So a message that only claims to come from a correspondent can replace the key we encrypt to them with (TOFU and key continuity miss first-contact and new-identity attacks, Undetectable key substitution or equivocation by key directories and CAs) — unless their domain has signed for the stored key. The mechanisms that limit this:

  • A signed claim is never replaced by an unsigned one. A key learnt from a message whose aligned DKIM signature passed at ingress and covered it (the Autocrypt: header in its h=, the body for an attachment) is stored on the inbound-signed rung, above plain inbound, and the rank rule then refuses a key from any unsigned message however new it claims to be. Forging such a correspondent’s From: does not redirect their mail; the forger needs the domain’s DKIM key. The stage decides this from the verdicts that ingress recorded (state.auth.dkim, the Authentication-Results fragment) and matches the passing signature back to its field by domain, selector and the start of b=, so a second field that a path attacker adds cannot borrow the genuine pass. A signed key replacing an unsigned one is itself audited and announced as a rotation. An S/MIME certificate is lifted to the same rung when DMARC passed for the message (state.auth.dmarc), by aligned DKIM or aligned SPF, because the certificate is learnt only when it verified a signature over that message (smime::signing_certificates); a certificate merely attached to a SignedData is never learnt at all.

  • The conflict rule is per protocol, so the choice is by rank first. crypto_peer_key_upsert compares keys of one protocol, so a planted OpenPGP key is never weighed against a stored S/MIME certificate. The encrypt stage therefore picks the best-ranked key across both protocols (keydisc::decide_preferring), and PREFER breaks only a tie between equal rungs: an Autocrypt: header on unsigned mail cannot take over a correspondent whose certificate came from a directory, DANE, the operator or an authenticated message. Between two keys on the same rung PREFER decides, with no rotation event, which is trust on first use and no worse than the newest-wins rule within one protocol.

  • A harvested key is a reason to look. Encrypting to a key that nobody published also raises a discovery request in the background, at most once per NEGATIVE_TTL, so that a key that the owner published through WKD, DANE or a key server replaces it for the next message. Such a key outranks every harvested one.

  • The replacement is recorded by the statement that makes it. crypto_peer_key_upsert writes a key.peer.rotate row to pepsi.event_log (the append-only audit log that no mail-handling role can UPDATE or DELETE) in the same transaction as the swap, naming the address, both fingerprint sets and both effective dates. No caller can rotate a key without the row, and a compromised stage that wanted to hide one would have to be the kind of adversary A compromised component already concedes the queue to.

  • The people about to reply are told. pepsi-stage-autocrypt-learn mails each local envelope recipient of the rotating message (RESPONSE_STAGE, the key-rotation template) with both fingerprints, so a forged rotation is something the targeted user can notice before sending anything confidential. Each fingerprint is printed in hex and in the PGP word list, the form made for comparison aloud, and the new key’s rung is named (inbound-signed, inbound, gossip), so the reader knows what vouches for the key that their reply will be encrypted to. Only recipients at served domains are mailed, so the notice cannot be turned into backscatter, and at most one per recipient per message.

  • A user who compared can make the result stick. The notice gives the subject of the pin key command; under an enrolled second factor and with the whole fingerprint it pins the key on the manual rung, where no later rotation displaces it (A user’s own pin, and What a security indicator means for what that does to [verified]).

  • An operator can refuse rotation over a live key. ACCEPT_ROTATION = expired accepts the newer key only when every stored one is recorded as revoked or expired, or is past the expiry its own material states (stored when the key was learnt, and for OpenPGP only ever moved later, so a replayed older copy of the certificate cannot backdate it); otherwise the offer is held, audited as key.peer.rotate.held and reported to the recipients. It trades a forged rotation for a genuine one refused until an operator intervenes.

  • The tier stays confined. None of this widens what may be replaced: a message can touch nothing that a domain, a directory, a key server or an operator published, and no pinned row, and an address that we hold an identity for is pre-empted by our own key regardless (Weak binding between signer certificate or key and the From address). A served address that we hold no identity for is not pre-empted, and pepsi-keys peer unclaimed lists every such address with a harvested or gossiped key (Finding the users who bring their own key).

  • Promotion is not rotation. When a gossiped key’s owner advertises the same key themselves, crypto_peer_key_upsert moves the row from the gossip to the inbound rung and writes a key.peer.promote row (never key.peer.rotate, and no notice, since the key did not change). It is decided under the same per-address lock, keyed on the source names, and maps to the same TrustSource::Autocrypt / Untrusted verdict as any harvested key (A gossiped key its owner confirms is promoted).

pepsi-status lists the last 30 days of both kinds of row.

17.15.34. A key lookup that fails in the DNS

Upholds

Keys of correspondents, against An active network attacker: an attacker who keeps a recipient’s key records from resolving gets a held message, not cleartext.

Under opportunistic encryption a recipient without a key is sent cleartext, so a lookup that fails must not read as one that found nothing. pepsi-keydisc classifies a failed OPENPGPKEY/SMIMEA query, and a WKD host name that does not resolve, by also asking the domain’s MX and A/AAAA records: nothing answering is unreachable; the domain answering while the key records fail is counted, and three such rounds in a row, each within an hour of the last, make it inconsistent (one lost packet is a retry, not a verdict). The verdict lives on the settled key_request row; the stages still do no network I/O.

pepsi-stage-encrypt, where the no-key route would have been cleartext, defers an unreachable (or not yet persistent) recipient and bounces it at its MAX_LIFETIME (never longer than the relays’ 120 h; a DELAY DSN on the way when asked for), and routes an inconsistent one to the secure-link portal, or bounces it, telling the sender why. A local sender may accept cleartext with the [clear-ok] subject keyword or the CLEAR_ON_DNS_FAILURE setting; ENCRYPT = required is unaffected.

What this does not close: a WKD fetch that fails over HTTPS (TLS, 5xx) stays “no key”, because such failures are common and harmless and holding mail for every broken web server would be a worse trade; and without DNSSEC on the recipient’s zone a forged NXDOMAIN or empty answer cannot be told from a real one and still reads as “no key” (Unauthenticated or failed denial of existence suppresses DNS records).

17.15.35. Telling the author what left in cleartext

Upholds

Keys of correspondents: under opportunistic encryption, cleartext to a keyless recipient is a stated outcome, and the author can be told of it.

The copy in the author’s Sent folder is made by their client before the gateway acts, so it cannot show whether a recipient got ciphertext. Under [stage-encrypt] NOTIFY_CLEARTEXT = author (off by default; per address through pepsi.settings) pepsi-stage-encrypt sends the author of a local message, at RESPONSE_STAGE, one notice per copy that left unencrypted although encryption was wanted, naming the recipients and the reason; the keyless recipients of a message share one copy and so one notice. Independently of the option, a subject that begins with a near miss of a request keyword earns a warning naming the keyword, because such a subject asked for protection and got none. A near miss is found by the skeleton comparison that the decrypt stage uses for forged tags: a look-alike letter, one edit or one swapped pair away, or [encrypted]-style wording. Neither notice is sent for a null sender or a list post, and neither changes what leaves the server; only ENCRYPT = required does. A keyword translated into another language is still ordinary mail.

17.15.36. Key-discovery SSRF

Upholds

A remote sender and Keys of correspondents: an address somebody writes to cannot aim the server at its own network.

Key discovery fetches URLs derived from an e-mail address — WKD, and HTTP key servers — which is a server-side request forgery primitive by construction. pepsi-keydisc resolves the hostname itself and refuses every candidate address in loopback, RFC 1918, RFC 6598 CGNAT, link-local or unique-local space, and re-applies the check on each redirect (the redirect is the hole an address-check-then-connect design leaves open). The check is disabled only by an explicit test seam, because a stub HTTPS server necessarily listens on loopback. The same address check (pepsi_common::net::is_public) guards the two other fetches that a remote party can aim: the MTA-STS policy fetch of pepsi-stage-relay-to-internet, whose host is named by the recipient domain, and the TLSRPT report POST.

17.15.37. Key-discovery certificate authorities

Upholds

Keys of correspondents: a WKD or key-server answer is believed only over TLS that chains to a CA the operator trusts for key discovery.

The WKD and VKS fetches verify the server certificate, with RFC 6125 name checking, and have no mode that does not. By default the anchors are the system root store, so any CA in it can issue the certificate that makes a WKD answer believable, and a WKD key ranks above everything but DANE. [pepsi-keydiscovery] TLS_CA_BUNDLE replaces that store, for these fetches only, with the CA certificates of one PEM file (pepsi_common::smtp::tls::ca_bundle_connector, built by Fetcher::for_keydiscovery in pepsi-keydisc/src/http.rs, which the discovery services, pepsi-keys and pepsi-stage-vks-confirm all use). A file that cannot be read or holds no certificate is an error at start, never a silent fall-back to the system roots. The default stays the system store, because a narrower one refuses every correspondent whose WKD host uses another CA.

17.15.38. Smarthost certificate authorities

Upholds

An active network attacker: a smarthost hop, which carries the relay credentials and every outgoing message, is authenticated by the CA the operator names for it, not by any CA the host trusts.

A [pepsi-stage-relay-to-smarthost-mta-<name>] entry validates the smarthost’s certificate against the system root store by default, with TLS_CA adding CA certificates to it. TLS_CA_BUNDLE makes the CA certificates of one PEM file the whole trust store for that entry (TlsVerify::Bundle in pepsi_common::smtp::tls): a certificate for the smarthost’s name from any other root is refused, in the PKIX check and in the DANE = warn fallback alike. The worker loads every entry’s bundle when it starts and refuses to run when one cannot be read or holds no certificate, since an empty store would defer all mail to that smarthost and a fall-back to the system roots would be the breadth the option removes. The internet relay keeps the system roots, because an arbitrary MX can use any public CA; DANE = strict narrows it where TLSA records exist.

Certificate Transparency is checked softly, for these fetches and for every other TLS client connection verified against the public roots (MTA-STS and smarthost delivery, the DANE stage’s PKIX fallback): the Signed Certificate Timestamps embedded in the server certificate must include at least two (three for a certificate valid for more than 180 days) from logs of two different operators, verified against the log list that pepsi-keys ct-logs update keeps at [pepsi] CT_LOG_LIST (pepsi_common::smtp::ct). A certificate that fails is logged as a warning and the connection goes ahead (CT_CHECK = warn). Refusing it would make mail depend on the CT ecosystem and on a log list that only Google and Apple publish, which the design principles rule out; the warning still makes a certificate that a CA issued without logging visible to the operator, which is what CT is for. Without a list, or with one older than 70 days, nothing is checked. Connections verified against an operator’s own TLS_CA or a smarthost’s TLS_CA_BUNDLE are not checked, since a private CA does not log.

17.15.39. Database server certificates

Upholds

An active network attacker: a remote database, which holds the queued mail and every key Pepsi keeps, is reached only over TLS that chains to a CA the host trusts.

A remote [pepsi-postgres] CONFIG with sslmode=verify-full (or verify-ca, which skips the name check) verifies the database server’s certificate against the system root store, the same store every other TLS client of Pepsi uses by default (rustls-native-certs, so SSL_CERT_FILE and SSL_CERT_DIR replace it), and never against a bundle compiled into the binary. A server certificate from a local CA therefore verifies once that CA is in the system store. sslrootcert adds the CA certificates of its file to the system store for that connection, unlike libpq, where it replaces it: it cannot narrow the trust to a private CA, so a public CA that issues a certificate for the database’s host name is accepted too. The local socket, the canonical setup, has no certificate to verify. The regression test is db::tests::postgres_tls_trusts_the_system_root_store in pepsi-common/src/db.rs.

17.15.40. What the key refresh asks, and whom

Upholds

Assets (privacy toward third parties) and Keys of correspondents: the daily refresh does not hand one key server the deployment’s correspondent list.

pepsi-keys peer refresh, run daily by pepsi-keys-refresh.service, re-checks a cached key that is due only through the method it was learnt from, and only while that method is still in [pepsi-keydiscovery] SOURCES (pepsi_keydisc::refresh_due): a key-server key at the key server, a WKD key at the same WKD method, a DANE key in DNS, an LDAP key in the directory. A harvested, gossiped, hand-entered or API-submitted key came from no network method and is never refreshed over the network (its owner’s next message refreshes a harvested one); a pinned key and a domain wildcard are never re-fetched. The sweep never looks up an address that has no key: Pepsi asks about an address when it has mail for it. What a lookup itself reveals is stated in What Pepsi does not protect.

17.15.41. DMARC aggregate reports

Upholds

Availability (a report is a compressed file from the Internet) and A remote sender (what the operator is told about p=reject cannot be forged by whoever writes to the rua= address).

pepsi-stage-dmarc-report reads the reports that other receivers mail to dmarc-reports@<served domain>. Inflating one goes through a reader that stops at MAX_REPORT_SIZE (16 MiB) whether the attachment is gzip or zip, a zip entry declaring a larger size is refused before it is read, and only the deflate method is understood; the XML reader expands the predefined entities and character references and never one the document declares; at most 20 000 records of a report are stored, and pepsi-queue gc deletes reports RETAIN_DAYS (90) after the period they cover.

A report proves nothing about its author, so the stage records what ingress vouched for: the From: domain when DMARC passed, else the envelope domain when SPF passed; dkim=pass alone does not count, since it says that some signature verified, not whose. Only such authenticated reports enter the verdict (pepsi_common::dmarc_report::verdict) that pepsi-setup check, pepsi-status and the console draw: a forged report can neither make p=reject look safe nor name a source that it would refuse. An unauthenticated report is stored apart and shown marked. The uniqueness of a report includes its authentication, so a forged copy that arrives first does not shadow the real one. Reports about domains the host does not serve are dropped, mail to the address that is not a readable report is dropped rather than delivered (no bounce to a forged sender), and only the pepsi role writes the tables: pepsi-httpd reads them, pepsi-ingress and pepsi-telemetry cannot reach them.

17.15.42. IP blocklists are downloaded, not queried

Upholds

Assets (privacy toward third parties): checking a client against a blocklist does not tell the list’s operator who mails this host.

Most MTAs ask a DNS blocklist about every connecting client. Pepsi downloads whole lists instead (pepsi-reputation iplists update, hourly, each list at most once per MIN_INTERVAL, conditionally where HTTPS allows) into pepsi.ip_blocklist, and pepsi-ingress looks the client of an unauthenticated session up there. The list operators see one download an hour from this host, not a query per correspondent, and a session never waits on them.

What a list is trusted with is narrow. A listing marks the message (state.origin.ip_blocklist) for the pipeline to act on; only a list the operator sets to ACTION = reject refuses mail, and then never to <postmaster>. A forged or broken list could at worst mark or refuse mail from the addresses that it names, so entries wider than a /8 (IPv4) or /16 (IPv6) are dropped and a file that is mostly not entries is refused. A list that stops updating stops being consulted after MAX_AGE and is treated as unknown, which admits mail and records nothing. Only the pepsi role writes the tables; pepsi-ingress reads them, pepsi-httpd and pepsi-telemetry cannot reach them. rsync lists run the optional rsync program with an empty environment and the URL after --.

The cost is coverage: Spamhaus ZEN, SpamCop and Barracuda are free only as DNS queries, so the shipped lists are Spamhaus DROP and blocklist.de (HTTPS) and, switched off, UCEPROTECT level 1 (rsync).

DNS blocklists are asked about one thing only: this host’s own sending and MX addresses and domains (pepsi-reputation check, daily), which tells their operators nothing that they do not learn from every receiver that this host mails.

17.15.43. Greylisting

Upholds

Trust boundaries (B8, the greylisting socket), A compromised component (what a compromised pepsi-greylist reaches) and Availability (the greylisting milter fails open).

pepsi-greylist is a milter that answers the first attempt of an unknown client, sender and recipient with 451 4.7.1 and lets a retry through. It runs as its own account, pepsi-greylist, under a hardened unit, and listens on /run/pepsi-greylist/milter.sock, a socket of mode 0660 in a directory of its own (RuntimeDirectory=, not /run/pepsi). The socket’s group is pepsi-greylist: membership lets an MTA ask, and grants nothing else, so the daemon needs no membership in an MTA’s group and an MTA none in the daemon’s files. pepsi-ingress is a member; a local Postfix is made one by the operator.

Its database role is built from nothing up (provision_greylist_role): SELECT, INSERT, UPDATE and DELETE on greylist_triplet, greylist_client and greylist_stats; SELECT and DELETE (for the prune) on greylist_rule; SELECT on whitelist; INSERT on event_log. Rules are added and removed through greylist_rule_add and greylist_rule_remove, SECURITY DEFINER functions that normalise the value and refuse a malformed one; pepsi-httpd may read the four tables and call those two functions, and nothing more. pepsi-ingress and pepsi-telemetry cannot reach them.

The console’s page of a user’s deferred mail (Greylisting) offers Allow this sender, which puts the sender on the user’s own whitelist rather than adding a rule, so it lets the sender through for that user alone. The console’s role has no grant on whitelist. It calls whitelist_add_user_sender, a third SECURITY DEFINER function that only pepsi-httpd may execute: it refuses a whitelist name without a / (a shared list), builds the anchored, escaped pattern from one address itself, and writes the row that pepsi-whitelist add writes, with DKIM required, so a forged envelope or From: address gains nothing from it. pepsi-setup revokes it from pepsi-ingress and pepsi-telemetry and checks that they cannot call it. Which whitelist is the user’s is decided by the console from the configuration, as the daemon’s whitelist bypass decides it: the first name in the user’s own namespace among those that the bypass consults for the address; an own: principal may only name its own address. pepsi-setup checks after every install that pepsi-greylist cannot read the queue, the settings, the key cache, the configuration overlay or the logs.

What the daemon learns is the envelope: the client address and HELO name, the sender and the recipients. It keeps the triplets for RETRY_WINDOW (48 hours) when nobody retries and for PASSED_TTL (35 days) after a passed triplet was last seen, so its tables say who wrote to whom in that time, as the mail log at MAIL_LOG = full does. The client identity it keys a triplet on is a domain only where the domain itself vouches for the client (its SPF record authorises the client, or its MX hosts include it); a reverse DNS name alone is never trusted, because whoever holds the address chooses it.

The answer is advice to the MTA. A database error or a DNS step longer than DNS_TIMEOUT lets the recipient through and is counted; so does an MTA whose milter connection fails, under ingress’s default ON_FAILURE = accept. Greylisting therefore never makes mail undeliverable, and an attacker who can make it fail only switches it off. A deny rule (550) is the one refusal it makes, and it never applies to the exempt recipients (postmaster and abuse by default).

17.15.44. The path to the resolver

Upholds

The network adversary: the DNSSEC AD bit Pepsi trusts is the validating resolver’s, not something written on the way; and a forged datagram cannot suppress the resolver’s answer.

Pepsi never validates DNSSEC itself; the AD-bit-aware lookups (pepsi_common::dns: TLSA, the MX security check, OPENPGPKEY, SMIMEA, the setup and status probes) send their own queries with AD requested, EDNS DO set and CD clear, and believe the AD bit of the answer. That bit is only as honest as the path that it travels. A resolver list (DNS_SERVERS of a section, else [pepsi] DNS_SERVERS, else /etc/resolv.conf) names how each resolver is reached: a bare address means plain DNS, tls://ADDRESS#NAME means DNS over TLS (RFC 7858) and https://ADDRESS/PATH#NAME means DNS over HTTPS (RFC 8484). The encrypted forms verify the resolver’s certificate against the system roots for NAME (stapled OCSP and the soft Certificate Transparency check as for every TLS client), so nobody between the resolver and Pepsi can set the bit; the same list drives the hickory resolver behind the SPF, DKIM, DMARC, ARC, MX and address lookups, with the same roots. A list never mixes plain and encrypted entries, since a lookup moves on to the next resolver when one fails, and there is no fallback to plain DNS: an unreachable encrypted resolver is a failed lookup, which DANE strict defers on and key discovery records as a DNS failure. The warnings of the relay workers, pepsi-keydisc@dane, pepsi-setup and pepsi-status name a resolver off this host only when it is reached over plain DNS; the probe of whether it validates runs for every resolver, because encryption does not make a resolver validate.

Every reply must decode, be a response, and echo the query’s random transaction id and question section, whatever the transport. Over UDP a datagram that fails this is dropped and the wait goes on until the query’s deadline (DNS_TIMEOUT), so a forged or garbled datagram racing the real answer cannot end the exchange early (the pattern of the TuDoor attacks); one warning per query reports how many were dropped. Only a matching reply with TC set sends the query to TCP. Over TCP, TLS and HTTPS, which an off-path attacker cannot write into, a reply that fails the check is that resolver’s error. The hickory stub resolver behind the other lookups applies the same rule over UDP: Pepsi builds it with a vendored hickory-net that skips a datagram whose source, id or question does not match, or that does not decode, and keeps waiting until the request’s timeout (see the literature chapter, Resolvers abort or crash on malformed responses and bad CD-bit caching).

17.15.45. Outbound TLS and DANE

Upholds

An active network attacker and The network adversary: a peer that publishes DNSSEC-signed TLSA records cannot be intercepted with another certificate.

Both relay stages read DANE per section (pepsi_common::smtp::dane) and default to strict, as RFC 7672 section 2.2 requires: usable TLSA records (DANE-TA/DANE-EE) behind an AD bit make STARTTLS mandatory, and a certificate matching none of them, or a TLSA lookup that fails, defers the message (reported as tlsa-invalid when [pepsi-tlsrpt] SEND_REPORTS is on). DANE = warn is an explicit opt-out for peers with stale records: the mismatch is logged and the hop falls back to the check that it has without DANE. For a smarthost that check is TLS_VERIFY (PKIX, on by default), so a mismatch never leaves a smarthost hop, its relay credentials included, without any certificate check. MTA-STS enforce policies are honoured by default and kept in pepsi.mta_sts_policy for their max_age; each is fetched again once half of that has gone, on use and by the hourly pepsi-queue gc (RFC 8461 section 10.2), so a domain that keeps publishing a policy is never back at the trust-on-first-use fetch, however rarely it is mailed.

Our own TLSA records must keep matching for strict peers to deliver to us. pepsi-setup obtains certificates with certbot --reuse-key and sets reuse_key = True in the renewal configuration of every certbot certificate that the configuration uses, so a renewal does not change the key that a 3 1 1 record names; pepsi-setup run and check compare the published records with the certificate that each listener serves and warn when none matches.

Only the mail key is pinned, and only the mail listeners hold it. pepsi-setup obtains two certbot lineages, each with its own key: the mail lineage <HOSTNAME> for the ingress listeners (the HOSTNAME and the MTA-STS mx names) and the web lineage <HOSTNAME>-web for the HTTPS listeners of pepsi-httpd (the HOSTNAME, openpgpkey. and autoconfig. names; each mta-sts. host has its own). No TLSA record is printed for the web key. A key taken from the web server, the more exposed of the two, therefore authenticates no SMTP session to a sender that enforces DANE. The web certificate still names HOSTNAME, so a sender or mail client that authenticates the MX by PKIX alone would accept it; an installation in which the web server shares the mail lineage is moved to its own at the next pepsi-setup run. A certificate that the operator supplies (TLS_CERT outside the certbot layout, a wildcard among them) is left as configured, and with it whatever names and key it shares.

17.15.46. The keys that sign our zones

Upholds

An active network attacker: a weak, shared or known-compromised key behind our own MX and TLSA records is reported to the operator.

A validating resolver says that an answer verified, not with what. Our TLSA pin and the MX records that senders follow are only as strong as the zone’s DNSKEY set, which the DNS host chooses. pepsi-setup check (group DNSKEY) and pepsi-status (section Own DNSSEC) read the DNSKEY RRset at the apex of every served zone (the accepted domains, HOSTNAME and the SRS domain; the apex is found through the SOA record) and report, as findings that check --fail-on-findings and its daily timer surface, every zone-signing key that uses an algorithm that RFC 8624 and RFC 9905 say not to sign with (RSAMD5, DSA, RSASHA1, DSA-NSEC3-SHA1, RSASHA1-NSEC3-SHA1, ECC-GOST; RSASHA512 is NOT RECOMMENDED), an RSA modulus below 2048 bits, a key that signs more than one of our zones, or a key in pepsi.compromised_key (the badkeys list and the batch-GCD screen, by badkeys’ hash of the public value). Nothing is refused and no key roll is attempted: the zone’s signer is not Pepsi. Keys of correspondents’ zones are not judged, since Pepsi trusts the AD bit of its resolver for them (The network adversary).

17.15.47. Who may obtain our certificates

Upholds

An active network attacker: the window in which a hijacked domain validation yields a trusted certificate for our MX or openpgpkey host is visible to the operator.

pepsi-setup obtains the ingress, console and WKD certificates from Let’s Encrypt over HTTP-01, so whoever redirects the route to this host, or its DNS, during a validation can obtain one as well. A CAA record naming letsencrypt.org with this host’s ACME accounturi (RFC 8659, RFC 8657) confines issuance to our own account; pepsi-setup run prints one, commented out, and never publishes it, because it refuses every other CA the domain uses (a web host, an S/MIME CA). pepsi-setup check looks up the set a CA would consult for each served domain and certificate host and reports it as none, without accounturi or not DNSSEC-validated (an attacker who answers the CA’s queries can hide an unsigned record). It reports a set under which certbot’s own renewal would fail as an error. Without the record, the protection is the CA’s multi-perspective validation, nothing that Pepsi controls.

17.15.48. Revocation of TLS peers: stapled OCSP only

Upholds

An active network attacker: a receiving domain’s or smarthost’s certificate whose key was exposed and revoked no longer authenticates a validated hop once the server staples the CA’s answer, and the check costs no query to the CA.

An outbound TLS peer’s certificate is otherwise valid until it expires; the CA’s revocation reaches a client only if the client asks (a CRL fetch or an OCSP query) or the server hands it over (a stapled OCSP response, RFC 6066 §8). Pepsi asks nothing: a query tells the CA which certificate this host talks to and when, and makes every delivery wait on a third party. For the relay stages, it would also tie them to the CRL fetcher and its soft-fail rules while an unanchored intermediate still covered nothing. What the server staples carries none of those costs, so pepsi_common::smtp::ocsp evaluates it on every outbound session, in every connector that both relay stages and key discovery build, and in every HTTPS request of pepsi_common::http_client (the merchant backend, OAuth token endpoints, telemetry submission, list template fetches and Mailman imports, the MTA-STS policy fetch and the pepsi-setup probes), whose certificates are validated against the system roots with the same verifier, Certificate Transparency check included.

The evaluation is RFC 6960’s: the response must be signed by the issuer of the server certificate, or by a responder certificate that issuer signed with id-kp-OCSPSigning and that the response carries; its CertID must name the certificate by serial and issuer hashes; and the answer must be inside its thisUpdate/nextUpdate window at the time of the handshake. Three outcomes:

  • A verified ``revoked`` fails the session as CertificateError::Revoked wherever the certificate is validated at all: TLS_VERIFY, TLS_CA and TLS_CA_BUNDLE on a smarthost, an MTA-STS policy, the DANE = warn fallback to PKIX, a DANE-TA match, key discovery’s TLS_CA_BUNDLE and pepsi_common::http_client. The relay stages treat it like any other certificate failure (the next MX host, or a deferral). This is a hard failure on purpose, where the rest of revocation in Pepsi is soft: a stapled revoked is the CA’s own signed statement that the key must not be trusted, handed over by the very server presenting it. Unlike a fetched status it cannot be withheld by an attacker to produce a pass, and unlike an absent one it leaves no uncertainty to resolve in the peer’s favour; soft-failing it would mean knowing that a key is burnt and using it anyway. On an accept-any (opportunistic) session it is logged only: nothing about that session was being validated, and refusing it would downgrade a hop that was never authenticated to no delivery.

  • A verified ``good`` is noted at debug level. Nothing is cached, so a replayed old good (Frieß et al.) buys an attacker only what the response’s own window allows, which is the CA’s choice.

  • Anything else is logged as a warning when a staple was present, and the session proceeds: no staple, unknown, a response for another certificate, a responder that the issuer did not authorise, a signature that does not verify, a window that has closed. That is the soft failure a stapled status can afford: no fetch was skipped, and an attacker who strips the staple leaves the certificate exactly as unchecked as every other peer’s.

A DANE-TA (usage 2) match is a PKIX path to the anchor the domain publishes, and the anchor’s CA can revoke the server certificate under it: a verified stapled revoked defeats the match (strict refuses the session, warn hands it to the check that the hop has without DANE, which refuses it too). A DANE-EE (usage 3) match asks no OCSP: the record ties the session to the key that the domain publishes now, and RFC 7672 section 3.1.1 makes the certificate around that key a mere carrier whose validity is not consulted. The revocation of a DANE-TA anchor itself is the domain owner’s to act on, by withdrawing the record (RFC 6698). What stays soft is in Stale certificates and missing revocation after key exposure; what an operator does after an exposure of their own keys is After a key exposure.

17.15.49. Require TLS for one message (RFC 8689)

Upholds

An active network attacker and The network adversary: a message that its originator tagged REQUIRETLS cannot be downgraded to cleartext or intercepted on any hop, whatever the recipient domain publishes; it bounces instead.

The recipient-side policies above protect only recipients who publish them. RFC 8689 is the originator’s instrument: the REQUIRETLS parameter on MAIL FROM asks every relay to use validated TLS or not deliver, and the TLS-Required: No header field asks relays to treat the recipient’s policy as advisory for a message that must get through (a report to a postmaster whose certificate has expired, say). pepsi_common::requiretls holds the shared vocabulary; the tag travels as state.tls_required.

Receiving (pepsi-ingress): the extension is advertised, and the parameter accepted, only on a TLS-protected session, which is the one requirement of RFC 8689 §2 that the receiver can observe; advertising it is a promise to carry the requirement onward, and a message that already crossed a hop in the clear cannot be given that promise, so the parameter is refused with 530 5.7.10 there. A lone TLS-Required: No field is honoured only when the parameter is absent and the field occurs exactly once with exactly that value; anything else means nothing, since reading a malformed field as an opt-out would hand anyone composing a message a one-line downgrade of a recipient’s DANE or MTA-STS policy. Every row split or cloned from a tagged message inherits the tag (§4.1).

Relaying (pepsi-stage-relay-to-internet, pepsi-stage-relay-to-smarthost): a "required" message is sent only to a next hop whose name is validated, over mandatory STARTTLS, and only if the hop advertises REQUIRETLS after the upgrade; the parameter is then passed on. For direct delivery the name is validated by a DNSSEC-signed MX RRset (DANE on and a validating resolver) or by an MTA-STS policy in either mode; for a smarthost, by the configuration. The certificate must be authenticated by DANE (a warn-mode mismatch falls back to PKIX, never to the accept-any check) or by PKIX against the system roots. A smarthost entry’s TLS_VERIFY = no is overridden for such a message and MODE = plain refuses it. Each MX host is tried in turn; a host that fails any step gets a QUIT and the message is bounced with 5.7.30 (no REQUIRETLS at the hop) or 5.7.10 (no validated TLS) once no host can take it, unless some host failed for a transient reason that a retry might clear. An attacker on the path can therefore turn such a message into a bounce (a denial of service, as under DANE strict), never into cleartext. The shared SMTP client enforces the hop-side rules (pepsi_common::smtp::client), so neither stage can send a tagged message without them.

A "no" message is delivered to every MX host over opportunistic STARTTLS, with an enforce policy and DANE treated as advisory (a mismatch warns). What is not relaxed: a handshake that fails after STARTTLS was offered is not retried in cleartext, since an attacker can cause that failure; smarthost settings, which are this site’s policy and not the recipient’s, stay in force; and a stapled OCSP status of revoked still refuses a validating session. Sessions of such a message are not counted for TLSRPT: the originator asked for the policy to be ignored, and the report would blame the domain’s policy for a failure that it did not cause.

Bounces (pepsi-stage-bounce): the DSN for a "required" message quotes headers only (RET=FULL is disregarded, §5), carries the tag, and is returned under the same requirement with the parameter where the return path advertises it; a hop without the extension still takes it (§5), a return path without validated TLS loses it — and its postmaster copy with it, which is held to the same rule. DsnParams::from_state reads the tag, so a relayed RET is HDRS too.

Limits. A mediator that composes a new message, such as a digest, a vacation or secretary notice or a payment request, starts without the tag (§6 asks for it “to the extent feasible”); per-member list copies and alias expansions are splits of the tagged row and keep it. The local submission socket is a UNIX socket, so pepsi-sendmail cannot request the parameter. A relay beyond the next hop that lies about its support sees the plaintext anyway and is outside the model, as the RFC says.

17.15.50. Strict SNI on the HTTPS listeners

Upholds

An active network attacker: a connection redirected to pepsi-httpd under another host name is refused rather than answered.

A pepsi-httpd TLS listener serves a [pepsi-httpd-cert-*] certificate for the SNI names that section lists, and its own TLS_CERT/TLS_KEY to a client that sends no SNI at all. An SNI name that matches no section gets the listener’s certificate only if that certificate is valid for the name (its subject alternative names, wildcards included); any other name fails the handshake. A server that answers every name with a fallback certificate is what a cross-protocol attack (ALPACA) needs: an attacker who redirects a client’s connection for some other service to this host gets a TLS session the client may accept if it does not check names, and a confused one otherwise. Refusing the handshake removes that, and costs nothing for a correctly configured name. Clients without SNI keep working.

17.15.51. Web clients at the SMTP port

Upholds

An active network attacker: a browser redirected to an SMTP listener is turned away before anything it sends is read as SMTP.

The SMTP listeners hold a certificate valid for names that a browser may also be sent to, so an attacker who redirects a browser’s HTTPS connection to port 25, 465 or 587 gets a completed handshake unless the server refuses one. Ingress reads the ClientHello before it chooses a configuration, and one whose ALPN offer names only HTTP-family protocols (http/1.1, h2, h3 and their relatives) gets a no_application_protocol alert. A hello without ALPN, or with any other identifier, proceeds, and ingress selects no protocol: putting smtp on the wire and refusing everything else (RFC 9325’s strict ALPN) would refuse a mail client on a generic TLS stack whose offer nobody can predict, while the refused offers are exactly what a browser sends. A client that reaches the SMTP dialogue anyway is closed at its first HTTP request line or header (554), and any client at its tenth line that is no command (421). SNI is not enforced: MTAs send the MX name, the domain or nothing.

17.15.53. The administrative API

Upholds

A delegated administrator and boundaries B6/B7.

Three authentication mechanisms, one identity model: SO_PEERCRED over a UNIX socket (unforgeable, and how first-run bootstrap works with no accounts yet), bearer tokens for automation (digest-stored, constant-time compared), and password plus session cookie for browsers (Argon2id, HttpOnly and SameSite=Strict, CSRF token on every mutating request). No session token travels in a URL (Reflected and stored XSS or HTML injection in portals and admin mails), and a fresh installation has no default account (Default passwords and missing application secrets). Administrative routes mount only on listeners flagged ADMIN = yes, so a relay install that never enables such a listener does not expose the surface at all.

A console password is chosen to survive guessing. Creating an account or changing its password refuses one shorter than twelve characters, one on the list of common passwords Pepsi ships, and one containing the account name (pepsi_common::password::new_password_refusal, NIST SP 800-63B §5.1.1.2’s blocklist check). The list is drawn from a published breach corpus, the million most frequent of Mark Burnett’s ten million passwords, and holds the part of it that is long enough to be accepted at all. It is matched without regard to case, because an online guesser tries exactly those passwords first and a rate limit only decides how many of them it gets through. List members’ passwords are held to the same list with their own ten-character floor, wherever they are chosen.

Online guessing of a console password is bounded twice: per minute, by account and by source address (LOGIN_RATE_LIMIT, 10), so neither many passwords at one account nor one password at many accounts goes fast; and per day, by account from every source together (LOGIN_DAILY_LIMIT, 100 failed sign-ins, refilling continuously), so a guesser spread over many addresses gets a hundred guesses a day rather than six hundred an hour. The ceiling is asked before the password is checked and charged only after it failed, and it is keyed on the name as presented, so it neither costs an owner who signs in nor says which accounts exist. Anybody who knows an account name can spend it, which refuses that account’s password sign-ins until it refills; the local socket (SO_PEERCRED) and bearer tokens are not password sign-ins, so the operator can still act.

Responses never contain secrets: GET /api/v1/config masks credential-bearing options rather than omitting them, so an operator can see that a password is set without the endpoint becoming a way to read one back.

Every response pepsi-httpd sends over one of its own TLS listeners carries Strict-Transport-Security: max-age=31536000 (without includeSubDomains or preload), so after one HTTPS visit a browser will not let an active attacker downgrade the console, the portal or the list pages to plain HTTP for a year. It is never sent over plain HTTP or a UNIX socket, so behind a reverse proxy the front server must set it; the nginx and Apache sites that pepsi-setup writes do. pepsi-setup check fetches https://<name>/ for every HTTPS name under which pepsi-httpd is reached (the certificate hosts and the mta-sts., openpgpkey. and autoconfig. names) and reports an HSTS [MISMATCH] when the answer carries no valid header with a max-age of at least six months, which is how a hand-written front server that drops the header is noticed. The first visit, and a user who clicks through a certificate warning, stay unprotected. Short plain-text answers (an unknown path, a wrong method, an error) carry X-Content-Type-Options: nosniff and a Content-Security-Policy that permits nothing, as the API’s JSON and the pages do, because several of them echo request-derived text.

17.15.54. Switching feature telemetry on from the console

Upholds

Assets (privacy toward third parties: nothing the operator did not opt into) and A compromised component (pepsi-httpd).

[pepsi] SHARE_TELEMETRY lives in the configuration file, so the console changes it only the way it changes anything there: a write-config request that root’s applier performs. What makes that safe to offer is a precondition that the operator sets up by hand and that the console can only observe: pepsi-telemetry-client must be running (dormant while telemetry is off) and [pepsi] SYSTEM_ID must be present. The daemon reports both in the one-row pepsi.telemetry_client table, which pepsi-httpd may read and not write, so a console cannot forge “ready”. The row carries a boolean for the identifier, never its value. Without it the question is disabled with directions and an API request to switch on is refused (409 telemetry_client_not_ready); switching off is never refused.

That gate is a statement of usefulness, not the boundary. The boundary is the daemon: it believes only the file (through the single reader of the switch), re-reading it on the telemetry_changed notification, on SIGHUP and every minute; a notification cannot turn it on. A compromised pepsi-httpd holding CONFIG_DB could already request any configuration, this switch included, and that is unchanged; what it cannot do is make a deployment whose operator never started the daemon submit anything. Nothing in this path mints an identifier that the installation did not already have: the applier carries an existing SYSTEM_ID across a console save instead, and pepsi-setup generates one only on a yes. Switching off discards what the daemon had gathered and not yet sent.

17.15.55. The supply chain

Upholds

A compromised dependency: a third-party crate enters or changes only through a recorded decision, and a released artefact can be checked against the source that claims to have produced it.

Every mechanism here is tooling around the build, not code in the server; none of them makes a malicious crate harmless, since a crate runs with the privilege of every program that links it. Together they make visible the moment at which a crate enters, and make the artefacts that a user installs checkable.

  • The lock file is the inventory. Cargo.lock names every crate version with its checksum; every build passes --locked, so a build that would need a different version fails rather than resolving one. cargo deny check (deny.toml) refuses every registry but crates.io, every git source, yanked versions, licences other than the ones listed, and versions with a published RustSec advisory; its ignore list is argued entry by entry in the file and is not empty. The two dependencies that the project patches are in the tree (vendor/), not fetched. Dependencies accounts for every package in the lock file, and a test fails when the lock file names a package that the chapter’s data does not name.

  • The audit record is ``supply-chain/`` (cargo vet). config.toml lists the public audit sets that are imported and, per crate version, the exemptions; audits.toml holds the project’s own audits; imports.lock pins the imported sets, so cargo vet --locked, the gate in make check and in CI, never fetches and cannot pass on audits that the tree does not carry. The check passes only when every third-party crate version in the lock file is covered by an audit or an exemption. A developer who adds or updates a crate meets a failing gate and records a decision: cargo vet diff or cargo vet inspect to read the change, then cargo vet certify (an audit, with the reviewer’s name, for what was actually read) or cargo vet add-exemption for what was not. An exemption is an honest “unread”, never a fake audit; the threat model counts them. Path dependencies are first-party and reviewed in the tree (vendor/PEPSI-VENDORING.md): the workspace’s own crates, the vendored mail-auth and the taler-rust submodule. So policy.mail-auth sets audit-as-crates-io = false: the patched copy is not the crates.io crate and no imported audit of that crate is taken to cover it.

  • Releases are signed. make dist-sign makes a detached, armoured OpenPGP signature of the release tarball with the release manager’s key (DIST_SIGN_KEYID), and verifies it before succeeding; make deb DEB_SIGN_KEYID=… signs the Debian .changes and .buildinfo files with the taler-systems release key, the one that the deb.taler.net repository is signed with, so apt verifies the packages against the keyring that the user installed. Verifying a download is the user’s side.

  • The release build is reproducible. make build maps every path that would otherwise end up in a binary to a fixed name (the checkout, the crate cache and the target directory), for rustc and for the C compiler that the native crates invoke; symbols are stripped; the toolchain is pinned (rust-toolchain.toml); SOURCE_DATE_EPOCH is the commit’s date; and make dist writes the tarball with sorted entries, fixed mtimes and numeric uid 0. The CI job 5-reproducible builds the release twice, from two clones at different paths with different crate caches, and fails on a differing byte, so the property is checked on every run rather than claimed. Reproducible builds is the recipe a user follows to compare a published binary with one they built.

The gaps are stated with the claim: an audit says that a crate was read, exemptions outnumber audits, and the compiler and the crates are trusted as downloaded against their recorded hashes.

17.15.56. Resource limits

Upholds

Availability: a stranger cannot make one message, one connection or one address cost the server without bound.

The limits themselves are tabulated in Availability; what matters here is where each is enforced and why it cannot be stepped around.

  • A session ends. pepsi-ingress bounds a TLS handshake, implicit or after STARTTLS, by TLS_HANDSHAKE_TIMEOUT (30 s) as one deadline on the whole handshake, so a ClientHello trickled a byte at a time does not extend it. It bounds every read by COMMAND_TIMEOUT or DATA_TIMEOUT, but a client resets those with every byte; the session deadline SESSION_TIMEOUT (30 m from the connection) is reset by nothing. It is enforced inside the one read primitive that every command, AUTH continuation and body read goes through, which clamps each read to the time left and fails at once when none is, so there is no path on which a client’s own pace keeps a session alive past it; the client is told 421 4.4.2 Session time limit exceeded and may reconnect.

  • Connections are bounded per source, not only in total. pepsi-ingress counts open connections per source range (MAX_CONNECTIONS_PER_IP) and, for the UNIX-socket peers that are exempt from its rate limit and never evicted, for all of them together (MAX_LOCAL_CONNECTIONS) and per peer uid (half of that, so one local account cannot lock out cron and the other users). When the local ceiling is full, a new local connection from a uid that holds fewer local connections than the heaviest uid evicts that uid’s longest-idle connection, provided it has sent no complete command line for 5 seconds (421 4.3.2): pepsi-sendmail reads its message before connecting and never pauses, so only a held-open slot is reclaimed, and accounts acting together cannot keep the ceiling full; pepsi-httpd does the same per client address. The check happens before a connection takes a slot of the global ceiling, so a source at its share cannot also queue for more.

  • A slow body is idle time. A connection waiting for the next bytes of a DATA or BDAT body counts as idle exactly as one waiting for a command does, so a client that trickles its body to keep resetting DATA_TIMEOUT is still the first to be evicted when the server is full. An oversized DATA body is drained to its end only for another MAX_MESSAGE_SIZE octets; past that the server answers 552 and closes.

  • The mail store is never handed an unbounded header block. At the end of data, before anything parses it, ingress counts the top-level header fields and measures each unfolded in one linear pass, and refuses more than MAX_HEADER_FIELDS or a field over MAX_HEADER_FIELD_SIZE with 552 5.3.4 on every listener. That is the bound that the Dovecot advisories CVE-2024-23184/23185 ask of the MTA in front. Pepsi’s own header parsers are linear and are tested at those limits; header blocks of attached messages are bounded by the message size alone.

  • Guessing and flooding are counted across sessions. A per-range token bucket (AUTH_FAILURES_PER_HOUR) is spent by every failed AUTH, and once it is empty the next AUTH is refused before the SASL backend is asked. A per-account bucket keyed on the authentication id (ACCOUNT_AUTH_FAILURES_PER_HOUR) is spent by failures from every source together. Once it is empty, an AUTH for that account from a range that it has not authenticated from in 30 days waits ACCOUNT_AUTH_DELAY and is checked one at a time with the others, so a spray from many addresses gets one guess per delay. Such an AUTH is delayed, never locked: a lock would hand anybody who knows an account name a way to shut its owner out. A per-uid bucket keyed on the kernel-reported SO_PEERCRED uid (LOCAL_MESSAGES_PER_MINUTE) meters local submission, and a per-account bucket keyed on the SASL authentication id (USER_RECIPIENTS_PER_HOUR) meters the recipients that an authenticated account submits to, wherever it connects from. A session may start only MAX_MESSAGES_PER_SESSION transactions before it must reconnect into the rate limit.

  • One sender’s burst does not delay everybody else. pepsi-dispatch claims each stage’s work by least virtual runtime per sender rather than oldest first (FAIR_SCHEDULING, on by default). The sender is the generated workqueue.sender_key: the authenticated account for a submission, otherwise the connecting address (an IPv6 peer by its /64, since a single host is routinely given one), and never the envelope domain of mail from outside, which the sender chooses per message. Worker time is charged to the sender that caused it, a newcomer starts level with the least-served sender so silence banks no credit, and a reserved oldest-first share (FAIR_FIFO_PERCENT) bounds any one message’s wait. The accounting is in the dispatcher’s memory only; it grants nothing and changes no grant.

  • Inbound verification has a work bound that is not a way around DMARC. At most MAX_DKIM_SIGNATURES signatures are verified, those that can align with the From: domain first, and SPF and each signature run concurrently under VERIFY_TIMEOUT, with DMARC under a second deadline. A check that runs out of time becomes temperror for that check: DMARC consults a temporary error only on an identifier that aligns with the From: domain, and the DNS that DMARC itself reads is that domain’s own, so a forger who slows their own DNS down gains nothing but their own temperror.

  • Key material from strangers has a size ceiling. Every OpenPGP certificate that arrives from outside passes through one parser that refuses an RSA key above 8192 bits, whether it comes from WKD, a key server, DANE, a harvested or gossiped header, an attached key or a pasted one. The verifier drops such a certificate from its trust store as well. S/MIME certificates have the same 8192-bit bound (smime::MAX_RSA_BITS), enforced where a certificate’s key is parsed.

  • Retention does not depend on the web tier. The audit and mail logs are pruned by pepsi-httpd prune from pepsi-log-prune.timer, as the pepsi-httpd account. That is the one service role holding DELETE on them, which keeps the logs append-only for everything that handles mail. TLS-report counters and expired MX cache rows are pruned by their own timers. All these timers are named by pepsi.target.

  • The queue has a ceiling, and the check cannot be starved or bypassed by splitting. pepsi-ingress refuses with 452 4.3.1 at RCPT, DATA/BDAT and after the end of data while the queue is at [pepsi] MAX_QUEUE_ROWS/MAX_QUEUE_BYTES or the database’s filesystem below MIN_FREE_SPACE. The measurement (pepsi.queue_usage()) reads only two generated size columns, so the least-privileged ingress role gains no access to queued mail for it, and it is cached per process (QUEUE_CHECK_INTERVAL), so a flood of RCPT commands costs no queries. Bytes are counted per stored body: bodies live in pepsi.workqueue_body, shared by every row that a split, clone or list fan-out makes, so one large message to many recipients does not multiply its body across the queue when it is split per recipient. The one amplifier left under a sender’s control, a post to a large list, holds its fan-out back (pepsi-stage-list-post, QUEUE_THROTTLE_DELAY) while the queue is full. Deleting the last row that references a body deletes it (a trigger), and the foreign key means that no role can delete a body that a queued message still carries, not even with the web tier’s DELETE on workqueue_body.

  • Mailing lists bound what one sender can make them do. A sender’s accepted posts to a list are counted per hour (SENDER_POSTS_PER_HOUR) in one SQL statement that decides and records, so parallel workers cannot both take the last slot; the excess is held rather than multiplied by the membership. The moderation queue is capped per list (MAX_HELD_MESSAGES) by discarding the new post, so a flood cannot flush out the posts a moderator has yet to see. A post that filter_action would keep is refused to its sender instead.

  • Automatic spending has an aggregate, and it cannot be raced. pepsi-stage-auto-pay books a demand against two budgets in the one auto_pay_try_spend call that also records it: the message’s (MAX_TOTAL, on the origin_nonce row, locked FOR UPDATE) and the paying wallet’s rolling 24 hours (MAX_TOTAL_PER_DAY, the auto_pay_spend ledger, under a transaction-scoped advisory lock keyed on the wallet; demands for different messages share no row, so without the lock each would read the same sum). A refusal by either writes nothing to the other; a payment that fails to settle is credited back to both by auto_pay_refund, which takes only the first lock, so the two cannot deadlock. The wallet key is the one that the helper pays from (uid:<n>, or the shared account and wallet database), so two senders cannot share a day unless they share a wallet. The daily limit is not optional where money moves: a section with a non-zero MAX_TOTAL and no MAX_TOTAL_PER_DAY is refused at worker start and by pepsi-setup validate (the wizard writes both), and pepsi-stage-edit-settings refuses both options in an e-mailed override, since the control message is authenticated by the very password whose theft they bound (Someone holding a user’s mail password).

  • No automatic reply to a sender that failed authentication. All automatic replies go through pepsi_common::autoreply: the vacation notice, the payment request, the secretary challenge, and the list command and autoresponder notices. Besides the RFC 3834 rules, autoreply withholds a reply when pepsi-ingress recorded a definite failure, state.auth.spf or state.auth.dmarc equal to fail: the envelope sender is then most likely forged, and the reply would be backscatter to whoever was impersonated. Only fail counts; softfail, neutral, none and temporary errors are still answered, so a legitimate sender at a domain that publishes no policy is not cut off. Locally submitted mail is exempt. The residue is a forged address at a domain that publishes no failing SPF policy and no DMARC record, and it is the operator’s to close: REQUIRE_AUTHENTICATED = yes in the vacation, pay-to-send or list-command stage section (autoreply::suppress_reason_with) withholds that stage’s reply from every sender that did not pass SPF or DMARC, at the price of never answering a correspondent at a domain that publishes neither record. The option is off by default; the secretary’s option of the same name is on by default.

  • A payment request answers a sender once per window. The request is an automatic reply to an unverified envelope sender, so besides RFC 3834 suppression pepsi-stage-anti-spam claims it through payment_request_should_send, keyed on the protected mailbox and the sender, with BLOCK_RESPONSE_SUPPRESS as the window. Like vacation_should_reply, that function decides and records in one statement (INSERT … ON CONFLICT DO UPDATE … WHERE). A failure to claim withholds the reply; the message is held either way.

17.16. What Pepsi does not defend against

The list is kept in one place, What Pepsi does not protect, together with the residuals that each adversary section states: root and a malicious operator, traffic analysis and metadata, plaintext in the queue, signatures against a compromised pipeline, a malicious dependency that nobody read, correspondents’ own compromise, and a network attacker who can also lie in DNS.

17.17. Reporting a vulnerability

Please report security issues privately by e-mail to Christian Grothoff at grothoff@gnunet.org, encrypted to the OpenPGP key published at https://grothoff.org/christian/grothoff.asc, whose fingerprint is D842 3BCB 326C 7907 0339 29C7 939E 6BE1 E29F C3CC. Do not use the public bug tracker for a vulnerability, and allow time for a fix before disclosure. SECURITY.md in the source tree states the full policy.

Ordinary bugs go to the public bug tracker at https://bugs.gnunet.org/view_all_bug_page.php?project_id=35.

17.18. See also

Key management — identities, custody, discovery and the trust ladder. The secure-link fallback portal — the portal in full. The administrative API — the API surface and its scopes. Client interoperability — what other clients can actually read, which bounds what protection is achievable in practice. Test Suite — the fuzzing and adversarial corpora behind the parser claims.