20. Mail client extensions¶
Pepsi records what it verified or decrypted on an inbound message in two
places: the [decrypted] / [verified] subject tags, which every client
displays, and the X-Pepsi-Crypto header field, which a client shows only
among the raw headers unless it has one of the extensions in this chapter. The tags
have a weakness that the gateway cannot remove: the sender writes the subject,
and a message body can carry a banner that looks like a tag. Pepsi
strips forged tags (Header forgery), but a reader who sees
“verified” in the body of an unsigned message has no way to tell it apart from
the real thing.
The two extensions in this chapter close that gap for the two clients they
cover. Each reads X-Pepsi-Crypto and X-Pepsi-Warning from the message
headers inside the client and shows the gateway’s verdict in a place that the
message content cannot reach: a task pane in Outlook, a toolbar button with a
badge and a popup in Thunderbird. Nothing that the sender writes into the
subject or the body changes what appears there, and what the gateway did not
say is shown as exactly that – a neutral “no gateway verdict” – never as a
good or a bad one. What a security indicator means states what each verdict promises.
Both are small, dependency-free pieces of JavaScript that share one parser
(contrib/addin/pepsi-crypto.js). make check holds that parser to the
gateway: every key the decrypt stage can write to X-Pepsi-Crypto, every
signature verdict and every X-Pepsi-Warning value must be one that it knows
(tests/check-extensions.sh).
Neither extension reports anything anywhere. The headers are read by the
client and stay there. The Outlook pages are fetched from the gateway like
any static file, and that fetch is all that the gateway sees; when telemetry is
on, it is counted under the addin key. No message content, no address and
no verdict leaves the client.
20.1. What is shown¶
The verdict is one headline with an explanation, coloured by severity, then any warnings, then the facts the gateway recorded:
Headline |
When |
|---|---|
Verified: signed by … (green) |
|
Decrypted by the gateway; sender not verified (blue) |
|
Encrypted to your own key (blue) |
|
No gateway verdict (grey) |
No |
No protection recorded (grey) |
An |
Signed, but not credited to the sender (amber) |
|
Only part of what you see is signed (amber) |
|
Signed with a key nobody vouches for (amber) |
|
Signed, but the signature could not be checked (amber) |
|
Encrypted; could not be opened here (amber) |
|
Decrypted, but nobody vouches for the content (red) |
|
Signature invalid (red) |
|
Conflicting gateway verdicts (red) |
More than one |
Below the headline:
every
X-Pepsi-Warningas its own red line, spelled out in words.display-name-claims-other-addressreads “the sender’s display name contains a different e-mail address than the one the message was sent from”;from-has-bidi-or-invisible-charactersdescribes hidden characters in the sender line that can reorder or hide what it shows;from-domain-resembles-served-domaindescribes a sender domain that looks like the organisation’s own but is not;attachment-name-has-bidi-or-invisible-charactersdescribes an attachment name that may show a different file type; and the four[external]warnings are explained likewise. In Thunderbird, such a warning also turns the badge red when the verdict is otherwise good or neutral (verified, decrypted, for-client or none), since the message then has the shape of a phishing message;a note when the sender’s mail usually carries a verified signature and this message does not (
usually-signed, with the date of the last one);a note when a mailing list added the
Reply-To:outside the signature (reply-to=unsigned) and when the signed subject is shown in place of a changed one (subject=protected);notes on the message’s structure: a
protected-mismatch(the signed copy ofFrom:,To:orSubject:differs from the displayed one), what isolation separated from the protected part (isolated,demoted,dropped);the facts:
signature,signer,bound-to,fingerprint,key-source,trust,algorithm,binding,anchor,withheld,unsigned-surface,signer-domain,protocol,container,layers,encrypted,decrypted, and the failure reasons. A key that the extension does not know is listed under its raw name rather than dropped, so an older extension beside a newer gateway degrades to an unexplained line, not to silence.
Every value is placed as text. A signer name comes from a certificate that the sender supplied; the gateway has already sanitised it for header syntax (pepsi-stage-decrypt), and the extension never interprets it as markup.
20.2. What it proves, and what it does not¶
The display is only as good as the field, and the field is trustworthy for
one reason: ingress and the decrypt stage remove every inbound X-Pepsi-*
field before the gateway writes its own (Header forgery). A
mailbox behind Pepsi therefore sees the gateway’s field or none. The
extensions do not, and cannot, check that the message came through Pepsi: on
a mailbox that also receives mail by another route, a stranger’s
X-Pepsi-Crypto reaches the client intact and is rendered. Deploy them
where the mail system accepts the managed domains only from Pepsi, which the Exchange chapter requires anyway.
A green headline means what valid means in What a security indicator means: a
signature over the plaintext by a key that the gateway trusts for the sender’s
address. It does not mean that the sender is who the display name says (the
warning line is there for that), and it does not mean that the content is safe.
Nothing changes for clients that the extensions do not cover: webmail, mobile clients and every other desktop client show the subject tags and nothing else. The tags remain in-band (Security status spoofed in-band in message body or headers).
20.3. Outlook: the read pane¶
The Outlook add-in (The Outlook add-in) carries both panes. Once the administrator has sideloaded its manifest, a user who reads a message finds a Gateway verdict button in the ribbon, which opens the pane. Older clients show the button in the add-in bar below the message. The pane can be pinned, and a pinned pane follows the selection. The compose pane, Protect message, is unchanged.
Requirements: the read pane uses getAllInternetHeadersAsync (Outlook
Mailbox requirement set 1.8; Outlook on the web, the new Outlook on Windows,
Outlook 2019 and later, and Outlook on Mac). On an older client the pane
opens and says that it cannot read headers; the compose pane still works
there, which is why the manifest’s floor stays at 1.3.
The assets are /addin/readpane.html, /addin/pepsi-crypto.js and the
icons /addin/icon-*.png, served by pepsi-httpd beside the manifest
and the compose pane under the same [pepsi-httpd] ADDIN switch
(pepsi-httpd). Office’s own JavaScript library is loaded from
Microsoft’s CDN, as every Office add-in’s is.
20.5. Remote content¶
A message the gateway decrypted arrives in the mailbox as an ordinary
message. Its HTML is delivered as it came out of the ciphertext
(pepsi-stage-decrypt, DECRYPTED_MARKUP = keep), and it
can still load remote content: an image, a stylesheet or a font fetched
from the sender’s server tells the sender that, when and roughly where the
message was read, and CSS can fingerprint the client. Unencrypted HTML mail
does the same, and a tracking pixel in a newsletter is the common case. Unless
the reader turned on pepsi-stage-defang (below), the mail
client decides whether those requests happen. This matters more behind Pepsi
than elsewhere. Some clients treat encrypted mail with extra care: they block
remote content in it, or refuse to mix it with other parts. Such a client
cannot tell that this message was encrypted. Set the client to block remote
content in all mail:
Thunderbird: Settings → Privacy & Security → Mail Content: leave Allow remote content in messages unticked (the default), and grant exceptions per sender only to senders you trust.
Outlook (classic, Windows): File → Options → Trust Center → Trust Center Settings → Automatic Download: tick Don’t download pictures automatically in standard HTML email messages or RSS items (the default). The new Outlook and Outlook on the web fetch remote images through Microsoft’s own proxy, which hides the reader’s address but still tells the sender that the message was opened; block external images under Settings → Mail → Privacy and data where the tenant allows it.
Apple Mail: Settings → Privacy: Protect Mail Activity loads remote content through a relay that hides the reader’s address and time; Block All Remote Content blocks it, which is what is meant here.
K-9 Mail / Thunderbird for Android: Settings → General settings → Display: Show images set to Never (or to contacts only).
FairEmail: remote images are not shown by default; keep Settings → Privacy → Confirm showing images on.
The gateway can also take the remote references out before the message is
filed. pepsi-setup --wizard wires pepsi-stage-defang on
every installation that delivers mail locally, switched off. A user turns it
on with DEFANG = on, by settings mail or pepsi-settings
(Using Pepsi: a guide for users). The stage then removes from that user’s HTML everything
that the HTML would load by itself: remote images, style sheets, fonts,
frames, url() and @import. Links, cid: parts and inline data:
images stay. The stage marks the message X-Pepsi-Warning:
remote-content-defanged, which both extensions show as a note. It leaves
alone what a client verifies again (a multipart/signed, an S/MIME signed or
encrypted part, an inline OpenPGP block), so a signed HTML message keeps its
references, and the client setting is still what protects it. Neither replaces
the other: the stage works for every client that the user reads with, and the
setting covers what the stage must leave alone.
A site whose users cannot be relied on to keep such a setting can make the
choice for them: DECRYPTED_MARKUP = text delivers every decrypted
plaintext as plain text, for everyone or, through a pepsi-config
overlay, for chosen addresses, at the price of the formatting of every
encrypted message. A plaintext from a container without integrity
protection that no signature covers is reduced that way whatever the setting
says (UNAUTHENTICATED_PLAINTEXT = text).