review HB

pep-email/draft-pep-email.mkd

@@ -155,8 +155,14 @@ contradict with security goals, the privacy goals SHALL have precedence.
 
 Examples: 
 
+<!-- HB:
+RFC2119 language is only useful, if specifying a protocol. Not sure this
+should already be used in the introduction section.
+Also condider s/SHALL/MUST/g
+-->
+
 * pEp implementers SHALL NOT make queries to public key servers by default, 
-  so as to make it more expensive for centralized network actors to learn 
+  in order to make it more expensive for centralized network actors to learn 
   a user's social graph. This is also problematic security-wise, as 
   centralized cryptgraphic key subversion at-scale is made cheaper.
 * Instead, key distribution SHALL be handled in-band while communicating with 
@@ -167,17 +173,17 @@ Examples:
   transitive trust information is held centrally: that is, while pEp MUST be 
   able to work with OpenPGP keys which carry trust information, this trust 
   information SHALL not be used to signal any trust level.
-* pEp-enlabed MUAs SHALL either engage in a signed-and-encrypted communication 
+* pEp-enabled MUAs SHALL either engage in a signed-and-encrypted communication 
   or in unsigned plaintext communication. While the signatures attached to 
   plaintext messages can be verified, this cannot enhance the perceived 
   quality of the message in the user interface, while an invalid signature 
-  degrades the perception: signed-only messages per se don't increase security
-  if no authentication was done and--taken alone--are without positive influence 
-  on privacy.
+  degrades the perception: signed-only messages per se do not increase security,
+  if no authentication was done and are -- as sole measure -- without positive
+  influence on privacy.
 
 ## Data Minimization
 
-Data Minimization includes data spareness and hiding all technically
+Data Minimization includes data spareness and hiding of all technically
 concealable information whenever possible.
 
 ### Metadata Protection
@@ -186,23 +192,26 @@ Email metadata (i.e., headers) MUST either be omitted or encrypted whenever
 possible.
 
 The PGP/MIME specification {{RFC3156}} provides no facility for
-metadata protection. The only protection possible for information
-represented by the header field values is to ensure they are encrypted
-as part of the message body.
+metadata protection. However, it is possible to protect the
+information contained in header field values by encapsulating the
+whole message into a new message body to be singed and encrypted.
 
-The S/MIME Message Specification {{RFC8551}} instead proposes a way to
-secure header fields, which currently is seldomly used in practice:
+The S/MIME Message Specification {{RFC8551}}, on the other hand,
+defines a way to protect also the header section in addition to the
+content of a message:
 
 > The sending client MAY wrap a full MIME message in a
 > message/rfc822 wrapper in order to apply S/MIME security
 > services to header fields.
 
+<!-- HB to much S/MIME
 S/MIME {{RFC8551}} provides no further guidance in deciding which header
 fields are transport-relevant and thus might be copied to the wrapper.
+-->
 
 ### Support for multiple formats
 
-What concerns any kind of email (metadata) encryption: implementors 
+What concerns any kind of email (metadata) encryption: implementers 
 of pEp SHOULD be liberal in accepting other approaches to encrypt 
 email headers, but MUST use the strict and interoperable pEp 
 format (cf. {{pef-1-0}}) for any outgoing communication.
@@ -210,10 +219,10 @@ format (cf. {{pef-1-0}}) for any outgoing communication.
 ## Interoperability
 
 While pEp implementers SHALL make sure that any communication between
-pEp users is maximizing for privacy, interoperability between other
-approches to encrypt payloads and hide metadata SHOULD be supported to 
-the widest extent. To reduce artefacts between non-pEp users, pEp
-implementers are 
+pEp users is maximized for privacy, interoperability between other
+approches to encrypt payloads and hide metadata SHOULD be supported to
+the widest extent. To mitigate artefacts in the presentation of messages
+sent from non-pEp to pEp implementions (and vice versa).
 
 ## End-to-End {#end-to-end}
 
@@ -221,7 +230,7 @@ An email endpoint in pEp is the MUA on a user's end-device: that is,
 encryption and decryption of messages SHALL be end-device-based and
 MUST NOT happen on a server infrastructure.
 
-\[\[ **TODO**: Add corporate settings with Key Escrow / Extra Keys \]\]
+\[\[ **TODO**: Add enterprise settings with Key Escrow / Extra Keys \]\]
 
 ## Peer-to-Peer {#peer-to-peer}
 
@@ -250,9 +259,10 @@ be done using a structured format, to faciliate the synchronization of state
 information across various devices, taking into account multi-device scenarios,
 which are common today.
 
-In pEp's reference implementation, keys are hold using the key store of the
-cryptographic library used, while peer-specific state information, including
-trust information is held in a simple relational database.
+In pEp's reference implementation (cf. {{implementation-status}}),
+keys are hold using the key store of the cryptographic library used,
+while peer-specific state information, including trust information is
+held in a simple relational database.
 
 \[\[ **TODO**: Check optimal order the following sections. \]\]
 
@@ -265,7 +275,7 @@ the network address.
 
 For now, a key in pEp for email is an OpenPGP key. Each 
 identity has a default key attached to it. This is the public 
-key to be used to encrypto communications to it.
+key to be used to encrypt communications to it.
 
 ### User {#elements-user}
 
@@ -278,6 +288,9 @@ Each user has at last one identity.
 
 An identity in pEp for email is represented by an email
 address, like mailto:alice@example.org. 
+<!-- HB:
+address vs. URI
+-->
 
 This can be Alice with her real name, using this identity for 
 private purposes. Should Alice create another address, like 
@@ -287,10 +300,14 @@ pair when a new email account is being configured, such as to
 not allow correlation by using the same key. If in turn, Alice 
 wants different addresses of her to be collapsed into one 
 single identity with one single key, then the user has to configure 
-them as an aliases. 
+them as aliases. 
 
 If various email addresses represent the same identity, this
-is called an alias.
+is called an alias (cf. {{elements-alias}}).
+<!-- HB:
+This section needs rework, e.g. Alice vs. the user, consistency using alias
+-->
+
 
 ### Alias {#elements-alias}
 
@@ -306,6 +323,11 @@ formats, which ensure messages to be signed and encrypted. In accordance with
 pEp's privacy (and not security) focus, signed-only messages SHALL NOT be 
 supported. <!-- todo: addreason --> While pEp-enabled clients MUST be able to 
 render all pEp Email Formats properly, it's RECOMMENDED to use pEp Email Format 2.1.
+<!-- HB
+- why restricted to PGP/MIME? How about S/MIME?
+- Better distinguish by sending and receiving side
+-->
+
 
 Since pEp Email Format 2.0, a compatibility format (i.e., pEp Email Format 
 1.0, cf. {{pef-1-0}}) exists, which SHOULD be applied towards non-pEp users, 
@@ -314,6 +336,10 @@ for which trustworthy public keys are available according to the local database.
 In case no suitable encryption key is available, an unencrypted, unsigned
 MIME email is sent out. This message SHALL contain the sender's public
 key, unless Passive Mode (cf. {{passive-mode}}) is active.
+<!-- HB
+not only in unencrypted case
+-->
+
 
 ### Unencrypted pEp Format {#pef-0}
 
@@ -322,6 +348,9 @@ This is the format to be used when unencrypted messages are sent out.
 The unencrypted pEp format is a multipart/mixed MIME format, which
 by default ensures the delivery of the sender's public key disposed
 as an attachment.
+<!-- HB
+disposed? sounds like trashed
+--->
 
 In its simplest form, such an email looks like the following:
 
@@ -331,6 +360,10 @@ In its simplest form, such an email looks like the following:
 
 {::include ../shared/fence-line.mkd}
 
+<!-- HB
+Added BEGIN and END lines (for key) to the example
+-->
+
 The "pEpkey.asc" file attachment holds the sender's OpenPGP public key in 
 ASCII-armored format, which is suitable for manual key import by non-pEp
 users. Thus, a user of any OpenPGP-enabled MUA is able to manually import the
@@ -363,35 +396,57 @@ which in case of a simple text-only email without attachments and
 other Content-Types has (1) a text/plain Content-Type with the 
 PGP-encrypted content and (2) the sender's tranferable public key 
 at the very end.
+<!-- HB
+This is too prominent for something that is deprecates.
+should rather be some side remark at the end of this section.
+Condider not to name the actual version "modern version"
+-->
+
 
 The modern version of PEF-1.0 instead, has a multipart/encrypted MIME
 node on the wire format with an OpenPGP encrypted and signed filename 
 "msg.asc" to be disposed inline.
 
-By default, the subject SHALL be set to "pEp" or alternatively to its 
-UTF-8 representation as =?utf-8?Q?p=E2=89=A1p?=. This is the only header 
-field which can be protected in this format. To achieve this, the intended
-subject value is moved in encrypted form into the very first text/plain 
-Content-Type--as the first line, like this:
+By default, the subject SHALL be set to "pEp" or alternatively to its
+UTF-8 representation as =?utf-8?Q?p=E2=89=A1p?=. This is the only
+header field which can be protected in this format. To achieve its
+protection, the real subject value is added to the top of the content
+section of the very first MIME entity with media type "text/plain",
+that is encrypted, e.g.:
+
 > Subject: Credentials
 
-Thus, legacy clients not aware of pEp's subject encryption, are still able 
-to grasp the actual subject (in the above example: "Credentials") disposed 
-inline. That subject line MUST also be rendered by pEp-implementing MUAs
-if it is written as "subject:" or "SUBJECT:" (i.e., this mechanism is not
-case-sensitive).
+<!-- HB
+- SHALL is too strong here, as this does not impact interoperability
+- should be made more readable
+-->
+
+Thus, legacy clients not aware of pEp's subject encryption, still
+display the actual subject (in the above example: "Credentials") to
+the user. Whenever the first encrypted "text/plain" MIME entity
+contains such a subject line, pEp-implementing MUAs MUST render it to
+the user. Note that this mechanism inherits the case-insensitiveness,
+e.g. also "subject:" or "SUBJECT:" are to be rendered.
 
-For clients not implementing the pEp functionality, but which only aim to 
-stay as interoperable as possible with pEp-enabled MUAs, it's OPTIONAL to add 
+<!-- HB
+It is a good idea to allow for the latter variation? IMHO there should
+be one (and only one way) of putting the Subject to the MIME content.
+-->
+
+Clients not (fully) implementing pEp, but still aim to 
+stay as interoperable as possible with pEp-enabled MUAs, it is OPTIONAL to add 
 the header "X-pEp-Version: 1.0" when using this format: this is considered
 implicitly the case. The reason for that is that pEp implementers are only
 REQUIRED to hold users exposing "X-pEp-Version: 2.0" or higher as actual
 pEp users. Very ancient pEp users and not pEp users are served with this
 compatibiltiy format.
+<!-- HB
+should be rewritten
+-->
 
 A modern pEp-enabled MUA, however, SHALL add the X-pEp-Version header with 
 its highest value (preferly with value "2.1" as for pEp Email Format 
-2.1 {{pef-2-1}}) when producing this format, so as to announce oneself as
+2.1 {{pef-2-1}}) when producing this format, in order to announce oneself as
 a pEp MUA with the capability to receive and render more privacy-preserving 
 formats. That is, upgrading both sides to modern pEp-enabled MUAs, allows
 them to upgrade to more privacy-enhancing formats, also protecting (more)
@@ -438,7 +493,7 @@ Decrypting the enclosed "msg.msc" part yields the following:
 {::include ../shared/fence-line.mkd}
 
 Note that in either case, the actual subject's value is encrypted in 
-the very first text/plain MIME part under a multipart/mixed MIME node.
+the very first text/plain MIME entity under a multipart/mixed MIME node.
 
 ### pEp Email Format 2.0 {#pef-2-0}