|
1 |
| -# did:key method driver _(did-method-key)_ |
| 1 | +# `did:key` DID Method Specification |
2 | 2 |
|
3 |
| -[](https://travis-ci.org/digitalbazaar/did-method-key) |
| 3 | +This repository contains the `did:key` DID Method Specification. |
4 | 4 |
|
5 |
| -> A [DID](https://w3c-ccg.github.io/did-spec/) (Decentralized Identifier) method driver for the `did-io` library and for standalone use |
6 |
| -
|
7 |
| -## Table of Contents |
8 |
| - |
9 |
| -- [Background](#background) |
10 |
| - * [Example DID Document](#example-did-document) |
11 |
| -- [Security](#security) |
12 |
| -- [Install](#install) |
13 |
| -- [Usage](#usage) |
14 |
| -- [Contribute](#contribute) |
15 |
| -- [Commercial Support](#commercial-support) |
16 |
| -- [License](#license) |
17 |
| - |
18 |
| -## Background |
19 |
| - |
20 |
| -See also (related specs): |
21 |
| - |
22 |
| -* [Decentralized Identifiers (DIDs) - Data Model and Syntaxes](https://w3c-ccg.github.io/did-spec/) |
23 |
| -* [Linked Data Cryptographic Suite Registry](https://w3c-ccg.github.io/ld-cryptosuite-registry/) |
24 |
| -* [Linked Data Proofs](https://w3c-dvcg.github.io/ld-proofs/) |
25 |
| - |
26 |
| -A `did:key` method driver for the [`did-io`](https://github.com/digitalbazaar/did-io) |
27 |
| -client library and for standalone use. |
28 |
| - |
29 |
| -The `did:key` method is used to express public keys in a way that doesn't |
30 |
| -require a DID Registry of any kind. Its general format is: |
31 |
| - |
32 |
| -``` |
33 |
| -did:key:<multibase encoded, multicodec identified, public key> |
34 |
| -``` |
35 |
| - |
36 |
| -So, for example, the following DID would be derived from a base-58 encoded |
37 |
| -ed25519 public key: |
38 |
| - |
39 |
| -``` |
40 |
| -did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH |
41 |
| -``` |
42 |
| - |
43 |
| -That DID would correspond to the following DID Document: |
44 |
| - |
45 |
| -### Example DID Document |
46 |
| - |
47 |
| -```json |
48 |
| -{ |
49 |
| - "@context": "https://w3id.org/did/v1", |
50 |
| - "id": "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH", |
51 |
| - "publicKey": [ |
52 |
| - { |
53 |
| - "id": "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH#z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH", |
54 |
| - "type": "Ed25519VerificationKey2018", |
55 |
| - "controller": "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH#z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH", |
56 |
| - "publicKeyBase58": "B12NYF8RrR3h41TDCTJojY59usg3mbtbjnFs7Eud1Y6u" |
57 |
| - } |
58 |
| - ], |
59 |
| - "authentication": [ |
60 |
| - "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH#z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH" |
61 |
| - ], |
62 |
| - "assertionMethod": [ |
63 |
| - "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH#z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH" |
64 |
| - ], |
65 |
| - "capabilityDelegation": [ |
66 |
| - "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH#z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH" |
67 |
| - ], |
68 |
| - "capabilityInvocation": [ |
69 |
| - "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH#z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH" |
70 |
| - ], |
71 |
| - "keyAgreement": [ |
72 |
| - { |
73 |
| - "id": "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH#zBzoR5sqFgi6q3iFia8JPNfENCpi7RNSTKF7XNXX96SBY4", |
74 |
| - "type": "X25519KeyAgreementKey2019", |
75 |
| - "controller": "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH", |
76 |
| - "publicKeyBase58": "JhNWeSVLMYccCk7iopQW4guaSJTojqpMEELgSLhKwRr" |
77 |
| - } |
78 |
| - ] |
79 |
| -} |
80 |
| -``` |
81 |
| - |
82 |
| -## Security |
83 |
| - |
84 |
| -The `keyAgreement` key is a Curve25519 public key (suitable for |
85 |
| -Diffie-Hellman key exchange) that is deterministically _derived_ from the source |
86 |
| -Ed25519 key, using [`ed2curve-js`](https://github.com/dchest/ed2curve-js). |
87 |
| - |
88 |
| -Note that this derived key is optional -- there's currently |
89 |
| -[no proof](https://crypto.stackexchange.com/questions/3260/using-same-keypair-for-diffie-hellman-and-signing/3311#3311) |
90 |
| -that this is safe to do. |
91 |
| - |
92 |
| -## Install |
93 |
| - |
94 |
| -Requires Node.js 8.3+ |
95 |
| - |
96 |
| -To install locally (for development): |
97 |
| - |
98 |
| -``` |
99 |
| -git clone https://github.com/digitalbazaar/did-method-key.git |
100 |
| -cd did-method-key |
101 |
| -npm install |
102 |
| -``` |
103 |
| - |
104 |
| -## Usage |
105 |
| - |
106 |
| -To generate a new key and get its corresponding `did:key` method DID Document: |
107 |
| - |
108 |
| -```js |
109 |
| -const didKeyDriver = require('did-method-key').driver(); |
110 |
| - |
111 |
| -const didDocument = await didKeyDriver.generate(); // Ed25519 key type by default |
112 |
| - |
113 |
| -JSON.stringify(didDocument, null, 2); |
114 |
| -``` |
115 |
| - |
116 |
| -To get a DID Document for an existing `did:key` DID: |
117 |
| - |
118 |
| -```js |
119 |
| -const didDocument = await didKeyDriver.get({did: 'did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH'}); |
120 |
| -``` |
121 |
| - |
122 |
| -(Results in the [example DID Doc](#example-did-document) above). |
123 |
| - |
124 |
| -If you have an existing [`crypto-ld`](https://github.com/digitalbazaar/crypto-ld) |
125 |
| -key pair, you can convert it to a `did:key` method DID Doc: |
126 |
| - |
127 |
| -```js |
128 |
| -const {Ed25519KeyPair} = require('crypto-ld'); |
129 |
| -const {keyToDidDoc} = require('did-method-key').driver(); |
130 |
| - |
131 |
| -const edKey = await Ed25519KeyPair.generate(); |
132 |
| - |
133 |
| -keyToDidDoc(edKey); |
134 |
| - |
135 |
| -// Returns a DID Document |
136 |
| -``` |
137 |
| - |
138 |
| -## Contribute |
139 |
| - |
140 |
| -See [the contribute file](https://github.com/digitalbazaar/bedrock/blob/master/CONTRIBUTING.md)! |
141 |
| - |
142 |
| -PRs accepted. |
143 |
| - |
144 |
| -Small note: If editing the Readme, please conform to the |
145 |
| -[standard-readme](https://github.com/RichardLitt/standard-readme) specification. |
146 |
| - |
147 |
| -## Commercial Support |
148 |
| - |
149 |
| -Commercial support for this library is available upon request from |
150 |
| -Digital Bazaar: support@digitalbazaar.com |
151 |
| - |
152 |
| -## License |
153 |
| - |
154 |
| -[New BSD License (3-clause)](LICENSE) © Digital Bazaar |
| 5 | +We encourage contributions meeting the |
| 6 | +[Contribution Guidelines](CONTRIBUTING.md). While we prefer the creation of |
| 7 | +issues and Pull Requests in the GitHub repository, discussions often occur on the |
| 8 | +[public-credentials](http://lists.w3.org/Archives/Public/public-credentials/) |
| 9 | +mailing list as well. |
0 commit comments