forked from spherity/vc-status-2021-ldap
-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.html
610 lines (546 loc) · 21.8 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
<!DOCTYPE html>
<html>
<head>
<title>Revocation Status 2021 LDAP</title>
<meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
<script src='https://www.w3.org/Tools/respec/respec-w3c-common' class='remove' defer></script>
<script type="text/javascript" class="remove">
var respecConfig = {
shortName: "vc-status-2021-ldap",
specStatus: 'unofficial',
additionalCopyrightHolders: '<a href="https://spherity.com/">Spherity</a>',
publishISODate: "2016-08-18T00:00:00.000Z",
license: 'none',
logos: [
{
src: "logo.png",
url: "https://spherity.com/",
width: 100,
alt: 'Spherity logo'
},
],
edDraftURI: "https://spherity.github.io/vc-status-2021-ldap",
subtitle: "Directory service (LDAP) based mechanism for revoking Verifiable Credentials",
doJsonLd: true,
github: "https://github.com/spherity/vc-status-2021-ldap/",
includePermalinks: false,
editors: [
{
name: "Alexander Yenkalov",
url: "https://github.com/AlexYenkalov",
company: "Spherity",
companyURL: "https://www.spherity.com/",
},
{
name: "Juan Caballero",
url: "https://github.com/bumblefudge",
company: "Spherity",
companyURL: "https://www.spherity.com/",
},
{ name: "Andrey Orlov", url: "https://github.com/aaorlov",
company: "Spherity", companyURL: "https://spherity.com/"},
],
authors:
[
{ name: "Alexander Yenkalov", url: "https://github.com/AlexYenkalov",
company: "Spherity", companyURL: "http://spherity.com/"},
{ name: "Andrey Orlov", url: "https://github.com/aaorlov",
company: "Spherity", companyURL: "https://spherity.com/"}
],
maxTocLevel: 2,
inlineCSS: true
};
</script>
<style>
body {
background: white!important;
}
table {
width: 100%;
}
</style>
</head>
<body>
<section id='abstract'>
<p>
This specification describes a mechanism for publishing the revocation
status of Verifiable Credentials that leverages directory service
(e.g. Active Directory), where respective records are publicly
accessible via LDAP.
</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/spherity/vc-status-2021-ldap">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/spherity/vc-status-2021-ldap/issues/">GitHub</a>
</p>
</section>
<section class="informative">
<h2>Introduction</h2>
<p>
In the majority of cases, businesses already implement some known revocation
approaches.
<br>
<br>
One of these "known" options is the usage of directory services such
as Active Directory that provides the access to records via
<a href='https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol'>Lightweight Directory Access Protocol (LDAP)</a>.
<br>
<br>
An issuer of verifiable credentials in such a system
[[VC-DATA-MODEL]] can use a pointer to a particular location at
directory service inside of verifiable credential, that
a verifier can check to see if a credential has been revoked.
</p>
<p>
The <a href="#data-model">Data Model</a> section covers each vocabulary
item, its properties, other attributes for each item.
</p>
</section>
<section id="conformance"></section>
<section class="informative">
<h2>Terminology</h2>
<p>
The following terms are used to describe concepts in this specification.
</p>
<div data-include="./terms.html" data-oninclude="restrictReferences"></div>
</section>
<section class="informative">
<h2>Process Flow</h2>
Here we describe the assumptions in this usage of an underlying directory
service, which leverages LDAP to obtain records of revocation
status for a given verifiable credential.
<br>
<br>
First of all, entire verifiable credentials issued by an issuer
are not assumed to be recorded in directory service by default.
Some subset of information, however, need to be retained for revocation to be
executed later, i.e. the pointer to where a revocation record will be posted
if that credential is revoked later. This record can contain more or less
information, but it is assumed this record at least exist to claim credential
status as revoked.
<br>
<br>
In the case of a given credential's revocation, a respective record becomes
publicly accessible and a data of this record can be returned via an LDAP URL that
can be be securely and deterministically constructed via the following list of
properties of a verifiable credential:
<ul>
<li>credentialStatus.ssl</li>
<li>credentialStatus.host</li>
<li>credentialStatus.query</li>
<li>credentialStatus.params</li>
</ul>
If a record is returned by the query assembled from these variables, thereafter,
this verifiable credential should be considered as revoked and any additional
information will be included in the returned message.
</section>
<section class="normative" id="data-model">
<h2>Data Model</h2>
<p>
The following sections outlines the data model for this document.
</p>
<p>
You may view the latest json-ld vocabulary at: <br />
<a href="https://spherity.github.io/vc-status-2021-ldap/contexts/vc-status-2021-ldap/v1.jsonld">
https://spherity.github.io/vc-status-2021-ldap/contexts/vc-status-2021-ldap/v1.jsonld
</a>
</p>
<section id="RevocationStatus2021LDAP">
<h2>RevocationStatus2021LDAP</h2>
<p>
When an issuer desires to enable revocation for a
verifiable credential, they MAY add a <code>status</code>
property that uses the data model described in this specification.
</p>
<table class="simple">
<tbody>
<tr>
<td>
<a href="https://json-ld.org/spec/latest/json-ld/#dfn-terms">Term</a>
</td>
<td>
<a href="https://spherity.github.io/vc-status-2021-ldap#RevocationStatus2021LDAP">RevocationStatus2021LDAP</a>
</td>
</tr>
<tr>
<td>
<a href="https://json-ld.org/spec/latest/json-ld/#dfn-iris">Full IRI</a>
</td>
<td>
<a href="https://spherity.github.io/vc-status-2021-ldap#RevocationStatus2021LDAP">https://spherity.github.io/vc-status-2021-ldap#RevocationStatus2021LDAP</a>
</td>
</tr>
</tbody>
</table>
<pre class="example nohighlight" title="Example RevocationStatus2021LDAP">
{
"@context": [
"https://www.w3.org/2018/credentials/v1"
],
"id": "https://example.com/credentials/23894672367",
"type": ["VerifiableCredential"],
"issuer": "did:example:12345",
"issued": "2021-01-11T00:35:00Z",
<span class="highlight">"credentialStatus": {
"id": "ldaps://62.242.203.212:636/o=dolor,cn=ipsum,ou=lorem,dc=example,dc=com",
"type": "RevocationStatus2021LDAP",
"ssl": true,
"host": "62.242.203.212:636",
"query": "o={{0}},cn={{1}},ou={{2}},dc={{3}},dc={{4}}",
"params": [
"dolor",
"ipsum",
"lorem",
"example",
"com"
]
}</span>,
"credentialSubject": {
"id": "did:example:6789",
"type": "Person"
},
"proof": { <span class="comment">...</span> }
}
</pre>
<pre class="example nohighlight" title="Example RevocationStatus2021LDAP">
{
"@context": [
"https://www.w3.org/2018/credentials/v1"
],
"id": "https://example.com/credentials/23894672367",
"type": ["VerifiableCredential"],
"issuer": "did:example:12345",
"issued": "2021-01-11T00:35:00Z",
<span class="highlight">"credentialStatus": {
"id": "ldaps://example.com/o=dolor,cn=ipsum,ou=lorem,dc=example,dc=com",
"type": "RevocationStatus2021LDAP",
"ssl": true,
"host": "example.com",
"query": "o={{0}},cn={{1}},ou={{2}},dc={{3}},dc={{4}}",
"params": [
"dolor",
"ipsum",
"lorem",
"example",
"com"
]
}</span>,
"credentialSubject": {
"id": "did:example:6789",
"type": "Person"
},
"proof": { <span class="comment">...</span> }
}
</pre>
<section id="ssl">
<h3>SSL</h3>
<p>
The <code>ssl</code> property MUST be a boolean value if
present or it MAY be skipped that should be treated the
same as like <code>false</code> value was provided.
In case <code>true</code> value is provided then
ldaps protocol will be applied, otherwise - ldap.
</p>
<table class="simple">
<tbody>
<tr>
<td>
<a href="https://json-ld.org/spec/latest/json-ld/#dfn-terms">Term</a>
</td>
<td>
<a href="https://spherity.github.io/vc-status-2021-ldap#ssl">ssl</a>
</td>
</tr>
<tr>
<td>
<a href="https://json-ld.org/spec/latest/json-ld/#dfn-iris">Full IRI</a>
</td>
<td>
<a href="https://spherity.github.io/vc-status-2021-ldap#ssl">https://spherity.github.io/vc-status-2021-ldap#ssl</a>
</td>
</tr>
</tbody>
</table>
</section>
<section id="host">
<h3>Host</h3>
<p>
The <code>host</code> property MUST be a valid domain address,
or host ip address with port address concatenated using
<code>:</code>.
</p>
<table class="simple">
<tbody>
<tr>
<td>
<a href="https://json-ld.org/spec/latest/json-ld/#dfn-terms">Term</a>
</td>
<td>
<a href="https://spherity.github.io/vc-status-2021-ldap#host">host</a>
</td>
</tr>
<tr>
<td>
<a href="https://json-ld.org/spec/latest/json-ld/#dfn-iris">Full IRI</a>
</td>
<td>
<a href="https://spherity.github.io/vc-status-2021-ldap#host">https://spherity.github.io/vc-status-2021-ldap#host</a>
</td>
</tr>
</tbody>
</table>
</section>
<section id="query">
<h3>Query</h3>
<p>
The <code>query</code> property MUST a be a valid LDAP search
query for the verifiable credential revocation status
location. Numbers that are present inside brackets identify
indexes of respective values from credentialStatus.params
params array.
</p>
<table class="simple">
<tbody>
<tr>
<td>
<a href="https://json-ld.org/spec/latest/json-ld/#dfn-terms">Term</a>
</td>
<td>
<a href="https://spherity.github.io/vc-status-2021-ldap#query">query</a>
</td>
</tr>
<tr>
<td>
<a href="https://json-ld.org/spec/latest/json-ld/#dfn-iris">Full IRI</a>
</td>
<td>
<a href="https://spherity.github.io/vc-status-2021-ldap#query">https://spherity.github.io/vc-status-2021-ldap#query</a>
</td>
</tr>
</tbody>
</table>
</section>
<section id="params">
<h3>Params</h3>
<p>
The <code>params</code> property MUST be input params for
credentialStatus.params query.
</p>
<table class="simple">
<tbody>
<tr>
<td>
<a href="https://json-ld.org/spec/latest/json-ld/#dfn-terms">Term</a>
</td>
<td>
<a href="https://spherity.github.io/vc-status-2021-ldap#params">params</a>
</td>
</tr>
<tr>
<td>
<a href="https://json-ld.org/spec/latest/json-ld/#dfn-iris">Full IRI</a>
</td>
<td>
<a href="https://spherity.github.io/vc-status-2021-ldap#params">https://spherity.github.io/vc-status-2021-ldap#params</a>
</td>
</tr>
</tbody>
</table>
</section>
</section>
</section>
<section class="normative">
<h2>Algorithms</h2>
<p>
The following section outlines the algorithms that are used to initialize,
revoke and validate revocation status as described by this document.
</p>
<section class="normative">
<h2>Initialization Algorithm</h2>
<p>
This process MUST be followed to define LDAP URL parts for identifying
a location for a potential revocation status record per each verifiable
credential that includes RevocationStatus2021LDAP method as
value for its credentialStatus.type property, and thus relies on
an underlying directory service to store revocation information.
</p>
<ol class="algorithm">
<li>
Define parts of LDAP URL to a resource at directory service
that MAY resolve to an array of results to describe the revocation status
for the verifiable credential in question.
LDAP URL parts MUST include following properties ssl, host,
query and params.
</li>
<li>
Securely combine aforementioned LDAP URL parts to construct a fully
qualified LDAP URL value and apply its value to credentialStatus.id
property.
</li>
<li>
Apply aforementioned LDAP URL parts as values to respective properties within
credentialStatus section.
</li>
</ol>
</section>
<section class="normative">
<h2>Revocation Algorithm</h2>
<p>
This process MUST be followed to execute revocation per each
verifiable credential that includes RevocationStatus2021LDAP
method as value for its credentialStatus.type property, and thus
relies on an underlying directory service to store revocation
information.
</p>
<ol class="algorithm">
<li>
Create a revocation status record at the location defined by LDAP URL
parts described inside credentialStatus section of a given
verifiable credential.
The record MAY include a description property.
The record MAY also include a date property.
The value of the date property MUST be ISO string or UNIX
timestamp in milliseconds. ISO string format is suggested due to its
readability.
</li>
</ol>
</section>
<section class="normative">
<h2>Validation Algorithm</h2>
<p>
This process MUST be followed to identify revocation status of
verifiable credential that includes RevocationStatus2021LDAP
method as value for its credentialStatus.type property. This
identifies it as relying on underlying LDAP directory service.
</p>
<ol class="algorithm">
<li>
Build a fully qualified LDAP URL by securely combining properties
from credentialStatus section of a verifiable credential.
</li>
<li>
Execute LDAP search operation using LDAP URL.
</li>
<li>
Evaluate results of LDAP search operation.
<br>
<br>In case error code 32 (not found) is thrown, then the status
of a verifiable credential should be considered as not rovoked.
<br>
<br>In case LDAP search operation results are recieved, then the status
of a verifiable credential should be considered as revoked.
<br>
<br>If present, LDAP search results MAY include an object with
description property. If present, description property
MUST be a string.
<br>
<br>If present, LDAP search results MAY include an object with
date property. If present, date property MUST be a date
as ISO-formatted string or UNIX Epoch milliseconds as number.
</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>
<section class="informative">
<h2>Correlation</h2>
<p>
This method is best suited for fully public or semi-public credentials;
potentially leaking status information is assumed to be an acceptable
risk, and recent, signed data about current status of a verifiable
credential is assumed to be "authoritative" over other or older records,
which this method is not optimized to minimize.
</p>
<p>
Referencing the verifiable credential's unique ID in the LDAP
query string adds additional correlation risk, which may be an
anti-pattern in some use cases.
</p>
</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>
Our architecture assumes keys are managed in common across both issuance
and status-publication infrastructure. The latter is assumed to be secured
by LDAPS; LDAP-specific security is assumed and largely out of scope of
this specification, although LDAP queries are stored in the credential in
both composed and decomposed form to assure validation and comparison to
better secure queries.
</p>
<p>
Further research would be needed on how (or whether it is worthwhile) to
sign the specific status object and how to verify the relationship between
signing key of same and issuance key of original VC. A signed envelope
around the status object returned (or even a fully-formed credential
issued against a published schema) is definitely one possibility, for
use-cases where metadata passed along with status would be complex, or
need to be secured additionally.
</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>