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;hrefon any element but<a>and<area>(<link>keeps onlycid:, SVG elements keep references to a fragment of the document,#id);any
srcof<iframe>,<frame>and<embed>, anddataof<object>, since a framed document loads what it likes;ping,attributionsrc,srcdoc,manifest,codebaseandarchiveon every element;url(),@importand URL strings (image-set("..."), a custom property’s string) instyleattributes,<style>elements,text/cssparts and the SVG properties that take a URL (fill,filter,mask,clip-path,marker,cursor, …), replaced by the keywordnone; SVG animation may not set anhref;<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
onoroff(defaultoff). 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, elseinfo).- -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 (DEFANGneitheronnoroff).
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.