-
Notifications
You must be signed in to change notification settings - Fork 3
/
Copy pathindex.html
678 lines (604 loc) · 24.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
<!DOCTYPE html>
<html>
<head>
<title>Revocation List 2020</title>
<meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
<!--
=== NOTA BENE ===
For the three scripts below, if your spec resides on dev.w3 you can check them
out in the same tree and use relative links so that they'll work offline,
-->
<script src='https://www.w3.org/Tools/respec/respec-w3c-common' class='remove'></script>
<script src="./common.js" class="remove"></script>
<script type="text/javascript" class="remove">
var respecConfig = {
// specification status (e.g., WD, LCWD, NOTE, etc.). If in doubt use ED.
specStatus: "CG-DRAFT",
// the specification's short name, as in http://www.w3.org/TR/short-name/
shortName: "vc-status-rl-2020",
// subtitle for the spec
subtitle: "A privacy-preserving mechanism for revoking Verifiable Credentials",
// if you wish the publication date to be other than today, set this
//publishDate: "2019-03-26",
//crEnd: "2019-04-23",
//implementationReportURI: "https://w3c.github.io/sdh-test-suite",
previousMaturity: "UNOFFICIAL",
previousPublishDate: "2020-03-18",
// if there is a previously published draft, uncomment this and set its YYYY-MM-DD date
// and its maturity status
// previousPublishDate: "1977-03-15",
// previousMaturity: "WD",
// extend the bibliography entries
localBiblio: ccg.localBiblio,
doJsonLd: true,
github: "https://github.com/digitalbazaar/vc-status-rl-2020/",
includePermalinks: false,
// if there a publicly available Editor's Draft, this is the link
edDraftURI: "https://digitalbazaar.github.io/vc-status-rl-2020/",
// if this is a LCWD, uncomment and set the end of its review period
// lcEnd: "2009-08-05",
// editors, add as many as you like
// only "name" is required
editors: [
{ name: "Manu Sporny", url: "http://manu.sporny.org/",
company: "Digital Bazaar", companyURL: "http://digitalbazaar.com/"},
{ name: "Dave Longley", url: "https://github.com/dlongley",
company: "Digital Bazaar", companyURL: "https://digitalbazaar.com/"}
],
// 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://github.com/dlongley",
company: "Digital Bazaar", companyURL: "http://digitalbazaar.com/"},
{ name: "Manu Sporny", url: "http://manu.sporny.org/",
company: "Digital Bazaar", companyURL: "http://digitalbazaar.com/" }
],
// name of the WG
wg: "Credentials Community Group",
// URI of the public WG page
wgURI: "https://www.w3.org/community/credentials/",
// name (with the @w3c.org) of the public mailing to which comments are due
wgPublicList: "public-credentials",
// URI of the patent status for this WG, for Rec-track documents
// !!!! IMPORTANT !!!!
// This is important for Rec-track documents, do not copy a patent URI from a random
// document unless you know what you're doing. If in doubt ask your friendly neighborhood
// Team Contact.
//wgPatentURI: "https://www.w3.org/2004/01/pp-impl/98922/status",
maxTocLevel: 2,
inlineCSS: true
};
</script>
<style>
pre .highlight {
font-weight: bold;
color: green;
}
pre .comment {
font-weight: bold;
color: Gray;
}
.color-text {
font-weight: bold;
text-shadow: -1px 0 black, 0 1px black, 1px 0 black, 0 -1px black;
}
ol.algorithm {
counter-reset: numsection;
list-style-type: none;
}
ol.algorithm li {
margin: 0.5em 0;
}
ol.algorithm li:before {
font-weight: bold;
counter-increment: numsection;
content: counters(numsection, ".") ") ";
}
</style>
</head>
<body>
<section id='abstract'>
<p>
This specification describes a privacy-preserving, space-efficient, and
high-performance mechanism for publishing the revocation status of
Verifiable Credentials.
</p>
</section>
<section id='sotd'>
<p>
This document is experimental and is undergoing heavy development.
It is inadvisable to implement the specification in its current form.
An
<a href="https://github.com/digitalbazaar/vc-revocation-list-2020">experimental
implementation</a> is available.
</p>
<!--p>
Comments regarding all aspects of this document are welcome.
Please file issues
directly on <a href="https://github.com/digitalbazaar/vc-status-rl-2020/issues/">GitHub</a>,
or send them to
<a href="mailto:public-credentials@w3.org">public-credentials@w3.org</a>
(<a href="mailto:public-credentials-request@w3.org?subject=subscribe">subscribe</a>,
<a href="https://lists.w3.org/Archives/Public/public-credentials/">archives</a>).
</p-->
</section>
<section class="informative">
<h2>Introduction</h2>
<p>
It is often useful for an <a>issuer</a> of <a>verifiable credentials</a>
[[VC-DATA-MODEL]] to link to a location where a <a>verifier</a> can check to see
if a credential has been revoked. There are a variety of privacy and performance
considerations that are made when designing, publishing, and processing
revocation lists.
</p>
<p>
One such privacy consideration happens when there is a one-to-one mapping
between a <a>verifiable credential</a> and a URL where the revocation status is
published. This type of mapping enables the website that publishes the URL to
correlate the <a>holder</a>, time, and <a>verifier</a> when the status is
checked. This could enable the <a>issuer</a> to discover the type of interaction
the <a>holder</a> is having with the <a>verifier</a>, such as providing an age
verification credential when entering a bar. Being tracked by the <a>issuer</a>
of a driver's license when entering an establishment violates a privacy
expectation that many people have today.
</p>
<p>
Similarly, there are performance considerations that are explored when designing
revocation lists. One such consideration is where the list is published and the
burden it places from a bandwidth and processing perspective, both on the server
and the client fetching the information. In order to meet privacy expectations,
it is useful to bundle the status of large sets of credentials into a single
list to help with herd privacy. However, doing so can place an impossible
burden on both the server and client if the status information is as much as a
few hundred bytes in size per credential across a population of
hundreds of millions of <a>holders</a>.
</p>
<p>
The rest of this document proposes a highly compressible, bitstring-based
revocation list mechanism with strong privacy-preserving characteristics,
that is compatible with the architecture of the Web, is highly space-efficient,
and lends itself well to content distribution networks. As an example of
using this specification to achieve a number of beneficial privacy and
performance goals, it is possible to create a revocation list that can be
constructed for 100,000 <a>verifiable credentials</a> that is roughly
12,500 bytes in size in the worst case. In a case where a few hundred
credentials have been revoked, the size of the list is less than a
few hundred bytes while providing privacy in a herd of 100,000 individuals.
</p>
</section>
<section id="conformance" class="normative">
</section>
<section class="informative">
<h2>Terminology</h2>
<div
data-include="./terms.html" data-oninclude="restrictReferences"></div>
</section>
<section class="informative">
<h2>Core Concept</h2>
<p>
This section outlines the core concept utilized by the revocation list
mechanism described in this document. At the most basic level, revocation
information for all <a>verifiable credentials</a> issued by an <a>issuer</a>
are expressed as simple binary values. The <a>issuer</a> keeps a bitstring
list of all <a>verifiable credentials</a> it has issued. Each
<a>verifiable credential</a> is associated with a position in the list. If
the binary value of the position in the list is 1 (one), the
<a>verifiable credential</a> is revoked, if it is 0 (zero) it is not revoked.
</p>
<p>
One of the benefits of using a bitstring is that it is a highly compressible
data format since, in the average case, large numbers of credentials will
remain unrevoked. This will ensure long sections of bits that are the same
value and thus highly compressible using run-length compression techniques
such as ZLIB [[RFC1950]]. The default bitstring size is 16KB (131,072 entries),
and when only a handful of <a>verifiable credentials</a> are revoked, the
compressed bitstring size is reduced down to a few hundred bytes.
</p>
<p>
Another benefit of using a bitstring is that it enables large numbers of
<a>verifiable credential</a> revocation statuses to be placed in the same list.
This specification utilizes a minimum bitstring length of 131,072 (16KB). This
population size ensures an adequate amount of herd privacy in the average case.
If better herd privacy is required, the bitstring can be made to be larger.
</p>
<figure id="bitstring">
<img style="margin: auto; display: block; width: 75%;"
src="diagrams/RevocationList2020.svg" alt="diagram showing a
list of boxes at the top of the image with two of them in
red depicting revoked credentials. Text beside the boxes to the
right reads 16 kilobytes. An depiction of the boxes being
ZLIB compressed into a cylinder on the bottom of the page shows
that compression has resulted in a final size of 135 bytes.">
<figcaption style="text-align: center;">
A visual depiction of the concepts outlined in this section.
</figcaption>
</figure>
</section>
<section class="normative">
<h2>Data Model</h2>
<p>
The following sections outlines the data model for this document.
</p>
<section>
<h3>RevocationList2020Status</h3>
<p>
When an <a>issuer</a> desires to enable revocation for a
<a>verifiable credential</a>, they MAY add a <code>status</code> property
that uses the data model described in this specification.
</p>
<table class="simple">
<thead>
<tr>
<th style="white-space: nowrap">Property</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>id</td>
<td>
The constraints on the <code>id</code> property are listed in the
Verifiable Credentials Data Model specification [[VC-DATA-MODEL]]. The
value is expected to be a URL that identifies the status information associated
with the <a>verifiable credential</a>. It MUST NOT be the URL for the
revocation list.
</td>
</tr>
<tr>
<td>type</td>
<td>
The <code>type</code> property MUST be <code>RevocationList2020Status</code>.
</td>
</tr>
<tr>
<td>revocationListIndex</td>
<td>
The <code>revocationListIndex</code> property MUST be an arbitrary size integer
greater than or equal to 0, expressed as a string. The value identifies the bit
position of the revocation status of the <a>verifiable credential</a>.
</td>
</tr>
<tr>
<td>revocationListCredential</td>
<td>
The <code>revocationListCredential</code> property MUST be a URL to a
<a>verifiable credential</a>. When the URL is dereferenced, the resulting
<a>verifiable credential</a> MUST have <code>type</code> property that
includes the <code>RevocationList2020Credential</code> value.
</td>
</tr>
</tbody>
</table>
<pre class="example nohighlight" title="Example RevocationList2020Status">
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://w3id.org/vc-revocation-list-2020/v1"
],
"id": "https://example.com/credentials/23894672394",
"type": ["VerifiableCredential"],
"issuer": "did:example:12345",
"issued": "2020-04-05T14:27:42Z",
<span class="highlight">"credentialStatus": {
"id": "https://dmv.example.gov/credentials/status/3#94567",
"type": "RevocationList2020Status",
"revocationListIndex": "94567",
"revocationListCredential": "https://example.com/credentials/status/3"
}</span>,
"credentialSubject": {
"id": "did:example:6789",
"type": "Person"
},
"proof": { <span class="comment">...</span> }
}
</pre>
</section>
<section>
<h3>RevocationList2020Credential</h3>
<p>
When a revocation list is published, the result is a <a>verifiable
credential</a> that encapsulates the revocation list. The following section
describes the format of the <a>verifiable credential</a> that encapsulates the
revocation list:
</p>
<table class="simple">
<thead>
<tr>
<th style="white-space: nowrap">Property</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>id</td>
<td>
The <a>verifiable credential</a> that contains the revocation list MUST
express an <code>id</code> property that matches the value specified in
<code>revocationListCredential</code> for the corresponding
<code>RevocationList2020Status</code>
(see <a href="#revocationlist2020status"></a>).
</td>
</tr>
<tr>
<td>type</td>
<td>
The <a>verifiable credential</a> that contains the revocation list MUST
express a <code>type</code> property that includes the
<code>RevocationList2020Credential</code> value.
</td>
</tr>
<tr>
<td>credentialSubject.type</td>
<td>
The <code>type</code> of the credential <a>subject</a>, which is the
revocation list, MUST be <code>RevocationList2020</code>.
</td>
</tr>
<tr>
<td>credentialSubject.encodedList</td>
<td>
The <code>encodedList</code> property of the credential <a>subject</a> MUST be
the ZLIB-compressed [[RFC1950]], base-64 encoded [[RFC4648]] bitstring values
for the associated range of <a>verifiable credential</a> status values. The
uncompressed bitstring MUST be at least 16KB in size.
</td>
</tr>
</tbody>
</table>
<pre class="example nohighlight" title="Example RevocationList2020 Credential">
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://w3id.org/vc-revocation-list-2020/v1"
],
"id": "<span class="highlight">https://example.com/credentials/status/3</span>",
"type": ["VerifiableCredential", "<span class="highlight">RevocationList2020Credential</span>"],
"issuer": "did:example:12345",
"issued": "2020-04-05T14:27:40Z",
"credentialSubject": {
"id": "https://example.com/status/3#list",
"type": "<span class="highlight">RevocationList2020</span>",
<span class="highlight">"encodedList": "H4sIAAAAAAAAA-3BMQEAAADCoPVPbQsvoAAAAAAAAAAAAAAAAP4GcwM92tQwAAA"</span>
},
"proof": { ... }
}
</pre>
</section>
</section>
<section class="normative">
<h2>Algorithms</h2>
<p>
The following section outlines the algorithms that are used to generate
and validate revocation lists as described by this document.
</p>
<section class="normative">
<h3>Generate Algorithm</h3>
<p>
The following process, or one generating the exact output, MUST be followed
when producing a
<a href="#revocationlist2020credential">RevocationList2020Credential</a>:
</p>
<ol class="algorithm">
<li>
Let <strong>issued credentials</strong> be a list of all issued
<a>verifiable credentials</a>.
</li>
<li>
Let <strong>RLC</strong> be an unsigned
<a href="#revocationlist2020credential">RevocationList2020Credential</a>
without the <code>encodedList</code> property set.
</li>
<li>
Generate a <strong>compressed bitstring</strong> by passing
<strong>issued credentials</strong> to the
<strong>Bitstring Generation Algorithm</strong>.
</li>
<li>
Set the <code>encodedList</code> to <strong>compressed bitstring</strong>.
</li>
<li>
Generate a proof for the <strong>RLC</strong> and publish it to the
endpoint listed in the <a>verifiable credential</a>.
</li>
</ol>
</section>
<section class="normative">
<h3>Validate Algorithm</h3>
<p>
The following process, or one generating the exact output, MUST be followed
when validating a <a>verifiable credential</a> that is contained in a
<a href="#revocationlist2020credential">RevocationList2020Credential</a>:
</p>
<ol class="algorithm">
<li>
Let <strong>credentialToValidate</strong> be a <a>verifiable credentials</a>
containing a <code>status</code> entry that is a
<a href="#revocationlist2020status">RevocationList2020Status</a>.
</li>
<li>
Verify all proofs associated with the <strong>credentialToValidate</strong>.
If a proof fails, return a validation error.
</li>
<li>
Let <strong>revocationListCredential</strong> be set to the value of the
<a href="#revocationlist2020credential">RevocationList2020Credential</a>.
</li>
<li>
Let <strong>compressed bitstring</strong> be the value of the
<code>encodedList</code> property of the
<a href="#revocationlist2020credential">RevocationList2020Credential</a>.
</li>
<li>
Let <strong>credentialIndex</strong> be the value of the
<code>revocationListIndex</code> property of the
<a href="#revocationlist2020credential">RevocationList2020Status</a>.
</li>
<li>
Generate a <strong>revocation bitstring</strong> by passing
<strong>compressed bitstring</strong> to the
<a href="#bitstring-expansion-algorithm">Bitstring Expansion Algorithm</a>.
</li>
<li>
Let <strong>revoked</strong> be the value of the bit at position
<strong>credentialIndex</strong> in the <strong>revocation bitstring</strong>.
</li>
<li>
Return <code>true</code> if revoked is 1, false otherwise.
</li>
</ol>
</section>
<section class="normative">
<h3>Bitstring Generation Algorithm</h3>
<p>
The following process, or one generating the exact output, MUST be followed
when generating a revocation list bitstring. The algorithm takes a
<strong>issuedCredentials</strong> list as input and returns a
<strong>compressed bitstring</strong> as output.
</p>
<ol class="algorithm">
<li>
Let <strong>bitstring</strong> be a list of bits with a minimum size of 16KB,
where each bit is initialized to 0 (zero).
</li>
<li>
For each bit in <strong>bitstring</strong>, if there is a
corresponding <code>revocationListIndex</code> value in
a revoked credential in <strong>issuedCredentials</strong>, set the bit to
1 (one), otherwise set the bit to 0 (zero).
</li>
<li>
Generate a <strong>compressed bitstring</strong> by using the ZLIB
compression algorithm [[RFC1950]] on the <strong>bitstring</strong>
and then base64-encoding [[RFC4648]] the result.
</li>
<li>
Return the <strong>compressed bitstring</strong>.
</li>
</ol>
</section>
<section class="normative">
<h3>Bitstring Expansion Algorithm</h3>
<p>
The following process, or one generating the exact output, MUST be followed
when expanding a compressed revocation list bitstring. The algorithm takes a
<strong>compressed bitstring</strong> as input and returns a
<strong>uncompressed bitstring</strong> as output.
</p>
<ol class="algorithm">
<li>
Let <strong>compressed bitstring</strong> be a compressed revocation list
bitstring.
</li>
<li>
Generate an <strong>uncompressed bitstring</strong> by using the
base64-decoding [[RFC4648]] algorithm on the
<strong>compressed bitstring</strong> and then expanding the output using
the ZLIB decompression algorithm [[RFC1950]].
</li>
<li>
Return the <strong>uncompressed bitstring</strong>.
</li>
</ol>
</section>
</section>
<section class="informative">
<h2>Privacy Considerations</h2>
<p>
This section details the general privacy considerations and specific privacy
implications of deploying this specification into production environments.
</p>
<section class="informative">
<h3>Revocation Bitstring Length</h3>
<p>
This document specifies a minimum revocation bitstring length of 131,072, or
16KB uncompressed. This is enough to give <a>holders</a> an adequate amount of
herd privacy if the number of verifiable credentials issued is large enough.
However, if the number of issued verifiable credentials is a small population,
the ability to correlate an individual increases because the number of allocated
slots in the bitstring is small. Correlating this information with, for example,
where the geographic request came from can also help to correlate individuals
that have received a credential from the same geographic region.
</p>
</section>
<section class="informative">
<h3>Verifier Caching</h3>
<p>
It is possible for <a>verifiers</a> to increase the privacy of the
<a>holder</a> whose <a>verifiable credential</a> is being checked by caching
revocation lists that have been fetched from remote servers. By caching the
content locally, less correlatable information can be inferred from
<a>verifier</a>-based access patterns on the revocation list.
</p>
</section>
<section class="informative">
<h3>Content Distribution Networks</h3>
<p>
The use of content distribution networks by <a>issuers</a> can increase the
privacy of <a>holders</a> by reducing or eliminating requests for the
revocation lists from the <a>issuer</a>. Often, a request for a revocation
list will be served by an edge device and thus be faster and reduce the load
on the server as well as cloaking <a>verifiers</a> and <a>holders</a>
from <a>issuers</a>.
</p>
</section>
</section>
<section class="informative">
<h2>Security Considerations</h2>
<p>
There are a number of security considerations that implementers should be
aware of when processing data described by this specification. Ignoring or
not understanding the implications of this section can result in
security vulnerabilities.
</p>
<p>
While this section attempts to highlight a broad set of security
considerations, it is not a complete list. Implementers are urged to seek the
advice of security and cryptography professionals when implementing mission
critical systems using the technology outlined in this specification.
</p>
<p class="issue">
Write security considerations.
</p>
</section>
<section class="informative">
<h2>Accessibility Considerations</h2>
<p>
There are a number of accessibility considerations implementers should be
aware of when processing data described in this specification. As with any web
standards or protocols implementation, ignoring accessibility issues makes
this information unusable to a large subset of the population. It is important
to follow accessibility guidelines and standards, such as [[WCAG21]], to ensure
all people, regardless of ability, can make use of this data. This is
especially important when establishing systems utilizing cryptography, which
have historically created problems for assistive technologies.
</p>
<p>
This section details the general accessibility considerations to take into
account when utilizing this data model.
</p>
<p class="issue">
Write accessibility considerations.
</p>
</section>
<section class="informative">
<h2>Internationalization Considerations</h2>
<p>
There are a number of internationalization considerations implementers should be
aware of when publishing data described in this specification. As with any web
standards or protocols implementation, ignoring internationalization makes it
difficult for data to be produced and consumed across a disparate set of
languages and societies, which would limit the applicability of the
specification and significantly diminish its value as a standard.
</p>
<p>
This section outlines general internationalization considerations to take into
account when utilizing this data model.
</p>
<p class="issue">
Write i18n considerations.
</p>
</section>
</body>
</html>