-
Notifications
You must be signed in to change notification settings - Fork 2
/
index.html
1320 lines (1164 loc) · 70.1 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 lang="en-us">
<head>
<title>Verifiable Credentials Overview</title>
<meta http-equiv='Content-Type' content='text/html;charset=utf-8'>
<meta name="color-scheme" content="light dark">
<!--
=== 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' class='remove'></script>
<script class="remove" src="https://cdn.jsdelivr.net/gh/w3c/[email protected]/dist/main.js"></script>
<script type="text/javascript" class="remove">
var respecConfig = {
// specification status (e.g. WD, LCWD, NOTE, etc.). If in doubt use ED.
// specStatus: "DNOTE",
specStatus: "ED",
// the specification's short name, as in http://www.w3.org/TR/short-name/
shortName: "vc-overview",
// if you wish the publication date to be other than today, set this
//publishDate: "2023-11-07",
// if there a publicly available Editor's Draft, this is the link
edDraftURI: "https://w3c.github.io/vc-overview/",
// if you want to have extra CSS, append them to this list
// it is recommended that the respec.css stylesheet be kept
//extraCSS: ["spec.css", "prettify.css"],
noRecTrack: true,
// 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/",
// w3cid: 41758
// },
{
name: "Ivan Herman", url: "https://www.w3.org/People/Ivan/",
company: "W3C", companyURL: "https://www.w3.org",
w3cid: 7382, orcid: "0000-0003-0782-2704"
},
],
authors: [
{
name: "Greg Bernstein", url: "https://www.grotto-networking.com/",
company: "Invited Expert", w3cid: 140479
},
{
name: "Daniel C. Burnett", url: "https://www.linkedin.com/in/daburnett/",
company: "ConsenSys", companyURL: "https://consensys.net/",
w3cid: 37473
},
{
name: "David Chadwick",
url: "https://www.linkedin.com/in/davidwchadwick/",
company: "Crossword Cybersecurity PLC",
companyURL: "https://www.crosswordcybersecurity.com/",
w3cid: 46156
},
{
name: "Gabe Cohen", url: "https://github.com/decentralgabe",
company: "Block", companyURL: "https://block.xyz/",
w3cid: 116851
},
{
name: "Michael B. Jones", url: "https://self-issued.info/",
company: "Invited Expert",
w3cid: 38745
},
{
name: "Dave Longley", url: "https://digitalbazaar.com/",
company: "Digital Bazaar", companyURL: "https://digitalbazaar.com/",
w3cid: 48025
},
{
name: "Manu Sporny", url: "https://digitalbazaar.com/",
company: "Digital Bazaar", companyURL: "https://digitalbazaar.com/",
w3cid: 41758
},
{
name: "Orie Steele", url: "https://github.com/OR13",
company: "Transmute",
companyURL: "https://www.transmute.industries/",
w3cid: 109171
},
{
name: "Ted Thibodeau Jr", url: "https://github.com/TallTed",
company: "OpenLink Software", companyURL: "https://www.openlinksw.com/",
w3cid: 42501
},
{
name: "Brent Zundel", url: "https://www.linkedin.com/in/bzundel/",
company: "mesur.io", companyURL: "https://www.mesur.io",
w3cid: 102128
},
],
// name of the WG
group: "vc",
// name (with the @w3c.org) of the public mailing to which comments are due
wgPublicList: "public-vc-wg",
github: "w3c/vc-overview",
// 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: "",
maxTocLevel: 4,
lint: { "informative-dfn": false },
/*preProcess: [ ],
alternateFormats: [ {uri: "diff-20111214.html", label: "diff to previous version"} ],
*/
localBiblio: {
"MULTIBASE": {
title: "The Multibase Data Format",
date: "February 2023",
href: "https://datatracker.ietf.org/doc/draft-multiformats-multibase",
authors: [
"Juan Benet",
"Manu Sporny"
],
status: "Internet-Draft",
publisher: "IETF"
},
"MULTIHASH": {
title: "The Multihash Data Format",
date: "February 2023",
href: "https://datatracker.ietf.org/doc/draft-multiformats-multihash",
authors: [
"Juan Benet",
"Manu Sporny"
],
status: "Internet-Draft",
publisher: "IETF"
},
"MULTICODEC": {
title: "The Multi Codec Encoding Scheme",
date: "February 2022",
href: "https://github.com/multiformats/multicodec/blob/master/table.csv",
authors: [
"The Multiformats Community"
],
status: "Internet-Draft",
publisher: "IETF"
},
"SD-JWT": {
title: "Selective Disclosure for JWTs (SD-JWT)",
href: "https://datatracker.ietf.org/doc/draft-ietf-oauth-selective-disclosure-jwt/",
authors: [
"Daniel Fett",
"Kristina Yasuda",
"Brian Campbell"
],
status: "I-D",
publisher: "The IETF OAuth Working Group"
},
"CFRG-BBS-SIGNATURE": {
title: "The BBS Signature Scheme",
href: "https://www.ietf.org/archive/id/draft-irtf-cfrg-bbs-signatures-05.html",
authors: [
"Tobias Looker",
"Vasilis Kalos",
"Andrew Whitehead",
"Mike Lodder",
],
status: "I-D",
publisher: "IETF"
}
},
postProcess: [
window.respecVc.createVcExamples
],
};
</script>
<style>
pre {
overflow-x: auto;
white-space: pre-wrap;
}
pre .highlight {
font-weight: bold;
color: Green;
}
pre .highlight2 {
font-weight: bold;
color: teal;
}
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;
}
code {
color: rgb(199, 73, 0);
font-weight: bold;
}
pre.nohighlight {
overflow-x: auto;
white-space: pre-wrap;
}
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>
Credentials are a part of our daily lives; driver's licenses are used to assert that we are capable of operating a motor vehicle, university degrees can be used to assert our level of education, and government-issued passports enable us to travel between countries.
The family of W3C Recommendations for Verifiable Credentials, described in this overview document, provides a mechanism to express these sorts of credentials on the Web in a way that is cryptographically secure, privacy respecting, and machine-verifiable.
</p>
</section>
<section id='sotd'>
</section>
<section>
<!-- MARK: Introduction -->
<h2>Introduction</h2>
<p>
This document provides a non-normative, high-level overview for W3C's Verifiable Credential specifications and serves as a roadmap for the documents that define, describe, and secure these credentials.
It is not the goal of this document to be very precise, nor does this overview cover all the details.
The intention is to provide users, implementers, or anyone interested in the subject, a general understanding of the concepts and how the various specifications, published by the Verifiable Credentials Working Group, fit together.
</p>
<section>
<!--MARK: High Level Overview -->
<h2>High Level View of the Specifications</h2>
<p>
<a href="#overall"></a> provides an overview of the main building blocks for Verifiable Credentials, including their (normative) dependencies.
For more details, see the subsequent sections in this document.
</p>
<p>
The [[[VC-DATA-MODEL-2.0]]] [[VC-DATA-MODEL-2.0]] specification, which defines the core concepts that all other specifications depend on, plays a central role.
The model is defined in abstract terms, and applications express their specific credentials using a serialization of the data model.
The current specifications mostly use a JSON serialization; the community may develop other serializations in the future.
</p>
<p>
When Verifiable Credentials are serialized in JSON, it is important to trust that the structure of a Credential may be interpreted in a consistent manner by all participants in the verifiable credential ecosystem.
The [[[VC-JSON-SCHEMA]]] [[VC-JSON-SCHEMA]] defines how [[JSON-SCHEMA]] can be used for that purpose.
</p>
<p>
Credentials can be secured using two different mechanisms: [=enveloping proofs=] or [=embedded proofs=].
In both cases, a Credential is cryptographically secured by a proof (for example, using digital signatures).
In the enveloping case, the proof wraps around the Credential, whereas embedded proofs are included in the serialization, alongside the Credential itself.
</p>
<p>
A family of enveloping proofs is defined in the [[[VC-JOSE-COSE]]] [[VC-JOSE-COSE]] document, relying on technologies defined by the IETF.
Other types of enveloping proofs may be specified by the community.
</p>
<p>
The general structure for embedded proofs is defined in a separate [[[VC-DATA-INTEGRITY]]] [[VC-DATA-INTEGRITY]] specification.
Furthermore, the Working Group also specifies some instances of this general structure in the form of the "cryptosuites": [[[VC-DI-EDDSA]]] [[VC-DI-EDDSA]], [[[VC-DI-ECDSA]]] [[VC-DI-ECDSA]], and [[[VC-DI-BBS]]] [[VC-DI-BBS]].
Other cryptosuites may be specified by the community.
</p>
<p>
The [[[VC-BITSTRING-STATUS-LIST]]] [[VC-BITSTRING-STATUS-LIST]] specification defines a privacy-preserving, space-efficient, and high-performance mechanism for publishing the status of a specific Verifiable Credential, such as its suspension or revocation, through the use of bitstrings.
</p>
<p>
Finally, the [[[CONTROLLER-DOCUMENT]]] [[CONTROLLER-DOCUMENT]] specification defines some common terms (e.g., verification <a href="https://www.w3.org/TR/controller-document/#verification-relationships">relationships</a> and
<a href="https://www.w3.org/TR/controller-document/#dfn-verification-method">methods</a>) that are used not only by other Verifiable Credential specifications, but also other Recommendations such as [[[DID-CORE]]] [[DID-CORE]].
</p>
<figure id="overall">
<img style="margin: auto; display: block; width: 100%;" src="diagrams/VCWG_specifications.svg"
alt="Diagram illustrating the structure of the Verifiable Credential (VC) specifications, using boxes labeled with references to the specification. Arrows on the diagram connect some of the boxes to represent (normative) dependencies. The box labeled as the VC Data Model is at the top-center of the diagram. Additional component boxes — such as JSON Schema for structural checking; Bitstring Status List for publishing status information; and Controller Documents for verification methods and relationships — are related to the VC Data Model. The box for securing mechanisms contain separate boxes for embedded proofs, on the left, and enveloping proofs, on the right. The box for embedded proofs contains a box labeled as Data Integrity, which depends both on the VC Data Model and on Controller Documents, as well as boxes for the ECDSA, EdDSA, and BBS Cryptosuites, supporting different elliptic curves and signature schemes; all of these depend on Data Integrity, and the BBS Cryptosuites also depend on ECDSA. The enveloping proofs box contains a single box labeled as 'JOSE and COSE ... using JWS, SD-JWT, or CBOR'; as with Data Integrity, this depends both on the VC Data Model and on Controller Documents.">
<figcaption style="text-align: center;">
Verifiable Credentials Working Group Recommendations
</figcaption>
</figure>
</section>
</section>
<section>
<!--MARK: Ecosystem Overview -->
<h3>Ecosystem Overview</h3>
<p>
The Verifiable Credential specifications rely on an ecosystem consisting of entities playing different "roles".
The main roles are:
</p>
<dl>
<dt>Issuer</dt>
<dd>
An entity that <em>creates</em> a Verifiable Credential, consisting of a series of statements related to its subject.
An example is a university that issues credentials for university degrees or certificates for alumni.
</dd>
<dt>Holder</dt>
<dd>
An entity that <em>possesses</em> one or more Credentials, and that can transmit <em>presentations</em> of those
Verifiable Credentials to third parties.
An example may be the person who "holds" his/her own educational degrees.
Another example may be a digital wallet that contains several Credentials on someone's behalf.
</dd>
<dt>Verifier</dt>
<dd>
An entity that performs verification on a Verifiable Credential to check the validity, consistency, etc., of a Credential.
An example may be an employer's digital system that checks the validity of a university degree before deciding on the
employment of a person.
</dd>
</dl>
<p>
For a more precise definition of these roles, as well as other roles, see the relevant <a
data-cite="VC-DATA-MODEL-2.0#ecosystem-overview">section</a> in the data model specification.
</p>
<figure id="roles">
<img style="margin: auto; display: block; width: 100%;" src="diagrams/ecosystem.svg"
alt="Diagram showing how credentials flow from issuer to holder, and presentations flow from holder to verifier, where all three parties can use information from a logical verifiable data registry.">
<figcaption style="text-align: center;">
The roles and information flows forming the basis for the VC Data Model.
</figcaption>
</figure>
</section>
<section id="s_vcdm">
<!--MARK: VCDM Model -->
<h2>Verifiable Credentials Data Model</h2>
<section>
<!--MARK: Basic Structure -->
<h3>Basic Concepts</h3>
<section>
<!--MARK: Claims, Properties -->
<h4>Claims, Properties</h4>
<p>
A core concept is "claims": statements made about various entities, referred to as "subjects".
Subjects may be a holder, an issuer, or a verifier as listed above, but may also any be another person (e.g., the person holding a university degree), an animal, an abstract concept, etc.
Claims may also be on a Credential itself, such as issuance date, validity periods, etc.
(Such claims are also loosely referred to as "credential metadata".)
</p>
<p>
Claims are expressed using "properties" referring to "values".
Values may be literals, but may also be other entities referred to, usually, by a [[URL]].
It that case, the entity may become the subject of another claim; these claims, together, form a "graph" of claims that represents a Credential.
(See <a href="#credential-example-claims"></a> for an example of such a graph represented graphically.
For more complex examples, refer to the [[[VC-DATA-MODEL-2.0]]] specification itself.)
</p>
<figure id="basic-structure">
<img style="margin: auto; display: block; width: 80%;" src="diagrams/claim.svg" alt="Diagram showing an ellipse on the left labeled as 'Subject', connected by an arrow from left to right labeled as 'Property', to a box on the right labeled as 'Value'.">
<figcaption style="text-align: center;">
The basic structure of a claim with (in this case) a literal value.
</figcaption>
</figure>
<p>
The [[[VC-DATA-MODEL-2.0]]] document specifies a number of standard properties. These include, for example, `credentialSubject`, `type`, `issuer`, or `validFrom`.
Developers may define their own properties to express specific types of Credentials, like a driving license, a university degree, or a marriage certificate.
</p>
</section>
<section>
<!--MARK: Verifiable Credentials -->
<h4>Verifiable Credentials</h4>
<p>
A <em>Credential</em> is a set of one or more claims made by the same entity.
Credentials might also include an identifier and metadata to describe properties of the Credential, such as a reference to the issuer, the validity date, a representative image, the revocation mechanism, and so on.
A <em>Verifiable Credential</em> is a set of claims and metadata that also includes verification mechanisms that cryptographically prove who issued it, ensures that the data has not been tampered with, etc.
</p>
<p>
For a more detailed description of abstract Verifiable Credentials, with examples, see the relevant <a data-cite="VC-DATA-MODEL-2.0#credentials">section</a> in the data model specification.
</p>
<figure id="basic-vc">
<img style="margin: auto; display: block; width: 35%;" src="diagrams/vc.svg"
alt="Diagram showing a lozenge labeled as 'Verifiable Credential' containing three vertically stacked lozenges, labeled as 'Credential Metadata', 'Claim(s)', and 'Proof(s)'.">
<figcaption style="text-align: center;">
Basic components of a Verifiable Credential.
</figcaption>
</figure>
</section>
<section>
<!--MARK: Verifiable Presentations -->
<h4>Verifiable Presentations</h4>
<p>
Enhancing privacy is a key design feature of Verifiable Credentials.
Therefore, it is important, for entities using this technology, to be able to express only the portions of their persona that are appropriate for a given situation.
The expression of a subset of one's persona is called a <em>Verifiable Presentation</em>.
Examples of different personas include a person's professional persona, their online gaming persona, their family persona, or an incognito persona.
</p>
<p>
A Verifiable Presentation is created by a holder, can express data stemming from multiple Verifiable Credentials, and can contain additional metadata in forms of additional claims.
They are used to present claims to a verifier.
It is also possible to present Verifiable Credential directly.
</p>
<p>
A Verifiable Presentation is usually short-lived, it is not meant to be stored for a longer period.
</p>
<p>
For a more detailed description of abstract Verifiable Presentations, with examples, see the relevant <a data-cite="VC-DATA-MODEL-2.0#presentations">section</a> in the data model specification.
</p>
<figure id="basic-vp">
<img style="margin: auto; display: block; width: 35%;" src="diagrams/presentation.svg"
alt="Diagram showing a lozenge labeled as 'Verifiable Presentation' containing three vertically stacked lozenges, labeled as 'Presentation Metadata', 'Verifiable Credential(s)', and 'Proof(s)'.">
<figcaption style="text-align: center;">
Basic components of a verifiable presentation.
</figcaption>
</figure>
</section>
</section>
<section>
<!--MARK: Serialization in JSON -->
<h3>Serialization in JSON</h3>
<p>
In the [[VC-DATA-MODEL-2.0]] specification, as in the other documents, Verifiable Credentials and Presentations are mostly expressed in JSON [[RFC7519]], more specifically [[JSON-LD11]].
In this serialization, properties of claims are represented as JSON names, and values as JSON literals or objects.
Subjects of claims are either explicitly identified by an `id` property, or implicitly by appearing as an object of another claim.
</p>
<p id="p_vocabularies">
Standard properties defined by the [[VC-DATA-MODEL-2.0]] form a distinct set of JSON names, referred to as a (standard) <em>vocabulary</em>.
An important characteristics of Verifiable Credentials in JSON-LD is that it favors a decentralized and permissionless approach to <em>extend</em> to a new application area through application-specific set of properties, i.e., vocabularies, distributed on the Web.
Anyone can "publish" such a vocabulary, following some rules described in the <a data-cite="VC-DATA-MODEL-2.0#extensibility">extensibility section</a> of the specification.
</p>
<p>
The following JSON-LD code is an example for a simple Credential. It states that the person named "Pat", identified by <code>https://www.exampl.org/persons/pat</code>, is an alumni of the Example University (identified by <code>did:example:c276e12ec21ebfeb1f712ebc6f1</code>).
The Credential is valid from the 1st of January 2010, and is issued by an entity identified by <code>did:example:2g55q912ec3476eba2l9812ecbfe</code>.
Most of the properties in the Credential are from the standard Verifiable Credentials vocabulary, but some terms (like `alumniOf`, `AlumniCredential`) are added by the application-specific vocabulary referred to by <code>https://www.w3.org/ns/credentials/examples/v2</code>.
</p>
<pre id="base_example" class="example nohighlight" title="A Simple Credential">
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "https://university.example/Credential123",
"type": ["VerifiableCredential", "ExampleAlumniCredential"],
"issuer": "did:example:2g55q912ec3476eba2l9812ecbfe",
"validFrom": "2010-01-01T00:00:00Z",
"credentialSubject": {
"id": "https://www.example.org/persons/pat",
"name": "Pat",
"alumniOf": {
"id": "did:example:c276e12ec21ebfeb1f712ebc6f1",
"name": "Example University"
}
}
}
</pre>
<p>
<a href="#credential-example-claims"></a> shows the same Credential, but represented as a graph of claims, as described in <a href="#claims-properties"></a>.
</p>
<figure id="credential-example-claims">
<img style="margin: auto; display: block; width: 100%;" src="diagrams/credential_example.svg" alt="Diagram showing an example of a Verifiable Credential. At top, there is an ellipse labeled 'https://university.example/Credential123 (Type: VerifiableCredential, ExampleAlumniCredential)'. This ellipse has two arrows going down. One arrow is nearer the right side of the ellipse, is labeled as 'validFrom', angles to the right, and terminates at a box labeled as '2010-01-01T00:00:00Z'. The second arrow is at the middle of the ellipse, is labeled as 'credentialSubject', and ends at an ellipse labeled as 'https://www.example.org/persons/pat'. This ellipse has two more arrows going down. One arrow is nearer the right side of the ellipse, is labeled as 'name', and angles to the right, terminating at a box labeled as 'Pat'. The second arrow is nearer the left side of the ellipse, labeled as 'alumniOf', and ends at another ellipse labeled as 'did:example:c276e12ec21ebfeb1f712ebc6f1'. This ellipse has a final arrow going down, which is labeled as 'name' and ends at a final box labeled as 'Example University'.">
<figcaption style="text-align: center;">
Credential in <a href="#base_example"></a> represented as a collection of claims.
</figcaption>
</figure>
<p class="note">
The Credential in <a href="#base_example"></a> is used throughout this document to show how to apply additional features defined by the various specifications.
</p>
<p>
The Credential in <a href="#base_example"></a>, issued by Example University, is stored by a holder (who may be a person, a digital wallet, or any other entity). On request, the holder may "present" a Credential to a verifier, encapsulated in a Verifiable Presentation. This is how the result may look like in the JSON-LD serialization:
</p>
<pre class="example nohighlight" title="Presenting the Credential">
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"type": "VerifiablePresentation",
"id": "urn:uuid:313801ba-24b7-11ee-be02-ff560265cf9b",
"holder": "did:example:12345678",
"validUntil": "2020-12-31T00:00:00Z"
<span class="highlight">"verifiableCredential": {
"id": "https://university.example/Credential123",
"type": ["VerifiableCredential", "ExampleAlumniCredential"],
"issuer": "did:example:2g55q912ec3476eba2l9812ecbfe",
"validFrom": "2010-01-01T00:00:00Z",
"credentialSubject": {
"id": "https://www.example.org/persons/pat",
"name": "Pat",
"alumniOf": {
"id": "did:example:c276e12ec21ebfeb1f712ebc6f1",
"name": "Example University"
}
}
}</span>
}
</pre>
<p>
Note that the holder could have presented several Credentials within the same presentation or create a new Credential by either combining it with others, or removing some claims as irrelevant for the specific context.
</p>
</section>
<section id="s_js_schema">
<!--MARK: JSON Schemas -->
<h4>Checking Structure with JSON Schemas</h4>
<p>
A significant part of the integrity of a Verifiable Credential comes from the ability to structure its contents so that all three parties — issuer, holder, verifier — may have a consistent mechanism of trust in interpreting the data that they are provided with.
One way of doing that is to use [[JSON-SCHEMA]] to check the structural validity of the Credential.
The [[[VC-JSON-SCHEMA]]] [[VC-JSON-SCHEMA]] specification adds standard properties to express the association of a Credential with a JSON Schema.
</p>
<p>
Consider the following example:
</p>
<pre id="base_example_schema" class="example nohighlight" title="A Simple Credential with a JSON Schema">
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "https://university.example/Credential123",
"type": ["VerifiableCredential", "ExampleAlumniCredential"],
"issuer": "did:example:2g55q912ec3476eba2l9812ecbfe",
"validFrom": "2010-01-01T00:00:00Z",
"credentialSubject": {
"id": "https://www.example.org/persons/pat",
"name": "Pat",
"alumniOf": {
"id": "did:example:c276e12ec21ebfeb1f712ebc6f1",
"name": "Example University"
}
},
<span class="highlight">"credentialSchema": {
"id": "https://university.example/Credential-schema.json",
"type": "JsonSchema"
}</span>
}
</pre>
<p>When dereferenced, the URL `https://university.example/Credential-schema.json` should return a JSON Schema, for example:</p>
<pre class="example nohighlight" title="JSON Schema for the Simple Credential">
{
"$id": "https://university.example/schemas/credential.json",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "ExampleAlumniCredential",
"description": "Alumni Credential using JsonSchema",
"type": "object",
"properties": {
"credentialSubject": {
"type": "object",
"properties": {
"alumniOf": {
"type": "string",
"format": "url"
}
},
"required": [
"alumniOf"
]
}
}
}
</pre>
<p>
Using this JSON Schema, a verifier can check whether the Credential is structurally valid or not.
</p>
<p>
For security reasons one may want to go a step further: check/verify the JSON Schema itself to see if, for example, it has been tempered with.
This can be done by referring to the JSON Schema <em>indirectly through a separate Verifiable Credential</em>.
The reference to such a Verifiable Credential looks very much like <a href="#base_example_schema"></a> except for the value of the `type`:
</p>
<pre class="example nohighlight" title="A Simple Credential with a JSON Schema Credential">
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "https://university.example/Credential123",
"type": ["VerifiableCredential", "ExampleAlumniCredential"],
"issuer": "did:example:2g55q912ec3476eba2l9812ecbfe",
"validFrom": "2010-01-01T00:00:00Z",
"credentialSubject": {
"id": "https://www.example.org/persons/pat",
"name": "Pat",
"alumniOf": {
"id": "did:example:c276e12ec21ebfeb1f712ebc6f1",
"name": "Example University"
}
},
<span class="highlight">"credentialSchema": {
"id": "https://university.example/Credential-schema-credential",
"type": "JsonSchemaCredential"
}</span>
}
</pre>
<p>
In this case, when dereferenced, the URL `https://university.example/Credential-schema-credential` should return a Verifiable Credential, whose `credentialSubject` property refers to the required JSON Schema (i.e., <code>https://university.example/Credential-schema.json</code>).
See the <a data-cite="VC-JSON-SCHEMA#jsonschemacredential">example</a> in the [[[VC-JSON-SCHEMA]]] specification for an example and for further details.
</p>
</section>
</section>
<section>
<!--MARK: Securing Credentials -->
<h2>Securing Credentials</h2>
<section>
<!--MARK: Enveloping Proofs -->
<h3>Enveloping Proofs</h3>
<p>
Enveloping proofs of Credentials, defined by this Working Group, are based on JSON Object Signing and Encryption
(<a href="https://datatracker.ietf.org/wg/jose/about/">JOSE</a>), CBOR Object Signing and Encryption (COSE) [[RFC9052]], or Selective Disclosure for JWTs [[SD-JWT]].
These are all IETF specifications, or groups of specifications (like JOSE, that refers to JWT [[RFC7519]], JWS [[RFC7515]], or JWK [[RFC7517]]).
The [[[VC-JOSE-COSE]]] [[VC-JOSE-COSE]] recommendation defines a "bridge" between these and the [[[VC-DATA-MODEL-2.0]]],
specifying the suitable header claims, media types, etc.
</p>
<p>
In the case of JOSE, the Credential is the "payload" (to use the IETF terminology).
This is preceded by a suitable header whose details are specified by the relevant
<a data-cite="VC-JOSE-COSE#with-jose">section</a> of the [[VC-JOSE-COSE]] specification.
These are encoded, concatenated, and signed, to be transferred in a compact form by one entity to another
(e.g., sent by the holder to the verifier).
All the intricate details on signatures, encryption keys, etc., are defined by the IETF specifications; see <a href="#base_example_jwt_unencoded"></a> for a specific case.
</p>
<p>
The usage of COSE [[RFC9052]] is similar to JOSE, except that all structures are represented in CBOR [[RFC8949]].
From the Credentials point of view, however, the structure is similar insofar as the Credential (or the Presentation)
is again the payload for COSE.
The usage of CBOR means that the final representation of the Verifiable Credential (or Presentation) has a significantly reduced footprint which can be, for example, shown in a QR Code.
</p>
<p>
The [[SD-JWT]] is a variant of JOSE, which allows for the selective disclosure of individual claims.
Claims can be selectively hidden or revealed to the verifier, but all claims are cryptographically
protected against modification.
This approach is obviously more complicated than the JOSE case but, from the Credentials point of view, the structure
is again similar.
The original Credential is the payload for SD-JWT; and it is the holder's responsibility to use the SD-JWT
when presenting the Credential to a verifier using selective disclosure.
</p>
<section>
<!--MARK: Core Example with JOSE -->
<h4>Example: the Core Example Secured with JOSE and COSE</h4>
<p>
<a href="#base_example_jwt_unencoded"></a> shows the Credential example shown in <a href="#base_example"></a>,
enriched with a reference to a JSON Schema in <a href="#base_example_schema"></a>.
It is secured by two different enveloping proofs, namely JOSE and COSE.
</p>
<pre id="base_example_jwt_unencoded" class="example nohighlight vc" title="A Simple Credential in JWT (unencoded)"
data-vc-vm="https://university.example/issuers/565049#key-1"
data-vc-tabs="jose cose">
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "https://university.example/Credential123",
"type": ["VerifiableCredential", "ExampleAlumniCredential"],
"issuer": "did:example:2g55q912ec3476eba2l9812ecbfe",
"validFrom": "2010-01-01T00:00:00Z",
"credentialSubject": {
"id": "https://www.example.org/persons/pat",
"name": "Pat",
"alumniOf": {
"id": "did:example:c276e12ec21ebfeb1f712ebc6f1",
"name": "Example University"
}
},
"credentialSchema": {
"id": "https://university.example/Credential123-schema-credential",
"type": "JsonSchemaCredential"
}
}
</pre>
</section>
</section>
<section>
<!--MARK: Embedded Proofs -->
<h3>Embedded Proofs</h3>
<section>
<!--MARK: DI Generic Structures -->
<h4 id="proof-generation-steps">Creation of Proofs in Data Integrity</h4>
<p>
The operation of Data Integrity is conceptually simple. To create a cryptographic proof, the following steps are performed: 1) Transformation, 2) Hashing, and 3) Proof Generation.
</p>
<figure id="proof-generation-steps-figure">
<img style="margin: auto; display: block; width: 90%;" src="diagrams/di_crypto_proof.svg" alt="Simple flow diagram, with steps from left to right, labeled as 'Data', 'Transform Data', 'Hash Data', 'Generate Proof', and 'Data with Proof'.">
<figcaption style="text-align: center;">
View of the proof generation steps.
</figcaption>
</figure>
<ol>
<li>
<em>Transformation</em> is a process described by a <em>transformation algorithm</em> that takes input data and prepares it for the hashing process.
In the case of data serialized in JSON this transformation includes the removal of all the artifacts that do not influence the semantics of the data, such as spaces, new lines, the order of JSON names, etc. (a step often referred to as <em>canonicalization</em>).
In some cases the transformation may be more involved.
</li>
<li>
<em>Hashing</em> is a process described by a <em>hashing algorithm</em> that calculates an identifier for the transformed data using a
<a href="https://en.wikipedia.org/wiki/Cryptographic_hash_function">cryptographic hash function</a>.
Typically, the size of the resulting hash is smaller than the data, which makes it more suitable for complex cryptographic functions like digital signatures.
</li>
<li>
<em>Proof Generation</em> is a process described by a <em>proof method</em> that calculates a value that protects the
integrity of the input data from modification or otherwise proves a certain desired threshold of trust.
A typical example is the application of a cryptographic signature using asymmetric keys, generating the signature of the data.
</li>
</ol>
<p>
<em>Verification</em> of a proof involves repeating the same transformation and hashing steps on the verifier's side and, depending on the proof method, validating the newly calculated hash value with the proof associated with the data.
In the case of a digital signature, this means verifying, using the cryptographic algorithms associated with the asymmetric keys, that the proof value indeed signs the newly calculated hash.
</p>
</section>
<section id="s_di">
<!--MARK: VC DI -->
<h4>Data Integrity of Credentials</h4>
<p>
The [[[VC-DATA-INTEGRITY]]] [[VC-DATA-INTEGRITY]] specification relies on the general structure and defines a set of standard properties describing the details of the proof generation process.
The specific details (canonicalization algorithm, hash and/or proof method algorithms, etc.) are defined by separate <em>cryptosuites</em>.
The Working Group has defined a number of such cryptosuites as separate specifications, see <a href="#cryptosuites"></a> below.
</p>
<p>
The core property, in the general structure, is `proof`.
This property embeds a claim in the Credential, referring to a separate collection of claims (referred to as a <em>Proof Graph</em>) detailing all the claims about the proof itself:
</p>
<pre class="example nohighlight" title="Skeleton of a proof added to a Credential">
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "https://university.example/Credential123",
"type": ["VerifiableCredential", "ExampleAlumniCredential"],
"issuer": "did:example:2g55q912ec3476eba2l9812ecbfe",
"validFrom": "2010-01-01T00:00:00Z",
"credentialSubject": {
"id": "https://www.example.org/persons/pat",
"name": "Pat",
"alumniOf": {
"id": "did:example:c276e12ec21ebfeb1f712ebc6f1",
"name": "Example University"
}
},
"credentialSchema": {
"id": "https://university.example/Credential123-schema-credential",
"type": "JsonSchemaCredential"
},
<span class="highlight">"proof": {
"type": "DataIntegrityProof",</span>
<span class="comment">…
// All the details about the proof
…</span>
<span class="highlight">"proofValue": "zQeVb…Wx"
}</span>
}
</pre>
<p>
Note the `proofValue` property, whose object is the result of the proof generation process.
</p>
<p class="note">
The proof value is for illustrative purposes only, and does not reflect the result of real cryptographic calculations.
</p>
<p>
The <a data-cite="VC-DATA-INTEGRITY#proofs">definition of `proof`</a> introduces a number of additional properties.
Some of these are metadata properties on the proof itself, like `created`, `expires`, or `domain`.
Others provide the necessary details on the proof generation process itself, like `cryptosuite`, `nonce` (if needed), or `verificationMethod` that usually refers to cryptographic keys.
The exact format of the public keys, when used for Credentials, is defined in the [[CONTROLLER-DOCUMENT]] specification, and is based on either the JWK [[RFC7517]] format or a <a data-cite="CONTROLLER-DOCUMENT#multibase-0">Multibase</a> encoding of the keys, called <a data-cite="CONTROLLER-DOCUMENT#multikey">Multikey</a>.
Details of the key values are defined by other communities (IETF, cryptography groups, etc.) and are dependent on the specific cryptographic functions they operate with.
</p>
<p>
It is possible to embed several proofs for the same Credential.
These may be a set of independent proofs (based, for example, on different cryptosuites, to accommodate to the specificities of different verifiers), but may also be a "chain" of proofs that must be evaluated in a given order.
</p>
<p>
A proof may also specify its "purpose" via the `proofPurpose` property: different proofs may be provided for authentication, for assertion, or for key agreement protocols.
These are defined in the [[CONTROLLER-DOCUMENT]] specification.
The verifier is supposed to choose the right proof depending on the purpose of its own operations, which is yet another possible reasons why the holder or the issuer may provide several proofs for the same Credential.
</p>
</section>
<section>
<!--MARK: Cryptosuites -->
<h4>Cryptosuites</h4>
<p>
The Working Group publishes three cryptosuite documents: [[[VC-DI-EDDSA]]] [[VC-DI-EDDSA]], [[[VC-DI-ECDSA]]] [[VC-DI-ECDSA]], and [[[VC-DI-BBS]]] [[VC-DI-BBS]].
As their name suggests, the documents rely on existing cryptographic signature schemes: the Edwards-Curve Digital Signature Algorithm (EdDSA) specification [[RFC8032]], the Elliptic Curve Digital Signature Algorithm (ECDSA) specification [[FIPS-186-5]], and the BBS Signature Scheme [[CFRG-BBS-SIGNATURE]], respectively.
</p>
<p>
<a href="#cryptosuites-diagram"></a> provides an overall view of the six cryptosuites defined by the three recommendations.
They all implement the general pipeline of proof generation as described in <a href="#proof-generation-steps">section 4.2.1</a>.
As shown on the figure, one axes of differentiation is the data transformation function, i.e., the canonicalization of the JSON serialization: two cryptosuites use JSON Canonicalization (JCS) [[RFC8785]], the others use RDF Dataset Canonicalization (RDFC-1.0) [[RDF-CANON]].
The other axis is whether the cryptosuite provides selective disclosure, which is the case for two of the six
cryptosuites.
</p>
<figure id="cryptosuites-diagram">
<img style="margin: auto; display: block; width: 90%;" src="diagrams/cryptosuites.svg" alt="The image is a flowchart showing the categorization of various cryptographic suites and their respective canonicalization methods. The chart branches from an initial box labeled 'Cryptosuites', to three main cryptosuite documents: 'EdDSA (based on Edwards curves)', 'ECDSA (based on ECDSA curves)', and 'BBS (based on BBS schemes)'. The EdDSA suite further divides into two specific cryptosuites: 'eddsa-rdfc-2022 (using RDFC-1.0 for canonicalization)' and 'eddsa-jcs-2022 (using JCS for canonicalization)'. The ECDSA suite branches into three specific cryptosuites: 'ecdsa-rdfc-2019 (using RDFC-1.0 or canonicalization)', 'ecdsa-jcs-2019 (using JCS canonicalization)', and 'ecdsa-sd-2023 (using RDFC-1.0 for canonicalization and providing selective disclosure schemes)'. The BBS suite splits into one method: 'bbs-2023 (using RDFC-1.0 for canonicalization and providing selective disclosure schemes)'. There is an additional dotted lozenge, labeled 'Selective disclosure schemes', which contains the 'ecdsa-sd-2023' and 'bbs-2023' documents.">
<figcaption style="text-align: center;">
Overall view of cryptosuites.
</figcaption>
</figure>
<p class="note">
A common characteristics of all these cryptosuites is that keys must always be encoded using the <a data-cite="CONTROLLER-DOCUMENT#multikey">Multikey</a> encoding.
For the ECDSA case the keys may also carry the choice of the hash functions to be used by the proof generation algorithm.
This provides yet another differentiation axis among cryptosuites.
</p>
<section>
<h5>Full Disclosure Schemes</h5>
<p>
The two EdDSA cryptosuites, as well as `ecdsa-rdfc-2019` and `ecdsa-jcs-2019`, follow a simple version of the proof generation pipeline as described in <a href="#proof-generation-steps">section 4.2.1</a>: the Credential is canonicalized (using either JCS or RDFC-1.0) and the result is hashed (using the hash functions as defined by the signature key).
The calculation of the hash values depend on the canonicalization method: in the JCS case the canonical JSON data is hashed directly, whereas
in the RDFC-1.0 case the individual canonicalized claims are first sorted and then concatenated before being hashed.
</p>
<p>
However, before signing the hash values, there is an extra twist: the same pipeline is also used on a set of claims called <em>proof options</em>, i.e., all the claims
of the proof graph <em>except</em> `proofValue`.
This set of claims is also canonicalized and hashed, following the same process as for the Credential itself, yielding a second hash value.
<em>It is the concatenation of these two values</em> that is signed by EdDSA or ECDSA, respectively, producing the value for the `proofValue` property.
By doing so, the various proof metadata, as well as the public key reference itself, are also signed and become verifiable.
</p>
</section>
<section>
<h5>Selective Disclosure Schemes</h5>
<p>
The `ecdsa-sd-2023` and `bbs-2023` cryptosuites provide selective disclosures of individual claims.
In both cases, the process separates the <em>base proof</em> (calculated by the issuer for the holder), and the <em>derived proof</em> (which is typically calculated by the holder when selectively presenting credential claims to the verifier).
</p>
<p>
To calculate the base proof, the Credential is supplemented with extra information that separates the <em>mandatory</em> and <em>non-mandatory</em> claims.
Using that information, the issuer's transformation step in <a href="#proof-generation-steps">section 4.2.1</a> produces a
data structure containing the hash of the proof options (much like in the case of the full disclosure schemes) and of the set of mandatory claims, plus the identification of mandatory claims.
Some elements of this data structure are then signed, the resulting structure is converted into CBOR, and
encoded to provide as a multibase-encoded `proofValue`.
</p>
<p>
The derived proof is generated by the holder upon a request containing JSON pointers [[RFC6901]] identifying the claims to be disclosed.
To answer the request the information in the `proofValue` is used to create a <em>reveal document</em>, i.e., a new Credential containing the mandatory claims and the requested non-mandatory claims.
Finally, the holder generates a derived proof for this reveal document, which is sent to the verifier.
</p>
<p>
The verifier should be in position to trust the proof of the reveal document without having access to the original data and its (base) proof.
In the `ecdsa-sd-2023` case, each non-mandatory claim is signed separately by the issuer using a common, ephemeral ECDSA secret key, whose public counterpart is part of the both the base and derived proof values. That can be used to check the disclosed non-mandatory claims.
The `bbs-2023` case relies on the cryptographic properties of the BBS scheme itself, which support the creation proofs for the verification of selectively disclosed data.
This is based on the mathematical nature of the BBS scheme: the <em>BBS signature</em> of all the claims (generated by the issuer and part of the base proof) can be reused by the holder to generate a <em>BBS Proof</em> of the subset of the claims (which is part of the derived proof). The BBS specific verification step ensures the required trust.
</p>
<p>
It is worth noting that the `bbs-2023` cryptosuite also offers a number of additional, privacy preserving options; see the sections on
<a data-cite="VC-DI-BBS#pseudonyms-with-hidden-pid">anonymous holder biding</a>,
<a data-cite="VC-DI-BBS#pseudonyms-with-issuer-known-pid">pseudonyms with issuer-known id</a>, or
<a data-cite="VC-DI-BBS#pseudonyms-with-hidden-pid">pseudonyms with hidden id</a> in the [[[VC-DI-BBS]]] specification.
</p>
</section>
</section>
<section>
<!--MARK: Core example with ECDSA -->
<h4>Example: the Core Example Secured with EdDSA and ECDSA</h4>
<p>
<a href="#base_example_secured_di"></a> shows the Credential example, shown in <a href="#base_example"></a> and enriched with a reference to a JSON Schema in <a href="#base_example_schema"></a>.
It is secured by two different embedded proofs, using the `ecdsa-rdfc-2019` and `eddsa-rdfc-2022` cryptosuites.
</p>
<pre id="base_example_secured_di" class="example nohighlight vc" title="EdDSA and ECDSA proofs added to a Credential"
data-vc-vm="https://university.example/issuers/565049#key-1"
data-vc-tabs="eddsa-rdfc-2022 ecdsa-rdfc-2019">
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "https://university.example/Credential123",
"type": ["VerifiableCredential", "ExampleAlumniCredential"],
"issuer": "did:example:2g55q912ec3476eba2l9812ecbfe",
"validFrom": "2010-01-01T00:00:00Z",
"credentialSubject": {
"id": "https://www.example.org/persons/pat",
"name": "Pat",
"alumniOf": {
"id": "did:example:c276e12ec21ebfeb1f712ebc6f1",
"name": "Example University"
}
},
"credentialSchema": {
"id": "https://university.example/Credential123-schema-credential",
"type": "JsonSchemaCredential"
}
}
</pre>
<p>
When dereferenced, the URL `did:example:2g55q912ec3476eba2l9812ecbfe#ecdsa-public-key` should return an ECDSA public key in Multikey format, for example:
</p>
<pre class="example nohighlight" title="An ECDSA public key">
{
"@context": [
"https://www.w3.org/ns/did/v1",
"https://w3id.org/security/multikey/v1"
],
"id": "did:example:2g55q912ec3476eba2l9812ecbfe#ecdsa-public-key",
"type": "Multikey",
"controller": "did:example:2g55q912ec3476eba2l9812ecbfe",