Title: Decentralized Identity on XRP Ledger Revision: 1 (2023-02-09)
Author: Aanchal Malhotra Affiliation: Ripple
Self-sovereign identity, defined as a lifetime portable digital identity that does not depend on any centralized authority, requires a new class of identifier that fulfills the following four requirements: persistence, global resolvability, cryptographic verifiability, and decentralization. World Wide Web Consortium (W3C) standardized Decentralized Identifiers (DIDs) are a new type of identifier that enable verifiable, self-sovereign digital identity and are designed to be compatible with any distributed ledger or network. In the context of digital identities, W3C's Standards for DIDs and Verifiable Credentials (VCs) are rapidly gaining traction, especially in blockchain-related domains. In this document we propose to implement native support for W3C DIDs on XRP ledger.
To this end, we specify the following on XRPL:
- A new
DID methodthat describes:- the format for XRP ledger DID, and
- defines how XRP ledger generates DIDs
- How to do
CRUD operationson XRP ledger DIDs.
This specification conforms to the requirements specified in the DID v1.0 specification currently recommended by the W3C Credentials Community Group.
This proposal chooses to recommend W3C DID standard to satisfy the following first principles.
-
Decentralized: Requires no central issuing agency and functions effectively in DeFi.
-
Persistent and portable: Inherently persistent and long-lived, not requiring the continued operation of any underlying organization.
-
Cryptographically verifiable: Based on cryptographic proofs rather than out-of-band trust.
-
Resolvable and interoperable: Open to any solution that recognizes the common W3C DID standards and requires no one specific software vendor implementation.
-
This document aims to define DID format for XRPl conformant to W3C DID standards that can be created and owned by any XRPL account holder, and specify definitions for DID methods that can be implemented by any service, wallet, or application.
-
This proposal is NOT intended as a competing decentralized identity standard; it aims to leverage existing (and emerging) decentralized identity standard proposed by W3C.
In this section we specify the implementation details of W3C DID that are specific to XRP Ledger.
We do not propose a new ledger object. Instead we introduce a new optional field DIDoc to the AccountRoot object associated with an XRP Ledger account.
| Field Name | Required? | JSON Type | Internal Type |
|---|---|---|---|
DIDoc |
Object |
Custom Object |
DIDoc field specifies a custom-defined object that contains DID related information. This field, if present, may contain the following required and optional subfields.
| Field Name | Required? | JSON Type | Internal Type |
|---|---|---|---|
URI |
:heavy check mark | String |
Blob |
URI specifies a Universal Resource Identifier, a.k.a. URI, that points to the corresponding DID document. This field could be an HTTP(S) URL or IPFS URI. The URI field is NOT checked for validity, but the field is limited to a maximum length of 256 bytes.
| Field Name | Required? | JSON Type | Internal Type |
|---|---|---|---|
Hash |
String |
Blob |
Hash specifies the SHA-256 hash of the document in the location referenced by the URI field. This is an optional field for additional security.
In this section, we describe the DID method specification that conforms to the requirements specified in the DID specification currently published by the W3C Credentials Community Group. For more information about DIDs and DID method specifications, refer to the DID Primer.
The DID format as defined by W3C is as follows:
"did:" method-name ":" method-specific-idstring
We propose the following format for DIDs on XRPL:
"did:xrpl": network-id: xrpl-specific-idstring
The components specific to the XRP ledger network are the following:
-
method-name: The"xrpl"namestring specifies that this is a DID for XRP Ledger. A DID that uses this method MUST begin with the following prefix:did:xrpl. Per the DID specification, this string MUST be in lowercase. The remainder of the DID, after the prefix, is specified below. -
method-specific-idstringis formed bynetwork-idandxrpl-specific-idstringnetwork-id:network-idis a chain ID which is an identifier of XRP ledger networks. It specifies the underlying network instance where the DID related information is stored. The network is identified as 32-bit unsigned integer, formatted as a decimal value without leading zeroes (except for the value 0 which is represented as a single digit 0). The following values are defined at this time:
| Value | Description |
|---|---|
| 0 | The XRPL Mainnet |
| 1 | The XRPL Testnet |
| 2 | The XRPL Devnet |
xrpl-specific-idstring: Specifies the 256-bit hash generated as described in the next section.
XRPL DID MUST be unique within the XRPL network.
xrpl-specific-idstring is the ID of the AccountRoot object of an XRPL account, a.k.a., AccountRootID, which is the SHA-512Half of the following values, concatenated in order:
- The Account space key (0x0061)
- The Account ID of the account
Example:
A valid XRPL Testnet DID may be
did:xrpl:1:
XRPL DID is managed by the corresponding XRP ledger account owner. In this section we outline the following four CRUD operations for did:xrpl method using the existing methods supported by XRP ledger client libraries.
CreateResolveUpdateDelete
The XRPL DID creation is implicit and DOES NOT require any interaction with the ledger. In other words, an entity with an XRP ledger address need not invoke any method and will automatically own an XRPL DID that is formed by concatenating did:xrpl string, the network-id and the AccountRootID (fixed and well-known for a known account).
For instance, Bob, who has an XRPL address r9QxhA9RghPZBbUchA9HkrmLKaWvkLXU29 will automatically own & become the subject of following DID on XRPL:
did:xrpl:1:FB23699BE0D5D59766E999223B050EAA97EF907C9E365701D6D40163811D8241
In other words, one needs to create an account to XRP ledger to creste (implicit), own and control an XRP ledger DID.
The first step in using a DID for any application is to resolve the DID to the underlying DID Document, to further reveal the cryptographic material and service endpoints associated with that DID.
In this case XRP ledger DID, the read operation resolves to the URI. Following steps to retrieve the corresponding URI and hash:
-
Given a DID (known and fixed for each XRPL account), retrieve the
AccountRootIDof theAccountRootobject from thexrpl-specific-idstringof the DID. -
Given
AccountRootIDfrom the previous step, retrieve the contents of the correspondingAccountRootobject in its raw format using the the XRPL's ledger_entry method. Theindexfield is used to specify the unique object ID of theAccountRootobject to retrieve its contents.
Sample ledger_entry Method Request to retrieve the contents of AccountRoot object:
{
"method": “ledger_entry”,
"params": [
{
“index”: AccountRootID,
"ledger_index": "validated"
}
]
}
A sample response to the above query might look like this:
{
"result":
{
“index”: Identifier Object ID,
"ledger_hash": "256-bit hash",
"ledger_index": 58269896,
"node": {
"LedgerEntryType": "AccountRoot",
"DIDoc":
{
URI: "256-bit IPFS hash";
}
},
"validated": true
},
"status": "success",
"type": "response"
}
Upon receiving this response, an HTTP(S) or an IPFS address (CAS) can be retrieved from the DIDoc field.
These addresses can then be resolved to retrieve the corresponding DID Document. The DID URL dereferencing dereferences a DID URL into a resource with contents depending on the DID URL's components. The details of how this process is accomplished are outside the scope of this specification. Note that a DID resolver must return the referenced DID document as is.
Note: Applications implementing this method MAY extend it to enable DID document fetching from the retrieved URI.
Update:The owner of the XRP ledger DID may want to modify the storage location of a DID document OR, rotate the cryptographic material, or change the service end-points associated with a DID. This MAY require managing/updating the DID document URL and/or its corresponding hash. This can be done in the XRPL'sAccountRootobject by sending anAccountSettransaction.
The DID owner SHOULD also upload the (new) DID document to the corresponding (new) storage network location.
Example AccountSet JSON to update DID document reference
{
"Flags": ,
"TransactionType": "AccountSet",
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Fee": "12",
"DIDoc":
{
URI: "New 256-bit IPFS hash";
}
}
Delete:Similarly, XRP ledger DID owner MAY want to remove all references to theDIDoc. Most decentralized systems cannot guarantee actual deletion of a record. Indeed, distributed ledgers are often touted as "immutable".So, instead of deleting a DID, owner should be able to deactivate a DID such that downstream processes for dereferencing are no longer functional. XRP ledger'sAccountSetmethod described as follows achieves the same effect as deletion.
Example AccountSet JSON to delete DID document reference
{
"Flags": ,
"TransactionType": "IdentifierSet",
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Fee": "12",
"DIDoc": "Null",
}
There are several securities and privacy considerations that implementers would want to take into consideration when implementing this specification.
Sending transactions to the XRPL requires control over the private key used to anchor the DID, so any key recovery method which applies to XRPL keys can be applied here. This can involve seed phrases stored in an analogue manner among other methods.
No party can revoke the keys of DID control of another party under the XRPL system.
As mentioned in the Key Recovery section, the entity which controls the private key associated with the DID also effectively controls the DID Document which the DID resolves to. Thus great care should be taken to ensure that the private key is kept private. Methods for ensuring key privacy are outside the scope of this document.
The DID document anchored with the XRPL DID's DIDDoc field can contain any content, though it is recommended that it conforms to the W3C DID Document specification. As anchored DIDs on XRPL can be resolved by anyone, care should be taken to only update to resolve DID Documents which DO NOT expose any sensitive personal information, or information which you may not wish to be public. DID documents should be limited to verification methods and service endpoints, and should not store any personal information.
IPFS allows anyone to store content publicly on the nodes in a distributed network. A common misconception is that anyone can edit content, however the content-addressability of IPFS means that this new edited content will have a different address to the original. While any entity can copy a DID Document anchored with an XRPL account's DIDDoc, they cannot change the document that a DID resolves to via the XRPL ledger_entry resolution unless they control the private key which created the corresponding DIDDoc field on XRPL.
For more, see § 10. Privacy Considerations in did-core.
TBD$$
A DID is associated with a DID document. A DID document contains the necessary information to cryptographically verify the identity of the DID subject. W3C defines the core properties in a DID document, that describe relationships between the DID subject and the value of the property. For example, a DID document could contain cryptographic public keys such that the DID subject can use it to authenticate itself and proves its association with the DID. Usually, a DID document can be serialized to JSON representation or JSON-LD representation (see [DIDs v1.0]).
The DID document associated with the XRPL DID is not directly stored on the XRPL. Instead, XRPL DID method stores a reference on the ledger in the DIDoc field of AccountRoot object to the DID document stored in one or more parts on other decentralized storage networks such as IPFS or STORJ.
A sample XRPL DID Document MAY look like:
{
"@context" : "https://w3id.org/did/v1",
"id" : "did:xrpl:testnet:256-bit hash",
"publicKey" : [
{
"id" : "did:xrpl:testnet:256-bit hash#keys-1",
"type" : ["CryptographicKey", "EcdsaKoblitzPublicKey"],
"curve" : "secp256k1",
"expires" : 15674657,
"publicKeyHex": "04f42987b7faee8b95e2c3a3345224f00e00dfc67ba882…."
} ],
}
W3C defines the core properties in a DID document, that describe relationships between the DID subject and the value of the property.
A Universal Resolver is an identifier resolver that works with any decentralized identifier system, including Decentralized Identifiers (DIDs). Refer here. A driver for XRPL DID mehod resolution will be added to universal resolver configurations to make it publicly accessible.