95.1.41. pepsi-stage-defang

neutralise the remote references in HTML messages

Manual section:

1

95.1.41.1.1. Name

pepsi-stage-defang - the remote-content stage of the Pepsi pipeline.

95.1.41.1.2. Synopsis

pepsi-stage-defang [GLOBAL-OPTIONS] worker

95.1.41.1.3. Description

pepsi-stage-defang is a stage program run by pepsi-dispatch(1) as a persistent worker reading message ids on standard input. When DEFANG is on for a message’s recipient, the stage removes everything that the message’s HTML would load from the network by itself when it is displayed, so that opening the message tells its sender nothing. A one-pixel image with a per-recipient URL reports who read a mail, when, from which address and with which program. The same mechanism lets a decrypted HTML part send its own plaintext to an attacker’s server (EFAIL’s direct exfiltration).

DEFANG is off by default and meant to be turned on per address, by the address’s owner: pepsi-settings set ADDRESS STAGE DEFANG on, or a settings mail to pepsi-stage-edit-settings(1) when the stage is listed in its EDITABLE_STAGES. A message whose recipients differ is split first, so each copy is treated as its recipient chose. While DEFANG is off for a message, the stage advances the message untouched. The stage defaults to FUSION = yes. Folded into the unified pepsi binary, it passes a message on its metadata alone, without loading the body, when DEFANG is certainly off for it (off in the section, and no override for any of the message’s addresses).

95.1.41.1.4. What is rewritten

The stage rewrites every text/html, application/xhtml+xml and text/x-amp-html part, at any depth and whatever its Content-Disposition, and every text/css part, including those of attached messages. A part is decoded from its transfer-encoding and its charset and encoded again in the same transfer-encoding. Some charsets do not write ASCII text as ASCII bytes (ISO-2022-JP, Shift_JIS, UTF-16, …); a part in such a charset is read in that charset and written back as UTF-8, with its charset label changed.

The stage removes the following, unless the reference names a part of the message itself (cid:) or an image, sound or video carried inline (data:image/..., data:audio/..., data:video/...):

  • the attributes that load a resource: src, srcset, imagesrcset, lowsrc, dynsrc, poster, background; href on any element but <a> and <area> (<link> keeps only cid:, SVG elements keep references to a fragment of the document, #id);

  • any src of <iframe>, <frame> and <embed>, and data of <object>, since a framed document loads what it likes;

  • ping, attributionsrc, srcdoc, manifest, codebase and archive on every element;

  • url(), @import and URL strings (image-set("..."), a custom property’s string) in style attributes, <style> elements, text/css parts and the SVG properties that take a URL (fill, filter, mask, clip-path, marker, cursor, …), replaced by the keyword none; SVG animation may not set an href;

  • <base href>, <meta http-equiv="refresh"> and <meta http-equiv="link">; <script> with its content.

A removed attribute is removed, not kept under another name, so no client can put it back. Links (<a href>, <area href>) and forms stay: nothing is fetched until the reader acts. A relative reference goes too, because a Content-Base or Content-Location field can point it anywhere.

The stage reads the HTML the way a browser reads it, following the HTML tokenizer’s own rules for tag ends, quoting, comments and raw text. A rewriter that reads a tag differently from the client is one that an attacker can write around. In some places the reading depends on the document tree: <style>, <title> and the other raw-text elements are text in HTML but markup inside <svg>, <math>, <select> and <frameset>. There the output is made to read the same either way. <noscript> loses its tags and keeps its content. Comment bodies are rewritten too, since Outlook renders the markup in its conditional comments. A MIME tree nested deeper than 32 levels cannot be checked, and its too-deep part is replaced by a short note.

95.1.41.1.5. What is never touched

The stage leaves alone what a client verifies again: a multipart/signed and everything inside it, an application/pkcs7-mime part (signed or still encrypted), a multipart/encrypted, and an HTML part that carries an inline OpenPGP block. Such a part keeps its remote references, and the stage logs how many it left alone. Plaintext that pepsi-stage-decrypt(1) produced is ordinary content.

A message the stage changed carries X-Pepsi-Warning: remote-content-defanged at the top of its header; the Outlook and Thunderbird extensions show it as a note, not as a warning. A message with nothing to neutralise is passed on byte for byte.

95.1.41.1.6. Placement

The stage belongs after every stage that verifies or reads the content (pepsi-stage-decrypt(1), pepsi-stage-dmarc-report(1), the whitelist and payment gates, pepsi-stage-autocrypt-learn(1)). It also belongs after pepsi-stage-dot-forward(1), so that a forwarded copy keeps the bytes that its DKIM and ARC signatures cover, and before pepsi-stage-reencrypt(1), which seals what it is handed. This is where pepsi-setup –wizard puts it, with DEFANG = off, on every installation that delivers mail locally; the wizard also lists it in EDITABLE_STAGES when it configures the settings editor.

95.1.41.1.7. Configuration

Options live in the stage’s own [stage-<name>] section (PROGRAM = pepsi-stage-defang):

NEXT_STAGE

Where every message goes, rewritten or not. Required.

DEFANG

on or off (default off). Read after per-address settings are applied; it is what a user turns on for their own mail.

Listing the stage in EDITABLE_STAGES hands users nothing but this switch: the stage has no branch target and only ever removes what is shown.

95.1.41.1.8. State

Inputs: none.

Outputs: none; the stage records its work in the X-Pepsi-Warning field and the log. The state layout is described in pepsi.state(7).

Transitions: always advances to NEXT_STAGE. Any error is retried as usual (see pepsi-dispatch(1)); a section that does not parse refuses the worker’s start, and a per-address value that does not parse fails the message.

95.1.41.1.9. Commands

worker

Run as a persistent pepsi-dispatch(1) worker, reading message ids on standard input.

95.1.41.1.10. Global Options

-c FILE, –config FILE

Read the configuration from FILE instead of searching the default locations.

-L LOGLEVEL, –log LOGLEVEL

Set the logging verbosity (default [pepsi] LOG, else info).

-v, –verbose

Show log messages from all sources.

-h, –help; -V, –version

Print a usage summary / the version and exit.

95.1.41.1.11. Exit Status

The outcome of each message is reported to pepsi-dispatch(1) on the worker’s status line, not as the exit status.

0

The worker ran until its standard input was closed.

1

A fatal error occurred (unreadable configuration, the database could not be opened, or standard input/output failed). The reason is written to the log.

78

The worker refused to start: a [stage-*] section it serves does not parse (DEFANG neither on nor off).

95.1.41.1.12. Examples

The section pepsi-setup –wizard writes:

[stage-defang]
PROGRAM = pepsi-stage-defang
NEXT_STAGE = reencrypt
DEFANG = off

Turning it on for one address:

pepsi-settings set alice@example.org defang DEFANG on

The same by mail, from Alice’s own account, to the settings editor’s address (by default pepsi@ the domain, subject Pepsi):

[stage-defang]
DEFANG = on

95.1.41.1.13. See Also

pepsi-settings(1), pepsi-stage-edit-settings(1), pepsi-stage-decrypt(1), pepsi-stage-reencrypt(1), pepsi-dispatch(1), pepsi.conf(5), pepsi.state(7)

95.1.41.1.14. Bugs

Report bugs to the Pepsi issue tracker.