-
Notifications
You must be signed in to change notification settings - Fork 2
/
index.html
1301 lines (1147 loc) · 66.5 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 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 documents, 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 proof cryptographically secures a Credential (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 status information, such as suspension or revocation of Verifiable Credentials, 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 Credentials (VCs) specification, 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 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. Boxes for securing mechanisms represent separate groups of boxes, with further grouping for embedded proofs and enveloping proofs. The group for embedded proofs includes a box labeled as Data Integrity, which depends on the VC Data Model and the Controller Document; and the ECDSA, EdDSA, and BBS Cryptosuites for different elliptic curves and signature schemes, which all depend on Data Integrity. The enveloped proofs section includes a single box labeled as JOSE and COSE using JWS, SD-JWT, or CBOR, and is also dependent on the VC Data Model and the Controller Document.">
<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 Credential, consisting of a series of statements related to the subject of a
Verifiable Credential.
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 Structure</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="Subject has a property which has a 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="A Verifiable Credential contains 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="A Verifiable Presentation contains 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="A Verifiable Presentation contains Presentation Metadata, Verifiable Credential(s), and Proof(s)">
<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 [[[VC-JOSE-COSE]]] for the usage of JWT.
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> and
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="di-integrity-structure">Generic Data Integrity Structure</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="di-integrity-structure-figure">
<img style="margin: auto; display: block; width: 90%;" src="diagrams/di_crypto_proof.svg" alt="TBD">
<figcaption style="text-align: center;">
Generic 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 like 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, yielding the signature of the data.
</li>
</ol>
<p>
<em>Verification</em> of a proof involves repeating the same steps on the verifier's side and, depending on the proof method, validating the newly calculated proof value with the one associated with the data.
In the case of a digital signature, this test usually means comparing the calculated signature value with the one which is embedded in the data.
</p>
</section>
<section id="s_di">
<!--MARK: VC DI -->
<h4>VC Data Integrity</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 Multibase [[MULTIBASE]] encoding of the keys, called <a data-cite="VC-DATA-INTEGRITY#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 possible purposes 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-ECDSA]]] [[VC-DI-ECDSA]], [[[VC-DI-EDDSA]]] [[VC-DI-EDDSA]], and [[[VC-DI-BBS]]] [[VC-DI-BBS]].
As their name suggests, the documents rely on existing cryptographic signature schemes: the Elliptic Curve Digital Signature Algorithm (ECDSA) specification [[FIPS-186-5]], the Edwards-Curve Digital Signature Algorithm (EdDSA) specification [[RFC8032]], 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 structure of proofs as described in <a href="#di-integrity-structure"></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 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).">
<figcaption style="text-align: center;">
Generic view of the proof generation steps.
</figcaption>
</figure>
<p class="note">
A common characteristics of all these cryptosuites is that keys must always be encoded using the <a data-cite="VC-DATA-INTEGRITY#multikey">Multikey</a> encoding.
The keys, whose exact formats are defined in the respective signature scheme specifications, also carry the choice of the hash functions to be used by the proof generation algorithm.
This provides yet another differentiation axis among cryptosuites although, in practice, SHA-256 [[RFC6234]] is usually used.
</p>
<section>
<h5>Full Disclosure Schemes</h5>
<p>
The two EdDSA cryptosuites, as well as `ecdsa-rdfc-2019` and `ecdsa-jcs-2019`, follow the proof generation pipeline as described in <a href="#di-integrity-structure"></a>: the Credential is canonicalized (using either JCS or RDFC-1.0), the result is hashed (using the hash functions as defined by the signature key), and the proof is generated using that hash value.
There is, however, an extra twist: the same pipeline is also used on a set of claims called "proof options", 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, yielding a second hash value.
<em>It is the concatenation of these two values</em> that is signed by EdDSA or ECDSA, respectively, producing a value for the `proofValue` property.
</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 "Base Proof" (calculated by the issuer), and the "Derived Proof" (which is typically calculated by the holder when selectively presenting the credential claims to the verifier).
The challenge is that the verifier should check that the holder can be trusted when verifying a partial value, without having access to the full original data.
</p>
<p>
To calculate the Base Proof, the Credential is supplemented with extra information that separates the "mandatory" and "non-mandatory" claims.
Using that extra information, the transformation step described in <a href="#di-integrity-structure"></a> does not only canonicalize the Credential, but also transforms it by explicitly separating these two types of claims into their own sets.
Furthermore, each non-mandatory claim must be signed individually, yielding a series of signatures.
The final Base Proof is, conceptually, the concatenation of all these signatures and related informations like the separation of mandatory and non-mandatory claims.
</p>
<p>
The Derived Proof is generated by the holder, when presenting the (derived) Credential.
These data are combined with the kind of selective disclosure requests the holder is prepared to honor; it is the combination of all these data that are used for the creation of a Derived Proof that is forwarded to the verifier.
</p>
</section>
</section>
<section>
<!--MARK: Core example with ECDSA -->
<h4>Example: the Core Example Secured with ECDSA and EdDSA</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="ECDSA and EdDSA proofs added to a Credential"
data-vc-vm="https://university.example/issuers/565049#key-1"
data-vc-tabs="ecdsa-rdfc-2019 eddsa-rdfc-2022">
{
"@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",
"publicKeyMultibase": "z42twTcNeSYcnqg1FLuSFs2bsGH3ZqbRHFmvS9XMsYhjxvHN"
}
</pre>
<p>
Note that the value of the `verificationMethod` property may have been the public key itself, instead of a reference to a separate resource containing the key.
</p>
</section>
</section>
</section>
<section id="s_bsl">
<!--MARK: Bitstrings -->
<h2>Bitstring Status List</h2>
<p>
It is often useful for an issuer of Verifiable Credentials to link to a location where a verifier can check to see if a credential has been suspended or revoked.
This additional resource is referred to as a "status list".
</p>
<p>
The simplest approach for a status list, where there is a one-to-one mapping between a Verifiable Credential and a URL where the status is published, raises privacy as well as performance issues.