Merge pull request #386 from dhh1128/236

fix 236

docs/spec-files/message_structure.md

@@ -10,14 +10,19 @@ Circumstances sometimes require communication about the format of DIDComm messag
 
 All three DIDComm message formats — plaintext, signed, and encrypted — can be correctly understood as more generic [JWMs (JSON Web Messages)](https://tools.ietf.org/html/draft-looker-jwm-01) or even as arbitrary JOSE content. Since code that expects JOSE conventions but not DIDComm may matter in some implementations, this spec recommends the JOSE convention of [using `typ` to make JOSE structure formats self-describing](https://tools.ietf.org/html/rfc7515#section-4.1.9). This is particularly helpful in the outermost envelope of any DIDComm message, before unwrapping begins. (As RFC 7515 notes, `typ` "will typically not be used by applications when the kind of object is already known.")
 
-The relevant media types are:
-
-| Envelope | `typ` |
-|-----------------|-------|
-| Authcrypted and/or anoncrypted | `application/didcomm-encrypted+json`|
-| Signed and then anoncrypted | `application/didcomm-encrypted+json`|
-| Signed | `application/didcomm-signed+json` |
-| Plaintext | `application/didcomm-plain+json`|
+When a sender prepares a message for [routing](#routing-protocol-20), it wraps the message once for each hop that has cryptographic consequences in the path. Each wrapping operation applies one or more layers of envelope, and potentially transforms the associated media type of the output. The relevant possibilities are: 
+
+| Envelopes | IANA type (`typ` header) | Notes
+|-----------------|-------|----|
+| plaintext (no envelope) | `application/didcomm-plain+json`| Used as the building block of [higher-level protocols](#protocols), but rarely transmitted directly, since it lacks security guarantees.
+| signed(plaintext) | `application/didcomm-signed+json` | Adds non-repudiation to a plaintext message; whoever receives a message wrapped in this way can prove its origin to any external party.
+| anoncrypt(plaintext) | `application/didcomm-encrypted+json` | Guarantees confidentiality and integrity without revealing the identity of the sender.
+| authcrypt(plaintext)  | `application/didcomm-encrypted+json` | Guarantees confidentiality and integrity. Also proves the identity of the sender -- but in a way that only the recipient can verify. This is the default wrapping choice, and SHOULD be used unless a different goal is clearly identified. By design, this combination and all other combinations that use encryption in their outermost layer share an identical IANA media type, because only the recipient should care about the difference.
+| anoncrypt(sign(plaintext)) | `application/didcomm-encrypted+json`| Guarantees confidentiality, integrity, and non-repudiation -- but prevents an observer of the outer envelope from accessing the signature. Relative to authcrypt(plaintext), this increases guarantees to the recipient, since non-repudiation is strong than simple authentication. However, it also forces the sender to talk "on the record" and is thus not assumed to be desirable by default. 
+| authcrypt(sign(plaintext)) | `application/didcomm-encrypted+json` | Adds no useful guarantees over the previous choice, and is slightly more expensive, so this wrapping combination SHOULD NOT be emitted by conforming implementations. However, implementations MAY accept it. If they choose to do so, they MUST emit an error if the signer of the plaintext is different from the sender identified by the authcrypt layer.
+| anoncrypt(authcrypt(plaintext)) | `application/didcomm-encrypted+json` | A specialized combination that hides the `skid` header in the authcrypt envelope, so the hop immediately sourceward of a mediator cannot discover an identifier for the sender. See [Protecting the Sender Identity](#protecting-the-sender-identity). 
+
+In the aggregate, complex combinations of envelopes may occur across a route. However, in the set of envelopes that targets a single hop, envelope combinations other than the ones above MUST NOT be used. In particular, it makes no sense to use anoncrypt(authcrypt(sign(plaintext))); use anoncrypt(sign(plaintext)) instead.
 
 [Aligning with RFC 7515](https://tools.ietf.org/html/rfc7515#section-4.1.9), IANA types for DIDComm messages MAY omit the `application/` prefix; the recipient MUST treat media types not containing `/` as having the `application/` prefix present.