Skip to content

Aries RFC 0794: DID Rotate 1.0

Summary

This protocol signals the change of DID in use between parties.

This protocol is only applicable to DIDComm v1 - in DIDComm v2 use the more efficient DID Rotation header.

Motivation

This mechanism allows a party in a relationship to change the DID they use to identify themselves in that relationship. This may be used to switch DID methods, but also to switch to a new DID within the same DID method. For non-updatable DID methods, this allows updating DID Doc attributes such as service endpoints. Inspired by (but different from) the DID rotation feature of the DIDComm Messaging (DIDComm v2) spec.

Implications for Software Implementations

Implementations will need to consider how data (public keys, DIDs and the ID for the relationship) related to the relationship is managed. If the relationship DIDs are used as identifiers, those identifiers may need to be updated during the rotation to maintain data integrity. For example, both parties might have to retain and be able to use as identifiers for the relationship the existing DID and the rotated to DID, and their related keys for a period of time until the rotation is complete.

Tutorial

Name and Version

DID Rotate 1.0

URI: https://didcomm.org/did-rotate/1.0/

Roles

rotating_party: this party is rotating the DID in use for this relationship. They send the rotate message.

observing_party: this party is notified of the DID rotation

Messages

Rotate

Message Type URI: https://didcomm.org/did-rotate/1.0/rotate

to_did: The new DID to be used to identify the rotating_party

{
    "@id": "123456780",
    "@type": "https://didcomm.org/did-rotate/1.0/rotate",
    "to_did": "did:example:newdid",

}

The rotating_party is expected to receive messages on both the existing and new DIDs and their associated keys for a reasonable period that MUST extend at least until the following ack message has been received.

This message MUST be sent using AuthCrypt or as a signed message in order to establish the provenance of the new DID. In Aries implementations, messages sent within the context of a relationship are by default sent using AuthCrypt. Proper provenance prevents injection attacks that seek to take over a relationship. Any rotate message received without being authcrypted or signed MUST be discarded and not processed.

DIDComm v1 uses public keys as the outer message identifiers. This means that rotation to a new DID using the same public key will not result in a change for new inbound messages. The observing_party must not assume that the new DID uses the same keys as the existing relationship.

Ack

Message Type URI: https://didcomm.org/did-rotate/1.0/ack

This message has been adopted from [the ack protocol] (https://github.com/hyperledger/aries-rfcs/tree/main../../features/0015-acks).

This message is still sent to the prior DID to acknowledge the receipt of the rotation. Following messages will be sent to the new DID.

In order to correctly process out of order messages, the The observing_party may choose to receive messages from the old DID for a reasonable period. This allows messages sent before rotation but received after rotation in the case of out of order message delivery.

In this message, the thid (Thread ID) MUST be included to allow the rotating_party to correlate it with the sent rotate message.

{
    "@id": "123456780",
    "@type": "https://didcomm.org/did-rotate/1.0/ack",
      "~thread"          : {
        "thid": "<id of rotate message>"
    },

}

Problem Report

Message Type URI: https://didcomm.org/did-rotate/1.0/problem-report

This message has been adopted from [the report-problem protocol] (https://github.com/hyperledger/aries-rfcs/blob/main../../features/0035-report-problem/README.md).

If the observing_party receives a rotate message with a DID that they cannot resolve, they MUST return a problem-report message.

The description code must be set to one of the following: - e.did.unresolvable - used for a DID who's method is supported, but will not resolve - e.did.method_unsupported - used for a DID method for which the observing_party does not support resolution. - e.did.doc_unsupported - used for a DID for which the observing_party does not find information sufficient for a DIDComm connection in the resolved DID Document. This would include compatible key types and a DIDComm capable service endpoint.

Upon receiving this message, the rotating_party must not complete the rotation and resolve the issue. Further rotation attempts must happen in a new thread.

{
  "@type"            : "https://didcomm.org/did-rotate/1.0/problem-report",
  "@id"              : "an identifier that can be used to discuss this error message",
  "~thread"          : {
        "pthid": "<id of rotate message>"
    },
  "description"      : { "en": "DID Unresolvable", "code": "e.did.unresolvable" },
  "problem_items"    : [ {"did": "<did_passed_in_rotate>"} ],
}

Hangup

Message Type URI: https://didcomm.org/did-rotate/1.0/hangup

This message is sent by the rotating_party to inform the observing_party that they are done with the relationship and will no longer be responding.

There is no response message.

Use of this message does not require or indicate that all data has been deleted by either party, just that interaction has ceased.

{
    "@id": "123456780",
    "@type": "https://didcomm.org/did-rotate/1.0/hangup"
}

Prior art

This protocol is inspired by the rotation feature of DIDComm Messaging (DIDComm v2). The implementation differs in important ways. The DIDComm v2 method is a post rotate operation: the first message sent AFTER the rotation contains the prior DID and a signature authorizing the rotation. This is efficient, but requires the use of a message header and a higher level of integration with message processing. This protocol is a pre rotate operation: notifying the other party of the new DID in advance is a less efficient but simpler approach. This was done to minimize adoption pain. The pending move to DIDComm v2 will provide the efficiency.

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.

Implementation Notes may need to include a link to test results.

Name / Link Implementation Notes