Example Website

Abstract -------- The Veres One Ledger is a permissionless public ledger designed specifically for the creation and management of [decentralized identifiers](https://w3c-ccg.github.io/did-spec/) (DIDs). Veres One DIDs are [self-sovereign identifiers](https://www.coindesk.com/path-self-sovereign-identity/) that may be used by people, organizations, and digital devices to establish an identifier that is under their control. Veres One DIDs are useful in ecosystems where one needs to issue, store, and use [Verifiable Claims](https://w3c.github.io/vc-data-model/). This specification defines how a developer may create and update DIDs in the Veres One Ledger.

Status of This Document ----------------------- This specification was published by the [Credentials Community Group](https://www.w3.org/community/credentials/). It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the [W3C Community Contributor License Agreement (CLA)](https://www.w3.org/community/about/agreements/cla/) there is a limited opt-out and other conditions apply. Learn more about [W3C Community and Business Groups](https://www.w3.org/community/). Comments regarding this document are welcome. Please file issues directly on [GitHub](https://github.com/w3c-ccg/didm-veres-one/issues/), or send them to ([subscribe](mailto:public-credentials-request@w3.org?subject=subscribe), [archives](https://lists.w3.org/Archives/Public/public-credentials/)). Work on this specification has been funded in part by the United States Department of Homeland Security's Science and Technology Directorate under contract HSHQDC-17-C-00019. The content of this specification does not necessarily reflect the position or the policy of the U.S. Government and no official endorsement should be inferred. Work on this specification has also been supported by the Rebooting the Web of Trust group facilitated by Christopher Allen, Shannon Appelcline, Kiara Robles, Kaliya Young, Brian Weller, and Betty Dhamers. If you wish to make comments regarding this document, please send them to ([subscribe](mailto:public-credentials-request@w3.org?subject=subscribe), [archives](https://lists.w3.org/Archives/Public/public-credentials/)).

1. Introduction ------------------------------------------

Issue 1

TBD: This section will provide a gentle introduction to the purpose of the Veres One Ledger, expanding upon the abstract of the document.

2. Core Data Model ---------------------------------------------

Issue 2

TBD: This section will describe the use of the Web Ledger, JSON-LD, and the DID spec to build the Veres One Ledger.

3. Basic Concepts --------------------------------------------

### 3.1 Authentication Authentication is the process the ledger uses to determine if an entity is associated with a DID.

Example 1: Expressing authentication credentials

``` {.nohighlight} { "@context": "https://w3id.org/veres-one/v1", "id": "did:v1:215cb1dc-1f44-4695-a07f-97649cad9938", "authenticationCredential": [... array of acceptable authentication credentials ...] } ```

A detailed example of a valid set of authentication credentials follows:

Example 2: Detailed example of authentication credentials entry

``` {.nohighlight} { "@context": "https://w3id.org/veres-one/v1", "id": "did:v1:215cb1dc-1f44-4695-a07f-97649cad9938", "authenticationCredential": [{ "type": "RsaSignature2017", "publicKey": { "id": "did:v1:215cb1dc-1f44-4695-a07f-97649cad9938/keys/2", "type": "CryptographicKey", "owner": "did:v1:215cb1dc-1f44-4695-a07f-97649cad9938", "publicKeyPem": "-----BEGIN PUBLIC KEY...END PUBLIC KEY-----\r\n", } }] } ```

### 3.2 Authorization Authorization is the process the ledger uses to determine what an entity may to do the DID Document.

Example 3

``` {.nohighlight title=""} { "@context": "https://w3id.org/veres-one/v1", "id": "did:v1:215cb1dc-1f44-4695-a07f-97649cad9938", "authorizationCapability": [... array of capability descriptions ...] } ```

A detailed example of a valid set of authorization capability descriptions follows:

Example 4

``` {.nohighlight title=""} { "@context": "https://w3id.org/veres-one/v1", "id": "did:v1:215cb1dc-1f44-4695-a07f-97649cad9938", // proof of update authorization may be provided by digital wallet + friend OR // by mobile phone "authorizationCapability": [{ // this entity may update any field in this DID Document using any // authentication mechanism understood by the ledger "permission": "UpdateDidDocument", "entity": "did:v1:215cb1dc-1f44-4695-a07f-97649cad9938" }, { // this entity may update the authenticationCredential field in this // DID Document as long as they authenticate with RsaSignature2017 "entity": "did:v1:b5f8c320-f7ca-4869-85e6-a1bcbf825b2a", "permission": "UpdateDidDocument", "field": ["authenticationCredential"], "permittedProofType": [{ "proofType": "RsaSignature2017" }] }, { // anyone may update the authenticationCredential and writeAuthorization // fields as long as they provide a specific multi-signature proof "permission": "UpdateDidDocument", "field": ["authenticationCredential", "authorizationCapability"], "permittedProofType": [{ "proofType": "RsaSignature2017", "minimumSignatures": 3, "authenticationCredential": [{ "id": "did:v1:304ebc3e-7997-4bf4-a915-dd87e8455941/keys/123", "type": "RsaCryptographicKey", "owner": "did:v1:304ebc3e-7997-4bf4-a915-dd87e8455941", "publicKeyPem": "-----BEGIN PUBLIC KEY...END PUBLIC KEY-----\r\n" }, { "id": "did:v1:0f22346a-a360-4f3e-9b42-3366e348e941/keys/foo", "type": "RsaCryptographicKey", "owner": "did:v1:0f22346a-a360-4f3e-9b42-3366e348e941", "publicKeyPem": "-----BEGIN PUBLIC KEY...END PUBLIC KEY-----\r\n" }, { "id": "did:v1:a8d00377-e9f1-44df-a1b9-55072e13262a/keys/abc", "type": "RsaCryptographicKey", "owner": "did:v1:a8d00377-e9f1-44df-a1b9-55072e13262a", "publicKeyPem": "-----BEGIN PUBLIC KEY...END PUBLIC KEY-----\r\n" }] }] } ```

### 3.3 Service Descriptions Services may be listed by including them at the top-level of the DID Document.

Example 5: Simple example of a service description

``` {.nohighlight} { "@context": "https://w3id.org/veres-one/v1", "id": "did:v1:215cb1dc-1f44-4695-a07f-97649cad9938", "credentialRepositoryService": "https://wallet.veres.io/" } ```

A detailed example of the expression of a service description follows:

Example 6

``` {.nohighlight title=""} { "@context": "https://w3id.org/veres-one/v1", "id": "did:v1:215cb1dc-1f44-4695-a07f-97649cad9938", "credentialRepositoryService": [{ // the verifiable credential repository service "id": "did:v1:5d6c3b20-56a9-42e1-bfc8-ed7e685c9039", "type": "VerifiableCredentialRepository", "url": "https://wallet.veres.io/", "description": "Pat Doe's Digital Wallet" }] } ```

4. Operations ---------------------------------------- Every conforming Veres Ledger node *MUST* expose at least the following HTTP endpoints: Service Example URL Description ----------------------- ------------------ ---------------------------------- veresOneCreateService POST /dids Create a new DID. veresOneReadService GET /dids/{did} Gets an existing DID Document. veresOneUpdateService POST /dids/{did} Update an existing DID Document.

### 4.1 Discovering Service Endpoints {#x4.1-discovering-service-endpoints} A website may provide service endpoint discovery by embedding JSON-LD in their top-most HTML web page (e.g. at `https://example.com/`):

Example 7: Example of HTML-based service description

``` {.highlight .hljs .xml aria-busy="false" aria-live="polite"} Example Website ```

Service descriptions may also be requested via content negotiation. In the following example a JSON-compatible service description is provided (e.g. `curl -H "Accept: application/json" https://example.com/`):

Example 8: Example of a JSON-based service description

``` {.highlight .hljs .json aria-busy="false" aria-live="polite"} { "@context": "https://w3id.org/veres-one/v1", "id": "https://example.com/", "name": "Example Website", "veresOneCreateService": "https://example.com/veres-one/dids", "veresOneReadService": "https://example.com/veres-one/dids/", "veresOneUpdateService": "https://example.com/veres-one/dids/" } ```

### 4.2 Creating a DID A DID is created by performing an HTTP POST of a signed DID Document to the `veresOneCreateService`. The following HTTP status codes are defined for this service: HTTP Status Description ------------- -------------------------------------------------------------------------------------------------------------------------- 201 DID creation request was successful. The HTTP `Location` header will contain the URL for the newly created DID Document. 400 DID creation request failed. 409 A duplicate DID exists. An example exchange of DID creation request is shown below:

Example 9: DID creation request

``` {.highlight .hljs .http aria-busy="false" aria-live="polite"} POST /dids HTTP/1.1 Host: example.com Content-Type: application/ld+json Content-Length: 1062 Accept: application/ld+json, application/json, text/plain, */* Accept-Encoding: gzip, deflate { "@context": "https://w3id.org/webledger/v1", "type": "WebLedgerEvent", "operation": "Create", "input": [{ "@context": "https://w3id.org/veres-one/v1", "id": "did:v1:770f2d84-5e62-4caa-af95-111a3205bc84", "authorizationCapability": [{ "permission": "UpdateDidDocument", "entity": "did:v1:770f2d84-5e62-4caa-af95-111a3205bc84", "permittedProofType": [{ "proofType": "LinkedDataSignature2015" }, { "proofType": "EquihashProof2017", "equihashParameterAlgorithm": "VeresOne2017" }] }], "authenticationCredential": [{ "id": "did:v1:770f2d84-5e62-4caa-af95-111a3205bc84/keys/1", "type": "CryptographicKey", "owner": "did:v1:770f2d84-5e62-4caa-af95-111a3205bc84", "publicKeyPem": "-----BEGIN PUBLIC KEY-----\r\n MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAmbDqPu6IKHiiIQ4d0AQ6\r\n PBduDhUUVqyQirvxqsdcNdKgZ2L8whBml/nTyuB4cd+hHrsfMDiHiT5kX2pbZ7Yy\r\n 2ctWkGw8e0J94CbwVh2H15gBQBUCjLiGvVIHO2pni693qmre+3Ya2NJ8gGwPLJ7h\r\n TLca2b2dX0y16qu0MT0osUGGEoPsdg6ibD2pxnADS3GNPObHT12GrAuxjYFMHecF\r\n A4hLZ8U+MIcVmHZuokqqbcyJyjOV+kmhFNeTKFP5P5U8HA3Y42/rE1UJp/wyy7Lc\r\n ZAvq0t75ddXKyvYh5dkzxxeeELNKNWVxJ2yvgAr0SatLEPzxJoeYdCyU5N5E22Fj\r\n jQIDAQAB\r\n-----END PUBLIC KEY-----\r\n" }] }], "signature": [{ "type": "EquihashProof2017", "equihashParameterN": 64, "equihashParameterK": 3, "nonce": "AQAAAA==", "proofValue": "AAAaPwABxrIAAFOKAAGo4QAAVW0AAN7cAACXcgABjEI=" }, { "type": "LinkedDataSignature2015", "created": "2017-09-30T02:54:31Z", "creator": "did:v1:770f2d84-5e62-4caa-af95-111a3205bc84/keys/1", "signatureValue": "SNMbsPqLnB+hJFhXzS6hcpZnm9cGvSZZg7o26UYnyGYTvKder/S+Xk hNhXisS5385Ljlf5CXTQT5j6qYZtP8ut1Benaae8TMH17txP0CfzHbUMJFnHA1+Nru+e/Pw yPwuQ+VZYlXOB7g/tKVVZsxAYTKCAOJvJMIE+nlHjpB+RsKs9z4ZzVtddntqqAcvbZxV/o7 azBFDizeJu/gHVVMncCJ00SRoOzCOZUABRJV/k68bNSAfpELkrdWx8/xvMIF8r+LWhwdKCS iOw4DjSwIK40yD5rOvQn/GlC+unyB8zFe60jCToz/UOJNZBiIYwo+Pwwx28Wqd4Jkb3IeDr /L2Q==" }] } ```

If the creation of the DID was successful, an HTTP 201 status code is expected in return:

Example 10: Successful DID creation response

``` {.highlight .hljs .http aria-busy="false" aria-live="polite"} HTTP/1.1 201 Created Location: https://ledger.example.com/dids/did:v1:215cb1dc-1f44-4695-a07f-97649cad9938 Cache-Control: no-cache, no-store, must-revalidate Pragma: no-cache Expires: 0 Date: Fri, 14 Oct 2016 18:35:33 GMT Connection: keep-alive Transfer-Encoding: chunked ```

### 4.3 Updating a DID Document A DID is updated by performing an HTTP POST of a signed DID Document to the `veresOneUpdateService`. The following HTTP status codes are defined for this service: HTTP Status Description ------------- ------------------------------------ 200 DID update request was successful. 400 DID update request failed. An example exchange for a DID update request is shown below:

Example 11: DID Document update request

``` {.highlight .hljs .http aria-busy="false" aria-live="polite"} POST /dids/did:v1:215cb1dc-1f44-4695-a07f-97649cad9938 HTTP/1.1 Host: example.com Content-Type: application/ld+json Content-Length: 1062 Accept: application/ld+json, application/json, text/plain, */* Accept-Encoding: gzip, deflate { "@context": "https://w3id.org/webledger/v1", "type": "WebLedgerEvent", "operation": "Update", "input": [{ "@context": "https://w3id.org/veres-one/v1", "id": "did:v1:770f2d84-5e62-4caa-af95-111a3205bc84", "authorizationCapability": [{ "permission": "UpdateDidDocument", "entity": "did:v1:770f2d84-5e62-4caa-af95-111a3205bc84", "permittedProofType": [{ "proofType": "LinkedDataSignature2015" }, { "proofType": "EquihashProof2017", "equihashParameterAlgorithm": "VeresOne2017" }] }], "authenticationCredential": [{ "id": "did:v1:770f2d84-5e62-4caa-af95-111a3205bc84/keys/1", "type": "CryptographicKey", "owner": "did:v1:770f2d84-5e62-4caa-af95-111a3205bc84", "publicKeyPem": "-----BEGIN PUBLIC KEY-----\r\n MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAmbDqPu6IKHiiIQ4d0AQ6\r\n PBduDhUUVqyQirvxqsdcNdKgZ2L8whBml/nTyuB4cd+hHrsfMDiHiT5kX2pbZ7Yy\r\n 2ctWkGw8e0J94CbwVh2H15gBQBUCjLiGvVIHO2pni693qmre+3Ya2NJ8gGwPLJ7h\r\n TLca2b2dX0y16qu0MT0osUGGEoPsdg6ibD2pxnADS3GNPObHT12GrAuxjYFMHecF\r\n A4hLZ8U+MIcVmHZuokqqbcyJyjOV+kmhFNeTKFP5P5U8HA3Y42/rE1UJp/wyy7Lc\r\n ZAvq0t75ddXKyvYh5dkzxxeeELNKNWVxJ2yvgAr0SatLEPzxJoeYdCyU5N5E22Fj\r\n jQIDAQAB\r\n-----END PUBLIC KEY-----\r\n" }, { "id": "did:v1:770f2d84-5e62-4caa-af95-111a3205bc84/keys/2", "type": "CryptographicKey", "owner": "did:v1:770f2d84-5e62-4caa-af95-111a3205bc84", "publicKeyPem": "-----BEGIN PUBLIC KEY-----\r\n MIIBIj0BAQEFAKHiiIQ4d0AQ6ANBgkqhkiG9wAOCAQ8AMIIBCgKCAQEAmbDqPu6I\r\n xqsdcNdKgZ2L8whBml/nTyuBiHiPBduDhUUVqyQirvT5kX2pbZ7Yy4cd+hHrsfMD\r\n VhVIHO2pni693qmre+2ctWkGw8e0J94Cbw3Ya2NJ8gGwPLJ7hH15gBQBUCjLiGv\r\n 0osUNPObHT12GrAuxjYFMHecFGTLca2b2dX0y16qu0MTGEoPsdg6ibD2pxnADS3G\r\n kqqbcyJyjOV+kmh8HA3Y42/rE1UJpA4hLZ8U+MIcVmHZuo/wyy7LcFNeTKFP5P5U\r\n 5dkzxxezxJoeYdCyU5N5E2ZAvq0t75ddXKyvYh2FjeELNKNWVxJ2yvgAr0SatLEP\r\n AQABjQID\r\n-----END PUBLIC KEY-----\r\n" }] }], "signature": [{ "type": "EquihashProof2017", "equihashParameterN": 64, "equihashParameterK": 3, "nonce": "AQAAAA==", "proofValue": "AAAaPwABxrIAAFOKAAGo4QAAVW0AAN7cAACXcgABjEI=" }, { "type": "LinkedDataSignature2015", "created": "2017-09-30T02:54:31Z", "creator": "did:v1:770f2d84-5e62-4caa-af95-111a3205bc84/keys/2", "signatureValue": "Zg7o26UYnyGYTvKdSN6hcpZnm9cGvSZB+hJFhXzSer/S+XkMbsPqLn VMncCJ00SRoOzCOZUABRJV/azBFDizeJu/gHVk68bNSAfpELkrdWx8/xvMIF8r+LWhwdKCS XTQT5j6qYZtP8ut1BenahNhXisS5385Ljlf5Cae8TMH17txP0CfzHbUMJFnHA1+Nru+e/Pw K40yD5rOvQn/GlC+unyB8ziOw4DjSwIFe60jCToz/UOJNZBiIYwo+Pwwx28Wqd4Jkb3IeDr VVZsxAYTKCAOJvJMIE+nlHjpB+RyPwuQ+VZYlXOB7g/tKsKs9z4ZzVtddntqqAcvbZxV/o7 /45H==" }] } ```

If the update request for the DID was successful, an HTTP 200 status code is expected in return:

Example 12: Successful ledger creation response

``` {.highlight .hljs .http aria-busy="false" aria-live="polite"} HTTP/1.1 200 Success Cache-Control: no-cache, no-store, must-revalidate Pragma: no-cache Expires: 0 Date: Fri, 14 Oct 2016 18:35:33 GMT Connection: keep-alive Transfer-Encoding: chunked ```

### 4.4 Delegating Control

Issue 3

TBD: Explain that delegation of control is merely placing a digital wallet provider in the proofOfControl field.

### 4.5 Key Rotation and Transferring Control

Issue 4

TBD: Explain that transferring control and rotating keys is a matter of adding and removing the appropriate keys from proofofControl and proofOfUpdateAuthorization.

### 4.6 Recovering a DID

Issue 5

TBD: Explain that recoverying a DID is a matter of meeting the requirements under proofOfUpdateAuthorization.

5. Appendix A: Examples --------------------------------------------------

### 5.1 Typical DID Document The following is a complete example of a typical Veres One DID Document:

Example 13

``` {.nohighlight} { "@context": "https://w3id.org/veres-one/v1", "id": "did:v1:eaaf4df5-471d-404e-b143-652fe38cd2c7", "authorizationCapability": [{ "permission": "UpdateDidDocument", "entity": "did:v1:eaaf4df5-471d-404e-b143-652fe38cd2c7", "permittedProofType": [{ "proofType": "LinkedDataSignature2015" }, { "proofType": "EquihashProof2017", "equihashParameterAlgorithm": "VeresOne2017" }] }], "authenticationCredential": [{ "id": "did:v1:eaaf4df5-471d-404e-b143-652fe38cd2c7/keys/1", "type": "CryptographicKey", "owner": "did:v1:eaaf4df5-471d-404e-b143-652fe38cd2c7", "publicKeyPem": "-----BEGIN PUBLIC KEY-----\r\n MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvZXq8jX38lwndvzadCsT\r\n Xa2Zafdrg9I69gzfccH6XWY3Ddi/JoMuTSB1GwxKBfXpo9gjaPYsm6wCLv9Kku4x\r\n HL4LA1kmIalVTVDYgSO4sGK9k9oQNTY+hgUoTtdMxMShWrVy6+DIS/ZzIPyQBtbm\r\n 9D7RojrvESmjq/OuMs6sTlC0JjEE1ijuuHY+iY7gDYcR7RGFAsi4WGbCVy6c8VqL\r\n 29h8yGps2U+AxKr9f783VGMCk469ESHVwVyw6Jbxihn/h4TH3ZH8WTQW9rpS9GhO\r\n euSAA6iSH5UcmAzJZKSzaC+oghEJwMtOcgvr1F9iSn9tuHebgy9R6tHvEChhvdgz\r\n 2wIDAQAB\r\n -----END PUBLIC KEY-----\r\n", }] } ```

### 5.2 Legacy DID Document The Veres One ledger was launched in 2015, predated this specification, and as a result has a number of legacy objects that developers should be aware of. The typical format for these objects are shown below:

Example 14

``` {.nohighlight} { "@context": "https://w3id.org/identity/v1", "id": "did:8743453f-e45e-4ac6-b85f-4513ba4c1460", "idp": "did:d1d1d1d1-d1d1-d1d1-d1d1-d1d1d1d1d1d1", "accessControl": { "writePermission": [ { "id": "did:8743453f-e45e-4ac6-b85f-4513ba4c1460/keys/1", "type": "CryptographicKey" }, { "id": "did:d1d1d1d1-d1d1-d1d1-d1d1-d1d1d1d1d1d1", "type": "Identity" } ] }, "publicKey": [ { "id": "did:8743453f-e45e-4ac6-b85f-4513ba4c1460/keys/1", "type": "CryptographicKey", "owner": "did:8743453f-e45e-4ac6-b85f-4513ba4c1460", "publicKeyPem": "-----BEGIN PUBLIC KEY-----\r\nMIIBIjA...DAQAB\r\n-----END PUBLIC KEY-----\r\n", "@context": "https://w3id.org/identity/v1" } ], "signature": { "type": "LinkedDataSignature2015", "created": "2017-07-25T17:29:49Z", "creator": "did:8743453f-e45e-4ac6-b85f-4513ba4c1460/keys/1", "signatureValue": "LJoxpV...daOLHbA==" } } ```