-
Notifications
You must be signed in to change notification settings - Fork 15
/
index.html
2585 lines (2404 loc) · 106 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>Verifiable Credentials Implementation Guidelines 1.0</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: "ED",
// the specification's short name, as in http://www.w3.org/TR/short-name/
shortName: "vc-imp-guide",
// subtitle for the spec
subtitle: "Implementation guidance for Verifiable Credentials",
// if you wish the publication date to be other than today, set this
// publishDate: "2019-09-24",
// 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: vcwg.localBiblio,
doJsonLd: true,
github: "https://github.com/w3c/vc-imp-guide",
includePermalinks: false,
// if there a publicly available Editor's Draft, this is the link
edDraftURI: "https://w3c.github.io/vc-imp-guide/",
// 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: "Andrei Sambra", url: "https://deiu.me/"}],
// 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: "David Chadwick", url: "https://www.linkedin.com/in/david-chadwick-36816395/",
company: "University of Kent", companyURL: "https://www.kent.ac.uk/"
},
{
name: "Dave Longley", url: "https://github.com/dlongley",
company: "Digital Bazaar", companyURL: "https://digitalbazaar.com/"
},
{
name: "Manu Sporny", url: "http://manu.sporny.org/",
company: "Digital Bazaar", companyURL: "https://digitalbazaar.com/"
},
{
name: "Oliver Terbu", url: "mailto:[email protected]",
company: "Consensys", companyURL: "https://consensys.net/"
},
{
name: "Dmitri Zagidulin", url: "mailto:[email protected]",
company: "Digital Bazaar", companyURL: "https://digitalbazaar.com"
},
{
name: "Brent Zundel", url: "https://www.linkedin.com/in/bzundel/",
company: "Evernym", companyURL: "https://evernym.com/"
}
],
// name of the WG
wg: "Verifiable Claims Working Group",
// URI of the public WG page
wgURI: "https://www.w3.org/2017/vc/",
// name (with the @w3c.org) of the public mailing to which comments are due
wgPublicList: "public-vc-comments",
// 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 neighbourhood
// Team Contact.
wgPatentURI: "https://www.w3.org/2004/01/pp-impl/98922/status",
maxTocLevel: 4,
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;
}
.supported {
background-color: #93c47d;
}
.missing {
background-color: #e06666;
}
</style>
</head>
<body>
<section id='abstract'>
<p>
This document provides implementation guidance for Verifiable Credentials.
</p>
</section>
<section id='sotd'>
<p>
Future versions of this document will be updated and maintained by the
<a href="https://www.w3.org/community/credentials/">
Credentials Community Group</a>. Please consult that group for the most
up to date version of this document.
</p>
<p>
The work on this document was carried out under tight time constraints due to
limitations of the W3C process and publishing deadlines. Under such conditions,
errors are unavoidable and some of the ideas presented here are incomplete.
The Working Group hopes that in the future, W3C process can be revised to better
support the dynamic nature of standards work in a more consistent way across
different groups.
</p>
<p>
Comments regarding this document are welcome. Please file issues
directly on <a href="https://github.com/w3c/vc-data-model/issues/">GitHub</a>,
or send them to
<a href="mailto:[email protected]">[email protected]</a>
(<a href="mailto:[email protected]?subject=subscribe">subscribe</a>,
<a href="https://lists.w3.org/Archives/Public/public-vc-comments/">archives</a>).
</p>
</section>
<section>
<h2>Introduction</h2>
<em>This section is non-normative.</em>
<p>
This guide provides some examples and resources for implementing
protocols which make use of <a>verifiable credentials</a>, beyond those available in the core specification.
</p>
<p>
It may be useful to first familiarize yourself with the official
<a href="https://www.w3.org/TR/verifiable-claims-use-cases/">Use Cases document</a>,
which offers a concise collection of examples of <a>Verifiable Credentials</a>
as they may appear in everyday life, and how they may be used.
</p>
<p>
The <a href="https://www.w3.org/TR/vc-data-model/">data model specification</a>
contains the technical details about <a>verifiable credentials</a>. However, the
data model specification does not specify any <em>protocols</em> for using
<a>verifiable credentials</a>, nor any <em>proof formats</em> or additional
<em>identifiers</em> upon which such protocols may depend.
</p>
</section>
<section>
<h2>Identifiers</h2>
<em>This section is non-normative.</em>
<p>
When expressing statements about a specific entity, such as a person, product,
or organization, it is often useful to have an identifier for it so that others
can express statements about the same thing. The <a>verifiable credentials</a>
<a href="https://www.w3.org/TR/vc-data-model//">data model specification</a>
contains numerous examples where the identifier is a
<a href="https://w3c-ccg.github.io/did-primer/">decentralized identifier</a>,
also known as a DID. An example of a DID is <code>did:example:123456abcdef</code>.
</p>
<p>
There is currently a proposed charter for a W3C <a href="https://w3c-ccg.github.io/did-wg-charter/">
Decentralized Identifier Working Group</a>, which will put DIDs on track to
become a W3C standard.
</p>
<p class="note">
As of the publication of the <a>verifiable credentials</a>
<a href="https://www.w3.org/TR/vc-data-model/">data model specification</a>,
DIDs are not necessary for <a>verifiable credentials</a> to be useful.
Specifically, <a>verifiable credentials</a> do not depend on <a>DIDs</a> and
<a>DIDs</a> do not depend on <a>verifiable credentials</a>. However, it is
expected that many <a>verifiable credentials</a> will use <a>DIDs</a> and that
software libraries implementing the
<a href="https://www.w3.org/TR/vc-data-model/">data model specification</a>
will benefit from knowing how to resolve <a>DIDs</a>. <a>DID</a>-based URLs may
be used to express identifiers associated with <a>subjects</a>, <a>issuers</a>,
<a>holders</a>, credential status lists, cryptographic keys, and other
machine-readable information associated with a <a>verifiable credential</a>.
</p>
</section>
<section class="informative">
<h2>Terminology</h2>
<div data-include="./terms.html"
data-oninclude="restrictReferences">
</div>
</section>
<section>
<h2>Verification</h2>
<em>This section is non-normative.</em>
<p>
<a>Verification</a> is the process a <a>verifier</a> or <a>holder</a> performs
when presented with a <a>verifiable presentation</a> or
<a>verifiable credential</a>. <a>Verification</a> includes checking the
presented item against the <a href="https://www.w3.org/TR/vc-data-model/">core
data model</a>, and may also include validating the provided proof section and
checking the item's status.
</p>
<section>
<h3>Core Data Model</h3>
<p>
Conformant tooling that processes Verifiable Credentials will ensure that
the core data model is verified when processing credentials.
</p>
</section>
<section>
<h3>Specific Verifiable Credentials</h3>
<p>
There are many data verification languages, the following approach is one
that should work for most use cases.
</p>
</section>
<section>
<h3>Content Integrity</h3>
<p>
Protecting the integrity of content is an important component of verification.
<a>Verifiers</a> need to have confidence that the content they rely on to
verify <a>credentials</a> doesn't change without their knowledge. This content
may include data schemas, identifiers, public keys, etc.
</p>
<p>
There are a number of ways to provide content integrity protection. A few of
these are described in greater detail below.
</p>
<section>
<h4>Hashlinks</h4>
<p>
<a href="https://tools.ietf.org/html/draft-sporny-hashlink">Hashlink URLs</a>
can be used to provide content integrity for links to external resources.
</p>
</section>
<section>
<h4>Verifiable Data Registries</h4>
<p>
A <a>verifiable data registry</a> can also provide content integrity protection.
One example of a <a>verifiable data registry</a> which provides content
integrity protection is a distributed ledger. This is a shared transaction
record which provides mechanisms for verifying the content it stores. These
mechanisms include consensus protocols, digital signatures, and verifiable data
structures such as Merkle trees. These mechanisms provide cryptographic
assurances that the content retrieved from the ledger has not been altered, and
is complete.
</p>
</section>
</section>
</section>
<section>
<h3>Referencing Other Credentials</h3>
<p>
Usage of <a>verifiable credentials</a> will often require referencing other
credentials, embedding or attaching multiple credentials, or otherwise binding
them together.
</p>
<section>
<h4>Referencing Credentials Without Integrity Protection</h4>
<p>
The simplest way for a <a>credential</a> to reference another external
credential is to link to it, either directly by using its URI, or indirectly by
providing a well-known ID (for example, a credential modeling an internal
company Invoice may refer to its parent Purchase Order credential simply by the
PO Number, relevant only within the context of this specific enterprise).
</p>
<p>
This method of linking to an external credential without using an integrity
protection mechanism may be acceptable in some use cases, such as when both
credentials are issued by the same entity, the verifier has a high level of
trust and confidence in the issuer's security and auditing mechanisms, and the
risk to the verifier is sufficiently low. However, implementers should keep
in mind that although the credential that contains the reference may be
integrity protected itself (by a cryptographic signature or a similar proof
mechanism), the verifier has no way of knowing that the external credential
being linked to has not been tampered with, unless the link itself has a content
integrity protection mechanism built into it.
</p>
</section>
<section>
<h4>Referencing Credentials With Integrity Protection</h4>
<p>
The recommended way of referencing an external credential from within a
<a>verifiable credential</a> is to use a linking mechanism that
cryptographically binds the contents of the target document to the URI itself.
One way to accomplish this would be to use <a>hashlinks</a> or an equivalent
URI scheme. Another mechanism would be to encode the full contents of the
target credential in the URI itself, although this is much less commonly used,
and the discussion of the practical limits of URI length are outside the scope
of this document.
</p>
</section>
<section>
<h4>Attaching Evidence</h4>
<p>
<a>Issuers</a> wishing to attach additional supporting information to a
<a>verifiable credential</a> are encouraged to use the
<a href="https://www.w3.org/TR/vc-data-model/#evidence">evidence</a> property.
Note that this can be done either by embedding the relevant evidence information
in the credential itself, or by referencing it (with or without an integrity
protection mechanism, as previously discussed).
</p>
</section>
</section>
</section>
<section class="informative">
<h2>Subject-Holder Relationships</h2>
<p>
This section describes possible relationships between a <a>subject</a> and a
<a>holder</a> and how the Verifiable Credentials Data Model expresses these
relationships. The following diagram illustrates these relationships, with the
subsequent sections describing how each of these relationships are handled in
the data model.
</p>
<figure>
<img style="margin: auto; display: block; width: 75%;"
src="diagrams/subject-ne-holder.svg" alt="Long decision tree
from top to bottom. For the first question, 'Subject
Present?', No means Bearer Credential and Yes points to the
rest of the tree. From this point on until the very end,
each Yes points to an answer and each No points to another
question. The first question here is 'Subject = Holder?',
with Yes meaning Most Common Use Case. If No, 'Credential
Uniquely Identifies Subject?' with Yes meaning Irrelevant who
Holder is. If No, 'Subject Passes VC to Holder?' with Yes
meaning, e.g., Power of Attorney, Employee. If No, 'Issuer
Independently Authorizes Holder?' with Yes meaning, e.g., Law
Enforcement. If No, 'Holder Acts for Subject?' with Yes
meaning, e.g., Parent, Pet Owner, Travel Agent. If No,
'Holder Acts for Verifier?' with Yes meaning, e.g., Recruiter
passing on VC of job applicant to employer and No meaning
'Random Holder with no relationship to Subject, Issuer or Verifier">
<figcaption style="text-align: center;">
Subject-Holder Relationships in Verifiable Credentials.
</figcaption>
</figure>
<section class="informative">
<h3>Subject is the Holder</h3>
<p>
The most common relationship is when a <a>subject</a> is the <a>holder</a>. In
this case, a <a>verifier</a> can easily deduce that a <a>subject</a> is the
<a>holder</a> if the <a>verifiable presentation</a> is digitally signed by the
<a>holder</a> and all contained <a>verifiable credentials</a> are about a
<a>subject</a> that can be identified to be the same as the <a>holder</a>.
</p>
<p>
If only the <code>credentialSubject</code> is allowed to insert a
<a>verifiable credential</a> into a <a>verifiable presentation</a>, the
<a>issuer</a> can insert the <code>nonTransferable</code> <a>property</a> into
the <a>verifiable credential</a>, as described below.
</p>
<section class="informative">
<h4>nonTransferable Property</h4>
<p>
The <code>nonTransferable</code> <a>property</a> indicates that a
<a>verifiable credential</a> must only be encapsulated into a
<a>verifiable presentation</a> whose proof was issued by the
<code>credentialSubject</code>. A <a>verifiable presentation</a> that contains
a <a>verifiable credential</a> containing the <code>nonTransferable</code>
<a>property</a>, whose proof creator is not the <code>credentialSubject</code>,
is invalid.
</p>
<pre class="example nohighlight" title="Usage of the nonTransferable property">
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"id": "http://example.edu/credentials/3732",
"type": ["VerifiableCredential", "ProofOfAgeCredential"],
"issuer": "https://example.edu/issuers/14",
"issuanceDate": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"ageOver": 21
},
"nonTransferable": true,
"proof": { ..
"verificationMethod": "did:example:ebfeb1f712ebc6f1c276e12ec21",
... }
}
</pre>
</section>
</section>
<section class="informative">
<h3>Credential Uniquely Identifies a Subject</h3>
<p>
In this case, the <code>credentialSubject</code> <a>property</a> might contain
multiple <a>properties</a>, each providing an aspect of a description of the
<a>subject</a>, which combine together to unambiguously identify the
<a>subject</a>. Some use cases might not require the <a>holder</a> to be
identified at all, such as checking to see if a doctor (the <a>subject</a>) is
board-certified. Other use cases might require the <a>verifier</a> to use
out-of-band knowledge to determine the relationship between the <a>subject</a>
and the <a>holder</a>.
</p>
<pre class="example nohighlight" title="A credential uniquely identifying a subject">
{
"@context": ["https://www.w3.org/2018/credentials/v1", "https://schema.org/"]
"id": "http://example.edu/credentials/332",
"type": ["VerifiableCredential", "IdentityCredential"],
"issuer": "https://example.edu/issuers/4",
"issuanceDate": "2017-02-24T19:73:24Z",
"credentialSubject": {
"name": "J. Doe",
"address": {
"streetAddress": "10 Rue de Chose",
"postalCode": "98052",
"addressLocality": "Paris",
"addressCountry": "FR"
},
"birthDate": "1989-03-15"
...
},
"proof": { <span class="comment">...</span> }
}
</pre>
<p>
The example above uniquely identifies the <a>subject</a> using the name,
address, and birthdate of the individual.
</p>
</section>
<section class="informative">
<h3>Subject Passes the Verifiable Credential to a Holder</h3>
<p>
Usually <a>verifiable credentials</a> are presented to <a>verifiers</a> by the
<a>subject</a>. However, in some cases, the <a>subject</a> might need to pass the
whole or part of a <a>verifiable credential</a> to another <a>holder</a>. For
example, if a patient (the <a>subject</a>) is too ill to take a prescription
(the <a>verifiable credential</a>) to the pharmacist (the <a>verifier</a>), a
friend might take the prescription in to pick up the medication.
</p>
<p>
The data model allows for this by letting the <a>subject</a> issue a new
<a>verifiable credential</a> and give it to the new <a>holder</a>, who can
then present both <a>verifiable credentials</a> to the <a>verifier</a>.
However, the content of this second <a>verifiable credential</a> is likely to
be application-specific, so this specification cannot standardize the contents
of this second <a>verifiable credential</a>. Nevertheless, a non-normative
example is provided in Appendix
<a href="#subject-passes-a-verifiable-credential-to-someone-else"></a>.
</p>
</section>
<section class="informative">
<h3>Holder Acts on Behalf of the Subject</h3>
<p>
The Verifiable Credentials Data Model supports the <a>holder</a> acting on
behalf of the <a>subject</a> in at least the following ways. The:
</p>
<ul>
<li>
<a>Issuer</a> can include the relationship between the <a>holder</a> and
the <a>subject</a> in the <code>credentialSubject</code> <a>property</a>.
</li>
<li>
<a>Issuer</a> can express the relationship between the <a>holder</a> and
the <a>subject</a> by issuing a new <a>verifiable credential</a>, which the
<a>holder</a> utilizes.
</li>
<li>
<a>Subject</a> can express their relationship with the <a>holder</a> by
issuing a new <a>verifiable credential</a>, which the <a>holder</a> utilizes.
</li>
</ul>
<p>
The mechanisms listed above describe the relationship between the
<a>holder</a> and the <a>subject</a> and helps the <a>verifier</a> decide
whether the relationship is sufficiently expressed for a given use case.
</p>
<p class="note">
The additional mechanisms the <a>issuer</a> or the <a>verifier</a> uses to
verify the relationship between the <a>subject</a> and the <a>holder</a> are
outside the scope of this specification.
</p>
<pre class="example nohighlight" title="The relationship property in a child's credential">{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"id": "http://example.edu/credentials/3732",
"type": ["VerifiableCredential", "AgeCredential", "RelationshipCredential"],
"issuer": "https://example.edu/issuers/14",
"issuanceDate": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"ageUnder": 16,
"parent": {
"id": "did:example:ebfeb1c276e12ec211f712ebc6f",
"type": "Mother"
}
},
"proof": { <span class="comment">...</span> } <span class="comment">// the proof is generated by the DMV</span>
}
</pre>
<p>
In the example above, the <a>issuer</a> expresses the relationship between the
child and the parent such that a <a>verifier</a> would most likely accept the
<a>credential</a> if it is provided by the child or the parent.
</p>
<pre class="example nohighlight" title="A relationship credential issued to a parent">{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"id": "http://example.edu/credentials/3732",
"type": ["VerifiableCredential", "RelationshipCredential"],
"issuer": "https://example.edu/issuers/14",
"issuanceDate": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1c276e12ec211f712ebc6f",
"child": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"type": "Child"
}
},
"proof": { <span class="comment">...</span> } <span class="comment">// the proof is generated by the DMV</span>
}
</pre>
<p>
In the example above, the <a>issuer</a> expresses the relationship between the
child and the parent in a separate <a>credential</a> such that a
<a>verifier</a> would most likely accept any of the child's <a>credentials</a>
if they are provided by the child or if the <a>credential</a> above is
provided with any of the child's <a>credentials</a>.
</p>
<pre class="example nohighlight" title="A relationship credential issued by a child">{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"id": "http://example.org/credentials/23894",
"type": ["VerifiableCredential", "RelationshipCredential"],
"issuer": "http://example.org/credentials/23894",
"issuanceDate": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"parent": {
"id": "did:example:ebfeb1c276e12ec211f712ebc6f",
"type": "Mother"
}
},
"proof": { <span class="comment">...</span> } <span class="comment">// the proof is generated by the child</span>
}
</pre>
<p>
In the example above, the child expresses the relationship between the child and
the parent in a separate <a>credential</a> such that a <a>verifier</a> would
most likely accept any of the child's <a>credentials</a> if the
<a>credential</a> above is provided.
</p>
<p>
Similarly, the strategies described in the examples above can be used for many
other types of use cases, including power of attorney, pet ownership, and
patient prescription pickup.
</p>
</section>
<section class="informative">
<h3>Subject Passes a Verifiable Credential to Someone Else</h3>
<p>
When a <a>subject</a> passes a <a>verifiable credential</a> to another
<a>holder</a>, the <a>subject</a> might issue a new <a>verifiable credential</a>
to the <a>holder</a> in which the:
</p>
<ul>
<li>
<a>Issuer</a> is the <a>subject</a>.
</li>
<li>
<a>Subject</a> is the <a>holder</a> to whom the <a>verifiable credential</a> is
being passed.
</li>
<li>
<a>Claim</a> contains the <a>properties</a> being passed on.
</li>
</ul>
<p>
The <a>holder</a> can now create a <a>verifiable presentation</a> containing
these two <a>verifiable credentials</a> so that the <a>verifier</a> can
<a>verify</a> that the <a>subject</a> gave the original
<a>verifiable credential</a> to the <a>holder</a>.
</p>
<pre class="example nohighlight" title="A holder presenting a
verifiable credential that was passed to it by the subject">
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"id": "https://example.com/VP/0987654321",
"type": ["VerifiablePresentation"],
"verifiableCredential": [
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"id": "http://pharma.example.com/credentials/3732",
"type": ["VerifiableCredential", "PrescriptionCredential"],
"issuer": "https://pharma.example.com/issuer/4",
"issuanceDate": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"prescription": {....}
},
"credentialStatus": {
"id": "https://pharma.example.com/credentials/status/3#94567",
"type": "RevocationList2020Status",
"revocationListIndex": "94567",
"revocationListCredential": "https://pharma.example.com/credentials/status/3"
},
"proof": {....}
},
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"id": "https://example.com/VC/123456789",
"type": ["VerifiableCredential", "PrescriptionCredential"],
"issuer": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"issuanceDate": "2010-01-03T19:53:24Z",
"credentialSubject": {
"id": "did:example:76e12ec21ebhyu1f712ebc6f1z2",
"prescription": {....}
},
"proof": {
"type": "RsaSignature2018",
"created": "2018-06-17T10:03:48Z",
"proofPurpose": "assertionMethod",
"jws": "pYw8XNi1..Cky6Ed=",
"verificationMethod": "did:example:ebfeb1f712ebc6f1c276e12ec21/keys/234"
}
}
],
"proof": [{
"type": "RsaSignature2018",
"created": "2018-06-18T21:19:10Z",
"proofPurpose": "authentication",
"verificationMethod": "did:example:76e12ec21ebhyu1f712ebc6f1z2/keys/2",
"challenge": "c0ae1c8e-c7e7-469f-b252-86e6a0e7387e",
"jws": "BavEll0/I1..W3JT24="
}]
}
</pre>
<p>
In the above example, a patient (the original <a>subject</a>) passed a
prescription (the original <a>verifiable credential</a>) to a friend, and
issued a new <a>verifiable credential</a> to the friend, in which the friend is
the <a>subject</a>, the <a>subject</a> of the original
<a>verifiable credential</a> is the <a>issuer</a>, and the <a>credential</a> is
a copy of the original prescription.
</p>
</section>
<section class="informative">
<h3>Issuer Authorizes Holder</h3>
<p>
When an <a>issuer</a> wants to authorize a <a>holder</a> to possess a
<a>credential</a> that describes a <a>subject</a> who is not the <a>holder</a>,
and the <a>holder</a> has no known relationship with the <a>subject</a>, then
the <a>issuer</a> might insert the relationship of the <a>holder</a> to itself
into the <a>subject's</a> <a>credential</a>.
</p>
<p class="note">
Verifiable credentials are not an authorization framework and therefore
delegation is outside the scope of this specification. However, it is understood
that verifiable credentials are likely to be used to build authorization and
delegation systems. The following is one approach that might be appropriate for
some use cases.
</p>
<pre class="example nohighlight" title="A credential issued to a
holder who is not the (only) subject of the credential, who has no relationship with
the subject of the credential, but who has a relationship with the issuer">
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"id": "http://example.edu/credentials/3732",
"type": ["VerifiableCredential", "NameAndAddress"],
"issuer": "https://example.edu/issuers/14",
"holder": {
"type": "LawEnforcement",
"id": "did:example:ebfeb1276e12ec21f712ebc6f1c"
},
"issuanceDate": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"name": "Mr John Doe",
"address": "10 Some Street, Anytown, ThisLocal, Country X"
},
"proof": {
"type": "RsaSignature2018",
"created": "2018-06-17T10:03:48Z",
"proofPurpose": "assertionMethod",
"verificationMethod": "https://example.edu/issuers/14/keys/234",
"jws": "pY9...Cky6Ed = "
}
}
</pre>
</section>
<section class="informative">
<h3>Holder Acts on Behalf of the Verifier, or has no Relationship with
the Subject, Issuer, or Verifier</h3>
<p>
The Verifiable Credentials Data Model currently does not support either of
these scenarios. It is for further study how they might be supported.
</p>
</section>
</section>
<section>
<h2>Disputes</h2>
<p>
There are at least two different cases to consider where an <a>entity</a>
wants to dispute a <a>credential</a> issued by an <a>issuer</a>:
</p>
<ul>
<li>
A <a>subject</a> disputes a claim made by the <a>issuer</a>. For example, the
<code>address</code> property is incorrect or out of date.
</li>
<li>
An <a>entity</a> disputes a potentially false claim made by the <a>issuer</a>
about a different <a>subject</a>. For example, an imposter has claimed the
social security number for an <a>entity</a>.
</li>
</ul>
<p>
The mechanism for issuing a <code>DisputeCredential</code> is the same as
for a regular <a>credential</a>, except that the <code>credentialSubject</code>
identifier in the <code>DisputeCredential</code> property is the identifier of
the disputed <a>credential</a>.
</p>
<p>
For example, if a <a>credential</a> with an identifier of
<code>https://example.org/credentials/245</code> is disputed, an <a>entity</a>
can issue one of the <a>credentials</a> shown below. In the first example, the
<a>subject</a> might present this to the <a>verifier</a> along with the disputed
<a>credential</a>. In the second example, the <a>entity</a> might publish the
<code>DisputeCredential</code> in a public venue to make it known that the
<a>credential</a> is disputed.
</p>
<pre class="example nohighlight" title="A subject disputes a credential">
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"id": "http://example.com/credentials/123",
"type": ["VerifiableCredential", "DisputeCredential"],
<span class="highlight">"credentialSubject": {
"id": "http://example.com/credentials/245",
"currentStatus": "Disputed",
"statusReason": {
"@value": "Address is out of date",
"@language": "en"
},
}</span>,
"issuer": "https://example.com/people#me",
"issuanceDate": "2017-12-05T14:27:42Z",
"proof": { <span class="comment">...</span> }
}
</pre>
<pre class="example nohighlight" title="Another entity disputes a credential">
{
"@context": "https://w3id.org/credentials/v1",
"id": "http://example.com/credentials/321",
"type": ["VerifiableCredential", "DisputeCredential"],
<span class="highlight">"credentialSubject": {
"id": "http://example.com/credentials/245",
"currentStatus": "Disputed",
"statusReason": {
"@value": "Credential contains disputed statements",
"@language": "en"
},
"disputedClaim": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"address": "Is Wrong"
}
}</span>,
"issuer": "https://example.com/people#me",
"issuanceDate": "2017-12-05T14:27:42Z",
"proof": { <span class="comment">...</span> }
}
</pre>
<p>
In the above <a>verifiable credential</a>, the <a>issuer</a> is claiming that
the address in the disputed <a>verifiable credential</a> is wrong. For example,
the <a>subject</a> might wrongly be claiming to have the same address as that of
the <a>issuer</a>.
</p>
<p class="note">
If a <a>credential</a> does not have an identifier, a content-addressed
identifier can be used to identify the disputed <a>credential</a>. Similarly,
content-addressed identifiers can be used to uniquely identify individual
claims.
</p>
</section>
<section>
<h3>Presentations</h3>
<p>
<a>Verifiable credentials</a> may be presented to a <a>verifier</a> by
using a <a>verifiable presentation</a>. A <a>verifiable presentation</a> can
be targeted to a specific <a>verifier</a> by using a Linked Data Proof
that includes a <code>domain</code> and <code>challenge</code>. This also
helps prevent a <a>verifier</a> from reusing a <a>verifiable presentation</a>
as their own.
</p>
<p>
The <code>domain</code> value can be any string or URI, and the
<code>challenge</code> should be a randomly generated string.
</p>
<p>
The following sample <a>verifiable presentation</a> is for authenticating to
a website, <code>https://example.com</code>.
</p>
<pre class="example nohighlight" title="A targeted verifiable presentation">
{
"@context": [
"https://www.w3.org/2018/credentials/v1"
],
"type": "VerifiablePresentation,
"verifiableCredential": { <span class="comment">...</span> },
"proof": {
"type": "Ed25519Signature2018",
"created": "2019-08-13T15:09:00Z",
<span class="highlight">"challenge": "d1b23d3...3d23d32d2",
"domain": "https://example.com",</span>
"jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..uyW7Hv
VOZ8QCpLJ63wHode0OdgWjsHfJ0O8d8Kfs55dMVEg3C1Z0bYUGV49s8IlTbi3eXsNvM63n
vah79E-lAg",
"proofPurpose": "authentication"
}
}
</pre>
</section>
<section>
<h4>Using the JWT aud claim</h3>
<p>
The JWT <code>aud</code> <a>claim</a> name refers to (i.e., identifies) the
intended audience of the <a>verifiable presentation</a> (i.e., the <a>verifier(s)</a>).
Consequently this is an alternative to the Linked Data Proof method specified
above. It lets the <a>holder</a> indicate which <a>verifier(s)</a> it allows
to verify the <a>verifiable presentation</a>. Any JWT-compliant <a>verifier</a>
that is not identified in the <code>aud</code> is required to
reject the JWT (see <a href="https://tools.ietf.org/html/rfc7519">RFC 7519</a>).
</p>
<p>
<a href="https://tools.ietf.org/html/rfc7519">RFC 7519</a> defines
<code>aud</code> as "an array of case-sensitive strings, each containing a
<code>StringOrURI</code> value". For use in a <a>verifiable presentation</a>,
we strongly suggest that this be restricted to a single URI value, equal to the URI
of the intended verifier.
</p>
<p>
The <a href="https://w3c.github.io/vc-data-model/">data model specification</a>
provides no guidance of how to transform this JWT <a>claim</a> into a property
of the <a>verifiable presentation</a>, nor vice versa. We strongly suggest that the
<code>aud</code> JWT <a>claim</a> be mapped to the <code>verifier</code>
property of the <a>verifiable presentation</a>.
</p>
<pre class="example nohighlight" title="An example of a
targeted verifiable presentation using the verifier property">
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2019/credentials/v1.1"
],
"type": "VerifiablePresentation",
"verifiableCredential": [" <span class="comment">...</span> "],
"holder": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"verifier": "https://some.verifier.com"
}
</pre>
<pre class="example nohighlight" title="An example JWT for a
targeted verifiable presentation using the JWT aud claim">
{
"iss": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"jti": "urn:uuid:3978344f-8596-4c3a-a978-8fcaba3903c5",
"aud": "https://some.verifier.com",
"nbf": 1541493724,
"iat": 1541493724,
"exp": 1573029723,
"nonce": "343s$FSFDa-",
"vp": {
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credImpGuide/v1"
],
"type": "VerifiablePresentation",
"verifiableCredential": [" <span class="comment">...</span> "]
}
}
</pre>
</section>
<section>