-
Notifications
You must be signed in to change notification settings - Fork 19
/
Copy pathindex.html
3741 lines (3449 loc) · 159 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 Credential Data Integrity 1.0</title>
<meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
<!--
=== NOTA BENE ===
For the three scripts below, if your spec resides on dev.w3 you can check them
out in the same tree and use relative links so that they'll work offline,
-->
<script src='//www.w3.org/Tools/respec/respec-w3c' class='remove'></script>
<script class='remove' src="./common.js"></script>
<script class="remove"
src="https://cdn.jsdelivr.net/gh/digitalbazaar/[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: "PR",
// the specification's short name, as in http://www.w3.org/TR/short-name/
shortName: "vc-data-integrity",
// subtitle
subtitle: "Securing the Integrity of Verifiable Credential Data",
// if you wish the publication date to be other than today, set this
publishDate: "2025-3-20",
crEnd: "2025-01-19",
prEnd: "2025-4-17",
// if there is a previously published draft, uncomment this and set its YYYY-MM-DD date
// and its maturity status
// previousPublishDate: "1977-03-15",
// previousMaturity: "WD",
// if there a publicly available Editor's Draft, this is the link
edDraftURI: "https://w3c.github.io/vc-data-integrity/",
// if this is a LCWD, uncomment and set the end of its review period
implementationReportURI: "https://w3c.github.io/vc-data-integrity/implementations/",
// 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"],
// 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: "Ted Thibodeau Jr", url: "https://github.com/TallTed",
company: "OpenLink Software", companyURL: "https://www.openlinksw.com/",
w3cid: 42501
}, {
name: "Ivan Herman", url: "https://www.w3.org/People/Ivan/",
company: "W3C", companyURL: "https://www.w3.org",
w3cid: 7382, orcid: "0000-0003-0782-2704"
}, {
name: "Dave Longley", url: "https://digitalbazaar.com/",
company: "Digital Bazaar", companyURL: "http://digitalbazaar.com/",
w3cid: 48025
}, {
name: "Greg Bernstein", url: "https://www.grotto-networking.com/",
company: "Invited Expert", w3cid: 140479
}],
// authors, add as many as you like.
// This is optional, uncomment if you have authors as well as editors.
// only "name" is required. Same format as editors.
authors: [{
name: "Dave Longley", url: "https://digitalbazaar.com/",
company: "Digital Bazaar", companyURL: "http://digitalbazaar.com/",
w3cid: 48025
}, {
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"
}],
// extend the bibliography entries
//localBiblio: webpayments.localBiblio,
// 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-data-integrity",
// 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: 3,
/*preProcess: [ ],
alternateFormats: [ {uri: "diff-20111214.html", label: "diff to previous version"} ],
*/
localBiblio: {
"DI-EDDSA": {
title: "The Edwards Digital Signature Algorithm Cryptosuites v1.0",
href: "https://www.w3.org/TR/vc-di-eddsa/",
authors: ["David Longley", "Manu Sporny", "Dmitri Zagidulin"],
status: "WD",
publisher: "W3C Verifiable Credentials Working Group"
},
"DI-ECDSA": {
title: "The Elliptic Curve Digital Signature Algorithm Cryptosuites v1.0",
href: "https://www.w3.org/TR/vc-di-ecdsa/",
authors: ["David Longley", "Manu Sporny", "Marty Reed"],
status: "WD",
publisher: "W3C Verifiable Credentials Working Group"
},
"DI-BBSDSA": {
title: "The BBS Digital Signature Algorithm Cryptosuites v1.0",
href: "https://www.w3.org/TR/vc-di-bbs/",
authors: ["Tobias Looker", "Orie Steele"],
status: "WD",
publisher: "W3C Verifiable Credentials Working Group"
},
"JOSE-REGISTRIES": {
title: "The JSON Object Signing and Encryption (JOSE) Registries",
href: "https://www.iana.org/assignments/jose",
authors: ["The Internet Assigned Numbers Authority"],
status: "REC",
publisher: "The Internet Assigned Numbers Authority"
},
"SECURITY-VOCABULARY": {
title: "The Security Vocabulary",
href: "https://w3id.org/security",
authors: ["Ivan Herman", "Manu Sporny","David Longley"],
status: "ED",
publisher: "Verifiable Credentials Working Group"
},
"ZCAP": {
title: "Authorization Capabilities for Linked Data",
href: "https://w3c-ccg.github.io/zcap-spec/",
status: "CGDRAFT",
publisher: "Credentials Community Group"
},
"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"
},
"VC-EXTENSIONS": {
title: "Verifiable Credential Extensions",
href: "https://w3c.github.io/vc-extensions/",
authors: [
"Manu Sporny"
],
status: "ED",
publisher: "W3C Verifiable Credentials Working Group"
},
"DID-KEY": {
title: "The did:key Method",
href: "https://w3c-ccg.github.io/did-method-key/",
authors: [
"Manu Sporny",
"Dmitri Zagidulin",
"Dave Longley",
"Orie Steele"
],
status: "CG-DRAFT",
publisher: "W3C Credentials Community Group"
},
"SHA3": {
title: "SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions",
href: "https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf",
authors: [
"National Institute of Standards and Technology",
],
status: "National Standard",
publisher: "U.S. Department of Commerce"
},
"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"
}
},
postProcess: [
restrictRefs,
window.respecVc.createVcExamples
],
xref: ["INFRA", "MIMESNIFF", "VC-DATA-MODEL-2.0", "CID"],
otherLinks: [{
key: "Related Specifications",
data: [{
value: "The Verifiable Credentials Data Model v2.0",
href: "https://www.w3.org/TR/VC-DATA-MODEL-2.0/"
}, {
value: "The Edwards Digital Signature Algorithm Cryptosuites v1.0",
href: "https://www.w3.org/TR/vc-di-eddsa/"
}, {
value: "The Elliptic Curve Digital Signature Algorithm Cryptosuites v1.0",
href: "https://www.w3.org/TR/vc-di-ecdsa/"
}, {
value: "The BBS Digital Signature Algorithm Cryptosuites v1.0",
href: "https://www.w3.org/TR/vc-di-bbs/"
}]
}]
};
</script>
<style>
code {
color: rgb(199, 73, 0);
font-weight: bold;
}
pre {
overflow-x: auto;
white-space: pre-wrap;
}
pre .highlight {
font-weight: bold;
color: Green;
}
pre .subject {
font-weight: bold;
color: RoyalBlue;
}
pre .property {
font-weight: bold;
color: DarkGoldenrod;
}
pre .comment {
font-weight: bold;
color: SteelBlue;
-webkit-user-select: none;
-moz-user-select: none;
-ms-user-select: none;
user-select: none;
}
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, ".") ") "; }
table.simple {
border-collapse: collapse;
margin: 25px 0;
min-width: 400px;
border: 1px solid #dddddd;
}
table.simple thead tr {
background-color: #005a9c;
color: #ffffff;
text-align: left;
}
table.simple th,
table.simple td {
padding: 12px 15px;
vertical-align: top;
text-align: left;
}
table.simple tbody tr {
border-bottom: 1px solid #dddddd;
}
table.simple tbody tr:nth-of-type(even) {
background-color: #00000008;
}
table.simple tbody tr:last-of-type {
border-bottom: 2px solid #005a9c;
}
</style>
</head>
<body>
<section id='abstract'>
<p>
This specification describes mechanisms for ensuring the authenticity and
integrity of [=verifiable credentials=] and similar types of constrained digital
documents using cryptography, especially through the use of digital
signatures and related mathematical proofs.
</p>
</section>
<section id='sotd'>
<p>
The Working Group is actively seeking implementation feedback for this
specification. In order to exit the Candidate Recommendation phase, the
Working Group has set the requirement of at least two independent
implementations for each mandatory feature in the specification. For details
on the conformance testing process, see the test suites listed in the
<a href="https://w3c.github.io/vc-data-integrity/implementations/">
implementation report</a>.
</p>
</section>
<section class="informative">
<h2>Introduction</h2>
<p>
This specification describes mechanisms for ensuring the authenticity and
integrity of [=verifiable credentials=] and similar types of constrained digital
documents using cryptography, especially through the use of digital signatures
and related mathematical proofs. Cryptographic proofs enable functionality that
is useful to implementors of distributed systems. For example, proofs can be
used to:
</p>
<ul>
<li>
Make statements that can be shared without loss of trust, because their
authorship can be verified by a third party, for example as part of a
[=verifiable credential=] [[?VC-DATA-MODEL-2.0]], [=verifiable presentation=],
or social media post.
</li>
<li>
Authenticate as an entity identified by a particular identifier, for example, as
the subject identified by a Decentralized Identifier (DID) [[?DID]].
</li>
<li>
Delegate authorization for actions in a remote execution environment, via
mechanisms such as Authorization Capabilities [[ZCAP]].
</li>
<li>
Agree to contracts where the agreement can be verified by another party.
</li>
<li>
Additionally, many proofs that are based on cryptographic digital signatures
provide the benefit of integrity protection, making documents and data
tamper-evident.
</li>
</ul>
<section class="informative">
<h3>How it Works</h3>
<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="hiw-creation">
<img style="margin: auto; display: block; width: 100%;"
src="diagrams/hiw-creation.svg" alt="
Diagram showing the three steps involved in the creation of a cryptographic
proof. The diagram is laid out left to right with a blue box labeled 'Data'
on the far left. The blue box travels, left to right, through three subsequent
yellow arrows labeled 'Transform Data', 'Hash Data', and 'Generate Proof'. The
resulting blue box at the far right is labeled 'Data with Proof'.
">
<figcaption style="text-align: center;">
To create a cryptographic proof, data is transformed, hashed, and
cryptographically protected.
</figcaption>
</figure>
<p>
<dfn>Transformation</dfn> is a process described by a <dfn>transformation
algorithm</dfn> that takes input data and prepares it for the hashing process.
One example of a possible transformation is to take a record of people's names
that attended a meeting, sort the list alphabetically by the individual's family
name, and rewrite the names on a piece of paper, one per line, in sorted order.
Examples of transformations include
<a href="https://en.wikipedia.org/wiki/Canonicalization">canonicalization</a>
and
<a href="https://en.wikipedia.org/wiki/Binary-to-text_encoding">
binary-to-text</a> encoding.
</p>
<p>
<dfn>Hashing</dfn> is a process described by a <dfn>hashing algorithm</dfn> that
calculates an identifier for the transformed data using a
<a href="https://en.wikipedia.org/wiki/Cryptographic_hash_function">
cryptographic hash function</a>. This process is conceptually similar to how a
phone address book functions, where one takes a person's name (the input data)
and maps that name to that individual's phone number (the hash). Examples of
cryptographic hash functions include
<a href="https://en.wikipedia.org/wiki/Cryptographic_hash_function#SHA-3">
SHA-3</a> and
<a href="https://en.wikipedia.org/wiki/Cryptographic_hash_function#BLAKE3">
BLAKE-3</a>.
</p>
<p>
<dfn class="lint-ignore">Proof Generation</dfn> is a process described by a
<dfn>proof serialization algorithm</dfn> that calculates a value that protects the
integrity of the input data from modification or otherwise proves a certain
desired threshold of trust. This process is conceptually similar to the way a
wax seal can be used on an envelope containing a letter to establish trust in
the sender and show that the letter has not been tampered with in transit.
Examples of proof serialization functions include
<a href="https://en.wikipedia.org/wiki/Digital_signature">
digital signatures</a>,
<a href="https://en.wikipedia.org/wiki/Proof_of_stake">proofs of stake</a>, and
<a href="https://en.wikipedia.org/wiki/Proof_of_knowledge">
proofs of knowledge</a>, in general.
</p>
<p>
To verify a cryptographic proof, the following steps are performed:
1) Transformation, 2) Hashing, and 3) Proof Verification.
</p>
<figure id="hiw-verification">
<img style="margin: auto; display: block; width: 100%;"
src="diagrams/hiw-verification.svg" alt="
Diagram showing the three steps involved in the verification of a cryptographic
proof. The diagram is laid out left to right with a blue box labeled
'Data with Proof' on the far left. The blue box travels, left to right, through
three subsequent yellow arrows labeled 'Transform Data', 'Hash Data', and
'Verify Proof'. The resulting blue box at the far right is labeled 'Data with
Proof'.
">
<figcaption style="text-align: center;">
To verify a cryptographic proof, data is transformed, hashed, and
checked for correctness.
</figcaption>
</figure>
<p>
During verification, the [=transformation=] and [=hashing=] steps are
conceptually the same as described above.
</p>
<p>
<dfn class="lint-ignore">Proof Verification</dfn> is a process that is described
by a <dfn>proof verification algorithm</dfn> that applies a cryptographic proof
verification function to see if the input data can be trusted. Possible proof
verification functions include
<a href="https://en.wikipedia.org/wiki/Digital_signature">
digital signatures</a>,
<a href="https://en.wikipedia.org/wiki/Proof_of_stake">proofs of stake</a>, and
<a href="https://en.wikipedia.org/wiki/Proof_of_knowledge">
proofs of knowledge</a>, in general.
</p>
<p>
This specification details how cryptographic software architects and
implementers can package these processes together into things called
[=cryptographic suites=] and provide them to application developers for the
purposes of protecting the integrity of application data in transit and at rest.
</p>
</section>
<section class="informative">
<h3>Design Goals and Rationale</h3>
<p>
This specification optimizes for the following design goals:
</p>
<dl>
<dt>Simplicity</dt>
<dd>
The technology is designed to be easy to use for application developers,
without requiring significant training in cryptography. It optimizes for the
following priority of constituencies: application developers over cryptographic
suite implementers, over cryptographic suite designers, over cryptographic
algorithm specification authors. The solution focuses on sensible defaults to
prevent the selection of ineffective protection mechanisms. See section
[[[#protecting-application-developers]]] and
[[[#versioning-cryptography-suites]]] for further details.
</dd>
<dt>Composability</dt>
<dd>
A number of historical digital signature mechanisms have had monolithic
designs which limited use cases by combining data transformation, syntax,
digital signature, and serialization into a single specification. This
specification layers each component such that a broader range of use cases are
enabled, including generalized selective disclosure and serialization-agnostic
signatures. See section [[[#transformations]]], section [[[#data-opacity]]], and
[[[#versioning-cryptography-suites]]] for further rationale.
</dd>
<dt>Resilience</dt>
<dd>
Since digital proof mechanisms might be compromised without warning due to
technological advancements, it is important that [=cryptographic suites=]
provide multiple layers of protection and can be rapidly upgraded. This
specification provides for both algorithmic agility and cryptographic layering,
while still keeping the digital proof format easy for developers to understand
and use. See section [[[#agility-and-layering]]] to understand the particulars.
</dd>
<dt>Progressive Extensibility</dt>
<dd>
Creating and deploying new cryptographic protection mechanisms is designed to be
a deliberate, iterative, and careful process that acknowledges that extension
happens in phases from experimentation, to implementation, to standardization.
This specification strives to balance the need for an increase in the rate of
innovation in cryptography with the need for stable production-grade
cryptography suites. See section [[[#cryptographic-suites]]] for instructions on
establishing new types of cryptographic proofs.
</dd>
<dt>Serialization Flexibility</dt>
<dd>
Cryptographic proofs can be serialized in many different but equivalent ways and
have often been tightly bound to the original document syntax. This
specification enables one to create cryptographic proofs that are not
bound to the original document syntax, which enables more advanced use cases
such as being able to use a single digital signature across a variety of
serialization syntaxes such as JSON and CBOR without the need to regenerate the
cryptographic proof. See section [[[#transformations]]] for an explanation of
the benefits of such an approach.
</dd>
</dl>
<p class="note" title="Application of technology to broader use cases">
While this specification primarily focuses on [=verifiable credentials=], the
design of this technology is generalized, such that it can be used for other use
cases. In these instances, implementers are expected to perform their own due
diligence and expert review as to the applicability of the technology to their
use case.
</p>
</section>
<section id="conformance">
<p>
A <dfn>conforming secured document</dfn> is any [=byte sequence=] that can be
converted to a
<a data-cite="INFRA#parse-json-bytes-to-a-javascript-value">
JSON document</a> that follows the relevant normative requirements in
Sections [[[#proofs]]], [[[#proof-purposes]]], [[[#resource-integrity]]],
[[[#contexts-and-vocabularies]]], and [[[#dataintegrityproof]]].
</p>
<p>
A <dfn class="lint-ignore">conforming cryptographic suite specification</dfn> is
any specification that follows the relevant normative requirements in Section
[[[#cryptographic-suites]]].
</p>
<p>
A <dfn class="lint-ignore">conforming processor</dfn> is any algorithm realized
as software and/or hardware that generates and/or consumes a
[=conforming secured document=] according to the relevant normative statements
in Section [[[#algorithms]]]. Conforming processors MUST produce errors when
non-conforming documents are consumed.
</p>
</section>
<section>
<h3>Terminology</h3>
<p>
This section defines the terms used in this specification. A link to these terms
is included whenever they appear in this specification.
</p>
<dl class="termlist definitions" data-sort="ascending">
<dt><dfn class="export">data integrity proof</dfn></dt>
<dd>
A set of attributes that represent a digital proof and the parameters required
to verify it. A <strong>digital signature</strong> is a type of data integrity
proof.
</dd>
<dt><dfn>public key</dfn></dt>
<dd>
Cryptographic material that can be used to verify digital proofs created with a
corresponding [=secret key=].
</dd>
<dt><dfn>secret key</dfn></dt>
<dd>
Cryptographic material, sometimes referred to as a
<strong>private key</strong>, that is not to be shared with anyone, and is used
to generate digital proofs and/or digital signatures.
</dd>
<dt><dfn class="export">proof purpose</dfn></dt>
<dd>
The specific intent for the proof; the reason why an entity created it. The
protected declaration acts as a safeguard to prevent the proof from being
misused for a purpose other than the one it was intended for.
</dd>
<dt><dfn class="export" data-lt="cryptosuite">cryptographic suite</dfn></dt>
<dd>
A specification defining the usage of specific cryptographic primitives in
order to achieve a particular security goal. These documents are often used
to specify [=verification methods=], digital signature types,
their identifiers, and other related properties. See Section
[[[#cryptographic-suites]]] for further detail.
</dd>
<dt><dfn>controlled identifier document</dfn></dt>
<dd>
A document that contains public cryptographic material as defined in the
[[[CID]]] specification.
</dd>
<dt><dfn data-lt="verifier|verifiers|verifier's">verifier</dfn></dt>
<dd>
A role an entity performs by receiving data containing one or more
[=data integrity proofs=] and then determining whether or not the proof
is legitimate.
</dd>
<dt><dfn class="export">verification method</dfn></dt>
<dd>
<p>
A set of parameters that can be used together with a process to independently
verify a proof. For example, a cryptographic [=public key=] can be used as a
verification method with respect to a digital signature; in such usage, it
verifies that the signer possessed the associated cryptographic [=secret key=].
</p>
<p>
"Verification" and "proof" in this definition are intended to apply broadly. For
example, a cryptographic public key might be used during Diffie-Hellman key
exchange to negotiate a shared symmetric key for encryption. This guarantees the
integrity of the key agreement process. It is thus another type of verification
method, even though descriptions of the process might not use the words
"verification" or "proof."
</p>
</dd>
<dt><dfn class="export">verification relationship</dfn></dt>
<dd>
<p>
An expression of the relationship between the [=subject=] and a
[=verification method=]. An example of a verification relationship is
<a data-cite="CID#authentication">authentication</a>.
</p>
</dd>
</dl>
</section>
</section>
<section>
<h2>Data Model</h2>
<p>
This section specifies the data model that is used for expressing
[=data integrity proofs=] and the integrity of related resources.
</p>
<p>
All of the data model properties and types in this specification map to URLs.
The vocabulary where these URLs are defined is the [[[?SECURITY-VOCABULARY]]].
The explicit mechanism that is used to perform this mapping in a secured
document is the `@context` property.
</p>
<p>
The mapping mechanism is defined by [[[JSON-LD11]]]. To ensure a document can be
interoperably consumed without the use of a JSON-LD library, document authors
are advised to ensure that domain experts have 1) specified the expected order
for all values associated with a `@context` property, 2) published cryptographic
hashes for each `@context` file, and 3) deemed that the contents of each
`@context` file are appropriate for the intended use case.
</p>
<p>
When a document is processed by a processor that does not utilize JSON-LD
libraries, and there is a requirement to use the same semantics as those used in
a JSON-LD environment, implementers are advised to 1) enforce the expected order
and values in the `@context` property, and 2) ensure that each `@context` file
matches the known cryptographic hashes for each `@context` file.
</p>
<p>
Using static, versioned, `@context` files with published cryptographic hashes in
conjunction with JSON Schema is one acceptable approach to implementing the
mechanisms described above, which ensures proper term identification, typing,
and order, when a processor that does not utilize a JSON-LD library is used.
See the section on
<a data-cite="?VC-DATA-MODEL-2.0#type-specific-credential-processing">
Type-Specific Processing</a> in [[[?VC-DATA-MODEL-2.0]]] for more details.
</p>
<section>
<h3>Proofs</h3>
<p>
A [=data integrity proof=] provides information about the proof mechanism,
parameters required to verify that proof, and the proof value itself. All of
this information is provided using Linked Data vocabularies such as
[[[?SECURITY-VOCABULARY]]].
</p>
<p>
When expressing a [=data integrity proof=] on an object, a
<dfn class="lint-ignore">`proof`</dfn> property MUST be used. The `proof`
property within a [=verifiable credential=] is a [=named graph=]. If present,
its value MUST be either a single object, or an unordered set of objects,
expressed using the properties below:
</p>
<dl style="margin-left: 1em;">
<dt>id</dt>
<dd>
An optional identifier for the proof, which MUST be a URL [[URL]], such as
a UUID as a URN (`urn:uuid:6a1676b8-b51f-11ed-937b-d76685a20ff5`).
The usage of this property is further explained in Section [[[#proof-chains]]].
</dd>
<dt>type</dt>
<dd>
The specific type of proof MUST be specified as a [=string=] that maps to a URL
[[URL]]. Examples of proof types include `DataIntegrityProof` and
`Ed25519Signature2020`. Proof types determine what other fields are required to
secure and verify the proof.
</dd>
<dt><dfn class="lint-ignore">proofPurpose</dfn></dt>
<dd>
The reason the proof was created MUST be specified as a [=string=] that maps to a
URL [[URL]]. The proof purpose acts as a safeguard to prevent the proof from
being misused by being applied to a purpose other than the one that was
intended. For example, without this value the creator of a proof could be
tricked into using cryptographic material typically used to create a Verifiable
Credential (`assertionMethod`) during a login process (`authentication`) which
would then result in the creation of a [=verifiable credential=] they never meant to
create instead of the intended action, which was to merely log in to a website.
</dd>
<dt>verificationMethod</dt>
<dd>
A verification method is the means and information needed to verify the proof.
If included, the value MUST be a [=string=] that maps to a [[URL]]. Inclusion of
`verificationMethod` is OPTIONAL, but if it is not included, other properties
such as `cryptosuite` might provide a mechanism by which to obtain the information
necessary to verify the proof. Note that when `verificationMethod` is
expressed in a [=data integrity proof=], the value points to the actual location
of the data; that is, the `verificationMethod` references, via a URL, the
location of the [=public key=] that can be used to verify the proof. This
[=public key=] data is stored in a [=controlled identifier document=], which contains a
full description of the verification method.
</dd>
<dt>cryptosuite</dt>
<dd>
An identifier for the cryptographic suite that can be used to verify the proof. See
[[[#cryptographic-suites]]] for more information. If the proof `type` is
`DataIntegrityProof`, `cryptosuite` MUST be specified; otherwise, `cryptosuite`
MAY be specified. If specified, its value MUST be a string.
</dd>
<dt><dfn class="lint-ignore">created</dfn></dt>
<dd>
The date and time the proof was created is OPTIONAL and, if included, MUST be
specified as an [[XMLSCHEMA11-2]] `dateTimeStamp` string, either in Universal
Coordinated Time (UTC), denoted by a Z at the end of the value, or with a time
zone offset relative to UTC. A [=conforming processor=] MAY chose to consume
time values that were incorrectly serialized without an offset. Incorrectly
serialized time values without an offset are to be interpreted as UTC.
</dd>
<dt id="defn-proof-expires">expires</dt>
<dd>
The `expires` property is OPTIONAL and, if present, specifies when the proof
expires. If present, it MUST be an [[XMLSCHEMA11-2]] `dateTimeStamp` string,
either in Universal Coordinated Time (UTC), denoted by a Z at the end of the
value, or with a time zone offset relative to UTC. A [=conforming processor=]
MAY chose to consume time values that were incorrectly serialized without an
offset. Incorrectly serialized time values without an offset are to be
interpreted as UTC.
</dd>
<dt id="defn-domain">domain</dt>
<dd>
The `domain` property is OPTIONAL. It conveys one or more security domains in which the
proof is meant to be used. If specified, the associated value MUST be either a
string, or an unordered set of strings. A verifier SHOULD use the value to
ensure that the proof was intended to be used in the security domain in which
the verifier is operating. The specification of the `domain` parameter is useful
in challenge-response protocols where the verifier is operating from within a
security domain known to the creator of the proof. Example domain values
include: `domain.example` (DNS domain), `https://domain.example:8443`
(Web origin), `mycorp-intranet` (bespoke text string), and
`b31d37d4-dd59-47d3-9dd8-c973da43b63a` (UUID).
</dd>
<dt id="defn-challenge"><dfn>challenge</dfn></dt>
<dd>
A [=string=] value that SHOULD be included in a proof if a `domain` is specified.
The value is used once for a particular [=domain=] and window of time. This
value is used to mitigate replay attacks. Examples of a challenge value include:
`1235abcd6789`, `79d34551-ae81-44ae-823b-6dadbab9ebd4`, and `ruby`.
</dd>
<dt><dfn class="lint-ignore">proofValue</dfn></dt>
<dd>
A [=string=] value that expresses base-encoded binary data necessary to verify the
digital proof using the `verificationMethod` specified. The value MUST use a
header and encoding as described in Section
<a data-cite="CID#multibase-0">2.4 Multibase</a> of the
[[[CID]]] specification to express the binary data.
The contents of this value are determined by a specific cryptosuite and set
to the <em>proof value</em> generated by the <a href="#add-proof">Add Proof Algorithm</a>
for that cryptosuite. Alternative properties with different encodings specified by the
cryptosuite MAY be used, instead of this property, to encode the data necessary
to verify the digital proof.
</dd>
<dt><dfn class="lint-ignore">previousProof</dfn></dt>
<dd>
The `previousProof` property is OPTIONAL. If present, it MUST be a string
value or an unordered list of string values. Each value identifies another
[=data integrity proof=], all of which MUST also verify for the current
proof to be considered verified. This property is used in Section
[[[#proof-chains]]].
</dd>
<dt><dfn class="lint-ignore">nonce</dfn></dt>
<dd>
An OPTIONAL [=string=] value supplied by the proof creator. One use of this
field is to increase privacy by decreasing linkability that is the result
of deterministically generated signatures.
</dd>
</dl>
<p>
A proof can be added to a JSON document like the following:
</p>
<pre class="example nohighlight" title="A simple JSON data document">
{
"myWebsite": "https://hello.world.example/"
};
</pre>
<p>
The following proof secures the document above using the `eddsa-jcs-2022`
cryptography suite [[?DI-EDDSA]], which produces a verifiable digital proof by
transforming the input data using the JSON Canonicalization Scheme (JCS)
[[?RFC8785]] and then digitally signing it using an Edwards Digital Signature
Algorithm (EdDSA).
</p>
<pre class="example nohighlight"
title="A simple signed JSON data document">
{
"myWebsite": "https://hello.world.example/",
"proof": {
"type": "DataIntegrityProof",
"cryptosuite": "eddsa-jcs-2022",
"created": "2023-03-05T19:23:24Z",
"verificationMethod": "https://di.example/issuer#z6MkjLrk3gKS2nnkeWcm<wbr>cxiZPGskmesDpuwRBorgHxUXfxnG",
"proofPurpose": "assertionMethod",
"proofValue": "zQeVbY4oey5q2M3XKaxup3tmzN4DRFTLVqpLMweBrSxMY2xHX5XTYV<wbr>8nQApmEcqaqA3Q1gVHMrXFkXJeV6doDwLWx"
}
}
</pre>
<p>
Similarly, a proof can be added to a JSON-LD data document like the following:
</p>
<pre class="example nohighlight"
title="A simple JSON-LD data document">
{
"@context": {"myWebsite": "https://vocabulary.example/myWebsite"},
"myWebsite": "https://hello.world.example/"
};
</pre>
<p>
The following proof secures the document above by using the `ecdsa-rdfc-2019`
cryptography suite [[?DI-ECDSA]], which produces a verifiable digital proof by
transforming the input data using the RDF Dataset Canonicalization Scheme
[[?RDF-CANON]] and then digitally signing it using the Elliptic Curve Digital
Signature Algorithm (ECDSA).
</p>
<pre class="example nohighlight"
title="A simple signed JSON-LD data document">
{
"@context": [
{"myWebsite": "https://vocabulary.example/myWebsite"},
"https://w3id.org/security/data-integrity/v2"
],
"myWebsite": "https://hello.world.example/",
"proof": {
"type": "DataIntegrityProof",
"cryptosuite": "ecdsa-rdfc-2019",
"created": "2020-06-11T19:14:04Z",
"verificationMethod": "https://ldi.example/issuer#zDnaepBuvsQ8cpsWrVK<wbr>w8fbpGpvPeNSjVPTWoq6cRqaYzBKVP",
"proofPurpose": "assertionMethod",
"proofValue": "zXb23ZkdakfJNUhiTEdwyE598X7RLrkjnXEADLQZ7vZyUGXX8cyJZR<wbr>BkNw813SGsJHWrcpo4Y8hRJ7adYn35Eetq"
}
}
</pre>
<p class="note" title="Representing time values to individuals">
This specification enables the expression of dates and times, such as through
the `created` and `expires` properties. This information might be indirectly
exposed to an individual if a proof is processed and is detected to be outside
an allowable time range. When displaying date and time values related to the
validity of cryptographic proofs, implementers are advised to respect the
<a data-cite="LTLI#locale" href="https://www.w3.org/TR/ltli/#locale">locale</a>
and local calendar preferences of the individual [[?LTLI]]. Conversion of
timestamps to local time values are expected to consider the time zone
expectations of the individual. See
<a data-cite="?VC-DATA-MODEL-2.0#representing-time"></a> for more details about
representing time values to individuals.
</p>
<pre class="example nohighlight"
title="A data document with an attached proof that uses the 'expires' property">
{
"@context": [
{"myWebsite": "https://vocabulary.example/myWebsite"},
"https://w3id.org/security/data-integrity/v2"
],
"myWebsite": "https://hello.world.example/",
"proof": {
"type": "DataIntegrityProof",
"cryptosuite": "ecdsa-rdfc-2019",
"created": "2020-06-11T19:14:04Z",
<span class="comment">// the proof expires a month after it was created</span>
<span class="highlight">"expires": "2020-07-11T19:14:04Z"</span>,
"verificationMethod": "https://ldi.example/issuer#zDnaepBuvsQ8cpsWrVK<wbr>w8fbpGpvPeNSjVPTWoq6cRqaYzBKVP",
"proofPurpose": "assertionMethod",
"proofValue": "z98X7RLrkjnXEADJNUhiTEdwyE5GXX8cyJZRLQZ7vZyUXb23Zkdakf<wbr>RJ7adYY8hn35EetqBkNw813SGsJHWrcpo4"
}
}
</pre>
<p>
The Data Integrity specification supports the concept of multiple
proofs in a single document. There are two types of multi-proof
approaches that are identified: Proof Sets (un-ordered) and Proof Chains
(ordered).
</p>
<section>
<h3>Proof Sets</h3>
<p>
A <dfn>proof set</dfn> is useful when the same data needs to be secured by
multiple entities, but where the order of proofs does not matter, such as in the
case of a set of signatures on a contract. A proof set, which has no order, is
represented by associating a set of proofs with the `proof` key in a document.
</p>
<pre class="example nohighlight" title="A proof set in a data document">
{
"@context": [
{"myWebsite": "https://vocabulary.example/myWebsite"},
"https://w3id.org/security/data-integrity/v2"
],
"myWebsite": "https://hello.world.example/",
<span class="highlight">"proof": [{
<span class="comment">// This is one of the proofs in the set</span>
"type": "DataIntegrityProof",
"cryptosuite": "eddsa-rdfc-2022",
"created": "2020-11-05T19:23:24Z",
"verificationMethod": "https://ldi.example/issuer/1#z6MkjLrk3gKS2nnkeW<wbr>cmcxiZPGskmesDpuwRBorgHxUXfxnG",
"proofPurpose": "assertionMethod",
"proofValue": "z4oey5q2M3XKaxup3tmzN4DRFTLVqpLMweBrSxMY2xHX5XTYVQeVbY8<wbr>nQAVHMrXFkXJpmEcqdoDwLWxaqA3Q1geV6"
}, {
<span class="comment">// This is the other proof in the set</span>
"type": "DataIntegrityProof",
"cryptosuite": "eddsa-rdfc-2022",
"created": "2020-11-05T13:08:49Z",
"verificationMethod": "https://pfps.example/issuer/2#z6MkGskxnGjLrk3gK<wbr>S2mesDpuwRBokeWcmrgHxUXfnncxiZP",
"proofPurpose": "assertionMethod",
"proofValue": "z5QLBrp19KiWXerb8ByPnAZ9wujVFN8PDsxxXeMoyvDqhZ6Qnzr5CG9<wbr>876zNht8BpStWi8H2Mi7XCY3inbLrZrm95"
}]</span>
}
</pre>