< draft-dkg-lamps-e2e-mail-guidance-00.txt		draft-dkg-lamps-e2e-mail-guidance-01.txt >
	lamps D.K. Gillmor		lamps D.K. Gillmor
	Internet-Draft ACLU		Internet-Draft ACLU
	Intended status: Informational 31 October 2020		Intended status: Informational 22 February 2021
	Expires: 4 May 2021		Expires: 26 August 2021
	Guidance on End-to-End E-mail Security		Guidance on End-to-End E-mail Security
	draft-dkg-lamps-e2e-mail-guidance-00		draft-dkg-lamps-e2e-mail-guidance-01
	Abstract		Abstract
	End-to-end cryptographic protections for e-mail messages can provide		End-to-end cryptographic protections for e-mail messages can provide
	useful security. However, the standards for providing cryptographic		useful security. However, the standards for providing cryptographic
	protection are extremely flexible. That flexibility can trap users		protection are extremely flexible. That flexibility can trap users
	and cause surprising failures. This document offers guidance for		and cause surprising failures. This document offers guidance for
	mail user agent implementers that need to compose or interpret e-mail		mail user agent implementers that need to compose or interpret e-mail
	messages with end-to-end cryptographic protection. It provides a		messages with end-to-end cryptographic protection. It provides a
	useful set of vocabulary as well as suggestions to avoid common		useful set of vocabulary as well as suggestions to avoid common
	skipping to change at page 1, line 37 ¶		skipping to change at page 1, line 37 ¶
	Internet-Drafts are working documents of the Internet Engineering		Internet-Drafts are working documents of the Internet Engineering
	Task Force (IETF). Note that other groups may also distribute		Task Force (IETF). Note that other groups may also distribute
	working documents as Internet-Drafts. The list of current Internet-		working documents as Internet-Drafts. The list of current Internet-
	Drafts is at https://datatracker.ietf.org/drafts/current/.		Drafts is at https://datatracker.ietf.org/drafts/current/.
	Internet-Drafts are draft documents valid for a maximum of six months		Internet-Drafts are draft documents valid for a maximum of six months
	and may be updated, replaced, or obsoleted by other documents at any		and may be updated, replaced, or obsoleted by other documents at any
	time. It is inappropriate to use Internet-Drafts as reference		time. It is inappropriate to use Internet-Drafts as reference
	material or to cite them other than as "work in progress."		material or to cite them other than as "work in progress."
	This Internet-Draft will expire on 4 May 2021.		This Internet-Draft will expire on 26 August 2021.
	Copyright Notice		Copyright Notice
	Copyright (c) 2020 IETF Trust and the persons identified as the		Copyright (c) 2021 IETF Trust and the persons identified as the
	document authors. All rights reserved.		document authors. All rights reserved.
	This document is subject to BCP 78 and the IETF Trust's Legal		This document is subject to BCP 78 and the IETF Trust's Legal
	Provisions Relating to IETF Documents (https://trustee.ietf.org/		Provisions Relating to IETF Documents (https://trustee.ietf.org/
	license-info) in effect on the date of publication of this document.		license-info) in effect on the date of publication of this document.
	Please review these documents carefully, as they describe your rights		Please review these documents carefully, as they describe your rights
	and restrictions with respect to this document. Code Components		and restrictions with respect to this document. Code Components
	extracted from this document must include Simplified BSD License text		extracted from this document must include Simplified BSD License text
	as described in Section 4.e of the Trust Legal Provisions and are		as described in Section 4.e of the Trust Legal Provisions and are
	provided without warranty as described in the Simplified BSD License.		provided without warranty as described in the Simplified BSD License.
	Table of Contents		Table of Contents
	1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3		1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
	1.1. Requirements Language . . . . . . . . . . . . . . . . . . 3		1.1. Requirements Language . . . . . . . . . . . . . . . . . . 3
	1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3		1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4
	1.2.1. Structural Headers . . . . . . . . . . . . . . . . . 4		1.2.1. Structural Headers . . . . . . . . . . . . . . . . . 4
	2. Usability . . . . . . . . . . . . . . . . . . . . . . . . . . 4		2. Usability . . . . . . . . . . . . . . . . . . . . . . . . . . 4
	3. Types of Protection . . . . . . . . . . . . . . . . . . . . . 4		2.1. Simplicity . . . . . . . . . . . . . . . . . . . . . . . 5
	4. Cryptographic MIME Message Structure . . . . . . . . . . . . 5		2.2. E-mail Users Want a Familiar Experience . . . . . . . . . 5
	4.1. Cryptographic Layers . . . . . . . . . . . . . . . . . . 5		2.3. Warning About Failure vs. Announcing Success . . . . . . 6
	4.1.1. S/MIME Cryptographic Layers . . . . . . . . . . . . . 5		3. Types of Protection . . . . . . . . . . . . . . . . . . . . . 7
	4.1.2. PGP/MIME Cryptographic Layers . . . . . . . . . . . . 6		4. Cryptographic MIME Message Structure . . . . . . . . . . . . 7
	4.2. Cryptographic Envelope . . . . . . . . . . . . . . . . . 7		4.1. Cryptographic Layers . . . . . . . . . . . . . . . . . . 7
	4.3. Cryptographic Payload . . . . . . . . . . . . . . . . . . 7		4.1.1. S/MIME Cryptographic Layers . . . . . . . . . . . . . 7
	4.4. Types of Cryptographic Envelope . . . . . . . . . . . . . 7		4.1.2. PGP/MIME Cryptographic Layers . . . . . . . . . . . . 8
	4.4.1. Simple Cryptographic Envelopes . . . . . . . . . . . 8		4.2. Cryptographic Envelope . . . . . . . . . . . . . . . . . 9
	4.4.2. Multilayer Cryptographic Envelopes . . . . . . . . . 8		4.3. Cryptographic Payload . . . . . . . . . . . . . . . . . . 10
	4.5. Errant Crytptographic Layers . . . . . . . . . . . . . . 8		4.4. Types of Cryptographic Envelope . . . . . . . . . . . . . 10
	4.5.1. Mailing List Wrapping . . . . . . . . . . . . . . . . 8		4.4.1. Simple Cryptographic Envelopes . . . . . . . . . . . 10
	4.5.2. A Baroque Example . . . . . . . . . . . . . . . . . . 9		4.4.2. Multilayer Cryptographic Envelopes . . . . . . . . . 10
	5. Message Composition . . . . . . . . . . . . . . . . . . . . . 10		4.5. Errant Crytptographic Layers . . . . . . . . . . . . . . 10
	5.1. Message Composition Algorithm . . . . . . . . . . . . . . 10		4.5.1. Mailing List Wrapping . . . . . . . . . . . . . . . . 11
	5.2. Encryption Outside, Signature Inside . . . . . . . . . . 11		4.5.2. A Baroque Example . . . . . . . . . . . . . . . . . . 11
	5.3. Avoid Offering Encrypted-only Messages . . . . . . . . . 11		5. Message Composition . . . . . . . . . . . . . . . . . . . . . 12
	5.4. Composing a Reply Message . . . . . . . . . . . . . . . . 12		5.1. Message Composition Algorithm . . . . . . . . . . . . . . 12
	6. Message Interpretation . . . . . . . . . . . . . . . . . . . 12		5.2. Encryption Outside, Signature Inside . . . . . . . . . . 13
	6.1. Rendering Well-formed Messages . . . . . . . . . . . . . 12		5.3. Avoid Offering Encrypted-only Messages . . . . . . . . . 13
	6.2. Errant Cryptographic Layers . . . . . . . . . . . . . . . 13		5.4. Composing a Reply Message . . . . . . . . . . . . . . . . 14
	6.2.1. Errant Signing Layer . . . . . . . . . . . . . . . . 13		6. Message Interpretation . . . . . . . . . . . . . . . . . . . 14
	6.2.2. Errant Encryption Layer . . . . . . . . . . . . . . . 14		6.1. Rendering Well-formed Messages . . . . . . . . . . . . . 15
	6.3. Forwarded Messages with Cryptographic Protection . . . . 15		6.2. Errant Cryptographic Layers . . . . . . . . . . . . . . . 15
	6.4. Signature failures . . . . . . . . . . . . . . . . . . . 16		6.2.1. Errant Signing Layer . . . . . . . . . . . . . . . . 15
	7. Common Pitfalls and Guidelines . . . . . . . . . . . . . . . 16		6.2.2. Errant Encryption Layer . . . . . . . . . . . . . . . 17
	8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17		6.3. Forwarded Messages with Cryptographic Protection . . . . 17
	9. Security Considerations . . . . . . . . . . . . . . . . . . . 17		6.4. Signature failures . . . . . . . . . . . . . . . . . . . 18
	10. Document Considerations . . . . . . . . . . . . . . . . . . . 17		7. Certificate Management . . . . . . . . . . . . . . . . . . . 19
	10.1. Document History . . . . . . . . . . . . . . . . . . . . 17		7.1. Peer Certificates . . . . . . . . . . . . . . . . . . . . 19
	11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 17		7.1.1. Cert Discovery from Incoming Messages . . . . . . . . 19
	12. References . . . . . . . . . . . . . . . . . . . . . . . . . 17		7.1.2. Certificate Directories . . . . . . . . . . . . . . . 19
	12.1. Normative References . . . . . . . . . . . . . . . . . . 17		7.1.3. Peer Certificate Selection . . . . . . . . . . . . . 19
	12.2. Informative References . . . . . . . . . . . . . . . . . 18		7.1.4. Checking for Revocation . . . . . . . . . . . . . . . 20
	Appendix A. Test Vectors . . . . . . . . . . . . . . . . . . . . 19		7.2. Local Certificates . . . . . . . . . . . . . . . . . . . 20
	Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 19		7.2.1. Getting a Certificate for the User . . . . . . . . . 20
			7.2.2. Local Certificate Maintenance . . . . . . . . . . . . 21
			7.2.3. Shipping Certificates in Outbound Messages . . . . . 21
			7.3. Certificate Authorities . . . . . . . . . . . . . . . . . 22
			8. Common Pitfalls and Guidelines . . . . . . . . . . . . . . . 22
			9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22
			10. Security Considerations . . . . . . . . . . . . . . . . . . . 23
			11. Document Considerations . . . . . . . . . . . . . . . . . . . 23
			11.1. Document History . . . . . . . . . . . . . . . . . . . . 23
			11.1.1. Substantive changes from -00 to -01 . . . . . . . . 23
			12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 23
			13. References . . . . . . . . . . . . . . . . . . . . . . . . . 23
			13.1. Normative References . . . . . . . . . . . . . . . . . . 23
			13.2. Informative References . . . . . . . . . . . . . . . . . 24
			Appendix A. Test Vectors . . . . . . . . . . . . . . . . . . . . 25
			Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 25
	1. Introduction		1. Introduction
	E-mail end-to-end security using S/MIME [RFC8551] and PGP/MIME		E-mail end-to-end security using S/MIME ([RFC8551]) and PGP/MIME
	[RFC3156] cryptographic standards can provide integrity,		([RFC3156]) cryptographic standards can provide integrity,
	authentication and confidentiality to MIME e-mail messages [RFC4289].		authentication and confidentiality to MIME ([RFC4289]) e-mail
			messages.
	However, there are many ways that a receiving mail user agent can		However, there are many ways that a receiving mail user agent can
	misinterpret or accidentally break these security guarantees (e.g.,		misinterpret or accidentally break these security guarantees (e.g.,
	[EFAIL]).		[EFAIL]).
	A mail user agent that interprets a message with end-to-end		A mail user agent that interprets a message with end-to-end
	cryptographic protections needs to do so defensively, staying alert		cryptographic protections needs to do so defensively, staying alert
	to different ways that these protections can be bypassed by mangling		to different ways that these protections can be bypassed by mangling
	(either malicious or accidental) or a failed user experience.		(either malicious or accidental) or a failed user experience.
	skipping to change at page 4, line 6 ¶		skipping to change at page 4, line 20 ¶
	* _Protection_ of message data refers to cryptographic encryption		* _Protection_ of message data refers to cryptographic encryption
	and/or signatures, providing confidentiality, authenticity, and/or		and/or signatures, providing confidentiality, authenticity, and/or
	integrity.		integrity.
	* _Cryptographic Layer_, _Cryptographic Envelope_, _Cryptographic		* _Cryptographic Layer_, _Cryptographic Envelope_, _Cryptographic
	Payload_, and _Errant Cryptographic Layer_ are defined in		Payload_, and _Errant Cryptographic Layer_ are defined in
	Section 4		Section 4
	* A _well-formed_ e-mail message with cryptographic protection has		* A _well-formed_ e-mail message with cryptographic protection has
	both a _Cryptographic Envelope_ and a _Cryptographic Payload_,		both a _Cryptographic Envelope_ and a _Cryptographic Payload_.
	* _Structural Headers_ are documented in Section 1.2.1.		* _Structural Headers_ are documented in Section 1.2.1.
	1.2.1. Structural Headers		1.2.1. Structural Headers
	A message header whose name begins with "Content-" is referred to in		A message header whose name begins with "Content-" is referred to in
	this document as a "structural" header.		this document as a "structural" header.
	These headers indicate something about the specific MIME part they		These headers indicate something about the specific MIME part they
	are attached to, and cannot be transferred or copied to other parts		are attached to, and cannot be transferred or copied to other parts
	skipping to change at page 4, line 32 ¶		skipping to change at page 4, line 46 ¶
	* "Content-Transfer-Encoding"		* "Content-Transfer-Encoding"
	* "Content-Disposition"		* "Content-Disposition"
	FIXME: are there any non-"Content-*" headers we should consider as		FIXME: are there any non-"Content-*" headers we should consider as
	structural?		structural?
	2. Usability		2. Usability
			Any MUA that enables its user to transition from unprotected messages
			to messages with end-to-end cryptographic protection needs to
			consider how the user understands this transition. That said, the
			primary goal of the user of an MUA is communication -- so interface
			elements that get in the way of communication should be avoided where
			possible.
			Furthermore, it is likely is that the user will continue to encounter
			unprotected messages, and may need to send unprotected messages (for
			example, if a given recipient cannot handle cryptographic
			protections). This means that the MUA needs to provide the user with
			some guidance, so that they understand what protections any given
			message or conversation has. But the user should not be overwhelmed
			with choices or presented with unactionable information.
			2.1. Simplicity
	The end user (the operator of the MUA) is unlikely to understand		The end user (the operator of the MUA) is unlikely to understand
	complex end-to-end cryptographic protections on any e-mail message,		complex end-to-end cryptographic protections on any e-mail message,
	so keep it simple.		so keep it simple.
	For clarity to the user, any cryptographic protections should apply		For clarity to the user, any cryptographic protections should apply
	to the message as a whole, not just to some subparts.		to the message as a whole, not just to some subparts.
	This is true for message composition: the standard message		This is true for message composition: the standard message
	composition user interface of an MUA should offer minimal controls		composition user interface of an MUA should offer minimal controls
	which indicate which types of protection to apply to the new message		which indicate which types of protection to apply to the new message
	as a whole.		as a whole.
	This is also true for message interpretation: the standard message		This is also true for message interpretation: the standard message
	rendering user interface of an MUA should offer a minimal, clear		rendering user interface of an MUA should offer a minimal, clear
	indicator about the end-to-end cryptographic status of the message as		indicator about the end-to-end cryptographic status of the message as
	a whole.		a whole.
			2.2. E-mail Users Want a Familiar Experience
			A person communicating over the Internet today often has many options
			for reaching their desired correspondent, including web-based
			bulletin boards, contact forms, and instant messaging services.
			E-mail offers a few distinctions from these other systems, most
			notably features like:
			* Ubiquity: Most correspondents will have an e-mail address, while
			not everyone is present on every alternate messaging service,
			* Federation: interaction between users on distinct domains who have
			not agreed on a common communications provider is still possible,
			and
			* User Control: the user can interact with the e-mail system using a
			MUA of their choosing, including automation and other control over
			their preferred and/or customized workflow.
			Other systems (like some popular instant messaging applications, such
			as WhatsApp and Signal Private Messenger) offer built-in end-to-end
			cryptographic protections by default, which are simpler for the user
			to understand. ("All the messages I see on Signal are confidential
			and integrity-protected" is a clean user story)
			A user of e-mail is likely using e-mail instead of other systems
			because of the distinctions outlined above. When adding end-to-end
			cryptographic protection to an e-mail endpoint, care should be taken
			not to negate any of the distinct features of e-mail as a whole. If
			these features are violated to provide end-to-end crypto, the user
			may just as well choose one of the other systems that don't have the
			drawbacks that e-mail has. Implmenters should try to provide end-to-
			end protections that retain the familiar experience of e-mail itself.
			Furthermore, an e-mail user is likely to regularly interact with
			other e-mail correspondents who _cannot_ handle or produce end-to-end
			cryptographic protections. Care should be taken that enabling
			cryptography in a MUA does not inadvertently limit the ability of the
			user to interact with legacy correspondents.
			2.3. Warning About Failure vs. Announcing Success
			Moving the web from http to https offers useful historical
			similarities to adding end-to-end encryption to e-mail.
			In particular, the indicators of what is "secure" vs. "insecure" for
			web browsers have changed over time. For example, years ago the
			default experience was http, and https sites were flagged with
			"secure" indicators like a lock icon. In 2018, some browsers
			reversed that process by downplaying https, and instead visibly
			marking http as "not secure" (see [chrome-indicators]).
			By analogy, when the user of a MUA first enables end-to-end
			cryptographic protection, it's likely that they will want to see
			which messages _have_ protection. But a user whose e-mail
			communications are entirely end-to-end protected might instead want
			to know which messages do _not_ have the expected protections.
			Note also that some messages are expected to be confidential, but
			other messages are expected to be public -- the types of protection
			(see Section 3) that apply to each particular message will be
			different. And the types of protection that are _expected_ to be
			present in any context might differ (for example, by sender, by
			thread, or by date).
			It is out of scope for this document to define expectations about
			protections for any given message, but an implementer who cares about
			usable experience should be deliberate and judicious about the
			expectations their interface assumes that the user has in a given
			context.
	3. Types of Protection		3. Types of Protection
	A given message might be:		A given message might be:
	* signed,		* signed,
	* encrypted, or		* encrypted,
	* both signed and encrypted.		* both signed and encrypted, or
			* none of the above.
	Given that many e-mail messages offer no cryptographic protections,		Given that many e-mail messages offer no cryptographic protections,
	the user needs to be able to detect which protections are present for		the user needs to be able to detect which protections are present for
	any given message.		any given message.
	4. Cryptographic MIME Message Structure		4. Cryptographic MIME Message Structure
	Implementations use the structure of an e-mail message to protect the		Implementations use the structure of an e-mail message to protect the
	headers. This section establishes some conventions about how to		headers. This section establishes some conventions about how to
	think about message structure.		think about message structure.
	skipping to change at page 7, line 4 ¶		skipping to change at page 9, line 14 ¶
	4.1.2.1. PGP/MIME Signing Cryptographic Layer (multipart/signed)		4.1.2.1. PGP/MIME Signing Cryptographic Layer (multipart/signed)
	└┬╴multipart/signed; protocol="application/pgp-signature"		└┬╴multipart/signed; protocol="application/pgp-signature"
	├─╴[protected part]		├─╴[protected part]
	└─╴application/pgp-signature		└─╴application/pgp-signature
	This MIME layer offers authenticity and integrity.		This MIME layer offers authenticity and integrity.
	4.1.2.2. PGP/MIME Encryption Cryptographic Layer (multipart/encrypted)		4.1.2.2. PGP/MIME Encryption Cryptographic Layer (multipart/encrypted)
	└┬╴multipart/encrypted		└┬╴multipart/encrypted
	├─╴application/pgp-encrypted		├─╴application/pgp-encrypted
	└─╴application/octet-stream		└─╴application/octet-stream
	↧ (decrypts to)		↧ (decrypts to)
	└─╴[protected part]		└─╴[protected part]
	Note that for PGP/MIME, this MIME layer can offer any of:		This MIME layer can offer any of:
	* confidentiality (via a Symmetrically Encrypted Data Packet, see		* confidentiality (via a Symmetrically Encrypted Data Packet, see
	Section 5.7 of [RFC4880]; a MUA MUST NOT generate this form due to		Section 5.7 of [RFC4880]; a MUA MUST NOT generate this form due to
	ciphertext malleability)		ciphertext malleability)
	* confidentiality and integrity (via a Symmetrically Encrypted		* confidentiality and integrity (via a Symmetrically Encrypted
	Integrity Protected Data Packet (SEIPD), see section 5.13 of		Integrity Protected Data Packet (SEIPD), see section 5.13 of
	[RFC4880]), or		[RFC4880]), or
	* confidentiality, integrity, and authenticity all together (by		* confidentiality, integrity, and authenticity all together (by
	skipping to change at page 7, line 48 ¶		skipping to change at page 10, line 12 ¶
	Cryptographic Envelope. They are Errant Cryptographic Layers (see		Cryptographic Envelope. They are Errant Cryptographic Layers (see
	Section 4.5).		Section 4.5).
	Note also that the ordering of the Cryptographic Layers implies		Note also that the ordering of the Cryptographic Layers implies
	different cryptographic properties. A signed-then-encrypted message		different cryptographic properties. A signed-then-encrypted message
	is different than an encrypted-then-signed message. See Section 5.2.		is different than an encrypted-then-signed message. See Section 5.2.
	4.3. Cryptographic Payload		4.3. Cryptographic Payload
	The Cryptographic Payload of a message is the first non-Cryptographic		The Cryptographic Payload of a message is the first non-Cryptographic
	Layer - the "protected part" - within the Cryptographic Envelope.		Layer -- the "protected part" -- within the Cryptographic Envelope.
	4.4. Types of Cryptographic Envelope		4.4. Types of Cryptographic Envelope
	4.4.1. Simple Cryptographic Envelopes		4.4.1. Simple Cryptographic Envelopes
	As described above, if the "protected part" identified in the sction		As described above, if the "protected part" identified in the sction
	above is not itself a Cryptographic Layer, that part _is_ the		above is not itself a Cryptographic Layer, that part _is_ the
	Cryptographic Payload.		Cryptographic Payload.
	If the application wants to generate a message that is both encrypted		If the application wants to generate a message that is both encrypted
	and signed, it MAY use the simple MIME structure from Section 4.1.2.2		and signed, it MAY use the simple MIME structure from Section 4.1.2.2
	by ensuring that the [RFC4880] Encrypted Message within the		by ensuring that the [RFC4880] Encrypted Message within the
	"application/octet-stream" part contains an [RFC4880] Signed Message		"application/octet-stream" part contains an [RFC4880] Signed Message
	skipping to change at page 10, line 31 ¶		skipping to change at page 12, line 39 ¶
	cryptographic envelope and payload.		cryptographic envelope and payload.
	The message composition algorithm takes three parameters:		The message composition algorithm takes three parameters:
	* "origbody": the traditional unprotected message body as a well-		* "origbody": the traditional unprotected message body as a well-
	formed MIME tree (possibly just a single MIME leaf part). As a		formed MIME tree (possibly just a single MIME leaf part). As a
	well-formed MIME tree, "origbody" already has structural headers		well-formed MIME tree, "origbody" already has structural headers
	present (see Section 1.2.1).		present (see Section 1.2.1).
	* "origheaders": the intended non-structural headers for the		* "origheaders": the intended non-structural headers for the
	message, represented here as a table mapping from header names to		message, represented here as a list of "(h,v)" pairs, where "h" is
	header values.. For example, "origheaders['From']" refers to the		a header field name and "v" is the associated value.
	value of the "From" header that the composing MUA would typically
	place on the message before sending it.
	* "crypto": The series of cryptographic protections to apply (for		* "crypto": The series of cryptographic protections to apply (for
	example, "sign with the secret key corresponding to X.509		example, "sign with the secret key corresponding to X.509
	certificate X, then encrypt to X.509 certificates X and Y"). This		certificate X, then encrypt to X.509 certificates X and Y"). This
	is a routine that accepts a MIME tree as input (the Cryptographic		is a routine that accepts a MIME tree as input (the Cryptographic
	Payload), wraps the input in the appropriate Cryptographic		Payload), wraps the input in the appropriate Cryptographic
	Envelope, and returns the resultant MIME tree as output.		Envelope, and returns the resultant MIME tree as output.
	The algorithm returns a MIME object that is ready to be injected into		The algorithm returns a MIME object that is ready to be injected into
	the mail system:		the mail system:
	* Apply "crypto" to "origbody", yielding MIME tree "output"		* Apply "crypto" to "origbody", yielding MIME tree "output"
	* For header name "h" in "origheaders":		* For each header name and value "(h,v)" in "origheaders":
	- Set header "h" of "output" to "origheaders[h]"		- Add header "h" of "output" with value "v"
	* Return "output"		* Return "output"
	5.2. Encryption Outside, Signature Inside		5.2. Encryption Outside, Signature Inside
	Users expect any message that is both signed and encrypted to be		Users expect any message that is both signed and encrypted to be
	signed _inside_ the encryption, and not the other way around.		signed _inside_ the encryption, and not the other way around.
	Putting the signature inside the encryption has two advantages:		Putting the signature inside the encryption has two advantages:
	skipping to change at page 15, line 41 ¶		skipping to change at page 17, line 47 ¶
	An incoming e-mail message may include an attached forwarded message,		An incoming e-mail message may include an attached forwarded message,
	typically as a MIME subpart with "Content-Type: message/rfc822"		typically as a MIME subpart with "Content-Type: message/rfc822"
	([RFC5322]) or "Content-Type: message/global" ([RFC5355]).		([RFC5322]) or "Content-Type: message/global" ([RFC5355]).
	Regardless of the cryptographic protections and structure of the		Regardless of the cryptographic protections and structure of the
	incoming message, the internal forwarded message may have its own		incoming message, the internal forwarded message may have its own
	Cryptographic Envelope.		Cryptographic Envelope.
	The Cryptographic Layers that are part of the Cryptographic Envelope		The Cryptographic Layers that are part of the Cryptographic Envelope
	of the forwarded message are not Errant Cryptographic Layers of the		of the forwarded message are not Errant Cryptographic Layers of the
	surrounding message - they are simply layers that apply to the		surrounding message -- they are simply layers that apply to the
	forwarded message itself.		forwarded message itself.
	The rendering MUA MUST NOT conflate the cryptographic protections of		The rendering MUA MUST NOT conflate the cryptographic protections of
	the forwarded message with the cryptographic protections of the		the forwarded message with the cryptographic protections of the
	incoming message.		incoming message.
	The rendering MUA MAY render a cryptograpic summary of the		The rendering MUA MAY render a cryptograpic summary of the
	protections afforded to the forwarded message by its own		protections afforded to the forwarded message by its own
	Cryptographic Envelope, as long as that rendering is unambiguously		Cryptographic Envelope, as long as that rendering is unambiguously
	tied to the forwarded message itself.		tied to the forwarded message itself.
	skipping to change at page 16, line 39 ¶		skipping to change at page 18, line 44 ¶
	* the signature is made by a certificate which the receiving MUA		* the signature is made by a certificate which the receiving MUA
	does not have access to.		does not have access to.
	* the certificate that made the signature was revoked.		* the certificate that made the signature was revoked.
	* the certificate that made the signature was expired at the time		* the certificate that made the signature was expired at the time
	that the signature was made.		that the signature was made.
	* the certificate that made the signature does not correspond to the		* the certificate that made the signature does not correspond to the
	author of the message.		author of the message. (for X.509, there is no subjectAltName of
			type RFC822Name whose value matches an e-mail address found in
			"From:" or "Sender:")
			* the certificate that made the signature was not issued by an
			authority that the MUA user is willing to rely on for certifying
			the sender's e-mail address.
	* the signature indicates that it was made at a time much before or		* the signature indicates that it was made at a time much before or
	much after from the date of the message itself.		much after from the date of the message itself.
	A valid signature must pass all these tests, but of course invalid		A valid signature must pass all these tests, but of course invalid
	signatures may be invalid in more than one of the ways listed above.		signatures may be invalid in more than one of the ways listed above.
	7. Common Pitfalls and Guidelines		7. Certificate Management
			A cryptographically-capable MUA typically maintains knowledge about
			certificates for the user's own account(s), as well as certificates
			for the peers that it communicates with.
			7.1. Peer Certificates
			Most certificates that a cryptographically-capable MUA will use will
			be certificates belonging to the parties that the user communicates
			with through the MUA. This section discusses how to manage the
			certificates that belong to such a peer.
			The MUA will need to be able to discover X.509 certificates for each
			peer, cache them, and select among them when composing an encrypted
			message.
			7.1.1. Cert Discovery from Incoming Messages
			TODO: incoming PKCS#7 messages tend to have a bundle of certificates
			in them. How should these certs be handled?
			TODO: point to Autocrypt certificate discovery mechanism
			TODO: point to OpenPGP embedded certificate subpacket proposal
			TODO: compare mechanisms, explain where each case is useful.
			7.1.2. Certificate Directories
			Some MUAs may have the capability to look up peer certificates in a
			directory.
			TODO: more information here about X.509 directories -- LDAP?
			TODO: mention WKD for OpenPGP certificates?
			7.1.3. Peer Certificate Selection
			When composing an encrypted message, the MUA needs to select a
			certificate for each recipient that is capable of encryption.
			To select such a certificate for a given destination e-mail address,
			the MUA should look through all of its known certificates and verify
			that _all_ of the conditions below are met:
			* The certificate must be valid, not expired or revoked.
			* It must have a subjectAltName of type rFC822Name whose contents
			exactly match the destination address.
			* The algorithm OID in the certificate's SPKI is known to the MUA
			and capable of encryption. Examples include (TODO: need OIDs)
			- RSA, with keyUsage present and the "key encipherment" bit set
			- EC Public Key, with keyUsage present and the "key agreement"
			bit set
			- EC DH, with keyUsage present and the "key agreement" bit set
			* If extendedKeyUsage is present, it contains at least one of the
			following OIDs: e-mail protection, anyExtendedKeyUsage.
			TODO: If OID is EC Public Key and keyUsage is absent, what should
			happen?
			TODO: what if multiple certificates meet all of these criteria for a
			given recipient?
			7.1.4. Checking for Revocation
			TODO: discuss how/when to check for peer certificate revocation
			TODO: privacy concerns: what information leaks to whom when checking
			peer cert revocations?
			7.2. Local Certificates
			The MUA also needs to know about one or more certificates associated
			with the user's e-mail account. It is typically expected to have
			access to the secret key material associated with the public keys in
			those certificates.
			7.2.1. Getting a Certificate for the User
			TODO: mention ACME SMIME?
			TODO: mention automatic self-signed certs e.g. OpenPGP?
			TODO: SHOULD generate secret key material locally, and MUST NOT
			accept secret key material from an untrusted third party as the basis
			for the user's certificate.
			7.2.2. Local Certificate Maintenance
			The MUA should warn the user when/if:
			* The user's own certificate set does not include a valid, unexpired
			encryption-capable X.509 certificate, and a valid, unexpired
			signature-capable X.509 certificate.
			* Any of the user's own certificates is due to expire soon (TODO:
			what is "soon"?)
			* Any of the user's own certificates does not match the e-mail
			address associated with the user's account.
			* Any of the user's own certificates does not have a keyUsage
			section
			* Any of the user's own certificates does not contain an
			extendedKeyUsage extension
			TODO: how does the MUA do better than warning in the cases above?
			What can the MUA actually _do_ here to fix problems before they
			happen?
			TODO: discuss how/when to check for own certificate revocation, and
			what to do if it (or any intermediate certificate authority) is found
			to be revoked.
			7.2.3. Shipping Certificates in Outbound Messages
			TODO: What certificates should the MUA include in an outbound message
			so that peers can discover them?
			* local signing certificate so that signature can be validated
			* local encryption-capable certificate(s) so that incoming messages
			can be encypted.
			* On an encrypted message to multiple recipients, the encryption-
			capable peer certs of the other recipients (to enable "reply
			all")?
			* intermediate certificates to chain all of the above to some set of
			root authorities?
			7.3. Certificate Authorities
			TODO: how should the MUA select root certificate authorities?
			TODO: should the MUA cache intermediate CAs?
			TODO: should the MUA share such a cache with other PKI clients (e.g.,
			web browsers)? Are there distinctions between a CA for S/MIME and
			for the web?
			8. Common Pitfalls and Guidelines
	This section highlights a few "pitfalls" and guidelines based on		This section highlights a few "pitfalls" and guidelines based on
	these discussions and lessons learned.		these discussions and lessons learned.
	FIXME: some possible additional commentary on:		FIXME: some possible additional commentary on:
	* indexing and search of encrypted messages		* indexing and search of encrypted messages
	* managing access to cryptographic secret keys that require user		* managing access to cryptographic secret keys that require user
	interaction		interaction
	* secure deletion		* secure deletion
	* inline PGP, ugh		* inline PGP, ugh
	8. IANA Considerations		* storage of composed/sent messages
			* encrypt-to-self during composition
			* cached signature validation
			* interaction between encryption and Bcc
			* aggregated cryptographic status of threads/conversations ?
			* Draft messages
			* copies to the Sent folder
			9. IANA Considerations
	MAYBE: provide an indicator in the IANA header registry for which		MAYBE: provide an indicator in the IANA header registry for which
	headers are "structural" ? This is probably unnecessary.		headers are "structural" ? This is probably unnecessary.
	9. Security Considerations		10. Security Considerations
	This entire document addresses security considerations about end-to-		This entire document addresses security considerations about end-to-
	end cryptographic protections for e-mail messages.		end cryptographic protections for e-mail messages.
	10. Document Considerations		11. Document Considerations
	[ RFC Editor: please remove this section before publication ]		[ RFC Editor: please remove this section before publication ]
	This document is currently edited as markdown. Minor editorial		This document is currently edited as markdown. Minor editorial
	changes can be suggested via merge requests at		changes can be suggested via merge requests at
	https://gitlab.com/dkg/e2e-mail-guidance or by e-mail to the author.		https://gitlab.com/dkg/e2e-mail-guidance or by e-mail to the author.
	Please direct all significant commentary to the public IETF LAMPS		Please direct all significant commentary to the public IETF LAMPS
	mailing list: spasm@ietf.org		mailing list: spasm@ietf.org
	10.1. Document History		11.1. Document History
	11. Acknowledgements		11.1.1. Substantive changes from -00 to -01
			* consideration of success/failure indicators for usability
			* clarify extendedKeyUsage and keyUsage algorithm-specific details
			* initial section on certificate management
			* added more TODO items
			12. Acknowledgements
	The set of constructs and recommendations in this document are		The set of constructs and recommendations in this document are
	derived from discussions with many different implementers, including		derived from discussions with many different implementers, including
	Alexey Melnikov, Bernie Hoeneisen, Bjarni Runar Einarsson, David		Alexey Melnikov, Bernie Hoeneisen, Bjarni Runar Einarsson, David
	Bremner, Holger Krekel, Jameson Rollins, juga, Patrick Brunschwig,		Bremner, Deb Cooley, Holger Krekel, Jameson Rollins, Jonathan
	and Vincent Breitmoser.		Hammell, juga, Patrick Brunschwig, Santosh Chokhani, and Vincent
			Breitmoser.
	12. References		13. References
	12.1. Normative References		13.1. Normative References
	[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate		[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
	Requirement Levels", BCP 14, RFC 2119,		Requirement Levels", BCP 14, RFC 2119,
	DOI 10.17487/RFC2119, March 1997,		DOI 10.17487/RFC2119, March 1997,
	<https://www.rfc-editor.org/info/rfc2119>.		<https://www.rfc-editor.org/info/rfc2119>.
	[RFC3156] Elkins, M., Del Torto, D., Levien, R., and T. Roessler,		[RFC3156] Elkins, M., Del Torto, D., Levien, R., and T. Roessler,
	"MIME Security with OpenPGP", RFC 3156,		"MIME Security with OpenPGP", RFC 3156,
	DOI 10.17487/RFC3156, August 2001,		DOI 10.17487/RFC3156, August 2001,
	<https://www.rfc-editor.org/info/rfc3156>.		<https://www.rfc-editor.org/info/rfc3156>.
	skipping to change at page 18, line 24 ¶		skipping to change at page 24, line 24 ¶
	[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC		[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
	2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,		2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
	May 2017, <https://www.rfc-editor.org/info/rfc8174>.		May 2017, <https://www.rfc-editor.org/info/rfc8174>.
	[RFC8551] Schaad, J., Ramsdell, B., and S. Turner, "Secure/		[RFC8551] Schaad, J., Ramsdell, B., and S. Turner, "Secure/
	Multipurpose Internet Mail Extensions (S/MIME) Version 4.0		Multipurpose Internet Mail Extensions (S/MIME) Version 4.0
	Message Specification", RFC 8551, DOI 10.17487/RFC8551,		Message Specification", RFC 8551, DOI 10.17487/RFC8551,
	April 2019, <https://www.rfc-editor.org/info/rfc8551>.		April 2019, <https://www.rfc-editor.org/info/rfc8551>.
	12.2. Informative References		13.2. Informative References
			[chrome-indicators]
			Schechter, E., "Evolving Chrome's security indicators",
			May 2018, <https://blog.chromium.org/2018/05/evolving-
			chromes-security-indicators.html>.
	[EFAIL] "EFAIL", n.d., <https://efail.de>.		[EFAIL] "EFAIL", n.d., <https://efail.de>.
	[I-D.draft-bre-openpgp-samples-01]		[I-D.draft-bre-openpgp-samples-01]
	Einarsson, B., juga, j., and D. Gillmor, "OpenPGP Example		Einarsson, B. R., "juga", and D. K. Gillmor, "OpenPGP
	Keys and Certificates", Work in Progress, Internet-Draft,		Example Keys and Certificates", Work in Progress,
	draft-bre-openpgp-samples-01, 20 December 2019,		Internet-Draft, draft-bre-openpgp-samples-01, 20 December
	<http://www.ietf.org/internet-drafts/draft-bre-openpgp-		2019, <https://www.ietf.org/archive/id/draft-bre-openpgp-
	samples-01.txt>.		samples-01.txt>.
	[I-D.draft-dkg-lamps-samples-02]		[I-D.draft-dkg-lamps-samples-05]
	Gillmor, D., "S/MIME Example Keys and Certificates", Work		Gillmor, D. K., "S/MIME Example Keys and Certificates",
	in Progress, Internet-Draft, draft-dkg-lamps-samples-02,		Work in Progress, Internet-Draft, draft-dkg-lamps-samples-
	24 December 2019, <http://www.ietf.org/internet-drafts/		05, 18 February 2021, <https://www.ietf.org/archive/id/
	draft-dkg-lamps-samples-02.txt>.		draft-dkg-lamps-samples-05.txt>.
	[RFC3274] Gutmann, P., "Compressed Data Content Type for		[RFC3274] Gutmann, P., "Compressed Data Content Type for
	Cryptographic Message Syntax (CMS)", RFC 3274,		Cryptographic Message Syntax (CMS)", RFC 3274,
	DOI 10.17487/RFC3274, June 2002,		DOI 10.17487/RFC3274, June 2002,
	<https://www.rfc-editor.org/info/rfc3274>.		<https://www.rfc-editor.org/info/rfc3274>.
	[RFC4880] Callas, J., Donnerhacke, L., Finney, H., Shaw, D., and R.		[RFC4880] Callas, J., Donnerhacke, L., Finney, H., Shaw, D., and R.
	Thayer, "OpenPGP Message Format", RFC 4880,		Thayer, "OpenPGP Message Format", RFC 4880,
	DOI 10.17487/RFC4880, November 2007,		DOI 10.17487/RFC4880, November 2007,
	<https://www.rfc-editor.org/info/rfc4880>.		<https://www.rfc-editor.org/info/rfc4880>.
	skipping to change at page 19, line 25 ¶		skipping to change at page 25, line 30 ¶
	[RFC6376] Crocker, D., Ed., Hansen, T., Ed., and M. Kucherawy, Ed.,		[RFC6376] Crocker, D., Ed., Hansen, T., Ed., and M. Kucherawy, Ed.,
	"DomainKeys Identified Mail (DKIM) Signatures", STD 76,		"DomainKeys Identified Mail (DKIM) Signatures", STD 76,
	RFC 6376, DOI 10.17487/RFC6376, September 2011,		RFC 6376, DOI 10.17487/RFC6376, September 2011,
	<https://www.rfc-editor.org/info/rfc6376>.		<https://www.rfc-editor.org/info/rfc6376>.
	Appendix A. Test Vectors		Appendix A. Test Vectors
	FIXME: This document should contain examples of well-formed and		FIXME: This document should contain examples of well-formed and
	malformed messages using cryptographic key material and certificates		malformed messages using cryptographic key material and certificates
	from [I-D.draft-bre-openpgp-samples-01] and		from [I-D.draft-bre-openpgp-samples-01] and
	[I-D.draft-dkg-lamps-samples-02].		[I-D.draft-dkg-lamps-samples-05].
	It may also include example renderings of these messages.		It may also include example renderings of these messages.
	Author's Address		Author's Address
	Daniel Kahn Gillmor		Daniel Kahn Gillmor
	American Civil Liberties Union		American Civil Liberties Union
	125 Broad St.		125 Broad St.
	New York, NY, 10004		New York, NY, 10004
	United States of America		United States of America
End of changes. 34 change blocks.
	79 lines changed or deleted		370 lines changed or added
This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/