Skip to content

Aries RFC 0021: DIDComm Message Anatomy

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.

  1. 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.
  2. 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.
  3. 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