Consider proposed text for draft-00 #14

dkg · 2019-11-04T06:38:11Z

We have an IETF draft filing deadline today. I'm proposing submitting this as version -00.

I know it's a lot of churn, but i've been re-reading and thinking about overall document structure and i think it's an improvement.

The summary is an important part of the document. Someone who reads the summary and understands cryptographic e-mail in general should get a sense of what's happening here without reading much more. I've moved it to a more prominent place in the document, and i've stripped it of language that blends together "what are the underlying changes?" with "how should one construct such a message?" -- we want this section to focus on the former, and leave details of the latter to later sections. Signed-off-by: Daniel Kahn Gillmor <[email protected]>

I think this structure makes the algorithm more understandable, and provides a simple contrast with the steps that legacy MUA clients are doing. It also makes it easier to parameterize the process. At the moment, i think we want the defaults to be `legacy` = True and `obscures` = `{'Subject': '...'}`. But in the future, some MUAs might experiment with adjusting either variable and can report back on that experience, all while still using the same message composition algorithm. Signed-off-by: Daniel Kahn Gillmor <[email protected]>

This is a simple enough concept, and it belongs up in the Terminology section. Signed-off-by: Daniel Kahn Gillmor <[email protected]>

In practice, you can't do all this header shuffling if you also shuffle things like "Content-Type". This change just makes that explicit. Signed-off-by: Daniel Kahn Gillmor <[email protected]>

These are minor changes, trying to make the document read more smoothly and use more consistent terminology. Signed-off-by: Daniel Kahn Gillmor <[email protected]>

Signed-off-by: Daniel Kahn Gillmor <[email protected]>

We want to be able to show the reader what this stuff looks like inside the encrypted layer, even if they can't do the work themselves. Signed-off-by: Daniel Kahn Gillmor <[email protected]>

This tab marker was present because it is expected in a diff. But now that we are rendering the cleartext, it's clear that kramdosn complains: *** Input contains HT ("tab") characters. Undefined behavior will ensue. We work around this by just removing the tab character from the included file. Signed-off-by: Daniel Kahn Gillmor <[email protected]>

The "Examples" section contained a text that was difficult to read, in a non-standard format. It was particularly unclear to me what the E: and S: prefixes were supposed to mean, and it was distracting to see pieces that are not actual parts of the message rendered in brackets. Most examples also included unnecessary/distracting text like a MIME preamble. Furthermore, the Legacy Display parts included unobscured headers, which is not a recommended practice. Now that the Test Vectors include the cleartext, most of this functionality is superceded anyway, and it is superceded by messages that can be parsed directly in tests. If there are flaws in the Test Vectors, we should fix those. Signed-off-by: Daniel Kahn Gillmor <[email protected]>

I think readers will want to get the bigger picture about message composition before wading into the specific algorithms. Signed-off-by: Daniel Kahn Gillmor <[email protected]>

Signed-off-by: Daniel Kahn Gillmor <[email protected]>

BjarniRunar · 2019-11-04T08:46:01Z

I like this! :-)

There are a few FIXMEs still in there, and at least one unwritten section. I'm going to merge this PR into my own branch, make some quick fixes to those things and file another PR with the combination. You can then either merge or cherry-pick as you prefer?

juga0

i went through the commits, then run make and read the resulting html. It makes sense to me. It's also great that now all the parts of the test vectors are generated automatically.
i just added some comments, mostly about the style in which the terms should appear. I've not gone through all the instances of those terms.

juga0 · 2019-11-04T07:28:49Z

draft-protected-headers.in.md

@@ -59,7 +59,7 @@ normative:
 RFC8174:
 --- abstract

-This document describes a common strategy to extend the cryptographic protections provided by PGP/MIME, etc. to protect message headers in addition to message bodies.
+This document describes a common strategy to extend the end-to-end cryptographic protections provided by PGP/MIME, etc. to protect message headers in addition to message bodies.


Hmm, something like kuvert could protect headers, but it's not end-to-end. Isn't the end-to-end part something transversal?

I'm not sure what you mean by "transversal" but the point of this document is to try to focus on the PGP/MIME and S/MIME use cases, where cryptographic transformations are typically applied by the composing mail user agent. (e.g. as opposed to DKIM, which is designed for application by middleware transport).

Even if there are some systems (kuvert isn't the only one) that apply these transformations off of the client box, i think we can keep the "end-to-end" term as a distinguishing characteristic.

juga0 · 2019-11-04T07:32:13Z

draft-protected-headers.in.md


-All headers known to the MUA at composition time MUST be copied verbatim into the header of the target MIME part.
+All non-structural headers known to the composing MUA are copied to the MIME header of the Cryptographic Payload.


should MIME header be defined or clarified?

I see now #15 :)

juga0 · 2019-11-04T07:32:57Z

draft-protected-headers.in.md

@@ -75,7 +75,7 @@ This document defines a scheme, "Protected Headers for Cryptographic E-mail", wh

 This document describes how these protections can be applied to cryptographically signed messages, and also discusses some of the challenges of encrypting many transit-oriented headers.

-It offers guidance for encrypting non-transit-oriented headers like Subject, and also offers a means to preserve backwards compatibility so that an encrypted Subject remains available to recipients using software that does not implement support for the Protected Headers scheme.
+It offers guidance for protecting the confidentiality of non-transit-oriented headers like Subject, and also offers a means to preserve backwards compatibility so that an encrypted Subject remains available to recipients using software that does not implement support for the Protected Headers scheme.


i understand what transit-header means, but is it defined somewhere?

I've opened #20 about this.

juga0 · 2019-11-04T07:33:52Z

draft-protected-headers.in.md


 When a message is encrypted, the Subject should be obscured by replacing the Exposed Subject with three periods: `...`

-This value (`...`) was chosen because it is believed to be language agnostic and avoids communicating any potentially misleading information to the recipient (see {{common-pitfalls}} for a more detailed discussion).
+This value (`...`) was chosen because it is believed to be language agnostic and avoids communicating any potentially misleading information to the recipient (see {{misunderstood-obscured-subjects}} for a more detailed discussion).


also in non-occidental languages?, but this is a different discussion...

hm, yes, this is a concern. I've opened #19 to keep track of it.

juga0 · 2019-11-04T08:33:36Z

draft-protected-headers.in.md

+ - `Cc`
+ - `Date`
+
+The above is a complete list.  No other headers are considered "user-facing".


Should all defined terms appear in ```` or with 1st letter capitalized?,
s/"user-facing"/User-Facing/

I've been trying to use code style to indicate literal textual elements, and Upper Case to indicate defined terms.

juga0 · 2019-11-04T08:36:40Z

draft-protected-headers.in.md


-Details:
+All non-structural headers known to the composing MUA are copied to the MIME header of the Cryptographic Payload.


Should all defined terms appear in ```` or with 1st letter capitalized?, here:
s/All non-strucutural headers/All non-Structural Headers/

I've been trying to use code style to indicate literal textual elements, and Upper Case to indicate defined terms.

juga0 · 2019-11-04T08:40:36Z

draft-protected-headers.in.md


-Legacy Display {#legacy-display}
-==============
+A reasonable sequential algorithm for composing a message *with* protected headers takes two more parameters in addition to `origbody`, `origheaders`, and `crypto`:


s/reasonable//?

juga0 · 2019-11-04T08:42:39Z

draft-protected-headers.in.md


-Other headers may affect the visible rendering of the message (e.g., `References` and `In-Reply-To` may affect the placement of a message in a threaded discussion), but they are not directly displayed to the user and so are not considered "typically visible" for the purposes of this document.
+This section presents a workaround to mitigate this risk by restructuring the Cryptographic Payload before encrypting to include a "Legacy Display" part.


s/"Legacy Display"/Legacy Display/?

I've been trying to use code style to indicate literal textual elements, and Upper Case to indicate defined terms.

hpk42

this looks good to me. thanks for pushing ahead!

dkg added 14 commits November 3, 2019 21:58

Merge branches 'generation-algorithm' and 'summarize' into dkg-drafting

e6a8ddf

Change "typically-visible" to "user-facing" headers, move to Terminology

63dcf90

This is a simple enough concept, and it belongs up in the Terminology section. Signed-off-by: Daniel Kahn Gillmor <[email protected]>

Define "structural" headers

2565290

In practice, you can't do all this header shuffling if you also shuffle things like "Content-Type". This change just makes that explicit. Signed-off-by: Daniel Kahn Gillmor <[email protected]>

Textual cleanup

9ae3674

These are minor changes, trying to make the document read more smoothly and use more consistent terminology. Signed-off-by: Daniel Kahn Gillmor <[email protected]>

note concern about enigmail-generated cryptographic payload

7aa2a9e

Signed-off-by: Daniel Kahn Gillmor <[email protected]>

avoid accidental commits to generated file

a54eb6a

Test Vectors: include cleartext unwrapping

c6eea5e

We want to be able to show the reader what this stuff looks like inside the encrypted layer, even if they can't do the work themselves. Signed-off-by: Daniel Kahn Gillmor <[email protected]>

fix wayward spelling

8e7510d

Moving sections around for easier reading

9912c9b

I think readers will want to get the bigger picture about message composition before wading into the specific algorithms. Signed-off-by: Daniel Kahn Gillmor <[email protected]>

bumping the date on the draft

814716c

Signed-off-by: Daniel Kahn Gillmor <[email protected]>

juga0 approved these changes Nov 4, 2019

View reviewed changes

hpk42 approved these changes Nov 4, 2019

View reviewed changes

This was referenced Nov 4, 2019

Address how ... appears to speakers of non-alphabetic, non-occidental languages #19

Open

define "transit-oriented" header #20

Open

dkg merged commit 814716c into master Nov 4, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Consider proposed text for draft-00 #14

Consider proposed text for draft-00 #14

dkg commented Nov 4, 2019

BjarniRunar commented Nov 4, 2019

juga0 left a comment

juga0 Nov 4, 2019

dkg Nov 4, 2019

juga0 Nov 4, 2019

juga0 Nov 4, 2019

juga0 Nov 4, 2019

dkg Nov 4, 2019

juga0 Nov 4, 2019 •

edited

Loading

dkg Nov 4, 2019

juga0 Nov 4, 2019

dkg Nov 4, 2019

juga0 Nov 4, 2019

dkg Nov 4, 2019

juga0 Nov 4, 2019

juga0 Nov 4, 2019

dkg Nov 4, 2019

hpk42 left a comment


		All headers known to the MUA at composition time MUST be copied verbatim into the header of the target MIME part.
		All non-structural headers known to the composing MUA are copied to the MIME header of the Cryptographic Payload.


		Details:
		All non-structural headers known to the composing MUA are copied to the MIME header of the Cryptographic Payload.


		Other headers may affect the visible rendering of the message (e.g., `References` and `In-Reply-To` may affect the placement of a message in a threaded discussion), but they are not directly displayed to the user and so are not considered "typically visible" for the purposes of this document.
		This section presents a workaround to mitigate this risk by restructuring the Cryptographic Payload before encrypting to include a "Legacy Display" part.

Consider proposed text for draft-00 #14

Consider proposed text for draft-00 #14

Conversation

dkg commented Nov 4, 2019

BjarniRunar commented Nov 4, 2019

juga0 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

juga0 Nov 4, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hpk42 left a comment

Choose a reason for hiding this comment

juga0 Nov 4, 2019 •

edited

Loading