├── .gitignore
├── LICENSE.md
├── README.md
├── terms.html
├── common.js
└── index.html


/.gitignore:
--------------------------------------------------------------------------------
1 | *~
2 | .cache
3 | .project
4 | .settings
5 | 


--------------------------------------------------------------------------------
/LICENSE.md:
--------------------------------------------------------------------------------
1 | All documents in this Repository are licensed by contributors under the
2 | [W3C Software and Document License](https://www.w3.org/Consortium/Legal/copyright-software).
3 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # did:key method driver _(did-method-key)_
  2 | 
  3 | [![Build Status](https://travis-ci.org/digitalbazaar/did-method-key.png?branch=master)](https://travis-ci.org/digitalbazaar/did-method-key)
  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",
 54 |       "type": "Ed25519VerificationKey2018",
 55 |       "controller": "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH",
 56 |       "publicKeyBase58": "B12NYF8RrR3h41TDCTJojY59usg3mbtbjnFs7Eud1Y6u"
 57 |     }
 58 |   ],
 59 |   "authentication": [
 60 |     "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH"
 61 |   ],
 62 |   "assertionMethod": [
 63 |     "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH"
 64 |   ],
 65 |   "capabilityDelegation": [
 66 |     "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH"
 67 |   ],
 68 |   "capabilityInvocation": [
 69 |     "did:key: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
155 | 


--------------------------------------------------------------------------------
/terms.html:
--------------------------------------------------------------------------------
  1 | <p>
  2 | The following terms are used to describe concepts in this specification.
  3 | </p>
  4 | 
  5 | <dl class="termlist">
  6 |   <dt><dfn data-lt="claims">claim</dfn></dt>
  7 |   <dd>
  8 | An assertion made about a <a>subject</a>.
  9 |   </dd>
 10 |   <dt><dfn data-lt="credential|credentials">credential</dfn></dt>
 11 |   <dd>
 12 | A set of one or more <a>claims</a> made by an <a>issuer</a>. A
 13 | <dfn data-lt="verifiable credentials">verifiable credential</dfn> is a
 14 | tamper-evident credential that has authorship that can be cryptographically
 15 | verified. Verifiable credentials can be used to build
 16 | <a>verifiable presentations</a>, which can also be cryptographically verified.
 17 | The <a>claims</a> in a credential can be about different <a>subjects</a>.
 18 |   </dd>
 19 |   <dt><dfn>data minimization</dfn></dt>
 20 |   <dd>
 21 | The act of limiting the amount of shared data strictly to the minimum
 22 | necessary to successfully accomplish a task or goal.
 23 |   </dd>
 24 |   <dt><dfn data-lt="decentralized identifiers|DID|DIDs">decentralized identifier</dfn></dt>
 25 |   <dd>
 26 | A portable URL-based identifier, also known as a <strong><em>DID</em></strong>,
 27 | associated with an <a>entity</a>. These identifiers are most often used in a
 28 | <a>verifiable credential</a> and are associated with <a>subjects</a> such that a
 29 | <a>verifiable credential</a> itself can be easily ported from one
 30 | <a>repository</a> to another without the need to reissue the <a>credential</a>.
 31 | An example of a DID is <code>did:example:123456abcdef</code>.
 32 |   </dd>
 33 |   <dt><dfn data-lt="decentralized identifier documents|DID document|DID documents">decentralized identifier document</dfn></dt>
 34 |   <dd>
 35 | Also referred to as a <strong><em>DID document</em></strong>, this is a document 
 36 | that is accessible using a <a>verifiable data registry</a> and contains
 37 | information related to a specific <a>decentralized identifier</a>, such as the
 38 | associated <a>repository</a> and public key information.
 39 |   </dd>
 40 |   <dt><dfn data-lt="predicates|derived predicates">derived predicate</dfn></dt>
 41 |   <dd>
 42 | A verifiable, boolean assertion about the value of another attribute in a
 43 | <a>verifiable credential</a>. These are useful in zero-knowledge-proof-style
 44 | <a>verifiable presentations</a> because they can limit information disclosure.
 45 | For example, if a <a>verifiable credential</a> contains an attribute
 46 | for expressing a specific height in centimeters, a derived predicate
 47 | might reference the height attribute in the <a>verifiable credential</a>
 48 | demonstrating that the <a>issuer</a> attests to a height value meeting the
 49 | minimum height requirement, without actually disclosing the specific height
 50 | value. For example, the <a>subject</a> is taller than 150 centimeters.
 51 |   </dd>
 52 |   <dt><dfn>digital signature</dfn></dt>
 53 |   <dd>
 54 | A mathematical scheme for demonstrating the authenticity of a digital message.
 55 |   </dd>
 56 |   <dt><dfn data-lt="entities|entity's">entity</dfn></dt>
 57 |   <dd>
 58 | A thing with distinct and independent existence, such as a person,
 59 | organization, or device that performs one or more roles in the ecosystem.
 60 |   </dd>
 61 |   <dt><dfn data-lt="graphs">graph</dfn></dt>
 62 |   <dd>
 63 | A network of information composed of <a>subjects</a> and their relationship
 64 | to other <a>subjects</a> or data.
 65 |   </dd>
 66 |   <dt><dfn data-lt="holders|holder's|holders'">holder</dfn></dt>
 67 |   <dd>
 68 | A role an <a>entity</a> might perform by possessing one or more
 69 | <a>verifiable credentials</a> and generating <a>presentations</a> from them.
 70 | A holder is usually, but not always, a <a>subject</a> of the <a>verifiable
 71 | credentials</a> they are holding. Holders store their <a>credentials</a> in
 72 | <a>credential repositories</a>.
 73 |   </dd>
 74 |   <dt><dfn data-lt="identities|identity's">identity</dfn></dt>
 75 |   <dd>
 76 | The means for keeping track of <a>entities</a> across contexts. Digital
 77 | identities enable tracking and customization of <a>entity</a> interactions
 78 | across digital contexts, typically using identifiers and attributes. Unintended
 79 | distribution or use of identity information can compromise privacy. Collection
 80 | and use of such information should follow the principle of
 81 | <a>data minimization</a>.
 82 |   </dd>
 83 |   <dt><dfn data-lt="identity providers|idp">identity provider</dfn></dt>
 84 |   <dd>
 85 | An identity provider, sometimes abbreviated as <em>IdP</em>, is a system
 86 | for creating, maintaining, and managing identity information for
 87 | <a>holders</a>, while providing authentication services to
 88 | <a>relying party</a> applications within a federation or distributed network.
 89 | In this case the <a>holder</a> is always the <a>subject</a>. Even if the
 90 | <a>verifiable credentials</a> are bearer <a>credentials</a>, it is assumed the
 91 | <a>verifiable credentials</a> remain with the <a>subject</a>, and if they are
 92 | not, they were stolen by an attacker. This specification does not use this term
 93 | unless comparing or mapping the concepts in this document to other
 94 | specifications. This specification decouples the <a>identity provider</a>
 95 | concept into two distinct concepts: the <a>issuer</a> and the <a>holder</a>.
 96 |   </dd>
 97 |   <dt><dfn data-lt="issuers|issuer's">issuer</dfn></dt>
 98 |   <dd>
 99 | A role an <a>entity</a> can perform by asserting <a>claims</a> about one or
100 | more <a>subjects</a>, creating a <a>verifiable credential</a> from these
101 | <a>claims</a>, and transmitting the <a>verifiable credential</a> to a
102 | <a>holder</a>.
103 |   </dd>
104 |   <dt><dfn data-lt="presentations">presentation</dfn></dt>
105 |   <dd>
106 | Data derived from one or more <a>verifiable credentials</a>, issued by one or
107 | more <a>issuers</a>, that is shared with a specific <a>verifier</a>. A
108 | <dfn data-lt="verifiable presentations">verifiable presentation</dfn>
109 | is a tamper-evident presentation encoded in such a way that authorship of the
110 | data can be trusted after a process of cryptographic verification. Certain
111 | types of verifiable presentations might contain data that is synthesized from,
112 | but do not contain, the original <a>verifiable credentials</a> (for example,
113 | zero-knowledge proofs).
114 |   </dd>
115 |   <dt><dfn data-lt="credential repository|credential repositories|repositories">repository</dfn></dt>
116 |   <dd>
117 | A program, such as a storage vault or personal <a>verifiable credential</a>
118 | wallet, that stores and protects access to <a>holders'</a>
119 | <a>verifiable credentials</a>.
120 |   </dd>
121 |   <dt><dfn>selective disclosure</dfn></dt>
122 |   <dd>
123 | The ability of a <a>holder</a> to make fine-grained decisions about what 
124 | information to share.
125 |   </dd>
126 |   <dt><dfn data-lt="subjects|subject's">subject</dfn></dt>
127 |   <dd>
128 | A thing about which <a>claims</a> are made.
129 |   </dd>
130 |   <dt><dfn>user agent</dfn></dt>
131 |   <dd>
132 | A program, such as a browser or other Web client, that mediates the
133 | communication between <a>holders</a>, <a>issuers</a>, and <a>verifiers</a>.
134 |   </dd>
135 |   <dt><dfn data-lt="credential validation">validation</dfn></dt>
136 |   <dd>
137 | The assurance that a <a>verifiable credential</a> or a
138 | <a>verifiable presentation</a> meets the needs of a <a>verifier</a> and other
139 | dependent stakeholders. This specification is constrained to <a>verifying</a>
140 | <a>verifiable credentials</a> and <a>verifiable presentations</a> regardless of
141 | their usage. Validating <a>verifiable credentials</a> or
142 | <a>verifiable presentations</a> is outside the scope of this specification.
143 |   </dd>
144 |   <dt><dfn data-lt="verifiable data registries">verifiable data registry</dfn></dt>
145 |   <dd>
146 | A role a system might perform by mediating the creation and <a>verification</a>
147 | of identifiers, keys, and other relevant data, such as
148 | <a>verifiable credential</a> schemas, revocation registries, issuer public keys,
149 | and so on, which might be required to use <a>verifiable credentials</a>. Some
150 | configurations might require correlatable identifiers for <a>subjects</a>. Some
151 | registries, such as ones for UUIDs and public keys, might just act as namespaces
152 | for identifiers.
153 |   </dd>
154 |   <dt><dfn data-lt="verify|verified|verifying|verifiable|verifiability">verification</dfn></dt>
155 |   <dd>
156 | The evaluation of whether a <a>verifiable credential</a> or <a>verifiable presentation</a> 
157 | is an authentic and timely statement of the issuer or presenter, respectively.  
158 |     This includes checking that: the credential (or presentation) conforms to the specification; the proof method is
159 | satisfied; and, if present, the status check succeeds.
160 | 
161 |   </dd>
162 |   <dt><dfn data-lt="verifier|verifiers|verifier's|credential verifiers|credential verifier's">verifier</dfn></dt>
163 |   <dd>
164 | A role an <a>entity</a> performs by receiving one or more
165 | <a>verifiable credentials</a>, optionally inside a
166 | <a>verifiable presentation</a> for processing. Other specifications might refer
167 | to this concept as a <dfn data-lt="relying parties">relying party</dfn>.
168 |   </dd>
169 |   <dt><dfn data-lt="URI|URIs">URI</dfn></dt>
170 |   <dd>
171 | A Uniform Resource Identifier, as defined by [[RFC3986]].
172 |   </dd>
173 | </dl>
174 | 


--------------------------------------------------------------------------------
/common.js:
--------------------------------------------------------------------------------
  1 | /* globals omitTerms, respecConfig, $, require */
  2 | /* exported linkCrossReferences, restrictReferences, fixIncludes */
  3 | 
  4 | var ccg = {
  5 |   // Add as the respecConfig localBiblio variable
  6 |   // Extend or override global respec references
  7 |   localBiblio: {
  8 |     "REST": {
  9 |       title: "Architectural Styles and the Design of Network-based Software Architectures",
 10 |       date: "2000",
 11 |       href: "http://www.ics.uci.edu/~fielding/pubs/dissertation/",
 12 |       authors: [
 13 |         "Fielding, Roy Thomas"
 14 |       ],
 15 |       publisher: "University of California, Irvine."
 16 |     },
 17 |     "VC-USECASES": {
 18 |       title: "Verifiable Claims Use Cases",
 19 |       href: "https://www.w3.org/TR/verifiable-claims-use-cases/",
 20 |       authors: [
 21 |       	"Shane McCarron",
 22 |         "Daniel Burnett",
 23 |         "Gregg Kellogg",
 24 |         "Brian Sletten",
 25 |         "Manu Sporny"
 26 |       ],
 27 |       status: "NOTE",
 28 |       publisher: "Verifiable Claims Working Group"
 29 |     },
 30 |     "VC-EXTENSION-REGISTRY": {
 31 |       title: "Verifiable Credentials Extension Registry",
 32 |       href: "https://w3c-ccg.github.io/vc-extension-registry/",
 33 |       authors: [
 34 |         "Manu Sporny"
 35 |       ],
 36 |       status: "CG-DRAFT",
 37 |       publisher: "Credentials Community Group"
 38 |     },
 39 |     "STRING-META": {
 40 |       title: "Strings on the Web: Language and Direction Metadata",
 41 |       href: "https://www.w3.org/TR/string-meta/",
 42 |       authors: [
 43 |         "Addison Phillips",
 44 |         "Richard Ishida"
 45 |       ],
 46 |       status: "WD",
 47 |       publisher: "Internationalization Working Group"
 48 |     },
 49 |     "LD-PROOFS": {
 50 |       title: "Linked Data Proofs",
 51 |       href: "https://w3c-dvcg.github.io/ld-proofs/",
 52 |       authors: [
 53 |         "Manu Sporny",
 54 |         "Dave Longley"
 55 |       ],
 56 |       status: "CG-DRAFT",
 57 |       publisher: "Digital Verification Community Group"
 58 |     },
 59 |     "LD-SIGNATURES": {
 60 |       title: "Linked Data Signatures",
 61 |       href: "https://w3c-dvcg.github.io/ld-signatures/",
 62 |       authors: [
 63 |         "Manu Sporny",
 64 |         "Dave Longley"
 65 |       ],
 66 |       status: "CG-DRAFT",
 67 |       publisher: "Digital Verification Community Group"
 68 |     },
 69 |     "LDS-RSA2018": {
 70 |       title: "The 2018 RSA Linked Data Signature Suite",
 71 |       href: "https://w3c-dvcg.github.io/lds-rsa2018/",
 72 |       authors: [
 73 |         "Manu Sporny",
 74 |         "Dave Longley"
 75 |       ],
 76 |       status: "CG-DRAFT",
 77 |       publisher: "Digital Verification Community Group"
 78 |     },
 79 |     "MULTIBASE": {
 80 |       title: "Multibase",
 81 |       href: "https://tools.ietf.org/html/draft-multiformats-multibase",
 82 |       authors: [
 83 |         "Juan Benet",
 84 |         "Manu Sporny"
 85 |       ],
 86 |       status: "Independent Draft",
 87 |       publisher: "IETF"
 88 |     },
 89 |     "MULTICODEC": {
 90 |       title: "Multibase",
 91 |       href: "https://github.com/multiformats/multicodec/blob/master/README.md",
 92 |       authors: [
 93 |         "Juan Benet",
 94 |         "Manu Sporny"
 95 |       ],
 96 |       status: "Independent Draft",
 97 |       publisher: "IETF"
 98 |     },
 99 |     "CL-SIGNATURES": {
100 |       title: "A Signature Scheme with Efficient Protocols",
101 |       href: "http://groups.csail.mit.edu/cis/pubs/lysyanskaya/cl02b.pdf",
102 |       authors: [
103 |         "Jan Camenisch",
104 |         "Anna Lysyanskaya"
105 |       ],
106 |       status: "Peer Reviewed Paper",
107 |       publisher: "IBM Research"
108 |     },
109 |     // aliases to known references
110 |     "HTTP-SIGNATURES": {
111 |       aliasOf: "http-signatures"
112 |     },
113 |     "MACAROONS": {
114 |       title: 'Macaroons',
115 |       // TODO: create spec
116 |       href: 'http://macaroons.io/',
117 |       authors: ['Arnar Birgisson', 'Joe Gibbs Politz', 'Úlfar Erlingsson',
118 |         'Ankur Taly', 'Michael Vrable', 'Mark Lentczner'],
119 |       status: 'unofficial',
120 |       publisher: 'Credentials Community Group'
121 |     },
122 |     'OPEN-BADGES': {
123 |       title: 'Open Badges',
124 |       href: 'https://github.com/openbadges/openbadges-specification',
125 |       authors: ['Brian Brennan', 'Mike Larsson', 'Chris McAvoy',
126 |         'Nate Otto', 'Kerri Lemoie'],
127 |       status:   'BA-DRAFT',
128 |       publisher:  'Badge Alliance Standard Working Group'
129 |     },
130 |     'RDF-NORMALIZATION': {
131 |       title: 'RDF Dataset Normalization',
132 |       href: 'http://json-ld.github.io/normalization/spec/',
133 |       authors: ['Dave Longley', 'Manu Sporny'],
134 |       status:   'CG-DRAFT',
135 |       publisher:  'Credentials W3C Community Group'
136 |     },
137 |     'DEMOGRAPHICS': {
138 |       title: 'Simple Demographics Often Identify People Uniquely',
139 |       href: 'http://dataprivacylab.org/projects/identifiability/paper1.pdf',
140 |       authors: ['Latanya Sweeney'],
141 |       publisher: 'Data Privacy Lab'
142 |     },
143 |     'VC-IMP-GUIDE': {
144 |       title: 'Verifiable Credentials Implementation Guidelines 1.0',
145 |       href: 'https://w3c.github.io/vc-imp-guide/',
146 |       authors: ['Andrei Sambra', 'Manu Sporny'],
147 |       status: 'ED',
148 |       publisher: 'Credentials Community Group'
149 |     },
150 |     'HASHLINK': {
151 |       title: 'Cryptographic Hyperlinks',
152 |       href: 'https://tools.ietf.org/html/draft-sporny-hashlink',
153 |       authors: ['Manu Sporny'],
154 |       status: 'Internet-Draft',
155 |       publisher: 'Internet Engineering Task Force (IETF)'
156 |     },
157 |     'IPFS': {
158 |       title: 'InterPlanetary File System (IPFS)',
159 |       href: 'https://en.wikipedia.org/wiki/InterPlanetary_File_System',
160 |       publisher: 'Wikipedia'
161 |     },
162 |     'JSON-SCHEMA-2018': {
163 |       title: 'JSON Schema: A Media Type for Describing JSON Documents',
164 |       href: 'https://tools.ietf.org/html/draft-handrews-json-schema',
165 |       authors: ['Austin Wright', 'Henry Andrews'],
166 |       status: 'Internet-Draft',
167 |       publisher: 'Internet Engineering Task Force (IETF)'
168 |     },
169 |     'JSON-LD': {
170 |       title: 'JSON-LD 1.1: A JSON-based Serialization for Linked Data',
171 |       href: 'https://www.w3.org/TR/json-ld11/',
172 |       authors: ['Gregg Kellogg', 'Manu Sporny', 'Dave Longley', 'Markus Lanthaler', 'Pierre-Antoine Champin', 'Niklas Lindström'],
173 |       status: 'WD',
174 |       publisher: 'W3C JSON-LD 1.1 Working Group'
175 |     }
176 |   }
177 | };
178 | 
179 | 
180 | 
181 | // We should be able to remove terms that are not actually
182 | // referenced from the common definitions
183 | //
184 | // the termlist is in a block of class "termlist", so make sure that
185 | // has an ID and put that ID into the termLists array so we can
186 | // interrogate all of the included termlists later.
187 | var termNames = [] ;
188 | var termLists = [] ;
189 | var termsReferencedByTerms = [] ;
190 | 
191 | function restrictReferences(utils, content) {
192 |     "use strict";
193 |     var base = document.createElement("div");
194 |     base.innerHTML = content;
195 | 
196 |     // New new logic:
197 |     //
198 |     // 1. build a list of all term-internal references
199 |     // 2. When ready to process, for each reference INTO the terms,
200 |     // remove any terms they reference from the termNames array too.
201 |     $.each(base.querySelectorAll("dfn"), function(i, item) {
202 |         var $t = $(item) ;
203 |         var titles = $t.getDfnTitles();
204 |         var dropit = false;
205 |         // do we have an omitTerms
206 |         if (window.hasOwnProperty("omitTerms")) {
207 |             // search for a match
208 |             $.each(omitTerms, function(j, term) {
209 |                 if (titles.indexOf(term) !== -1) {
210 |                     dropit = true;
211 |                 }
212 |             });
213 |         }
214 |         // do we have an includeTerms
215 |         if (window.hasOwnProperty("includeTerms")) {
216 |             var found = false;
217 |             // search for a match
218 |             $.each(includeTerms, function(j, term) {
219 |                 if (titles.indexOf(term) !== -1) {
220 |                     found = true;
221 |                 }
222 |             });
223 |             if (!found) {
224 |                 dropit = true;
225 |             }
226 |         }
227 |         if (dropit) {
228 |             $t.parent().next().remove();
229 |             $t.parent().remove();
230 |         } else {
231 |             var n = $t.makeID("dfn", titles[0]);
232 |             if (n) {
233 |                 termNames[n] = $t.parent() ;
234 |             }
235 |         }
236 |     });
237 | 
238 |     var $container = $(".termlist",base) ;
239 |     var containerID = $container.makeID("", "terms") ;
240 |     termLists.push(containerID) ;
241 | 
242 |     return (base.innerHTML);
243 | }
244 | // add a handler to come in after all the definitions are resolved
245 | //
246 | // New logic: If the reference is within a 'dl' element of
247 | // class 'termlist', and if the target of that reference is
248 | // also within a 'dl' element of class 'termlist', then
249 | // consider it an internal reference and ignore it.
250 | 
251 | require(["core/pubsubhub"], function(respecEvents) {
252 |     "use strict";
253 |     respecEvents.sub('end', function(message) {
254 |         if (message === 'core/link-to-dfn') {
255 |             // all definitions are linked; find any internal references
256 |             $(".termlist a.internalDFN").each(function() {
257 |                 var $r = $(this);
258 |                 var id = $r.attr('href');
259 |                 var idref = id.replace(/^#/,"") ;
260 |                 if (termNames[idref]) {
261 |                     // this is a reference to another term
262 |                     // what is the idref of THIS term?
263 |                     var $def = $r.closest('dd') ;
264 |                     if ($def.length) {
265 |                         var $p = $def.prev('dt').find('dfn') ;
266 |                         var tid = $p.attr('id') ;
267 |                         if (tid) {
268 |                             if (termsReferencedByTerms[tid]) {
269 |                                 termsReferencedByTerms[tid].push(idref);
270 |                             } else {
271 |                                 termsReferencedByTerms[tid] = [] ;
272 |                                 termsReferencedByTerms[tid].push(idref);
273 |                             }
274 |                         }
275 |                     }
276 |                 }
277 |             }) ;
278 | 
279 |             // clearRefs is recursive.  Walk down the tree of
280 |             // references to ensure that all references are resolved.
281 |             var clearRefs = function(theTerm) {
282 |                 if ( termsReferencedByTerms[theTerm] ) {
283 |                     $.each(termsReferencedByTerms[theTerm], function(i, item) {
284 |                         if (termNames[item]) {
285 |                             delete termNames[item];
286 |                             clearRefs(item);
287 |                         }
288 |                     });
289 |                 }
290 |                 // make sure this term doesn't get removed
291 |                 if (termNames[theTerm]) {
292 |                     delete termNames[theTerm];
293 |                 }
294 |             };
295 | 
296 |             // now termsReferencedByTerms has ALL terms that
297 |             // reference other terms, and a list of the
298 |             // terms that they reference
299 |             $("a.internalDFN").each(function () {
300 |                 var $item = $(this) ;
301 |                 var t = $item.attr('href');
302 |                 var r = t.replace(/^#/,"") ;
303 |                 // if the item is outside the term list
304 |                 if ( ! $item.closest('dl.termlist').length ) {
305 |                     clearRefs(r);
306 |                 }
307 |             });
308 | 
309 |             // delete any terms that were not referenced.
310 |             /*
311 |             Object.keys(termNames).forEach(function(term) {
312 |                 var $p = $("#"+term) ;
313 |                 if ($p) {
314 |                     var tList = $p.getDfnTitles();
315 |                     $p.parent().next().remove();
316 |                     $p.parent().remove() ;
317 |                     tList.forEach(function( item ) {
318 |                       console.log("CHECKING ITEM", item, respecConfig);
319 |                         if (respecConfig.definitionMap[item]) {
320 |                             delete respecConfig.definitionMap[item];
321 |                         }
322 |                     });
323 |                 }
324 |             });*/
325 |         }
326 |     });
327 | });
328 | 


--------------------------------------------------------------------------------
/index.html:
--------------------------------------------------------------------------------
  1 | <!DOCTYPE html>
  2 | <html>
  3 |   <head>
  4 |     <title>The did:key Method v0.7</title>
  5 |     <meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
  6 |     <!--
  7 |       === NOTA BENE ===
  8 |       For the three scripts below, if your spec resides on dev.w3 you can check them
  9 |       out in the same tree and use relative links so that they'll work offline,
 10 |      -->
 11 |     <script src='https://www.w3.org/Tools/respec/respec-w3c-common' class='remove'></script>
 12 |     <script src="./common.js" class="remove"></script>
 13 |     <script type="text/javascript" class="remove">
 14 |       var respecConfig = {
 15 |         // specification status (e.g., WD, LCWD, NOTE, etc.). If in doubt use ED.
 16 |         specStatus: "unofficial",
 17 | 
 18 |         // the specification's short name, as in http://www.w3.org/TR/short-name/
 19 |         shortName: "did-method-key",
 20 | 
 21 |         // subtitle for the spec
 22 |         subtitle: "A DID Method for Static Cryptographic Keys",
 23 | 
 24 |         // if you wish the publication date to be other than today, set this
 25 |         //publishDate: "",
 26 |         //crEnd: "",
 27 |         //prEnd: "",
 28 |         //implementationReportURI: "",
 29 | 
 30 |         // if there is a previously published draft, uncomment this and set its YYYY-MM-DD date
 31 |         // and its maturity status
 32 |         // previousPublishDate:  "1977-03-15",
 33 |         // previousMaturity:  "WD",
 34 | 
 35 |         // extend the bibliography entries
 36 |         localBiblio: ccg.localBiblio,
 37 |         doJsonLd: true,
 38 | 
 39 |         github: "https://github.com/digitalbazaar/did-method-key/",
 40 |         includePermalinks: false,
 41 | 
 42 |         // if there a publicly available Editor's Draft, this is the link
 43 |         edDraftURI: "https://digitalbazaar.github.io/did-method-key/",
 44 | 
 45 |         // if this is a LCWD, uncomment and set the end of its review period
 46 |         // lcEnd: "2009-08-05",
 47 | 
 48 |         // editors, add as many as you like
 49 |         // only "name" is required
 50 |         editors: [
 51 |           { name: "Manu Sporny", url: "https://www.linkedin.com/in/manusporny/",
 52 |             company: "Digital Bazaar", companyURL: "https://digitalbazaar.com/"},
 53 |           { name: "Dmitri Zagidulin", url: "https://www.linkedin.com/in/dzagidulin/",
 54 |             company: "Digital Bazaar", companyURL: "https://digitalbazaar.com/"},
 55 |           { name: "Dave Longley", url: "https://github.com/dlongley",
 56 |             company: "Digital Bazaar", companyURL: "https://digitalbazaar.com/"}
 57 |         ],
 58 |         // authors, add as many as you like.
 59 |         // This is optional, uncomment if you have authors as well as editors.
 60 |         // only "name" is required. Same format as editors.
 61 |         authors:
 62 |         [
 63 |           { name: "Dave Longley", url: "https://digitalbazaar.com/",
 64 |             company: "Digital Bazaar", companyURL: "https://digitalbazaar.com/"},
 65 |           { name: "Dmitri Zagidulin", url: "https://www.linkedin.com/in/dzagidulin/",
 66 |             company: "Digital Bazaar", companyURL: "https://digitalbazaar.com/"},
 67 |           { name: "Manu Sporny", url: "https://digitalbazaar.com/",
 68 |             company: "Digital Bazaar", companyURL: "https://digitalbazaar.com/" }
 69 |         ],
 70 |         // name of the WG
 71 |         wg:           "W3C Credentials Community Group",
 72 | 
 73 |         // URI of the public WG page
 74 |         wgURI:        "https://digitalbazaar.com/",
 75 | 
 76 |         // name (with the @w3c.org) of the public mailing to which comments are due
 77 |         wgPublicList: "public-credentials",
 78 | 
 79 |         // URI of the patent status for this WG, for Rec-track documents
 80 |         // !!!! IMPORTANT !!!!
 81 |         // This is important for Rec-track documents, do not copy a patent URI from a random
 82 |         // document unless you know what you're doing. If in doubt ask your friendly neighborhood
 83 |         // Team Contact.
 84 |         wgPatentURI:  "https://www.w3.org/2004/01/pp-impl/98922/status",
 85 |         maxTocLevel: 2,
 86 |         inlineCSS: true
 87 |       };
 88 |     </script>
 89 |     <style>
 90 | pre .highlight {
 91 |   font-weight: bold;
 92 |   color: Green;
 93 | }
 94 | pre .subject {
 95 |   font-weight: bold;
 96 |   color: RoyalBlue;
 97 | }
 98 | pre .property {
 99 |   font-weight: bold;
100 |   color: DarkGoldenrod;
101 | }
102 | pre .comment {
103 |   font-weight: bold;
104 |   color: SteelBlue;
105 |   -webkit-user-select: none;
106 |   -moz-user-select: none;
107 |   -ms-user-select: none;
108 |   user-select: none;
109 | }
110 | .color-text {
111 |   font-weight: bold;
112 |   text-shadow: -1px 0 black, 0 1px black, 1px 0 black, 0 -1px black;
113 | }
114 |     </style>
115 |   </head>
116 |   <body>
117 |     <section id='abstract'>
118 |       <p>
119 | Decentralized Identifiers (DIDs) are a new type of identifier for verifiable,
120 | decentralized digital identity. These new identifiers are designed to enable the
121 | controller of a DID to prove control over it and to be implemented independently
122 | of any centralized registry, identity provider, or certificate authority.
123 | These sorts of identifiers often utilize a heavy-weight registry, such as ones
124 | utilizing Decentralized Ledger Technologies (DLT), to create, read, update,
125 | and deactivate DIDs. This specification describes a non-registry based DID
126 | Method based on expanding a cryptographic public key into a DID Document. This
127 | approach provides the simplest possible implementation of a DID Method that
128 | is able to achive many, but not all, of the benefits of utilizing DIDs.
129 |       </p>
130 |     </section>
131 | 
132 |     <section id='sotd'>
133 | 
134 |       <p>
135 | Portions of the work on this specification have been funded by the
136 | United States Department of Homeland Security's Science and Technology
137 | Directorate under contract HSHQDC-17-C-00019. The content of this specification
138 | does not necessarily reflect the position or the policy of the U.S. Government
139 | and no official endorsement should be inferred.
140 |       </p>
141 | 
142 |     </section>
143 | 
144 |     <section class="informative">
145 |       <h2>Introduction</h2>
146 | 
147 |       <p>
148 | Decentralized Identifiers (DIDs) [[DID-CORE]] are a new type of identifier for
149 | verifiable, decentralized digital identity. These new identifiers are designed
150 | to enable the controller of a DID to prove control over it and to be implemented
151 | independently of any centralized registry, identity provider, or certificate
152 | authority. These sorts of identifiers often utilize a heavy-weight registry,
153 | such as ones utilizing Decentralized Ledger Technologies (DLT), to create, read,
154 | update, and deactivate DIDs.
155 |       </p>
156 | 
157 |       <p>
158 | While DLT-based DID Methods have great decentralization characteristics, and
159 | some of the more centralized DID Methods provide strong system control
160 | guarantees, the general approaches tend to be expensive to setup and operate.
161 | Some use cases requiring DIDs do not need the guarantees provided by these
162 | heavy-weight systems. For example, a DID that will only be used for a single,
163 | ephemeral interaction might not need to be registered, updated, or deactivated.
164 | It is for this class of use cases that the <tt>did:key</tt> method exists.
165 |       </p>
166 | 
167 |       <p>
168 | The rest of this document outlines the syntax for the <tt>did:key</tt> method,
169 | the operations it supports, and some security and privacy considerations that
170 | implementers might want to be aware of when implementing.
171 |       </p>
172 | 
173 |       </section>
174 | 
175 |     </section>
176 | 
177 |     <section class="normative">
178 |       <h2 id="format">The did:key Format</h2>
179 | 
180 |       <p>
181 | The format for the <tt>did:key</tt> method conforms to the [[DID-CORE]]
182 | specification and is simple. It consists of the <code>did:key</code> prefix,
183 | followed by a Multibase [[MULTIBASE]] base58-btc encoded value that is a
184 | concatenation of the Multicodec [[MULTICODEC]] identifier for the public key
185 | type and the raw bytes associated with the public key format.
186 |       </p>
187 | 
188 |       <p>
189 | The ABNF for the key format is described below:
190 |       </p>
191 | 
192 |       <pre>
193 | did-key-format := did:key:&lt;mb-value>
194 | mb-value       := z[a-km-zA-HJ-NP-Z1-9]+
195 |       </pre>
196 | 
197 |       <p>
198 | Alternatively, the encoding rules can also be thought of as the application
199 | of a series of transformation functions on the raw public key bytes:
200 |       </p>
201 | 
202 |       <tt>
203 | did-key-format := did:key:MULTIBASE(base58-btc, MULTICODEC(public-key-type, raw-public-key-bytes))
204 |       </tt>
205 | 
206 |       <p>
207 | A simple example of a valid Ed25519 <tt>did:key</tt> DID is:
208 |       </p>
209 | 
210 |       <pre class="example" title="A simple Ed25519 did:key value">
211 | did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH
212 |       </pre>
213 | 
214 |     </section>
215 | 
216 |     <section class="normative">
217 |       <h2>Operations</h2>
218 | 
219 |       <p>
220 | The following section outlines the DID operations for the <tt>did:key</tt>
221 | method. Implementers might note that this DID Method is purely generative,
222 | requiring no look ups in a registry. Since <tt>did:key</tt> values are not
223 | stored in any registry, they cannot be updated or deactivated.
224 |       </p>
225 | 
226 |       <section class="normative">
227 |         <h3>Create</h3>
228 | 
229 |         <p>
230 | Creating a <tt>did:key</tt> value consists of creating a cryptographic key pair
231 | and encoding the public key using the format provided in  Section <a
232 | href="#format"></a>. The creation of a DID Document is also performed by taking
233 | the public key value and expanding it into DID Document. An example is given
234 | below that expands the ed25519 <tt>did:key</tt>
235 | <code>did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH</code> into its
236 | associated DID Document:
237 |         </p>
238 | 
239 |         <pre class="example" title="A DID Document derived from a did:key">
240 | {
241 |   "@context": "https://w3id.org/did/v1",
242 |   "id": "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH",
243 |   "publicKey": [{
244 |     "id": "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH#pubkey",
245 |     "type": "Ed25519VerificationKey2018",
246 |     "controller": "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH",
247 |     "publicKeyBase58": "B12NYF8RrR3h41TDCTJojY59usg3mbtbjnFs7Eud1Y6u"
248 |   }],
249 |   "authentication": [ "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH#pubkey" ],
250 |   "assertionMethod": [ "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH#pubkey" ],
251 |   "capabilityDelegation": [ "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH#pubkey" ],
252 |   "capabilityInvocation": [ "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH#pubkey" ],
253 |   "keyAgreement": [{
254 |     "id": "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH#kakey",
255 |     "type": "X25519KeyAgreementKey2019",
256 |     "controller": "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH",
257 |     "publicKeyBase58": "JhNWeSVLMYccCk7iopQW4guaSJTojqpMEELgSLhKwRr"
258 |   }]
259 | }
260 |         </pre>
261 |       </section>
262 | 
263 |       <section class="normative">
264 |         <h3>Read</h3>
265 | 
266 |         <p>
267 | Reading a <tt>did:key</tt> value is a matter of deterministically expanding  the
268 | value to a DID Document. This process is described in Section <a
269 | href="#create"></a>.
270 |         </p>
271 |       </section>
272 | 
273 |       <section class="normative">
274 |         <h3>Update</h3>
275 | 
276 |         <p>
277 | This DID Method does not support updating the DID Document.
278 |         </p>
279 |       </section>
280 | 
281 |       <section class="normative">
282 |         <h3>Deactivate</h3>
283 | 
284 |         <p>
285 | This DID Method does not support deactivating the DID Document.
286 |         </p>
287 |       </section>
288 | 
289 |     </section>
290 | 
291 |     <section class="informative">
292 |       <h2>Security and Privacy Considerations</h2>
293 | 
294 |       <p>
295 | There are a number of security and privacy considerations that implementers
296 | will want to take into consideration when implementing this specification.
297 |       </p>
298 | 
299 |       <section class="informative">
300 |         <h3>Key Rotation Not Supported</h3>
301 | 
302 |         <p>
303 | The <tt>did:key</tt> method is a purely generative method, which means that
304 | updates are not supported. This can be an issue if a <tt>did:key</tt> is
305 | expected to be used over a long period of time. For example, if a
306 | <tt>did:key</tt> is ever compromised, it is not possible to rotate the
307 | compromised key. For this reason, using a <tt>did:key</tt> for interactions
308 | that last weeks to months is strongly discouraged.
309 |         </p>
310 |       </section>
311 | 
312 |       <section class="informative">
313 |         <h3>Deactivation Not Supported</h3>
314 | 
315 |         <p>
316 | The <tt>did:key</tt> method is a purely generative method, which means that
317 | deactivations are not supported. This can be an issue if a <tt>did:key</tt> is
318 | expected to be used over a long period of time. For example, if a
319 | <tt>did:key</tt> is ever compromised, it is not possible to deactivate the  DID
320 | to stop an attacker from using it. For this reason, using a <tt>did:key</tt> for
321 | interactions that last weeks to months is strongly discouraged.
322 |         </p>
323 |       </section>
324 | 
325 |       <section class="informative">
326 |         <h3>Key Derivation Lacks Proof</h3>
327 | 
328 |         <p>
329 | Some implementations might utlize a key derivation function when converting from
330 | an ed25519 public key to a Curve25519 ECDH key, used in the
331 | <code>keyAgreement</code> verification method. It is expected that this is a
332 | relatively safe operation, but implementers might consider that there exists no
333 | mathematical proof that confirms this assumption.
334 |         </p>
335 |       </section>
336 | 
337 |       <section class="informative">
338 |         <h3>Long Term Usage is Discouraged</h3>
339 | 
340 |         <p>
341 | Since there is no support for update and deactivate for the <tt>did:key</tt>
342 | method, it is not possible to recover from a security compromise. For this
343 | reason, using a <tt>did:key</tt> for interactions that last weeks to months is
344 | strongly discouraged.
345 |         </p>
346 |       </section>
347 | 
348 |     </section>
349 | 
350 |   </section>
351 | 
352 |   <section class="appendix informative">
353 |     <h2>Acknowledgements</h2>
354 | 
355 |     <p>
356 | The Working Group would like to thank the following individuals for reviewing
357 | and providing feedback on the specification (in alphabetical order):
358 |     </p>
359 | 
360 |     <p>
361 | TBD...
362 |     </p>
363 |   </section>
364 |   </body>
365 | </html>
366 | 


--------------------------------------------------------------------------------