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
GRANTkeyed on the effective uid; anosuidmount 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_SERVERSas 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 thepepsi-keydisc@danediscovery 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 signedietf.orgSOA: 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 toDANE = strict, so a peer with DNSSEC-signedTLSArecords gets mandatory TLS and a certificate that matches none of them defers the message (DANE = warnis 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:SELECTonly on the columns other thanprivate_wrapped, noINSERT, andUPDATEonly of the use flags (is_primary,published,vks_wanted) and the key-server progress columns thatpepsi-stage-vks-confirmrecords (DELETEhas no column granularity and stays);pepsi-cryptoalone holdsprivate_wrappedand may write what an identity is – its address, protocol, purpose, fingerprint and public half;config_override:SELECTonly — writing it is thepepsi-configrole’s (pepsi-httpdwrites through a[pepsi-admin] CONFIG_DBconnection that authenticates as that role);setup_taskandsetup_task_log: nothing; onlypepsi-configmayINSERTa task;secure_messageandsecure_access:INSERT,DELETEandSELECTof every column butciphertextonsecure_message;SELECTandDELETEonsecure_access;admin_account,admin_session,api_token,own_enrolmentandown_session: nothing;otp_keyandotp_pending: nothing (pepsi-cryptoalone holds them, see A second factor for key management);crl_cacheandca_issuer_cache:SELECTonly — onlypepsi-keydiscwrites the CRL cache and the fetched intermediates;compromised_keyandcompromised_key_import:SELECTonly forpepsi—pepsi-cryptoalone writes the known-compromised-key list;the managed-PKI tables
mpki_domain,mpki_user,mpki_order,admin_notificationandcrypto_identity_chain: nothing forpepsi.pepsi-crypto(pepsi-keys mpkiand the encrypt stage) holds them, and is the only role that may readmpki_order.key_wrapped(Certificates from a commercial CA);schema_file:SELECTonly, for every service role;event_logandmail_log: append-only (noUPDATE/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 |
|---|---|---|
|
|
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. |
|
Its |
Everything else, so a collector sharing a database with a pipeline cannot reach the mail. |
|
The administrative credential tables (with the end users’
|
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 |
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 |
|---|---|---|
|
|
|
|
|
The pipeline grant above: the queue, settings, statistics, whitelist,
and the secure-link tables without their |
|
|
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 |
|
the invoking operator |
Installed |
|
|
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 |
|
|
The discovery request queue, |
|
|
No database role. The DKIM and ARC private keys in its own 0700
state directory, and |
|
invoking user (setuid) |
|
|
|
|
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 |
|---|---|---|
|
|
Becomes the recipient to write into a |
|
|
The setgid bit is the sole gate on exec’ing that helper, so the mode is
|
|
|
Same helper, so a |
|
|
Drops fully to the user before reading their |
|
|
The same gate, for that helper. |
|
|
Drives the wallet as the account that owns it: a local user at or above
|
|
|
The same gate, for that helper. |
|
|
Reads the group-restricted OAuth token files that
|
|
|
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. |
|
|
Peer authentication keys off the effective uid, so the stage has to
be the role granted |
|
|
See the table above. A site may make it setuid |
|
|
The unprivileged half of the |
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. Underheader_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_limitnew 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=anda=are the request’s, itsb=is empty and no tag is repeated;for DKIM:
h=namesfrom, there is aFrom:field, and every mailbox of everyFrom:field is in the same organisational domain asd=;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
statustakes the code as a six-digit word in theSubject::generate,register,publish,retire,pinandotp enroll/otp removethemselves.otp confirmtakes a code from the new secret instead (see below). An ordinary message’sAutocrypt:header or attached key then registers nothing for that address.pinis 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’sgenerate-identity,register-client-key,revoke-identity,set-identity-flags(publication, key-server upload, primary key),identity-csrandidentity-certificaterequests carry anotpfield.pepsi-httpdholds no grant on the table at all, so it cannot check the field and passes it through;pepsi-setup applychecks it before acting, for a task admitted onown:<address>alone. An operator holdingkeys:writeis 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 CODEfor 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:clientDataJSONmust name the ceremony, carry the issued challenge (compared in constant time), name exactly the configured origin ([pepsi-admin] CONSOLE_URL, defaultENROL_URL, for the console; the origin of[pepsi-list] BASE_URLfor the member pages; bothhttps://only) and not have run in a cross-origin frame (crossOrigintrue or atopOriginis 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
noneonly. 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 byDELETE … RETURNINGso 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_WEBAUTHNthe 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 intopepsi-httpd. Those pages’Content-Security-Policyallows 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 withoutscript-src.Both tables are credentials: granted to
pepsi-httpdalone, revoked from every other role and verified bypepsi-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_enrolmentstores only their SHA-256, with the address, an expiry (ENROL_LIFETIME, 30 minutes) and an attempt counter. Each submission is counted in the sameUPDATEthat checks the expiry, so concurrent submissions cannot exceed five; the session is minted only after aDELETE ... RETURNINGof 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, anhttps://origin that the operator configures. It is never taken from the request: aHostheader 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
.forwardstage) 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 withAuto-Submitted: auto-generated.The second factor is the applier’s.
otp_keyis granted topepsi-cryptoalone and its secrets are wrapped under a KEK outside the database, so no grant topepsi-httpdcould let the web tier check a code. Not even aSECURITY DEFINERfunction 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 aconfirm-enrolmenttask carrying the code, under the address’s own scope and through the configuration role, like every other request to the applier;pepsi-setup applychecks the code with the replay protection and lock of A second factor for key management, and the session is opened only when the task endsdone. 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_sessionthat 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 sameHttpOnly,SameSite=Strict,__Host--prefixed cookies and CSRF check as an administrator’s session. It stores an address, not a scope list, so it can holdown:<address>and nothing else by construction. Both tables are credentials:pepsi-setupgrants them topepsi-httpdalone 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.workqueueholds theheadersandpepsi.workqueue_bodythe 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: afailedrow is bounced bypepsi-failure-bouncerafterMIN_AGE(an hour), a message held at a quarantine stage bypepsi-queue gcafter[pepsi-queue] QUARANTINE_MAX_AGE_DAYSor by the stage’s ownMAX_HOLD(Quarantined mail; 14 days by default; the DSN returns no content, whateverRETasked, and a message from an AES-CBCEnvelopedDatais dropped rather than bounced, Bounces and replies to encrypted mail), andpepsi-setup schema --backup-dirkeeps 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_cacheandca_issuer_cache(which CAs correspondents use) andlogin_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.ciphertextis 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 exportuses 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-signruns aspepsiand has its signatures made bypepsi-dkimover a socket open to grouppepsi, so anypepsiprocess 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-encryptsigns as the row’sFrom:author. Ingress enforcesUSERNAME_MAPat submission, but the queue row is writable by everypepsistage afterwards and nothing downstream can tell whether ingress made that decision. A compromisedpepsistage can therefore rewrite a queued submission’sFrom:(or inject a message withworkqueue_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 ofcrypto_identityunder the ordinary pipeline grant. It never namesprivate_wrapped, and gaining thepepsi-cryptoidentity 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.inand inX-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.insays encrypted and decrypted), and recordsstate.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 = bouncethe DSN’s header block is cut to the addressing fields, the body is emptied andRET=HDRSforced, 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, theretiree-mail command and therevoke-identitytask that the console and the API enqueue all callpepsi_keymat::revoke. For an OpenPGP key whose private half is held it unwraps the key (as thepepsi-cryptorole, like every revocation, since it namesprivate_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 oneUPDATE(revocation_certified_atrecords 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_atset is on the second work list ofpepsi-keys identity publish --retryuntil 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
emailAddressattribute 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 9598SmtpUTF8MailboxbindsFrom:too, so it is held to therfc822Namesubtrees 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
nameConstraintsat 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 inca_trust.permitted_domains, and path validation applies them as RFC 5937 trust-anchor constraints: anrfc822Namepermitted 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 theFrom: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, sovalid-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 bypepsi-keys ca list, pepsi-status andpepsi-setup check. The scope covers S/MIME signature trust only; outbound TLS validates servers against the system’s root store (orTLS_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-rejectedrather 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; aminimumormaximum; or an undecodable extension, critical or not. Where Pepsi departs from RFC 5280 or from OpenSSL it is always in that direction: a wildcarddNSNamethat 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 twokeyUsageornameConstraintsvalues 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
signingTimethe 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_BITSapplies 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_BITSis 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 andpepsi-keys peer importrefuse to store it.pepsi-keys blocklist updatekeeps the list current (pepsi-keys-blocklist.timer, daily): it asks[pepsi-keydiscovery] BADKEYS_URLwith the last run’sETag, 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. Onlypepsi-cryptomay 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, andpepsi-statuswarns when the list has not been checked for three days.Keys that share a prime are found.
pepsi-keys peer screen, whichpepsi-keys-refresh.serviceruns 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 askey.peer.compromised, and its modulus added to the known-compromised list (pepsi.compromised_key, sourcescreen), so a rediscovered copy is refused as well. One of our own identities that shares a prime is reported (key.identity.compromised, severityerror) 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
SignerInfomust carry exactly onecontentType(equal to the content type it signs), onemessageDigestand at most onesigningTime, each with a single value, and no attribute twice. When the RFC 6211CMSAlgorithmProtectionattribute is present it must repeat theSignerInfo’s digest and signature algorithm identifiers exactly (absent and NULL parameters being the same), or the signature isbad-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
cRLSignpermitted, current (itsnextUpdatenot 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-keydiscfetches the CRLs that the cached S/MIME peer certificates name incRLDistributionPoints(http://andhttps://only; there is no OCSP) intopepsi.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’snextUpdatebut at least daily. Only thepepsi-keydiscrole 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-keydiscacts 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 withcRLSignpermitted, or by an intermediate CA certificate fetched underCA_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 markedrevokedinpepsi.peer_key(revoked_at,revoked_reason). The shared lookup that every stage uses then withholds the row:pepsi-stage-encrypthas no key for the recipient and followsON_NO_KEY, reportingrevokedas 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-encryptsets aside a recipient’s S/MIME certificate outside its validity period, and an OpenPGP key past its expiry, so the recipient takesON_NO_KEYwithexpired onand 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-keydiscfollows thehttp:///https://caIssuerspointers of the cached certificates and stores the CA certificates of each answer inpepsi.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 andpepsi-keys peer importall 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-encryptresume 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-encryptsigns 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-decryptopens a message and the signature inside names one or more intended recipients, none of which is the certificate whose key opened it, the signature isinvalidwith the layer verdictwrong-recipient(a signature that would not have verified anyway staysbad-signature). For S/MIME the comparison is with the digest of the certificate of the identity that opened theEnvelopedDataorAuthEnvelopedData. 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:withholdsvalid. When the protectedFrom:names another addr-spec than the outerFrom:(first mailbox, compared case-insensitively, as everywhere else), the verdict isvalid-untrusted: no[verified]tag, nostate.signature_verified. Two disagreeing protectedFrom:fields, an illegible one, or no legible outerFrom: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 ownFrom:, so that the certificate binding to the outer address passes.A different, added or removed reply-steering field withholds
validthe same way (withheld=reply-to). The reply-steering fields areReply-To:,Mail-Reply-To:andMail-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 thatPROTECT_HEADERSitself 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 aList-Id:with none of the three signed. Such a field keepsvalidunder 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 otherwisevalid, so the message stays[verified]under the subject its signer wrote; a marker written without brackets, such asEXTERNAL:, is thereby removed. The difference is reported either way.A protected
Subject:carrying a forged indicator withholdsvalid. 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 protectedSubject. 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 isvalid-untrusted(withheld=protected-subject). The tags Pepsi writes are not sent on:pepsi-stage-encryptremoves them from the subject of outgoing mail before signing (see Indicator tags do not leave the deployment), so a reply to a verified message keepsvalidat a receiving Pepsi deployment.To:differences are only reported, instate.crypto.in.protected_mismatchand theprotected-mismatchkey ofX-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.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 asstate.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_trustanchor (Binding::NoIdentity): it contradicts noFrom:, so the verifier does not fail it, but it vouches for no address, and would otherwise bevalidfor every sender and satisfysignature_requiredwhitelist 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
fromwhitelist: 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 toX-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 theDate:that the replayer writes; the claimed signing time is shown assigned-at=inX-Pepsi-Crypto. A signature without a creation time (CMS withoutsigningTime) 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 = negotiateonly a recipient recorded as unable to readAuthEnvelopedDatagetsEnvelopedData; 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, andyes(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-learnreads the RFC 8551SMIMECapabilitiesattribute only from a signature that verifies under a certificate that the message carries, and stores the claim against that certificate’s fingerprint. Forging aFrom: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 capabilitywrites it (audited askey.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 frompepsi-httpd,pepsi-ingressorpepsi-telemetry; it is not a per-address setting, so it cannot be changed by e-mail throughpepsi-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
AuthEnvelopedDatacan have itsRecipientInfore-submitted under a syntheticEnvelopedDatathat opens with the same content key. A correspondent whose learnt record says that its own signedSMIMECapabilitiesname RFC 9709id-alg-cek-hkdf-sha256is 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, andpepsi-stage-decrypthonours it on every message whose content-encryption algorithm names it.[stage-decrypt] OPEN_ENVELOPED_DATA = nocloses the inbound side for mail sent without the derivation: noEnvelopedDatais 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
Padderwrites 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 theContent-*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 = passthroughdelivers 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 settingbounceis an alias for the longer but unambiguousbounce-if-unproblematic: no setting bounces a failed ciphertext without integrity protection.A bounce for what the plaintext turned out to be.
ON_BAD_SIGNATURE = bounceandpepsi-stage-reencrypt’sON_NO_CLIENT_KEY = bouncewould bounce a message only because its ciphertext opened, into something that looks signed or not. For content from anEnvelopedDatacontainer (state.crypto.in.layers) both drop the message instead (telemetrydecrypt-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 = quarantineholds a failed message while one that opened is delivered, andON_BAD_SIGNATURE = quarantineholds one that opened into a bad signature;pepsi-queue gcends a hold after[pepsi-queue] QUARANTINE_MAX_AGE_DAYS, andpepsi-stage-quarantineafter itsMAX_HOLD(Quarantined mail). It bounces an expired message only whenstate.crypto.inshows noEnvelopedDatacontent and no failed ciphertext without integrity protection (crypto_state::unauthenticated_ciphertext); any other expired message is dropped and logged (telemetrydecrypt-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-milterdrops it where a filter’sREJECT(orON_FAILURE = reject) or an expiredTEMPFAILwould bounce it; a stage that keeps failing on it past itsMAX_LIFETIMEdrops it rather than rerouting it to itsBOUNCE_STAGE, andpepsi-failure-bouncerdrops it rather than bouncing it (telemetrydecrypt-droppedthroughout).pepsi-stage-block-languageunderENFORCEMENT = hardmarks and delivers it assoftmode 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_requiredwhitelist entry is satisfied by a signature that verified:pepsi-stage-check-whitelistdoes 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, whichPOST /resumecalls when a GNU Taler order is paid, answersheldand changes nothing for a message whosestate.quarantinerecords 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-allleaves thepausedrows 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-ingressanswers550 5.1.1for 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 withRCPT 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-bouncesends 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_HOPStimes 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
~/.forwardresends, 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-bounceandpepsi-stage-aliaseshand the row onpausedwith thattimeout(StageContext::hold_reflected),pepsi-stage-dot-forwardandpepsi-stage-list-postcreate 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’sSESSION_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
RCPTis: 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_REPLYCODEreaches the client only if it is a4xxor5xxreply of the verdict’s class with printable lines, all with the same code; a2xx, a bare CR or LF that would start a second reply line, or a code of the other class is replaced by a generic451/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_FAILUREpath: 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-arcverifies the chain over the original while sealing what is stored, so the seal does not reportcv=failfor 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 itsh=, the body for an attachment) is stored on theinbound-signedrung, above plaininbound, and the rank rule then refuses a key from any unsigned message however new it claims to be. Forging such a correspondent’sFrom: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, theAuthentication-Resultsfragment) and matches the passing signature back to its field by domain, selector and the start ofb=, 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 aSignedDatais never learnt at all.The conflict rule is per protocol, so the choice is by rank first.
crypto_peer_key_upsertcompares 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), andPREFERbreaks only a tie between equal rungs: anAutocrypt: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 rungPREFERdecides, 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_upsertwrites akey.peer.rotaterow topepsi.event_log(the append-only audit log that no mail-handling role canUPDATEorDELETE) 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-learnmails each local envelope recipient of the rotating message (RESPONSE_STAGE, thekey-rotationtemplate) 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
pinkey command; under an enrolled second factor and with the whole fingerprint it pins the key on themanualrung, 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 = expiredaccepts 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 askey.peer.rotate.heldand 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 unclaimedlists 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_upsertmoves the row from thegossipto theinboundrung and writes akey.peer.promoterow (neverkey.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 sameTrustSource::Autocrypt/Untrustedverdict 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.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.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::Revokedwherever the certificate is validated at all:TLS_VERIFY,TLS_CAandTLS_CA_BUNDLEon a smarthost, an MTA-STS policy, theDANE = warnfallback to PKIX, aDANE-TAmatch, key discovery’sTLS_CA_BUNDLEandpepsi_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 stapledrevokedis 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.52. The secure-link portal¶
Upholds
Somebody holding a copy of the database and the stored-message claim of The secure-link fallback portal.
The portal renders attacker-influenced content (a subject line, a sender name) into HTML, and gates it on a PIN. The design decisions that matter:
the PIN is never stored, in any form. It is an input to the Argon2id derivation of the content key, so an attacker with the database cannot verify a guess without also having the server pepper (Offline guessing of weak password hashes, key passphrases and derived keys);
the link and the PIN travel separately — the link to the recipient, the PIN to the sender to pass on by another channel. Compromising one mailbox yields neither the message nor a way to get it;
wrong PINs are counted and lock the message out for a configured interval, so the online guessing rate is bounded. Each attempt is charged before its key derivation, in one statement that holds the message’s row lock while it checks for a lockout and counts, so guesses sent in parallel cannot exceed the limit either (Login and recovery rate limits defeated by races and logic errors);
attachment file names are shown without bidirectional formatting characters and truncated keeping their extension, so a name cannot disguise what kind of file it is (the list archive and digests do the same);
the subject and the sender, which may legitimately contain right-to-left text and so keep their bidirectional characters, are each wrapped in an HTML
<bdi>element, so a right-to-left override (U+202E) in them reorders only their own text, never the page around them. The administrative console and the list archive isolate subjects, senders, recipients and file names the same way;a reply may be addressed only to the original sender, recorded in the row. The portal is not a mail-sending surface, and nothing in the delivered mail can redirect it (Portal binding data kept in unauthenticated ciphertext fields).
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.locknames 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; itsignorelist 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.tomllists the public audit sets that are imported and, per crate version, the exemptions;audits.tomlholds the project’s own audits;imports.lockpins the imported sets, socargo vet --locked, the gate inmake checkand 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 difforcargo vet inspectto read the change, thencargo vet certify(an audit, with the reviewer’s name, for what was actually read) orcargo vet add-exemptionfor 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 vendoredmail-authand thetaler-rustsubmodule. Sopolicy.mail-authsetsaudit-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-signmakes 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.changesand.buildinfofiles with the taler-systems release key, the one that thedeb.taler.netrepository is signed with, soaptverifies the packages against the keyring that the user installed. Verifying a download is the user’s side.The release build is reproducible.
make buildmaps 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_EPOCHis the commit’s date; andmake distwrites the tarball with sorted entries, fixed mtimes and numeric uid 0. The CI job5-reproduciblebuilds 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-ingressbounds a TLS handshake, implicit or afterSTARTTLS, byTLS_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 byCOMMAND_TIMEOUTorDATA_TIMEOUT, but a client resets those with every byte; the session deadlineSESSION_TIMEOUT(30 m from the connection) is reset by nothing. It is enforced inside the one read primitive that every command,AUTHcontinuation 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 told421 4.4.2 Session time limit exceededand may reconnect.Connections are bounded per source, not only in total.
pepsi-ingresscounts 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-sendmailreads 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-httpddoes 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
DATAorBDATbody counts as idle exactly as one waiting for a command does, so a client that trickles its body to keep resettingDATA_TIMEOUTis still the first to be evicted when the server is full. An oversizedDATAbody is drained to its end only for anotherMAX_MESSAGE_SIZEoctets; past that the server answers552and 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_FIELDSor a field overMAX_HEADER_FIELD_SIZEwith552 5.3.4on 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 failedAUTH, and once it is empty the nextAUTHis 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, anAUTHfor that account from a range that it has not authenticated from in 30 days waitsACCOUNT_AUTH_DELAYand is checked one at a time with the others, so a spray from many addresses gets one guess per delay. Such anAUTHis 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-reportedSO_PEERCREDuid (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 onlyMAX_MESSAGES_PER_SESSIONtransactions before it must reconnect into the rate limit.One sender’s burst does not delay everybody else.
pepsi-dispatchclaims each stage’s work by least virtual runtime per sender rather than oldest first (FAIR_SCHEDULING, on by default). The sender is the generatedworkqueue.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_SIGNATURESsignatures are verified, those that can align with theFrom:domain first, and SPF and each signature run concurrently underVERIFY_TIMEOUT, with DMARC under a second deadline. A check that runs out of time becomestemperrorfor that check: DMARC consults a temporary error only on an identifier that aligns with theFrom: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 owntemperror.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 prunefrompepsi-log-prune.timer, as thepepsi-httpdaccount. That is the one service role holdingDELETEon 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 bypepsi.target.The queue has a ceiling, and the check cannot be starved or bypassed by splitting.
pepsi-ingressrefuses with452 4.3.1atRCPT,DATA/BDATand after the end of data while the queue is at[pepsi] MAX_QUEUE_ROWS/MAX_QUEUE_BYTESor the database’s filesystem belowMIN_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 ofRCPTcommands costs no queries. Bytes are counted per stored body: bodies live inpepsi.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’sDELETEonworkqueue_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 thatfilter_actionwould keep is refused to its sender instead.Automatic spending has an aggregate, and it cannot be raced.
pepsi-stage-auto-paybooks a demand against two budgets in the oneauto_pay_try_spendcall that also records it: the message’s (MAX_TOTAL, on theorigin_noncerow, lockedFOR UPDATE) and the paying wallet’s rolling 24 hours (MAX_TOTAL_PER_DAY, theauto_pay_spendledger, 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 byauto_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-zeroMAX_TOTALand noMAX_TOTAL_PER_DAYis refused at worker start and bypepsi-setup validate(the wizard writes both), andpepsi-stage-edit-settingsrefuses 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,autoreplywithholds a reply whenpepsi-ingressrecorded a definite failure,state.auth.spforstate.auth.dmarcequal tofail: the envelope sender is then most likely forged, and the reply would be backscatter to whoever was impersonated. Onlyfailcounts;softfail,neutral,noneand 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 = yesin 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-spamclaims it throughpayment_request_should_send, keyed on the protected mailbox and the sender, withBLOCK_RESPONSE_SUPPRESSas the window. Likevacation_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.