Aries RFC 0021: DIDComm Message Anatomy¶
- Authors: Tobias Looker, Daniel Hardman
- Status: ADOPTED
- Since: 2019-05-25
- Start Date: 2019-05-25
- Tags: concept, decorator
Summary¶
Explain the basics of DID communication messages at a high level, and link to other RFCs to promote deeper exploration.
Motivation¶
Promote a deeper understanding of the DIDComm message anatomy through a overarching view of the two distinct levels of messages in a single place.
Tutorial¶
DIDComm messages are comprised of the following two main layers, which are not dissimilar to how postal messages occur in the real world.
Envelope Level¶
As the name suggests, envelope
borrows from the analogy of how physical messages are handled in the postal system, this message format level acts as the digital envelope for DIDComm messages.
There are two main variations of the envelope level format which are defined to cater for the different audiences and use cases DIDComm messages serve.
1. Encrypted¶
This format is for when the audience of the message is a DID or DID's known to the sender, in this case the message can be prepared and encrypted with the key information present in the audiences DID docs.
Within this encrypted format, there are multiple sub-formats which give rise to different properties.
- Anonymous Encrypted format This format is when a message is encrypted to a recipient in an anonymous fashion, and it does not include any sender information.
- Authenticated Encrypted format This format is when a message is encrypted to a recipient and sender information is included through the use of authenticated encryption. With this format only the true recipient(s) can both decrypt the message and authenticate its content is truly from the sender.
- Signed Encrypted format This format is when a message is encrypted to the recipient and sender information is included along with a non-repudiable signature. In this case the recipient(s) is still the only party that can decrypt the message. However, because the underlying message includes non-repudiability, authentication of the decrypted message content can be done by any party who knows the sender.
2. Signed Unencrypted¶
This format is for when the audience of the message is unknown (for example some form of public challenge). This format is signed, so that when a member of the audience receives the message they can authenticate the message with its non-repudiable signature.
Serialization Format¶
All of the envelope level formats are achieved through JOSE based structures. The encrypted formats uses a JWE structure, whereas the signed unencrypted format uses a JWS structure.
Details on the encrypted forms are found here
Details on the signed un-encrypted are TBC
Content Level¶
This level to continue the postal metaphor is the content inside the envelope and contains the message.
At this level, several conventions are defined around how messages are structured, which facilitates in message identification and processing.
The most important ../../concepts to introduce about these conventions are the following.
Message Type¶
Every message contains a message type which allows the context of the message to be established and therefore process the content, see here for more information. It is also important to note that in DIDComm, the message identification does not just identify the message, the message type also identifies the associated protocol. These protocols are essentially a group of related messages that are together required to achieve some form of multi-step flow see here for more information.
Message Id¶
Every message contains a message id which is uniquely generated by the sender, this allows unique identification of the message. See here for more information.
Decorators¶
DIDComm messages at a content level allow for the support of re-usable conventions that are present across multiple messages in order to handle the same functionality in a consistent manner.
A relevant analogy for decorators, is that they are like HTTP headers in a HTTP request. The same HTTP header is often reused as a convention across multiple requests to achieve cross cutting functionality.
See here for more details.
Serialization Format¶
At present all content level messages are represented as JSON. Further more these messages are also JSON-LD sympathetic however they do not have full and direct support for JSON-LD.
Reference¶
All references are defined inline where required.
Drawbacks¶
Why should we not do this?
Rationale and alternatives¶
Prior art¶
Unresolved questions¶
Implementations¶
The following lists the implementations (if any) of this RFC. Please do a pull request to add your implementation. If the implementation is open source, include a link to the repo or to the implementation within the repo. Please be consistent in the "Name" field so that a mechanical processing of the RFCs can generate a list of all RFCs supported by an Aries implementation.
Name / Link | Implementation Notes |
---|---|