16. Threat model

This chapter states what Pepsi protects, from whom, and how far — the claims. The next chapter, Security model, describes the mechanisms that uphold them (the account split, the database grants, the setuid programs, key custody) and is the one to read after a compromise. Every claim here names the mechanism it rests on, and every residual — a thing Pepsi does not protect — is stated as such rather than left to be inferred.

16.1. How to read this chapter

A security claim has three parts: an asset (what is worth protecting), an adversary (who wants it, and what they can already do), and a mechanism (what stands between the two). The chapter is organised the same way:

Two words are used strictly. Holds means the claim is enforced by a mechanism that the adversary in question cannot switch off. Residual means the adversary gets it, and the text says so on purpose.

16.2. Assets

Asset

Where it lives

The property that matters

Mail in flight

pepsi.workqueue (headers, state) and pepsi.workqueue_body (the body, shared by a message’s recipient rows), in the clear; deleted on delivery.

Confidentiality and integrity while queued; it must reach the recipient it was addressed to and nobody else.

Delivered mail

The recipient’s Maildir, the LMTP server, or the next MTA. Not Pepsi’s after delivery.

Pepsi’s part: deliver to the right mailbox as the right user, never to another’s — and, for a user with a client key, never file a message that arrived encrypted in a readable form (pepsi-stage-reencrypt).

Stored secure-link messages

pepsi.secure_message.ciphertext, sealed under a PIN-derived key.

Confidentiality against anybody who does not hold the PIN.

End-to-end private keys

crypto_identity.private_wrapped, AEAD-wrapped under the key-encryption key (KEK) in secrets.d.

Never disclosed; used only by the two crypto stages and pepsi-keys.

Domain signing keys and service secrets

The DKIM and ARC private keys, 0600 files of the pepsi-dkim account in its 0700 state directory, held by the signing daemon and left out of backups; the SRS key, the Pepsi-Origin key, the secure-link pepper, the list unsubscribe key, smarthost and LMTP credentials, OAuth tokens, the TSIG key of DKIM record updates, the API key of each managed-PKI domain’s CA account — each in its own secrets.d fragment.

Confidentiality; each readable only by the account that uses it.

Sending identity and reputation

What the keys above let one do: sign for the domain (DKIM, ARC), rewrite senders (SRS), vouch for mail as ours (Pepsi-Origin).

Nobody outside the pipeline may send mail that carries our domain’s authority; the server must not become an open relay or a backscatter source.

Per-user signatures

OpenPGP/S/MIME signatures pepsi-stage-encrypt makes with a user’s server-held key.

A signature as alice is made only on mail alice submitted.

Sponsored names

The managed PKI’s users (mpki_user): the given name and surname that a CA-issued certificate carries, which the organisation vouches for to the CA.

Integrity: a certificate names a person only when an administrator or the directory vouches for the name, or when the operator chose to trust display names (Certificates from a commercial CA).

Security indicators

X-Pepsi-Crypto, Authentication-Results, the [decrypted] / [verified] subject tags, and the state keys that other stages act on (state.signature_verified, state.spam, state.local_origin).

Integrity: a reader or a later stage may believe them.

Configuration and policy

pepsi.conf (0644, no secrets), pepsi.config_override, pepsi.settings, the whitelist.

Integrity: only the operator decides policy, and each user only their own part of it.

Correspondence metadata

Envelopes in the queue, mail_log, event_log, the whitelist, the peer-key cache, dns_address, mta_sts_policy, tls_session, list_confirmation, smime_capability (whose clients cannot read authenticated S/MIME), crl_cache and ca_issuer_cache (which CAs correspondents use), login_assignment (when each login changed owner), dmarc_report (which addresses send mail under the served domains, as other receivers report it); and, toward recipients, the submitting client’s address, machine name and software, which a submission listener keeps out of the message (RECEIVED_PRIVACY, The submitter’s address stays out of the message).

Confidentiality against outsiders; see What Pepsi does not protect for what is visible to whom.

Privacy toward third parties

What leaves the host on its own initiative: key-discovery lookups (DNS, WKD, VKS, LDAP), TLS reports, opt-in telemetry, and, for a managed-PKI domain, the address and name of each user it enrols, sent to the CA. Not blocklist queries: IP blocklists are downloaded whole, so no list operator learns which servers mail this host.

Disclose the minimum, and nothing the operator did not opt into.

Money

GNU Taler wallets driven by pepsi-helper-auto-pay; the merchant backend credentials of [pepsi-payments]; the CA account of a managed-PKI domain, which bills the organisation for each certificate.

A wallet is spent only by its owner or, automatically, within the budget the operator set, and only against a demand for mail we really sent. A certificate is ordered only for a user whom the domain’s settings enrol, and at most daily_limit new ones a day.

Credentials of the administrative surface

admin_account (Argon2id), api_token (digests), admin_session; the end users’ sign-in links and sessions (own_enrolment, own_session, digests); the second-factor secrets in otp_key (wrapped under the KEK); list accounts in list_user.

Not recoverable from the database; not replayable.

Availability

The pipeline as a whole.

Mail keeps flowing under hostile input; a failure defers rather than loses or discloses. See Availability.

16.3. Principals and how far each is trusted

Principal

Trust

The operator (root, or whoever may edit /etc/pepsi)

Fully trusted, and stated precisely: the operator configures the pipeline, holds every secret, and sees every message that passes through in gateway custody. No claim in this manual holds against an operator who modifies the server. The at-rest claims (wrapped keys, secure-link ciphertext, credential digests) hold against a passive reader of stored data — a stolen backup, a database-only administrator — never against somebody who controls the running system.

A database administrator without host root

A passive adversary for the purposes of this model: can read and change every table, cannot read secrets.d or the DKIM keys. What that yields is exactly An attacker who has the database — plus, being able to write, control of the queue and of every state key downstream stages believe.

The pipeline (the pepsi account and every stage it runs)

Trusted to process mail, and therefore part of what an attacker aims for. Every stage can read and rewrite every queued message, and can have messages DKIM-signed and ARC-sealed by pepsi-dkim within its policy; see A compromised component for what one compromised stage is worth.

The DKIM signing daemon (the pepsi-dkim account)

Trusted with the domain signing keys, and with nothing else: no database role, no queue, no other secret but the TSIG key of DNS_UPDATE = rfc2136. It treats every request on its socket as coming from a possibly compromised stage.

The greylisting milter (the pepsi-greylist account)

Trusted to answer “now or later?” for a recipient, and with nothing else: it sees the envelope (client address, HELO, sender, recipients) of every session an MTA asks it about, never a message, and its database role reaches only the greylisting tables, a read of the whitelists and an append to the audit log. It treats every question on its socket as coming from any member of the socket’s group.

Local shell users

Hostile to each other and to Pepsi. A user may submit mail as themselves (through sendmail, authenticated by SO_PEERCRED), manage their own whitelist namespace, read their own mailbox, and nothing else.

Mail-only users (SMTP submission, IMAP, no shell)

Hostile to each other. Their levers are submission (as the identities USERNAME_MAP allows them), the control addresses (pepsi-stage-edit-settings, the wallet self-service, the key commands) and whatever the operator lets them override for their own address.

Trusted relay hosts (MYNETWORKS, client certificates)

Trusted to submit mail as local origin. A compromised one is a compromised submitter for every address it may send as: the addresses SENDER_MAP binds it to — for a certificate under a CA, its own mailbox when the certificate names one. An unbound certificate is no submitter, and an unbound network outside loopback is a configuration on which ingress refuses to start; a loopback entry may send as every address. A network wider than one host bound to * is allowed as an explicit decision and warned about at every start.

Exchange Online tenants ([pepsi-ingress-exchange-online-*])

Trusted to relay as the domains their section lists, one message at a time, when the message proves the tenant: Microsoft’s tenant id, which Exchange Online writes on its way out, and a DKIM signature by the From: domain. Microsoft is trusted to write that id truthfully on every message that leaves its listed outbound addresses. A compromised tenant is a compromised submitter for those domains; another tenant is a remote sender.

Delegated administrators (API tokens and console accounts with a narrow scope, including own:<address>)

Hostile beyond their scope: a principal can never mint a credential stronger than itself (scope_escalation), and an own: principal reaches exactly one address. See The administrative API.

Console end users (a browser session minted by a link mailed to the address, [pepsi-admin] ENROL_STAGE)

Hostile beyond their address. The proof is control of the mailbox (plus the address’s second factor, when one is enrolled), and what it buys is own:<address> and nothing else. See Someone who can read a user’s mailbox.

List members, owners and moderators

Hostile beyond their lists. A separate account system (pepsi.list_user) that grants nothing on the administrative side, and vice versa.

The Mailman REST client ([pepsi-list] API_USER/API_PASS, e.g. a Postorius or HyperKitty front end)

Trusted with every list, its members and list accounts; nothing on the administrative side. Served only on a LIST_API listener that is TLS, a UNIX socket or loopback. See The GNU Mailman 3 REST API.

Remote senders

Hostile. Everything they send — envelope, headers, MIME structure, ciphertext, keys, Autocrypt headers, DSNs, payment demands — is attacker-controlled input.

Remote receiving MTAs

Untrusted for confidentiality unless TLS is authenticated (DANE or an enforced MTA-STS policy); see The network adversary.

Correspondents’ key sources (their DNS, WKD host, a VKS server, an LDAP directory)

Trusted exactly as far as the trust ladder ranks them (Key management). A domain can always speak for its own users.

The CA of a managed PKI (DigiCert CertCentral, one account per domain)

Trusted to issue a certificate for the request that it is sent, and with the address and name that the request states. It never receives a private key, and a certificate that it returns installs only when it names the order’s address and is over the order’s own key. Like every public CA, it can issue certificates for the domain’s addresses that nobody here ordered; that is a property of the public PKI, not of this integration.

External helpers the operator wires in (milters, the LMTP server, the smarthost, Taler wallets and exchanges)

Trusted with what the operator hands them: a milter sees the message in the clear, an LMTP server files it, a smarthost relays it. A milter that pepsi-ingress consults during the SMTP session also decides what is accepted, and may change what is stored within its ALLOW_ACTIONS (header and body by default, the envelope only when granted). It cannot make ingress relay for an unauthenticated client (a recipient it adds is held to the RCPT rule) or put an arbitrary reply on the wire (its reply text is checked); see Milters consulted during the SMTP session.

The maintainers of the crates Pepsi links, and of the toolchain

Trusted with everything, by construction: their code runs in every program, root and pepsi-crypto included. What limits the trust is that a crate enters or changes only through a recorded decision, and that a release can be rebuilt and compared (A compromised dependency).

16.4. Trust boundaries

Authority changes hands at a small number of places, and every mechanism in Security model sits on one of them:

  remote MTAs,        local users           browser / API client
  senders             (sendmail)            (operator, delegate)
     |                    |                          |
=====|====================|=========== B1: network ==|=================
     v                    v                          v
+--------------+  SO_PEERCRED           +-----------------------+
| pepsi-ingress|<- B2: submission       |      pepsi-httpd      |
|  (auth, SPF, |   identity             |  B6: scopes, CSRF     |
|  DKIM, DMARC)|                        +-----------+-----------+
+------+-------+                                    | setup_task
       | workqueue row                              v  (a request)
=======|===== B3: queue (pepsi.workqueue)   +-----------------------+
       v                                    | pepsi-setup apply     |
+---------------------+   B4: setuid/gid    |  (root; B7: re-checks)|
| stages as `pepsi`   |------------------+  +-----------------------+
| (dispatcher, ARC,   |                  |
|  SRS, dkim-sign ...)|                  v
+----+-----------+----+     +-----------------------------+
     |           |          | helpers: become the user    |
     | B5: key   | socket   | (maildir, .forward, wallet) |
     | custody   |          +-----------------------------+
     v           v
+-----------+ +------------------+
| encrypt / | | pepsi-dkim       |  DKIM/ARC keys in
| decrypt   | | (own account,    |  /var/lib/pepsi-dkim
| (setuid   | |  signs on        |  (0600, not backed up)
| pepsi-    | |  request, never  |
| crypto)   | |  hands out a key)|
+-----------+ +------------------+
  crypto_identity.private_wrapped + KEK in secrets.d

B1 — the network. Everything arriving is hostile until ingress has authenticated it, and even then only the verdict is trusted, never the content. Outbound, a hop is trusted only as far as its TLS is authenticated.

B2 — the submission identity. Ingress decides who submitted a message: SASL, a client certificate, MYNETWORKS, or SO_PEERCRED on the local socket. USERNAME_MAP then decides which From:/envelope identities that submitter may use, and SENDER_MAP the same for a network or certificate it binds (an unbound certificate authenticates nothing, an unbound network outside loopback is refused at start-up, a loopback network may use any, and a CA-issued certificate is held to the mailbox it names). A message from an Exchange Online tenant proves its tenant instead, per message, before it may leave for another domain. The same gate refuses a From: display name that names an address other than its own mailbox’s. This is the only place the question “may this person send as this address?” is asked.

B3 — the queue. Everything after ingress is one table that every pipeline stage may read and write. The verdicts ingress recorded (state.auth, state.local_origin) and those later stages add (state.spam, state.signature_verified) are unauthenticated data inside this boundary: they are believed because only pipeline code can write them. That is the design’s largest single trust assumption, and it is why A compromised component treats a pepsi stage as equivalent to the queue.

B4 — the helpers. Three pieces of work need to be a specific local user (write a Maildir, act on a ~/.forward, drive a wallet). Each is a small setuid-root helper reachable only through a setgid program that the pepsi account runs (the stage, and for the Maildir helper also pepsi-quota), and it drops fully to the target user before touching anything the user owns.

B5 — key custody. Only pepsi-crypto holds both the wrapped private keys and the KEK. The crypto stages cross this boundary on every message; nothing else in the pipeline does. The domain signing keys sit behind a boundary of the same kind: only pepsi-dkim can read them, and the DKIM-signing and ARC stages cross it by asking the daemon’s socket for a signature over a header block, which it makes only for a served domain, a From: aligned with d= and, for ARC, the ARC_DOMAIN. Key use crosses the boundary; the keys do not.

B6 — the administrative surface. Every request is authenticated (SO_PEERCRED, bearer token, or password + session) and authorised against the endpoint’s one scope.

B7 — the privileged applier. The web tier holds no root authority. It records what should happen in pepsi.setup_task; pepsi-setup apply, running as root and started separately, re-validates each task against the requester’s authority and performs it. Removing the pepsi-httpd-admin package removes the applier, which makes this boundary absolute.

B8 — the greylisting socket. pepsi-greylist answers whoever may connect to /run/pepsi-greylist/milter.sock: a member of the socket’s group (pepsi-greylist; pepsi-ingress is one, a local Postfix may be made one), or anyone who reaches an inet: socket. A client of the socket chooses the client address, sender and recipient it reports, so it can make the daemon remember triplets, pass a sender of its choice for later sessions, or learn whether a sender has written to a recipient before. It cannot reach the queue, and the worst it can do to mail is delay it or, by making the daemon fail, let it through ungreylisted. The answer is advice to the MTA: an MTA that does not ask, or ignores the answer, accepts the mail.

16.5. Adversaries

16.5.1. A passive network observer

Can: read traffic between Pepsi and other MTAs, and between clients and Pepsi.

Stopped by: opportunistic STARTTLS in both directions, TLS on submission (required, except on the local UNIX socket), HTTPS on the portal and the console. End-to-end encrypted messages stay encrypted on the wire whatever the transport. A TLS client certificate, which names its holder, is requested only from a client that negotiates TLS 1.3, where it is encrypted, unless the operator sets TLS_AUTH_CLIENT_TLS12 on the listener for devices that speak nothing newer.

Gets anyway: the transport metadata — which hosts talk, when, and how much — and the plaintext of any hop where the peer offers no TLS at all. The length of an end-to-end encrypted message is visible only to within its padding bucket (The length of an encrypted message).

16.5.2. An active network attacker

Can: intercept, modify and drop traffic; strip STARTTLS; present their own certificate; and, with a lying resolver on the path, forge DNS.

Stopped by: only what the deployment and the peer have configured. With the defaults, an active attacker can downgrade an outbound hop to cleartext or intercept it with their own certificate unless the receiving domain publishes an MTA-STS enforce policy (honoured by default) or DANE TLSA records. Such records make STARTTLS mandatory, so the hop cannot be downgraded to cleartext, and under the default DANE = strict a certificate that matches none of them defers the message (and is reported as tlsa-invalid when TLSRPT is on). An operator who sets DANE = warn opts out of that refusal: a mismatch is then only logged. A smarthost is the exception: its certificate is checked against the system roots (TLS_VERIFY, on by default), or against its own CA alone when TLS_CA_BUNDLE names it, and even under DANE = warn a TLSA mismatch falls back to that check rather than replacing it. TLS_VERIFY = no removes that exception: the relay then hands its AUTH credentials and every message to whoever intercepts the connection. A message whose originator tagged it REQUIRETLS (RFC 8689) is protected whatever the recipient publishes: it leaves only over validated TLS to a DNSSEC- or MTA-STS-validated next hop that promises the same, or it bounces, headers only (Require TLS for one message (RFC 8689)). The attacker can turn such a message into a bounce, never into cleartext. A TLS-Required: No header makes the recipient’s policy advisory for that one message. Only the originator controls this header, so the choice is the originator’s, not the attacker’s: Pepsi reads the field only from the message as it arrived, and a stapled revoked status still refuses a validating session. A browser the attacker redirects to an SMTP port (ALPACA) is refused at the TLS handshake when it offers only HTTP protocols by ALPN, and at its first HTTP line otherwise. See The network adversary for the hardened profile that closes the rest.

Gets anyway: a denial of service, always. With DANE strict an attack is converted into a deferral rather than a disclosure — the best available answer, not a complete one. An attacker who controls the route to this host, or its DNS, while Let’s Encrypt validates a name can obtain a trusted certificate for our MX or openpgpkey host, unless the operator publishes the CAA record pepsi-setup run suggests (with accounturi, in a DNSSEC-signed zone); pepsi-setup check reports whether one is published (Who may obtain our certificates).

16.5.3. A remote sender

Can: send any bytes to port 25: forged From: headers, malformed MIME, hostile ciphertext and signatures, Autocrypt and Autocrypt-Gossip headers, forged DSNs, forged payment demands, and forged Pepsi security headers.

Stopped by:

  • Parsers treated as the attack surface. Every stage parses hostile input; the most sensitive parser, the CMS/S/MIME code in pepsi-crypto, is fuzzed (Test Suite), and so is the armor and packet path (Memory corruption in ASN.1, CMS, certificate and OpenPGP parsers). A message that crashes a worker is struck out after three attempts rather than retried for ever (Invalid, expired or old signatures reported as valid).

  • Forged indicators are removed. Every X-Pepsi-* header is stripped from inbound mail before the decrypt stage writes its own. Anything at the front of the subject that would display as a security indicator is removed before our tags are added, judged by what a mail client renders: encoded-words are decoded, and look-alike, invisible and reordering characters cannot disguise a tag (look-alikes are judged with the full UTS #39 confusables data; Forged security tags in the Subject bypass gateway sanitisation, Security status spoofed in-band in message body or headers).

  • Sender addresses are read the way a mail client reads them. Comments and quoted strings in a From: field cannot make the key lookup, the signer binding or the submission identity check see a different address than the one the recipient sees (Ambiguous From headers checked as one address and displayed as another).

  • Protected content stands alone. Before anything is decrypted, a message that carries ciphertext next to other content is reduced to the ciphertext, with the other parts moved into attachments that no client renders inline, and one that carries signed content next to unsigned content is reduced to the signed content (ISOLATE_ENCRYPTED, ISOLATE_SIGNED). A captured ciphertext wrapped in attacker HTML therefore cannot be exfiltrated through a client that decrypts it (EFAIL direct exfiltration: plaintext spliced into attacker content), and a valid signature on one part cannot lend its tag to a stranger’s text (Signature spoofing via partial signing and MIME/CMS wrapping): beside a signed plaintext, moved parts not signed by the same key are dropped.

  • Another Microsoft 365 customer cannot relay as the organisation. Every Microsoft 365 tenant sends from the same Exchange Online addresses, so no address list can admit only the organisation’s tenant. A message from those addresses may leave for another domain only when it carries exactly one X-MS-Exchange-CrossTenant-Id field naming a configured tenant and a verified DKIM signature by its From: domain (Exchange Online: the tenant proof). A second tenant’s claim to the organisation’s id arrives next to Exchange’s own field, which names the second tenant, and a signed message sent again through another tenant fails the same way; outside Microsoft’s listed addresses the header proves nothing and is not asked for. The residual is Microsoft: the rule holds as long as Exchange Online writes the sending tenant’s id on every message that leaves those addresses.

  • Opening a message tells its sender nothing, for a reader who asks. With DEFANG = on for their address, every reference an HTML or CSS part would load by itself is removed before the message is filed, decrypted content included (Remote references in HTML), so neither a tracking pixel nor a decrypted part’s <img src="... reaches the sender (Remote content and personalised links reveal opens, device and location, EFAIL direct exfiltration: plaintext spliced into attacker content). Parts a signature covers are left to the client’s own blocking, and a link the reader follows is the reader’s act. Off by default.

  • Decrypted content is not returned to the sender. A DSN about a message that arrived encrypted quotes only its addressing fields, whatever RET asks for, and automatic replies do not quote its subject. Re-sending a captured ciphertext under one’s own envelope sender and arranging a bounce therefore returns neither the plaintext nor whether it opened (Bounces after gateway decryption reveal decrypted content, CBC padding and format oracles against unauthenticated S/MIME). The plaintext copy that an alias or ~/.forward sends off-site leaves with a forward return address, so a remote host that bounces it later bounces to Pepsi, which answers the sender with a DSN of its own that quotes nothing of such a message and drops the remote report (Forwarding addresses in delivery reports). For the same reason no key discovery is started for a signature inside content decrypted from an AES-CBC container, and a decryption failure is never bounced by default, and under bounce-if-unproblematic only for an integrity-protected ciphertext; when it is bounced, the DSN never says why decryption failed. A bad signature (ON_BAD_SIGNATURE = bounce) or a missing client key (ON_NO_CLIENT_KEY = bounce) in content from an AES-CBC container drops the message rather than bouncing it, so no setting answers whether a modified CBC ciphertext opened. The stages after decryption follow the same rule for such content: a milter rejection, a retry that runs out and pepsi-failure-bouncer drop the message, the language gate delivers it marked instead of bouncing it, no signature from it whitelists the sender (which decides whether pay-to-send or confirm-to-send answers), and no reply is written in the language detected in it. What the sender can still measure is processing time.

  • Markup from a malleable ciphertext is not rendered. A plaintext from an S/MIME container without integrity protection that no signature inside it covers is delivered as plain text, or by configuration not opened at all, so a CBC gadget rewrite has no channel out of the recipient’s client (Protected content stands alone).

  • One From: field. A message with more than one From: field is refused at ingress, so the address that is checked is the address that is shown.

  • Harvested keys cannot impersonate our users. Keys learnt from inbound mail land on the bottom rungs of the trust ladder, and for any address we hold an identity for, our own key pre-empts every cached key (lookup_own_first). A forged From: alice@our-domain carrying an Autocrypt: header therefore cannot redirect encryption for Alice or make a signature verify as hers (Weak binding between signer certificate or key and the From address).

  • Gossip is bounded. A gossiped key is learnt only from mail that arrived encrypted and only about To:/Cc: addresses; it is never learnt about our own users, never displaces a better key, and can never produce a valid signature verdict. A gossiped key leaves the bottom rung only when its owner advertises the same key themselves, which promotes it to the inbound rung (audited as key.peer.promote, never as a rotation) and still cannot produce valid. The “arrived encrypted” test relies on the decrypt stage’s record, which an armored message carrying no encryption layer may satisfy (OpenPGP integrity protection (MDC) missing, strippable or not enforced).

  • A signed claim beats an unsigned one. A key learnt from a message whose aligned DKIM signature passed and covered it sits on the inbound-signed rung, as does an S/MIME certificate that signed a message DMARC authenticated, and no key from an unsigned message can replace it; forging a correspondent’s From: redirects their mail only while nothing that their domain signed has vouched for a key. Encrypting to any harvested key also asks discovery, in the background, whether the owner published one.

  • An S/MIME certificate is learnt only from its own signature. A certificate is harvested when a signature in the message verifies under its key, never because a SignedData merely carries it.

  • Rank before protocol. The encrypt stage takes the best-ranked key of either protocol; PREFER decides only between equal rungs, so a key planted in one protocol cannot outrank a better-sourced key in the other, which the per-protocol conflict rule would never have compared it with.

  • A key rotation is never silent. Replacing a correspondent’s harvested key with a newer one (Autocrypt’s newest-wins) writes an audit row in the same statement and mails the local recipients of the message that caused it; under ACCEPT_ROTATION = expired it is refused while the stored key is alive. This limits, and does not prevent, the key replacement of Undetectable key substitution or equivocation by key directories and CAs.

  • A forged DMARC report decides nothing. A DMARC aggregate report counts towards the p=reject verdict of pepsi-setup check, pepsi-status and the console only when the mail carrying it passed DMARC or SPF; any other report is stored marked and shown as such, and cannot shadow the authenticated copy of the same report. A sender can still report what it likes about its own sending (DMARC aggregate reports).

  • A delivery report does not say where a user’s mail goes. A DSN about a recipient that an alias or ~/.forward produced names only the address the sender used, with a generic diagnostic (Forwarding addresses in delivery reports). So does the answer to a report that the forwarding target’s own server sends: because the copy left with a forward return address, the report comes back to Pepsi and is not passed on.

  • Loops are broken. Null-sender mail is never bounced, auto-replies follow RFC 3834 suppression (pepsi-common::autoreply), .forward chains carry a loop guard, hop counts are capped, and a message that has passed through this host’s ingress MAX_SELF_HOPS times is refused.

  • No backscatter. An address at a served domain that nothing on the host vouches for is refused at RCPT (VERIFY_RECIPIENTS), and a bounce goes only to an envelope sender the message authenticated (BOUNCE_UNAUTHENTICATED), so a forged sender is not mailed on the spammer’s behalf. The exception is a temporary DNS error about the sender’s own domain: during an outage of that domain’s DNS or of this host’s resolver, forged mail can draw a DSN. What the host does reflect – a DSN, an alias or .forward copy, a list’s fan-out – leaves after a random hold of up to REFLECTION_HOLD_MAX (30 s), and no session may be parked longer than SESSION_TIMEOUT (30 m), so reflections from many hosts cannot be timed to land on one victim as a pulse. No automatic reply goes to a sender that failed SPF or DMARC outright (a fail verdict); one that merely could not be confirmed (softfail, neutral, none, a temporary error) is still answered unless the operator sets REQUIRE_AUTHENTICATED on the responding stage, which answers only a sender that passed. Either way, an automatic reply quotes nothing the sender wrote (display name, subject, command lines) unless the sender passed SPF or DMARC or submitted locally, so a forged envelope sender draws fixed text, never text of the forger’s choosing under this host’s DKIM signature (Provider notification workflows send attacker-controlled mail).

  • The payment gate trusts only our own proof for our own mail. Mail that this deployment injected itself, with a human envelope sender (the secure-link notifications), passes pepsi-stage-anti-spam only with a Pepsi-Origin stamp bound to its envelope recipients and a tracked nonce, so a recipient of such a stamp can reuse it only for mail to themselves; an ordinary outbound stamp, which every correspondent holds, never exempts.

  • A bounce passes the spam gates only with our proof. A null-sender message, which neither gate may ask to pay or confirm, passes pepsi-stage-anti-spam and pepsi-stage-secretary only with a verifying Pepsi-Origin field and a tracked nonce; without one it goes to the paywall’s BOUNCE_TARGET_STAGE or the secretary’s unchallengeable path. An anti-spam section without that option forwards it, and with proof of origin switched off nothing is proven; pepsi-setup warns about both. A correspondent can reuse an ordinary stamp from our mail on a forged bounce for two weeks.

  • Payment demands are checked. pepsi-stage-auto-pay pays only for mail it can prove we sent (the Pepsi-Origin HMAC), and only within the per-message budget and the paying wallet’s daily one (MAX_TOTAL_PER_DAY, required wherever MAX_TOTAL is not zero). A correspondent can still price each demand up to what those budgets leave; bounding the loss is the daily limit’s job, not the proof’s.

  • Our signature does not vouch for a forgery of our domain. A message that arrived from outside with a From: at a domain we sign for, and that authenticated neither by DMARC nor by an aligned DKIM signature, is forwarded without our DKIM signature, so forwarding it does not make it pass DMARC elsewhere. Its SRS envelope sender is at SRS_DOMAIN, which pepsi-setup requires to be a dedicated domain not aligned with any served one, so the SPF pass it earns does not align either; an operator who sets ALLOW_ALIGNED_DOMAIN keeps that route open unless DMARC is enforced at ingress.

  • A message we signed is not a lasting licence. Every DKIM signature Pepsi makes expires seven days after signing (x=, SIGNATURE_EXPIRATION_DAYS; 0 turns it off), so a correspondent who keeps a signed copy can replay it to other recipients only within that week; the signature binds no envelope recipient (The lifetime of our DKIM signatures). With rotation on ([pepsi-dkim] ROTATION_DAYS) the key itself is retired after a while, and with PUBLISH_RETIRED_KEYS its private half is published, so an old signature stops proving who made it (Rotating DKIM keys).

  • Authentication is enforced only through DMARC, and only where the configuration says so. Inbound SPF, DKIM and DMARC are fail-open: only a definite DMARC failure under DMARC_ENFORCE rejects. The wizard writes DMARC_ENFORCE = yes for a new installation; the compiled-in default is off. With a pepsi.conf that does not mention it, or after an operator switched it off, Pepsi therefore delivers a spoofed message with an honest Authentication-Results rather than refusing it; pepsi-setup warns about the first and, while a served domain publishes p=reject, the second. With enforcement on, every domain a From: names is checked, and a message without a From: address is refused, so neither shape is a way around it. The one override is ARC: a failing message whose chain validates and was sealed last by a domain in [pepsi-ingress] ARC_TRUSTED_SEALERS is accepted, recorded as state.auth.arc_override. The list is empty by default, the operator curates it, and a chain sealed last by anyone else proves nothing — so the override is worth exactly the trust placed in each listed forwarder, and a listed forwarder that relays forgeries unexamined relays them here. A From: whose display name names an address other than its own is delivered too, but marked with X-Pepsi-Warning and state.auth.display_name_mismatch, and so is one carrying bidi controls or invisible characters that can make it render as something else.

  • A list or a whitelist does not launder a forged sender. A mailing list re-signs and re-sends every post under its own name, so a post whose From: failed DMARC is held for a moderator on every list with hold_dmarc_failures on — the default for lists Pepsi creates, whatever the domain’s published policy and whether or not the poster is a member; lists imported from GNU Mailman start with it off, as they behaved there (Forwarders, relays and lists launder spoofed mail into authenticated mail). A whitelist row keyed on an address can demand that the address was authenticated: dkim_required (aligned DKIM), dmarc_required (any aligned DMARC pass, aligned SPF included) or signature_required. Rows written automatically demand the strongest level the correspondent showed — pepsi-stage-secretary writes dmarc_required for a sender whose held mail passed DMARC but not DKIM, and pepsi-stage-auto-whitelist writes it by default — so a forged From: naming a correspondent skips the payment and confirmation gates only through a row the operator or the user wrote without a requirement (Sender whitelists bypassed by a forged From address).

  • Ambiguous MIME reaches no filter as it arrived. A message whose MIME structure has no right reading (an empty boundary, a NUL in a MIME header, conflicting duplicate Content-Type or Content-Transfer-Encoding fields, an encoded-word boundary) is refused at DATA; one whose structure the standards say how to read (an unknown transfer encoding, whitespace after a quoted-printable soft break, non-alphabet base64 characters, a missing close delimiter, identical duplicate fields) is rewritten to that reading, outside signed and encrypted parts, before anything after ingress parses it. The rewrite happens after SPF/DKIM/DMARC and before the ARC seal, so the verdicts stand and the seal covers what is stored. MIME_ANOMALIES = log is the opt-out. Shapes outside those classes still reach the filter and the client as they arrived (see Ambiguous MIME is settled at the boundary).

  • What is delivered unproven is marked. A message from outside whose From: is at a served domain with no aligned pass behind it, one whose Sender: names a served mailbox nobody authenticated, one whose From: clients may read as different authors, and one whose DMARC failure was recorded but not acted on, carry an X-Pepsi-Warning naming the reason and the [external] tag at the front of the subject, so the reader sees what the Authentication-Results field already said (What a security indicator means). The tag cannot be forged: every inbound subject has rendered copies of it removed first, and a message without a subject gets one.

Gets anyway: code execution in a stage if a parser bug exists (see A compromised component); a message in the recipient’s mailbox with a forged From: if the operator does not enforce DMARC — marked [external] and X-Pepsi-Warning, which a reader may still overlook; a key they chose used to encrypt mail to an address we hold no identity for, at the trust-on-first-use rungs, unless MIN_TRUST excludes them. This includes replacing a correspondent’s harvested key with a newer one under a forged From:, which is audited and announced to the recipients but not prevented, unless ACCEPT_ROTATION = expired is set or the stored key came from a message that the correspondent’s domain DKIM-signed; an unsigned forgery can never displace such a key. They also learn, from the RCPT answers, which addresses at a verified domain exist — as from any MTA that refuses unknown users — at ten guesses per connection (MAX_INVALID_RECIPIENTS). The address may be one of ours: a served user that we hold no identity for, which a forged From: can reach whenever DMARC is not enforced on our own domain. The planted key is not prevented there either, but it is not invisible: pepsi-keys peer unclaimed lists every served address whose encryption a harvested or gossiped key decides, as a worklist for the operator to confirm and convert into identities (Finding the users who bring their own key).

16.5.4. A local shell user

Can: run every world-executable program, connect to world-accessible sockets, and read world-readable files — including pepsi.conf, which is why it holds no secrets.

Stopped by:

  • Submission as themselves only. The local submission socket may be mode 0666 because ingress takes the caller’s identity from SO_PEERCRED and feeds it to USERNAME_MAP; a user can only send as the identities mapped to their login.

  • No privileged program is reachable from an ordinary account, except pepsi-whitelist, which is deliberately world-executable and enforces its own per-login namespace (and pepsi-keys, where a site chooses to make it setuid pepsi-crypto; it then confines each caller to their own identities, Key management). The other setuid/setgid programs are mode 2550 or 4750, executable only by pepsi or a dedicated group — and 2550 rather than 2755 is the whole defence: world-execute would give every account the group that gates a setuid-root helper.

  • Setuid programs sanitise before trusting. pepsi-whitelist drops to the invoking user immediately, clears the environment variables that steer the configuration and libpq, refuses -c, and re-raises privilege only around its database connection. Mailbox parsing happens in a separate process that can never regain the privilege (setresuid on all three ids).

  • Helpers become the user fully. The Maildir, .forward and wallet helpers set every uid and gid to the target user and refuse root, so a user’s own files are touched with that user’s authority and no other. Which program a helper runs is not the caller’s to choose: the wallet helper runs only the taler-wallet-cli fixed when it was built, refusing it unless root owns it and nobody else can write it or a directory above it, and only as a local user (a uid at or above UID_MIN) or an account whose primary group is the helper’s own. Nor is the environment: the .forward and wallet helpers build the child’s environment from the target’s passwd entry and a fixed PATH, inheriting nothing from the caller.

Gets anyway: the configuration topology (served domains, the pipeline graph, host names) from the world-readable pepsi.conf.

16.5.5. A mail-only user

Can: submit mail through an authenticated channel, send control messages to the control addresses, and use the self-service web pages their deployment enables.

Stopped by: USERNAME_MAP (which addresses they may send as, and on which they may register a key); the control stages keying every action on the authenticated envelope sender of a state.local_origin message; the EDITABLE_STAGES allowlist, which bounds what their overrides may touch (see Per-address settings are a trust boundary); and, for a user who is also a Unix account, the helpers acting with that account’s authority only.

Gets anyway: control over the handling of their own mail within what the operator made editable — including, for an editable stage, the right to route their own copy of a message somewhere other than the operator’s default.

At a managed-PKI domain, their first message registers them as a user, with the name that their mail program puts in the display name. Stopped by: under the default header_names = approve nothing is ordered for that name until an administrator confirms or corrects it (Certificates from a commercial CA). Gets anyway: under header_names = trust, a certificate for their own address under a name of their choosing, sponsored by the organisation and paid for by it, within the domain’s daily limit.

16.5.6. Someone holding a user’s mail password

Can: everything the mail-only user can, as that user: submit mail with a bound From:, send control messages, and usually read the mailbox over IMAP too, since the same password opens it.

The key-registration road, and what closes it. Submitting as a user is what registers a key as theirs (a submitted Autocrypt: header, or the register command), so a stolen password is enough to make the attacker’s own key the address’s public face: correspondents’ future mail is then encrypted to it, and signatures made with it verify as the user. The “a new key was registered” notice is a partial mitigation only: whoever holds the password can also read the mailbox that the notice lands in, and delete it.

A user who enrols a second factor (otp enroll, see Key management) closes that road. From then on, every change to their keys that a user can make needs a current six-digit TOTP code from their authenticator app: a key-registration or retirement command by e-mail; generating, registering or revoking a key, or changing its publication, key-server upload or primary flag, in the web console under own:<address>; and an unprivileged pepsi-keys. Replacing or removing the second factor itself needs a code too, and an ordinary message’s Autocrypt: header registers nothing at all.

Stopped by (with a second factor): the code (RFC 6238, a 30-second step, ±1 step of skew); replay protection (a code is accepted once, for a step later than the last one used); a lock after ten consecutive wrong codes that only the operator clears (pepsi-keys otp reset, DELETE /api/v1/otp/{address}); and custody — the secret is wrapped under the key store’s KEK and the otp_key table is granted to pepsi-crypto alone, so neither pepsi-httpd nor an ordinary stage can read a secret, reset a counter or delete an enrolment.

Gets anyway:

  • Without a second factor, everything above. Nothing forces one; it is the user’s choice, and until they make it the notice is the only mitigation. Pinning a correspondent’s key (pin), which changes what every user’s mail trusts, is refused without one: a password alone never reaches it.

  • The first enrolment. Enrolling needs no code (there is none yet), so an attacker who gets there first owns the second factor and the user needs the operator to reset it. The enrolment reply — which carries the secret — is sealed to the user’s own key when they registered one; without one it lands in the mailbox in clear, and a later thief of the password who finds it undeleted has both factors: the reply says to delete it, carries an Expires: header, and its secret does nothing until confirmed with a code within OTP_CONFIRM_WINDOW.

  • A denial of service on self-service key management. Ten wrong codes lock it, which an attacker can always cause; the operator’s reset is the remedy, and the lock never affects mail delivery or encryption.

  • Reading the mailbox, and sending mail as the user: a second factor guards neither.

  • Payments, up to the daily limit. Mail sent as the user to a pay-to-send gate the attacker controls draws payment demands that pepsi-stage-auto-pay settles for mail it provably originated. Each is bounded by MAX_TOTAL, and all of them by MAX_TOTAL_PER_DAY per paying wallet, which a stage with a non-zero MAX_TOTAL must set or refuses to start; neither limit can be raised by a control message, which the same password authenticates. The loss is at most the daily limit for each day the password stays stolen.

16.5.7. Someone who can read a user’s mailbox

Where sign-in by e-mail is switched on (Signing in by e-mail), reading a mailbox is itself a credential: a link mailed to the address opens a console session holding own:<address>. The proof is exactly control of the mailbox, which is also what every password-reset mail on the Internet relies on. So whoever reads the mailbox (with a stolen mail password, a forwarding rule they planted, a backup of the mail store) can obtain the principal.

Can: request a link for any address, and complete one only for a mailbox they can read; then, as own:<address>, read that address’s own identities, correspondent keys and mail log, and ask for the key operations an owner may ask for (publication and primary-key changes included).

Stopped by: the link itself – 256 random bits stored only as a digest, working once, for 30 minutes by default, for at most five submissions, and replaced by the next one mailed to the address; the requester never sees it, and its origin is the configured ENROL_URL, never the request’s Host, so a requester cannot have somebody else’s link sent to a host of their choosing. The address form answers identically, and before any lookup, whether or not the address is served, so it is no directory of who has an account; a per-address budget (three links an hour by default) and a per-client one bound how much mail the form can make the server send. With a second factor enrolled, the link alone is not enough: the session is minted only once the privileged applier has accepted the address’s current TOTP code (confirm-enrolment, checked with the same replay protection and ten-failure lock as every other code), and every key change the session then asks for needs a code again. With a security key registered for the address, the link alone is not enough either: the confirmation asks for an assertion by the key, bound to that link’s own challenge, and a TOTP code stands in only where REQUIRE_WEBAUTHN does not name users and the applier reports having checked one.

Gets anyway:

  • Without a second factor, an own:<address> session for every mailbox they can read – and with it what Someone holding a user’s mail password already gets: registering their own key as the user’s by a key task, exactly as they could by mail.

  • A lock on the second factor. Wrong codes at the confirmation count towards the ten-failure lock, as wrong codes by mail do; the operator’s reset is the remedy.

  • Nothing beyond the address. The session can never hold another scope – own_session stores an address, not a scope list – and a compromise of pepsi-httpd itself could already write sessions of either kind, so this adds no capability to that adversary (A compromised component).

16.5.8. A delegated administrator

Can: whatever the scopes on their token or account allow — for example queue:read without queue:write, or own:<address> for one address.

Stopped by: each endpoint’s single declared scope, enforced from the same table that the OpenAPI document is generated from; scope_escalation on minting a credential; and, for own:, a re-check of the address on the endpoint and again in the applier for every privileged task.

Gets anyway: the data their scope reads. queue:read sees envelopes and state (never headers or bodies — the console’s queries do not select those columns), logs:read the correspondence graph, keys:read every public key and the managed PKI’s users and orders. keys:write also changes the managed PKI’s settings and users: it decides which certificates the organisation pays for and whose names they carry, the daily limit included. It never reaches the CA credential, and an own: principal reaches none of it.

Somebody guessing or holding a console account’s password becomes that delegated administrator, within the account’s scopes. Stopped by: a password that is at least twelve characters, not on the shipped list of common passwords and not the account’s name (checked wherever one is set); sign-in limits per minute by account and by source (LOGIN_RATE_LIMIT, 10) and a daily ceiling on failed sign-ins per account from all sources (LOGIN_DAILY_LIMIT, 100); and, for an account that enrolled one (pepsi-keys otp enroll --console), a TOTP code checked by the setup applier, which the web tier cannot open. Gets anyway: without a second factor, a guessed or stolen password is the account; with one, a guesser who finds the password learns that it is right (the answer waits for the applier), but gets no session without the code, and can trigger the code’s ten-failure lock. An account with a WebAuthn security key is in the same position: a correct password is answered with the key’s challenge, which tells the guesser that it was right, but the guesser gets no session without an assertion by one of the account’s keys. Anybody who knows an account’s name can use up its daily ceiling and so refuse its password sign-ins until the allowance refills; the local socket and bearer tokens are unaffected, which is the operator’s way back in.

16.5.9. A phishing proxy (adversary in the middle)

A look-alike site with a valid certificate that relays the genuine sign-in pages to the victim and the victim’s input to Pepsi: the reverse-proxy phishing kits that defeat one-time codes.

Can: collect whatever the victim types — a console or list password, a TOTP code, a secure-link PIN, a mailed sign-in link the victim follows through it — and replay it within its lifetime, keeping the session cookie that results.

Stopped by: a WebAuthn security key on the account (Security keys (WebAuthn)). The key signs the origin the browser is actually on and the hash of this server’s RP id, neither of which the page chooses; Pepsi accepts an assertion only for the configured origin ([pepsi-admin] CONSOLE_URL, [pepsi-list] BASE_URL) and RP id, for a single-use challenge it issued to that account, so an assertion obtained on the proxy’s origin verifies nowhere. Once an account holds a key, a sign-in needs it (or, where TOTP may stand in, the code — see below); under [pepsi-httpd] REQUIRE_WEBAUTHN only the key does.

Gets anyway:

  • Accounts without a key, and accounts whose TOTP code may stand in for their key: the code is relayed like any other input, so the proxy obtains the session. Requiring keys (REQUIRE_WEBAUTHN) for a kind of account closes this for it.

  • The secure-link portal, whose recipient has no account and no authenticator: a proxy the recipient reaches receives the PIN and reads the message.

  • A mailbox it can read. Sign-in by e-mail trusts the mailbox; a key on the address stops a proxy that only relays the link page, but not somebody who also holds the key.

  • The password, for an account with a key: the second step reveals that it was right, and it is the first factor elsewhere if it is reused.

A session cookie obtained some other way (a stolen cookie, a phished TOTP sign-in) cannot be turned into a lasting foothold on an account that has a key: adding another key needs an assertion by an existing one.

16.5.10. Somebody holding a copy of the database

A backup, a replica, an SQL-injection foothold on a read path. An attacker who has the database lists it in full. In short: gets the queued mail in the clear and all metadata; does not get any private key (wrapped under a KEK outside the database), any secure-link body (PIN and pepper both absent, Offline guessing of weak password hashes, key passphrases and derived keys), or any usable credential (salted Argon2id and digests, Offline guessing of weak password hashes, key passphrases and derived keys; a hash made with older parameters is replaced at its next use, A moderator password hash is upgraded when it is used for a list’s moderator password).

Somebody who can write the database, as the schema owner or the pipeline role, additionally controls the queue and the state keys, and with them everything that, as B3 says, the pipeline believes. The pipeline role cannot rewrite what an identity is (its public half, fingerprint, address, protocol or purpose), only its use flags; the schema owner can, and a public half replaced together with its fingerprint is then served by the Web Key Directory until noticed, while the identity itself stops opening, because its wrapped private half is bound to the fingerprint (The private-key custody boundary).

16.5.11. Somebody holding the configuration or a secret

pepsi.conf is reconnaissance. Each secrets.d fragment is exactly one capability: the SRS key forges SRS addresses, the Pepsi-Origin key forges “we sent this” (and so makes auto-pay pay a demand), the pepper removes one of two factors from the secure-link key, the KEK opens the wrapped keys if the attacker also has the database. The TSIG key of [pepsi-dkim] DNS_UPDATE = rfc2136 changes whatever records the DNS server lets that key update: confined to the _domainkey names, it can publish a DKIM key of the attacker’s own, which is the domain’s signing authority. A managed-PKI credential (secrets.d/mpki-<domain>.secret) is the API key of that domain’s CA account: it orders certificates that the organisation pays for, and revokes the users’ certificates, until it is revoked in the CA’s portal. Since every key is generated here, it yields no user’s private key, but a certificate that it orders over an attacker’s own key, in a name that the organisation’s account may sponsor, is one that correspondents trust as much as the real one. A backup holds no DKIM key, since /var/lib/pepsi-dkim is left out of it. Only root has write access to pepsi.conf, because the file names the programs that the pipeline runs. The database overlay cannot name them: it refuses the options that name an executable and accepts a stage’s PROGRAM only as a bare pepsi-stage-* command, so its writers control the pipeline graph and the stages’ options but not which code runs (Command injection and XXE in mail gateway management interfaces). See An attacker who has the configuration file.

16.5.12. A compromised component

The realistic serious case: a parser bug gives code execution in one process. Each account’s reach is bounded by its operating-system identity and its database grants (The privilege split). Within an account, the processes that hold long-lived secrets (pepsi-httpd, pepsi-keys, pepsi-setup apply, pepsi-config export/import, the setuid crypto stages) are non-dumpable: another process of the same uid cannot ptrace them or make them leave a core file (A process of the same account). What such code gets is what the account’s files and database role give it, listed below.

Compromised

Gets

Does not get

A pepsi stage (most of them, and the dispatcher)

The whole queue: read, change, redirect, delete, or inject messages. Every state verdict. The settings, whitelist and peer-key cache. DKIM signatures and ARC seals for every served domain while it runs: it can ask pepsi-dkim’s socket directly, or rewrite a queued message’s From: and let pepsi-stage-dkim-sign sign it. And — by rewriting a queued submission’s From: before pepsi-stage-encrypt sees it — a per-user signature from any local user who has an identity, and the same rewrite registers a sender at a managed-PKI domain, whose name then waits for approval under the default policy (Certificates from a commercial CA).

The DKIM and ARC private keys, so signing as the domain ends when the stage is fixed, without a rotation; a DKIM signature whose From: is not aligned with its d=. Any private end-to-end key or the KEK; the secure-link ciphertext column; write access to the configuration overlay; root’s task queue; the administrative credentials and end-user sessions; the second-factor table; write access to the CRL cache; the managed PKI’s tables and CA credentials; another Unix account.

pepsi-stage-encrypt / -decrypt (pepsi-crypto)

Everything above, plus every private end-to-end key and the KEK: it can decrypt all inbound mail to server-held keys and sign as any identity, and it can carry the keys away (Mail appliances store secrets world-readable or unprotected). Also the managed PKI’s tables and CA credentials, which order and revoke certificates that the organisation pays for.

Keys whose private half the user keeps in their own client (custody = client).

pepsi-ingress

Every message as it arrives, before any stage; the SRS key; the TLS key of the listener; every mailing list’s address (the recipient check). It decides B2, so it can admit a message as any local submitter.

Any message already queued (its database role may add to the queue and read nothing of it); settings, whitelists, keys; any private end-to-end key; mailbox_quota writes.

pepsi-httpd

The queue’s envelopes and state, and the power to requeue, reroute, delete or inject messages; key metadata, including the public half of our own identities (Unauthenticated stored encrypt-to-self key replaced to read sent mail); the TLS key of the HTTPS certificate, a key of its own that no TLSA record pins (its certificate names HOSTNAME, so a peer checking the MX by PKIX alone would accept it); the list and archive tables; the administrative credential tables; the portal’s ciphertext (but no PIN); the managed PKI’s settings and users, so it decides what the next pass orders and in whose name, within the daily limit that it may also raise. It can request any privileged change — switching feature telemetry on included, which takes effect only where the operator runs pepsi-telemetry-client; it learns whether a SYSTEM_ID exists, never its value.

The headers or body of a queued message; users’ settings; reading a whitelist, or writing to one anything but a literal sender address, with DKIM required, on a user’s own (<login>/…) whitelist, which the console’s Allow this sender writes through a function that refuses a shared one; second factors; the S/MIME capability records (so it cannot downgrade a correspondent’s mail to CBC); root, /etc, any other private key, the mail listeners’ TLS key included; the managed PKI’s CA credentials and the keys of its waiting orders; the configuration overlay unless CONFIG_DB is configured. A request it records is re-validated by the applier — and is inert if pepsi-httpd-admin is not installed.

pepsi-keydisc

The LDAP bind password of key discovery, when one is configured. The peer-key cache, the CRL cache and the discovery request queue; so it can plant a correspondent key at any rank, retire any cached key by marking it revoked (sending that correspondent’s mail down the encrypt stage’s ON_NO_KEY route), and withhold revocation data (a forged list can neither revoke nor clear a certificate for the verifier, which checks the issuer’s signature; the retirement check accepts only a list an enabled anchor signed, or a fetched intermediate whose own chain to an enabled anchor verifies). It also writes the fetched intermediate certificates, so it can withhold one (that signer then reads valid-untrusted) but cannot anchor anything with a forged one. In the queue, every row’s state and the status and timeout columns it releases parked mail with – so it can stall or release queued mail, but not read or rewrite it.

Message envelopes, headers and bodies; any other queue column; our own identities (which pre-empt the cache); any private key.

pepsi-dkim

Every DKIM and ARC private key, so it can sign as every served domain and carry the keys away (recovery: pepsi-dkim rotate --hard, After a key exposure); with DNS_UPDATE = rfc2136, the TSIG key and whatever the DNS server lets that key update. Its requests come from every stage, which is why it runs under a fully hardened unit.

The queue, the database (it has no role), any end-to-end key or the KEK, another account’s files.

pepsi-greylist

The greylisting state: it can pass or defer any sender, and add rules that let any client through or refuse one (550). The envelopes of the sessions its MTAs ask about, as they arrive; which senders wrote to which recipients (the triplets, kept for PASSED_TTL). A read of every whitelist.

Any message, envelope or state in the queue; settings, keys, the configuration overlay; a write to a whitelist; any other account’s files. Its group grants nothing but its own socket.

A setuid helper (maildir, .forward, wallet)

Root, while it is compromised before it drops privilege. These are kept small and do their parsing only after becoming the user.

—

Important

Signatures are only as strong as the pipeline role. A per-user signature says “this deployment accepted this message from alice”, and that statement is made by pepsi-stage-encrypt on the strength of a From: header that every pepsi stage may rewrite after ingress checked it. The account split protects the keys — a compromised stage cannot carry one away, so the damage ends when the stage is fixed and no re-keying is needed — but not the use of them. Domain DKIM signatures are in the same position: the keys are pepsi-dkim’s, but every pepsi process may ask it to sign within its policy, and any stage may rewrite the From: it signs. This is a known residual, recorded in Security model (Unauthenticated private-key encryption lets the storage holder maul keys).

16.5.13. A compromised dependency

Pepsi is built from about 570 third-party crates (Cargo.lock), and every program links most of them: an async runtime, a serialisation library or a parser is in the setuid-root helpers, in pepsi-stage-encrypt and pepsi-stage-decrypt, which hold the key-encryption key, and in the root-run pepsi-setup alike. A malicious release of such a crate — by a hijacked maintainer account, a compromised registry, or a maintainer who was socially engineered (Subversion of legitimate packages in source, build or distribution) — therefore reaches every process at the next lock-file update, and the privilege separation that bounds a compromised process (A compromised component) bounds nothing: the crate runs as root and as pepsi-crypto. The Rust toolchain and the host’s C libraries (nettle, GMP, Kerberos, the PostgreSQL client) are in the same position and are the distribution’s to protect.

What stands between a malicious crate and a deployment (mechanisms in The supply chain):

  • Pinning. Cargo.lock names every crate version and its checksum, and every build is --locked, so a crate changes only when a developer updates the lock file, and a tampered download or mirror fails the checksum. cargo deny check refuses any registry but crates.io, any git source, any yanked version and any version with a published advisory.

  • A review record. cargo vet (supply-chain/, a gate of make check and of CI) requires every third-party crate version to be covered by an audit — the project’s own, or one imported from the public audit sets of Mozilla, Google, the Bytecode Alliance, ISRG, Zcash, Embark Studios, Fermyon and Ariel OS, pinned in imports.lock — or by an explicit exemption. An update to a crate nobody has recorded fails the gate, so a new or updated crate enters only through a recorded decision: a certified audit of the diff, or a deliberate exemption.

  • Signed, reproducible releases. Release tarballs are signed with the release manager’s OpenPGP key and Debian packages with the taler-systems release key (Verifying a download); the release build is reproducible and a CI job builds it twice and compares, so a binary that does not match what the published source produces is detectable (Reproducible builds).

Important

The residue. An audit vouches that somebody read a crate, not that a deliberately hidden backdoor was found, and the crates nobody has read are exempted, not audited: the audit record exempts 463 of the 564 third-party crates in the lock file (cargo vet prints the current figures; an exemption names the version, so an update to an exempted crate is still a recorded decision). A malicious crate that is already in the lock file, or whose malicious update is exempted without being read, runs with the privilege of every program that links it: it can read every message and every key, sign as anyone and take the host. The signatures and the reproducible build cover Pepsi’s own artefacts; the compiler and the crates it builds are trusted as downloaded, checked against their recorded hashes.

Dependencies names every package in the lock file, the reason for each direct dependency, what it brings with it and how much of that is audited.

16.6. End-to-end encryption: two custody modes

“End-to-end” needs an end. Pepsi supports two, per identity, and every claim depends on which one a key is in.

16.6.1. Gateway custody (custody = local, the MTA key)

The server generates the key, holds the private half wrapped, and signs and decrypts on the user’s behalf. The user reads ordinary mail in any client.

The end is the server. The protection is between domains and at rest:

  • In transit between deployments: mail is encrypted from the sending gateway (or client) to the receiving one. A network adversary and every relay in between see ciphertext.

  • At rest against a passive reader: a database copy yields wrapped keys but not the KEK; a stolen secrets.d yields the KEK but not the keys.

  • Not against the operator, root, or a compromised ``pepsi-crypto`` stage: they see plaintext and use the keys.

  • Not against a compromised pipeline for signatures — see the box above.

  • A CA-issued certificate changes who vouches for the key, not who holds it. With a managed PKI the key is generated here as well, only a certificate request goes to the CA, and the key is wrapped and guarded like every other gateway key (Certificates from a commercial CA).

  • Mail in the queue is plaintext on both sides of the crypto stages; that is what a pipeline is. Encrypt the database at rest if that matters. How long it stays is bounded: mail held at a quarantine stage is bounced, without its content, QUARANTINE_MAX_AGE_DAYS (14) days after arrival, or earlier at the end of a pepsi-stage-quarantine stage’s MAX_HOLD (dropped when it came out of, or failed to open from, an AES-CBC EnvelopedData, since that bounce would answer the padding question), and only the two newest pre-upgrade dumps are kept (An attacker who has the database).

  • Mail filed in the mailbox is plaintext — the mail store is trusted — unless the recipient also holds a client key and pepsi-stage-reencrypt is in the pipeline, in which case the filed copy is re-sealed to that key (see below). [stage-reencrypt] ON_NO_CLIENT_KEY = bounce (site-wide or per recipient) refuses mail rather than file it readable.

  • A revoked MTA key is announced, not merely dropped. Every revocation signs a revocation certificate with the key while its private half still exists; the Web Key Directory serves it, and a key that had been uploaded to a key server has it uploaded there too (Revocation is published while the key can still sign it). A correspondent who refreshes neither keeps the old key, which nothing on this side can change.

  • No forward secrecy unless the operator opts in. A gateway key decrypts everything ever encrypted to it, so a later theft of the database and the KEK reads all recorded past ciphertext to keys still held. The forward-secrecy profile ([pepsi-crypto] ENCRYPTION_ROTATION_DAYS, The forward-secrecy profile) bounds that: gateway encryption keys are replaced on schedule, and a retired one’s private half is destroyed after RETIRED_PRIVATE_GRACE_DAYS once no queued message is encrypted to it, so such a theft yields only the keys of the current period and the grace window. The price is that ciphertext to a destroyed key – archived, late, or sent by a correspondent with a stale key – is unreadable for good. The operator remains trusted: one who keeps copies of the keys defeats it.

This is the model of an S/MIME gateway appliance, and it is chosen on purpose: it protects users who will never install anything.

16.6.2. Client custody (custody = client, the MUA key)

The user’s own mail client holds the private key; Pepsi holds only the public half (registered through pepsi-keys, the console, the register control command, or the user’s own Autocrypt: header).

The end is the user’s client. Pepsi publishes the key (it becomes the address’s public face in WKD), encrypts mail from other local users to it, and passes mail encrypted to it through unopened — even when an MTA key of the same user is among the recipients too. What that buys:

  • Against a database thief, a compromised stage, or a compromised crypto stage: mail encrypted to the client key cannot be read — no server process ever held the private half.

  • Not against a malicious operator, who can still (a) substitute a different key in what Pepsi publishes (WKD, DANE, VKS) and in the own pre-emption, so that future mail is encrypted to a key of their choosing; (b) read mail that arrived in cleartext before Pepsi encrypted it to the user; and (c) suppress or delay mail. A user who needs protection from the operator must have correspondents encrypt to a fingerprint verified out of band. A user signed in to the console for their own address sees there the fingerprints that WKD, OPENPGPKEY and SMIMEA serve for it right now (Checking what is actually served), so a substitution in what is published can be noticed by the user who compares them with their client’s key — but only as served to this host at that moment: an operator or an on-path attacker who answers one chosen correspondent differently (equivocation) is not detected, and nothing keeps a signed record of what was published.

  • Signatures the user makes in their client are theirs alone; Pepsi adds no signature of its own over mail the client already signed.

  • All this holds only for mail actually encrypted to that key, in transit. A user may hold both kinds: the MTA key is not retired when an MUA key appears, and it keeps opening mail from correspondents who still use it. That mail is in gateway custody while it is queued, with gateway custody’s guarantees.

  • At rest, mail the gateway opened is re-sealed to the client keys when pepsi-stage-reencrypt runs before local delivery: the spam, language and whitelist stages read the plaintext, and what is filed is ciphertext only the client opens — with any of the user’s registered keys, so a backup token is not locked out of the mailbox. That protects the filed copy against anybody who later obtains the mail store, the database or the server; it does not undo the plaintext’s passage through the queue, which a compromised stage or the operator could have read or diverted at the time. Mail that arrived in cleartext is filed as it arrived — sealing it would claim a confidentiality it never had. No signature is added: the stage holds no private key, and the sender-signature verdict is the one pepsi-stage-decrypt recorded.

  • Losing every client key loses what was filed under them. There is no escrow or gateway key that could open the filed copy later — by decision, because such a key would open every mailbox it covers for whoever holds it, the operator included. The recovery path is a second or third registered client key (another device, a backup token): mail is sealed to all of them, and the key-registered notice and the register reply tell the user so (Losing a client key).

  • Revoking a client key is the client’s to publish. Pepsi stops using and serving it, but holds no private half to sign a revocation certificate with; the reply says that correspondents who have the key are not told.

16.6.3. Choosing between them

Adversary

Gateway custody

Client custody

Passive network observer

Protected

Protected

Database or backup thief

Protected (keys wrapped)

Protected (no private key)

Compromised ordinary stage

Reads queued plaintext; can obtain signatures; cannot take the key

Reads mail only if it arrived in cleartext; cannot sign as the user

Compromised pepsi-crypto stage

Keys taken; all mail readable

Protected for mail encrypted to the client key

Malicious operator

Not protected

Not protected for future mail (key substitution, which the user can see in the console’s served-key view unless it is shown only to chosen correspondents); protected for mail already encrypted to a verified fingerprint

Thief of the mail store after delivery

Not protected (filed in plaintext)

Protected: mail encrypted to the client key, and — with pepsi-stage-reencrypt — mail the gateway opened

16.6.4. Keys of correspondents

Encrypting to a correspondent is only as good as the key’s provenance. The trust ladder (Key management) ranks every source, and [pepsi-keydiscovery] MIN_TRUST sets the floor. The default floor is the bottom rung, so trust-on-first-use keys are encrypted to — which defeats a passive eavesdropper, and does not defeat an attacker who controls the correspondent’s key source or can inject a harvested key before the real one is seen. That is a deliberate trade: the alternative to a TOFU key is cleartext, not a better key (see Users skip, botch or cannot use key fingerprint verification, TOFU and key continuity miss first-contact and new-identity attacks). A deployment that prefers cleartext (or the secure-link portal) to an unauthenticated key raises the floor; see The network adversary.

The same reasoning does not extend to a key lookup that fails. An active attacker who makes a recipient’s key records fail to resolve (a forged SERVFAIL, dropped responses, a bogus DNSSEC answer) would otherwise turn opportunistic encryption into cleartext, so such a recipient is held instead: deferred while the recipient’s domain does not answer at all, and bounced at MAX_LIFETIME; sent to the secure-link portal, or bounced, once the domain answers for its mail servers while its key records keep failing. The attacker gets a delay or a diverted message, not the plaintext — unless the sender explicitly accepts cleartext ([clear-ok], CLEAR_ON_DNS_FAILURE) (A key lookup that fails in the DNS). The residue: without DNSSEC on the recipient’s zone a forged NXDOMAIN or empty answer is indistinguishable from a real “no record” and still reads as “no key”; only ENCRYPT = required closes that. A WKD fetch that fails over HTTPS likewise still reads as “no key”.

Cleartext to a keyless recipient is the opportunistic default, and the author’s own copy, filed by their client before the gateway acted, cannot show it. With NOTIFY_CLEARTEXT = author the author is told, per copy, which recipients got the message unencrypted; a subject that only resembles a request keyword is answered with a warning whatever the option says (Telling the author what left in cleartext). Off by default, so an author who did not ask is not told.

The same trade governs a key changing. Within the trust-on-first-use rungs the newest key wins (Autocrypt Level 1’s peer-state update), and “newest” is judged from a message whose From: the sender wrote — so a remote sender who can forge a correspondent’s address can make future mail to that correspondent go to a key of their choosing. What Pepsi guarantees is that this is never silent: every such replacement is an audit-log row written by the statement that makes it, and the local recipients of the message that caused it are mailed both fingerprints (A rotation is never silent). An operator who prefers refusing genuine rotations to accepting forged ones sets ACCEPT_ROTATION = expired, under which a live stored key is never replaced by a message; the correspondent then cannot read our mail until an operator accepts their new key by hand, or the stored key reaches the expiry it states itself. That date is read from the stored key’s own material when it is learnt (an OpenPGP self-signature, an X.509 notAfter), and on a re-sighting of the same OpenPGP key it only ever moves later — so replaying an older copy of the certificate, whose earlier self-signature had a shorter, lapsed expiry, cannot make a live key look dead. Nor can a replayed older copy make a dead key look live: copies of one OpenPGP key are merged rather than replaced, so a revocation, once stored, is kept whatever copy arrives next.

A gossiped key the owner later advertises themselves is promoted to the owner’s rung rather than replaced (A gossiped key its owner confirms is promoted). That grants a remote sender nothing a forged From: did not already: a forged Autocrypt: header carrying the attacker’s own key displaces a gossiped row outright on rank, so repeating the gossiped key can only confirm what was stored. Promotion changes the rank the row defends itself with, never the verdict a signature checked against it can reach.

A correspondent’s key can also be sound in provenance and still worthless: its private half may be public. Pepsi refuses, for encryption and for signature verification alike, a key on the known-compromised list (the badkeys list, which each deployment fetches daily into its database and which includes the Debian OpenSSL weak keys of the usual key types and sizes), an RSA key whose modulus gives its primes away, and an RSA key the daily batch-GCD screen found sharing a prime with another stored key; discovery and harvesting do not store such a key. The guarantee is bounded by what is known: a key that leaked but has not reached the list yet (or since the last daily check), a shared prime with a key this deployment has never seen, and a key learnt since the last screen (at most a day) are not recognised. The list’s source is trusted as far as TLS vouches for it, since its metadata is unsigned: whoever controls the server [pepsi-keydiscovery] BADKEYS_URL names can add entries, and so make Pepsi refuse a chosen correspondent’s key – mail to them then takes the ON_NO_KEY route, which may be cleartext. An update that would grow the list by more than a quarter, or whose list shrank, is refused until the operator forces it, and every run records what it added from which source list; within those bounds an addition is not detected. Inside the deployment only pepsi-crypto may write the list. A factored key among our own identities is reported to the operator, who revokes it; the screen does not act on its own.

The S/MIME container follows the correspondent too (Which S/MIME container a correspondent gets): authenticated AuthEnvelopedData unless the recipient’s capability record says their client cannot read it. A learnt record is keyed on the certificate whose signature carried the claim, so a remote sender can downgrade only mail encrypted to a certificate of their own; an operator-configured record overrides it. What remains is the correspondent’s own choice of client: one whose signatures announce no AES-GCM (Thunderbird today) is sent AES-256-CBC, which carries no integrity protection (EFAIL: CBC/CFB malleability gadgets exfiltrate decrypted mail), and one with no record at all is sent AEAD — which such a client shows as a blank message until a record is learnt or configured. The container’s algorithm identifier is not authenticated, so the content key of an AES-GCM message can be re-submitted under a synthetic AES-CBC container; Pepsi binds the key to the algorithm (RFC 9709) for every correspondent whose signatures announce that they can read it, and OPEN_ENVELOPED_DATA = no keeps Pepsi’s own decrypt stage from applying any key to an EnvelopedData. Mail to a correspondent whose client announces neither stays exposed to the relabelling wherever a CBC copy is opened. The first message to an unrecorded certificate therefore carries a plaintext notice beside the ciphertext (What a correspondent on an unmeasured client sees), sent once and saying nothing about the message; what it discloses is that the sender’s server encrypts S/MIME, which the pkcs7-mime part beside it already shows.

16.7. What a security indicator means

A reader, a filter rule, and later stages all act on what Pepsi says about a message. Each indicator’s meaning is exact:

[decrypted], state.encrypted

The message arrived encrypted to a key this deployment held, and was opened here. It says nothing about who sent it. “Encrypted” means an encryption packet or container was actually removed: an armored PGP MESSAGE that holds only a literal or signed packet earns neither indicator.

[verified: alice@example.org], state.signature_verified, verdict valid

A signature that covers the plaintext verified, and the key is anchored: our own identity, a manually pinned key (pinned by the operator, or by a local user — see below), a DNSSEC-validated DANE key, a WKD key, or an S/MIME chain to an operator-installed trust anchor — a chain that also stays inside every nameConstraints bound and certificate-policy requirement set by the CAs on it, the anchor’s own included, so anchoring a partner CA vouches for the partner’s namespace and nothing more; and inside the mail domains the operator scoped that anchor to, when it has a scope (pepsi-keys ca scope; an anchor with neither a scope nor constraints of its own vouches for every domain and is reported as such). The intermediates on such a chain may come from the message or, under CA_ISSUERS_FETCH, from the caIssuers fetch of pepsi-keydisc; none of them is ever an anchor, and a learnt copy of the signer’s certificate is held to the same path. Nothing weaker — a harvested, gossiped, attached or VKS key, a DANE answer without the AD bit, a CA nobody chose (Keys and certificates imported or trusted without verification) — can produce it; those give valid-untrusted (CMS eContent confusion and multi-signer mishandling in S/MIME clients). A signature that covers only ciphertext never produces it either, because anybody who holds a ciphertext can wrap their own signature around it. Unless the operator sets ISOLATE_SIGNED = no, the signed content is also all the message contains: unsigned content beside it is removed before delivery, and beside a signed plaintext that was encrypted, only attachments signed by the same key remain. The tag names the address the signer is bound to, and binds the signer to the From: line as the reader sees it, not merely to its first addr-spec (What [verified] binds the signer to): a display name or comment showing another address (Weak binding between signer certificate or key and the From address), a From: naming more than one mailbox, an anchored S/MIME certificate that names no address at all (Weak binding between signer certificate or key and the From address; unless the operator opted that anchor in) and a signer domain that looks like a served domain or a known correspondent’s (equal look-alike skeletons, different domains) each give valid-untrusted, with the reason in X-Pepsi-Crypto. An OpenPGP signature inside the ciphertext that names its intended recipients, none of them the key that opened the message, is invalid: it was signed for somebody else and re-encrypted to us. The same holds for an S/MIME signature carrying the private recipient attribute Pepsi writes (Who a signed and encrypted message was for). A signature that names no recipient (still the common case, and every S/MIME signature but Pepsi’s) cannot be told apart from one sent to us. When the signed content carries its own From: or reply-steering field (Reply-To:, Mail-Reply-To:, Mail-Followup-To:; protected headers, or a signed message/rfc822) and that differs from what the reader sees — for a reply-steering field, an outer one the signer did not protect counts — the verdict is valid-untrusted, never valid (Protected headers against the outer ones); one a mailing list added, beside a signer who protected none of them, keeps valid under [verified (except reply-to): …]. Where a reply goes remains the client’s choice: a client that replies to Sender:, or lets the reader pick an unsigned address, is outside this. A protected Subject: that only gained bracketed segments in front is no difference; one changed beyond that is shown in place of the outer one, so the tag stands over the subject that was signed. A protected Subject: that itself carries a security tag or a look-alike of one gives valid-untrusted: a client may show it, and it cannot be cleaned inside a signed part. To: and every other header field the reader sees are not covered: a protected To: that differs is reported, not acted on, and without a protected copy there is nothing to compare. A verified inline clearsigned block that shows the reader text its signature does not cover (armor header lines other than Hash:, or a block rendered as HTML) is partial: no tag, no state.signature_verified, the block delivered as it arrived.

The tag says the signer vouched for this message recently. A signature made more than MAX_SIGNATURE_AGE_DAYS (default 7) before this host received the message, or more than a day after, is valid-untrusted (withheld=old-signature/future-signature); the signing time is shown as signed-at= in X-Pepsi-Crypto. The comparison uses this host’s arrival time, never the sender-written Date:. So a captured signed message replayed under a fresh outer Subject: or Date: loses the tag when it is older than the window. Inside the window a replay still verifies, and a signature without a creation time (CMS without signingTime) is not judged: freshness beyond that needs the sender to protect its headers.

A user’s own pin raises a key’s rung. A local user with an enrolled second factor who compared a correspondent’s fingerprint can pin that key by e-mail (pin FPR CODE, A user’s own pin). The key then sits on the manual rung, an operator entry’s, and its signatures earn this tag — for every user of the deployment, because the key cache is shared. [verified] on that correspondent’s mail then rests on that one user’s comparison, which the key.peer.pin audit row attributes to them; it takes the full fingerprint, so an attacker would have to produce a second key with the same fingerprint rather than the same 64-bit key ID, and a stolen password alone cannot do it.

[unsigned, usually signed], usually-signed=<date> in X-Pepsi-Crypto

The message has no valid signature, and a valid signature by an anchored key bound to the same From: address verified on an earlier message within MISSING_SIGNATURE_WINDOW_DAYS. Only a valid verdict writes that record, so a stranger cannot create it for somebody else’s address. The tag is written only under ON_MISSING_SIGNATURE = tag; the default records the fact in the header and the state alone, because a correspondent writing from a new device looks the same (Correspondents who usually sign). Its absence says nothing: the first anchored signature from an address starts the record.

[unverified signer], [bad signature] (inside a ciphertext)

The message was decrypted here and carries a signature that does not make it valid: the key is untrusted or unknown, the cover is partial ([unverified signer]), or the signature fails ([bad signature]). The tag is written beside [decrypted] because anyone can re-send a captured ciphertext, or encrypt to a published key, from an address of their own; the tag says the signer is not vouched for, nothing more. Outside a ciphertext neither is written by default: a bad signature on cleartext mail is routine list damage, and an unknown signer is the normal state of mail from a stranger.

An S/MIME signer certificate listed on its issuer’s current CRL, as pepsi-keydisc fetched it from the certificate’s distribution point, makes the signature bad (revoked). The check soft-fails: an adversary who can block or delay that fetch, or a CA whose list is unobtainable, leaves the verdict at “not checked”, so a revoked certificate then still verifies (Revocation not checked or soft-failed by clients). Forging or replaying a list gains nothing more: the verifier believes only a current list the issuer’s key signed, and the cache never replaces a list with an older one. A list signed by an enabled anchor, or by a fetched intermediate (CA_ISSUERS_FETCH) whose path to an enabled anchor validates, also retires the cached certificates it names – inside that anchor’s scope, when it has one – so outbound mail is no longer encrypted to them (the encrypt stage’s ON_NO_KEY applies, reason revoked); any other list retires nothing. An expired certificate is withheld from outbound mail the same way, reason expired on and the date, with no list needed.

X-Pepsi-Warning: display-name-claims-other-address

The inbound From: has a display name (or comment) naming an address other than its own mailbox’s — the shape of a display-name spoof. Only ingress writes the field; any copy the sender wrote is removed. Its absence says nothing about the address itself.

X-Pepsi-Warning: from-has-bidi-or-invisible-characters

The inbound From: carries a bidirectional control, a directional mark or an invisible character (the zero-width joiners and variation selectors aside), so what the client shows may not be what the field says: a right-to-left override can display a reversed address as the one it spells. The field is delivered as received. Only ingress writes the warning; its absence says nothing about look-alike letters, which are not controls.

X-Pepsi-Warning: from-domain-resembles-served-domain

The inbound From: domain renders like one of this deployment’s served domains — the same UTS #39 skeleton (examp1e.org, a Cyrillic e, U+0435) — but is a different domain. It is written however well the sender authenticated their own domain, and it is a header field only: it earns no [external] tag and refuses nothing. Its absence says nothing about a look-alike of a correspondent’s domain, which ingress does not know.

X-Pepsi-Warning: attachment-name-has-bidi-or-invisible-characters

An attachment of the inbound message (in any MIME part, attached messages included) has a file name that carries a bidirectional control, a directional mark or an invisible character once RFC 2231 and RFC 2047 are decoded, so the client may show another name, or another extension, than the one the file has (invoice<RLO>fdp.exe). The name is delivered as received. Its absence says nothing about attachments inside ciphertext.

X-Pepsi-Warning: duplicate-header-<field>

The inbound message header carries two or more differing copies of a field RFC 5322 allows once — duplicate-header-cc always, and duplicate-header-date, -subject, -to, -reply-to or -sender only under MIME_ANOMALIES = log, since enforce refuses those messages. Mail clients show one copy or the other, and a DKIM signature that names the field once covers only the bottom one, so the copy the reader sees may be one nobody signed. Every copy is delivered as received. Its absence on mail from outside means the field occurs once (identical copies are reduced to one); only ingress writes the warning.

X-Pepsi-Warning: from-ambiguous

The inbound From: cannot be read one way only (an encoded-word or obsolete-syntax address, text after the angle-addr, a second angle-addr, a group), or it names mailboxes in more than one domain. Mail clients disagree on which author such a field shows, so no single authentication verdict describes the one the reader sees; the mark is written whatever the verdicts were. The field is delivered as received. Only ingress writes the warning.

X-Pepsi-Warning: served-domain-not-authenticated

The message came from outside (not local_origin) with a From: mailbox at one of this deployment’s served domains, and nothing vouched for the claim: no DMARC pass, no DKIM pass aligned with that domain, no SPF pass on an aligned envelope. The claim may still be true — a user’s mail bouncing back through a forwarder that re-signs nothing looks exactly like this — but it was not proven. Only ingress writes the field; any copy the sender wrote is removed.

X-Pepsi-Warning: served-sender-not-authenticated

The message came from outside with a Sender: mailbox at one of this deployment’s served domains — the delegate a client shows as “on behalf of” is a colleague — and nothing vouched for that domain: no DKIM pass and no SPF pass on an envelope aligned with it. A Sender: at a foreign domain (a mailing list, a delegation service) earns nothing. Only ingress writes the field.

X-Pepsi-Warning: dmarc-fail-not-enforced

DMARC evaluated to fail and the message was delivered anyway: because DMARC_ENFORCE is off, or because the From: domain publishes p=none. A failure a sealer in ARC_TRUSTED_SEALERS vouched for does not earn it; one DMARC_ENFORCE refused is never seen.

[external], state.auth.warnings

The subject tag written with any of the four warnings above (TAG_EXTERNAL, off with EXTERNAL_SUBJECT_TAG = no): this deployment could not vouch for the sender’s claim to be one of us, could not say which author the reader will be shown, or the sender’s own domain said the message was not theirs. It means no more than that. It is not a spam verdict, not a statement about the content, and not a mark on every message from the internet: a correspondent writing from their own domain earns no tag, whatever their authentication results, because they claimed nothing this deployment can judge. Its absence therefore says only that no such claim was made or that the claim was authenticated. A sender cannot write it: the rendered front of every inbound subject has copies of the tag removed before ingress decides, judged as a client displays it (encoded-words decoded, look-alikes folded, invisible and reordering characters removed), and a message without a Subject gets one. state.auth.warnings lists every warning value written, for stages and filters.

Authentication-Results

What ingress concluded about SPF, DKIM, DMARC and ARC, as recorded; it is not a filter. Inbound authentication is fail-open.

X-Pepsi-Crypto

The decrypt stage’s summary. Believable only because every inbound X-Pepsi-* header is stripped first (see GnuPG status-line and output injection fools front ends); a client must not believe it on mail that did not pass through a Pepsi decrypt stage. Its protected-mismatch key names the signed protected header fields (from, to, subject) that differ from the outer ones, and its usually-signed key marks a message missing the signature its sender’s mail usually carries.

Where a reader sees them. The subject tags are in-band: the subject is a field the sender writes, and a body can carry text that looks like a tag. Pepsi removes forged tags, but it cannot make a client tell a genuine tag from a banner painted in the body. The Outlook add-in’s read pane and the Thunderbird extension (Mail client extensions) are the out-of-band display: each reads X-Pepsi-Crypto and X-Pepsi-Warning inside the client and renders them in a surface that the message content cannot reach. It shows a verdict of valid as verified and never shows valid-untrusted as verified; it shows a missing field as a neutral “no gateway verdict” (the message carried no protection, or never crossed a decrypt stage; the extension cannot tell which and does not guess), and a message with more than one field as inconsistent. What that display proves is exactly what the field proves, on a mailbox that receives the managed domains only from Pepsi; on a mailbox fed by another route as well, a stranger’s field reaches the client and is rendered. Clients without an extension see the subject tags and nothing else.

Every one of these is written by pipeline code into the queue (boundary B3). They mean what they say against a remote sender; they mean nothing against a compromised pepsi stage, which can write any of them.

Using Pepsi: a guide for users restates the subject tags for the people who read the mail, in plain words and claiming no more than this section.

16.8. Forged notices

Pepsi writes mail itself: console sign-in links, secure-link portal notifications, secretary challenges, payment requests, replies to key, settings and wallet commands, key-change and out-of-office notices. A forged copy of any of them is a phishing template with the deployment’s name on it. Two mechanisms answer it, one for each direction.

Inbound, a forged notice claiming a served domain arrives as any other mail from outside that claims to be ours: marked [external] with X-Pepsi-Warning: served-domain-not-authenticated unless a DMARC, aligned DKIM or aligned SPF pass vouched for it, and refused when DMARC_ENFORCE and an enforcing policy say so (What a security indicator means, Mail from outside that claims to be ours is marked). That protects this deployment’s own users only.

Outbound, with NOTICE_SIGNER configured every such message carries an OpenPGP or S/MIME signature by one identity of the deployment, whose public key its Web Key Directory serves (Signed notices). What a valid notice signature proves: the message was composed by this deployment’s pipeline and not changed since, including the protected From:, To:, Subject and Date; a recipient whose client verifies it against the published key can tell it from a forgery that DMARC at their provider let through. What it does not prove: that every word is the operator’s. A notice quotes fields of the message that caused it — a correspondent’s display name, a subject hint, the addresses involved — and those are that party’s words, inside a signed message; the operator’s templates hold the rest. A notice to a third party is not signed while a per-address override applies to the message that caused it, since an override can change its wording; mail whose content is somebody else’s (portal replies, list posts and digests, bounces) is never signed, and neither are list notices and TLS reports (Signed notices). It also proves nothing to a client that does not verify signatures, or that shows an OpenPGP signature as an attachment. A signed notice is sent from the signer’s address, so the signature’s binding to From: holds; the address it would otherwise have come from is its Reply-To:, which the signature covers but does not vouch for. Its absence means the notice signer is not configured, or that the message is not one of the signed kinds; it is a warning only to a recipient who knows the deployment signs.

The signature is as strong as the pepsi role (like every signature Pepsi makes): the mark that selects a message is written into the queue by pipeline code, so a compromised pepsi stage can have anything signed with the notice key, while the key itself stays wrapped behind the pepsi-crypto boundary. The option is off unless the operator creates the identity and sets it.

16.9. Per-address settings are a trust boundary

Configuration is layered (Configuration): the INI file, then the operator’s database overlay (global, domain:, address:), then pepsi.settings — the one layer an account owner can write, by e-mail through pepsi-stage-edit-settings. The layers below it are the operator’s; this one is the user’s, and it is treated as untrusted input:

  • Only stages the operator lists in EDITABLE_STAGES can be changed. An edit to any other section is refused and nothing is stored.

  • Only the user’s own copy is affected. An override is keyed on the envelope sender of locally submitted mail and on the envelope recipient of everything else, and a message whose recipients’ overrides diverge is split first, so one user’s settings never act on another user’s copy.

  • Identity options are barred (SIGNING_DOMAIN; and on the paying side WALLET_MODE, WALLET_SCOPE, WALLET_USER): which domain a message is signed as, and whose wallet settles a payment demand, are the operator’s decision. So are the spending limits (MAX_TOTAL, MAX_TOTAL_PER_DAY): a control message is authenticated by the submission password whose theft those limits bound.

  • Programs cannot be replaced. Which program runs a stage, its default successor NEXT_STAGE and BOUNCE_STAGE are taken from the operator’s file; an override of them has no effect (and PROGRAM is additionally restricted to a pepsi-stage-* command by the edit stage). An option that names a program a stage or setuid tool executes (HELPER, SCAN_HELPER, MAILBOX_HELPER, PIN_COMMAND) may not be set by e-mail at all.

  • Every edit is validated by the owning stage’s own parser, against the effective configuration it would produce, before it is stored.

  • Secrets are never echoed. The reply quotes the effective options with every credential-bearing value masked, using the same predicate as the API.

  • Every spelling of an address is one key. An override, a whitelist row, a reply log or a rate count is stored and looked up in one canonical form (NFC, case-folded local part, A-label domain), in Rust and in the database alike, so a sender cannot pick a spelling of an address under which a record about it does not apply (Addresses are compared in one form).

  • They belong to one owner of the login. A login the operator deletes and later gives to somebody else is noticed as reassigned (a new uid, or back after it was gone), and the previous owner’s overrides, own whitelists, quota and auto-reply records are dropped before the new owner’s mail is delivered by the stage that notices. Key material is not dropped but reported to the operator, and senders can ask, through RFC 7293, that mail not reach a later owner at all (A login that changes owner). A reassignment Pepsi never saw – the account deleted and recreated under the same uid between two checks, with no mail delivered in between – is not detected. Logins are recorded by Pepsi’s own Maildir delivery, by LMTP delivery for every recipient the MDA accepted that resolves to a passwd login, and by an RFC 7293 check at ~/.forward; a virtual user that exists only in the MDA’s own user database has no passwd entry, so it is never recorded and its reassignment is not noticed either.

Some stages hand the user nothing an attacker could want: pepsi-stage-defang reads one switch, which only ever removes what a message shows, and has no branch target, so pepsi-setup --wizard lists it whenever it configures the settings editor.

What an editable stage does hand the user is every option that stage reads from its own section — including its branch targets (TRUE_STAGE, QUARANTINE_STAGE, RESPONSE_STAGE, SECURE_LINK_STAGE and the like). So a user can route their own mail through a different branch than the operator’s default. That is the intended power; the consequence is a rule for the operator:

Warning

Never list a stage in EDITABLE_STAGES whose effect you mean to be mandatory. In particular:

  • pepsi-stage-encrypt — ENCRYPT, SIGN and SECURE_LINK_STAGE decide whether a message leaves in the clear. List it only if users may choose that for their own mail.

  • pepsi-stage-dkim-sign, pepsi-stage-arc, pepsi-stage-srs — these protect the domain’s reputation, not the user’s.

  • pepsi-stage-decrypt on a shared path — its QUARANTINE_STAGE and ON_BAD_SIGNATURE route inbound mail. (pepsi-stage-quarantine itself reads its options from the base configuration whether it is listed or not, so its holds are the operator’s alone.)

  • The anti-spam and whitelist stages, if the site’s policy is that filtering is not optional.

  • pepsi-stage-auto-pay — the wallet and its limits are fixed (its selection options are identity options, MAX_TOTAL and MAX_TOTAL_PER_DAY are refused by e-mail), but every other option of the section is the account’s.

  • Any delivery or relay stage — their credentials are masked, but their targets are not (Mail appliances store secrets world-readable or unprotected).

UNRESTRICTED_UNSAFE_STAGES = yes lifts the PROGRAM, executable-option (HELPER, SCAN_HELPER, MAILBOX_HELPER, PIN_COMMAND), identity and spending-limit restrictions entirely; it turns every editable stage into one the user fully controls.

16.10. The network adversary

The defaults defeat a passive eavesdropper, not an active one. Every hop uses TLS when the peer offers it, and every key the ladder finds is used for encryption, but an attacker in the path can strip STARTTLS, substitute a certificate, or (with the resolver) substitute a key, wherever the peer has not published a policy that forbids it. This is the posture of every opportunistic MTA, and it is what keeps mail flowing to the majority of domains that publish nothing.

A hardened profile makes a deployment resist an active attacker wherever the peer has published something to check against:

Setting

What it closes

A validating resolver on a trusted path: on loopback (unbound, or systemd-resolved with DNSSEC=yes), or a validating resolver the operator trusts, reached over DNS over TLS or HTTPS (a tls:// or https:// entry of [pepsi] DNS_SERVERS, its certificate verified for the name the entry gives)

Every DNSSEC-based check below depends on the AD bit being honest; without such a resolver, DANE finds nothing and silently does not apply. An encrypted channel removes the path, not the resolver, from what is trusted: its operator still decides what counts as validated, and an unreachable encrypted resolver fails the lookup instead of falling back to plain DNS. pepsi-setup warns when DANE is in use and a resolver it relies on does not validate, and names by IP address every resolver off this host reached over plain DNS that it trusts; each relay worker with DANE on, and pepsi-keydisc@dane, warns when it starts about such a resolver and about one that does not set the AD bit on a signed probe answer, and pepsi-status reports both. Nothing refuses one: DNS setup is outside Pepsi’s scope, and the operator chooses whom to trust.

DANE = strict on pepsi-stage-relay-to-internet (and on each smarthost entry) – the default; keep it, rather than warn

A peer with DNSSEC-signed TLSA records cannot be intercepted: a mismatch defers instead of delivering.

MTA_STS left enabled (the default)

A peer with an enforce policy cannot be downgraded once its policy has been fetched: the policy is kept for its max_age (at most a week) in pepsi.mta_sts_policy, across worker and service restarts, and fetched again once half of that has passed, on use and by the hourly pepsi-queue gc whether or not the domain is mailed, so the attacker has to be in the path at the first fetch, or block every refresh until the policy expires (trust on first use, as RFC 8461 designs it; failed refreshes are logged as warnings well before that).

[pepsi-keydiscovery] MIN_TRUST = owner-confirmed (or wkd)

Encryption only to keys whose publication somebody controlling the mailbox or domain proved; below the floor, the message goes cleartext or to the secure-link portal as ENCRYPT decides.

TLS_CA_BUNDLE on each smarthost entry, naming the CA that issues the smarthost’s certificate

A certificate for the smarthost’s name mis-issued by any other CA in the system root store cannot intercept the relay credentials and the outgoing mail.

[pepsi-keydiscovery] TLS_CA_BUNDLE naming the few CAs your correspondents’ WKD hosts and your key servers use

A certificate mis-issued by any other CA in the system root store can no longer plant a WKD or key-server key; correspondents whose WKD host uses a CA outside the file lose WKD discovery.

DMARC_ENFORCE on ingress (the wizard’s default for a new installation), with ARC_TRUSTED_SEALERS naming only forwarders whose authentication you rely on

Mail forging a DMARC-protected domain’s From: — including your own — is refused rather than delivered with a failing result; a listed forwarder’s validating ARC chain is the only thing that overrides the refusal.

Publish your own TLSA, MTA-STS enforce and TLSRPT records (pepsi-setup prints them)

The same protection for mail sent to you, by senders that check.

Have your zones signed with keys of their own, ECDSA P-256 or Ed25519 (or RSA of at least 2048 bits), and act on the DNSKEY findings of pepsi-setup check

Your MX and TLSA records cannot be forged with a key your DNS host shares with other customers, a deprecated algorithm, a factorable modulus or a key whose private half is public (The keys that sign our zones).

Mail clients that submit sensitive messages with REQUIRETLS (RFC 8689) over the TLS submission listener

Those messages cannot be downgraded on any hop: a next hop that offers no validated TLS, or does not promise the same, gets a bounce instead of the message. The recipient domain need not publish anything.

Even hardened, an active attacker can always cause a denial of service; the profile converts interception into deferral.

16.11. Availability

Pepsi’s availability goal is narrower than its confidentiality goal, and stated as a rule: under hostile input, a message is deferred rather than lost, and a failure is closed rather than disclosing. A stage that cannot decide parks or fails the one message; it does not stop its peers, and it never sends in the clear because a check could not be made. Volumetric flooding of the network or the host is out of scope — that belongs in front of the MTA.

Within that scope, each resource an attacker can make Pepsi spend is bounded as follows.

16.11.1. SMTP ingress

Resource

Limit

Status

Connections

MAX_CONNECTIONS (1024), capped below the file-descriptor limit; at the cap the most idle connection of the busiest address range is evicted. New connections are rate-limited per /32 (CONN_RATE_PER_SECOND, CONN_RATE_BURST), and one address range may hold at most MAX_CONNECTIONS_PER_IP (16) at once. The local submission socket, exempt from the rate limit and from the server-wide eviction, has a ceiling of its own (MAX_LOCAL_CONNECTIONS, 32), so local users cannot starve remote SMTP, and one peer uid may hold at most half of it, so one local account cannot lock out the others; when it is full, a uid holding fewer local connections evicts the heaviest uid’s longest-idle one (idle at least 5 s, 421 4.3.2), so colluding accounts cannot fill it either.

Bounded

Messages

MAX_MESSAGES_PER_SESSION (100) transactions per session, then 421 and a reconnect into the rate limit. Local submission is metered per SO_PEERCRED uid across sessions (LOCAL_MESSAGES_PER_MINUTE, 60, burst LOCAL_MESSAGE_BURST, 120), deferring with 451. Recipients of SASL submission are metered per account across sessions (USER_RECIPIENTS_PER_HOUR, 500, burst USER_RECIPIENT_BURST, 500), deferring with 450, so a stolen password cannot make the host a bulk sender.

Bounded

Recipient checks

MAX_INVALID_RECIPIENTS (10) unknown recipients per session, then 421. Probes of the MDA or backend are cached (an hour for “yes”, five minutes for “no”) and capped at 16 in flight; past the cap the address is accepted rather than queued behind the backend.

Bounded

Message size and shape

MAX_MESSAGE_SIZE (25 MiB) at MAIL SIZE=, during DATA and BDAT; an oversized DATA body is drained for at most another MAX_MESSAGE_SIZE before the connection is closed; 1000 recipients; 4 KiB command lines, 1 MiB data lines; at most MAX_HEADER_FIELDS (1000) top-level header fields and MAX_HEADER_FIELD_SIZE (100 KiB) per field, unfolded (552 5.3.4), so the mail store behind Pepsi is never handed the header blocks of the Dovecot advisories CVE-2024-23184/23185; header blocks of attached messages are bounded by the message size only.

Bounded

Time

TLS_HANDSHAKE_TIMEOUT (30 s) on a TLS handshake, implicit or after STARTTLS, after which the connection is closed; COMMAND_TIMEOUT (300 s), DATA_TIMEOUT (180 s), both per read and reset by every byte; ten lines that are no SMTP command close the session; SESSION_TIMEOUT (30 m) on the whole session, reset by nothing, after which the next read is answered 421. A connection waiting for client input – a command or the next bytes of a body – also counts as idle and is evicted first when the server is full.

Bounded

Password guessing

Three failed AUTH attempts close the session with 421, so every further batch of guesses costs a new, rate-limited connection; across sessions an address range may fail AUTH_FAILURES_PER_HOUR (20) times an hour, after which AUTH is refused without the password being checked; an account that has collected ACCOUNT_AUTH_FAILURES_PER_HOUR (10) failures from all sources is guessed at no faster than once per ACCOUNT_AUTH_DELAY (20 s) from ranges it has not signed in from, delayed rather than locked. Invalid SRS recipients are capped at three per session.

Bounded

Authentication work

SPF’s ten-lookup limit, at most 50 ARC sets, DNS_TIMEOUT per query; at most MAX_DKIM_SIGNATURES (10) signatures verified, those that can align with From: first; SPF and DKIM concurrently under VERIFY_TIMEOUT (20 s), then DMARC under another. A check that runs out of time is temperror for that check alone, which DMARC ignores unless it aligns — so the deadline cannot be used to dodge DMARC_ENFORCE.

Bounded

Milters in the SMTP session

One connection per configured milter per session, so at most MAX_CONNECTIONS per milter. Each reply is awaited for at most COMMAND_TIMEOUT (CONTENT_TIMEOUT at the end of the message, which SMFIR_PROGRESS may extend to ten times that); a packet is at most 16 MiB, an end of message at most 1024 modifications and 64 MiB of replacement body. A milter that cannot be consulted costs, under the default ON_FAILURE = accept, its own verdicts for the rest of the session, and nothing else.

Bounded

16.11.2. The greylisting milter

pepsi-greylist is asked at every RCPT of the sessions that an MTA filters through it, so a remote sender chooses much of what it spends.

Resource

Limit

Status

MTA connections

MAX_CONNECTIONS (256) at once; one beyond it is closed, which the MTA treats as a milter failure. An idle connection is closed after 15 minutes.

Bounded

DNS lookups per recipient

Each step (one SPF evaluation within SPF’s own limit of ten lookups, one reverse lookup with its forward confirmation, one DMARC tree walk of at most eight queries, one MX lookup with the addresses of at most ten hosts) is bounded by DNS_TIMEOUT (2 s). The identity is worked out once per transaction; a retry from another host is compared with at most eight earlier triplets, and each answer is kept for DNS_CACHE_TTL in a cache of at most 10 000 entries. A step that runs out of time lets the recipient through.

Bounded; fails open

Rows

One triplet per (identity, sender, recipient) that a client tries, removed by pepsi-greylist-prune.timer once RETRY_WINDOW (48 h) passed without a retry, or PASSED_TTL (35 days) after it was last seen. A sender that rotates through invented senders adds rows for two days; ingress’s own per-session and per-address limits bound how many.

Bounded by time

The database

A database error lets the recipient through, so an outage of PostgreSQL turns greylisting off rather than refusing mail. Ingress refuses mail anyway when it cannot queue it.

Fails open

16.11.3. The queue and the pipeline

Resource

Limit

Status

Queue depth and disk

[pepsi] MAX_QUEUE_ROWS (1 000 000 rows), MAX_QUEUE_BYTES (off by default) and MIN_FREE_SPACE (1 GiB on FREE_SPACE_PATH): pepsi-ingress answers 452 4.3.1 at RCPT, DATA and after the end of data while any is reached, and pepsi-stage-list-post holds a fan-out back instead of emitting its next batch. Measured at most every QUEUE_CHECK_INTERVAL (10 s), so the ceilings are soft by one interval’s admissions; a failed measurement admits. Mail the pipeline itself originates (bounces, DSNs, notices) is never refused, and a queue already over a limit drains normally.

Bounded

Storage amplification

A message’s body is stored once in pepsi.workqueue_body and shared by every row split off it, so a post to N recipients costs one body and N small rows, not N bodies. A stage that rewrites a body copies it for that one row (copy-on-write).

Bounded

Fairness

pepsi-dispatch shares each stage’s worker time among senders (an authenticated account, else the connecting address, IPv6 by /64), least recently served first, so one sender’s burst queues behind itself rather than in front of everybody. [pepsi-dispatch] FAIR_FIFO_PERCENT (10) of every stage’s slots still go to its oldest rows, which bounds how long any message can wait. A sender able to connect from many addresses counts as many senders.

Bounded

A hung or crashing worker

MAX_RUNTIME (300 s, 900 s for delivery stages) kills the worker, and a crash ends it; either way the message takes a strike and is retried a minute (then two) later, and the third strike moves it to timeout or failed, both terminal. A poison message is therefore tried three times, not in a loop; pepsi-failure-bouncer never re-bounces a row already at the bounce stage. A kill in a delivery stage is the exception: it blames the next hop, so retries go on, at most hourly, until MAX_LIFETIME. Delivery stages end a slow delivery before the kill, and LMTP delivery stops after three attempts without an acknowledgement.

Bounded

Retries

MAX_LIFETIME (120 h) on every stage, for its own retries and for any error it does not mark permanent; PAYMENT_DEADLINE on the anti-spam gate.

Bounded

Parsing

MIME depth 16–32 and part counts; decompressed OpenPGP plaintext capped at 64 MiB while streaming; three cleartext signature layers above the ciphertext; X.509 chains of eight, with at most 64 policies or policy mappings per certificate in the policy tree and 220 name-against-subtree comparisons per certificate in name-constraint checking; harvested and gossiped key material capped in count and size; an OpenPGP certificate from anybody else with an RSA key above 8192 bits refused (OpenPGP and S/MIME alike); language detection reads at most 20 000 characters; a DMARC aggregate report is inflated to at most MAX_REPORT_SIZE (16 MiB) whether gzip or zip and whatever its archive declares, no entity its XML declares is expanded, and at most 20 000 of its records are stored, each report kept for RETAIN_DAYS (90).

Bounded

The signing daemon

A signing request is one line of at most 256 KiB carrying at most 512 header fields, checked before anything is signed; signing never waits for the daemon’s DNS checks. While pepsi-dkim does not answer, the signing stages pause their messages and retry them under MAX_LIFETIME: mail is deferred, never sent unsigned.

Bounded

Whitelist patterns

The expressions users store are evaluated by PostgreSQL under a five-second statement_timeout; one that backtracks for longer (a back-reference against a long From:) is cancelled and the message treated as not whitelisted.

Bounded

16.11.4. Loops and amplification

  • Mail loops stop at MAX_HOP_COUNT (30) on the relay stages, at the .forward chain guard, at alias depth 32 and at five list hops, and pepsi-setup refuses a smarthost that is this host’s own ingress listener. A bounce is never bounced.

  • Automatic replies — vacation notices, secretary challenges and the anti-spam payment request — all obey the RFC 3834 suppression rules in pepsi-common::autoreply, so none answers a list, a bulk mailing, another responder or a delivery report, nor a sender that failed SPF or DMARC outright (nor, with REQUIRE_AUTHENTICATED on the stage, one that did not pass), and none quotes the sender’s words to a sender that did not pass. Vacation notices are further limited to one per correspondent per SUPPRESS_DAYS, secretary challenges to five per sender a day, and payment requests to one per sender and protected mailbox per BLOCK_RESPONSE_SUPPRESS (one hour by default), decided and recorded in one statement so parallel workers cannot both send.

  • A list member is disabled only by a bounce Pepsi can attribute. Every copy’s VERP envelope sender carries an authentication code keyed with [pepsi-list] VERP_SECRET; a bounce to a member-shaped address whose code does not verify is dropped unscored, and with BOUNCE_PROBES (on by default) even an attributed score only sends a probe, whose own bounce — a random token nobody can forge — is what disables delivery.

  • Mailing lists multiply a post by their membership, so a sender’s posts to one list beyond SENDER_POSTS_PER_HOUR (30) in an hour are held for the moderator instead of distributed, and a list holds at most MAX_HELD_MESSAGES (1000) posts for moderation — past that a post that would be held is discarded, the new one rather than the oldest, so a flood cannot flush out what a moderator has yet to see. A post that filter_action would keep is refused to its sender instead. List hops are capped as above.

  • Mail the web forms send (list sign-up, password reset) is limited per target address to two an hour, and per client, so the forms cannot be used to flood a third party’s mailbox.

  • Key discovery answers each address once however many messages ask (requests are de-duplicated), remembers failures (NEGATIVE_TTL, ERROR_TTL), caps a response at 256 KiB and one same-host redirect, and puts a deadline on the whole response — a server that dribbles bytes cannot hold a discovery method, which serves every other lookup in turn. A message waits at most TIMEOUT for a key before it proceeds without one — except when the lookup failed in the recipient’s DNS, where it is deferred (one re-check per 15 minutes, per address rather than per message) and bounced at the encrypt stage’s MAX_LIFETIME (A key lookup that fails in the DNS). A revocation list is fetched under the same deadline, capped at CRL_MAX_BYTES (1 MiB), at most two distribution points per certificate and with no redirect at all, by a loop of its own, so neither a slow nor a huge list delays a key lookup.

16.11.5. The web tier

Resource

Limit

Status

Connections and slow clients

MAX_CONNECTIONS (256), at most MAX_CONNECTIONS_PER_IP (32) from one client address (an IPv4 address or IPv6 /64; connections through a reverse proxy’s UNIX socket are the proxy’s to limit); 30 s for the headers, the TLS handshake and the request body each.

Bounded

Argon2id (PINs and passwords)

One derivation per CPU at a time, off the executor; a request that cannot get a slot within seconds is turned away with 429 rather than queued. The secure-link PIN is additionally limited to MAX_ATTEMPTS per message with a doubling LOCKOUT, charged atomically before the derivation so parallel guesses cannot overshoot it (Login and recovery rate limits defeated by races and logic errors); sign-ins by account and by source (LOGIN_RATE_LIMIT, 10 a minute), and failed sign-ins per account per day from all sources (LOGIN_DAILY_LIMIT, 100), past which the account’s password sign-ins are refused until the allowance refills – a ceiling anybody who knows the name can spend, so the local socket and bearer tokens stay unaffected.

Bounded

Request bodies

8 KiB for forms, 1 MiB for the administrative API, 8 MiB for the list API.

Bounded

Stored data

Secure-link messages expire (EXPIRY_DAYS) and are deleted daily (pepsi-secure-link-prune.timer). Timers named by pepsi.target, independent of the web server, prune the logs (90 days of event_log, 30 of mail_log; pepsi-log-prune.timer), the TLS-report counters (RETAIN_DAYS; pepsi-tlsrpt-prune.timer) and, hourly (pepsi-origin-gc.timer), expired origin nonces, MX address cache rows, MTA-STS policies, list confirmation requests and lapsed learnt whitelist rows.

Bounded

16.11.6. Money and mailboxes

  • Auto-pay spends at most MAX_TOTAL per message we sent and at most MAX_TOTAL_PER_DAY per wallet in any 24 hours, both booked atomically in one statement (serialised per wallet) so concurrent demands — for one message or for many — cannot overspend either, and a payment that fails to settle is credited back to both. Without the daily limit, somebody who received many of our messages, or a thief sending with a user’s password to a gate of their own, could demand MAX_TOTAL for each, so a stage with a non-zero MAX_TOTAL refuses to start without one, and neither limit can be changed by e-mail. It is deliberately not per correspondent: mailing lists and aliases make the demanding party unknowable, while the wallet is always known. Under WALLET_SCOPE = unified the one wallet is everybody’s, so one correspondent can use up the day for all senders — a denial of automatic payment (the demands then bounce as usual), not a loss beyond the limit.

  • Mailbox quotas refuse only on a measurement, never on an estimate, and the three rules that stop a full mailbox from staying shut after its owner empties it (a maximum age for the measurement ingress acts on, a re-measure before refusing, and the pepsi-quota reconcile timer) are in pepsi-quota.

16.12. What Pepsi does not protect

  • Anything against root or a malicious operator. See Principals and how far each is trusted.

  • Traffic analysis. Who corresponds with whom, when and how much is visible to anyone who can see the network, the queue, or the logs. End-to-end encryption does not encrypt envelopes, and header protection covers only what the container allows. Padding blurs an encrypted message’s length to a size class (The length of an encrypted message); it does not hide that the message exists. The one piece the recipient is denied is the submitting client’s address, machine name and software, withheld on a submission listener by default (RECEIVED_PRIVACY); the operator’s journal still has it, and the Message-ID a client wrote passes through.

  • Plaintext in the queue. Every stage must read the message it processes.

  • Signatures against a compromised pipeline, as above.

  • A malicious dependency that nobody read. The audit record exempts most crates rather than vouching for them, and a crate runs in every process (A compromised dependency).

  • Correspondents’ own compromise. A key published by a compromised domain is a compromised key, at whatever rank the ladder gives that domain.

  • Recipients’ mailboxes after delivery, beyond one thing: for a user with a client key, mail the gateway decrypted is filed re-sealed to it (Client custody (custody = client, the MUA key)).

  • Lookup privacy toward the correspondent’s domain. Discovering a key tells that domain’s DNS and WKD host that somebody here is about to write to the address; a VKS server learns the same. The daily key refresh re-asks only the method each cached key came from, and only while that method is still in SOURCES; harvested, gossiped and hand-entered keys are never refreshed over the network. So a key server (keys.openpgp.org by default) learns again only about the correspondents whose key it supplied. ALLOW_DOMAINS / DENY_DOMAINS, removing vks from SOURCES and DISCOVERY = no (message-driven lookups only) limit it (Key management). Fetching revocation lists tells a correspondent’s CA, on the list’s own schedule (its nextUpdate, but at most hourly and at least daily), that this host holds some certificate it issued – not which one, and not when a message signed with it arrives, because there is no OCSP query; a distribution point on plain HTTP shows the same to the network path. [pepsi-keydiscovery] CRL_FETCH = no stops it, and S/MIME revocation then reads “not checked”. A TLS report tells the receiving domain only how many sessions to each of its MX hosts succeeded or failed on one day, and why they failed; opt-in telemetry discloses aggregate counts only. Telemetry is off until the operator turns it on — at a terminal, or in the console, which can offer it only once the operator has started pepsi-telemetry-client and given [pepsi] a SYSTEM_ID by hand.

16.13. The guarantees at a glance

“Yes” means the adversary can compromise that asset; “No” means a mechanism prevents it; “Partial” is explained in the section named in the first column.

Adversary

Queued mail

E2E private keys

Signing as a user / the domain

Other users’ settings and mail

Money

Credentials

Filed mail (MUA-key users)

Passive network

No

No

No

No

No

No

No

Active network (defaults)

Partial (downgrade; not a REQUIRETLS message)

No

No

No

No

No

No

Remote sender

No

No

Partial (fields a signed notice quotes)

No

Partial (budget)

No

No

Local shell user

No

No

No

No

No

No

No

Mail-only user

No

No

Partial (fields a signed notice quotes)

No

Own wallet only

No

No

Stolen mail password

No

No

Partial (no second factor)

No

Own wallet only

No

Partial (no second factor)

Mailbox reader (sign-in by e-mail)

No

No

Partial (no second factor)

No

No

No

Partial (no second factor)

Delegated admin

Partial (scope)

No

No

Partial (scope)

Partial (keys:write: CA orders)

No

No

Stolen console password

Partial (scope; no second factor)

No

No

Partial (scope; no second factor)

Partial (keys:write: CA orders)

No

No

Phishing proxy

Partial (accounts without a security key)

No

No

Partial (accounts without a security key)

No

No

No

Database copy

Yes

No

No

Read only

No

No

No

One secret fragment

No

No (KEK alone)

Partial (per secret)

No

Partial (Origin key, CA credential)

No

No

Compromised pepsi stage

Yes

No

Yes (while it runs; no key leaves)

Yes

Partial (budget)

No

Partial (future mail)

Compromised pepsi-dkim

No

No

Partial (the domain, and its keys; no user)

No

No

No

No

Compromised pepsi-greylist

No (delay or pass only)

No

No

No

No

No

No

Compromised crypto stage

Yes

Yes (gateway custody)

Yes

Yes

Partial (budget, CA orders)

No

Partial (future mail)

Compromised pepsi-httpd

Partial (envelopes, routing; no content)

No

No

Partial (routing, whitelist entries; no settings)

Partial (CA orders)

Its own tables

No

Compromised dependency

Yes

Yes (gateway custody)

Yes

Yes

Yes

Yes

Partial (future mail)

Operator / root

Yes

Yes (gateway custody)

Yes

Yes

Yes

Yes

Partial (future mail)

“Yes (while it runs; no key leaves)” for a compromised pepsi stage: it can have any message of a served domain DKIM-signed and ARC-sealed, and any local user’s identity sign a message, but cannot read the DKIM keys, so the signing ends when the stage is fixed (A compromised component). A compromised pepsi-dkim holds every DKIM and ARC key and can carry them away, so the domain’s signatures stay forgeable until pepsi-dkim rotate --hard has replaced them; it signs nothing as a user.

“Partial (accounts without a security key)” for a phishing proxy: an account whose second factor is a TOTP code, or that has none, is signed in through the proxy like through the real page; an account whose sign-in needs a WebAuthn key is not (A phishing proxy (adversary in the middle)).

“Partial (no second factor)” for a stolen mail password: without a second factor the thief can register their own key as the user’s, which makes signatures verify as the user and has future mail — filed mail included — sealed to a key they hold; with one enrolled, every key change needs a code (Someone holding a user’s mail password). A mailbox reader where sign-in by e-mail is on gets the same through the console, and nothing more (Someone who can read a user’s mailbox).

“Partial (fields a signed notice quotes)”: with NOTICE_SIGNER configured, a notice the deployment signs can quote words of the sender or the user whose message caused it — a display name, a subject hint — so those words reach the notice’s recipient inside a valid signature; they can never have the notice key sign a message of their own (Forged notices).

“Whitelist entries”: a compromised pepsi-httpd can put any sender address on any user’s own whitelist (never a shared one, and never a pattern), through the function behind the console’s Allow this sender. The row requires DKIM, so it counts only for mail that the sender’s domain authenticates (a DKIM signature at the whitelist stage, SPF when greylisting); for that mail, the user’s pay-to-send gate and greylisting are skipped. It cannot remove a row or read one.

“CA orders” in the money column: whoever may change a managed-PKI domain’s settings and users (keys:write in the console, pepsi-httpd itself, the pepsi-crypto role) decides which certificates the organisation pays for, the daily limit included; whoever holds a domain’s CA credential (one secret fragment, or the crypto stages, which can read it) orders through the CA’s API directly. None of them obtains a user’s private key that way. A mail-only user at a domain whose display names are trusted (header_names = trust) gets one certificate for their own address under a name of their choosing; under the default approve, none until an administrator confirms the name (Certificates from a commercial CA).

Filed mail is a message the gateway decrypted and then re-sealed to the recipient’s own client key before delivery (pepsi-stage-reencrypt, see Client custody (custody = client, the MUA key)). “Partial (future mail)”: an adversary who controls the pipeline, a crypto stage or the host can read — or stop re-sealing — mail that passes through while they are in control, and can never open a copy already filed, since no server process holds the client key. A compromised dependency is the operator’s row: a crate every program links runs as root in pepsi-setup and as pepsi-crypto in the key-holding stages (A compromised dependency). For a user with no MUA key the column does not apply: their mail is filed in plaintext, or refused under ON_NO_CLIENT_KEY = bounce.

The matrix covers what is held here. The key that future mail to a correspondent is encrypted with is covered by Keys of correspondents: a remote sender able to forge that correspondent’s From: can replace a trust-on-first-use key (Partial: always audited and announced to the recipients, and refused under ACCEPT_ROTATION = expired while the stored key is alive, that is, not revoked and not past the expiry it states itself), and can never replace a pinned, published or operator-entered one.

The “E2E private keys” column is about the keys as they are now. Mail recorded in transit and encrypted to a gateway key is readable by whoever later obtains that key with the KEK (the database and secrets.d together, the host, the operator) for as long as the key’s private half exists: for ever by default, for the rotation interval plus the grace period under the forward-secrecy profile (Gateway custody (custody = local, the MTA key)). A signature from a partner CA’s domain is “No” in the signing column only for an anchor whose scope or own nameConstraints limit it; an unscoped, unconstrained anchor vouches for every domain, which pepsi-status reports.

16.14. See also

Security model — the mechanisms behind every “No” above. Key management — custody, the trust ladder, discovery. The secure-link fallback portal — the no-key fallback and its PIN model. The administrative API — scopes and the applier. Configuration — the layering the settings boundary sits on top of.