├── .github ├── dependabot.yml └── workflows │ └── render-specs.yml ├── .gitignore ├── LICENSE.md ├── README.md ├── agenda-2024.md ├── agenda.md ├── didtdw_light.jpg ├── didwebvh-icon.png ├── didwebvh.jpg ├── favicon.ico ├── index.html ├── package.json ├── schemas └── v1.0 │ └── log_entry.json ├── spec-anoncreds-method ├── abstract.md ├── definitions.md ├── header.md ├── references.md ├── specification.md └── version.md ├── spec-v0.3 ├── abstract.md ├── definitions.md ├── example.md ├── header.md ├── implementors_guide.md ├── overview.md ├── references.md ├── security_and_privacy.md ├── specification.md └── version.md ├── spec-v0.4 ├── abstract.md ├── definitions.md ├── header.md ├── overview.md ├── references.md ├── security_and_privacy.md ├── specification.md └── version.md ├── spec-v0.5 ├── abstract.md ├── definitions.md ├── header.md ├── overview.md ├── references.md ├── security_and_privacy.md ├── specification.md └── version.md ├── spec-v1.0 ├── abstract.md ├── definitions.md ├── header.md ├── overview.md ├── references.md ├── security_and_privacy.md ├── specification.md └── version.md ├── spec ├── abstract.md ├── definitions.md ├── header.md ├── overview.md ├── references.md ├── security_and_privacy.md ├── specification.md └── version.md ├── specs.json ├── tdw.jpg └── watcherOpenAPI └── watcher-v1.0.0.yml /.github/dependabot.yml: -------------------------------------------------------------------------------- 1 | # For details on how this file works refer to: 2 | # - https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file 3 | version: 2 4 | updates: 5 | # Maintain dependencies for GitHub Actions 6 | # - Check for updates once a week 7 | # - Group all updates into a single PR 8 | - package-ecosystem: "github-actions" 9 | directory: "/" 10 | schedule: 11 | interval: "weekly" 12 | groups: 13 | all-actions: 14 | patterns: [ "*" ] 15 | 16 | # Maintain dependencies for TypeScript and JavaScript 17 | - package-ecosystem: "npm" 18 | directory: "/" 19 | schedule: 20 | interval: "weekly" 21 | day: "monday" 22 | time: "04:00" 23 | timezone: "Canada/Pacific" 24 | ignore: 25 | - dependency-name: "*" 26 | update-types: ["version-update:semver-major", "version-update:semver-patch"] 27 | 28 | -------------------------------------------------------------------------------- /.github/workflows/render-specs.yml: -------------------------------------------------------------------------------- 1 | 2 | name: spec-up-render 3 | 4 | on: 5 | push: 6 | branches: 7 | - main 8 | 9 | jobs: 10 | build-and-deploy-spec: 11 | runs-on: ubuntu-latest 12 | permissions: 13 | contents: write 14 | steps: 15 | - name: Checkout 🛎️ 16 | uses: actions/checkout@v4 # If you're using actions/checkout@v4 you must set persist-credentials to false in most cases for the deployment to work correctly. 17 | with: 18 | persist-credentials: false 19 | 20 | - name: Install and Build 🔧 # This example project is built using npm and outputs the result to the 'build' folder. Replace with the commands required to build your project, or remove this step entirely if your site is pre-built. 21 | run: | 22 | npm install 23 | node -e "require('spec-up')({ nowatch: true })" 24 | rm -rf .gitignore 25 | rm -rf node_modules 26 | 27 | - name: Deploy 28 | uses: peaceiris/actions-gh-pages@v4.0.0 29 | with: 30 | github_token: ${{ secrets.GITHUB_TOKEN }} 31 | publish_dir: ./ 32 | allow_empty_commit: true 33 | force_orphan: true 34 | 35 | 36 | 37 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | package-lock.json 2 | index.html 3 | !/index.html 4 | fonts 5 | 6 | # Logs 7 | logs 8 | *.log 9 | npm-debug.log* 10 | yarn-debug.log* 11 | yarn-error.log* 12 | lerna-debug.log* 13 | .vscode/* 14 | 15 | # Diagnostic reports (https://nodejs.org/api/report.html) 16 | report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json 17 | 18 | # Runtime data 19 | pids 20 | *.pid 21 | *.seed 22 | *.pid.lock 23 | 24 | # Directory for instrumented libs generated by jscoverage/JSCover 25 | lib-cov 26 | 27 | # Coverage directory used by tools like istanbul 28 | coverage 29 | *.lcov 30 | 31 | # nyc test coverage 32 | .nyc_output 33 | 34 | # Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files) 35 | .grunt 36 | 37 | # Bower dependency directory (https://bower.io/) 38 | bower_components 39 | 40 | # node-waf configuration 41 | .lock-wscript 42 | 43 | # Compiled binary addons (https://nodejs.org/api/addons.html) 44 | build/Release 45 | 46 | # Dependency directories 47 | node_modules/ 48 | jspm_packages/ 49 | 50 | # TypeScript v1 declaration files 51 | typings/ 52 | 53 | # TypeScript cache 54 | *.tsbuildinfo 55 | 56 | # Optional npm cache directory 57 | .npm 58 | 59 | # Optional eslint cache 60 | .eslintcache 61 | 62 | # Microbundle cache 63 | .rpt2_cache/ 64 | .rts2_cache_cjs/ 65 | .rts2_cache_es/ 66 | .rts2_cache_umd/ 67 | 68 | # Optional REPL history 69 | .node_repl_history 70 | 71 | # Output of 'npm pack' 72 | *.tgz 73 | 74 | # Yarn Integrity file 75 | .yarn-integrity 76 | 77 | # dotenv environment variables file 78 | .env 79 | .env.test 80 | 81 | # parcel-bundler cache (https://parceljs.org/) 82 | .cache 83 | 84 | # Next.js build output 85 | .next 86 | 87 | # Nuxt.js build / generate output 88 | .nuxt 89 | dist 90 | 91 | # Gatsby files 92 | .cache/ 93 | # Comment in the public line in if your project uses Gatsby and *not* Next.js 94 | # https://nextjs.org/blog/next-9-1#public-directory-support 95 | # public 96 | 97 | # vuepress build output 98 | .vuepress/dist 99 | 100 | # Serverless directories 101 | .serverless/ 102 | 103 | # FuseBox cache 104 | .fusebox/ 105 | 106 | # DynamoDB Local files 107 | .dynamodb/ 108 | 109 | # TernJS port file 110 | .tern-port 111 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | # Specification License 2 | 3 | Specifications in this repository are subject to the W3C Patent Policy (2004), available at http://www.w3.org/Consortium/Patent-Policy-20040205. 4 | 5 | # Source Code License 6 | 7 | If source code is included in this repository, or for sample or reference code included in the specification itself, that code is subject to the Apache 2.0 license, available at http://www.apache.org/licenses/LICENSE-2.0.html, unless otherwise designated. In the case of any conflict or confusion within this specification repository between the W3C Patent Policy (2004) or other designated license, the terms of the W3C Patent Policy (2004) shall apply. 8 | 9 | These terms are inherited from the Decentralized Identity Foundation Project Charter, available at https://github.com/decentralized-identity/org/blob/master/Org%20documents/Membership%20agreements/DIF%20Project%20Charter%20_4.0.2.pdf 10 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # The `did:webvh` DID Method -- `did:web` + Verifiable History 2 | 3 | The spec repository for the `did:webvh` DID Method. `did:webvh` is `did:web` 4 | extended to include the Verifiable History of the DID. 5 | 6 | Read the spec: [https://identity.foundation/didwebvh](https://identity.foundation/didwebvh/next) 7 | 8 | Proof of concept implementations available: 9 | 10 | - Typescript: [https://github.com/decentralized-identity/trustdidweb-ts](https://github.com/decentralized-identity/trustdidweb-ts) 11 | - Python: [https://github.com/decentralized-identity/trustdidweb-py](https://github.com/decentralized-identity/trustdidweb-py) 12 | - Go: [https://github.com/nuts-foundation/trustdidweb-go](https://github.com/nuts-foundation/trustdidweb-go) 13 | - Python Web Server: [https://github.com/decentralized-identity/trustdidweb-server-py](https://github.com/decentralized-identity/trustdidweb-server-py) 14 | 15 | ## Current Status of the Specification 16 | 17 | The current stable version of the specification can be found at 18 | [https://identity.foundation/didwebvh](https://identity.foundation/didwebvh). 19 | See any guidance there about the status of the specification -- past versions, 20 | upcoming changes, etc. 21 | 22 | ## Abstract 23 | 24 | The `did:webvh` DID Method is an enhancement to the well-known `did:web` DID 25 | method, providing a complementary web-based DID method that addresses 26 | limitations of `did:web`, most notability, the verifiable history for which it 27 | is name. `did:webvh` features include the following. 28 | 29 | - Ongoing publishing of all DID Document (DIDDoc) versions for a DID instead of, 30 | or alongside a `did:web` DID/DIDDoc. 31 | - Uses the same DID-to-HTTPS transformation as `did:web`. 32 | - Provides resolvers the full history of the DID using a verifiable chain of 33 | updates to the DIDDoc from genesis to deactivation. 34 | - A self-certifying identifier (SCID) for the DID that is globally 35 | unique and derived from the initial DIDDoc that enables DID portability, such 36 | as moving the DIDs web location (and so the DID string itself) while retaining 37 | the DID's history. 38 | - DIDDoc updates include a proof signed by the DID Controller(s) *authorized* to 39 | update the DID. 40 | - An optional mechanism for publishing "pre-rotation" keys to prevent loss of 41 | control of the DID in cases where an active private key is compromised. 42 | - An optional mechanism for having collaborating "witnesses" 43 | that approve updates to the DID by the DID Controller before publication. 44 | - DID URL path handling that defaults (but can be overridden) to automatically 45 | resolving `/path/to/file` by using a comparable DID-to-HTTPS translation 46 | as for the DIDDoc. 47 | - A DID URL path `/whois` that defaults to automatically returning (if 48 | published by the DID controller) a Verifiable Presentation containing 49 | Verifiable Credentials with the DID as the `credentialSubject`, 50 | signed by the DID. 51 | 52 | Combined, the additional features enable greater trust, security and 53 | verifiability without compromising the simplicity of `did:web`. The incorporation 54 | of the DID Core compatible "/whois" path, drawing inspiration from the 55 | traditional WHOIS protocol, offers an easy to use, decentralized, trust 56 | registry. `did:webvh` aims to establish a more trusted and secure web 57 | environment by providing robust verification processes and enabling transparency 58 | and authenticity in the management of decentralized digital identities. 59 | 60 | ## Contributing to the Specification 61 | 62 | Pull requests (PRs) to this repository may be accepted. Each commit of a PR must 63 | have a DCO (Developer Certificate of Origin - 64 | [https://github.com/apps/dco](https://github.com/apps/dco)) sign-off. This can 65 | be done from the command line by adding the `-s` (lower case) option on the `git 66 | commit` command (e.g., `git commit -s -m "Comment about the commit"`). 67 | 68 | Rendering and reviewing the spec locally for testing requires `npm` and `node` 69 | installed. Follow these steps: 70 | 71 | - Fork and locally clone the repository. 72 | - Install `node` and `npm`. 73 | - Run `npm install` from the root of your local repository. 74 | - Edit the spec documents (in the `/spec` folder). 75 | - Run `npm run render`' 76 | - Use `npm run edit` to interactively edit, render and review the spec. 77 | - Load the root `index.html` file in a browser to be redirected to the current default version of the specification. 78 | 79 | The specification is currently in [Spec-Up] format. See the 80 | [Spec-Up Documentation] for a list of Spec-Up features and functionality. 81 | 82 | [Spec-Up]: https://github.com/decentralized-identity/spec-up 83 | [Spec-Up Documentation]: https://identity.foundation/spec-up/ 84 | 85 | ## Publishing Previous Spec Versions 86 | 87 | [Spec-Up] allows for multiple versions of the spec to be rendered and accessed 88 | on the same site. We use that feature for the `did:webvh` DID Method spec to snapshot 89 | previous versions of the spec for reference. 90 | 91 | To create a snapshot of a version: 92 | 93 | - Make a new folder in the root of the repository for the new version, called `spec-v`. For example `spec-v0.3`. 94 | - Copy the current `spec` folder markdown files from the point of that version into the new folder. If you are doing this process as you are starting a new version, you can just copy the files from the `spec` folder of the main branch. Otherwise, you have to find the last commit of the version and get the files from that point in the GitHub history. 95 | - Update the `specs.json` file to include a new specification: 96 | - Copy the primary spec entry text. 97 | - Paste that text into a new spec entry in the `"specs"` array. 98 | - Update the `"spec_directory"` property to be the name of the new folder you created. 99 | - Update the `"output_path"` property to be `./v`. For example `"./v0.3"`. 100 | - Append to the `"title"` property the version ` - Version `, For example ` - Version 0.3`. 101 | - Add a link to the versioned specification in the `Previous Drafts` bullet list, in the `header.md` file in the main spec, so that readers can click on it from the main specification. 102 | - Update the `header.md` file of the new version spec folder (e.g in `spec-v0.3`) to: 103 | - Change the status to `HISTORICAL -- **THIS IS NOT THE CURRENT VERSION OF THE SPECIFICATION**` 104 | - As appropriate, add guidance for readers **WITHOUT** altering the version of the specification itself. 105 | - Remove the `Past Drafts` section and put a relative link back to the current spec -- such as: 106 | 107 | ```text 108 | **Latest Version:** 109 | 110 | - Specification: [https://identity.foundation/didwebvh/](../) 111 | - Repository: [https://github.com/decentralized-identity/didwebvh](https://github.com/decentralized-identity/didwebvh) 112 | 113 | ``` 114 | 115 | ## Setting the Default Landing Page Version 116 | 117 | In the lifecycle of the specification, there will be times when the latest 118 | version is stable, with clarifications being added, and other times when new 119 | versions are being defined with breaking changes. At all times we want to 120 | control which version is the default spec. that comes up when a user goes to the 121 | base spec URL 122 | [https://identity.foundation/didwebvh/](:https://identity.foundation/didwebvh/). 123 | We control that via the `index.html` file in the root folder. That is just a 124 | redirect to one of the versions of the spec. 125 | 126 | To change the default landing page spec. version, change the root folder 127 | `index.html` line: 128 | 129 | ```html 130 | window.location.replace("v1.0"); 131 | ``` 132 | 133 | Notably -- set the `v1.0` to the appropriate version, which might be `next`, if 134 | the we want the landing page to be the `Editor's Draft` for a period of time. 135 | 136 | Here's how we manage things in different situations: 137 | 138 | - The specification website landing page is always the current stable version of 139 | the specification, and past versions plus the next version ("Editor's Draft") 140 | are linked in that folder's `header.md` file. 141 | - The `spec` folder is the `./next` folder and is called the `Editor's Draft`. 142 | Immediately after a stable version is announced, it is a copy of the newly 143 | stable version, but will evolve from there. Clarifications may be applied to the latest 144 | `spec-vx.x` folder, and if so, those changes **MUST** also be applied to the Editor's 145 | Draft. 146 | -------------------------------------------------------------------------------- /didtdw_light.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/decentralized-identity/didwebvh/805782c9aeaf43d29a7366ca96e311c5b2f39d84/didtdw_light.jpg -------------------------------------------------------------------------------- /didwebvh-icon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/decentralized-identity/didwebvh/805782c9aeaf43d29a7366ca96e311c5b2f39d84/didwebvh-icon.png -------------------------------------------------------------------------------- /didwebvh.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/decentralized-identity/didwebvh/805782c9aeaf43d29a7366ca96e311c5b2f39d84/didwebvh.jpg -------------------------------------------------------------------------------- /favicon.ico: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/decentralized-identity/didwebvh/805782c9aeaf43d29a7366ca96e311c5b2f39d84/favicon.ico -------------------------------------------------------------------------------- /index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Redirecting 5 | 8 | 9 | 10 | 11 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "didwebvh", 3 | "version": "1.0.0", 4 | "description": "did:webvh -- did:web + Verifiable History", 5 | "main": "index.js", 6 | "scripts": { 7 | "edit": "node -e \"require('spec-up')()\"", 8 | "render": "node -e \"require('spec-up')({ nowatch: true })\"", 9 | "dev": "node -e \"require('spec-up')({ dev: true })\"" 10 | }, 11 | "keywords": [ 12 | "decentralized identifier", 13 | "DID", 14 | "spec", 15 | "didwebvh", 16 | "tdw" 17 | ], 18 | "author": "Stephen Curran", 19 | "license": "Apache 2.0", 20 | "bugs": { 21 | "url": "https://github.com/decentralized-identity/didwebvh/issues" 22 | }, 23 | "homepage": "https://identity.foundation/didwebvh/", 24 | "dependencies": { 25 | "spec-up": "github:brianorwhatever/spec-up#master" 26 | } 27 | } 28 | -------------------------------------------------------------------------------- /schemas/v1.0/log_entry.json: -------------------------------------------------------------------------------- 1 | { 2 | "$schema": "https://json-schema.org/draft/2020-12/schema", 3 | "title": "DID WebVH 1.0 Log Entry", 4 | "description": "A log entry from a log file for webvh 1.0.", 5 | "type": "object", 6 | "properties": { 7 | "versionId": { 8 | "type": "string" 9 | }, 10 | "versionTime": { 11 | "type": "date-time" 12 | }, 13 | "parameters": { 14 | "$ref": "#/schemas/didParameters" 15 | }, 16 | "state": { 17 | "$ref": "#/schemas/didDocument" 18 | }, 19 | "proof": { 20 | "oneOf": [ 21 | { 22 | "$ref": "#/schemas/dataIntegrityProof" 23 | }, 24 | { 25 | "type": "array", 26 | "items": { 27 | "$ref": "#/schemas/dataIntegrityProof", 28 | "minItems": 1 29 | } 30 | } 31 | ] 32 | } 33 | }, 34 | "required": [ 35 | "versionId", 36 | "versionTime", 37 | "parameters", 38 | "state" 39 | ], 40 | "schemas": { 41 | "didParameters": { 42 | "type": "object", 43 | "properties": { 44 | "method": { 45 | "const": "did:webvh:1.0" 46 | }, 47 | "scid": { 48 | "type": "string" 49 | }, 50 | "portable": { 51 | "type": "boolean" 52 | }, 53 | "updateKeys": { 54 | "type": "array", 55 | "items": { 56 | "type": "string" 57 | }, 58 | "minItems": 1, 59 | "uniqueItems": true 60 | }, 61 | "nextKeyHashes": { 62 | "type": "array", 63 | "items": { 64 | "type": "string" 65 | }, 66 | "minItems": 1, 67 | "uniqueItems": true 68 | }, 69 | "watchers": { 70 | "type": "array", 71 | "items": { 72 | "type": "string" 73 | }, 74 | "minItems": 1, 75 | "uniqueItems": true 76 | }, 77 | "witness": { 78 | "type": "object", 79 | "properties": { 80 | "threshold": { 81 | "type": "integer", 82 | "minimum": 1 83 | }, 84 | "witnesses": { 85 | "type": "array", 86 | "items": { 87 | "type": "object", 88 | "properties": { 89 | "id": { 90 | "type": "string" 91 | } 92 | } 93 | }, 94 | "minItems": 1, 95 | "uniqueItems": true 96 | } 97 | } 98 | }, 99 | "deactivated": { 100 | "type": "boolean" 101 | }, 102 | "ttl": { 103 | "type": "integer" 104 | } 105 | } 106 | }, 107 | "verificationMethod": { 108 | "type": "object", 109 | "properties": { 110 | "type": { 111 | "type": "string" 112 | }, 113 | "id": { 114 | "type": "string" 115 | } 116 | }, 117 | "required": [ 118 | "type", 119 | "id" 120 | ] 121 | }, 122 | "didDocument": { 123 | "type": "object", 124 | "properties": { 125 | "@context": { 126 | "oneOf": [ 127 | { 128 | "type": "string" 129 | }, 130 | { 131 | "type": "array", 132 | "items": { 133 | "type": "string" 134 | }, 135 | "minItems": 1, 136 | "uniqueItems": true 137 | } 138 | ] 139 | }, 140 | "id": { 141 | "type": "string" 142 | }, 143 | "verificationMethod": { 144 | "type": "array", 145 | "items": { 146 | "$ref": "#/schemas/verificationMethod" 147 | } 148 | }, 149 | "assertionMethod": { 150 | "type": "array", 151 | "items": { 152 | "oneOf": [ 153 | { 154 | "$ref": "#/schemas/verificationMethod" 155 | }, 156 | { 157 | "type": "string" 158 | } 159 | ] 160 | } 161 | }, 162 | "authentication": { 163 | "type": "array", 164 | "items": { 165 | "oneOf": [ 166 | { 167 | "$ref": "#/schemas/verificationMethod" 168 | }, 169 | { 170 | "type": "string" 171 | } 172 | ] 173 | } 174 | }, 175 | "capabilityInvocation": { 176 | "type": "array", 177 | "items": { 178 | "oneOf": [ 179 | { 180 | "$ref": "#/schemas/verificationMethod" 181 | }, 182 | { 183 | "type": "string" 184 | } 185 | ] 186 | } 187 | }, 188 | "capabilityDelegation": { 189 | "type": "array", 190 | "items": { 191 | "oneOf": [ 192 | { 193 | "$ref": "#/schemas/verificationMethod" 194 | }, 195 | { 196 | "type": "string" 197 | } 198 | ] 199 | } 200 | }, 201 | "keyAgreement": { 202 | "type": "array", 203 | "items": { 204 | "oneOf": [ 205 | { 206 | "$ref": "#/schemas/verificationMethod" 207 | }, 208 | { 209 | "type": "string" 210 | } 211 | ] 212 | } 213 | }, 214 | "service": { 215 | "type": "array", 216 | "items": { 217 | "type": "object", 218 | "properties": { 219 | "type": { 220 | "type": "string" 221 | }, 222 | "id": { 223 | "type": "string" 224 | }, 225 | "serviceEndpoint": { 226 | "type": "string" 227 | } 228 | }, 229 | "required": [ 230 | "type", 231 | "id", 232 | "serviceEndpoint" 233 | ] 234 | } 235 | } 236 | }, 237 | "required": [ 238 | "@context", 239 | "id" 240 | ] 241 | }, 242 | "dataIntegrityProof": { 243 | "type": "object", 244 | "properties": { 245 | "id": { 246 | "type": "string" 247 | }, 248 | "type": { 249 | "const": "DataIntegrityProof" 250 | }, 251 | "cryptosuite": { 252 | "const": "eddsa-jcs-2022" 253 | }, 254 | "proofPurpose": { 255 | "const": "assertionMethod" 256 | }, 257 | "proofValue": { 258 | "type": "string" 259 | }, 260 | "verificationMethod": { 261 | "type": "string" 262 | }, 263 | "created": { 264 | "type": "date-time" 265 | }, 266 | "expires": { 267 | "type": "date-time" 268 | } 269 | }, 270 | "required": [ 271 | "type", 272 | "cryptosuite", 273 | "verificationMethod", 274 | "proofPurpose", 275 | "proofValue" 276 | ] 277 | } 278 | } 279 | } -------------------------------------------------------------------------------- /spec-anoncreds-method/abstract.md: -------------------------------------------------------------------------------- 1 | ## Abstract 2 | 3 | This `did:webvh` AnonCreds Method specification defines how [[spec: AnonCreds]] objects should be registered (written) and resolved when rooting them in a `did:webvh` DID. This specification parallels other DID-specific AnonCreds methods that are registered in the [AnonCreds Methods Registry]. 4 | 5 | [AnonCreds Methods Registry]: https://hyperledger.github.io/anoncreds-methods-registry/ 6 | 7 | The specification introduces the concept of an [[ref: Attested Resource]] that enables verifiable identifiers that resolve to resources (files) managed by a `did:webvh` Controller. We anticipate later extracting the [[ref: Attested Resources]] concept into a separate specification on its own. Each of the published AnonCreds objects ([[ref: schema]], [[ref: CredDef]], [[ref: RevRegDef]], and [[ref: RevRegEntry]] are treated as [[ref: Attested Resources]] in this AnonCreds method. 8 | 9 | For information beyond this `did:webvh` AnonCreds Method specification, the (`did:webvh`) DID method, and how (and 10 | where) it is used in practice, please visit [https://didwebvh.info/](https://didwebvh.info/). 11 | -------------------------------------------------------------------------------- /spec-anoncreds-method/definitions.md: -------------------------------------------------------------------------------- 1 | ## Definitions 2 | 3 | [[def: Schema, AnonCreds Schema, Schemas, AnonCreds Schemas]] 4 | 5 | ~ A JSON object that defines the schema for an AnonCreds verifiable credential. A schema for a given verifiable credential type rooted to a `did:webvh` DID can be resolved as an [[ref: Attested Resource]] associated with that DID. The AnonCreds schema is defined in the [Schema publishing section](https://hyperledger.github.io/anoncreds-spec/#schema-publisher-publish-schema-object) of the [[spec: AnonCreds]] specification. 6 | 7 | [[def: CredDef, AnonCreds CredDef, CredDefs, AnonCreds CredDefs]] 8 | 9 | ~ A JSON object that contains the public keys that enables verification of an an AnonCreds verifiable presentation derived from a verifiable credential from a specific Issuer. A CredDef for a given verifiable credential type rooted to a `did:webvh` DID can be resolved as an [[ref: Attested Resource]] associated with that DID. An AnonCreds CredDef object is defined in the [CredDef generation section](https://hyperledger.github.io/anoncreds-spec/#generating-a-credential-definition-without-revocation-support) of the [[spec: AnonCreds]] specification. 10 | 11 | [[def: RevRegDef, AnonCreds RevRegDef, RevRegDefs, AnonCreds RevRegDefs]] 12 | 13 | ~ A JSON object that contains the metadata and public key published by the Issuer that enables verification of an AnonCreds [non-revocation proof](https://hyperledger.github.io/anoncreds-spec/#collecting-data-for-generating-the-non-revocation-proof) that a holder includes in a presentation of a revocable credential. A RevRegDef for a given [[ref: AnonCreds CredDef]] rooted to a `did:webvh` DID can be resolved as an [[ref: Attested Resource]] associated with that DID. An AnonCreds RevRegDef object is defined in the [RevRegDef creation section](https://hyperledger.github.io/anoncreds-spec/#issuer-create-and-publish-revocation-registry-objects) of the [[spec: AnonCreds]] specification. 14 | 15 | [[def: RevRegEntry, AnonCreds RevRegEntry, RevRegEntries, AnonCreds RevRegEntries]] 16 | 17 | ~ A JSON object that contains the accumulator and current state (revoked or not) of all credentials within an AnonCreds revocation registry. The RevRegEntry data is used by the Holder to create a [non-revocation proof](https://hyperledger.github.io/anoncreds-spec/#collecting-data-for-generating-the-non-revocation-proof). A verifier must get the accumulator from the same RevRegEntry used by the holder to verify the non-revocation proof. A RevRegEntry for a given [[ref: AnonCreds RevRegDef]] rooted to a `did:webvh` DID can be resolved as an [[ref: Attested Resource]] associated with that DID. An AnonCreds RevRegEntry object is defined in the [RevRegEntry creation section](https://hyperledger.github.io/anoncreds-spec/#creating-the-initial-revocation-status-list-object) of the [[spec: AnonCreds]] specification. 18 | 19 | [[def: Attested Resource, Attested Resources, attestedResource]] 20 | 21 | ~ A JSON object, published as a resource associated with a `did:webvh` DID. The resolvable identifier for the resource includes the hash of the resource, and there is a Data Integrity proof signed by the DID Controller attached to the JSON object that includes the resource. The hash and proof are used to verify that the resolved resource has not been altered, and was published by the DID Controller. 22 | 23 | [[def: Data Integrity]] 24 | 25 | ~ [W3C Data 26 | Integrity](https://www.w3.org/community/reports/credentials/CG-FINAL-data-integrity-20220722/) 27 | is a specification of mechanisms for ensuring the authenticity and integrity of 28 | structured digital documents using cryptography, such as digital signatures and 29 | other digital mathematical proofs. 30 | 31 | [[def: DID Controller, DID Controller's, DID Controllers]] 32 | 33 | ~ The entity that controls (create, updates, deletes) a given DID, as defined 34 | in the [[spec:DID-CORE]]. 35 | -------------------------------------------------------------------------------- /spec-anoncreds-method/header.md: -------------------------------------------------------------------------------- 1 | The `did:webvh` AnonCreds Method
v0.1 / Editor's Draft 2 | ================== 3 | 4 | ![did:webvh Logo](https://raw.githubusercontent.com/decentralized-identity/didwebvh/refs/heads/main/didwebvh.jpg) 5 | 6 | **Specification Status:** EDITORS DRAFT 7 | 8 | At this time, the **Editor's Draft** contains the initial version of the specification. 9 | 10 | **Current Specification:** [Editor's Draft](./) 11 | 12 | **Specification Version:** v0.1 (see [Changelog](#didwebvh-anoncreds-methof-version-changelog)) 13 | 14 | **Source of Latest Draft:** 15 | [https://github.com/decentralized-identity/didwebvh/spec-anoncreds-method](https://github.com/decentralized-identity/didwebvh/spec-anoncreds-method) 16 | 17 | **Previous Versions:** 18 | - None 19 | 20 | **Information Site:** 21 | [https://didwebvh.info/](https://didwebvh.info/) 22 | 23 | **Editors:** 24 | ~ [Stephen Curran](https://github.com/swcurran) 25 | ~ [John Jordan, BC Gov](https://github.com/jljordan42) 26 | ~ [Andrew Whitehead](https://github.com/andrewwhitehead) 27 | ~ [Brian Richter](https://github.com/brianorwhatever) 28 | ~ [Michel Sahli](https://github.com/bj-ms) 29 | ~ [Martina Kolpondinos](https://github.com/martipos) 30 | ~ [Dmitri Zagdulin](https://github.com/dmitrizagidulin) 31 | 32 | **Participate:** 33 | ~ [GitHub repo](https://github.com/decentralized-identity/didwebvh) 34 | ~ [File a bug](https://github.com/decentralized-identity/didwebvh/issues) 35 | ~ [Commit history](https://github.com/decentralized-identity/didwebvh/commits/main) 36 | 37 | **Implementations:** 38 | ~ [didwebvh Server in Python] 39 | ~ [ACA-Py] 40 | 41 | [ACA-Py]: https://github.com/openwallet-foundation/acapy 42 | [didwebvh Server in Python]: https://github.com/decentralized-identity/trustdidweb-server-py 43 | 44 | ------------------------------------ 45 | -------------------------------------------------------------------------------- /spec-anoncreds-method/references.md: -------------------------------------------------------------------------------- 1 | ## References 2 | 3 | [[spec]] 4 | -------------------------------------------------------------------------------- /spec-anoncreds-method/version.md: -------------------------------------------------------------------------------- 1 | ## `did:webvh` AnonCreds Methof Version Changelog 2 | 3 | The following lists the substantive changes in each version of the specification. 4 | 5 | - Version 0.1 6 | - Initial version of the specification 7 | -------------------------------------------------------------------------------- /spec-v0.3/abstract.md: -------------------------------------------------------------------------------- 1 | ## Abstract 2 | 3 | Trust DID Web (`did:tdw`) is an enhancement to the `did:web` DID method, 4 | providing complementary web-based features that address `did:web`'s 5 | limitations. `did:tdw` features include: 6 | 7 | - Ongoing publishing of all DID Document ([[ref: DIDDoc]]) versions for a DID instead of, 8 | or alongside a current `did:web` DID/DIDDoc. 9 | - The same DID-to-HTTPS transformation as `did:web`. 10 | - Supports the same [High Assurance DIDs with DNS] mechanism. 11 | - The ability to resolve the full history of the DID using a verifiable chain of 12 | updates to the [[ref: DIDDoc]] from genesis to deactivation. 13 | - A [[ref: self-certifying identifier]] (SCID) for the DID. The [[ref: SCID]], globally unique and 14 | embedded in the DID, is derived from the initial [[ref: DID log entry]]. It ensures the integrity 15 | of the DID's history mitigating the risk of attackers creating a new object with 16 | the same identifier. 17 | - An optional mechanism for enabling [[ref: DID portability]] via the [[ref: SCID]], allowing 18 | the DID's web location to be moved and the DID string to be updated, both while retaining 19 | a connection to the predecessor DID(s) and preserving the DID's verifiable history. 20 | - [[ref: DIDDoc]] updates contain a proof signed by the [[ref: DID Controllers]] *authorized* to 21 | update the DID. 22 | - An optional mechanism for publishing "pre-rotation" keys to prevent the loss of 23 | control of a DID in cases where an active private key is compromised. 24 | - An optional mechanism for having collaborating [[ref: witnesses]] 25 | that approve of updates to the DID by a [[ref: DID Controller]] before publication. 26 | - DID URL path handling that defaults (but can be overridden) to automatically 27 | resolving `/path/to/file` by using a comparable DID-to-HTTPS translation 28 | as for the [[ref: DIDDoc]]. 29 | - A DID URL path `/whois` that defaults to automatically returning (if 30 | published by the [[ref: DID controller]]) a [[ref: Verifiable Presentation]] containing 31 | [[ref: Verifiable Credentials]] with the DID as the `credentialSubject`, 32 | signed by the DID. 33 | 34 | [High Assurance DIDs with DNS]: https://datatracker.ietf.org/doc/draft-carter-high-assurance-dids-with-dns/ 35 | 36 | Combined, the additional features enable greater trust and security without 37 | compromising the simplicity of `did:web`. 38 | 39 | The incorporation of the DID Core compatible "/whois" path, drawing inspiration 40 | from the traditional WHOIS protocol [[spec:rfc3912]], offers an easy-to-use, 41 | decentralized, trust registry. The `did:tdw` method aims to establish a more 42 | trusted and secure web environment by providing robust verification processes 43 | and enabling transparency and authenticity in the management of decentralized 44 | digital identities. 45 | -------------------------------------------------------------------------------- /spec-v0.3/definitions.md: -------------------------------------------------------------------------------- 1 | ## Definitions 2 | 3 | [[def: base58btc]] 4 | 5 | ~ Applies [[spec:draft-msporny-base58-03]] to convert 6 | data to a `base58` encoding. Used in `did:tdw` for encoding hashes for [[ref: SCIDs]] and [[ref: entry hashes]]. 7 | 8 | [[def: Data Integrity]] 9 | 10 | ~ [W3C Data 11 | Integrity](https://www.w3.org/community/reports/credentials/CG-FINAL-data-integrity-20220722/) 12 | is a specification of mechanisms for ensuring the authenticity and integrity of 13 | structured digital documents using cryptography, such as digital signatures and 14 | other digital mathematical proofs. 15 | 16 | [[def: Decentralized Identifier, Decentralized Identifiers]] 17 | 18 | ~ Decentralized Identifiers (DIDs) [[spec:did-core]] are a type of identifier that enable 19 | verifiable, decentralized digital identities. A DID refers to any subject (e.g., 20 | a person, organization, thing, data model, abstract entity, etc.) as determined 21 | by the controller of the DID. 22 | 23 | [[def: DIDDoc]] 24 | 25 | ~ A DID Document as defined by the [[spec: DID-Core]] -- the document returned when a DID is resolved. 26 | 27 | [[def: DID:key]] 28 | 29 | ~ `DID:key`... 30 | 31 | [[def: DID Log, DID Logs]] 32 | 33 | ~ A DID Log is a list of [[ref: Entries]] one being added for each update of an entry item, 34 | including new versions of the [[ref: DIDDoc]] or changed information necessary to generate or validate the DID. 35 | 36 | [[def: DID Log Entry, DID Log Entries, Entries, Log Entries]] 37 | 38 | ~ A DID Log Entry is a JSON array of five items which define the authorized 39 | transformation of a [[ref: DIDDoc]] from one version to the next. The initial entry 40 | establishes the DID and version 1 of the [[ref: DIDDoc]]. All entries are stored 41 | in the [[ref: DID Log]]. 42 | 43 | [[def: DID Method, DID Methods]] 44 | 45 | ~ DID methods are the mechanism by which a particular type of DID and its 46 | associated DID document are created, resolved, updated, and deactivated. DID 47 | methods are defined using separate DID method specifications. This document is 48 | the DID Method Specification for `DID:tdw`. 49 | 50 | [[def: DID Portability, DID:tdw portability, `DID:tdw` portability]] 51 | 52 | ~ `did:tdw` [[ref: portability]] encompasses the ability to change the DID string for the 53 | DID while retaining the [[ref: SCID]] and the history of the DID. This is useful 54 | when forced to change (such as when an organization is acquired by another, 55 | resulting in a change of domain names) and when changing DID hosting service 56 | providers. 57 | 58 | [[def: did:web]] 59 | 60 | ~ `did:web` as described in the [W3C specification](https://w3c-ccg.github.io/did-method-web/) 61 | is a DID method that leverages the Domain Name System (DNS) to perform the DID operations. 62 | It is valued for its simplicity and ease of deployment compared to [[ref: DID methods]] that are 63 | based on distributed ledgers or blockchain technology, but also comes with increased 64 | challenges related to trust and security. `did:web` provides a starting point for `did:tdw`, 65 | which complements `did:web` with specific features to address the challenges 66 | while still providing ease of deployment. 67 | 68 | [[def: eddsa-jcs-2022]] 69 | 70 | ~ A cryptosuite defined for producing a [[ref: Data Integrity]] proof for an 71 | unsecured input data document and verifying the [[ref: Data Integrity]] proof of 72 | the secured document. More information on further operations and applications of 73 | the cryptosuite can be found in the specification, here: 74 | [eddsa-jcs-2022](https://www.w3.org/TR/vc-di-eddsa/#eddsa-jcs-2022) 75 | 76 | [[def: Entry Hash, entryHash]] 77 | 78 | ~ A `DID:tdw` entry hash is a hash generated using a formally defined process 79 | over the input data to a [[ref: log entry]], excluding the [[ref: Data Integrity]] proof 80 | item. The input data includes content from the predecessor to the version of the 81 | DID, ensuring that all the versions are "chained" together in a microledger. The 82 | generated [[ref: entry hash]] is subsequently included in the `versionId` element of the [[ref: log entry]] and **MUST** be 83 | verified by a resolver. 84 | 85 | [[def: ISO8601, ISO8601 String]] 86 | 87 | ~ A date/time expressed using the [ISO8601 88 | Standard](https://en.wikipedia.org/wiki/ISO_8601). 89 | 90 | [[def: JSON Canonicalization Scheme]] 91 | 92 | ~ [[spec:rfc8785]] defines a method for canonicalizing a JSON 93 | structure such that is suitable for verifiable hashing or signing. 94 | 95 | [[def: JSON Lines]] 96 | 97 | ~ A file of JSON Lines, as described on the site 98 | [https://jsonlines.org/](https://jsonlines.org/). In short, `JSONL` is lines of JSON with 99 | whitespace removed and separated by a newline that is convenient for handling 100 | streaming JSON data or log files. 101 | 102 | [[def: JSON Patch]] 103 | 104 | ~ [[spec:rfc6902]] is a web standard format for describing how to change a JSON 105 | document from one state to another. A [[ref: DID Controller]] **MAY** use it in `DID:tdw` 106 | to define how a [[ref: DIDDoc]] is changed from one version to the next. 107 | 108 | [[def: Pre-Rotation]] 109 | 110 | ~ A technique for a controller of a cryptographic key to commit to the public 111 | key it will rotate to next, without exposing that actual public key. It protects 112 | from an attacker that gains knowledge of the current private key from being 113 | able to rotate to a new key known only to the attacker. 114 | 115 | [[def: Linked-VP, Linked Verifiable Presentation]] 116 | 117 | ~ A [[spec:DID-CORE]] `service` entry that specifies where a [[ref: verifiable 118 | presentation]] about the DID subject can be found. The [Decentralized Identity 119 | Foundation](https://identity.foundation/) hosts the [Linked VP 120 | Specification](https://identity.foundation/linked-vp/). 121 | 122 | [[def: multihash]] 123 | 124 | ~ Per the [[spec:draft-multiformats-multihash-07]], [[ref: multihash]] is a specification 125 | for differentiating instances of hashes. Software creating a hash prefixes 126 | (according to the specification) data to the hash indicating the algorithm used 127 | and the length of the hash, so that software receiving the hash knows how to 128 | verify it. Although [[ref: multihash]] supports many hash algorithms, for 129 | interoperability, [[ref: DID Controllers]] **MUST** only use the hash algorithms defined 130 | in this specification as permitted. 131 | 132 | [[def: multi-sig, multisig]] 133 | 134 | ~ A cryptographic signature that to be valid **MUST** contain a defined threshold 135 | (for example, 4 of 7) individual signatures to be considered valid. The 136 | multi-signature key reference points to a verification method that defines what 137 | keys may contribute to the signature, and under what conditions the 138 | multi-signature is considered valid. 139 | 140 | [[def: parameters]] 141 | 142 | ~ `DID:tdw` [[ref: parameters]] are a defined set of configurations that control how the 143 | issuer has generated the DID, and how the resolver should process the DID [[ref: Log 144 | entries]]. The use of [[ref: parameters]] allows for the controlled evolution of `DID:tdw` 145 | log handling, such as evolving the permitted hash algorithms. 146 | 147 | [[def: self-certifying identifier, SCID, SCIDs]] 148 | 149 | ~ An object identifier derived from initial data such that an attacker could not 150 | create a new object with the same identifier. The input for a `DID:tdw` SCID is 151 | the initial [[ref: DIDDoc]] with the placeholder `{SCID}` wherever the SCID is to be 152 | placed. 153 | 154 | [[def: Verifiable Credential, Verifiable Credentials]] 155 | 156 | ~ A verifiable credential can represent all of the same information that a physical credential represents, adding technologies such as digital signatures, to make the credentials more tamper-evident and so more trustworthy than their physical counterparts. The [Verifiable Credential Data Model](https://www.w3.org/TR/vc-data-model/) is a W3C Standard. 157 | 158 | [[def: Verifiable Presentation, Verifiable Presentations]] 159 | 160 | ~ A [[ref: verifiable presentation]] data model is part W3C's [Verifiable Credential Data 161 | Model](https://www.w3.org/TR/vc-data-model/) that contains a set of [[ref: 162 | verifiable credentials]] about a `credentialSubject`, and a signature across the 163 | verifiable credentials generated by that subject. In this specification, the use 164 | case of primary interest is where the DID is the `credentialSubject` and the DID 165 | signs the [[ref: verifiable presentation]]. 166 | 167 | [[def: witness, witnesses]] 168 | 169 | ~ Witnesses are participants in the process of creating and verifying a version 170 | of a `DID:tdw` [[ref: DIDDoc]]. Notably, a witness receives from the [[ref: DID Controller]] a [[ref: DID 171 | Log]] entry ready for publication, verifies it according to this specification, 172 | and approves it according to its ecosystem governance (whatever that might be). If the verification and 173 | approval process results are positive, witnesses returns to the DID Controller a [[ref: Data Integrity]] proof 174 | attesting to that positive result. 175 | 176 | [[def: W3C VCDM]] 177 | 178 | ~ A Verifiable Credential that uses the Data Model defined by the W3C [[spec: W3C-VC]] specification. 179 | -------------------------------------------------------------------------------- /spec-v0.3/header.md: -------------------------------------------------------------------------------- 1 | Trust DID Web - `did:tdw` - v0.3 2 | ================== 3 | 4 | **Specification Status:** HISTORICAL -- **THIS IS NOT THE CURRENT VERSION OF THE SPECIFICATION** 5 | 6 | This version of the specification was released at the time the OLD name for the DID Method was in use. The DID Method hame has since changed to `did:webvh` ("`did:web` + Verifiable History"). 7 | 8 | **Specification Version:** 0.3 (see [Changelog](#didtdw-version-changelog)) 9 | 10 | **Latest Version:** 11 | 12 | - Specification: [https://identity.foundation/didwebvh/](../) 13 | - Repository: [https://github.com/decentralized-identity/didwebvh](https://github.com/decentralized-identity/didwebvh) 14 | 15 | **Editors:** 16 | ~ [Stephen Curran](https://github.com/swcurran) 17 | ~ [John Jordan, BC Gov](https://github.com/jljordan42) 18 | ~ [Andrew Whitehead](https://github.com/andrewwhitehead) 19 | ~ [Brian Richter](https://github.com/brianorwhatever) 20 | ~ [Michel Sahli](https://github.com/bj-ms) 21 | ~ [Martina Kolpondinos](https://github.com/martipos) 22 | ~ [Dmitri Zagdulin](https://github.com/dmitrizagidulin) 23 | 24 | **Participate:** 25 | ~ [GitHub repo](https://github.com/decentralized-identity/didwebvh) 26 | ~ [File a bug](https://github.com/decentralized-identity/didwebvh/issues) 27 | ~ [Commit history](https://github.com/decentralized-identity/didwebvh/commits/main) 28 | 29 | **Implementations:** 30 | ~ [TypeScript] 31 | ~ [Python] 32 | ~ [Go] 33 | 34 | [TypeScript]: https://github.com/decentralized-identity/trustdidweb-ts 35 | [Python]: https://github.com/decentralized-identity/trustdidweb-py 36 | [Go]: https://github.com/nuts-foundation/trustdidweb-go 37 | 38 | ------------------------------------ 39 | -------------------------------------------------------------------------------- /spec-v0.3/overview.md: -------------------------------------------------------------------------------- 1 | ## Overview 2 | 3 | The emergence of [[ref: Decentralized Identifiers]] (DIDs) and with them the 4 | evolution of [[ref: DID Methods]] continues to be a dynamic area of 5 | development in the quest for trusted, secure and private digital identity 6 | management where the users are in control of their own data. 7 | 8 | The `did:web` method, for example, leverages the Domain Name System (DNS) to 9 | perform the DID operations. This approach is praised for its simplicity and 10 | ease of deployment, including DID-to-HTTPS transformation and addressing 11 | some aspects of trust by allowing for DIDs to be associated with a domain's 12 | reputation or published on platforms such as GitHub. However, it is not 13 | without its challenges-- 14 | from trust layers inherited from the web and the absence of a verifiable 15 | history for the DID. 16 | 17 | Tackling these concerns, the proposed `did:tdw` (Trust DID Web) 18 | method aims to enhance `did:web` by introducing additional features such 19 | as a [[ref: self-certifying identifier]] (SCID), update key(s) 20 | and a verifiable history, akin to what is available with ledger-based DIDs, 21 | without relying on a ledger. 22 | 23 | This approach not only maintains backward compatibility but also offers an 24 | additional layer of assurance for those requiring more robust verification 25 | processes. By publishing the resulting DID as both `did:web` and `did:tdw`, it 26 | caters to a broader range of trust requirements, from those who are comfortable 27 | with the existing `did:web` infrastructure to those seeking greater security 28 | assurances provided by `did:tdw`. This innovative step represents a significant 29 | stride towards a more trusted and secure web, where the integrity of 30 | cryptographic key publishing is paramount. 31 | 32 | The key differences between `did:web` and `did:tdw` revolve around the core 33 | issues of decentralization and security. `did:web` is recognized for its 34 | simplicity and cost-effectiveness, allowing for easy establishment of a 35 | credential ecosystem. However, it is not inherently decentralized as it relies 36 | on DNS domain names, which require centralized registries. Furthermore, it lacks a 37 | cryptographically verifiable, tamper-resistant, and persistently stored DID 38 | document. In contrast, `did:tdw` (Trust DID Web) is proposed as an enhancement 39 | to `did:web`, aiming to address these limitations by adding a verifiable history 40 | to the DID without the need for a ledger. This method seeks to provide a more 41 | decentralized approach by ensuring that the security of the embedded 42 | SCID does not depend on DNS. Additionally, `did:tdw` is 43 | capable of resolving a cryptographically verifiable trust registry and status 44 | lists, using DID-Linked Resources, which `did:web` lacks. These features are 45 | designed to build a trusted web, offering a higher level of assurance for 46 | cryptographic key publishing and management. 47 | 48 | For backwards compatibility, and for verifiers that "trust" `did:web`, a 49 | `did:tdw` can be trivially modified and published in parallel to a `did:web` 50 | DID. For resolvers that want more assurance, `did:tdw` provides a way to "trust 51 | did:web" (or to enable a "trusted web" if you say it fast) enabled by the 52 | features listed in the [Abstract](#abstract). 53 | 54 | The following is a `tl;dr` summary of how `did:tdw` works: 55 | 56 | 1. `did:tdw` uses the same DID-to-HTTPS transformation as `did:web`, so 57 | `did:tdw`'s `did.jsonl` ([[ref: JSON Lines]]) file is found in the same 58 | location as `did:web`'s `did.json` file, and supports an easy transition 59 | from `did:web` to gain the added benefits of `did:tdw`. 60 | 2. The `did.jsonl` is a list of JSON [[ref: DID log entries]], one per line, 61 | whitespace removed (per [[ref: JSON Lines]]). Each entry contains the 62 | information needed to derive a version of the [[ref: DIDDoc]] from its preceding 63 | version. The `did.jsonl` is also referred to as the [[ref: DID Log]]. 64 | 3. Each [[ref: DID log entry]] includes a JSON array of five items: 65 | 1. The `versionId` of the entry, a value that combines the version number 66 | (starting at `1` and incrementing by one per version), a literal dash 67 | `-`, and a hash of the entry. The [[ref: entry hash]] calculation links each entry 68 | to its predecessor in a ledger-like chain. 69 | 2. The `versionTime` (as stated by the [[ref: DID Controller]]) of the entry. 70 | 3. A set of `parameters` that impact the processing of the current and 71 | future [[ref: log entries]]. 72 | - Example [[ref: parameters]] are the version of the `did:tdw` specification and 73 | hash algorithm being used as well as the [[ref: SCID]] and update key(s). 74 | 4. The new version of the [[ref: DIDDoc]] as either a `value` (the full document) or 75 | a `patch` derived using [[ref: JSON Patch]] to update the new version from 76 | the previous entry. 77 | 5. A [[ref: Data Integrity]] (DI) proof across the entry, signed by a [[ref: DID 78 | Controller]] authorized to update the [[ref: DIDDoc]], using the `versionId` as the 79 | challenge. 80 | 4. In generating the first version of the [[ref: DIDDoc]], the [[ref: DID Controller]] calculates 81 | the [[ref: SCID]] for the DID from the entire first [[ref: log entry]] (which 82 | includes the [[ref: DIDDoc]]) by adding the string {SCID} everywhere the actual [[ref: SCID]] 83 | is to be placed. The [[ref: DID Controller]] then replaces these placeholders 84 | with the just calculated [[ref: SCID]], including it as a `parameter` in the first [[ref: log 85 | entry]], and inserting it where needed in the initial (and all subsequent) 86 | DIDDocs. The [[ref: SCID]] enables an optional [[ref: portability]] capability, allowing a DID's 87 | web location to be moved to a new location while retaining the DID and version 88 | history of the DID. 89 | 5. A [[ref: DID Controller]] generates and publishes the new/updated [[ref: DID Log]] file by making it 90 | available at the appropriate location on the web, based on the identifier of the 91 | DID. 92 | 6. Given a `did:tdw` DID, a resolver converts the DID to an HTTPS URL, 93 | retrieves, and processes the [[ref: DID Log]] `did.jsonl`, generating and verifying 94 | each [[ref: log entry]] as per the requirements outlined in this specification. 95 | - In the process, the resolver collects all the [[ref: DIDDoc]] versions and public 96 | keys used by the DID currently, or in the past. This enables 97 | resolving both current and past versions of the DID. 98 | 7. `did:tdw` DID URLs with paths and `/whois` are resolved to documents 99 | published by the [[ref: DID Controller]] that are by default in the web location relative to the 100 | `did.jsonl` file. See the [note below](#the-whois-use-case) about the 101 | powerful capability enabled by the `/whois` DID URL path. 102 | 8. Optionally, a [[ref: DID Controller]] can easily generate and publish a `did:web` DIDDoc 103 | from the latest `did:tdw` [[ref: DIDDoc]] in parallel with the `did:tdw` [[ref: DID Log]]. 104 | 105 | ::: warning 106 | A resolver settling for just the `did:web` version of the DID does not get the 107 | verifiability of the `did:tdw` log. 108 | ::: 109 | 110 | An example of a `did:tdw` evolving through a series of versions can be seen in 111 | the [did:tdw Examples](#didtdw-example) of this specification. 112 | 113 | This draft specification was developed in parallel with the development of two 114 | proof of concept implementations. The specification/implementation interplay 115 | helped immensely in defining a practical, intuitive, straightforward, DID 116 | method. The existing proof of concept implementations of the `did:tdw` DID 117 | Method are listed in the [Implementors Guide](#Implementations). The current 118 | implementations range from around 1500 to 2000 lines of code. 119 | 120 | ### The `/whois` Use Case 121 | 122 | This DID Method introduces what we hope will be a widely embraced convention for 123 | all [[ref: DID Methods]] -- the `/whois` path. This feature harkens back to the `WHOIS` 124 | protocol that was created in the 1970s to provide a directory about people and 125 | entities in the early days of ARPANET. In the 80's, `whois` evolved into 126 | [[spec-inform:rfc920]] that has expanded into the [global 127 | whois](https://en.wikipedia.org/wiki/WHOIS) feature we know today as 128 | [[spec-inform:rfc3912]]. Submit a `whois` request about a domain name, and get 129 | back the information published about that domain. 130 | 131 | We propose that the `/whois` path for a DID enable a comparable, decentralized, 132 | version of the `WHOIS` protocol for DIDs. Notably, when `/whois` is 133 | resolved (using a standard DID `service` that follows the [[ref: Linked-VP]] 134 | specification), a [[ref: Verifiable Presentation]] (VP) may be returned (if 135 | published by the [[ref: DID Controller]]) containing [[ref: Verifiable Credentials]] with 136 | the DID as the `credentialSubject`, and the VP signed by the DID. Given a DID, 137 | one can gather verifiable data about the [[ref: DID Controller]] by resolving 138 | `/whois` and processing the returned VP. That's powerful -- an efficient, 139 | highly decentralized, trust registry. For `did:tdw`, the approach is very simple 140 | -- transform the DID to its HTTPS equivalent, and execute a `GET /whois`. 141 | Need to know who issued the VCs in the VP? Get the issuer DIDs from those VCs, 142 | and resolve `/whois` for each. This is comparable to walking a CA 143 | (Certificate Authority) hierarchy, but self-managed by the [[ref: DID Controllers]] -- 144 | and the issuers that attest to them. 145 | 146 | The following is a use case for the `/whois` capability. Consider an example of 147 | the `did:tdw` controller being a mining company that has exported a shipment and 148 | created a "Product Passport" Verifiable Credential with information about the 149 | shipment. A country importing the shipment (the Importer) might want to know 150 | more about the issuer of the VC, and hence, the details of the shipment. They 151 | resolve the `/whois` of the entity and get back a Verifiable Presentation 152 | about that DID. It might contain: 153 | 154 | - A verifiable credential issued by the Legal Entity Registrar for the 155 | jurisdiction in which the mining company is headquartered. 156 | - Since the Importer knows about the Legal Entity Registrar, they can automate 157 | this lookup to get more information about the company from the VC -- its 158 | legal name, when it was registered, contact information, etc. 159 | - A verifiable credential for a "Mining Permit" issued by the mining authority 160 | for the jurisdiction in which the company operates. 161 | - Perhaps the Importer does not know about the mining authority for that 162 | jurisdiction. The Importer can repeat the `/whois` resolution process for 163 | the issuer of _that_ credential. The Importer might (for example), resolve 164 | and verify the `did:tdw` DID for the Authority, and then resolve the 165 | `/whois` DID URL to find a verifiable credential issued by the government of 166 | the jurisdiction. The Importer recognizes and trusts that government's 167 | authority, and so can decide to recognize and trust the mining permit 168 | authority. 169 | - A verifiable credential about the auditing of the mining practices of the 170 | mining company. Again, the Importer doesn't know about the issuer of the audit 171 | VC, so they resolve the `/whois` for the DID of the issuer, get its VP and 172 | find that it is accredited to audit mining companies by the [London Metal 173 | Exchange](https://www.lme.com/en/) according to one of its mining standards. 174 | As the Importer knows about both the London Metal Exchange and the standard, 175 | it can make a trust decision about the original Product Passport Verifiable 176 | Credential. 177 | 178 | Such checks can all be done with a handful of HTTPS requests and the processing 179 | of the DIDs and verifiable presentations. If the system cannot automatically 180 | make a trust decision, lots of information has been quickly collected that can 181 | be passed to a person to make such a decision. 182 | 183 | The result is an efficient, verifiable, credential-based, decentralized, 184 | multi-domain trust registry, empowering individuals and organizations to verify 185 | the authenticity and legitimacy of DIDs. The convention promotes a decentralized 186 | trust model where trust is established through cryptographic verification rather 187 | than reliance on centralized authorities. By enabling anyone to access and 188 | validate the information associated with a DID, the "/whois" path contributes to 189 | the overall security and integrity of decentralized networks. 190 | -------------------------------------------------------------------------------- /spec-v0.3/references.md: -------------------------------------------------------------------------------- 1 | ## References 2 | 3 | [[spec]] 4 | -------------------------------------------------------------------------------- /spec-v0.3/security_and_privacy.md: -------------------------------------------------------------------------------- 1 | ## Security and Privacy Considerations 2 | 3 | ### DNS Considerations 4 | 5 | #### DNS Security Considerations 6 | 7 | Implementers must secure DNS resolution to protect against attacks like Man in 8 | the Middle, following the detailed guidance in the [did:web 9 | specification](https://w3c-ccg.github.io/did-method-web/#dns-considerations). 10 | The use of DNSSEC [[spec:RFC4033]], [[spec:RFC4034]], [[spec:RFC4035]] is 11 | essential to prevent spoofing and ensure authenticity of DNS records. 12 | 13 | #### DNS Privacy Considerations 14 | 15 | Resolving a `did:tdw` identifier can expose users to tracking by DNS providers 16 | and web servers. To mitigate this risk, it's recommended to use privacy-enhancing 17 | technologies such as VPNs, TOR, or trusted universal resolver services, in line 18 | with strategies outlined in the [did:web 19 | specification](https://w3c-ccg.github.io/did-method-web/#dns-considerations) 20 | including emerging RFCs such as [Oblivious DNS over 21 | HTTPS](https://datatracker.ietf.org/doc/html/draft-pauly-dprive-oblivious-doh-03) 22 | for DNS privacy. 23 | 24 | ### In-transit Security 25 | 26 | For in-transit security, the guidance provided in the [did:web 27 | specification](https://w3c-ccg.github.io/did-method-web/#in-transit-security) 28 | regarding the encryption of traffic between the server and client should be 29 | followed. 30 | 31 | ### International Domain Names 32 | 33 | [[spec:DID-CORE]] identifier syntax does not allow Unicode in method name nor 34 | method specific identifiers. 35 | 36 | Implementers should be cautious when implementing support for DID URLs that rely 37 | on domain names or path components that contain Unicode characters. 38 | 39 | See also: 40 | 41 | - [UTS-46](https://unicode.org/reports/tr46/) 42 | - [[spec:RFC5895]] 43 | -------------------------------------------------------------------------------- /spec-v0.3/version.md: -------------------------------------------------------------------------------- 1 | ## `did:tdw` Version Changelog 2 | 3 | The following lists the substantive changes in each version of the specification. 4 | 5 | - Version 0.3 6 | - Removes the `cryptosuite` [[ref: parameter]], moving it to implied based on the `method` [[ref: parameter]]. 7 | - Change base32 encoding with [[ref: base58btc]], as it offers a better expansion rate. 8 | - Remove the step to extract part of the [[ref: base58btc]] result during the generation of the [[ref: SCID]]. 9 | - Use [[ref: multihash]] in the [[ref: SCID]] to differentiate the different hash function outputs. 10 | - Version 0.2 11 | - Changes the location of the [[ref: SCID]] in the DID to always be the first 12 | component after the DID Method prefix -- `did:tdw::...`. 13 | - Adds the [[ref: parameter]] `portable` to enable the capability to move a 14 | `did:tdw` during the creation of the DID. 15 | - Removes the first two [[ref: Log Entry]] items `entryHash` and `versionId` 16 | and replacing them with the new `versionId` as the first item in each [[ref: log 17 | entry]]. The new versionId takes the form `-`, 18 | where `` is the incrementing integer of version of the 19 | entry: 1, 2, 3, etc. 20 | - The `/whois` media type is changed to `application/vp` and the file is 21 | changed to `whois.vp` to match the IANA registration of a [[ref: Verifiable 22 | Presentation]]. 23 | -------------------------------------------------------------------------------- /spec-v0.4/abstract.md: -------------------------------------------------------------------------------- 1 | ## Abstract 2 | 3 | Trust DID Web (`did:tdw`) is an enhancement to the `did:web` DID method, 4 | providing complementary features that address `did:web`'s 5 | limitations. `did:tdw` features include: 6 | 7 | - Ongoing publishing of all DID Document ([[ref: DIDDoc]]) versions for a DID instead of, 8 | or alongside a current `did:web` DID/DIDDoc. 9 | - The same DID-to-HTTPS transformation as `did:web`. 10 | - Supports the same [High Assurance DIDs with DNS] mechanism. 11 | - The ability to resolve the full history of the DID using a verifiable chain of 12 | updates to the [[ref: DIDDoc]] from genesis to deactivation. 13 | - A [[ref: self-certifying identifier]] (SCID) for the DID. The [[ref: SCID]], globally unique and 14 | embedded in the DID, is derived from the initial [[ref: DID log entry]]. It ensures the integrity 15 | of the DID's history mitigating the risk of attackers creating a new object with 16 | the same identifier. 17 | - An optional mechanism for enabling [[ref: DID portability]] via the [[ref: SCID]], allowing 18 | the DID's web location to be moved and the DID string to be updated, both while retaining 19 | a connection to the predecessor DID(s) and preserving the DID's verifiable history. 20 | - [[ref: DIDDoc]] updates contain a proof signed by the [[ref: DID Controllers]] *authorized* to 21 | update the DID. 22 | - An optional mechanism for publishing "pre-rotation" keys to prevent the loss of 23 | control of a DID in cases where an active private key is compromised. 24 | - An optional mechanism for having collaborating [[ref: witnesses]] 25 | that approve of updates to the DID by a [[ref: DID Controller]] before publication. 26 | - DID URL path handling that defaults (but can be overridden) to automatically 27 | resolving `/path/to/file` by using a comparable DID-to-HTTPS translation 28 | as for the [[ref: DIDDoc]]. 29 | - A DID URL path `/whois` that defaults to automatically returning (if 30 | published by the [[ref: DID controller]]) a [[ref: Verifiable Presentation]] 31 | containing [[ref: Verifiable Credentials]] with the DID as the 32 | `credentialSubject`, signed by the DID. It draws inspiration from the 33 | traditional WHOIS protocol [[spec:rfc3912]], offering an easy-to-use, 34 | decentralized, trust registry. 35 | 36 | [High Assurance DIDs with DNS]: https://datatracker.ietf.org/doc/draft-carter-high-assurance-dids-with-dns/ 37 | 38 | Combined, the additional features enable greater trust and security without 39 | compromising the simplicity of `did:web`. 40 | 41 | For more information about the Trust DID Web (`did:tdw`) DID method and how (and 42 | where) it is used in practice, please visit 43 | [https://didtdw.org/](https://didtdw.org/) 44 | -------------------------------------------------------------------------------- /spec-v0.4/definitions.md: -------------------------------------------------------------------------------- 1 | ## Definitions 2 | 3 | [[def: base58btc]] 4 | 5 | ~ Applies [[spec:draft-msporny-base58-03]] to convert 6 | data to a `base58` encoding. Used in `did:tdw` for encoding hashes for [[ref: SCIDs]] and [[ref: entry hashes]]. 7 | 8 | [[def: Data Integrity]] 9 | 10 | ~ [W3C Data 11 | Integrity](https://www.w3.org/community/reports/credentials/CG-FINAL-data-integrity-20220722/) 12 | is a specification of mechanisms for ensuring the authenticity and integrity of 13 | structured digital documents using cryptography, such as digital signatures and 14 | other digital mathematical proofs. 15 | 16 | [[def: Decentralized Identifier, Decentralized Identifiers, DID, DIDs]] 17 | 18 | ~ Decentralized Identifiers (DIDs) [[spec:did-core]] are a type of identifier that enable 19 | verifiable, decentralized digital identities. A DID refers to any subject (e.g., 20 | a person, organization, thing, data model, abstract entity, etc.) as determined 21 | by the controller of the DID. 22 | 23 | [[def: DID Controller, DID Controllers]] 24 | 25 | ~ The entity that controls (create, updates, deletes) a given DID, as defined 26 | in the [[spec:DID-CORE]]. 27 | 28 | [[def: DIDDoc]] 29 | 30 | ~ A DID Document as defined by the [[spec: DID-Core]] -- the document returned when a DID is resolved. 31 | 32 | [[def: did:key]] 33 | 34 | ~ `DID:key`... 35 | 36 | [[def: DID Log, DID Logs]] 37 | 38 | ~ A DID Log is a list of [[ref: Entries]], with an entry added for each update of the DID, 39 | including new versions of the [[ref: DIDDoc]] or changed information necessary to generate or validate the DID. 40 | 41 | [[def: DID Log Entry, DID Log Entries, Entries, Log Entries, Log Entry]] 42 | 43 | ~ A DID Log Entry is a JSON object that defines the authorized 44 | transformation of a [[ref: DIDDoc]] from one version to the next. The initial entry 45 | establishes the DID and version 1 of the [[ref: DIDDoc]]. All entries are stored 46 | in the [[ref: DID Log]]. 47 | 48 | [[def: DID Method, DID Methods]] 49 | 50 | ~ DID methods are the mechanism by which a particular type of DID and its 51 | associated DID document are created, resolved, updated, and deactivated. DID 52 | methods are defined using separate DID method specifications. This document is 53 | the DID Method Specification for `DID:tdw`. 54 | 55 | [[def: DID Portability, DID:tdw portability, `DID:tdw` portability, portability]] 56 | 57 | ~ `did:tdw` portability is the capability to change the DID string for the 58 | DID while retaining the [[ref: SCID]] and the history of the DID. This is useful 59 | when forced to change (such as when an organization is acquired by another, 60 | resulting in a change of domain names) and when changing DID hosting service 61 | providers. 62 | 63 | [[def: did:web]] 64 | 65 | ~ `did:web` as described in the [W3C specification](https://w3c-ccg.github.io/did-method-web/) 66 | is a DID method that leverages the Domain Name System (DNS) to perform the DID operations. 67 | It is valued for its simplicity and ease of deployment compared to [[ref: DID methods]] that are 68 | based on distributed ledgers or blockchain technology, but also comes with increased 69 | challenges related to trust and security. `did:web` provides a starting point for `did:tdw`, 70 | which complements `did:web` with specific features to address the challenges 71 | while still providing ease of deployment. 72 | 73 | [[def: eddsa-jcs-2022]] 74 | 75 | ~ A cryptosuite defined for producing a [[ref: Data Integrity]] proof for an 76 | unsecured input data document and verifying the [[ref: Data Integrity]] proof of 77 | the secured document. More information on further operations and applications of 78 | the cryptosuite can be found in the specification, here: 79 | [eddsa-jcs-2022](https://www.w3.org/TR/vc-di-eddsa/#eddsa-jcs-2022) 80 | 81 | [[def: Entry Hash, entryHash, entry hashes]] 82 | 83 | ~ A `DID:tdw` entry hash is a hash generated using a formally defined process 84 | over the input data to a [[ref: log entry]], excluding the [[ref: Data Integrity]] 85 | proof. The input data includes content from the predecessor to the 86 | version of the DID, ensuring that all the versions are "chained" together in a 87 | sort of microledger. The generated [[ref: entry hash]] is subsequently included in the 88 | `versionId` of the [[ref: log entry]] and **MUST** be verified by a 89 | resolver. 90 | 91 | [[def: ISO8601, ISO8601 String]] 92 | 93 | ~ A date/time expressed using the [ISO8601 94 | Standard](https://en.wikipedia.org/wiki/ISO_8601). 95 | 96 | [[def: JSON Canonicalization Scheme]] 97 | 98 | ~ [[spec:rfc8785]] defines a method for canonicalizing a JSON 99 | structure such that is suitable for verifiable hashing or signing. 100 | 101 | [[def: JSON Lines, JSON Line]] 102 | 103 | ~ A file of JSON Lines, as described on the site 104 | [https://jsonlines.org/](https://jsonlines.org/). In short, `JSONL` is lines of JSON with 105 | whitespace removed and separated by a newline that is convenient for handling 106 | streaming JSON data or log files. 107 | 108 | [[def: Pre-Rotation, Key Pre-Rotation]] 109 | 110 | ~ A technique for a controller of a cryptographic key to commit to the public 111 | key it will rotate to next, without exposing that actual public key. It protects 112 | from an attacker that gains knowledge of the current private key from being 113 | able to rotate to a new key known only to the attacker. 114 | 115 | [[def: Linked-VP, Linked Verifiable Presentation]] 116 | 117 | ~ A [[spec:DID-CORE]] `service` entry that specifies where a [[ref: verifiable 118 | presentation]] about the DID subject can be found. The [Decentralized Identity 119 | Foundation](https://identity.foundation/) hosts the [Linked VP 120 | Specification](https://identity.foundation/linked-vp/). 121 | 122 | [[def: multihash]] 123 | 124 | ~ Per the [[spec:multiformats]], [[ref: multihash]] is a specification 125 | for differentiating instances of hashes. Software creating a hash prefixes 126 | (according to the specification) data to the hash indicating the algorithm used 127 | and the length of the hash, so that software receiving the hash knows how to 128 | verify it. Although [[ref: multihash]] supports many hash algorithms, for 129 | interoperability, [[ref: DID Controllers]] **MUST** only use the hash algorithms defined 130 | in this specification as permitted. 131 | 132 | [[def: multi-sig, multisig]] 133 | 134 | ~ A cryptographic signature that to be valid **MUST** contain a defined threshold 135 | (for example, 4 of 7) individual signatures to be considered valid. The 136 | multi-signature key reference points to a verification method that defines what 137 | keys may contribute to the signature, and under what conditions the 138 | multi-signature is considered valid. 139 | 140 | [[def: parameters, parameter]] 141 | 142 | ~ `did:tdw` parameters are a defined set of configurations that control how the 143 | issuer has generated the DID, and how the resolver must process the DID [[ref: 144 | Log entries]]. The use of parameters allows for the controlled evolution of 145 | `did:tdw` log handling, such as evolving the set of permitted hash algorithms or 146 | cryptosuites. This enables support for very long lasting identifiers -- decades. 147 | 148 | [[def: self-certifying identifier, self-certifying identifiers, SCID, SCIDs]] 149 | 150 | ~ An object identifier derived from initial data such that an attacker could not 151 | create a new object with the same identifier. The input for a `DID:tdw` SCID is 152 | the initial [[ref: DIDDoc]] with the placeholder `{SCID}` wherever the SCID is to be 153 | placed. 154 | 155 | [[def: Verifiable Credential, Verifiable Credentials]] 156 | 157 | ~ A verifiable credential can represent all of the same information that a physical credential represents, adding technologies such as digital signatures, to make the credentials more tamper-evident and so more trustworthy than their physical counterparts. The [Verifiable Credential Data Model](https://www.w3.org/TR/vc-data-model/) is a W3C Standard. 158 | 159 | [[def: Verifiable Presentation, Verifiable Presentations]] 160 | 161 | ~ A [[ref: verifiable presentation]] data model is part W3C's [Verifiable Credential Data 162 | Model](https://www.w3.org/TR/vc-data-model/) that contains a set of [[ref: 163 | verifiable credentials]] about a `credentialSubject`, and a signature across the 164 | verifiable credentials generated by that subject. In this specification, the use 165 | case of primary interest is where the DID is the `credentialSubject` and the DID 166 | signs the [[ref: verifiable presentation]]. 167 | 168 | [[def: witness, witnesses]] 169 | 170 | ~ Witnesses are participants in the process of creating and verifying a version 171 | of a `DID:tdw` [[ref: DIDDoc]]. Notably, a witness receives from the [[ref: DID Controller]] a [[ref: DID 172 | Log]] entry ready for publication, verifies it according to this specification, 173 | and approves it according to its ecosystem governance (whatever that might be). If the verification and 174 | approval process results are positive, witnesses returns to the DID Controller a [[ref: Data Integrity]] proof 175 | attesting to that positive result. 176 | 177 | [[def: W3C VCDM]] 178 | 179 | ~ A Verifiable Credential that uses the Data Model defined by the W3C [[spec: W3C-VC]] specification. 180 | -------------------------------------------------------------------------------- /spec-v0.4/header.md: -------------------------------------------------------------------------------- 1 | Trust DID Web - `did:tdw` - v0.4 2 | ================== 3 | 4 | **Specification Status:** HISTORICAL -- **THIS IS NOT THE CURRENT VERSION OF THE SPECIFICATION** 5 | 6 | This version of the specification was released at the time the OLD name for the DID Method was in use. The DID Method hame has since changed to `did:webvh` ("`did:web` + Verifiable History"). 7 | 8 | **Specification Version:** 0.4 (see [Changelog](#didtdw-version-changelog)) 9 | 10 | **Latest Version:** 11 | 12 | - Specification: [https://identity.foundation/didwebvh/](../) 13 | - Repository: [https://github.com/decentralized-identity/didwebvh](https://github.com/decentralized-identity/didwebvh) 14 | 15 | **Previous Versions:** 16 | - [v0.3](./v0.3) 17 | 18 | **Information Site:** 19 | [https://didtdw.org/](https://didtdw.org/) 20 | 21 | **Editors:** 22 | ~ [Stephen Curran](https://github.com/swcurran) 23 | ~ [John Jordan, BC Gov](https://github.com/jljordan42) 24 | ~ [Andrew Whitehead](https://github.com/andrewwhitehead) 25 | ~ [Brian Richter](https://github.com/brianorwhatever) 26 | ~ [Michel Sahli](https://github.com/bj-ms) 27 | ~ [Martina Kolpondinos](https://github.com/martipos) 28 | ~ [Dmitri Zagdulin](https://github.com/dmitrizagidulin) 29 | 30 | **Participate:** 31 | ~ [GitHub repo](https://github.com/decentralized-identity/didwebvh) 32 | ~ [File a bug](https://github.com/decentralized-identity/didwebvh/issues) 33 | ~ [Commit history](https://github.com/decentralized-identity/didwebvh/commits/main) 34 | 35 | **Implementations:** 36 | ~ [TypeScript] 37 | ~ [Python] 38 | ~ [Go] 39 | ~ [DIDTDW Server in Python] 40 | 41 | [TypeScript]: https://github.com/decentralized-identity/trustdidweb-ts 42 | [Python]: https://github.com/decentralized-identity/trustdidweb-py 43 | [Go]: https://github.com/nuts-foundation/trustdidweb-go 44 | [DIDTDW Server in Python]: https://github.com/decentralized-identity/trustdidweb-server-py 45 | 46 | ------------------------------------ 47 | -------------------------------------------------------------------------------- /spec-v0.4/overview.md: -------------------------------------------------------------------------------- 1 | ## Overview 2 | 3 | The emergence of [[ref: Decentralized Identifiers]] (DIDs) and with them the 4 | evolution of [[ref: DID Methods]] continues to be a dynamic area of 5 | development in the quest for trusted, secure and private digital identity 6 | management where the users are in control of their own data. 7 | 8 | The `did:web` method, for example, leverages the Domain Name System (DNS) to 9 | perform the DID operations. This approach is praised for its simplicity and 10 | ease of deployment, including DID-to-HTTPS transformation and addressing 11 | some aspects of trust by allowing for DIDs to be associated with a domain's 12 | reputation or published on platforms such as GitHub. However, it is not 13 | without its challenges-- 14 | from trust layers inherited from the web and the absence of a verifiable 15 | history for the DID. 16 | 17 | Tackling these concerns, the `did:tdw` (Trust DID Web) DID 18 | method aims to enhance `did:web` by introducing features such 19 | as a [[ref: self-certifying identifiers]] (SCIDs), update key(s) 20 | and a verifiable history, akin to what is available with ledger-based DIDs, 21 | but without relying on a ledger. 22 | 23 | This approach not only maintains backward compatibility but also offers an 24 | additional layer of assurance for those requiring more robust verification 25 | processes. By publishing the resulting DID as both `did:web` and `did:tdw`, it 26 | caters to a broader range of trust requirements, from those who are comfortable 27 | with the existing `did:web` infrastructure to those seeking greater security 28 | assurances provided by `did:tdw`. This innovative step represents a significant 29 | stride towards a more trusted and secure web, where the integrity of 30 | cryptographic key publishing is paramount. 31 | 32 | The key differences between `did:web` and `did:tdw` revolve around the core 33 | issues of decentralization and security. `did:web` is recognized for its 34 | simplicity and cost-effectiveness, allowing for easy establishment of a 35 | credential ecosystem. However, it is not inherently decentralized as it relies 36 | on DNS domain names, which require centralized registries. Furthermore, it lacks a 37 | cryptographically verifiable, tamper-resistant, and persistently stored DID 38 | document. In contrast, `did:tdw` (Trust DID Web) is proposed as an enhancement 39 | to `did:web`, aiming to address these limitations by adding a verifiable history 40 | to the DID without the need for a ledger. This method seeks to provide a more 41 | decentralized approach by ensuring that the security of the embedded 42 | SCID does not depend on DNS. Additionally, `did:tdw` is 43 | capable of resolving a cryptographically verifiable trust registry and status 44 | lists, using DID-Linked Resources, which `did:web` lacks. These features are 45 | designed to build a trusted web, offering a higher level of assurance for 46 | cryptographic key publishing and management. 47 | 48 | For backwards compatibility, and for verifiers that "trust" `did:web`, a 49 | `did:tdw` can be trivially modified and published in parallel to a `did:web` 50 | DID. For resolvers that want more assurance, `did:tdw` provides a way to "trust 51 | did:web" (or to enable a "trusted web" if you say it fast) enabled by the 52 | features listed in the [Abstract](#abstract). 53 | 54 | The following is a `tl;dr` summary of how `did:tdw` works: 55 | 56 | 1. `did:tdw` uses the same DID-to-HTTPS transformation as `did:web`, so 57 | `did:tdw`'s `did.jsonl` ([[ref: JSON Lines]]) file is found in the same 58 | location as `did:web`'s `did.json` file, and supports an easy transition 59 | from `did:web` to gain the added benefits of `did:tdw`. 60 | 2. The `did.jsonl` is a list of JSON [[ref: DID log entries]], one per line, 61 | whitespace removed (per [[ref: JSON Lines]]). Each entry contains the 62 | information needed to derive a version of the [[ref: DIDDoc]] from its preceding 63 | version. The `did.jsonl` is also referred to as the [[ref: DID Log]]. 64 | 3. Each [[ref: DID log entry]] is a JSON object containing the following properties: 65 | 1. `versionId` -- a value that combines the version number 66 | (starting at `1` and incremented by one per version), a literal dash 67 | `-`, and a hash of the entry. The [[ref: entry hash]] calculation links each entry 68 | to its predecessor in a ledger-like chain. 69 | 2. `versionTime` -- as asserted by the [[ref: DID Controller]]. 70 | 3. `parameters` -- a set of [[ref: parameters]] that impact the processing of the current and 71 | future [[ref: log entries]]. 72 | - Example [[ref: parameters]] are the version of the `did:tdw` specification and 73 | hash algorithm being used as well as the [[ref: SCID]] and update key(s). 74 | 4. `state` -- the new version of the [[ref: DIDDoc]]. 75 | 5. A [[ref: Data Integrity]] (DI) proof across the entry, signed by a [[ref: 76 | DID Controller]] authorized key to update the [[ref: DIDDoc]], and optionally, 77 | a set of witnesses that monitor the actions of the DID Controller. 78 | 4. In generating the first version of the [[ref: DIDDoc]], the [[ref: DID 79 | Controller]] calculates the [[ref: SCID]] for the DID from the first [[ref: 80 | log entry]] (which includes the [[ref: DIDDoc]]) by using the string 81 | `"{SCID}"` everywhere the actual [[ref: SCID]] is to be placed. The [[ref: DID 82 | Controller]] then replaces the placeholders with the calculated [[ref: SCID]], 83 | including it as a `parameter` in the first [[ref: log entry]], and inserting 84 | it where needed in the initial (and all subsequent) DIDDocs. The [[ref: SCID]] 85 | enables an optional [[ref: portability]] capability, allowing a DID's web 86 | location to be moved, while retaining the DID and version history of the DID. 87 | 1. A [[ref: DID Controller]] generates and publishes the new/updated [[ref: DID Log]] file by making it 88 | available at the appropriate location on the web, based on the identifier of the 89 | DID. 90 | 1. Given a `did:tdw` DID, a resolver converts the DID to an HTTPS URL, 91 | retrieves, and processes the [[ref: DID Log]] `did.jsonl`, generating and verifying 92 | each [[ref: log entry]] as per the requirements outlined in this specification. 93 | - In the process, the resolver collects all the [[ref: DIDDoc]] versions and public 94 | keys used by the DID currently, or in the past. This enables 95 | resolving both current and past versions of the DID. 96 | 1. `did:tdw` DID URLs with paths and `/whois` are resolved to documents 97 | published by the [[ref: DID Controller]] that are by default in the web location relative to the 98 | `did.jsonl` file. See the [note below](#the-whois-use-case) about the 99 | powerful capability enabled by the `/whois` DID URL path. 100 | 1. Optionally, a [[ref: DID Controller]] can easily generate and publish a `did:web` DIDDoc 101 | from the latest `did:tdw` [[ref: DIDDoc]] in parallel with the `did:tdw` [[ref: DID Log]]. 102 | 103 | ::: warning 104 | A resolver settling for just the `did:web` version of the DID does not get the 105 | verifiability of the `did:tdw` log. 106 | ::: 107 | 108 | An example of a `did:tdw` evolving through a series of versions can be seen in 109 | the [did:tdw Examples](https://didtdw.org/latest/example/) on the `did:tdw` 110 | information site. 111 | 112 | ### The `/whois` Use Case 113 | 114 | This DID Method introduces what we hope will be a widely embraced convention for 115 | all [[ref: DID Methods]] -- the `/whois` path. This feature harkens back to the `WHOIS` 116 | protocol that was created in the 1970s to provide a directory about people and 117 | entities in the early days of ARPANET. In the 80's, `whois` evolved into 118 | [[spec-inform:rfc920]] that has expanded into the [global 119 | whois](https://en.wikipedia.org/wiki/WHOIS) feature we know today as 120 | [[spec-inform:rfc3912]]. Submit a `whois` request about a domain name, and get 121 | back the information published about that domain. 122 | 123 | We propose that the `/whois` path for a DID enable a comparable, decentralized, 124 | version of the `WHOIS` protocol for DIDs. Notably, when `/whois` is 125 | resolved (using a standard DID `service` that follows the [[ref: Linked-VP]] 126 | specification), a [[ref: Verifiable Presentation]] (VP) may be returned (if 127 | published by the [[ref: DID Controller]]) containing [[ref: Verifiable Credentials]] with 128 | the DID as the `credentialSubject`, and the VP signed by the DID. Given a DID, 129 | one can gather verifiable data about the [[ref: DID Controller]] by resolving 130 | `/whois` and processing the returned VP. That's powerful -- an efficient, 131 | highly decentralized, trust registry. For `did:tdw`, the approach is very simple 132 | -- transform the DID to its HTTPS equivalent, and execute a `GET /whois`. 133 | Need to know who issued the VCs in the VP? Get the issuer DIDs from those VCs, 134 | and resolve `/whois` for each. This is comparable to walking a CA 135 | (Certificate Authority) hierarchy, but self-managed by the [[ref: DID Controllers]] -- 136 | and the issuers that attest to them. 137 | 138 | The following is a use case for the `/whois` capability. Consider an example of 139 | the `did:tdw` controller being a mining company that has exported a shipment and 140 | created a "Product Passport" Verifiable Credential with information about the 141 | shipment. A country importing the shipment (the Importer) might want to know 142 | more about the issuer of the VC, and hence, the details of the shipment. They 143 | resolve the `/whois` of the entity and get back a Verifiable Presentation 144 | about that DID. It might contain: 145 | 146 | - A verifiable credential issued by the Legal Entity Registrar for the 147 | jurisdiction in which the mining company is headquartered. 148 | - Since the Importer knows about the Legal Entity Registrar, they can automate 149 | this lookup to get more information about the company from the VC -- its 150 | legal name, when it was registered, contact information, etc. 151 | - A verifiable credential for a "Mining Permit" issued by the mining authority 152 | for the jurisdiction in which the company operates. 153 | - Perhaps the Importer does not know about the mining authority for that 154 | jurisdiction. The Importer can repeat the `/whois` resolution process for 155 | the issuer of _that_ credential. The Importer might (for example), resolve 156 | and verify the `did:tdw` DID for the Authority, and then resolve the 157 | `/whois` DID URL to find a verifiable credential issued by the government of 158 | the jurisdiction. The Importer recognizes and trusts that government's 159 | authority, and so can decide to recognize and trust the mining permit 160 | authority. 161 | - A verifiable credential about the auditing of the mining practices of the 162 | mining company. Again, the Importer doesn't know about the issuer of the audit 163 | VC, so they resolve the `/whois` for the DID of the issuer, get its VP and 164 | find that it is accredited to audit mining companies by the [London Metal 165 | Exchange](https://www.lme.com/en/) according to one of its mining standards. 166 | As the Importer knows about both the London Metal Exchange and the standard, 167 | it can make a trust decision about the original Product Passport Verifiable 168 | Credential. 169 | 170 | Such checks can all be done with a handful of HTTPS requests and the processing 171 | of the DIDs and verifiable presentations. If the system cannot automatically 172 | make a trust decision, lots of information has been quickly collected that can 173 | be passed to a person to make such a decision. 174 | 175 | The result is an efficient, verifiable, credential-based, decentralized, 176 | multi-domain trust registry, empowering individuals and organizations to verify 177 | the authenticity and legitimacy of DIDs. The convention promotes a decentralized 178 | trust model where trust is established through cryptographic verification rather 179 | than reliance on centralized authorities. By enabling anyone to access and 180 | validate the information associated with a DID, the "/whois" path contributes to 181 | the overall security and integrity of decentralized networks. 182 | -------------------------------------------------------------------------------- /spec-v0.4/references.md: -------------------------------------------------------------------------------- 1 | ## References 2 | 3 | [[spec]] 4 | -------------------------------------------------------------------------------- /spec-v0.4/security_and_privacy.md: -------------------------------------------------------------------------------- 1 | ## Security and Privacy Considerations 2 | 3 | ### DNS Considerations 4 | 5 | #### DNS Security Considerations 6 | 7 | Implementers must secure DNS resolution to protect against attacks like Man in 8 | the Middle, following the detailed guidance in the [did:web 9 | specification](https://w3c-ccg.github.io/did-method-web/#dns-considerations). 10 | The use of DNSSEC [[spec:RFC4033]], [[spec:RFC4034]], [[spec:RFC4035]] is 11 | essential to prevent spoofing and ensure authenticity of DNS records. 12 | 13 | #### DNS Privacy Considerations 14 | 15 | Resolving a `did:tdw` identifier can expose users to tracking by DNS providers 16 | and web servers. To mitigate this risk, it's recommended to use privacy-enhancing 17 | technologies such as VPNs, TOR, or trusted universal resolver services, in line 18 | with strategies outlined in the [did:web 19 | specification](https://w3c-ccg.github.io/did-method-web/#dns-considerations) 20 | including emerging RFCs such as [Oblivious DNS over 21 | HTTPS](https://datatracker.ietf.org/doc/html/draft-pauly-dprive-oblivious-doh-03) 22 | for DNS privacy. 23 | 24 | ### In-transit Security 25 | 26 | For in-transit security, the guidance provided in the [did:web 27 | specification](https://w3c-ccg.github.io/did-method-web/#in-transit-security) 28 | regarding the encryption of traffic between the server and client should be 29 | followed. 30 | 31 | ### International Domain Names 32 | 33 | [[spec:DID-CORE]] identifier syntax does not allow Unicode in method name nor 34 | method specific identifiers. 35 | 36 | Implementers should be cautious when implementing support for DID URLs that rely 37 | on domain names or path components that contain Unicode characters. 38 | 39 | See also: 40 | 41 | - [UTS-46](https://unicode.org/reports/tr46/) 42 | - [[spec:RFC5895]] 43 | -------------------------------------------------------------------------------- /spec-v0.4/version.md: -------------------------------------------------------------------------------- 1 | ## `did:tdw` Version Changelog 2 | 3 | The following lists the substantive changes in each version of the specification. 4 | 5 | - Version 0.4 6 | - Removes large non-normative sections, such as the implementer's guide, as they are now published on the [https://didtdw.org/](https://didtdw.org/) information site. 7 | - Removes the use of JSON Patch from the specification. The full DIDDoc is included in each [[ref: DID log entry]]. 8 | - Changes the data format of the [[ref: DID log entries]] from an array to an object. The [[ref: DID Log]] remains in the [[ref: JSON Lines]] format. 9 | - Changes the [[ref: DID log entry]] array to be named JSON objects or properties. 10 | - Makes each DID version's [[ref: Data Integrity]] proof apply across the JSON 11 | [[ref: DID log entry]] object, as is typical with [[ref: DID Integrity 12 | Proofs]]. Previously, the [[ref: Data Integrity]] proof was generated across 13 | the current DIDDoc version, with the `versionId` as the challenge. 14 | - Specified that the `versionTime` must be recorded as a UTC time zone timestamp. 15 | - Version 0.3 16 | - Removes the `cryptosuite` [[ref: parameter]], moving it to implied based on the `method` [[ref: parameter]]. 17 | - Change base32 encoding with [[ref: base58btc]], as it offers a better expansion rate. 18 | - Remove the step to extract part of the [[ref: base58btc]] result during the generation of the [[ref: SCID]]. 19 | - Use [[ref: multihash]] in the [[ref: SCID]] to differentiate the different hash function outputs. 20 | - Version 0.2 21 | - Changes the location of the [[ref: SCID]] in the DID to always be the first 22 | component after the DID Method prefix -- `did:tdw::...`. 23 | - Adds the [[ref: parameter]] `portable` to enable the capability to move a 24 | `did:tdw` during the creation of the DID. 25 | - Removes the first two [[ref: Log Entry]] items `entryHash` and `versionId` 26 | and replacing them with the new `versionId` as the first item in each [[ref: log 27 | entry]]. The new versionId takes the form `-`, 28 | where `` is the incrementing integer of version of the 29 | entry: 1, 2, 3, etc. 30 | - The `/whois` media type is changed to `application/vp` and the file is 31 | changed to `whois.vp` to match the IANA registration of a [[ref: Verifiable 32 | Presentation]]. 33 | -------------------------------------------------------------------------------- /spec-v0.5/abstract.md: -------------------------------------------------------------------------------- 1 | ## Abstract 2 | 3 | DID Web + Verifiable History (`did:webvh`) is an enhancement to the [[ref: did:web]] DID method, 4 | providing complementary features that address `did:web`'s 5 | limitations as a long-lasting DID. `did:webvh` features include: 6 | 7 | - The same DID-to-HTTPS transformation as `did:web`. 8 | - Ongoing publishing of the full history of the DID, including all of the DID 9 | Document ([[ref: DIDDoc]]) versions instead of, or alongside an existing 10 | `did:web` DIDDoc. 11 | - The ability to resolve the full history of the DID using a verifiable chain of 12 | updates to the [[ref: DIDDoc]] from genesis to deactivation. 13 | - A [[ref: self-certifying identifier]] (SCID) for the DID. The [[ref: SCID]], globally unique and 14 | embedded in the DID, is derived from the initial [[ref: DID log entry]]. It ensures the integrity 15 | of the DID's history mitigating the risk of attackers creating a new object with 16 | the same identifier. 17 | - An optional mechanism for enabling [[ref: DID portability]] via the [[ref: SCID]], allowing 18 | the DID's web location to be moved and the DID string to be updated, both while retaining 19 | a connection to the predecessor DID(s) and preserving the DID's verifiable history. 20 | - [[ref: DIDDoc]] updates contain a proof signed by the [[ref: DID Controller's]] *authorized* to 21 | update the DID. 22 | - An optional mechanism for publishing "pre-rotation" keys to prevent the loss of 23 | control of a DID in cases where an active private key is compromised. 24 | - An optional mechanism for having collaborating [[ref: witnesses]] 25 | that approve of updates to the DID by a [[ref: DID Controller]] before publication. 26 | - Supports the same [High Assurance DIDs with DNS] mechanism. 27 | - DID URL path handling that defaults (but can be overridden) to automatically 28 | resolving `/path/to/file` by using a comparable DID-to-HTTPS translation 29 | as for the [[ref: DIDDoc]]. 30 | - A DID URL path `/whois` that defaults to automatically returning (if 31 | published by the [[ref: DID controller]]) a [[ref: Verifiable Presentation]] 32 | containing [[ref: Verifiable Credentials]] with the DID as the 33 | `credentialSubject`, signed by the DID. It draws inspiration from the 34 | traditional WHOIS protocol [[spec:rfc3912]], offering an easy-to-use, 35 | decentralized, trust registry. 36 | 37 | [High Assurance DIDs with DNS]: https://datatracker.ietf.org/doc/draft-carter-high-assurance-dids-with-dns/ 38 | 39 | Combined, the additional features enable greater trust, security and verifiability without 40 | compromising the simplicity of `did:web`. 41 | 42 | For information beyond this specification about the (`did:webvh`) DID method and how (and 43 | where) it is used in practice, please visit 44 | [https://didwebvh.info/](https://didwebvh.info/) 45 | -------------------------------------------------------------------------------- /spec-v0.5/definitions.md: -------------------------------------------------------------------------------- 1 | ## Definitions 2 | 3 | [[def: base58btc]] 4 | 5 | ~ Applies [[spec:draft-msporny-base58-03]] to convert 6 | data to a `base58` encoding. Used in `did:webvh` for encoding hashes for [[ref: SCIDs]] and [[ref: entry hashes]]. 7 | 8 | [[def: Data Integrity]] 9 | 10 | ~ [W3C Data 11 | Integrity](https://www.w3.org/community/reports/credentials/CG-FINAL-data-integrity-20220722/) 12 | is a specification of mechanisms for ensuring the authenticity and integrity of 13 | structured digital documents using cryptography, such as digital signatures and 14 | other digital mathematical proofs. 15 | 16 | [[def: Decentralized Identifier, Decentralized Identifiers, DID, DIDs]] 17 | 18 | ~ Decentralized Identifiers (DIDs) [[spec:did-core]] are a type of identifier that enable 19 | verifiable, decentralized digital identities. A DID refers to any subject (e.g., 20 | a person, organization, thing, data model, abstract entity, etc.) as determined 21 | by the controller of the DID. 22 | 23 | [[def: DID Controller, DID Controller's, DID Controllers]] 24 | 25 | ~ The entity that controls (create, updates, deletes) a given DID, as defined 26 | in the [[spec:DID-CORE]]. 27 | 28 | [[def: DIDDoc]] 29 | 30 | ~ A DID Document as defined by the [[spec: DID-Core]] -- the document returned when a DID is resolved. 31 | 32 | [[def: DID Log, DID Logs]] 33 | 34 | ~ A DID Log is a list of [[ref: Entries]], with an entry added for each update of the DID, 35 | including new versions of the [[ref: DIDDoc]] or changed information necessary to generate or validate the DID. 36 | 37 | [[def: DID Log Entry, DID Log Entries, Entries, Log Entries, Log Entry]] 38 | 39 | ~ A DID Log Entry is a JSON object that defines the authorized 40 | transformation of a [[ref: DIDDoc]] from one version to the next. The initial entry 41 | establishes the DID and version 1 of the [[ref: DIDDoc]]. All entries are stored 42 | in the [[ref: DID Log]]. 43 | 44 | [[def: DID Method, DID Methods]] 45 | 46 | ~ DID methods are the mechanism by which a particular type of DID and its 47 | associated DID document are created, resolved, updated, and deactivated. DID 48 | methods are defined using separate DID method specifications. This document is 49 | the DID Method Specification for `did:webvh`. 50 | 51 | [[def: DID Portability, did:webvh portability, `did:webvh` portability, portability]] 52 | 53 | ~ `did:webvh` portability is the capability to change the DID string for the 54 | DID while retaining the [[ref: SCID]] and the history of the DID. This is useful 55 | when forced to change (such as when an organization is acquired by another, 56 | resulting in a change of domain names) and when changing DID hosting service 57 | providers. 58 | 59 | [[def: did:web]] 60 | 61 | ~ `did:web` as described in the [W3C specification](https://w3c-ccg.github.io/did-method-web/) 62 | is a DID method that leverages the Domain Name System (DNS) to perform the DID operations. 63 | It is valued for its simplicity and ease of deployment compared to [[ref: DID methods]] that are 64 | based on distributed ledgers or blockchain technology, but also comes with increased 65 | challenges related to trust, security and verifiability. `did:web` provides a starting point for `did:webvh`, 66 | which complements `did:web` with specific features to address its challenges 67 | while still providing ease of deployment. 68 | 69 | [[def: eddsa-jcs-2022]] 70 | 71 | ~ A cryptosuite defined for producing a [[ref: Data Integrity]] proof for an 72 | unsecured input data document and verifying the [[ref: Data Integrity]] proof of 73 | the secured document. More information on further operations and applications of 74 | the cryptosuite can be found in the specification, here: 75 | [eddsa-jcs-2022](https://www.w3.org/TR/vc-di-eddsa/#eddsa-jcs-2022) 76 | 77 | [[def: Entry Hash, entryHash, entry hashes]] 78 | 79 | ~ A `did:webvh` entry hash is a hash generated using a formally defined process 80 | over the input data to a [[ref: log entry]], excluding the [[ref: Data Integrity]] 81 | proof. The input data includes content from the predecessor to the 82 | version of the DID, ensuring that all the versions are "chained" together in a 83 | sort of microledger. The generated [[ref: entry hash]] is subsequently included in the 84 | `versionId` of the [[ref: log entry]] and **MUST** be verified by a 85 | resolver. 86 | 87 | [[def: ISO8601, ISO8601 String]] 88 | 89 | ~ A date/time expressed using the [ISO8601 90 | Standard](https://en.wikipedia.org/wiki/ISO_8601). 91 | 92 | [[def: JSON Canonicalization Scheme]] 93 | 94 | ~ [[spec:rfc8785]] defines a method for canonicalizing a JSON 95 | structure such that is suitable for verifiable hashing or signing. 96 | 97 | [[def: JSON Lines, JSON Line]] 98 | 99 | ~ A file of JSON Lines, as described on the site 100 | [https://jsonlines.org/](https://jsonlines.org/). In short, `JSONL` is lines of JSON with 101 | whitespace removed and separated by a newline that is convenient for handling 102 | streaming JSON data or log files. 103 | 104 | [[def: Pre-Rotation, Key Pre-Rotation]] 105 | 106 | ~ A technique for a controller of a cryptographic key to commit to the public 107 | key it will rotate to next, without exposing that actual public key. It protects 108 | from an attacker that gains knowledge of the current private key from being 109 | able to rotate to a new key known only to the attacker. 110 | 111 | [[def: Linked-VP, Linked Verifiable Presentation]] 112 | 113 | ~ A [[spec:DID-CORE]] `service` entry that specifies where a [[ref: verifiable presentation]] 114 | about the DID subject can be found. The [Decentralized Identity 115 | Foundation](https://identity.foundation/) hosts the [Linked VP 116 | Specification](https://identity.foundation/linked-vp/). 117 | 118 | [[def: multibase]] 119 | 120 | ~ A specification for encoding binary data as a string using a prefix that 121 | indicates the encoding. 122 | 123 | [[def: multikey]] 124 | 125 | ~ A verification method that encodes key types into a single binary stream that 126 | is then encoded as a [[ref: multibase]] value. 127 | 128 | [[def: multihash]] 129 | 130 | ~ Per the [[spec:multiformats]], [[ref: multihash]] is a specification 131 | for differentiating instances of hashes. Software creating a hash prefixes 132 | (according to the specification) data to the hash indicating the algorithm used 133 | and the length of the hash, so that software receiving the hash knows how to 134 | verify it. Although [[ref: multihash]] supports many hash algorithms, for 135 | interoperability, [[ref: DID Controllers]] **MUST** only use the hash algorithms defined 136 | in this specification as permitted. 137 | 138 | [[def: parameters, parameter]] 139 | 140 | ~ `did:webvh` parameters are a defined set of configurations that control how the 141 | issuer has generated the DID, and how the resolver must process the DID [[ref: 142 | Log entries]]. The use of parameters allows for the controlled evolution of 143 | `did:webvh` log handling, such as evolving the set of permitted hash algorithms or 144 | cryptosuites. This enables support for very long lasting identifiers -- decades. 145 | 146 | [[def: self-certifying identifier, self-certifying identifiers, SCID, SCIDs]] 147 | 148 | ~ An object identifier derived from initial data such that an attacker could not 149 | create a new object with the same identifier. The input for a `did:webvh` SCID is 150 | the initial [[ref: DIDDoc]] with the placeholder `{SCID}` wherever the SCID is to be 151 | placed. 152 | 153 | [[def: Verifiable Credential, Verifiable Credentials]] 154 | 155 | ~ A verifiable credential can represent all of the same information that a physical credential represents, adding technologies such as digital signatures, to make the credentials more tamper-evident and so more trustworthy than their physical counterparts. The [Verifiable Credential Data Model](https://www.w3.org/TR/vc-data-model/) is a W3C Standard. 156 | 157 | [[def: Verifiable Presentation, Verifiable Presentations]] 158 | 159 | ~ A [[ref: verifiable presentation]] data model is part W3C's [Verifiable Credential Data 160 | Model](https://www.w3.org/TR/vc-data-model/) that contains a set of [[ref: 161 | verifiable credentials]] about a `credentialSubject`, and a signature across the 162 | verifiable credentials generated by that subject. In this specification, the use 163 | case of primary interest is where the DID is the `credentialSubject` and the DID 164 | signs the [[ref: verifiable presentation]]. 165 | 166 | [[def: witness, witnesses, witnessed]] 167 | 168 | ~ Witnesses are participants in the process of creating and verifying a version 169 | of a `did:webvh` [[ref: DIDDoc]]. Notably, a witness receives from the [[ref: DID Controller]] a [[ref: DID 170 | Log]] entry ready for publication, verifies it according to this specification, 171 | and approves it according to its ecosystem governance (whatever that might be). If the verification and 172 | approval process results are positive, witnesses returns to the DID Controller a [[ref: Data Integrity]] proof 173 | attesting to that positive result. 174 | 175 | [[def: threshold, witness threshold]] 176 | 177 | ~ An algorithm that defines when a sufficient number of [[ref: witnesses]] have 178 | submitted valid [[ref: Data Integrity]] proofs for a [[ref: DID Log entry]] such 179 | that it is approved and can be published. The algorithm details are in the 180 | [Witness Threshold Algorithm](#witness-threshold-algorithm) section of this 181 | specification. 182 | 183 | [[def: W3C VCDM]] 184 | 185 | ~ A Verifiable Credential that uses the Data Model defined by the W3C [[spec: W3C-VC]] specification. 186 | -------------------------------------------------------------------------------- /spec-v0.5/header.md: -------------------------------------------------------------------------------- 1 | The `did:webvh` DID Method v0.5 2 | ================== 3 | 4 | ![did:webvh Logo](https://raw.githubusercontent.com/decentralized-identity/didwebvh/refs/heads/main/didwebvh.jpg) 5 | 6 | **Specification Status:** HISTORICAL -- **THIS IS NOT THE CURRENT VERSION OF THE SPECIFICATION** 7 | 8 | **Specification Version:** v0.5 (see [Changelog](#didtdw-version-changelog)) 9 | 10 | With this version of the specification the DID Method hame is changed to 11 | `did:webvh` ("`did:web` + Verifiable History"). It used to be named `did:tdw`. 12 | 13 | **Latest Version:** 14 | 15 | - Specification: [https://identity.foundation/didwebvh/](../) 16 | - Repository: [https://github.com/decentralized-identity/didwebvh](https://github.com/decentralized-identity/didwebvh) 17 | 18 | **Source For This Version:** 19 | [https://github.com/decentralized-identity/didwebvh/tree/main/spec-v0.5](https://github.com/decentralized-identity/didwebvh/tree/main/spec-v0.5) 20 | 21 | **Previous Versions:** 22 | - [v0.4](./v0.4) 23 | - [v0.3](./v0.3) 24 | 25 | **Information Site:** 26 | [https://didwebvh.info/](https://didwebvh.info/) 27 | 28 | **Editors:** 29 | ~ [Stephen Curran](https://github.com/swcurran) 30 | ~ [John Jordan, BC Gov](https://github.com/jljordan42) 31 | ~ [Andrew Whitehead](https://github.com/andrewwhitehead) 32 | ~ [Brian Richter](https://github.com/brianorwhatever) 33 | ~ [Michel Sahli](https://github.com/bj-ms) 34 | ~ [Martina Kolpondinos](https://github.com/martipos) 35 | ~ [Dmitri Zagdulin](https://github.com/dmitrizagidulin) 36 | 37 | **Participate:** 38 | ~ [GitHub repo](https://github.com/decentralized-identity/didwebvh) 39 | ~ [File a bug](https://github.com/decentralized-identity/didwebvh/issues) 40 | ~ [Commit history](https://github.com/decentralized-identity/didwebvh/commits/main) 41 | 42 | **Implementations:** 43 | ~ [TypeScript] 44 | ~ [Python] 45 | ~ [Go] 46 | ~ [did:webvh Server in Python] 47 | 48 | [TypeScript]: https://github.com/decentralized-identity/didwebvh-ts 49 | [Python]: https://github.com/decentralized-identity/didwebvh-py 50 | [Go]: https://github.com/nuts-foundation/didwebvh-go 51 | [did:webvh Server in Python]: https://github.com/decentralized-identity/didwebvh-server-py 52 | 53 | ------------------------------------ 54 | -------------------------------------------------------------------------------- /spec-v0.5/overview.md: -------------------------------------------------------------------------------- 1 | ## Overview 2 | 3 | The emergence of [[ref: Decentralized Identifiers]] (DIDs) and with them the 4 | evolution of [[ref: DID Methods]] continues to be a dynamic area of 5 | development in the quest for trusted, secure and private digital identity 6 | management where the users are in control of their own data. 7 | 8 | The `did:web` method, for example, leverages the Domain Name System (DNS) to 9 | perform the DID operations. This approach is praised for its simplicity and 10 | ease of deployment, including DID-to-HTTPS transformation and addressing 11 | some aspects of trust by allowing for DIDs to be associated with a domain's 12 | reputation or published on platforms such as GitHub. However, it is not 13 | without its challenges-- 14 | from trust layers inherited from the web and the absence of a verifiable 15 | history for the DID. 16 | 17 | Tackling these concerns, the `did:webvh` (`did:web` + Verifiable History) DID 18 | Method aims to enhance `did:web` by introducing features such as a [[ref: 19 | self-certifying identifiers]] (SCIDs), update key(s) and a verifiable history, 20 | akin to what is available with ledger-based DIDs, but without relying on a 21 | ledger. 22 | 23 | This approach not only maintains backward compatibility but also offers an 24 | additional layer of assurance for those requiring more robust verification 25 | processes. By publishing the resulting DID as both `did:web` and `did:webvh`, it 26 | caters to a broader range of trust requirements, from those who are comfortable 27 | with the existing `did:web` infrastructure to those seeking greater security 28 | assurances provided by `did:webvh`. This innovative step represents a significant 29 | stride towards a more trusted and secure web, where the integrity of 30 | cryptographic key publishing is paramount. 31 | 32 | The key differences between `did:web` and `did:webvh` revolve around the core 33 | issues of decentralization and security. `did:web` is recognized for its 34 | simplicity and cost-effectiveness, allowing for easy establishment of a 35 | credential ecosystem. However, it is not inherently decentralized as it relies 36 | on DNS domain names, which require centralized registries. Furthermore, it lacks a 37 | cryptographically verifiable, tamper-resistant, and persistently stored DID 38 | document. In contrast, `did:webvh` is an enhancement 39 | to `did:web`, aiming to address these limitations by adding a verifiable history 40 | to the DID without the need for a ledger. This method provides a more 41 | decentralized approach by ensuring that the security of the embedded 42 | SCID does not depend on DNS. `did:webvh` is 43 | capable of resolving a cryptographically verifiable trust registry and status 44 | lists, using DID-Linked Resources, which `did:web` lacks. These features are 45 | designed to build a trusted web by offering a higher level of assurance for 46 | cryptographic key publishing and management. 47 | 48 | For backwards compatibility, and for verifiers that "trust" `did:web`, a 49 | `did:webvh` can be trivially modified and published with a parallel `did:web` 50 | DID. For resolvers that want more assurance, `did:webvh` provides a way to 51 | verify a did:web using the features listed in the [Abstract](#abstract). 52 | 53 | The following is a `tl;dr` summary of how `did:webvh` works: 54 | 55 | 1. `did:webvh` uses the same DID-to-HTTPS transformation as `did:web`, so 56 | `did:webvh`'s `did.jsonl` ([[ref: JSON Lines]]) file is found in the same 57 | location as `did:web`'s `did.json` file, and supports an easy transition 58 | from `did:web` to gain the added benefits of `did:webvh`. 59 | 2. The `did.jsonl` is a list of JSON [[ref: DID log entries]], one per line, 60 | whitespace removed (per [[ref: JSON Lines]]). Each entry contains the 61 | information needed to derive a version of the [[ref: DIDDoc]] from its preceding 62 | version. The `did.jsonl` is also referred to as the [[ref: DID Log]]. 63 | 3. Each [[ref: DID log entry]] is a JSON object containing the following properties: 64 | 1. `versionId` -- a value that combines the version number 65 | (starting at `1` and incremented by one per version), a literal dash 66 | `-`, and a hash of the entry. The [[ref: entry hash]] calculation links each entry 67 | to its predecessor in a ledger-like chain. 68 | 2. `versionTime` -- as asserted by the [[ref: DID Controller]]. 69 | 3. `parameters` -- a set of [[ref: parameters]] that impact the processing of the current and 70 | future [[ref: log entries]]. 71 | - Example [[ref: parameters]] are the version of the `did:webvh` specification and 72 | hash algorithm being used, as well as the [[ref: SCID]] and update key(s). 73 | 4. `state` -- the new version of the [[ref: DIDDoc]]. 74 | 5. A [[ref: Data Integrity]] (DI) proof across the entry, signed by a [[ref: 75 | DID Controller]]-authorized key to update the [[ref: DIDDoc]]. 76 | 6. If the [[ref: DID Controller]] enables support for DID [[witnesses]], an 77 | extra file (`did-witness.json`) in the same web location contains [[ref: 78 | Data Integrity]] proofs from witness for [[ref: DID Log entries]]. 79 | 4. In generating the first version of the [[ref: DIDDoc]], the [[ref: DID 80 | Controller]] calculates the [[ref: SCID]] for the DID from the first [[ref: 81 | log entry]] (which includes the [[ref: DIDDoc]]). This is done by using the 82 | string `"{SCID}"` everywhere the actual [[ref: SCID]] is to be placed in order 83 | to generate the hash. The [[ref: DID Controller]] then replaces the 84 | placeholders with the calculated [[ref: SCID]], including it as a `parameter` 85 | in the first [[ref: log entry]], and inserting it where needed in the initial 86 | (and all subsequent) DIDDocs. The [[ref: SCID]] must be verified by the 87 | resolvers, to verify that the inception event has not been tampered with. The 88 | [[ref: SCID]] also enables an optional [[ref: portability]] capability, 89 | allowing a DID's web location to be moved, while retaining the [[ref: SCID]] and verifiable 90 | history of the identifier. 91 | 5. A [[ref: DID Controller]] generates and publishes the new/updated [[ref: DID Log]] file by making it 92 | available at the appropriate location on the web, based on the DID's identifier. 93 | 6. Given a `did:webvh` DID, a resolver converts the DID to an HTTPS URL, 94 | retrieves, and processes the [[ref: DID Log]] `did.jsonl` file, generating and verifying 95 | each [[ref: log entry]] as per the requirements outlined in this specification. 96 | - In the process, the resolver collects all the [[ref: DIDDoc]] versions and public 97 | keys used by the DID currently, and in the past. This enables 98 | resolving both current and past versions of the DID and keys. 99 | 7. `did:webvh` DID URLs with paths and `/whois` are resolved to documents 100 | published by the [[ref: DID Controller]] that are by default in the web location relative to the 101 | `did.jsonl` file. See the [note below](#the-whois-use-case) about the 102 | powerful capability enabled by the `/whois` DID URL path. 103 | 8. A [[ref: DID Controller]] can easily generate and publish a `did:web` DIDDoc 104 | from the latest `did:webvh` [[ref: DIDDoc]] in parallel with the `did:webvh` [[ref: DID Log]]. 105 | 106 | ::: warning 107 | A resolver settling for just the `did:web` version of the DID does not get the 108 | verifiability of the `did:webvh` log. 109 | ::: 110 | 111 | An example of a `did:webvh` evolving through a series of versions can be seen in 112 | the [`did:webvh` Examples](https://didwebvh.info/latest/example/) on the `did:webvh` 113 | information site. 114 | 115 | ### The `/whois` Use Case 116 | 117 | The `did:webvh` DID Method introduces what we hope will be a widely embraced convention for 118 | all [[ref: DID Methods]] -- the `/whois` path. This feature harkens back to the `WHOIS` 119 | protocol that was created in the 1970s to provide a directory about people and 120 | entities in the early days of ARPANET. In the 80's, `whois` evolved into 121 | [[spec-inform:rfc920]] that has expanded into the [global 122 | whois](https://en.wikipedia.org/wiki/WHOIS) feature we know today as 123 | [[spec-inform:rfc3912]]. Submit a `whois` request about a domain name, and get 124 | back the information published about that domain. 125 | 126 | We propose that the `/whois` path for a DID enable a comparable, decentralized, 127 | version of the `WHOIS` protocol for DIDs. Notably, when `/whois` is 128 | resolved (using a standard DID `service` that follows the [[ref: Linked-VP]] 129 | specification), a [[ref: Verifiable Presentation]] (VP) may be returned (if 130 | published by the [[ref: DID Controller]]) containing [[ref: Verifiable Credentials]] with 131 | the DID as the `credentialSubject`, and the VP signed by the DID. Given a DID, 132 | one can gather verifiable data about the [[ref: DID Controller]] by resolving 133 | `/whois` and processing the returned VP. That's powerful -- an efficient, 134 | highly decentralized, trust registry. For `did:webvh`, the approach is very simple 135 | -- transform the DID to its HTTPS equivalent, and execute a `GET /whois`. 136 | Need to know who issued the VCs in the VP? Get the issuer DIDs from those VCs, 137 | and resolve `/whois` for each. This is comparable to walking a CA 138 | (Certificate Authority) hierarchy, but self-managed by the [[ref: DID Controllers]] -- 139 | and the issuers that attest to them. 140 | 141 | The following is a use case for the `/whois` capability. Consider an example of 142 | the `did:webvh` controller being a mining company that has exported a shipment and 143 | created a "Product Passport" Verifiable Credential with information about the 144 | shipment. A country importing the shipment (the Importer) might want to know 145 | more about the issuer of the VC, and hence, the details of the shipment. They 146 | resolve the `/whois` of the entity and get back a Verifiable Presentation 147 | about that DID. It might contain: 148 | 149 | - A verifiable credential issued by the Legal Entity Registrar for the 150 | jurisdiction in which the mining company is headquartered. 151 | - Since the Importer knows about the Legal Entity Registrar, they can automate 152 | this lookup to get more information about the company from the VC -- its 153 | legal name, when it was registered, contact information, etc. 154 | - A verifiable credential for a "Mining Permit" issued by the mining authority 155 | for the jurisdiction in which the company operates. 156 | - Perhaps the Importer does not know about the mining authority for that 157 | jurisdiction. The Importer can repeat the `/whois` resolution process for 158 | the issuer of _that_ credential. The Importer might (for example), resolve 159 | and verify the `did:webvh` DID for the Authority, and then resolve the 160 | `/whois` DID URL to find a verifiable credential issued by the government of 161 | the jurisdiction. The Importer recognizes and trusts that government's 162 | authority, and so can decide to recognize and trust the mining permit 163 | authority. 164 | - A verifiable credential about the auditing of the mining practices of the 165 | mining company. Again, the Importer doesn't know about the issuer of the audit 166 | VC, so they resolve the `/whois` for the DID of the issuer, get its VP and 167 | find that it is accredited to audit mining companies by the [London Metal 168 | Exchange](https://www.lme.com/en/) according to one of its mining standards. 169 | As the Importer knows about both the London Metal Exchange and the standard, 170 | it can make a trust decision about the original Product Passport Verifiable 171 | Credential. 172 | 173 | Such checks can all be done with a handful of HTTPS requests and the processing 174 | of the DIDs and verifiable presentations. If the system cannot automatically 175 | make a trust decision, lots of information has been quickly collected that can 176 | be passed to a person to make such a decision. 177 | 178 | The result is an efficient, verifiable, credential-based, decentralized, 179 | multi-domain trust registry, empowering individuals and organizations to verify 180 | the authenticity and legitimacy of DIDs. The convention promotes a decentralized 181 | trust model where trust is established through cryptographic verification rather 182 | than reliance on centralized authorities. By enabling anyone to access and 183 | validate the information associated with a DID, the "/whois" path contributes to 184 | the overall security and integrity of decentralized networks. 185 | -------------------------------------------------------------------------------- /spec-v0.5/references.md: -------------------------------------------------------------------------------- 1 | ## References 2 | 3 | [[spec]] 4 | -------------------------------------------------------------------------------- /spec-v0.5/security_and_privacy.md: -------------------------------------------------------------------------------- 1 | ## Security and Privacy Considerations 2 | 3 | ### DNS Considerations 4 | 5 | #### DNS Security Considerations 6 | 7 | Implementers must secure DNS resolution to protect against attacks like Man in 8 | the Middle, following the detailed guidance in the [did:web 9 | specification](https://w3c-ccg.github.io/did-method-web/#dns-considerations). 10 | The use of DNSSEC [[spec:RFC4033]], [[spec:RFC4034]], [[spec:RFC4035]] is 11 | essential to prevent spoofing and ensure authenticity of DNS records. 12 | 13 | #### DNS Privacy Considerations 14 | 15 | Resolving a `did:webvh` identifier can expose users to tracking by DNS providers 16 | and web servers. To mitigate this risk, it's recommended to use privacy-enhancing 17 | technologies such as VPNs, TOR, or trusted universal resolver services, in line 18 | with strategies outlined in the [did:web 19 | specification](https://w3c-ccg.github.io/did-method-web/#dns-considerations) 20 | including emerging RFCs such as [Oblivious DNS over 21 | HTTPS](https://datatracker.ietf.org/doc/html/draft-pauly-dprive-oblivious-doh-03) 22 | for DNS privacy. 23 | 24 | ### In-transit Security 25 | 26 | For in-transit security, the guidance provided in the [did:web 27 | specification](https://w3c-ccg.github.io/did-method-web/#in-transit-security) 28 | regarding the encryption of traffic between the server and client should be 29 | followed. 30 | 31 | ### International Domain Names 32 | 33 | [[spec:DID-CORE]] identifier syntax does not allow Unicode in method name nor 34 | method specific identifiers. 35 | 36 | Implementers should be cautious when implementing support for DID URLs that rely 37 | on domain names or path components that contain Unicode characters. 38 | 39 | See also: 40 | 41 | - [UTS-46](https://unicode.org/reports/tr46/) 42 | - [[spec:RFC5895]] 43 | 44 | ### Cross-Origin Resource Sharing (CORS) Policy Considerations 45 | 46 | To support scenarios where DID resolution is performed by client applications running in a web browser, the file served for the [[ref: DID Log]] needs to be accessible by any origin. To enable this, the [[ref: DID Log]] HTTP response MUST include the following header: 47 | 48 | `Access-Control-Allow-Origin: *` 49 | -------------------------------------------------------------------------------- /spec-v0.5/version.md: -------------------------------------------------------------------------------- 1 | ## `did:webvh` Version Changelog 2 | 3 | The following lists the substantive changes in each version of the specification. 4 | 5 | - Version 0.5 6 | - Remove the `prerotation` parameter. The feature is automatically enforced 7 | when `nextKeyHashes` is present. 8 | - Clarify the way the [[ref: Pre-Rotation]] feature works, once a `nextKeyHashes` 9 | is committed, the next [[ref: DID log entries]] has to be signed by one of the committed keys. 10 | - Clarify how to stop using [[ref: pre-rotation]], including when deactivating the DID. 11 | - Change the [[ref: witness]] handling by removing the witness [[ref: Data Integrity]] 12 | proofs from the [[ref: DID Log]] file and puts them into a separate file 13 | `did-witness.json`. Adjustments to the witness threshold algorithm were also 14 | made, such as removing the [[ref: DID Controllers]]' `selfweight` attribute, 15 | and defining that all witness DIDs must be `did:key` DIDs. 16 | - Clarify how to stop using witnesses. 17 | - Clarify the initialization values of [[ref: parameters]] and that array 18 | [[ref: parameters]] must use `null` and **not** use empty lists (`[]`) when 19 | not active. 20 | - Rename the DID Method to `did:webvh` (`did:web` + Verifiable History) 21 | - Move the DID Method information site to [https://didwebvh.info](https://didwebvh.info). 22 | - Version 0.4 23 | - Removes large non-normative sections, such as the implementer's guide, as they are now published on the [https://didtdw.org/](https://didtdw.org/) information site. 24 | - Removes the use of JSON Patch from the specification. The full DIDDoc is included in each [[ref: DID log entry]]. 25 | - Changes the data format of the [[ref: DID log entries]] from an array to an object. The [[ref: DID Log]] remains in the [[ref: JSON Lines]] format. 26 | - Changes the [[ref: DID log entry]] array to be named JSON objects or properties. 27 | - Makes each DID version's [[ref: Data Integrity]] proof apply across the JSON 28 | [[ref: DID log entry]] object, as is typical with [[ref: Data Integrity]] proofs. 29 | Previously, the [[ref: Data Integrity]] proof was generated across 30 | the current DIDDoc version, with the `versionId` as the challenge. 31 | - Specified that the `versionTime` must be recorded as a UTC time zone timestamp. 32 | - Version 0.3 33 | - Removes the `cryptosuite` [[ref: parameter]], moving it to implied based on the `method` [[ref: parameter]]. 34 | - Change base32 encoding with [[ref: base58btc]], as it offers a better expansion rate. 35 | - Remove the step to extract part of the [[ref: base58btc]] result during the generation of the [[ref: SCID]]. 36 | - Use [[ref: multihash]] in the [[ref: SCID]] to differentiate the different hash function outputs. 37 | - Version 0.2 38 | - Changes the location of the [[ref: SCID]] in the DID to always be the first 39 | component after the DID Method prefix -- `did:tdw::...`. 40 | - Adds the [[ref: parameter]] `portable` to enable the capability to move a 41 | `did:tdw` during the creation of the DID. 42 | - Removes the first two [[ref: Log Entry]] items `entryHash` and `versionId` 43 | and replacing them with the new `versionId` as the first item in each 44 | [[ref: log entry]]. The new versionId takes the form `-`, 45 | where `` is the incrementing integer of version of the 46 | entry: 1, 2, 3, etc. 47 | - The `/whois` media type is changed to `application/vp` and the file is 48 | changed to `whois.vp` to match the IANA registration of a [[ref: Verifiable Presentation]]. 49 | -------------------------------------------------------------------------------- /spec-v1.0/abstract.md: -------------------------------------------------------------------------------- 1 | ## Abstract 2 | 3 | DID Web + Verifiable History (`did:webvh`) is an enhancement to the [[ref: did:web]] DID method, 4 | providing complementary features that address `did:web`'s 5 | limitations as a long-lasting DID. `did:webvh` features include: 6 | 7 | - The same DID-to-HTTPS transformation as `did:web`. 8 | - Ongoing publishing of the full history of the DID, including all of the DID 9 | Document ([[ref: DIDDoc]]) versions instead of, or alongside an existing 10 | `did:web` DIDDoc. 11 | - The ability to resolve the full history of the DID using a verifiable chain of 12 | updates to the [[ref: DIDDoc]] from genesis to deactivation. 13 | - A [[ref: self-certifying identifier]] (SCID) for the DID. The [[ref: SCID]], globally unique and 14 | embedded in the DID, is derived from the initial [[ref: DID log entry]]. It ensures the integrity 15 | of the DID's history mitigating the risk of attackers creating a new object with 16 | the same identifier. 17 | - An optional mechanism for enabling [[ref: DID portability]] via the [[ref: SCID]], allowing 18 | the DID's web location to be moved and the DID string to be updated, both while retaining 19 | a connection to the predecessor DID(s) and preserving the DID's verifiable history. 20 | - [[ref: DIDDoc]] updates contain a proof signed by the [[ref: DID Controller's]] *authorized* to 21 | update the DID. 22 | - An optional mechanism for publishing "pre-rotation" keys to prevent the loss of 23 | control of a DID in cases where an active private key is compromised. 24 | - An optional mechanism for having collaborating [[ref: witnesses]] 25 | that approve of updates to the DID by a [[ref: DID Controller]] before publication. 26 | - Support for cryptographic agility through versioned specification upgrades, 27 | algorithm-identifying formats (e.g., [[ref: multihash]] and [[ref: Data Integrity]] proofs), and 28 | per-entry method parameters in the [[ref: DID log]] that enable DIDs to evolve 29 | cryptographically over time. 30 | - An optional mechanism for publishing the location of `did:webvh` [[ref: 31 | watchers]] in the [[ref: DID log]] that resolvers can use as another 32 | source DID data for long term resolution or detection of malicious [[ref: DID Controllers]]. 33 | - DID URL path handling that defaults (but can be overridden) to automatically 34 | resolving `/path/to/file` by using a comparable DID-to-HTTPS translation 35 | as for the [[ref: DIDDoc]]. 36 | - A DID URL path `/whois` that defaults to automatically returning (if 37 | published by the [[ref: DID controller]]) a [[ref: Verifiable Presentation]] 38 | containing [[ref: Verifiable Credentials]] with the DID as the 39 | `credentialSubject`, signed by the DID. It draws inspiration from the 40 | traditional WHOIS protocol [[spec:rfc3912]], offering an easy-to-use, 41 | decentralized, trust registry. 42 | 43 | Combined, the additional features enable greater trust, security and verifiability without 44 | compromising the simplicity of `did:web`. 45 | 46 | For information beyond this specification about the (`did:webvh`) DID method and how (and 47 | where) it is used in practice, please visit 48 | [https://didwebvh.info/](https://didwebvh.info/) 49 | -------------------------------------------------------------------------------- /spec-v1.0/definitions.md: -------------------------------------------------------------------------------- 1 | ## Definitions 2 | 3 | [[def: base58btc]] 4 | 5 | ~ Applies [[spec:draft-msporny-base58-03]] to convert 6 | data to a `base58` encoding. Used in `did:webvh` for encoding hashes for [[ref: SCIDs]] and [[ref: entry hashes]]. 7 | 8 | [[def: Data Integrity]] 9 | 10 | ~ [W3C Data 11 | Integrity](https://www.w3.org/community/reports/credentials/CG-FINAL-data-integrity-20220722/) 12 | is a specification of mechanisms for ensuring the authenticity and integrity of 13 | structured digital documents using cryptography, such as digital signatures and 14 | other digital mathematical proofs. 15 | 16 | [[def: Decentralized Identifier, Decentralized Identifiers, DID, DIDs]] 17 | 18 | ~ Decentralized Identifiers (DIDs) [[spec:did-core]] are a type of identifier that enable 19 | verifiable, decentralized digital identities. A DID refers to any subject (e.g., 20 | a person, organization, thing, data model, abstract entity, etc.) as determined 21 | by the controller of the DID. 22 | 23 | [[def: DID Controller, DID Controller's, DID Controllers]] 24 | 25 | ~ The entity that controls (create, updates, deletes) a given DID, as defined 26 | in the [[spec:DID-CORE]]. 27 | 28 | [[def: DIDDoc]] 29 | 30 | ~ A DID Document as defined by the [[spec: DID-Core]] -- the document returned when a DID is resolved. 31 | 32 | [[def: DID Log, DID Logs]] 33 | 34 | ~ A DID Log is a list of [[ref: Entries]], with an entry added for each update of the DID, 35 | including new versions of the [[ref: DIDDoc]] or changed information necessary to generate or validate the DID. 36 | 37 | [[def: DID Log Entry, DID Log Entries, Entries, Log Entries, Log Entry]] 38 | 39 | ~ A DID Log Entry is a JSON object that defines the authorized 40 | transformation of a [[ref: DIDDoc]] from one version to the next. The initial entry 41 | establishes the DID and version 1 of the [[ref: DIDDoc]]. All entries are stored 42 | in the [[ref: DID Log]]. 43 | 44 | [[def: DID Method, DID Methods]] 45 | 46 | ~ DID methods are the mechanism by which a particular type of DID and its 47 | associated DID document are created, resolved, updated, and deactivated. DID 48 | methods are defined using separate DID method specifications. This document is 49 | the DID Method Specification for `did:webvh`. 50 | 51 | [[def: DID Portability, did:webvh portability, `did:webvh` portability, portability]] 52 | 53 | ~ `did:webvh` portability is the capability to change the DID string for the 54 | DID while retaining the [[ref: SCID]] and the history of the DID. This is useful 55 | when forced to change (such as when an organization is acquired by another, 56 | resulting in a change of domain names) and when changing DID hosting service 57 | providers. 58 | 59 | [[def: DID Resources, DID Resource]] 60 | 61 | ~ A DID Resource is an object (often a file) that is referenced by a DID URL, with a path to the resource. The DID URL allows resolvers to locate and retrieve specific content associated with a DID. Examples include configuration files, schemas, credential definitions, or other structured data linked to the DID. 62 | 63 | [[def: did:web]] 64 | 65 | ~ `did:web` as described in the [W3C specification](https://w3c-ccg.github.io/did-method-web/) 66 | is a DID method that leverages the Domain Name System (DNS) to perform the DID operations. 67 | It is valued for its simplicity and ease of deployment compared to [[ref: DID methods]] that are 68 | based on distributed ledgers or blockchain technology, but also comes with increased 69 | challenges related to trust, security and verifiability. `did:web` provides a starting point for `did:webvh`, 70 | which complements `did:web` with specific features to address its challenges 71 | while still providing ease of deployment. 72 | 73 | [[def: Entry Hash, entryHash, entry hashes]] 74 | 75 | ~ A `did:webvh` entry hash is a hash generated using a formally defined process 76 | over the input data to a [[ref: log entry]], excluding the [[ref: Data Integrity]] 77 | proof. The input data includes content from the predecessor to the 78 | version of the DID, ensuring that all the versions are "chained" together in a 79 | sort of microledger. The generated [[ref: entry hash]] is subsequently included in the 80 | `versionId` of the [[ref: log entry]] and **MUST** be verified by a 81 | resolver. 82 | 83 | [[def: ISO8601, ISO8601 String]] 84 | 85 | ~ A date/time expressed using the [ISO8601 86 | Standard](https://en.wikipedia.org/wiki/ISO_8601). 87 | 88 | [[def: JSON Canonicalization Scheme]] 89 | 90 | ~ [[spec:rfc8785]] defines a method for canonicalizing a JSON 91 | structure such that is suitable for verifiable hashing or signing. 92 | 93 | [[def: JSON Lines, JSON Line]] 94 | 95 | ~ A file of JSON Lines, as described on the site 96 | [https://jsonlines.org/](https://jsonlines.org/). In short, `JSONL` is lines of JSON with 97 | whitespace removed and separated by a newline that is convenient for handling 98 | streaming JSON data or log files. 99 | 100 | [[def: Pre-Rotation, Key Pre-Rotation]] 101 | 102 | ~ A technique for a controller of a cryptographic key to commit to the public 103 | key it will rotate to next, without exposing that actual public key. It protects 104 | from an attacker that gains knowledge of the current private key from being 105 | able to rotate to a new key known only to the attacker. 106 | 107 | [[def: Linked-VP, Linked Verifiable Presentation]] 108 | 109 | ~ A [[spec:DID-CORE]] `service` entry that specifies where a [[ref: verifiable presentation]] 110 | about the DID subject can be found. The [Decentralized Identity 111 | Foundation](https://identity.foundation/) hosts the [Linked VP 112 | Specification](https://identity.foundation/linked-vp/). 113 | 114 | [[def: multibase]] 115 | 116 | ~ A specification for encoding binary data as a string using a prefix that 117 | indicates the encoding. 118 | 119 | [[def: multikey]] 120 | 121 | ~ A verification method that encodes key types into a single binary stream that 122 | is then encoded as a [[ref: multibase]] value. 123 | 124 | [[def: multihash]] 125 | 126 | ~ Per the [[spec:multiformats]], [[ref: multihash]] is a specification 127 | for differentiating instances of hashes. Software creating a hash prefixes 128 | (according to the specification) data to the hash indicating the algorithm used 129 | and the length of the hash, so that software receiving the hash knows how to 130 | verify it. Although [[ref: multihash]] supports many hash algorithms, for 131 | interoperability, [[ref: DID Controllers]] **MUST** only use the hash algorithms defined 132 | in this specification as permitted. 133 | 134 | [[def: parameters, parameter]] 135 | 136 | ~ `did:webvh` parameters are a defined set of configurations that control how the 137 | issuer has generated the DID, and how the resolver must process the DID [[ref: 138 | Log entries]]. The use of parameters allows for the controlled evolution of 139 | `did:webvh` log handling, such as evolving the set of permitted hash algorithms or 140 | cryptosuites. This enables support for very long lasting identifiers -- decades. 141 | 142 | [[def: self-certifying identifier, self-certifying identifiers, SCID, SCIDs]] 143 | 144 | ~ An object identifier derived from initial data such that an attacker could not 145 | create a new object with the same identifier. The input for a `did:webvh` SCID is 146 | the initial [[ref: DIDDoc]] with the placeholder `{SCID}` wherever the SCID is to be 147 | placed. 148 | 149 | [[def: Verifiable Credential, Verifiable Credentials]] 150 | 151 | ~ A verifiable credential can represent all of the same information that a physical credential represents, adding technologies such as digital signatures, to make the credentials more tamper-evident and so more trustworthy than their physical counterparts. The [Verifiable Credential Data Model](https://www.w3.org/TR/vc-data-model/) is a W3C Standard. 152 | 153 | [[def: Verifiable Presentation, Verifiable Presentations]] 154 | 155 | ~ A [[ref: verifiable presentation]] data model is part W3C's [Verifiable Credential Data 156 | Model](https://www.w3.org/TR/vc-data-model/) that contains a set of [[ref: 157 | verifiable credentials]] about a `credentialSubject`, and a signature across the 158 | verifiable credentials generated by that subject. In this specification, the use 159 | case of primary interest is where the DID is the `credentialSubject` and the DID 160 | signs the [[ref: verifiable presentation]]. 161 | 162 | [[def: watcher, watchers]] 163 | 164 | ~ Watchers are entities within a decentralized trust ecosystem that monitor Decentralized Identifiers (DIDs) for changes or updates on behalf of their clients. Watchers maintain a historical cache of DID document versions and verify that the [[ref: DID Controller]] is consistently following the prescribed evolution process. By ensuring integrity and traceability, watchers help foster trust among clients who rely on up-to-date and authentic DID information. `did:webvh` watchers provide endpoints for retrieving DID information and to receive [[ref: webhooks]] notifying the watcher about updates to the DID and deletion requests. 165 | 166 | [[def: webhook, webhooks]] 167 | 168 | ~ A webhook is a mechanism that enables real-time communication between systems by sending HTTP callbacks (typically POST requests) to a specified URL when an event occurs. Webhooks are commonly used for event-driven integrations and automation. Although webhooks are an implementation pattern rather than a formal standard, best practices are documented in [[spec:rfc8030]]. 169 | 170 | [[def: witness, witnesses, witnessed]] 171 | 172 | ~ Witnesses are participants in the process of creating and verifying a version 173 | of a `did:webvh` [[ref: DIDDoc]]. Notably, a witness receives from the [[ref: DID Controller]] a [[ref: DID 174 | Log]] entry ready for publication, verifies it according to this specification, 175 | and approves it according to its ecosystem governance (whatever that might be). If the verification and 176 | approval process results are positive, witnesses returns to the DID Controller a [[ref: Data Integrity]] proof 177 | attesting to that positive result. 178 | 179 | [[def: threshold, witness threshold]] 180 | 181 | ~ An algorithm that defines when a sufficient number of [[ref: witnesses]] have 182 | submitted valid [[ref: Data Integrity]] proofs for a [[ref: DID Log entry]] such 183 | that it is approved and can be published. The algorithm details are in the 184 | [Witness Threshold Algorithm](#witness-threshold-algorithm) section of this 185 | specification. 186 | 187 | [[def: W3C VCDM]] 188 | 189 | ~ A Verifiable Credential that uses the Data Model defined by the W3C [[spec: W3C-VC]] specification. 190 | -------------------------------------------------------------------------------- /spec-v1.0/header.md: -------------------------------------------------------------------------------- 1 | The `did:webvh` DID Method
v1.0 2 | ================== 3 | 4 | ![did:webvh Logo](https://raw.githubusercontent.com/decentralized-identity/didwebvh/refs/heads/main/didwebvh.jpg) 5 | 6 | **Specification Status:** v1.0 7 | 8 | This is the specification of the `did:webvh` DID Method, Version 1.0. Please note that we continue to make cleanups (e.g., fixing typos, broken links, missing references, etc.) and making wording clarifications in this version of the specification. With that work there will be no changes to the meaning of the specification. 9 | 10 | The current [Editor's Draft](../next) of the specification will be maintained in sync with this version as the cleanups and clarifications to v1.0 are made. When a change to the meaning of the specification is identified, the Editor's Draft synchronization with this version will be stopped, and this message will be updated. 11 | 12 | **Current Specification:** [v1.0](../) 13 | 14 | **Specification Version:** v1.0 (see [Changelog](#didwebvh-version-changelog)) 15 | 16 | **Source of Latest Draft:** 17 | [https://github.com/decentralized-identity/didwebvh](https://github.com/decentralized-identity/didwebvh) 18 | 19 | **Previous Versions:** 20 | 21 | - [v0.5](../v0.5) 22 | - [v0.4](../v0.4) 23 | - [v0.3](../v0.3) 24 | 25 | **Information Site:** 26 | [https://didwebvh.info/](https://didwebvh.info/) 27 | 28 | **Editors:** 29 | ~ [Stephen Curran](https://github.com/swcurran) 30 | ~ [John Jordan, BC Gov](https://github.com/jljordan42) 31 | ~ [Andrew Whitehead](https://github.com/andrewwhitehead) 32 | ~ [Brian Richter](https://github.com/brianorwhatever) 33 | ~ [Michel Sahli](https://github.com/bj-ms) 34 | ~ [Martina Kolpondinos](https://github.com/martipos) 35 | ~ [Dmitri Zagdulin](https://github.com/dmitrizagidulin) 36 | ~ [Alexander Shenshin](https://github.com/AlexanderShenshin) 37 | 38 | **Participate:** 39 | ~ [GitHub repo](https://github.com/decentralized-identity/didwebvh) 40 | ~ [File a bug](https://github.com/decentralized-identity/didwebvh/issues) 41 | ~ [Commit history](https://github.com/decentralized-identity/didwebvh/commits/main) 42 | 43 | **Implementations:** 44 | ~ [TypeScript] 45 | ~ [Python] 46 | ~ [Go] - supports v03 47 | ~ [Rust] - work in progress 48 | ~ [did:webvh Server] 49 | ~ [did:webvh ACA-Py Plugin] 50 | 51 | [TypeScript]: https://github.com/decentralized-identity/trustdidweb-ts 52 | [Python]: https://github.com/decentralized-identity/trustdidweb-py 53 | [Go]: https://github.com/nuts-foundation/trustdidweb-go 54 | [Rust]: https://github.com/decentralized-identity/didwebvh-rs 55 | [did:webvh Server]: https://github.com/decentralized-identity/trustdidweb-server-py 56 | [did:webvh ACA-Py Plugin]: https://plugins.aca-py.org/latest/webvh/ 57 | 58 | ------------------------------------ 59 | -------------------------------------------------------------------------------- /spec-v1.0/overview.md: -------------------------------------------------------------------------------- 1 | ## Overview 2 | 3 | The emergence of [[ref: Decentralized Identifiers]] (DIDs) and with them the 4 | evolution of [[ref: DID Methods]] continues to be a dynamic area of 5 | development in the quest for trusted, secure and private digital identity 6 | management where the users are in control of their own data. 7 | 8 | The `did:web` method, for example, leverages the Domain Name System (DNS) to 9 | perform the DID operations. This approach is praised for its simplicity and 10 | ease of deployment, including DID-to-HTTPS transformation and addressing 11 | some aspects of trust by allowing for DIDs to be associated with a domain's 12 | reputation or published on platforms such as GitHub. However, it is not 13 | without its challenges-- 14 | from trust layers inherited from the web and the absence of a verifiable 15 | history for the DID. 16 | 17 | Tackling these concerns, the `did:webvh` (`did:web` + Verifiable History) DID 18 | Method aims to enhance `did:web` by introducing features such as a [[ref: 19 | self-certifying identifiers]] (SCIDs), update key(s) and a verifiable history, 20 | akin to what is available with ledger-based DIDs, but without relying on a 21 | ledger. 22 | 23 | This approach not only maintains backward compatibility but also offers an 24 | additional layer of assurance for those requiring more robust verification 25 | processes. By publishing the resulting DID as both `did:web` and `did:webvh`, it 26 | caters to a broader range of trust requirements, from those who are comfortable 27 | with the existing `did:web` infrastructure to those seeking greater security 28 | assurances provided by `did:webvh`. This innovative step represents a significant 29 | stride towards a more trusted and secure web, where the integrity of 30 | cryptographic key publishing is paramount. 31 | 32 | The key differences between `did:web` and `did:webvh` revolve around the core 33 | issues of decentralization and security. `did:web` is recognized for its 34 | simplicity and cost-effectiveness, allowing for easy establishment of a 35 | credential ecosystem. However, it is not inherently decentralized as it relies 36 | on DNS domain names, which require centralized registries. Furthermore, it lacks a 37 | cryptographically verifiable, tamper-resistant, and persistently stored DID 38 | document. In contrast, `did:webvh` is an enhancement 39 | to `did:web`, aiming to address these limitations by adding a verifiable history 40 | to the DID without the need for a ledger. This method provides a more 41 | decentralized approach by ensuring that the security of the embedded 42 | SCID does not depend on DNS. `did:webvh` is 43 | capable of resolving a cryptographically verifiable trust registry and status 44 | lists, using DID-Linked Resources, which `did:web` lacks. These features are 45 | designed to build a trusted web by offering a higher level of assurance for 46 | cryptographic key publishing and management. 47 | 48 | For backwards compatibility, and for verifiers that "trust" `did:web`, a 49 | `did:webvh` can be trivially modified and published with a parallel `did:web` 50 | DID. For resolvers that want more assurance, `did:webvh` provides a way to 51 | verify a did:web using the features listed in the [Abstract](#abstract). 52 | 53 | The following is a `tl;dr` summary of how `did:webvh` works: 54 | 55 | 1. `did:webvh` uses the same DID-to-HTTPS transformation as `did:web`, so 56 | `did:webvh`'s `did.jsonl` ([[ref: JSON Lines]]) file is found in the same 57 | location as `did:web`'s `did.json` file, and supports an easy transition 58 | from `did:web` to gain the added benefits of `did:webvh`. 59 | 2. The `did.jsonl` is a list of JSON [[ref: DID log entries]], one per line, 60 | whitespace removed (per [[ref: JSON Lines]]). Each entry contains the 61 | information needed to derive a version of the [[ref: DIDDoc]] from its preceding 62 | version. The `did.jsonl` is also referred to as the [[ref: DID Log]]. 63 | 3. Each [[ref: DID log entry]] is a JSON object containing the following properties: 64 | 1. `versionId` -- a value that combines the version number 65 | (starting at `1` and incremented by one per version), a literal dash 66 | `-`, and a hash of the entry. The [[ref: entry hash]] calculation links each entry 67 | to its predecessor in a ledger-like chain. 68 | 2. `versionTime` -- as asserted by the [[ref: DID Controller]]. 69 | 3. `parameters` -- a set of [[ref: parameters]] that impact the processing of the current and 70 | future [[ref: log entries]]. 71 | - Example [[ref: parameters]] are the version of the `did:webvh` specification and 72 | hash algorithm being used, as well as the [[ref: SCID]] and update key(s). 73 | 4. `state` -- the new version of the [[ref: DIDDoc]]. 74 | 5. A [[ref: Data Integrity]] (DI) proof across the entry, signed by a [[ref: 75 | DID Controller]]-authorized key to update the [[ref: DIDDoc]]. 76 | 6. If the [[ref: DID Controller]] enables support for DID [[witnesses]], an 77 | extra file (`did-witness.json`) in the same web location contains [[ref: 78 | Data Integrity]] proofs from witness for [[ref: DID Log entries]]. 79 | 4. In generating the first version of the [[ref: DIDDoc]], the [[ref: DID 80 | Controller]] calculates the [[ref: SCID]] for the DID from the first [[ref: 81 | log entry]] (which includes the [[ref: DIDDoc]]). This is done by using the 82 | string `"{SCID}"` everywhere the actual [[ref: SCID]] is to be placed in order 83 | to generate the hash. The [[ref: DID Controller]] then replaces the 84 | placeholders with the calculated [[ref: SCID]], including it as a `parameter` 85 | in the first [[ref: log entry]], and inserting it where needed in the initial 86 | (and all subsequent) DIDDocs. The [[ref: SCID]] must be verified by the 87 | resolvers, to verify that the inception event has not been tampered with. The 88 | [[ref: SCID]] also enables an optional [[ref: portability]] capability, 89 | allowing a DID's web location to be moved, while retaining the [[ref: SCID]] and verifiable 90 | history of the identifier. 91 | 5. A [[ref: DID Controller]] generates and publishes the new/updated [[ref: DID 92 | Log]] file by making it available at the appropriate location on the web, 93 | based on the DID's identifier. If a `did:webvh` has [[ref: watchers]], a 94 | webhook is triggered to notify the [[ref: watchers]] that an update is 95 | available and should be retrieved. 96 | 6. Given a `did:webvh` DID, a resolver converts the DID to an HTTPS URL, 97 | retrieves, and processes the [[ref: DID Log]] `did.jsonl` file, generating and verifying 98 | each [[ref: log entry]] as per the requirements outlined in this specification. 99 | - In the process, the resolver collects all the [[ref: DIDDoc]] versions and public 100 | keys used by the DID currently, and in the past. This enables 101 | resolving both current and past versions of the DID and keys. 102 | 7. `did:webvh` DID URLs with paths and `/whois` are resolved to documents 103 | published by the [[ref: DID Controller]] that are by default in the web location relative to the 104 | `did.jsonl` file. See the [note below](#the-whois-use-case) about the 105 | powerful capability enabled by the `/whois` DID URL path. 106 | 8. A [[ref: DID Controller]] can easily generate and publish a `did:web` DIDDoc 107 | from the latest `did:webvh` [[ref: DIDDoc]] in parallel with the `did:webvh` [[ref: DID Log]]. 108 | 109 | ::: warning 110 | A resolver settling for just the `did:web` version of the DID does not get the 111 | verifiability of the `did:webvh` log. 112 | ::: 113 | 114 | An example of a `did:webvh` evolving through a series of versions can be seen in 115 | the [`did:webvh` Examples](https://didwebvh.info/latest/example/) on the `did:webvh` 116 | information site. 117 | 118 | ### The `/whois` Use Case 119 | 120 | The `did:webvh` DID Method introduces what we hope will be a widely embraced convention for 121 | all [[ref: DID Methods]] -- the `/whois` path. This feature harkens back to the `WHOIS` 122 | protocol that was created in the 1970s to provide a directory about people and 123 | entities in the early days of ARPANET. In the 80's, `whois` evolved into 124 | [[spec-inform:rfc920]] that has expanded into the [global 125 | whois](https://en.wikipedia.org/wiki/WHOIS) feature we know today as 126 | [[spec-inform:rfc3912]]. Submit a `whois` request about a domain name, and get 127 | back the information published about that domain. 128 | 129 | We propose that the `/whois` path for a DID enable a comparable, decentralized, 130 | version of the `WHOIS` protocol for DIDs. Notably, when `/whois` is 131 | resolved (using a standard DID `service` that follows the [[ref: Linked-VP]] 132 | specification), a [[ref: Verifiable Presentation]] (VP) may be returned (if 133 | published by the [[ref: DID Controller]]) containing [[ref: Verifiable Credentials]] with 134 | the DID as the `credentialSubject`, and the VP signed by the DID. Given a DID, 135 | one can gather verifiable data about the [[ref: DID Controller]] by resolving 136 | `/whois` and processing the returned VP. That's powerful -- an efficient, 137 | highly decentralized, trust registry. For `did:webvh`, the approach is very simple 138 | -- transform the DID to its HTTPS equivalent, and execute a `GET /whois`. 139 | Need to know who issued the VCs in the VP? Get the issuer DIDs from those VCs, 140 | and resolve `/whois` for each. This is comparable to walking a CA 141 | (Certificate Authority) hierarchy, but self-managed by the [[ref: DID Controllers]] -- 142 | and the issuers that attest to them. 143 | 144 | The following is a use case for the `/whois` capability. Consider an example of 145 | the `did:webvh` controller being a mining company that has exported a shipment and 146 | created a "Product Passport" Verifiable Credential with information about the 147 | shipment. A country importing the shipment (the Importer) might want to know 148 | more about the issuer of the VC, and hence, the details of the shipment. They 149 | resolve the `/whois` of the entity and get back a Verifiable Presentation 150 | about that DID. It might contain: 151 | 152 | - A verifiable credential issued by the Legal Entity Registrar for the 153 | jurisdiction in which the mining company is headquartered. 154 | - Since the Importer knows about the Legal Entity Registrar, they can automate 155 | this lookup to get more information about the company from the VC -- its 156 | legal name, when it was registered, contact information, etc. 157 | - A verifiable credential for a "Mining Permit" issued by the mining authority 158 | for the jurisdiction in which the company operates. 159 | - Perhaps the Importer does not know about the mining authority for that 160 | jurisdiction. The Importer can repeat the `/whois` resolution process for 161 | the issuer of _that_ credential. The Importer might (for example), resolve 162 | and verify the `did:webvh` DID for the Authority, and then resolve the 163 | `/whois` DID URL to find a verifiable credential issued by the government of 164 | the jurisdiction. The Importer recognizes and trusts that government's 165 | authority, and so can decide to recognize and trust the mining permit 166 | authority. 167 | - A verifiable credential about the auditing of the mining practices of the 168 | mining company. Again, the Importer doesn't know about the issuer of the audit 169 | VC, so they resolve the `/whois` for the DID of the issuer, get its VP and 170 | find that it is accredited to audit mining companies by the [London Metal 171 | Exchange](https://www.lme.com/en/) according to one of its mining standards. 172 | As the Importer knows about both the London Metal Exchange and the standard, 173 | it can make a trust decision about the original Product Passport Verifiable 174 | Credential. 175 | 176 | Such checks can all be done with a handful of HTTPS requests and the processing 177 | of the DIDs and verifiable presentations. If the system cannot automatically 178 | make a trust decision, lots of information has been quickly collected that can 179 | be passed to a person to make such a decision. 180 | 181 | The result is an efficient, verifiable, credential-based, decentralized, 182 | multi-domain trust registry, empowering individuals and organizations to verify 183 | the authenticity and legitimacy of DIDs. The convention promotes a decentralized 184 | trust model where trust is established through cryptographic verification rather 185 | than reliance on centralized authorities. By enabling anyone to access and 186 | validate the information associated with a DID, the "/whois" path contributes to 187 | the overall security and integrity of decentralized networks. 188 | -------------------------------------------------------------------------------- /spec-v1.0/references.md: -------------------------------------------------------------------------------- 1 | ## References 2 | 3 | [[spec]] 4 | -------------------------------------------------------------------------------- /spec-v1.0/security_and_privacy.md: -------------------------------------------------------------------------------- 1 | ## Security and Privacy Considerations 2 | 3 | ### DNS Considerations 4 | 5 | #### DNS Security Considerations 6 | 7 | Implementers **MUST** secure DNS resolution to protect against attacks like Man in 8 | the Middle, following the detailed guidance in the [did:web 9 | specification](https://w3c-ccg.github.io/did-method-web/#dns-considerations). 10 | The use of DNSSEC [[spec:RFC4033]], [[spec:RFC4034]], [[spec:RFC4035]] is 11 | essential to prevent spoofing and ensure authenticity of DNS records. 12 | 13 | #### DNS Privacy Considerations 14 | 15 | Resolving a `did:webvh` identifier can expose users to tracking by DNS providers 16 | and web servers. To mitigate this risk, it's **RECOMMENDED** to use privacy-enhancing 17 | technologies such as VPNs, TOR, or trusted universal resolver services, in line 18 | with strategies outlined in the [did:web 19 | specification](https://w3c-ccg.github.io/did-method-web/#dns-considerations) 20 | including emerging RFCs such as [Oblivious DNS over 21 | HTTPS](https://datatracker.ietf.org/doc/html/draft-pauly-dprive-oblivious-doh-03) 22 | for DNS privacy. 23 | 24 | ### In-transit Security 25 | 26 | For in-transit security, the guidance provided in the [did:web 27 | specification](https://w3c-ccg.github.io/did-method-web/#in-transit-security) 28 | regarding the encryption of traffic between the server and client **SHOULD** be 29 | followed. Ecosystem implementors **SHOULD** follow the same guidance for [[ref: watchers]] and [[ref: witnesses]] implementations. 30 | 31 | ### International Domain Names 32 | 33 | `did:webvh` implementers **MAY** publish [[ref: DID Logs]] on domains that use international domains. 34 | The [DID-to-HTTPS Transformation](#the-did-to-https-transformation) section of this specification 35 | **MUST** be followed by [[ref: DID Controllers]] and DID resolvers to ensure the proper 36 | handling of international domains. 37 | 38 | ### Cross-Origin Resource Sharing (CORS) Policy Considerations 39 | 40 | To support scenarios where DID resolution is performed by client applications running in a web browser, the file served for the [[ref: DID Log]] needs to be accessible by any origin. To enable this, the [[ref: DID Log]] HTTP response MUST include the following header: 41 | 42 | `Access-Control-Allow-Origin: *` 43 | 44 | ### Publishing parallel `did:web` 45 | 46 | `did:webvh` implementers that consider [publishing parallel `did:web` DID](#publishing-a-parallel-didweb-did) **SHOULD** evaluate 47 | security impact from losing added security properties of `did:webvh` 48 | and refer to [did:web Security and Privacy Considerations](https://w3c-ccg.github.io/did-method-web/#dns-considerations) for additional guidance. 49 | 50 | ### Right to Erasure ([GDPR Art. 17](https://gdpr-info.eu/art-17-gdpr/)) 51 | 52 | While it's possible for [[ref: DID Controller]] to delete published data as described in [Deactivate (Revoke) operation](#deactivate-revoke), 53 | it's **RECOMMENDED** for monitoring [[ref: watchers]] to cache last known state indefinitely. 54 | This means that ability and specific process of complete data erasure depends on [[ref: watchers]] behavior 55 | and **SHOULD** be defined by governance of ecosystem. 56 | 57 | ### Post Quantum Attacks 58 | 59 | `did:webvh` [[ref: Key Pre-Rotation]] approach provides enough flexibility for "post-quantum safety". 60 | For guidance on post-quantum attacks mitigation, implementors **SHOULD** refer to [corresponding Implementation Guide section](https://didwebvh.info/latest/implementers-guide/prerotation-keys/#post-quantum-attacks). -------------------------------------------------------------------------------- /spec-v1.0/version.md: -------------------------------------------------------------------------------- 1 | ## `did:webvh` Version Changelog 2 | 3 | The following lists the substantive changes in each version of the specification. 4 | 5 | - Version 1.0 6 | - Removes the `weight` value and clarifies permitted values of `threshold`. 7 | - Adds the concept of a `watcher` to the specification, including the technical details of deploying and using a `watcher`. 8 | - Clarifies the [DID-to-HTTPS Transformation](#the-did-to-https-transformation) to include support for domain names using Unicode international languages. 9 | 10 | - Version 0.5 11 | - Remove the `prerotation` parameter. The feature is automatically enforced 12 | when `nextKeyHashes` is present. 13 | - Clarify the way the [[ref: Pre-Rotation]] feature works, once a `nextKeyHashes` 14 | is committed, the next [[ref: DID log entries]] has to be signed by one of the committed keys. 15 | - Clarify how to stop using [[ref: pre-rotation]], including when deactivating the DID. 16 | - Change the [[ref: witness]] handling by removing the witness [[ref: Data Integrity]] 17 | proofs from the [[ref: DID Log]] file and puts them into a separate file 18 | `did-witness.json`. Adjustments to the witness threshold algorithm were also 19 | made, such as removing the [[ref: DID Controllers]]' `selfweight` attribute, 20 | and defining that all witness DIDs must be `did:key` DIDs. 21 | - Clarify how to stop using witnesses. 22 | - Clarify the initialization values of [[ref: parameters]] and that array 23 | [[ref: parameters]] must use `null` and **not** use empty lists (`[]`) when 24 | not active. 25 | - Rename the DID Method to `did:webvh` (`did:web` + Verifiable History) 26 | - Move the DID Method information site to [https://didwebvh.info](https://didwebvh.info). 27 | - Version 0.4 28 | - Removes large non-normative sections, such as the implementer's guide, as they are now published on the [https://didtdw.org/](https://didtdw.org/) information site. 29 | - Removes the use of JSON Patch from the specification. The full DIDDoc is included in each [[ref: DID log entry]]. 30 | - Changes the data format of the [[ref: DID log entries]] from an array to an object. The [[ref: DID Log]] remains in the [[ref: JSON Lines]] format. 31 | - Changes the [[ref: DID log entry]] array to be named JSON objects or properties. 32 | - Makes each DID version's [[ref: Data Integrity]] proof apply across the JSON 33 | [[ref: DID log entry]] object, as is typical with [[ref: Data Integrity]] proofs. 34 | Previously, the [[ref: Data Integrity]] proof was generated across 35 | the current DIDDoc version, with the `versionId` as the challenge. 36 | - Specified that the `versionTime` must be recorded as a UTC time zone timestamp. 37 | - Version 0.3 38 | - Removes the `cryptosuite` [[ref: parameter]], moving it to implied based on the `method` [[ref: parameter]]. 39 | - Change base32 encoding with [[ref: base58btc]], as it offers a better expansion rate. 40 | - Remove the step to extract part of the [[ref: base58btc]] result during the generation of the [[ref: SCID]]. 41 | - Use [[ref: multihash]] in the [[ref: SCID]] to differentiate the different hash function outputs. 42 | - Version 0.2 43 | - Changes the location of the [[ref: SCID]] in the DID to always be the first 44 | component after the DID Method prefix -- `did:tdw::...`. 45 | - Adds the [[ref: parameter]] `portable` to enable the capability to move a 46 | `did:tdw` during the creation of the DID. 47 | - Removes the first two [[ref: Log Entry]] items `entryHash` and `versionId` 48 | and replacing them with the new `versionId` as the first item in each 49 | [[ref: log entry]]. The new versionId takes the form `-`, 50 | where `` is the incrementing integer of version of the 51 | entry: 1, 2, 3, etc. 52 | - The `/whois` media type is changed to `application/vp` and the file is 53 | changed to `whois.vp` to match the IANA registration of a [[ref: Verifiable Presentation]]. 54 | -------------------------------------------------------------------------------- /spec/abstract.md: -------------------------------------------------------------------------------- 1 | ## Abstract 2 | 3 | DID Web + Verifiable History (`did:webvh`) is an enhancement to the [[ref: did:web]] DID method, 4 | providing complementary features that address `did:web`'s 5 | limitations as a long-lasting DID. `did:webvh` features include: 6 | 7 | - The same DID-to-HTTPS transformation as `did:web`. 8 | - Ongoing publishing of the full history of the DID, including all of the DID 9 | Document ([[ref: DIDDoc]]) versions instead of, or alongside an existing 10 | `did:web` DIDDoc. 11 | - The ability to resolve the full history of the DID using a verifiable chain of 12 | updates to the [[ref: DIDDoc]] from genesis to deactivation. 13 | - A [[ref: self-certifying identifier]] (SCID) for the DID. The [[ref: SCID]], globally unique and 14 | embedded in the DID, is derived from the initial [[ref: DID log entry]]. It ensures the integrity 15 | of the DID's history mitigating the risk of attackers creating a new object with 16 | the same identifier. 17 | - An optional mechanism for enabling [[ref: DID portability]] via the [[ref: SCID]], allowing 18 | the DID's web location to be moved and the DID string to be updated, both while retaining 19 | a connection to the predecessor DID(s) and preserving the DID's verifiable history. 20 | - [[ref: DIDDoc]] updates contain a proof signed by the [[ref: DID Controller's]] *authorized* to 21 | update the DID. 22 | - An optional mechanism for publishing "pre-rotation" keys to prevent the loss of 23 | control of a DID in cases where an active private key is compromised. 24 | - An optional mechanism for having collaborating [[ref: witnesses]] 25 | that approve of updates to the DID by a [[ref: DID Controller]] before publication. 26 | - Support for cryptographic agility through versioned specification upgrades, 27 | algorithm-identifying formats (e.g., [[ref: multihash]] and [[ref: Data Integrity]] proofs), and 28 | per-entry method parameters in the [[ref: DID log]] that enable DIDs to evolve 29 | cryptographically over time. 30 | - An optional mechanism for publishing the location of `did:webvh` [[ref: 31 | watchers]] in the [[ref: DID log]] that resolvers can use as another 32 | source DID data for long term resolution or detection of malicious [[ref: DID Controllers]]. 33 | - DID URL path handling that defaults (but can be overridden) to automatically 34 | resolving `/path/to/file` by using a comparable DID-to-HTTPS translation 35 | as for the [[ref: DIDDoc]]. 36 | - A DID URL path `/whois` that defaults to automatically returning (if 37 | published by the [[ref: DID controller]]) a [[ref: Verifiable Presentation]] 38 | containing [[ref: Verifiable Credentials]] with the DID as the 39 | `credentialSubject`, signed by the DID. It draws inspiration from the 40 | traditional WHOIS protocol [[spec:rfc3912]], offering an easy-to-use, 41 | decentralized, trust registry. 42 | 43 | Combined, the additional features enable greater trust, security and verifiability without 44 | compromising the simplicity of `did:web`. 45 | 46 | For information beyond this specification about the (`did:webvh`) DID method and how (and 47 | where) it is used in practice, please visit 48 | [https://didwebvh.info/](https://didwebvh.info/) 49 | -------------------------------------------------------------------------------- /spec/definitions.md: -------------------------------------------------------------------------------- 1 | ## Definitions 2 | 3 | [[def: base58btc]] 4 | 5 | ~ Applies [[spec:draft-msporny-base58-03]] to convert 6 | data to a `base58` encoding. Used in `did:webvh` for encoding hashes for [[ref: SCIDs]] and [[ref: entry hashes]]. 7 | 8 | [[def: Data Integrity]] 9 | 10 | ~ [W3C Data 11 | Integrity](https://www.w3.org/community/reports/credentials/CG-FINAL-data-integrity-20220722/) 12 | is a specification of mechanisms for ensuring the authenticity and integrity of 13 | structured digital documents using cryptography, such as digital signatures and 14 | other digital mathematical proofs. 15 | 16 | [[def: Decentralized Identifier, Decentralized Identifiers, DID, DIDs]] 17 | 18 | ~ Decentralized Identifiers (DIDs) [[spec:did-core]] are a type of identifier that enable 19 | verifiable, decentralized digital identities. A DID refers to any subject (e.g., 20 | a person, organization, thing, data model, abstract entity, etc.) as determined 21 | by the controller of the DID. 22 | 23 | [[def: DID Controller, DID Controller's, DID Controllers]] 24 | 25 | ~ The entity that controls (create, updates, deletes) a given DID, as defined 26 | in the [[spec:DID-CORE]]. 27 | 28 | [[def: DIDDoc]] 29 | 30 | ~ A DID Document as defined by the [[spec: DID-Core]] -- the document returned when a DID is resolved. 31 | 32 | [[def: DID Log, DID Logs]] 33 | 34 | ~ A DID Log is a list of [[ref: Entries]], with an entry added for each update of the DID, 35 | including new versions of the [[ref: DIDDoc]] or changed information necessary to generate or validate the DID. 36 | 37 | [[def: DID Log Entry, DID Log Entries, Entries, Log Entries, Log Entry]] 38 | 39 | ~ A DID Log Entry is a JSON object that defines the authorized 40 | transformation of a [[ref: DIDDoc]] from one version to the next. The initial entry 41 | establishes the DID and version 1 of the [[ref: DIDDoc]]. All entries are stored 42 | in the [[ref: DID Log]]. 43 | 44 | [[def: DID Method, DID Methods]] 45 | 46 | ~ DID methods are the mechanism by which a particular type of DID and its 47 | associated DID document are created, resolved, updated, and deactivated. DID 48 | methods are defined using separate DID method specifications. This document is 49 | the DID Method Specification for `did:webvh`. 50 | 51 | [[def: DID Portability, did:webvh portability, `did:webvh` portability, portability]] 52 | 53 | ~ `did:webvh` portability is the capability to change the DID string for the 54 | DID while retaining the [[ref: SCID]] and the history of the DID. This is useful 55 | when forced to change (such as when an organization is acquired by another, 56 | resulting in a change of domain names) and when changing DID hosting service 57 | providers. 58 | 59 | [[def: DID Resources, DID Resource]] 60 | 61 | ~ A DID Resource is an object (often a file) that is referenced by a DID URL, with a path to the resource. The DID URL allows resolvers to locate and retrieve specific content associated with a DID. Examples include configuration files, schemas, credential definitions, or other structured data linked to the DID. 62 | 63 | [[def: did:web]] 64 | 65 | ~ `did:web` as described in the [W3C specification](https://w3c-ccg.github.io/did-method-web/) 66 | is a DID method that leverages the Domain Name System (DNS) to perform the DID operations. 67 | It is valued for its simplicity and ease of deployment compared to [[ref: DID methods]] that are 68 | based on distributed ledgers or blockchain technology, but also comes with increased 69 | challenges related to trust, security and verifiability. `did:web` provides a starting point for `did:webvh`, 70 | which complements `did:web` with specific features to address its challenges 71 | while still providing ease of deployment. 72 | 73 | [[def: Entry Hash, entryHash, entry hashes]] 74 | 75 | ~ A `did:webvh` entry hash is a hash generated using a formally defined process 76 | over the input data to a [[ref: log entry]], excluding the [[ref: Data Integrity]] 77 | proof. The input data includes content from the predecessor to the 78 | version of the DID, ensuring that all the versions are "chained" together in a 79 | sort of microledger. The generated [[ref: entry hash]] is subsequently included in the 80 | `versionId` of the [[ref: log entry]] and **MUST** be verified by a 81 | resolver. 82 | 83 | [[def: ISO8601, ISO8601 String]] 84 | 85 | ~ A date/time expressed using the [ISO8601 86 | Standard](https://en.wikipedia.org/wiki/ISO_8601). 87 | 88 | [[def: JSON Canonicalization Scheme]] 89 | 90 | ~ [[spec:rfc8785]] defines a method for canonicalizing a JSON 91 | structure such that is suitable for verifiable hashing or signing. 92 | 93 | [[def: JSON Lines, JSON Line]] 94 | 95 | ~ A file of JSON Lines, as described on the site 96 | [https://jsonlines.org/](https://jsonlines.org/). In short, `JSONL` is lines of JSON with 97 | whitespace removed and separated by a newline that is convenient for handling 98 | streaming JSON data or log files. 99 | 100 | [[def: Pre-Rotation, Key Pre-Rotation]] 101 | 102 | ~ A technique for a controller of a cryptographic key to commit to the public 103 | key it will rotate to next, without exposing that actual public key. It protects 104 | from an attacker that gains knowledge of the current private key from being 105 | able to rotate to a new key known only to the attacker. 106 | 107 | [[def: Linked-VP, Linked Verifiable Presentation]] 108 | 109 | ~ A [[spec:DID-CORE]] `service` entry that specifies where a [[ref: verifiable presentation]] 110 | about the DID subject can be found. The [Decentralized Identity 111 | Foundation](https://identity.foundation/) hosts the [Linked VP 112 | Specification](https://identity.foundation/linked-vp/). 113 | 114 | [[def: multibase]] 115 | 116 | ~ A specification for encoding binary data as a string using a prefix that 117 | indicates the encoding. 118 | 119 | [[def: multikey]] 120 | 121 | ~ A verification method that encodes key types into a single binary stream that 122 | is then encoded as a [[ref: multibase]] value. 123 | 124 | [[def: multihash]] 125 | 126 | ~ Per the [[spec:multiformats]], [[ref: multihash]] is a specification 127 | for differentiating instances of hashes. Software creating a hash prefixes 128 | (according to the specification) data to the hash indicating the algorithm used 129 | and the length of the hash, so that software receiving the hash knows how to 130 | verify it. Although [[ref: multihash]] supports many hash algorithms, for 131 | interoperability, [[ref: DID Controllers]] **MUST** only use the hash algorithms defined 132 | in this specification as permitted. 133 | 134 | [[def: parameters, parameter]] 135 | 136 | ~ `did:webvh` parameters are a defined set of configurations that control how the 137 | issuer has generated the DID, and how the resolver must process the DID [[ref: 138 | Log entries]]. The use of parameters allows for the controlled evolution of 139 | `did:webvh` log handling, such as evolving the set of permitted hash algorithms or 140 | cryptosuites. This enables support for very long lasting identifiers -- decades. 141 | 142 | [[def: self-certifying identifier, self-certifying identifiers, SCID, SCIDs]] 143 | 144 | ~ An object identifier derived from initial data such that an attacker could not 145 | create a new object with the same identifier. The input for a `did:webvh` SCID is 146 | the initial [[ref: DIDDoc]] with the placeholder `{SCID}` wherever the SCID is to be 147 | placed. 148 | 149 | [[def: Verifiable Credential, Verifiable Credentials]] 150 | 151 | ~ A verifiable credential can represent all of the same information that a physical credential represents, adding technologies such as digital signatures, to make the credentials more tamper-evident and so more trustworthy than their physical counterparts. The [Verifiable Credential Data Model](https://www.w3.org/TR/vc-data-model/) is a W3C Standard. 152 | 153 | [[def: Verifiable Presentation, Verifiable Presentations]] 154 | 155 | ~ A [[ref: verifiable presentation]] data model is part W3C's [Verifiable Credential Data 156 | Model](https://www.w3.org/TR/vc-data-model/) that contains a set of [[ref: 157 | verifiable credentials]] about a `credentialSubject`, and a signature across the 158 | verifiable credentials generated by that subject. In this specification, the use 159 | case of primary interest is where the DID is the `credentialSubject` and the DID 160 | signs the [[ref: verifiable presentation]]. 161 | 162 | [[def: watcher, watchers]] 163 | 164 | ~ Watchers are entities within a decentralized trust ecosystem that monitor Decentralized Identifiers (DIDs) for changes or updates on behalf of their clients. Watchers maintain a historical cache of DID document versions and verify that the [[ref: DID Controller]] is consistently following the prescribed evolution process. By ensuring integrity and traceability, watchers help foster trust among clients who rely on up-to-date and authentic DID information. `did:webvh` watchers provide endpoints for retrieving DID information and to receive [[ref: webhooks]] notifying the watcher about updates to the DID and deletion requests. 165 | 166 | [[def: webhook, webhooks]] 167 | 168 | ~ A webhook is a mechanism that enables real-time communication between systems by sending HTTP callbacks (typically POST requests) to a specified URL when an event occurs. Webhooks are commonly used for event-driven integrations and automation. Although webhooks are an implementation pattern rather than a formal standard, best practices are documented in [[spec:rfc8030]]. 169 | 170 | [[def: witness, witnesses, witnessed]] 171 | 172 | ~ Witnesses are participants in the process of creating and verifying a version 173 | of a `did:webvh` [[ref: DIDDoc]]. Notably, a witness receives from the [[ref: DID Controller]] a [[ref: DID 174 | Log]] entry ready for publication, verifies it according to this specification, 175 | and approves it according to its ecosystem governance (whatever that might be). If the verification and 176 | approval process results are positive, witnesses returns to the DID Controller a [[ref: Data Integrity]] proof 177 | attesting to that positive result. 178 | 179 | [[def: threshold, witness threshold]] 180 | 181 | ~ An algorithm that defines when a sufficient number of [[ref: witnesses]] have 182 | submitted valid [[ref: Data Integrity]] proofs for a [[ref: DID Log entry]] such 183 | that it is approved and can be published. The algorithm details are in the 184 | [Witness Threshold Algorithm](#witness-threshold-algorithm) section of this 185 | specification. 186 | 187 | [[def: W3C VCDM]] 188 | 189 | ~ A Verifiable Credential that uses the Data Model defined by the W3C [[spec: W3C-VC]] specification. 190 | -------------------------------------------------------------------------------- /spec/header.md: -------------------------------------------------------------------------------- 1 | The `did:webvh` DID Method
v1.0 / Editors Draft 2 | ================== 3 | 4 | ![did:webvh Logo](https://raw.githubusercontent.com/decentralized-identity/didwebvh/refs/heads/main/didwebvh.jpg) 5 | 6 | **Specification Status:** v1.0 - EDITORS DRAFT 7 | 8 | This **v1.0 - Editors Draft** is being maintained in sync with the v1.0 specification (other than this header) while cleanups and clarifications are made to the specification. Once a breaking change is identified, we will stop keeping the two versions of the specification in sync. 9 | 10 | **Current Specification:** [v1.0](../v1.0) 11 | 12 | **Specification Version:** v1.0 (see [Changelog](#didwebvh-version-changelog)) 13 | 14 | **Source of Latest Draft:** 15 | [https://github.com/decentralized-identity/didwebvh](https://github.com/decentralized-identity/didwebvh) 16 | 17 | **Previous Versions:** 18 | 19 | - [v0.4](../v0.5) 20 | - [v0.4](../v0.4) 21 | - [v0.3](../v0.3) 22 | 23 | **Information Site:** 24 | [https://didwebvh.info/](https://didwebvh.info/) 25 | 26 | **Editors:** 27 | ~ [Stephen Curran](https://github.com/swcurran) 28 | ~ [John Jordan, BC Gov](https://github.com/jljordan42) 29 | ~ [Andrew Whitehead](https://github.com/andrewwhitehead) 30 | ~ [Brian Richter](https://github.com/brianorwhatever) 31 | ~ [Michel Sahli](https://github.com/bj-ms) 32 | ~ [Martina Kolpondinos](https://github.com/martipos) 33 | ~ [Dmitri Zagdulin](https://github.com/dmitrizagidulin) 34 | ~ [Alexander Shenshin](https://github.com/AlexanderShenshin) 35 | 36 | **Participate:** 37 | ~ [GitHub repo](https://github.com/decentralized-identity/didwebvh) 38 | ~ [File a bug](https://github.com/decentralized-identity/didwebvh/issues) 39 | ~ [Commit history](https://github.com/decentralized-identity/didwebvh/commits/main) 40 | 41 | **Implementations:** 42 | ~ [TypeScript] 43 | ~ [Python] 44 | ~ [Go] - supports v03 45 | ~ [Rust] - work in progress 46 | ~ [did:webvh Server] 47 | ~ [did:webvh ACA-Py Plugin] 48 | 49 | [TypeScript]: https://github.com/decentralized-identity/trustdidweb-ts 50 | [Python]: https://github.com/decentralized-identity/trustdidweb-py 51 | [Go]: https://github.com/nuts-foundation/trustdidweb-go 52 | [Rust]: https://github.com/decentralized-identity/didwebvh-rs 53 | [did:webvh Server]: https://github.com/decentralized-identity/trustdidweb-server-py 54 | [did:webvh ACA-Py Plugin]: https://github.com/openwallet-foundation/acapy-plugins/pull/1377 55 | 56 | ------------------------------------ 57 | -------------------------------------------------------------------------------- /spec/overview.md: -------------------------------------------------------------------------------- 1 | ## Overview 2 | 3 | The emergence of [[ref: Decentralized Identifiers]] (DIDs) and with them the 4 | evolution of [[ref: DID Methods]] continues to be a dynamic area of 5 | development in the quest for trusted, secure and private digital identity 6 | management where the users are in control of their own data. 7 | 8 | The `did:web` method, for example, leverages the Domain Name System (DNS) to 9 | perform the DID operations. This approach is praised for its simplicity and 10 | ease of deployment, including DID-to-HTTPS transformation and addressing 11 | some aspects of trust by allowing for DIDs to be associated with a domain's 12 | reputation or published on platforms such as GitHub. However, it is not 13 | without its challenges-- 14 | from trust layers inherited from the web and the absence of a verifiable 15 | history for the DID. 16 | 17 | Tackling these concerns, the `did:webvh` (`did:web` + Verifiable History) DID 18 | Method aims to enhance `did:web` by introducing features such as a [[ref: 19 | self-certifying identifiers]] (SCIDs), update key(s) and a verifiable history, 20 | akin to what is available with ledger-based DIDs, but without relying on a 21 | ledger. 22 | 23 | This approach not only maintains backward compatibility but also offers an 24 | additional layer of assurance for those requiring more robust verification 25 | processes. By publishing the resulting DID as both `did:web` and `did:webvh`, it 26 | caters to a broader range of trust requirements, from those who are comfortable 27 | with the existing `did:web` infrastructure to those seeking greater security 28 | assurances provided by `did:webvh`. This innovative step represents a significant 29 | stride towards a more trusted and secure web, where the integrity of 30 | cryptographic key publishing is paramount. 31 | 32 | The key differences between `did:web` and `did:webvh` revolve around the core 33 | issues of decentralization and security. `did:web` is recognized for its 34 | simplicity and cost-effectiveness, allowing for easy establishment of a 35 | credential ecosystem. However, it is not inherently decentralized as it relies 36 | on DNS domain names, which require centralized registries. Furthermore, it lacks a 37 | cryptographically verifiable, tamper-resistant, and persistently stored DID 38 | document. In contrast, `did:webvh` is an enhancement 39 | to `did:web`, aiming to address these limitations by adding a verifiable history 40 | to the DID without the need for a ledger. This method provides a more 41 | decentralized approach by ensuring that the security of the embedded 42 | SCID does not depend on DNS. `did:webvh` is 43 | capable of resolving a cryptographically verifiable trust registry and status 44 | lists, using DID-Linked Resources, which `did:web` lacks. These features are 45 | designed to build a trusted web by offering a higher level of assurance for 46 | cryptographic key publishing and management. 47 | 48 | For backwards compatibility, and for verifiers that "trust" `did:web`, a 49 | `did:webvh` can be trivially modified and published with a parallel `did:web` 50 | DID. For resolvers that want more assurance, `did:webvh` provides a way to 51 | verify a did:web using the features listed in the [Abstract](#abstract). 52 | 53 | The following is a `tl;dr` summary of how `did:webvh` works: 54 | 55 | 1. `did:webvh` uses the same DID-to-HTTPS transformation as `did:web`, so 56 | `did:webvh`'s `did.jsonl` ([[ref: JSON Lines]]) file is found in the same 57 | location as `did:web`'s `did.json` file, and supports an easy transition 58 | from `did:web` to gain the added benefits of `did:webvh`. 59 | 2. The `did.jsonl` is a list of JSON [[ref: DID log entries]], one per line, 60 | whitespace removed (per [[ref: JSON Lines]]). Each entry contains the 61 | information needed to derive a version of the [[ref: DIDDoc]] from its preceding 62 | version. The `did.jsonl` is also referred to as the [[ref: DID Log]]. 63 | 3. Each [[ref: DID log entry]] is a JSON object containing the following properties: 64 | 1. `versionId` -- a value that combines the version number 65 | (starting at `1` and incremented by one per version), a literal dash 66 | `-`, and a hash of the entry. The [[ref: entry hash]] calculation links each entry 67 | to its predecessor in a ledger-like chain. 68 | 2. `versionTime` -- as asserted by the [[ref: DID Controller]]. 69 | 3. `parameters` -- a set of [[ref: parameters]] that impact the processing of the current and 70 | future [[ref: log entries]]. 71 | - Example [[ref: parameters]] are the version of the `did:webvh` specification and 72 | hash algorithm being used, as well as the [[ref: SCID]] and update key(s). 73 | 4. `state` -- the new version of the [[ref: DIDDoc]]. 74 | 5. A [[ref: Data Integrity]] (DI) proof across the entry, signed by a [[ref: 75 | DID Controller]]-authorized key to update the [[ref: DIDDoc]]. 76 | 6. If the [[ref: DID Controller]] enables support for DID [[witnesses]], an 77 | extra file (`did-witness.json`) in the same web location contains [[ref: 78 | Data Integrity]] proofs from witness for [[ref: DID Log entries]]. 79 | 4. In generating the first version of the [[ref: DIDDoc]], the [[ref: DID 80 | Controller]] calculates the [[ref: SCID]] for the DID from the first [[ref: 81 | log entry]] (which includes the [[ref: DIDDoc]]). This is done by using the 82 | string `"{SCID}"` everywhere the actual [[ref: SCID]] is to be placed in order 83 | to generate the hash. The [[ref: DID Controller]] then replaces the 84 | placeholders with the calculated [[ref: SCID]], including it as a `parameter` 85 | in the first [[ref: log entry]], and inserting it where needed in the initial 86 | (and all subsequent) DIDDocs. The [[ref: SCID]] must be verified by the 87 | resolvers, to verify that the inception event has not been tampered with. The 88 | [[ref: SCID]] also enables an optional [[ref: portability]] capability, 89 | allowing a DID's web location to be moved, while retaining the [[ref: SCID]] and verifiable 90 | history of the identifier. 91 | 5. A [[ref: DID Controller]] generates and publishes the new/updated [[ref: DID 92 | Log]] file by making it available at the appropriate location on the web, 93 | based on the DID's identifier. If a `did:webvh` has [[ref: watchers]], a 94 | webhook is triggered to notify the [[ref: watchers]] that an update is 95 | available and should be retrieved. 96 | 6. Given a `did:webvh` DID, a resolver converts the DID to an HTTPS URL, 97 | retrieves, and processes the [[ref: DID Log]] `did.jsonl` file, generating and verifying 98 | each [[ref: log entry]] as per the requirements outlined in this specification. 99 | - In the process, the resolver collects all the [[ref: DIDDoc]] versions and public 100 | keys used by the DID currently, and in the past. This enables 101 | resolving both current and past versions of the DID and keys. 102 | 7. `did:webvh` DID URLs with paths and `/whois` are resolved to documents 103 | published by the [[ref: DID Controller]] that are by default in the web location relative to the 104 | `did.jsonl` file. See the [note below](#the-whois-use-case) about the 105 | powerful capability enabled by the `/whois` DID URL path. 106 | 8. A [[ref: DID Controller]] can easily generate and publish a `did:web` DIDDoc 107 | from the latest `did:webvh` [[ref: DIDDoc]] in parallel with the `did:webvh` [[ref: DID Log]]. 108 | 109 | ::: warning 110 | A resolver settling for just the `did:web` version of the DID does not get the 111 | verifiability of the `did:webvh` log. 112 | ::: 113 | 114 | An example of a `did:webvh` evolving through a series of versions can be seen in 115 | the [`did:webvh` Examples](https://didwebvh.info/latest/example/) on the `did:webvh` 116 | information site. 117 | 118 | ### The `/whois` Use Case 119 | 120 | The `did:webvh` DID Method introduces what we hope will be a widely embraced convention for 121 | all [[ref: DID Methods]] -- the `/whois` path. This feature harkens back to the `WHOIS` 122 | protocol that was created in the 1970s to provide a directory about people and 123 | entities in the early days of ARPANET. In the 80's, `whois` evolved into 124 | [[spec-inform:rfc920]] that has expanded into the [global 125 | whois](https://en.wikipedia.org/wiki/WHOIS) feature we know today as 126 | [[spec-inform:rfc3912]]. Submit a `whois` request about a domain name, and get 127 | back the information published about that domain. 128 | 129 | We propose that the `/whois` path for a DID enable a comparable, decentralized, 130 | version of the `WHOIS` protocol for DIDs. Notably, when `/whois` is 131 | resolved (using a standard DID `service` that follows the [[ref: Linked-VP]] 132 | specification), a [[ref: Verifiable Presentation]] (VP) may be returned (if 133 | published by the [[ref: DID Controller]]) containing [[ref: Verifiable Credentials]] with 134 | the DID as the `credentialSubject`, and the VP signed by the DID. Given a DID, 135 | one can gather verifiable data about the [[ref: DID Controller]] by resolving 136 | `/whois` and processing the returned VP. That's powerful -- an efficient, 137 | highly decentralized, trust registry. For `did:webvh`, the approach is very simple 138 | -- transform the DID to its HTTPS equivalent, and execute a `GET /whois`. 139 | Need to know who issued the VCs in the VP? Get the issuer DIDs from those VCs, 140 | and resolve `/whois` for each. This is comparable to walking a CA 141 | (Certificate Authority) hierarchy, but self-managed by the [[ref: DID Controllers]] -- 142 | and the issuers that attest to them. 143 | 144 | The following is a use case for the `/whois` capability. Consider an example of 145 | the `did:webvh` controller being a mining company that has exported a shipment and 146 | created a "Product Passport" Verifiable Credential with information about the 147 | shipment. A country importing the shipment (the Importer) might want to know 148 | more about the issuer of the VC, and hence, the details of the shipment. They 149 | resolve the `/whois` of the entity and get back a Verifiable Presentation 150 | about that DID. It might contain: 151 | 152 | - A verifiable credential issued by the Legal Entity Registrar for the 153 | jurisdiction in which the mining company is headquartered. 154 | - Since the Importer knows about the Legal Entity Registrar, they can automate 155 | this lookup to get more information about the company from the VC -- its 156 | legal name, when it was registered, contact information, etc. 157 | - A verifiable credential for a "Mining Permit" issued by the mining authority 158 | for the jurisdiction in which the company operates. 159 | - Perhaps the Importer does not know about the mining authority for that 160 | jurisdiction. The Importer can repeat the `/whois` resolution process for 161 | the issuer of _that_ credential. The Importer might (for example), resolve 162 | and verify the `did:webvh` DID for the Authority, and then resolve the 163 | `/whois` DID URL to find a verifiable credential issued by the government of 164 | the jurisdiction. The Importer recognizes and trusts that government's 165 | authority, and so can decide to recognize and trust the mining permit 166 | authority. 167 | - A verifiable credential about the auditing of the mining practices of the 168 | mining company. Again, the Importer doesn't know about the issuer of the audit 169 | VC, so they resolve the `/whois` for the DID of the issuer, get its VP and 170 | find that it is accredited to audit mining companies by the [London Metal 171 | Exchange](https://www.lme.com/en/) according to one of its mining standards. 172 | As the Importer knows about both the London Metal Exchange and the standard, 173 | it can make a trust decision about the original Product Passport Verifiable 174 | Credential. 175 | 176 | Such checks can all be done with a handful of HTTPS requests and the processing 177 | of the DIDs and verifiable presentations. If the system cannot automatically 178 | make a trust decision, lots of information has been quickly collected that can 179 | be passed to a person to make such a decision. 180 | 181 | The result is an efficient, verifiable, credential-based, decentralized, 182 | multi-domain trust registry, empowering individuals and organizations to verify 183 | the authenticity and legitimacy of DIDs. The convention promotes a decentralized 184 | trust model where trust is established through cryptographic verification rather 185 | than reliance on centralized authorities. By enabling anyone to access and 186 | validate the information associated with a DID, the "/whois" path contributes to 187 | the overall security and integrity of decentralized networks. 188 | -------------------------------------------------------------------------------- /spec/references.md: -------------------------------------------------------------------------------- 1 | ## References 2 | 3 | [[spec]] 4 | -------------------------------------------------------------------------------- /spec/security_and_privacy.md: -------------------------------------------------------------------------------- 1 | ## Security and Privacy Considerations 2 | 3 | ### DNS Considerations 4 | 5 | #### DNS Security Considerations 6 | 7 | Implementers **MUST** secure DNS resolution to protect against attacks like Man in 8 | the Middle, following the detailed guidance in the [did:web 9 | specification](https://w3c-ccg.github.io/did-method-web/#dns-considerations). 10 | The use of DNSSEC [[spec:RFC4033]], [[spec:RFC4034]], [[spec:RFC4035]] is 11 | essential to prevent spoofing and ensure authenticity of DNS records. 12 | 13 | #### DNS Privacy Considerations 14 | 15 | Resolving a `did:webvh` identifier can expose users to tracking by DNS providers 16 | and web servers. To mitigate this risk, it's **RECOMMENDED** to use privacy-enhancing 17 | technologies such as VPNs, TOR, or trusted universal resolver services, in line 18 | with strategies outlined in the [did:web 19 | specification](https://w3c-ccg.github.io/did-method-web/#dns-considerations) 20 | including emerging RFCs such as [Oblivious DNS over 21 | HTTPS](https://datatracker.ietf.org/doc/html/draft-pauly-dprive-oblivious-doh-03) 22 | for DNS privacy. 23 | 24 | ### In-transit Security 25 | 26 | For in-transit security, the guidance provided in the [did:web 27 | specification](https://w3c-ccg.github.io/did-method-web/#in-transit-security) 28 | regarding the encryption of traffic between the server and client **SHOULD** be 29 | followed. Ecosystem implementors **SHOULD** follow the same guidance for [[ref: watchers]] and [[ref: witnesses]] implementations. 30 | 31 | ### International Domain Names 32 | 33 | `did:webvh` implementers **MAY** publish [[ref: DID Logs]] on domains that use international domains. 34 | The [DID-to-HTTPS Transformation](#the-did-to-https-transformation) section of this specification 35 | **MUST** be followed by [[ref: DID Controllers]] and DID resolvers to ensure the proper 36 | handling of international domains. 37 | 38 | ### Cross-Origin Resource Sharing (CORS) Policy Considerations 39 | 40 | To support scenarios where DID resolution is performed by client applications running in a web browser, the file served for the [[ref: DID Log]] needs to be accessible by any origin. To enable this, the [[ref: DID Log]] HTTP response MUST include the following header: 41 | 42 | `Access-Control-Allow-Origin: *` 43 | 44 | ### Publishing parallel `did:web` 45 | 46 | `did:webvh` implementers that consider [publishing parallel `did:web` DID](#publishing-a-parallel-didweb-did) **SHOULD** evaluate 47 | security impact from losing added security properties of `did:webvh` 48 | and refer to [did:web Security and Privacy Considerations](https://w3c-ccg.github.io/did-method-web/#dns-considerations) for additional guidance. 49 | 50 | ### Right to Erasure ([GDPR Art. 17](https://gdpr-info.eu/art-17-gdpr/)) 51 | 52 | While it's possible for [[ref: DID Controller]] to delete published data as described in [Deactivate (Revoke) operation](#deactivate-revoke), 53 | it's **RECOMMENDED** for monitoring [[ref: watchers]] to cache last known state indefinitely. 54 | This means that ability and specific process of complete data erasure depends on [[ref: watchers]] behavior 55 | and **SHOULD** be defined by governance of ecosystem. 56 | 57 | ### Post Quantum Attacks 58 | 59 | `did:webvh` [[ref: Key Pre-Rotation]] approach provides enough flexibility for "post-quantum safety". 60 | For guidance on post-quantum attacks mitigation, implementors **SHOULD** refer to [corresponding Implementation Guide section](https://didwebvh.info/latest/implementers-guide/prerotation-keys/#post-quantum-attacks). -------------------------------------------------------------------------------- /spec/version.md: -------------------------------------------------------------------------------- 1 | ## `did:webvh` Version Changelog 2 | 3 | The following lists the substantive changes in each version of the specification. 4 | 5 | - Version 1.0 6 | - Removes the `weight` value and clarifies permitted values of `threshold`. 7 | - Adds the concept of a `watcher` to the specification, including the technical details of deploying and using a `watcher`. 8 | - Clarifies the [DID-to-HTTPS Transformation](#the-did-to-https-transformation) to include support for domain names using Unicode international languages. 9 | 10 | - Version 0.5 11 | - Remove the `prerotation` parameter. The feature is automatically enforced 12 | when `nextKeyHashes` is present. 13 | - Clarify the way the [[ref: Pre-Rotation]] feature works, once a `nextKeyHashes` 14 | is committed, the next [[ref: DID log entries]] has to be signed by one of the committed keys. 15 | - Clarify how to stop using [[ref: pre-rotation]], including when deactivating the DID. 16 | - Change the [[ref: witness]] handling by removing the witness [[ref: Data Integrity]] 17 | proofs from the [[ref: DID Log]] file and puts them into a separate file 18 | `did-witness.json`. Adjustments to the witness threshold algorithm were also 19 | made, such as removing the [[ref: DID Controllers]]' `selfweight` attribute, 20 | and defining that all witness DIDs must be `did:key` DIDs. 21 | - Clarify how to stop using witnesses. 22 | - Clarify the initialization values of [[ref: parameters]] and that array 23 | [[ref: parameters]] must use `null` and **not** use empty lists (`[]`) when 24 | not active. 25 | - Rename the DID Method to `did:webvh` (`did:web` + Verifiable History) 26 | - Move the DID Method information site to [https://didwebvh.info](https://didwebvh.info). 27 | - Version 0.4 28 | - Removes large non-normative sections, such as the implementer's guide, as they are now published on the [https://didtdw.org/](https://didtdw.org/) information site. 29 | - Removes the use of JSON Patch from the specification. The full DIDDoc is included in each [[ref: DID log entry]]. 30 | - Changes the data format of the [[ref: DID log entries]] from an array to an object. The [[ref: DID Log]] remains in the [[ref: JSON Lines]] format. 31 | - Changes the [[ref: DID log entry]] array to be named JSON objects or properties. 32 | - Makes each DID version's [[ref: Data Integrity]] proof apply across the JSON 33 | [[ref: DID log entry]] object, as is typical with [[ref: Data Integrity]] proofs. 34 | Previously, the [[ref: Data Integrity]] proof was generated across 35 | the current DIDDoc version, with the `versionId` as the challenge. 36 | - Specified that the `versionTime` must be recorded as a UTC time zone timestamp. 37 | - Version 0.3 38 | - Removes the `cryptosuite` [[ref: parameter]], moving it to implied based on the `method` [[ref: parameter]]. 39 | - Change base32 encoding with [[ref: base58btc]], as it offers a better expansion rate. 40 | - Remove the step to extract part of the [[ref: base58btc]] result during the generation of the [[ref: SCID]]. 41 | - Use [[ref: multihash]] in the [[ref: SCID]] to differentiate the different hash function outputs. 42 | - Version 0.2 43 | - Changes the location of the [[ref: SCID]] in the DID to always be the first 44 | component after the DID Method prefix -- `did:tdw::...`. 45 | - Adds the [[ref: parameter]] `portable` to enable the capability to move a 46 | `did:tdw` during the creation of the DID. 47 | - Removes the first two [[ref: Log Entry]] items `entryHash` and `versionId` 48 | and replacing them with the new `versionId` as the first item in each 49 | [[ref: log entry]]. The new versionId takes the form `-`, 50 | where `` is the incrementing integer of version of the 51 | entry: 1, 2, 3, etc. 52 | - The `/whois` media type is changed to `application/vp` and the file is 53 | changed to `whois.vp` to match the IANA registration of a [[ref: Verifiable Presentation]]. 54 | -------------------------------------------------------------------------------- /specs.json: -------------------------------------------------------------------------------- 1 | { 2 | "specs": [ 3 | { 4 | "title": "The did:webvh DID Method -- did:web + Verifiable History - v1.0 (Editors Draft)", 5 | "spec_directory": "./spec", 6 | "markdown_paths": [ 7 | "header.md", 8 | "abstract.md", 9 | "overview.md", 10 | "specification.md", 11 | "security_and_privacy.md", 12 | "definitions.md", 13 | "references.md", 14 | "version.md" 15 | ], 16 | "source": { 17 | "host": "github", 18 | "account": "decentralized-identity", 19 | "repo": "didwebvh" 20 | }, 21 | "output_path": "./next", 22 | "logo": "https://raw.githubusercontent.com/decentralized-identity/didwebvh/refs/heads/main/didwebvh.jpg", 23 | "logo_link": "https://github.com/decentralized-identity/didwebvh", 24 | "katex": true, 25 | "external_specs": [ 26 | { 27 | "multiformats": { 28 | "href": "https://datatracker.ietf.org/doc/draft-multiformats-multibase/08/", 29 | "title": "Multiformats", 30 | "rawDate": "2024-02-21", 31 | "authors": [ 32 | "Juan Benet", 33 | "Manu Sporny" 34 | ], 35 | "status": "Internet Draft" 36 | } 37 | }, 38 | { 39 | "di-eddsa-v1.0": { 40 | "href": "https://www.w3.org/TR/vc-di-eddsa", 41 | "title": "Data Integrity EdDSA Cryptosuites v1.0", 42 | "rawDate": "2024-12-08", 43 | "authors": [ 44 | "Dave Longley", 45 | "Manu Sporny" 46 | ], 47 | "status": "W3C Technical Recommendation" 48 | } 49 | } 50 | ] 51 | }, 52 | { 53 | "title": "The did:webvh DID Method -- did:web + Verifiable History - v1.0", 54 | "spec_directory": "./spec-v1.0", 55 | "markdown_paths": [ 56 | "header.md", 57 | "abstract.md", 58 | "overview.md", 59 | "specification.md", 60 | "security_and_privacy.md", 61 | "definitions.md", 62 | "references.md", 63 | "version.md" 64 | ], 65 | "source": { 66 | "host": "github", 67 | "account": "decentralized-identity", 68 | "repo": "didwebvh" 69 | }, 70 | "output_path": "./v1.0", 71 | "logo": "https://raw.githubusercontent.com/decentralized-identity/didwebvh/refs/heads/main/didwebvh.jpg", 72 | "logo_link": "https://github.com/decentralized-identity/didwebvh", 73 | "katex": true, 74 | "external_specs": [ 75 | { 76 | "multiformats": { 77 | "href": "https://datatracker.ietf.org/doc/draft-multiformats-multibase/08/", 78 | "title": "Multiformats", 79 | "rawDate": "2024-02-21", 80 | "authors": [ 81 | "Juan Benet", 82 | "Manu Sporny" 83 | ], 84 | "status": "Internet Draft" 85 | } 86 | }, 87 | { 88 | "di-eddsa-v1.0": { 89 | "href": "https://www.w3.org/TR/vc-di-eddsa", 90 | "title": "Data Integrity EdDSA Cryptosuites v1.0", 91 | "rawDate": "2024-12-08", 92 | "authors": [ 93 | "Dave Longley", 94 | "Manu Sporny" 95 | ], 96 | "status": "W3C Technical Recommendation" 97 | } 98 | } 99 | ] 100 | }, 101 | { 102 | "title": "The did:webvh DID Method -- did:web + Verifiable History - Version 0.5", 103 | "spec_directory": "./spec-v0.5", 104 | "markdown_paths": [ 105 | "header.md", 106 | "abstract.md", 107 | "overview.md", 108 | "specification.md", 109 | "security_and_privacy.md", 110 | "definitions.md", 111 | "references.md", 112 | "version.md" 113 | ], 114 | "source": { 115 | "host": "github", 116 | "account": "decentralized-identity", 117 | "repo": "didwebvh" 118 | }, 119 | "output_path": "./v0.5", 120 | "logo": "https://raw.githubusercontent.com/decentralized-identity/didwebvh/refs/heads/main/didwebvh.jpg", 121 | "logo_link": "https://github.com/decentralized-identity/didwebvh", 122 | "katex": true, 123 | "external_specs": [ 124 | { 125 | "multiformats": { 126 | "href": "https://datatracker.ietf.org/doc/draft-multiformats-multibase/08/", 127 | "title": "Multiformats", 128 | "rawDate": "2024-02-21", 129 | "authors": [ 130 | "Juan Benet", 131 | "Manu Sporny" 132 | ], 133 | "status": "Internet Draft" 134 | } 135 | }, 136 | { 137 | "di-eddsa-v1.0": { 138 | "href": "https://www.w3.org/TR/vc-di-eddsa", 139 | "title": "Data Integrity EdDSA Cryptosuites v1.0", 140 | "rawDate": "2024-12-08", 141 | "authors": [ 142 | "Dave Longley", 143 | "Manu Sporny" 144 | ], 145 | "status": "W3C Technical Recommendation" 146 | } 147 | } 148 | ] 149 | }, 150 | { 151 | "title": "Trust DID Web - The did:tdw DID Method - Version 0.4", 152 | "spec_directory": "./spec-v0.4", 153 | "markdown_paths": [ 154 | "header.md", 155 | "abstract.md", 156 | "overview.md", 157 | "specification.md", 158 | "security_and_privacy.md", 159 | "definitions.md", 160 | "references.md", 161 | "version.md" 162 | ], 163 | "source": { 164 | "host": "github", 165 | "account": "decentralized-identity", 166 | "repo": "didwebvh" 167 | }, 168 | "output_path": "./v0.4", 169 | "logo": "https://raw.githubusercontent.com/decentralized-identity/didwebvh/refs/heads/main/tdw.jpg", 170 | "logo_link": "https://github.com/decentralized-identity/didwebvh", 171 | "katex": true, 172 | "external_specs": [ 173 | { 174 | "multiformats": { 175 | "href": "https://datatracker.ietf.org/doc/draft-multiformats-multibase/08/", 176 | "title": "Multiformats", 177 | "rawDate": "2024-02-21", 178 | "authors": [ 179 | "Juan Benet", 180 | "Manu Sporny" 181 | ], 182 | "status": "Internet Draft" 183 | } 184 | } 185 | ] 186 | }, 187 | { 188 | "title": "Trust DID Web - The did:tdw DID Method - Version 0.3", 189 | "spec_directory": "./spec-v0.3", 190 | "markdown_paths": [ 191 | "header.md", 192 | "abstract.md", 193 | "definitions.md", 194 | "overview.md", 195 | "specification.md", 196 | "security_and_privacy.md", 197 | "implementors_guide.md", 198 | "example.md", 199 | "references.md", 200 | "version.md" 201 | ], 202 | "source": { 203 | "host": "github", 204 | "account": "decentralized-identity", 205 | "repo": "didwebvh" 206 | }, 207 | "output_path": "./v0.3", 208 | "logo": "https://raw.githubusercontent.com/decentralized-identity/didwebvh/refs/heads/main/tdw.jpg", 209 | "logo_link": "https://github.com/decentralized-identity/didwebvh", 210 | "katex": true 211 | }, 212 | { 213 | "title": "did:webvh AnonCreds Method", 214 | "spec_directory": "./spec-anoncreds-method", 215 | "markdown_paths": [ 216 | "header.md", 217 | "abstract.md", 218 | "definitions.md", 219 | "specification.md", 220 | "references.md", 221 | "version.md" 222 | ], 223 | "source": { 224 | "host": "github", 225 | "account": "decentralized-identity", 226 | "repo": "didwebvh" 227 | }, 228 | "output_path": "./anoncreds-method", 229 | "logo": "https://raw.githubusercontent.com/decentralized-identity/didwebvh/refs/heads/main/didwebvh.jpg", 230 | "logo_link": "https://github.com/decentralized-identity/didwebvh", 231 | "katex": true, 232 | "external_specs": [ 233 | { 234 | "draft-msporny-base58-03": { 235 | "href": "https://datatracker.ietf.org/doc/html/draft-msporny-base58-03", 236 | "title": "The Base58 Encoding Scheme", 237 | "rawDate": "2021-03-31", 238 | "authors": [ 239 | "S. Nakamoto", 240 | "Manu Sporny" 241 | ], 242 | "status": "Internet Draft" 243 | } 244 | }, { 245 | "multiformats": { 246 | "href": "https://datatracker.ietf.org/doc/draft-multiformats-multibase/08/", 247 | "title": "The Multibase Data Format", 248 | "rawDate": "2024-02-21", 249 | "authors": [ 250 | "Juan Benet", 251 | "Manu Sporny" 252 | ], 253 | "status": "Internet Draft" 254 | } 255 | }, 256 | { 257 | "di-eddsa-v1.0": { 258 | "href": "https://www.w3.org/TR/vc-di-eddsa", 259 | "title": "Data Integrity EdDSA Cryptosuites v1.0", 260 | "rawDate": "2024-12-08", 261 | "authors": [ 262 | "Dave Longley", 263 | "Manu Sporny" 264 | ], 265 | "status": "W3C Technical Recommendation" 266 | } 267 | }, 268 | { 269 | "anoncreds": { 270 | "href": "https://hyperledger.github.io/anoncreds-spec/", 271 | "title": "AnonCreds", 272 | "rawDate": "2023-01-27", 273 | "authors": [ 274 | "Mike Lodder", 275 | "Stephen Curran" 276 | ], 277 | "status": "Internet Draft" 278 | } 279 | } 280 | ] 281 | } 282 | ] 283 | } -------------------------------------------------------------------------------- /tdw.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/decentralized-identity/didwebvh/805782c9aeaf43d29a7366ca96e311c5b2f39d84/tdw.jpg -------------------------------------------------------------------------------- /watcherOpenAPI/watcher-v1.0.0.yml: -------------------------------------------------------------------------------- 1 | openapi: 3.0.3 2 | info: 3 | title: did:webvh Watcher OpenAPI Definition 4 | description: |- 5 | This is the did:webvh watcher API definition. As per the did:webvh specification, a did:webvh watcher referenced in a did:webvh DID Log MUST implement at least this API. 6 | license: 7 | name: Apache 2.0 8 | url: http://www.apache.org/licenses/LICENSE-2.0.html 9 | version: 1.0.0 10 | externalDocs: 11 | description: Find out more about did:webvh and did:webvh Watchers 12 | url: https://didwebvh.info 13 | servers: [] 14 | tags: 15 | - name: log 16 | description: did:webvh DID Log related operations 17 | - name: witness 18 | description: did:webvh Witness related operations 19 | - name: resource 20 | description: did:webvh DID Resource related operations 21 | paths: 22 | /log: 23 | get: 24 | tags: 25 | - log 26 | summary: Return the latest DID Log file 27 | parameters: 28 | - $ref: '#/components/parameters/SCID' 29 | responses: 30 | '200': 31 | description: successful operation 32 | content: 33 | text/jsonl: 34 | schema: 35 | $ref: '#/components/schemas/LogFile' 36 | '400': 37 | description: Invalid SCID value 38 | '404': 39 | description: Unknown SCID value 40 | post: 41 | tags: 42 | - log 43 | summary: Notify the did:webvh Watcher that DID has been updated 44 | parameters: 45 | - $ref: '#/components/parameters/DID' 46 | responses: 47 | '202': 48 | description: Request received 49 | content: 50 | application/json: 51 | schema: 52 | $ref: '#/components/schemas/EmptyResponse' 53 | '400': 54 | description: Invalid input 55 | '422': 56 | description: Validation exception 57 | /log/delete: 58 | post: 59 | tags: 60 | - log 61 | summary: Request deletion of the cached did:webvh DID 62 | parameters: 63 | - $ref: '#/components/parameters/SCID' 64 | requestBody: 65 | $ref: '#/components/requestBodies/VerifiablePresentation' 66 | responses: 67 | '202': 68 | description: Request received 69 | '400': 70 | description: Invalid SCID value 71 | '404': 72 | description: Unknown SCID value 73 | /witness: 74 | get: 75 | tags: 76 | - witness 77 | summary: Return the latest witness file for the DID with the given SCID 78 | parameters: 79 | - $ref: '#/components/parameters/SCID' 80 | responses: 81 | '200': 82 | description: successful operation 83 | content: 84 | application/json: 85 | schema: 86 | $ref: '#/components/schemas/WitnessFile' 87 | '400': 88 | description: Invalid SCID value 89 | '404': 90 | description: Unknown SCID value 91 | /resource: 92 | get: 93 | tags: 94 | - resource 95 | summary: Return resource 96 | parameters: 97 | - $ref: '#/components/parameters/SCID' 98 | - $ref: '#/components/parameters/resourcePath' 99 | responses: 100 | '200': 101 | description: successful operation 102 | '400': 103 | description: Invalid SCID value 104 | '404': 105 | description: Unknown SCID value or resource not found 106 | post: 107 | tags: 108 | - resource 109 | summary: Notify a new resource is available 110 | parameters: 111 | - $ref: '#/components/parameters/SCID' 112 | - $ref: '#/components/parameters/resourcePath' 113 | requestBody: 114 | $ref: '#/components/requestBodies/VerifiablePresentation' 115 | responses: 116 | '202': 117 | description: Request received 118 | '400': 119 | description: Invalid input 120 | '404': 121 | description: Unknown SCID value 122 | '422': 123 | description: Validation exception 124 | /resource/delete: 125 | post: 126 | tags: 127 | - resource 128 | summary: Request deletion of a cached resource 129 | parameters: 130 | - $ref: '#/components/parameters/SCID' 131 | - $ref: '#/components/parameters/resourcePath' 132 | requestBody: 133 | $ref: '#/components/requestBodies/VerifiablePresentation' 134 | responses: 135 | '202': 136 | description: Request received 137 | '400': 138 | description: Invalid SCID value 139 | '404': 140 | description: Unknown SCID value or resource not found 141 | components: 142 | schemas: 143 | EmptyResponse: 144 | type: object 145 | DataIntegrityProof: 146 | type: object 147 | properties: 148 | type: 149 | type: string 150 | example: 'DataIntegrityProof' 151 | cryptosuite: 152 | type: string 153 | example: 'eddsa-jcs-2022' 154 | verificationMethod: 155 | type: string 156 | proofValue: 157 | type: string 158 | proofPurpose: 159 | type: string 160 | example: 'assertionMethod' 161 | VerifiablePresentation: 162 | type: object 163 | properties: 164 | '@context': 165 | type: array 166 | items: 167 | type: string 168 | example: 169 | - 'https://www.w3.org/ns/credentials/v2' 170 | type: 171 | type: string 172 | example: 'VerifiablePresentation' 173 | proof: 174 | type: object 175 | properties: 176 | type: 177 | type: string 178 | example: 'DataIntegrityProof' 179 | cryptosuite: 180 | type: string 181 | example: 'eddsa-jcs-2022' 182 | verificationMethod: 183 | type: string 184 | example: 'did:key:{updateKey}' 185 | proofPurpose: 186 | type: string 187 | example: 'authentication' 188 | proofValue: 189 | type: string 190 | challenge: 191 | type: string 192 | example: "{SCID}" 193 | domain: 194 | type: string 195 | example: 'https://watcher.example.com' 196 | WitnessFile: 197 | type: object 198 | properties: 199 | versionId: 200 | type: string 201 | proof: 202 | type: array 203 | items: 204 | $ref: '#/components/schemas/DataIntegrityProof' 205 | LogFile: 206 | type: string 207 | description: The DID log file contains a list of entries, one for each version of the DID. Each entry has (per the JSON Lines specification) all extra whitespace removed, a \n character appended, and the result added to the DID Log. 208 | example: | 209 | {"versionId":"","versionTime":"","parameters":{},"state":{},"proof":[]} 210 | {"versionId":"","versionTime":"","parameters":{},"state":{},"proof":[]} 211 | {"versionId":"","versionTime":"","parameters":{},"state":{},"proof":[]} 212 | parameters: 213 | SCID: 214 | name: scid 215 | in: query 216 | description: SCID 217 | required: true 218 | schema: 219 | type: string 220 | DID: 221 | name: did 222 | in: query 223 | description: DID 224 | required: true 225 | schema: 226 | type: string 227 | resourcePath: 228 | name: path 229 | in: query 230 | description: Resource Path, this value needs to be url encoded. 231 | required: true 232 | schema: 233 | type: string 234 | requestBodies: 235 | VerifiablePresentation: 236 | description: A DataIntegrityProof used for Authentication 237 | content: 238 | application/json: 239 | schema: 240 | $ref: '#/components/schemas/VerifiablePresentation' 241 | --------------------------------------------------------------------------------