Sovrin DID Method Specification

Sovrin is a public ledger designed specifically and only for privacy-preserving self-sovereign identity. The Sovrin Ledger is governed by the international non-profit Sovrin Foundation. As the only public ledger designed exclusively for self-sovereign identity, Sovrin is optimized for DIDs and DID Documents. DIDs are created, stored, and used with verifiable claims. This specification covers how these DIDs are managed. It also describes related features of Sovrin of particular interest to DID owners, guardians, and developers.

CRUD Operation Definitions

Create (Register)

The DID method specification must specify how a client creates a DID record—the combination of a DID and its associated document—on the target system, including all cryptographic operations necessary to establish proof of ownership. The Sovrin spec adds a new entry under publicKey called authorizations. This is used to indicate possible authorizations the public key is supposed to have. The keyword ALL means that the public key can make whatever change it wants to the DID doc. While creating a new DID doc, the field authorizations cannot be left empty. It has to either contain the keyword ALL or be omitted, in that case it is assumed that the key has all authorizations.

For example:

To create a DID, you must submit a "NYM" transaction that looks like this:

                {
                  'operation': {
                      'type': <Transaction type -- NYM >,
                      'dest': <new DID that is being registered>,
                      'role': <Role given to the new DID -- based on network config>,
                      'verkey': <Key material encoded>,
                  },
                  
                  'identifier': 'L5AD5g65TDQr1PPHHRoiGf' <Trust Anchor DID>,
                  'reqId': <A nonce for this transaction>,
                  'protocolVersion': 2,
                  'signature': <signature over this transaction from the Trust Anchor>
                }

The transaction must be signed by a Trust Anchor and must provide an un-registered DID and a document of data about that DID. Possible outcomes from the create operation include:

NACK: "Malformed transaction or missing required fields"
REJECT: "Authorization rules are invalid. DID already registered or non Trust Anchor authored the transaction or signature did not match”
SUCCESS: "Contains the sequence number of the transaction and the merkle proof"

DID Service Endpoint

By convention, Indy DID Controllers often create an Indy ATTRIB object (using the "ATTRIB" transaction) related to the NYM with a raw value of "endpoint", and a URL that represents the service endpoint for the DID. As noted in the "Read" section of this specification such an "endpoint" ATTRIB is read when resolving a DID and its data included in the resulting DID Document.

Read (Resolve)

A Sovrin DID record can be looked up directly by the DID using a standard Sovrin GET_NYM transaction that simply takes the DID and returns the DID record. The client trusts the DID record because it either receives the same DID record from sufficient number of validators or it receives a proof of the DID record from a single validator that the DID record is part of a merkle tree whose root has an aggregate signature from sufficient number of validators.

This is what the DID record query looks like

                {
                    "submitterId": <Optional; DID of the author of this query>,
                    "reqId": <Optional; a nonce for this query>,
                    "operation": {
                        "did": <DID to be queried>,
                        "type": "GET_NYM"
                    }
                }

Anyone can query a DID record by sending the above request. The response contains the data that can be used to create a DID document, as noted below.

DID Service Endpoint

When reading (resolving) a Sovrin DID, in addition to querying the DID record, a query MUST be performed for a related DID Service endpoint. This is done by executing the "GET_ATTRIB" transaction. The format of the GET_ATTRIB request looks like

          {
              "submitterId": <Optional; DID of the author of this query>,
              "reqId": <Optional; a nonce for this query>,
              "identifier": <Required; The DID being read/resolved>,
              "operation": {
                "raw": "{\"endpoint\":{\"endpoint\":\"https://example.com\"}}" <Required; the value must be endpoint>
              }
          }

The result may be a "Not Found" error, indicating the NYM does not have an optional corresponding ATTRIB endpoint record. If the call is successful, the relevant part of the response of such a GET_ATTRIB request is:

          {
            ...
            'data': '{"endpoint":{"endpoint":"https://example.com/endpoint"}}',
            'dest': 'AH4RRiPR78DUrCWatnCW2w' < The DID being read/resolved>, 
            'raw': 'endpoint',
            ...
          }

The value of the inner endpoint item (https://example.com/endpoint in the example above) is the service endpoint for the DID.

Historically on the Sovrin MainNet (through June 2021), the format of the endpoint ATTRIB has been simply a single name ("endpoint") value (a URL) pair, as shown above. An extended version of the endpoint ATTRIB MAY be written to an Indy ledger by a DID Controller to provide additional control over the generation of the DID Document. The format is as follows:

        {
          "endpoint": "https://example.com",
          "types": [ "endpoint", "did-communication", "DIDComm" ],
          "routingKeys": [ "did:key12345", "did:key12345" ]
        }

This corresponds to the raw value in the "ATTRIB" transaction as:

        "raw": "{\"endpoint\":{\"endpoint\":\"https://example.com\",\"types\":[\"endpoint\",\"did-communication\",\"DIDComm\" ],\"routingKeys\":[\"did:key12345\",\"did:key12345\"]}}"

A did:sov resolver MUST process the endpoint ATTRIB (extended or not) as follows:

If the types field is present it's entries MUST be endpoint, did-communication and/or DIDComm, generating entries in the DID Document service block.

The three service block formats corresponding to the three types is defined in the next section of this document.

If the endpoint is defined and the types item is NOT present, empty or contains any other values, default the types to "types": [ "endpoint", "did-communication" ].

Any did:sov DID wanting to include a DIDComm V2 (DIDComm) service entry MUST use the extended version of the "endpoint" ATTRIB with the types item included.

If the routingKeys item is present, use its value as the array for routingKeys in the did-communication and DIDComm type service blocks.
If the routingKeys entry is not present, default to the it being an empty array (e.g. "routingKeys": [ ])

Resolver DID Document Format

The DID Document is generated by a resolver (not by the Indy/Sovrin ledger) by taking the GET_NYM and optional GET_ATTRIB/endpoint data and rendering a DID Document as follows. See the notes following the rendering.

          {
            "@context": [
              "https://www.w3.org/ns/did/v1",
              "https://w3id.org/security/suites/ed25519-2018/v1",
              "https://w3id.org/security/suites/x25519-2019/v1"
            ],
            "id": "did:sov:HR6vs6GEZ8rHaVgjg2WodM",
            "verificationMethod": [
              {
                "type": "Ed25519VerificationKey2018",
                "id": "did:sov:HR6vs6GEZ8rHaVgjg2WodM#key-1",
                "publicKeyBase58": "9wvq2i4xUa5umXoThe83CDgx1e5bsjZKJL4DEWvTP9qe"
              },
              {
                "type": "X25519KeyAgreementKey2019",
                "id": "did:sov:HR6vs6GEZ8rHaVgjg2WodM#key-agreement-1",
                "publicKeyBase58": "3mHtKcQFEzqeUcnce5BAuzAgLEbqKaV542pUf9xQ5Pf8"
              }
            ],
            "authentication": [
              "did:sov:HR6vs6GEZ8rHaVgjg2WodM#key-1"
            ],
            "assertionMethod": [
              "did:sov:HR6vs6GEZ8rHaVgjg2WodM#key-1"
            ],
            "keyAgreement": [
              "did:sov:HR6vs6GEZ8rHaVgjg2WodM#key-agreement-1"
            ],
            "service": [
              {
                "type": "endpoint",
                "serviceEndpoint": "https://example.com/endpoint"
              },
              {
                "id": "did:sov:HR6vs6GEZ8rHaVgjg2WodM#did-communication",
                "type": "did-communication",
                "priority": 0,
                "recipientKeys": [
                  "did:sov:HR6vs6GEZ8rHaVgjg2WodM#key-agreement-1"
                ],
                "routingKeys": [],
                "accept": [
                  "didcomm/aip2;env=rfc19"
                ],
                "serviceEndpoint": "https://example.com/endpoint"
              }
            ]
          }

If an endpoint ATTRIB does not exist for the NYM, the service block is an empty array (e.g. "service": []

If the endpoint has a types item and that types item contains an entry "DIDComm", then the following extra service block is included:

          {
            "id": "did:sov:HR6vs6GEZ8rHaVgjg2WodM#didcomm-1",
            "type": "DIDComm",
            "serviceEndpoint": "https://example.com/endpoint",
            "accept": [
              "didcomm/v2"
            ],
            "routingKeys": []
          }

In addition the service block, the following entry needs to be added to the @context array:

          "https://didcomm.org/messaging/contexts/v2"

DID Document Notes

The following are notes about the example DID Document above:

The DID Document text is boilerplate except for the "did:sov..." identifier, the public keys ("publicKeyBase58" values) and the references to the service endpoint ("serviceEndpoint").
The X25519 key MUST be derived from the ED25519 key by the resolver. The Indy "GET_NYM" call returns only the ED25519 key.

Note that although the "keyAgreement" key is included in the DID Document, because of historical conventions it is the ED25519 key referenced in the recipientKeys item in the did-communication service block. The pending "did:indy" DID Method will correct such conventions and provide Indy DID Controller clients with full control over the contents of their DID Documents.

If there is no result from the GET_ATTRIB transaction, the "service" item is NOT included in the document.
The entries in the service block are included based on the value or absence of the types item in the "endpoint" ATTRIB. The three entry formats cover the three "eras" of DIDComm, AIP 1.0 (type "endpoint"), AIP 2.0 (type "did-communication") and DIDComm V2 (type "DIDComm").
A DID controlled MAY use the extended form of the "endpoint" ATTRIB (see previous section of this document) to include routingKeys in the did-communication and DIDComm service block entries.

Update (Replace)

To replace the DID document, the owner or guardian (guardianship ends once ownership begins) of the DID should send the following transaction using a key referenced in the authentication property.

                  {
                    "submitterId": <DID of the author of this query>,
                    "signature": [<signature over this transaction from the author>,]
                    "reqId": <a nonce for this query>,
                    "operation": {
                        "type": "NYM",
                        "did": <DID whose record needs to be updated>,
                        "document": {
                            "publicKey": [{
                                "id": <a valid unique identifier>
                                "type": <ED25519>
                                "publicKeyBase58": <Key material encoded in format>,
                                "authorizations": ["all"]
                            },{
                                "id": <a valid unique identifier>
                                "type": <ED25519>
                                "publicKeyBase58": <Key material encoded in format>
                            },{
                                "id": <a valid unique identifier>
                                "type": <ED25519>
                                "publicKeyBase58": <Key material encoded in format>
                            }],
                            "authentication": [{
                                "type": "ED25519SigningAuthenticationThreshold",
                                "threshold": <an integer>,
                                "publicKey": [<key references>]
                            }],
                            "service": [{
                              "type": <agentService, emailService, apiService, dnsService, authenticationService, etc>,
                              "serviceEndpoint": <A URI for the endpoint>
                            }]
                        }
                      }
                  }

This example shows how to update the DID document to require multiple signatures for authentication:

                {
                    "submitterId": "did:sov:qazWSX3erfcY459iLMh7",
                    "signature": ["1qaz2wsx3eeciguytGGVDR990ik=="]
                    "reqId": "897432983746n43g"
                    "operation": {
                        "type": "NYM",
                        "did": "did:sov:c432cDSGUASJN987jnJKb",
                        "document": {
                            "publicKey": [{
                                "id": "#key1",
                                "type": "ED25519VerificationKey",
                                "publicKeyBase58": ...
                            },{
                                "id": "#key2",
                                "type": "ED25519VerificationKey",
                                "publicKeyBase58": ...
                            },{
                                "id": "#key3",
                                "type": "ED25519VerificationKey",
                                "publicKeyBase58": ...
                            }],
                            "authentication": [{
                                "type": "ED25519SigningAuthenticationThreshold",
                                "threshold": 2,
                                "publicKey": ["#key1","#key2","#key3"]
                            }],
                            "service": [{
                              "type": "agentService",
                              "serviceEndpoint": "https://www.sovrin.org/agents"
                            }]
                        }
                      }
                  }

Delete (Revoke)

Deleting or revoking a verification key is not to be confused with temporary suspension or rotation. Deletion sets an identity's verification key to null; this permanently terminates the identity's ability to operate on the network because there is no key that the identity can use to authenticate itself--even to submit a new key rotation request. It is irreversible.

Revocation may be appropriate when a person dies or a business is legally dissolved. It does not remove any record or history of the identity--it simply prevents any new history from accruing. This guarantees that no malicious actor can recover and reactivate an identity that's dead.

The scope of deletion in Sovrin is one DID only. This does not prevent an entity from creating new DIDs; it simply prevents an entity from reusing the old DID that has been terminated.

To revoke the document of the DID, the owner of the DID should send the following transaction.

                {
                    "submitterId": <DID of the owner>,
                    "signature": <signature over this transaction from the DID in identifier>,
                    "reqId": <a nonce for this transaction>,
                    "operation": {
                        "type": "NYM",
                        "did": <DID whose key is being revoked>,
                        "document": null
                    }
                }

About