-
Notifications
You must be signed in to change notification settings - Fork 12
/
index.html
1096 lines (986 loc) · 42 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html>
<head>
<title>The did:key Method v0.7</title>
<meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
<!--
=== NOTA BENE ===
For the three scripts below, if your spec resides on dev.w3 you can check them
out in the same tree and use relative links so that they'll work offline,
-->
<script src='https://www.w3.org/Tools/respec/respec-w3c-common' class='remove'></script>
<script src="./common.js" class="remove"></script>
<script type="text/javascript" class="remove">
var respecConfig = {
// specification status (e.g., WD, LCWD, NOTE, etc.). If in doubt use ED.
specStatus: "unofficial",
// the specification's short name, as in http://www.w3.org/TR/short-name/
shortName: "did-method-key",
// subtitle for the spec
subtitle: "A DID Method for Static Cryptographic Keys",
// if you wish the publication date to be other than today, set this
//publishDate: "",
//crEnd: "",
//prEnd: "",
//implementationReportURI: "",
// if there is a previously published draft, uncomment this and set its YYYY-MM-DD date
// and its maturity status
// previousPublishDate: "1977-03-15",
// previousMaturity: "WD",
// extend the bibliography entries
localBiblio: ccg.localBiblio,
doJsonLd: true,
github: "https://github.com/w3c-ccg/did-method-key",
includePermalinks: false,
// if there a publicly available Editor's Draft, this is the link
edDraftURI: "https://w3c-ccg.github.io/did-method-key/",
// if this is a LCWD, uncomment and set the end of its review period
// lcEnd: "2009-08-05",
// editors, add as many as you like
// only "name" is required
editors: [
{ name: "Manu Sporny", url: "https://www.linkedin.com/in/manusporny/",
company: "Digital Bazaar", companyURL: "https://digitalbazaar.com/"},
{ name: "Dmitri Zagidulin", url: "https://www.linkedin.com/in/dzagidulin/",
company: "Digital Bazaar", companyURL: "https://digitalbazaar.com/"},
{ name: "Dave Longley", url: "https://github.com/dlongley",
company: "Digital Bazaar", companyURL: "https://digitalbazaar.com/"},
{ name: "Orie Steele", url: "https://github.com/OR13",
company: "Transmute", companyURL: "https://transmute.industries/"}
],
// authors, add as many as you like.
// This is optional, uncomment if you have authors as well as editors.
// only "name" is required. Same format as editors.
authors:
[
{ name: "Dave Longley", url: "https://digitalbazaar.com/",
company: "Digital Bazaar", companyURL: "https://digitalbazaar.com/"},
{ name: "Dmitri Zagidulin", url: "https://www.linkedin.com/in/dzagidulin/",
company: "Digital Bazaar", companyURL: "https://digitalbazaar.com/"},
{ name: "Manu Sporny", url: "https://digitalbazaar.com/",
company: "Digital Bazaar", companyURL: "https://digitalbazaar.com/" }
],
// name of the WG
wg: "W3C Credentials Community Group",
// URI of the public WG page
wgURI: "https://www.w3.org/community/credentials/",
// name (with the @w3c.org) of the public mailing to which comments are due
wgPublicList: "public-credentials",
// URI of the patent status for this WG, for Rec-track documents
// !!!! IMPORTANT !!!!
// This is important for Rec-track documents, do not copy a patent URI from a random
// document unless you know what you're doing. If in doubt ask your friendly neighborhood
// Team Contact.
wgPatentURI: "https://www.w3.org/2004/01/pp-impl/98922/status",
maxTocLevel: 2,
inlineCSS: true
};
</script>
<style>
pre .highlight {
font-weight: bold;
color: Green;
}
pre .subject {
font-weight: bold;
color: RoyalBlue;
}
pre .property {
font-weight: bold;
color: DarkGoldenrod;
}
pre .comment {
font-weight: bold;
color: SteelBlue;
-webkit-user-select: none;
-moz-user-select: none;
-ms-user-select: none;
user-select: none;
}
.color-text {
font-weight: bold;
text-shadow: -1px 0 black, 0 1px black, 1px 0 black, 0 -1px black;
}
ol.algorithm { counter-reset:numsection; list-style-type: none; }
ol.algorithm li { margin: 0.5em 0; }
ol.algorithm li:before { font-weight: bold; counter-increment: numsection; content: counters(numsection, ".") ") "; }
</style>
</head>
<body>
<section id='abstract'>
<p>
Decentralized Identifiers (DIDs) are a new type of identifier for verifiable,
decentralized digital identity. These new identifiers are designed to enable the
controller of a DID to prove control over it and to be implemented independently
of any centralized registry, identity provider, or certificate authority.
These sorts of identifiers often utilize a heavy-weight registry, such as ones
utilizing Decentralized Ledger Technologies (DLT), to create, read, update,
and deactivate DIDs. This specification describes a non-registry based DID
Method based on expanding a cryptographic public key into a DID Document. This
approach provides the simplest possible implementation of a DID Method that
is able to achieve many, but not all, of the benefits of utilizing DIDs.
</p>
</section>
<section id='sotd'>
<p>
Portions of the work on this specification have been funded by the
United States Department of Homeland Security's Science and Technology
Directorate under contract HSHQDC-17-C-00019. The content of this specification
does not necessarily reflect the position or the policy of the U.S. Government
and no official endorsement should be inferred.
</p>
</section>
<section class="informative">
<h2>Introduction</h2>
<p>
Decentralized Identifiers (DIDs) [[DID-CORE]] are a new type of identifier for
verifiable, decentralized digital identity. These new identifiers are designed
to enable the controller of a DID to prove control over it and to be implemented
independently of any centralized registry, identity provider, or certificate
authority. These sorts of identifiers often utilize a heavy-weight registry,
such as ones utilizing Decentralized Ledger Technologies (DLT), to create, read,
update, and deactivate DIDs.
</p>
<p>
While DLT-based DID Methods have great decentralization characteristics, and
some of the more centralized DID Methods provide strong system control
guarantees, the general approaches tend to be expensive to setup and operate.
Some use cases requiring DIDs do not need the guarantees provided by these
heavy-weight systems. For example, a DID that will only be used for a single,
ephemeral interaction might not need to be registered, updated, or deactivated,
or where private keys are protected by software or hardware isolation.
These are a few of the cases where using <tt>did:key</tt> might offer unique benefits.
</p>
<p class="advisement">
Use of <tt>did:key</tt> for long-lived use cases is only recommended when accompanied with high confidence in hardware isolation.
</p>
<p>
The rest of this document outlines the syntax for the <tt>did:key</tt> method,
the operations it supports, and some security and privacy considerations that
implementers might want to be aware of when implementing.
</p>
</section>
<section class="normative">
<h2 id="format">The did:key Format</h2>
<p>
The format for the <tt>did:key</tt> method conforms to the [[DID-CORE]]
specification and is simple. It consists of the <code>did:key</code> prefix,
followed by a Multibase [[MULTIBASE]] base58-btc encoded value that is a
concatenation of the Multicodec [[MULTICODEC]] identifier for the public key
type and the raw bytes associated with the public key format.
</p>
<p>
The ABNF for the key format is described below:
</p>
<pre>
did-key-format := did:key:<mb-value>
mb-value := z[a-km-zA-HJ-NP-Z1-9]+
</pre>
<p>
Alternatively, the encoding rules can also be thought of as the application
of a series of transformation functions on the raw public key bytes:
</p>
<tt>
did-key-format := did:key:MULTIBASE(base58-btc, MULTICODEC(public-key-type, raw-public-key-bytes))
</tt>
<p>
A simple example of a valid Ed25519 <tt>did:key</tt> DID is:
</p>
<pre class="example" title="A simple Ed25519 did:key value">
did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK
</pre>
</section>
<section class="normative">
<h2>Operations</h2>
<p>
The following section outlines the DID operations for the <tt>did:key</tt>
method. Implementers might note that this DID Method is purely generative,
requiring no look ups in a registry. Since <tt>did:key</tt> values are not
stored in any registry, they cannot be updated or deactivated.
</p>
<section class="normative">
<h3>Create</h3>
<p>
Creating a <tt>did:key</tt> value consists of creating a cryptographic key pair
and encoding the public key using the format provided in Section <a
href="#format"></a>. The creation of a DID Document is also performed by taking
the public key value and expanding it into DID Document. An example is given
below that expands the ed25519 <tt>did:key</tt>
<code>did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK</code> into its
associated DID Document:
</p>
<pre class="example" title="An example of a did:key DID Document"
style="font-size: 0.65em;">
{
"@context": [
"https://www.w3.org/ns/did/v1",
"https://w3id.org/security/suites/ed25519-2020/v1",
"https://w3id.org/security/suites/x25519-2020/v1"
],
"id": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
"verificationMethod": [{
"id": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK#z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
"type": "Ed25519VerificationKey2020",
"controller": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
"publicKeyMultibase": "z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
}],
"authentication": [
"did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK#z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
],
"assertionMethod": [
"did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK#z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
],
"capabilityDelegation": [
"did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK#z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
],
"capabilityInvocation": [
"did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK#z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
],
"keyAgreement": [{
"id": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK#z6LSj72tK8brWgZja8NLRwPigth2T9QRiG1uH9oKZuKjdh9p",
"type": "X25519KeyAgreementKey2020",
"controller": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
"publicKeyMultibase": "z6LSj72tK8brWgZja8NLRwPigth2T9QRiG1uH9oKZuKjdh9p"
}]
}
</pre>
<section class="normative">
<h4>Document Creation Algorithm</h4>
<p>
The following algorithm can be used for expanding a did:key identifier to a DID
Document. An <em>identifier</em> and <em>options</em> are the required inputs.
Implementations are expected to set a reasonable default for the
<em>options.publicKeyFormat</em> value such as `JsonWebKey2020` or `Multikey`.
The <em>options.enableExperimentalPublicKeyTypes</em> value SHOULD be set to
`false`. The <em>options.defaultContext</em> value SHOULD be set to an array
where the first element is the string value `https://www.w3.org/ns/did/v1`.
Defaults MAY be overridden by the caller of this algorithm. A <em>document</em>
is the resulting output.
</p>
<ol class="algorithm">
<li>
Initialize <em>document</em> to an empty object.
</li>
<li>
Using a colon (`:`) as the delimiter, split the <em>identifier</em> into its
components: a <em>scheme</em>, a <em>method</em>, a <em>version</em>, and a
<em>multibaseValue</em>. If there are only three components set the
<em>version</em> to the string value `1` and use the last value as the
<em>multibaseValue</em>.
</li>
<li>
Check the validity of the input <em>identifier</em>. The <em>scheme</em> MUST be
the value `did`. The <em>method</em> MUST be the value `key`. The
<em>version</em> MUST be convertible to a positive integer value. The
<em>multibaseValue</em> MUST be a string and begin with the letter `z`. If any
of these requirements fail, an `invalidDid` error MUST be raised.
</li>
<li>
Initialize the <em>signatureVerificationMethod</em> to the result of passing
<em>identifier</em>, <em>multibaseValue</em>, and <em>options</em> to
<a href="#signature-method-creation-algorithm"></a>.
</li>
<li>
Set <em>document.id</em> to <em>identifier</em>. If <em>document.id</em> is not
a valid DID, an `invalidDid` error MUST be raised.
</li>
<li>
Initialize the `verificationMethod` property in <em>document</em> to an array
where the first value is the <em>signatureVerificationMethod</em>.
</li>
<li>
Initialize the `authentication`, `assertionMethod`, `capabilityInvocation`,
and the `capabilityDelegation` properties in <em>document</em> to an array
where the first item is the value of the `id` property in
<em>signatureVerificationMethod</em>.
</li>
<li>
If <em>options.enableEncryptionKeyDerivation</em> is set to `true`:
<ol class="algorithm">
<li>
Initialize the <em>encryptionVerificationMethod</em> to the result of passing
<em>identifier</em>, <em>multibaseValue</em>, and <em>options</em> to
<a href="#encryption-method-creation-algorithm"></a>.
</li>
<li>
Add the <em>encryptionVerificationMethod</em> value to the `verificationMethod`
array.
</li>
<li>
Initialize the `keyAgreement` property in <em>document</em> to an array where
the first item is the value of the `id` property in
<em>encryptionVerificationMethod</em>.
</li>
</ol>
</li>
<li>
Initialize the `@context` property in <em>document</em> to the result of
passing <em>document</em> and <em>options</em> to the
<a href="#context-creation-algorithm"></a>.
</li>
<li>
Return <em>document</em>.
</li>
</ol>
<p>
Any alternative algorithm can be used that produces an equivalent result to the
output from the algorithm above.
</p>
</section>
<section class="normative">
<h4>Signature Method Creation Algorithm</h4>
<p>
The following algorithm can be used for decoding a multibase-encoded multicodec
value into a verification method that is suitable for verifying digital
signatures. An <em>identifier</em>, <em>multibaseValue</em>, and
<em>options</em> are the required inputs. A <em>verificationMethod</em> is
the resulting output.
</p>
<ol class="algorithm">
<li>
Initialize <em>verificationMethod</em> to an empty object.
</li>
<li>
Set <em>multicodecValue</em> and <em>rawPublicKeyBytes</em> to the result
of passing <em>multibaseValue</em> and <em>options</em> to
<a href="#decode-public-key-algorithm"></a>.
</li>
<li>
Ensure the proper key length of <em>rawPublicKeyBytes</em> based on the
<em>multicodecValue</em> table provided below:
<table class="simple">
<thead>
<th>Multicodec hexadecimal value</th>
<th>public key byte length</th>
<th>Description</th>
</thead>
<tbody>
<tr>
<td>`0xe7`</td>
<td>33 bytes</td>
<td>secp256k1-pub - Secp256k1 public key (compressed)</td>
</tr>
<tr>
<td>`0xec`</td>
<td>32 bytes</td>
<td>x25519-pub - Curve25519 public key</td>
</tr>
<tr>
<td>`0xed`</td>
<td>32 bytes</td>
<td>ed25519-pub - Ed25519 public key</td>
</tr>
<tr>
<td>`0x1200`</td>
<td>33 bytes</td>
<td>p256-pub - P-256 public key (compressed)</td>
</tr>
<tr>
<td>`0x1201`</td>
<td>49 bytes</td>
<td>p384-pub - P-384 public key (compressed)</td>
</tr>
<tr>
<td>`0x1202`</td>
<td>?? bytes</td>
<td>p521-pub - P-521 public key (compressed)</td>
</tr>
<tr>
<td>`0x1205`</td>
<td>?? bytes</td>
<td>
rsa-pub - RSA public key. DER-encoded ASN.1 type RSAPublicKey according to
IETF RFC 8017 (PKCS #1)
</td>
</tr>
</tbody>
</table>
If the byte length of <em>rawPublicKeyBytes</em> does not match the expected
public key length for the associated <em>multicodecValue</em>, an
`invalidPublicKeyLength` error MUST be raised.
</li>
<li>
Ensure the <em>rawPublicKeyBytes</em> are a proper encoding of the public key
type as specified by the <em>multicodecValue</em>. This validation is often
done by a cryptographic library when importing the public key by, for example,
ensuring that an Elliptic Curve public key is a specific coordinate that exists
on the elliptic curve. If an invalid public key value is detected, an
`invalidPublicKey` error MUST be raised.
<div class="issue" title="Request for feedback on implementability">
It is not clear if this particular check is implementable across all public
key types. The group is accepting feedback on the implementability of this
particular feature.
</div>
</li>
<li>
Set the <em>verificationMethod.id</em> value by concatenating
<em>identifier</em>, a hash character (`#`), and the <em>multicodecValue</em>.
If <em>verificationMethod.id</em> is not a valid DID URL, an `invalidDidUrl`
error MUST be raised.
</li>
<li>
Set the <em>publicKeyFormat</em> value to the <em>options.publicKeyFormat</em>
value.
</li>
<li>
If <em>publicKeyFormat</em> is not known to the implementation, an
`unsupportedPublicKeyType` error MUST be raised.
</li>
<li>
If <em>options.enableExperimentalPublicKeyTypes</em> is set to `false` and
<em>publicKeyFormat</em> is not `Multikey`, `JsonWebKey2020`, or
`Ed25519VerificationKey2020`, an `invalidPublicKeyType` error MUST be raised.
</li>
<li>
Set <em>verificationMethod.type</em> to the <em>publicKeyFormat</em> value.
</li>
<li>
Set <em>verificationMethod.controller</em> to the <em>identifier</em> value.
If <em>verificationMethod.controller</em> is not a valid DID, an `invalidDid`
error MUST be raised.
</li>
<li>
If <em>publicKeyFormat</em> is `Multikey` or `Ed25519VerificationKey2020`,
set the <em>verificationMethod.publicKeyMultibase</em> value to
<em>multibaseValue</em>.
<li>
If <em>publicKeyFormat</em> is `JsonWebKey2020`, set the
<em>verificationMethod.publicKeyJwk</em> value to the result of
passing <em>multicodecValue</em> and <em>rawPublicKeyBytes</em> to
<a href="#encode-jwk-algorithm"></a>.
</li>
<li>
Return <em>verificationMethod</em>.
</li>
</ol>
</section>
<section class="normative">
<h4>Decode Public Key Algorithm</h4>
<p>
The following algorithm can be used for expanding a multibase-encoded
multicodec value to decoded public key components. A <em>multibaseValue</em>
and <em>options</em> are the required inputs. A <em>decodedPublicKey</em> is
the output.
</p>
<ol class="algorithm">
<li>
Set <em>decodedPublicKey</em> to an empty object.
</li>
<li>
Decode <em>multibaseValue</em> using the base58-btc multibase alphabet and set
<em>multicodecValue</em> to the multicodec header for the decoded value.
Implementers are cautioned to ensure that the <em>multicodecValue</em>
is set to the result after performing varint decoding.
</li>
<li>
Set the <em>rawPublicKeyBytes</em> to the bytes remaining after the
multicodec header.
</li>
<li>
Return <em>multicodecValue</em> and <em>rawPublicKeyBytes</em> as the
<em>decodedPublicKey</em>.
</li>
</ol>
</section>
<section class="normative">
<h4>Encode JWK Algorithm</h4>
<p>
There are 2 categories of JWK expressions for multicodec encoded public keys.
</p>
<p>
Standard JWK representations can be found under the IANA registry for
<a href="https://www.iana.org/assignments/jose/jose.xhtml">
JSON Object Signing and Encryption (JOSE)
</a>.
</p>
<div class="note">
See also the associated RFCs:
<ul>
<li>
<a href="https://www.rfc-editor.org/rfc/rfc7517">RFC7515: JSON Web Key (JWK)</a>
</li>
<li>
<a href="https://www.rfc-editor.org/rfc/rfc8037">RFC8037:
CFRG Elliptic Curve Diffie-Hellman (ECDH) and Signatures
in JSON Object Signing and Encryption (JOSE)</a>
</li>
</ul>
</div>
<p>
In cases where a key type has not been formally standardized yet a
specification describing the key encoding is provided.
</p>
<p class="advisement">
BLS12381 is the only instance of such a key type in the current method specification.
See this document tracking its proposed standardization at IETF. See
<a href="https://datatracker.ietf.org/doc/draft-looker-cose-bls-key-representations/">
draft-looker-cose-bls-key-representations</a>.
</p>
<p>
Implementations MUST conform to the normative requirements of the RFCs and specifications above.
</p>
<p>
The following algorithm can be used to encode a multicodec value to a
JSON Web Key. A <em>multicodecValue</em>, <em>rawPublicKeyBytes</em>
are the required inputs. An <em>encodedJWK</em> is the output.
</p>
<ol class="algorithm">
<li>
Obtain the associated <code>kty</code>, <code>crv</code>, <code>n</code>,<code>e</code>
values for the JWK representation of the key type identified by <em>multicodecValue</em>.
</li>
<li>
If <code>y</code> is required member of the public key,
perform elliptic curve expansion by applying
<a href="https://tools.ietf.org/id/draft-jivsov-ecc-compact-05.html">decompression algorithm specified here.</a>
to obtain <code>y</code> and <code>x</code>.
Otherwise simply encode <code>x</code> according to the associated RFCs.
</li>
<li>
Encode the final JWK object by including the members required for the given key type identified by <em>multicodecValue</em>,
according to the requirements defined by the relevant RFC.
</li>
<li>
Ensure that <code>d</code> is NOT present.
</li>
</ol>
<p class="issue" data-number="55">
Address RSA encoding for DER encoded RSA keys.
</p>
<p class="issue" data-number="54">
Address BLS12381 Encoding.
</p>
</section>
<section class="normative">
<h4>Encryption Method Creation Algorithm</h4>
<p>
The following algorithm can be used for decoding a multibase-encoded multicodec
value into a verification method that is suitable for verifying that
encrypted information will be received by the intended recipient. An
<em>identifier</em>, <em>multibaseValue</em>, and
<em>options</em> are the required inputs. A <em>verificationMethod</em> is
the resulting output.
</p>
<ol class="algorithm">
<li>
Initialize <em>verificationMethod</em> to an empty object.
</li>
<li>
Set <em>multicodecValue</em> and <em>rawPublicKeyBytes</em> to the result
of passing <em>multibaseValue</em> and <em>options</em> to
<a href="#derive-encryption-key-algorithm"></a>.
</li>
<li>
Ensure the proper key length of <em>rawPublicKeyBytes</em> based on the
<em>multicodecValue</em> table provided below:
<table class="simple">
<thead>
<th>Multicodec hexadecimal value</th>
<th>public key byte length</th>
<th>Description</th>
</thead>
<tbody>
<tr>
<td>`0xec`</td>
<td>32 bytes</td>
<td>x25519-pub - Curve25519 public key</td>
</tr>
</tbody>
</table>
If the byte length of <em>rawPublicKeyBytes</em> does not match the expected
public key length for the associated <em>multicodecValue</em>, an
`invalidPublicKeyLength` error MUST be raised.
</li>
<li>
Create the <em>multibaseValue</em> by concatenating the letter 'z' and the
base58-btc encoding of the concatenation of the <em>multicodecValue</em> and
the <em>rawPublicKeyBytes</em>.
</li>
<li>
Set the <em>verificationMethod.id</em> value by concatenating
<em>identifier</em>, a hash character (`#`), and the <em>multibaseValue</em>.
If <em>verificationMethod.id</em> is not a valid DID URL, an `invalidDidUrl`
error MUST be raised.
</li>
<li>
Set the <em>publicKeyFormat</em> value to the <em>options.publicKeyFormat</em>
value.
</li>
<li>
If <em>publicKeyFormat</em> is not known to the implementation, an
`unsupportedPublicKeyType` error MUST be raised.
</li>
<li>
If <em>options.enableExperimentalPublicKeyTypes</em> is set to `false` and
<em>publicKeyFormat</em> is not `Multikey`, `JsonWebKey2020`, or
`X25519KeyAgreementKey2020`, an `invalidPublicKeyType` error MUST be raised.
</li>
<li>
Set <em>verificationMethod.type</em> to the <em>publicKeyFormat</em> value.
</li>
<li>
Set <em>verificationMethod.controller</em> to <em>identifier</em>. If
<em>verificationMethod.controller</em> is not a valid DID, an
`invalidDid` error MUST be raised.
</li>
<li>
If <em>publicKeyFormat</em> is `Multikey` or `X25519KeyAgreementKey2020`,
set the <em>verificationMethod.publicKeyMultibase</em> value to
<em>multibaseValue</em>.
<li>
If <em>publicKeyFormat</em> is `JsonWebKey2020`, set the
<em>verificationMethod.publicKeyJwk</em> value to the result of
passing <em>multicodecValue</em> and <em>rawPublicKeyBytes</em> to
<a href="#encode-jwk-algorithm"></a>.
</li>
<li>
Return <em>verificationMethod</em>.
</li>
</ol>
</section>
<section class="normative">
<h4>Derive Encryption Key Algorithm</h4>
<p>
The following algorithm can be used to transform a multibase-encoded multicodec
value to public encryption key components that are suitable for encrypting
messages to a receiver. A mathematical proof elaborating on the safety of
performing this operation is available in [[THORMARKER]]. A
<em>multibaseValue</em> and <em>options</em> are the required inputs. A
<em>publicEncryptionKey</em> is the output.
</p>
<ol class="algorithm">
<li>
Set <em>publicEncryptionKey</em> to an empty object.
</li>
<li>
Decode <em>multibaseValue</em> using the base58-btc multibase alphabet and set
<em>multicodecValue</em> to the multicodec header for the decoded value.
Implementers are cautioned to ensure that the <em>multicodecValue</em>
is set to the result after performing varint decoding.
</li>
<li>
Set the <em>rawPublicKeyBytes</em> to the bytes remaining after the
multicodec header.
</li>
<li>
If the <em>multicodecValue</em> is `0xed`, derive a public X25519 encryption
key by using the <em>rawPublicKeyBytes</em> and the
algorithm defined in [[OSCORE]] for Curve25519 in
Section 2.4.2: ECDH with Montgomery Coordinates and set
<em>generatedPublicEncryptionKeyBytes</em> to the result.
</li>
<li>
Set <em>multicodecValue</em> in <em>publicEncryptionKey</em> to `0xec`.
</li>
<li>
Set <em>rawPublicKeyBytes</em> in <em>publicEncryptionKey</em> to
<em>generatedPublicEncryptionKeyBytes</em>.
</li>
<li>
Return <em>publicEncryptionKey</em>.
</li>
</ol>
</section>
<section class="normative">
<h4>Context Creation Algorithm</h4>
<p>
The following algorithm is used to generate the array for the `@context`
property in the DID Document. A <em>document</em> and <em>options</em> are the
required inputs. A <em>contextArray</em> is the output.
</p>
<ol class="algorithm">
<li>
Set <em>contextArray</em> to an array that is initialized to
<em>options.defaultContext</em>.
</li>
<li>
For every object in every verification relationship listed in <em>document</em>,
add a string value to the <em>contextArray</em> based on the object `type`
value, if it doesn't already exist, according to the following table:
<table class="simple">
<thead>
<th>`type` value</th>
<th>Context URL</th>
</thead>
<tbody>
<tr>
<td>`Ed25519VerificationKey2020`</td>
<td>
https://w3id.org/security/suites/ed25519-2020/v1
</td>
</tr>
<tr>
<td>`X25519KeyAgreementKey2020`</td>
<td>
https://w3id.org/security/suites/x25519-2020/v1
</td>
</tr>
<tr>
<td>`JsonWebKey2020`</td>
<td>
https://w3id.org/security/suites/jws-2020/v1
</td>
</tr>
<tr>
<td>`Multikey`</td>
<td class="issue">
There is currently no JSON-LD Context that defines the Multikey type. This is
expected to be defined by the VC2WG in 2022 or 2023.
</td>
</tr>
</tbody>
</table>
</li>
<li>
Return <em>contextArray</em>.
</li>
</ol>
</section>
</section>
<section class="normative">
<h3>Read</h3>
<p>
Reading a <tt>did:key</tt> value is a matter of deterministically expanding the
value to a DID Document. This process is described in Section <a
href="#create"></a>.
</p>
</section>
<section class="normative">
<h3>Update</h3>
<p>
This DID Method does not support updating the DID Document.
</p>
</section>
<section class="normative">
<h3>Deactivate</h3>
<p>
This DID Method does not support deactivating the DID Document.
</p>
</section>
</section>
<section class="informative">
<h2>Test Vectors</h2>
<p>For a full list of test vectors see <a href="https://github.com/w3c-ccg/did-method-key/tree/main/test-vectors">test vectors</a>.</p>
<p>We provide only the <code>verificationMethod</code> section of the DID Document in these examples.</p>
<section class="informative">
<h3>Ed25519 / X25519</h3>
<p>These DID always start with <code>z6Mk</code>.</p>
<pre class="example" title="JWK Example">
...
"verificationMethod": [
{
"id": "did:key:z6MkiTBz1ymuepAQ4HEHYSF1H8quG5GLVVQR3djdX3mDooWp#z6MkiTBz1ymuepAQ4HEHYSF1H8quG5GLVVQR3djdX3mDooWp",
"type": "JsonWebKey2020",
"controller": "did:key:z6MkiTBz1ymuepAQ4HEHYSF1H8quG5GLVVQR3djdX3mDooWp",
"publicKeyJwk": {
"kty": "OKP",
"crv": "Ed25519",
"x": "O2onvM62pC1io6jQKm8Nc2UyFXcd4kOmOsBIoYtZ2ik"
}
},
{
"id": "did:key:z6MkiTBz1ymuepAQ4HEHYSF1H8quG5GLVVQR3djdX3mDooWp#z6LShs9GGnqk85isEBzzshkuVWrVKsRp24GnDuHk8QWkARMW",
"type": "JsonWebKey2020",
"controller": "did:key:z6MkiTBz1ymuepAQ4HEHYSF1H8quG5GLVVQR3djdX3mDooWp",
"publicKeyJwk": {
"kty": "OKP",
"crv": "X25519",
"x": "W_Vcc7guviK-gPNDBmevVw-uJVamQV5rMNQGUwCqlH0"
}
}
],
...
</pre>
<pre class="example" title="Multicodec Example">
...
"verificationMethod": [
{
"id": "did:key:z6MkiTBz1ymuepAQ4HEHYSF1H8quG5GLVVQR3djdX3mDooWp#z6MkiTBz1ymuepAQ4HEHYSF1H8quG5GLVVQR3djdX3mDooWp",
"type": "Ed25519VerificationKey2020",
"controller": "did:key:z6MkiTBz1ymuepAQ4HEHYSF1H8quG5GLVVQR3djdX3mDooWp",
"publicKeyMultibase": "z6MkiTBz1ymuepAQ4HEHYSF1H8quG5GLVVQR3djdX3mDooWp"
},
{
"id": "did:key:z6MkiTBz1ymuepAQ4HEHYSF1H8quG5GLVVQR3djdX3mDooWp#z6LShs9GGnqk85isEBzzshkuVWrVKsRp24GnDuHk8QWkARMW",
"type": "X25519KeyAgreementKey2020",
"controller": "did:key:z6MkiTBz1ymuepAQ4HEHYSF1H8quG5GLVVQR3djdX3mDooWp",
"publicKeyMultibase": "z6LShs9GGnqk85isEBzzshkuVWrVKsRp24GnDuHk8QWkARMW"
}
],
...
</pre>
<pre class="example">
did:key:z6MkiTBz1ymuepAQ4HEHYSF1H8quG5GLVVQR3djdX3mDooWp
did:key:z6MkjchhfUsD6mmvni8mCdXHw216Xrm9bQe2mBH1P5RDjVJG
did:key:z6MknGc3ocHs3zdPiJbnaaqDi58NGb4pk1Sp9WxWufuXSdxf
</pre>
</section>
<section class="informative">
<h3>X25519</h3>
<p>These DID always start with <code>z6LS</code>.</p>
<pre class="example">
did:key:z6LSeu9HkTHSfLLeUs2nnzUSNedgDUevfNQgQjQC23ZCit6F
did:key:z6LStiZsmxiK4odS4Sb6JmdRFuJ6e1SYP157gtiCyJKfrYha
did:key:z6LSoMdmJz2Djah2P4L9taDmtqeJ6wwd2HhKZvNToBmvaczQ
</pre>
</section>
<section class="informative">
<h3>Secp256k1</h3>
<p>These DID always start with <code>zQ3s</code>.</p>
<pre class="example">
did:key:zQ3shokFTS3brHcDQrn82RUDfCZESWL1ZdCEJwekUDPQiYBme
did:key:zQ3shtxV1FrJfhqE1dvxYRcCknWNjHc3c5X1y3ZSoPDi2aur2
did:key:zQ3shZc2QzApp2oymGvQbzP8eKheVshBHbU4ZYjeXqwSKEn6N
</pre>
</section>
<section class="informative">
<h3>BLS 12381</h3>
<p>These DID always start with <code>zUC7</code>.</p>
<pre class="example">
did:key:zUC7K4ndUaGZgV7Cp2yJy6JtMoUHY6u7tkcSYUvPrEidqBmLCTLmi6d5WvwnUqejscAkERJ3bfjEiSYtdPkRSE8kSa11hFBr4sTgnbZ95SJj19PN2jdvJjyzpSZgxkyyxNnBNnY
did:key:zUC7KKoJk5ttwuuc8pmQDiUmtckEPTwcaFVZe4DSFV7fURuoRnD17D3xkBK3A9tZqdADkTTMKSwNkhjo9Hs6HfgNUXo48TNRaxU6XPLSPdRgMc15jCD5DfN34ixjoVemY62JxnW
</pre>
</section>
<section class="informative">
<h3>P-256</h3>
<p>These DID always start with <code>zDn</code>.</p>
<pre class="example">
did:key:zDnaerDaTF5BXEavCrfRZEk316dpbLsfPDZ3WJ5hRTPFU2169
did:key:zDnaerx9CtbPJ1q36T5Ln5wYt3MQYeGRG5ehnPAmxcf5mDZpv
</pre>
</section>
<section class="informative">
<h3>P-384</h3>
<p>These DID always start with <code>z82</code>.</p>
<pre class="example">
did:key:z82Lm1MpAkeJcix9K8TMiLd5NMAhnwkjjCBeWHXyu3U4oT2MVJJKXkcVBgjGhnLBn2Kaau9
did:key:z82LkvCwHNreneWpsgPEbV3gu1C6NFJEBg4srfJ5gdxEsMGRJUz2sG9FE42shbn2xkZJh54
</pre>
</section>
<section class="informative">
<h3>P-521</h3>
<p>These DID always start with <code>z2J9</code>.</p>
<pre class="example">
did:key:z2J9gaYxrKVpdoG9A4gRnmpnRCcxU6agDtFVVBVdn1JedouoZN7SzcyREXXzWgt3gGiwpoHq7K68X4m32D8HgzG8wv3sY5j7
did:key:z2J9gcGdb2nEyMDmzQYv2QZQcM1vXktvy1Pw4MduSWxGabLZ9XESSWLQgbuPhwnXN7zP7HpTzWqrMTzaY5zWe6hpzJ2jnw4f
</pre>
</section>
<section class="informative">
<h3>RSA</h3>
<p>See also <a href="#rsa-repr">RSA Public Key
Representation</a>.</p>
<section class="informative" id="rsa-2048">
<h4>2048-bit</h4>
<p>These DID always start with <code>z4MX</code>.</p>
<pre class="example">
did:key:z4MXj1wBzi9jUstyPMS4jQqB6KdJaiatPkAtVtGc6bQEQEEsKTic4G7Rou3iBf9vPmT5dbkm9qsZsuVNjq8HCuW1w24nhBFGkRE4cd2Uf2tfrB3N7h4mnyPp1BF3ZttHTYv3DLUPi1zMdkULiow3M1GfXkoC6DoxDUm1jmN6GBj22SjVsr6dxezRVQc7aj9TxE7JLbMH1wh5X3kA58H3DFW8rnYMakFGbca5CB2Jf6CnGQZmL7o5uJAdTwXfy2iiiyPxXEGerMhHwhjTA1mKYobyk2CpeEcmvynADfNZ5MBvcCS7m3XkFCMNUYBS9NQ3fze6vMSUPsNa6GVYmKx2x6JrdEjCk3qRMMmyjnjCMfR4pXbRMZa3i
</pre>
</section>
<section class="informative" id="rsa-4096">
<h4>4096-bit</h4>
<p>These DID always start with <code>zgg</code>.</p>
<pre class="example">
did:key:zgghBUVkqmWS8e1ioRVp2WN9Vw6x4NvnE9PGAyQsPqM3fnfPf8EdauiRVfBTcVDyzhqM5FFC7ekAvuV1cJHawtfgB9wDcru1hPDobk3hqyedijhgWmsYfJCmodkiiFnjNWATE7PvqTyoCjcmrc8yMRXmFPnoASyT5beUd4YZxTE9VfgmavcPy3BSouNmASMQ8xUXeiRwjb7xBaVTiDRjkmyPD7NYZdXuS93gFhyDFr5b3XLg7Rfj9nHEqtHDa7NmAX7iwDAbMUFEfiDEf9hrqZmpAYJracAjTTR8Cvn6mnDXMLwayNG8dcsXFodxok2qksYF4D8ffUxMRmyyQVQhhhmdSi4YaMPqTnC1J6HTG9Yfb98yGSVaWi4TApUhLXFow2ZvB6vqckCNhjCRL2R4MDUSk71qzxWHgezKyDeyThJgdxydrn1osqH94oSeA346eipkJvKqYREXBKwgB5VL6WF4qAK6sVZxJp2dQBfCPVZ4EbsBQaJXaVK7cNcWG8tZBFWZ79gG9Cu6C4u8yjBS8Ux6dCcJPUTLtixQu4z2n5dCsVSNdnP1EEs8ZerZo5pBgc68w4Yuf9KL3xVxPnAB1nRCBfs9cMU6oL1EdyHbqrTfnjE8HpY164akBqe92LFVsk8RusaGsVPrMekT8emTq5y8v8CabuZg5rDs3f9NPEtogjyx49wiub1FecM5B7QqEcZSYiKHgF4mfkteT2
</pre>
</section>
</section>
</section>
<section class="informative">
<h2>Security and Privacy Considerations</h2>
<p>
There are a number of security and privacy considerations that implementers
will want to take into consideration when implementing this specification.
</p>
<section class="informative">
<h3>Key Rotation Not Supported</h3>
<p>
The <tt>did:key</tt> method is a purely generative method, which means that
updates are not supported. This can be an issue if a <tt>did:key</tt> is
expected to be used over a long period of time. For example, if a
<tt>did:key</tt> is ever compromised, it is not possible to rotate the
compromised key. For this reason, using a <tt>did:key</tt> for interactions
that last weeks to months is strongly discouraged.
</p>
</section>