Memory Hole Implementation Guidance


This document contains information on interpreting and generating memory hole compliant e-mails.

Please see the specification’s glossary for terms used in this document.

Generating: The specification permits MUAs to protect any e-mail header. However, implementors should note that encrypting some headers may have unexpected consequences. We, therefore, recommend protecting only some headers by default; more details are provided below.

Interpreting: while implementors are urged to only protect some headers by default, MUAs must be prepared to correctly interpret e-mails with any combination of protected headers. Advice on how to display memory-hole compliant emails is provided below.

We recommend that MUAs considering Memory Hole should start by adding message interpretation, and only enable message generation by default after interpretation is known to work properly.

Interpreting memory-hole compliant e-mails

  • Which header is ultimately displayed?

    Signed & encrypted, then signed, then encrypted, then unprotected

Generating memory-hole compliant emails

We recommend protecting all headers that might be relevant to the message. You can protect a header by including a copy of it in the top-level MIME part within the inner-most protection layer.

You may also want to obscure (remove or replace with a dummy) some headers from the external header if they are protected by an encryption layer. Guidance about obscuring is distinct from guidance about inclusion in protection layers. Initial implementations SHOULD obscure Subject: header lines when generating encrypted mail, and MAY obscure other header lines. See the “Consequences” section below for thoughts about other headers.

You may also want to make some protected headers explicitly visible to users who have MUAs that do not understand Memory Hole. We call these headers “force-displayed”. Selecting specific headers to force-display presents a usability tradeoff — they may appear noisy to recipients using legacy MUAs. memory-hole generating MUAs SHOULD force-display the Subject: header, MAY force-display From, To, and Cc headers, and SHOULD NOT force-display other headers.

Extent of protection

  • Obscured + protected: tamper-proofed within at least one encryption layer, and also stripped/stubbed
  • Protected: headers are copied into the top-level MIME part of the inner-most protection layer
  • Ignored

Message composition

All protection layers should be outside all protected parts of the message. Do not interleave protection layers with other MIME parts. The Content-Type of a message with any protection layers should be a protection layer.

FIXME: provide good/bad MIME tree examples.

Consequences of obscuring specific headers

  • Subject: we think there are no significant negative consequences to obscuring the Subject, and most users naively expect that the Subject of encrypted mail should be obscured anyway.
  • From
  • To
    • Separate emails to separate recipients, or is this issue orthogonal?


Don’t scare users unnecessarily. 🙂 The current situation is that users are not notified of tampered headers anyway. Therefore staying silent about tampered headers by default does not make anything worse.

In the future, there may be clever ways of alerting users to MITM attacks with a very low number of false positives: * by using a white/blacklist, or * by the MUA ‘learning’ and ignoring emails that are always tampered with (mailing lists) and warning about emails that usually are not tampered with (personal correspondence)

Thwart attacks where possible, which in this case means undo tampering by recovering original content from the protected headers. Log when attacks happen to document patterns of misbehaviour for people who want more info. Be cautious about explicit warnings because of “alert fatigue”. Provide clean settings (with sensible defaults) to allow users to see more warnings/logs if they want.


breakage of some legacy systems

There are some existing mail systems that typically modify message headers. For example:

  • mailman (mailing lists) modifies the Subject: header lie by prefixing it with [listname].
  • RT (request tracker) puts ticket ID numbers in the Subject: header line.

These systems are in principle indistinguishable from a MiTM that we are trying to defend against. To the extent that Memory Hole defends against tampered headers, it is likely to also break the modifications made by these systems when those systems process protected mail.

Memory Hole does not try to enable these legacy systems, though there may be ways that they can interoperate better than complete breakage. if someone working on such a system wants to discuss it, please do.