Aries RFC 0067: DIDComm DID document conventions¶
- Authors: Tobias Looker, Stephen Curran
- Status: PROPOSED
- Since: 2019-06-10
- Status Note: This revises the former INDY HIPE
- Start Date: 2019-04-15
- Tags: feature
Summary¶
Explain the DID document conventions required to enable DID communications.
Motivation¶
Standardization of these conventions is essential to promoting interoperability of DID communications.
Tutorial¶
DID documents¶
A DID document is the associated data model to a DID, it contains important associated cryptographic information and a declaration of capabilities the DID supports.
Of particular interested to this RFC is the definition of service endpoints. The primary object of this RFC is to document the DID communication service type and describe the associated conventions.
Service Conventions¶
As referenced above within the DID specification lies a section called service endpoints, this section of the DID document is reserved for any type of service the entity wishes to advertise, including decentralized identity management services for further discovery, authentication, authorization, or interaction
.
When a DID document wishes to express support for DID communications, the following service definition is defined.
{
"service": [{
"id": "did:example:123456789abcdefghi#did-communication",
"type": "did-communication",
"priority" : 0,
"recipientKeys" : [ "did:example:123456789abcdefghi#1" ],
"routingKeys" : [ "did:example:123456789abcdefghi#1" ],
"accept": [
"didcomm/aip2;env=rfc587",
"didcomm/aip2;env=rfc19"
],
"serviceEndpoint": "https://agent.example.com/"
}]
}
- id : Required by the Service Endpoints Spec.
- type : Required by the Service Endpoints Spec. It is mandatory that this field is set to
did-communication
- priority : This represents the priority of the service endpoint, used for distinction when multiple
did-communication
service endpoints are present in a single DID document. It is mandatory that this field is set to an unsigned integer with the default value of0
. - recipientKeys : This is an array of did key references used to denote the default recipients of an endpoint. (note-1)
- routingKeys: This is an array of did key references, ordered from most destward to most srcward, used to denote the individual routing hops in between the sender and recipients. See TBC for more information on how routing is intended to operate.
accept
- [optional] an array of media types in the order of preference for sending a message to the endpoint. Ifaccept
is not specified, the sender uses its preferred choice for sending a message to the endpoint. RFC 0044 provides a general discussion of media types.- serviceEndpoint : Required by the Service Endpoints Spec. This URL based endpoint is used to declare how the message should be sent. DID communication is transport agnostic, and therefore leverages existing application level transport protocols. However for each transport defined, which is identified by the URL scheme e.g
http
, a set of transport specific considerations are defined see transports for more details.
Notes 1. The keys featured in this array must resolve to keys of the same type, for example a mix
Ed25519VerificationKey2018
orRsaVerificationKey2018
in the same array is invalid.
Message Preparation Conventions¶
Below describes the process under which a DID communication message is prepared and sent to a DID based on the conventions declared in the associated DID document. The scenario in which the below is predicated has the following conditions. - The sender possesses the DID document for the intended recipient(s) of a DID communication message. - The sender has created a content level message that is now ready to be prepared for sending to the intended recipient(s).
- The sender resolves the relevant
did-communication
service of the intended recipient(s) DID document. - The sender resolves the recipient keys present in the
recipientKeys
array of the service declaration. - Using the resolved keys, the sender takes the content level message and packs it inside an encrypted envelope for the recipient keys. (note-2)
- The sender then inspects the
routingKeys
array, if it is found to be empty, then the process skips to step 5. Otherwise, the sender prepares a content level message of typeforward
. The resolved keys from therecipientKeys
array is set as the contents of theto
field in the forward message and the encrypted envelope from the previous step is set as the contents of themsg
field in the forward message. Following this, for each element in theroutingKeys
array the following sub-process is repeated:- The sender resolves the current key in the routing array and takes the outputted encrypted envelope from the previous step and packs it inside a new encrypted envelope for the current key.
- The sender prepares a content level message of type
forward
. The current key in the routing array is set as the contents of theto
field in the forward message and the encrypted envelope from the previous step is set as the contents of themsg
field in the forward message.
- Resolve the service endpoint:
- If the endpoint is a valid DID URL, check that it resolves to another DID service definition. If the resolution is successful the process from step 2. is repeated using the message outputted from this process as the input message.
- If the service endpoint is not a DID URL, send the message using the transport protocol declared by the URL's scheme.
Notes 1. There are two main situations that an agent will be in prior to preparing a new message.
- The agent is responding to a message that has just been received and has the context of the sender key of the previous message. In this case, a targeted lookup of the
did-communication
service definition can be done to find the service definition that ../../features the sender key as a recipient key which would ensure that the response was delivered back to the sender.- The agent is creating a new message to a connection and will use the default
did-communication
service definition for preparation of a message. In this case, the defaultdid-communication
service definition would be used by resolving the lowest priority service definition from the connections DID document.
- When preparing this envelope the sender has two main choices to make around properties to include in envelope
- Whether to include sender information
- Whether to include a non-reputable signature
Example: Domain and DID document¶
The following is an example of an arbitrary pair of domains that will be helpful in providing context to conventions defined above.
In the diagram above:
- Alice has
- 1 Edge Agent - "1"
- 1 Cloud Agent - "2"
- 1 Domain Endpoint - "8"
- Bob has
- 2 Edge Agents - "4", "5"
- 2 Cloud Agents - "3", "6"
- 1 Domain Endpoint - "9"
Bob's DID document for his Relationship with Alice¶
Bob’s domain has 3 devices he uses for processing messages - two phones (4 and 5) and a cloud-based agent (6). As well, Bob has one agent that he uses as a mediator (3) that can hold messages for the two phones when they are offline. However, in Bob's relationship with Alice, he ONLY uses one phone (4) and the cloud-based agent (6). Thus the key for device 5 is left out of the DID document (see below). For further privacy preservation, Bob also elects to use a shared domain endpoint (agents-r-us), giving him an extra layer of isolation from correlation. This is represented by the serviceEndpoint
in the service definition not directly resolving to an endpoint URI rather resolving to another did-communication
service definition which is owned and controlled by the endpoint owner (agents-r-us).
Bobs DID document given to Alice
{
"@context": "https://w3id.org/did/v1",
"id": "did:example:1234abcd",
"publicKey": [
{"id": "3", "type": "RsaVerificationKey2018", "controller": "did:example:1234abcd","publicKeyPem": "-----BEGIN PUBLIC X…"},
{"id": "4", "type": "RsaVerificationKey2018", "controller": "did:example:1234abcd","publicKeyPem": "-----BEGIN PUBLIC 9…"},
{"id": "6", "type": "RsaVerificationKey2018", "controller": "did:example:1234abcd","publicKeyPem": "-----BEGIN PUBLIC A…"}
],
"authentication": [
{"type": "RsaSignatureAuthentication2018", "publicKey": "did:example:1234abcd#4"}
],
"service": [
{
"id": "did:example:123456789abcdefghi;did-communication",
"type": "did-communication",
"priority" : 0,
"recipientKeys" : [ "did:example:1234abcd#4" ],
"routingKeys" : [ "did:example:1234abcd#3" ],
"serviceEndpoint" : "did:example:xd45fr567794lrzti67;did-communication"
}
]
}
Agents r Us DID document - resolvable by Alice
{
"@context": "https://w3id.org/did/v1",
"id": "did:example:xd45fr567794lrzti67",
"publicKey": [
{"id": "1", "type": "RsaVerificationKey2018", "controller": "did:example:xd45fr567794lrzti67","publicKeyPem": "-----BEGIN PUBLIC X…"},
],
"authentication": [
{"type": "RsaSignatureAuthentication2018", "publicKey": "did:example:xd45fr567794lrzti67#1"}
],
"service": [
{
"id": "did:example:xd45fr567794lrzti67;did-communication",
"type": "did-communication",
"priority" : 0,
"recipientKeys" : [ "did:example:xd45fr567794lrzti67#1" ],
"routingKeys" : [ ],
"serviceEndpoint" : "http://agents-r-us.com"
}
]
}
Message Preparation Example¶
Alices agent goes to prepare a message desired_msg
for Bob.
- Alices agent resolves the above DID document
did:example:1234abcd
for Bob and resolves thedid-communication
service definition. - Alices agent then packs
desired_msg
in an encrypted envelope message to the resolved keys defined in therecipientKeys
array. - Because the
routingKeys
array is not empty, a content level message of typeforward
is prepared where theto
field of the forward message is set to the resolved keys and themsg
field of the forward message is set to the encrypted envelope from the previous step. - The resulting forward message from the previous step is then packed inside another encrypted envelope for the first and only key in the
routingKeys
array. - Inspection of the service endpoint, reveals it is a did url and leads to resolving another
did-communication
service definition, this time owned and controlled byagents-r-us
. - Because in the
agents-r-us
service definition there is a recipient key. A content level message of typeforward
is prepared where theto
field of the forward message is set to the recipient key and themsg
field of the forward message is set to the encrypted envelope from the previous step. - This content message is then packed in a encrypted envelope for the recipient key in
agents-r-us
service definition. - Finally as the endpoint listed in the serviceEndpoint field for the
agents-r-us
did-communication
service definition is a valid endpoint URL, the message is transmitted in accordance with the URL's protocol.
Reference¶
Rationale and alternatives¶
Prior art¶
Unresolved questions¶
The following remain unresolved:
- The convention for packing the message for the required routes is dependent on the array order of key references, which could be viewed as a weak/brittle convention.
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 |
---|---|