juga
/
internet-drafts
forked from pEp.foundation/internet-drafts
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Work with HB on clarifications of the PEFs; other minor changes.

Browse Source
master
Hernâni Marques 3 years ago
parent 6c4aaf3355
commit 678d49eb6e
Signed by untrusted user: hernani
GPG Key ID: CB5738652768F7E9
1 changed files with 102 additions and 143 deletions
Show Stats Download Patch File Download Diff File

245
pep-email/draft-pep-email.mkd
Unescape View File

@ -303,8 +303,24 @@ MIME email is sent out. As in all pEp formats, also this (unprotected) message
MUST contain the sender's public key, unless Passive Mode
(cf. {{passive-mode}}) is active.
All pEp Email Formats include a "pEpkey.asc" file attachment holding 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 public key and engage in end-to-end
encryption with the pEp sender. MUA implementers of PGP-capable email clients,
even when not fully supporting pEp's protocols, are encouraged to
automatically import the key such that the user can immediately engage in
opportunistic encryption.
In pEp's reference implementation the subject is set to "pEp" (or
alternatively to its UTF-8 representation as "=?utf-8?Q?p=E2=89=A1p?=").
However, the subject's value of the outer message MUST be ignored. Therefore,
the subject can be set to any value (e.g., "..." as used in other
implementations).
<!-- Points to add here are things which are common to all formats, like:
- UTF-8 charset to be used always
- X-pEp-Version header always to be set by pEp-enabled MUAs
- ...
-->
@ -324,85 +340,52 @@ A simple plaintext email looks like the following:
{::include ../shared/fence-line.mkd}
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
public key and engage in end-to-end encryption with the pEp sender. MUA
implementers of PGP-capable email clients, even when not fully supporting
pEp's protocols, are encouraged to automatically import the key such that
the user can immediately engage in opportunistic encryption.
<!-- Commented by HB (wrong place)
On the other hand,
they SHOULD NOT use the "X-pEp-Version" header field to signal they are pEp
clients, if they are not following pEp's message formats and protocols.
-->
The plain text messages MUST be sent out with the UTF-8 charset
Content-Type set.
### pEp Email Format 1.0 {#pef-1-0}
pEp Message Format 1.0 (PEF-1.0) is an encrypted and signed PGP/MIME
format, which by default ensures:
pEp Email Format 1.0 (PEF-1.0) is an encrypted and signed MIME format, which
by default ensures:
* a signed and encrypted message, with subject encryption
* delivery of the sender's public key
PEF-1.0 has a "multipart/encrypted" MIME node on the wire format with an
OpenPGP encrypted and signed filename "msg.asc" with attribute
"Content-Disposition: inline".
PEF-1.0 has a "multipart/encrypted" MIME entity on the wire format with an
OpenPGP encrypted and signed filename "msg.asc" to be disposed inline.
By default, the subject SHOULd be set to "pEp" or alternatively to its
UTF-8 representation as =?utf-8?Q?p=E2=89=A1p?=. The subject is the only
header field that can be protected with PEF-1.0. 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",
The subject is the only header field that can be protected with PEF-1.0. 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
<!-- HB
- 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 also lines starting with "subject:" or "SUBJECT:"
are to be rendered (as with header fields, this marker is
case-insensitive).
It's OPTIONAL for clients to add the "X-pEp-Version: 1.0" header field,
as this format is implicitly assumed. Only users exposing
"X-pEp-Version: 2.0" or "X-pEp-Version: 2.1" are treated as pEp users.
Only ancient pEp users and non-pEp users are served with this
compatibiltiy format.
A pEp-enabled MUA, however, MUST 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, 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)
metadata.
are to be rendered (as with header fields, this is case-insensitive).
A pEp-enabled MUA MUST add the "X-pEp-Version" header field with
its highest value (preferably with value "2.1" as for pEp Email Format
2.1 {{pef-2-1}}) when producing this format. Herewith, a pEp-enabled MUA
announce its capability to receive and render more privacy-preserving
formats. Upgrading both sides to the highest version of the pEp Email Format
allows pEp-enabled MUAs for best possible protection of metadata. For non-pEp
MUAs it is OPTIONAL to add the "X-pEp-Version: 1.0" header field. However,
this format is implicitly assumed (if this header field is not present).
Please note that for messages between pEp- and non-pEp clients the subject
encryption MAY be disabled, sacrificing usability (avoiding artefacts
for receiving non-pEp clients) over privacy.
PEF-1.0 is also considered pEp's compatibility format towards non-pEp
clients
PEF-1.0 is also considered pEp's compatibility format towards non-pEp clients.
#### Example
PEF-1.0 looks as follows:
A PEF-1.0 example looks as follows:
{::include ../shared/fence-line.mkd}
{::include examples/pef-1-0_old.mkd}
{::include examples/pef-1-0.mkd}
{::include ../shared/fence-line.mkd}
@ -414,17 +397,16 @@ 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 entity under a multipart/mixed MIME node.
Note that the user-intended subject value is encrypted in the first
"text/plain" MIME entity under the "multipart/mixed" MIME node.
#### Deprecated variant of PEF-1.0
Some earlier variant of PEF-1.0 started with a "multipart/mixed" MIME entity,
An earlier variant of PEF-1.0 started with a "multipart/mixed" MIME node,
which in case of a simple text-only email without attachments and
other MIME entities has
(1) a "text/plain" MIME Entity with the PGP-encrypted content, and
(1) a "text/plain" MIME entity with the PGP-encrypted content, and
(2) the sender's tranferable public key at the very end.
@ -443,12 +425,9 @@ like the following; most obviously, the intended subject line
is now visible:
{::include ../shared/fence-line.mkd}
{::include examples/pef-1-0-text-payload.mkd}
{::include ../shared/fence-line.mkd}
### pEp Email Format 2.0 {#pef-2-0}
pEp Email Format 2.0 (PEF-2.0) is a strict MIME format, which by
@ -458,17 +437,18 @@ default ensures:
* delivery of the sender's public key
In PEF-2.0, the actual email (inner message) is encapsulated by a MIME
entity (media type "message/rfc822"), which is the second part of
another MIME entity (media type "multipart/mixed"). The first part of
this "multipart/mixed" MIME entity contains a text/plain element,
containing a marker "pEp-Message-Wrapped-Info: OUTER" in its body for
proper displaying and mapping of the nested message and its encrypted
header fields. Like with the PEF-1.0, the third (and last) part of
this "multipart/mixed" MIME entity MUST contain the sender's public
key.
The "multipart/mixed" MIME entity is contained in yet another MIME
entity (media type "multipart/encrypted", cf. {{RFC1847}} /
entity ("Content-Type: message/rfc822"), which is the second part of a
"multipart/mixed" MIME node. The first part of this MIME node contains a
"text/plain" MIME entity, including a marker text
"pEp-Message-Wrapped-Info: OUTER" (in its MIME content). This is used for
proper displaying and mapping of the nested message and its encrypted header
fields. Like with the PEF-1.0 (cf. {{pef-1-0}}), the third (and last) part of
the "multipart/mixed" MIME node MUST contain the sender's public key.
<!-- TODO: Explain pEp-Wrapped-Message-Info: INNER (and OUTER) markers. -->
The "multipart/mixed" MIME node is encrypted inside yet another MIME
node ("Content-Type: multipart/encrypted", cf. {{RFC1847}} /
{{RFC3156}}), which is the body part of the outer message.
Thus, the whole header section of the inner message can be fully
@ -476,43 +456,31 @@ preserved, not only encrypted, but also signed. In the outer message,
however, when communicating with pEp users all header fields not
needed MUST be omitted to the fullest extent possible.
As with PEF-1.0 {{pef-1-0}} the public key and other files attached
are structured in MIME tree (inner message). Once encrypted, only the
outer message consisting of the (minimal) outer header section and the
"multipart/encrypted" MIME entity as body with a
Once encrypted, only the outer message consisting of the (minimal) outer
header section and the "multipart/encrypted" MIME entity as body with a
application/octet-stream "Content-Type" with name "msg.asc" is visible
on the wire.
If the receiving side is not a known pEp-enabled MUA, but a public key is
available, PEF-1.0 (cf. {{pef-1-0}}) MUST be used to send the email.
If the receiving side is not a known pEp-enabled MUA, but a trustworthy
public key is available, PEF-1.0 (cf. {{pef-1-0}}) MUST be used to send the
email.
In any case, the "X-pEp-Version" header field is set to version 2.0,
In any case, the "X-pEp-Version" header field MUST be set to version 2.0,
as the highest version the sender supports.
<!--
#### Examples
##### Example PEF-2.0: pEp to pEp {#pef-2-0-ex1}
-->
The following example shows a PEF-2.0 multipart/encrypted email,
signed and encrypted, as an 7bit octet stream with a filename
"msg.asc", with inline content disposition.
In within that, the original email message is fully contained
in encrypted form (like this, also the subject line gets
encrypted). The support of version 2.0 is announced in the "X-pEp-Version"
header field (in the example, 2.0 is the newest pEp Email Format
the pEp-enabled MUA is able to produce and render):
"msg.asc", with "Content-Disposition: inline". In within that,
the original email message is fully contained in encrypted form (like this,
also the subject line gets encrypted). The support of version 2.0 is
announced in the "X-pEp-Version" header field (in this example, 2.0 is the
newest pEp Email Format the pEp-enabled MUA is able to produce and render):
{::include ../shared/fence-line.mkd}
{::include examples/pef-2-0.mkd}
{::include ../shared/fence-line.mkd}
Decrypting "msg.asc" results in a multipart/mixed structure, with
three elements:
Decrypting "msg.asc" results in a multipart/mixed node, with three elements:
(1) a text part indicating this is the encapsulated message
@ -523,13 +491,11 @@ three elements:
An unwrapped example looks like this:
{::include ../shared/fence-line.mkd}
{::include ../shared/fence-line.mkd}
{::include examples/msg-part-decrypted-pef-2-0.mkd}
{::include ../shared/fence-line.mkd}
<!-- HB: Isn't this simply a repetion of PEF-1.0?
##### Example PEF-2.0: pEp to non-pEp {#pef-2-0-ex1-compat}
@ -559,91 +525,82 @@ Concretly, that "msg.asc" element, when decrypted, looks like the following:
### pEp Email Format 2.1 {#pef-2-1}
pEp Email Format 2.1 (PEF-1.1) introduces further pEp-specific header
pEp Email Format 2.1 (PEF-2.1) introduces further pEp-specific header
fields to the inner message, which help to determine the behaviour
between pEp users.
<!-- TODO: Explain that behaviour. -->
In normal interpersonal messaging those additional header fields are:
(1) "X-pEp-Wrapped-Message-Info: INNER" header field stating that the
message carrying this is to be considered the most inner message
containing the actual payload (this is particulary relevant for mixnet
or other scenarios of nested messaging; cf {{pEp.mixnet}})
containing the original email (this is particulary relevant for mixnet
or other scenarios of nested messaging; cf. {{pEp.mixnet}})
(2) X-pEp-Sender-FPR with the value set to sender's full 160-bit
(2) "X-pEp-Sender-FPR" header field with the value set to sender's full 160-bit
public key fingerprint (e.g.,
"1234567890ABCDEF1234567890ABCDEF12345678"), and
(3) the X-pEp-Version header field set to version "2.1".
(3) the "X-pEp-Version" header field set to version "2.1".
<!-- TODO: Explain all the other headers which exists, e.g., for technical
messages (Key Reset / Sync etc.). -->
As with PEF-2.0 ({{pef-2-0}}), the actual email (inner message) is
encapsulated by a MIME entity (media type "message/rfc822"), which is
the second part of another MIME entity (media type "multipart/mixed").
The first part of this "multipart/mixed" MIME entity contains a
text/plain element, which SHOULD be used to inform about the nature of
this format (in case a non-pEp client encounters in the mailbox). It
MAY be used to carry the intended subject of the inner message (which
is not done in current reference implementations). Like with the
PEF-1.0 and PEF 2.0, the third (and last) part of this
"multipart/mixed" MIME entity MUST contain the sender's public key.
As with PEF-2.0 {{pef-2-0}}, in PEF-2.1 the actual email (inner message)
is encapsulated by a MIME entity ("Content-Type: message/rfc822"), which is
the second part of a "multipart/mixed" MIME node. The first part of this MIME
node contains a "text/plain" MIME entity, which SHOULD be used to inform about
the nature of this format (in case a non-pEp client encounters in the mailbox).
It MAY be used to carry the intended subject of the inner message (which
is not done in current reference implementations). Like with the PEF-1.0
(cf. {{pef-1-0}}) and PEF 2.0 (cf. {{pef-2-0}}), the third (and last) part of
this "multipart/mixed" MIME node MUST contain the sender's public key.
As with PEF-2.0 ({{pef-2-0}}), the "multipart/mixed" MIME entity is
contained in yet another MIME entity (media type
"multipart/encrypted", cf. {{RFC1847}} / {{RFC3156}}), which is the
body part of the outer message.
This "multipart/mixed" MIME node is encrypted inside yet another MIME
node ("Content-Type: multipart/encrypted", cf. {{RFC1847}} /
{{RFC3156}}), which is the body part of the outer message.
An caveat of PEF-2.1 is that message rendering varies considerably
across different MUAs. This is relevant as it may happen that a
non-pEp MUA encounters a PEF-2.1 message (e.g. if a pEp-enabled client
across different MUAs. This is relevant as it might happen that a
non-pEp MUA encounters a PEF-2.1 message (e.g., if a pEp-enabled client
was used in the past). No standard is currently available which
enables MUAs to reliably determine whenever a nested message/rfc822
entity is meant to blend the containing message, or if it was
enables MUAs to reliably determine whenever a nested "message/rfc822" MIME
entity is meant to render the contained email message, or if it was
effectively intended to be forwarded as an attachment, where a user
needs to click on in order to see its content. To help unaware MUAs, a
Content-Type header field parameter with name "forwarded" as per
{{I-D.melnikov-iana-reg-forwarded}} is added to the Content-Type
header field. MUAs can use this to distinguish between a forwarded
message and a nested message for the purpose of header protection
(i.e., using "forwarded=no").
message and a nested message (i.e., using "forwarded=no").
When the receiving peer was registered as being only PEF-2.0-capable,
the message must be sent in PEF-2.0 {{pef-2-0)). The reason for this
the message must be sent in PEF-2.0 (cf. {{pef-2-0}}). The reason for this
is that pEp-enabled MUAs which are only PEF-2.0-capable rely on the
plaintext "pEp-Message-Wrapped-Info: OUTER" and
"pEp-Message-Wrapped-Info: INNER" markers to properly display and map
the nested message and its encrypted header fields.
As with PEF-1.0, if the receiving side is not a known pEp-enabled MUA,
but a public key is available, PEF-1.0 (cf. {{pef-1-0}}) MUST be used
to send the email.
but a trustworthy public key is available, PEF-1.0 (cf. {{pef-1-0}}) MUST be
used to send the email.
In any case, the "X-pEp-Version" header field is set to version 2.1,
In any case, the "X-pEp-Version" header field MUST be set to version 2.1,
as the highest version the sender supports.
<!--
#### Examples
##### Example PEF-2.1: pEp to pEp {#pef-2-1-ex1}
-->
This is an example of what the format looks like between two
PEF-2.1-capable clients:
{::include ../shared/fence-line.mkd}
{::include examples/pef-2-1.mkd}
{::include ../shared/fence-line.mkd}
Unwrapping the "msg.asc" multipart/encrypted MIME part, yields this:
Unwrapping the "multipart/encrypted" MIME node, yields this:
{::include ../shared/fence-line.mkd}
{::include examples/msg-part-decrypted-pef-2-1.mkd}
{::include ../shared/fence-line.mkd}
<!-- Repetition?
##### Example PEF-2.1: pEp to pEp (support version 2.0) {#pef-2-1-ex2}
@ -756,8 +713,10 @@ For the second group, individual Bcc email Messages are sent.
### Protocol Negotiation for Format Selection
To be able to decide which email format to generate, the pEp-enabled MUA
REQUIRES to record state on a per-identity basis. Once a X-pEp-Version header
field is discovered, the user MUST be recorded as a pEp user.
REQUIRES to record state on a per-identity basis. Once a "X-pEp-Version" header
field is discovered, the user MUST be recorded as a pEp user and the
corresponding pEp Version it supports (according to the highest value of the
"X-pEp-Version" header field encountered).
### Saving Messages

Write Preview
Loading…
Cancel
Save