.. This file is part of PEPSI. Copyright (C) 2026 GNUnet e.V. PEPSI is free software; you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version. PEPSI is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. .. _mail-client-extensions: ====================== 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 (:ref:`sec-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. :ref:`tm-indicators` 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. What is shown ============= The verdict is one headline with an explanation, coloured by severity, then any warnings, then the facts the gateway recorded: .. list-table:: :header-rows: 1 :widths: 24 76 * - Headline - When * - **Verified: signed by …** (green) - ``signature=valid``: a signature over the content verified against a key that the gateway trusts for the sender, and the signer matches the ``From:`` address. The pane shows the address to which the signature is bound (``bound-to``), or else the signer as the gateway recorded it. * - **Decrypted by the gateway; sender not verified** (blue) - ``decrypted=yes`` without a credited signature. Says nothing about who sent the message. * - **Encrypted to your own key** (blue) - ``for-client=yes``: passed through unopened for a key held in the client. The client's own display applies. * - **No gateway verdict** (grey) - No ``X-Pepsi-Crypto`` field: the message carried no protection, or never crossed a decrypt stage. Shown identically for both, because the extension cannot tell them apart and must not guess. * - **No protection recorded** (grey) - An ``X-Pepsi-Crypto`` field that records neither encryption nor a signature. * - **Signed, but not credited to the sender** (amber) - ``signature=valid-untrusted`` with ``withheld``: the signature verifies, but a binding rule withheld it (a protected ``From:``, ``Reply-To:`` or forged subject tag, a nameless certificate, a display name or several ``From:`` mailboxes, a look-alike domain), and the reason is spelled out. * - **Only part of what you see is signed** (amber) - ``signature=partial``: a verified clearsigned block beside text the signature does not cover (``unsigned-surface``). * - **Signed with a key nobody vouches for** (amber) - ``signature=valid-untrusted``. The signature verifies, but anyone can produce one with a key that nothing anchors. Rendered like unsigned mail with an explanation, **never** as verified. * - **Signed, but the signature could not be checked** (amber) - ``signature=unverifiable``, with the recorded ``failure`` reason. * - **Encrypted; could not be opened here** (amber) - ``encrypted=yes; decrypted=no``, with ``decrypt-failure`` when recorded. * - **Decrypted, but nobody vouches for the content** (red) - ``unauthenticated=yes``: a plaintext from a container without integrity protection that no signature covers; whether it was reduced to plain text (``sanitised=text``) is said. * - **Signature invalid** (red) - ``signature=invalid``, with the ``failure`` reason and a reminder that mailing lists cause this on legitimate mail. * - **Conflicting gateway verdicts** (red) - More than one ``X-Pepsi-Crypto`` field. The gateway writes exactly one, so the message was altered after it left, or came through a path that does not strip the field; none of them is believed. Below the headline: * every ``X-Pepsi-Warning`` as its own red line, spelled out in words. ``display-name-claims-other-address`` reads "the sender's display name contains a different e-mail address than the one the message was sent from"; ``from-has-bidi-or-invisible-characters`` describes hidden characters in the sender line that can reorder or hide what it shows; ``from-domain-resembles-served-domain`` describes a sender domain that looks like the organisation's own but is not; ``attachment-name-has-bidi-or-invisible-characters`` describes 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 of ``From:``, ``To:`` or ``Subject:`` 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 (:doc:`programs/pepsi-stage-decrypt`), and the extension never interprets it as markup. 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 (:ref:`sec-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 :ref:`accepts the managed domains only from Pepsi `, which the Exchange chapter requires anyway. A green headline means what ``valid`` means in :ref:`tm-indicators`: 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 (:ref:`lit-in-band-indicator-spoofing`). .. _outlook-read-pane: Outlook: the read pane ====================== The Outlook add-in (:ref:`exchange-addin`) 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 (:doc:`programs/pepsi-httpd`). Office's own JavaScript library is loaded from Microsoft's CDN, as every Office add-in's is. .. _thunderbird-extension: Thunderbird: the verdict button =============================== The Thunderbird extension is a MailExtension (manifest version 2, Thunderbird 115 or later; it uses ``messages.getFull`` under the ``messagesRead`` permission, and nothing else). It adds a **Gateway** button to the message header toolbar. Whenever a message is displayed, the button's badge shows one mark coloured by the verdict, and its tooltip carries the headline. The badge shows a green tick for verified; a blue dot for decrypted or for-client; nothing for no verdict; an amber question mark for untrusted, unverifiable or unopened; and a red exclamation mark or cross for the red rows above and for a warning beside a green, blue or grey verdict. Clicking the button opens the full verdict. A banner inside the rendered message was deliberately not used: Thunderbird can inject one (``messageDisplayScripts``), but it would sit inside the message area, where a sender can place a look-alike. **Installing it.** ``make install`` puts the unpacked extension under ``${DATADIR}/thunderbird/`` (``/usr/share/pepsi/thunderbird/`` on Debian), and ``make thunderbird-xpi`` zips it into ``target/pepsi-verdict.xpi`` (``THUNDERBIRD_XPI=`` names another path). Without a source tree, the installed directory zips the same way: .. code-block:: sh cd /usr/share/pepsi/thunderbird && zip -r ~/pepsi-verdict.xpi . In Thunderbird, open *Add-ons and Themes*, choose *Install Add-on From File…* from the gear menu, and pick the ``.xpi``. For development, *Debug Add-ons* → *Load Temporary Add-on…* takes the directory's ``manifest.json`` directly. The extension is not listed on addons.thunderbird.net; it is signed by nobody, so Thunderbird asks for confirmation on installation and an enterprise policy (``ExtensionSettings``) is the way to roll it out to many users. An organisation that wants its users to see the verdict on a client not covered here can start from the parser. .. _clients-remote-content: 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 (:doc:`programs/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 :doc:`programs/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 :doc:`programs/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`` (:doc:`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``).