-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.html
1068 lines (895 loc) · 56 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>
<meta charset="utf-8" />
<title>Inter-Wallet Credential Exchange</title>
<script
src="https://www.w3.org/Tools/respec/respec-w3c"
class="remove"
defer
></script>
<script class="remove">
// All config options at https://respec.org/docs/
var respecConfig = {
authors: [
{
name: "Christoph Menzer",
url: "https://www.cb.hs-mittweida.de/mitarbeiterinnen-mitarbeiter-in-ihren-fachgruppen/menzer-christoph/",
company: "BCCM, Hochschule Mittweida",
companyURL: "https://blockchain.hs-mittweida.de",
}, {
name: "Sarah Otto",
url: "https://www.cb.hs-mittweida.de/mitarbeiterinnen-mitarbeiter-in-ihren-fachgruppen/otto-sarah/",
company: "BCCM, Hochschule Mittweida",
companyURL: "https://blockchain.hs-mittweida.de",
},
],
editors: [
{
name: "Christoph Menzer",
url: "https://www.cb.hs-mittweida.de/mitarbeiterinnen-mitarbeiter-in-ihren-fachgruppen/menzer-christoph/",
company: "BCCM, Hochschule Mittweida",
companyURL: "https://blockchain.hs-mittweida.de",
}, {
name: "Sarah Otto",
url: "https://www.cb.hs-mittweida.de/mitarbeiterinnen-mitarbeiter-in-ihren-fachgruppen/otto-sarah/",
company: "BCCM, Hochschule Mittweida",
companyURL: "https://blockchain.hs-mittweida.de",
},
],
github: "b2cm/iwce",
shortName: "iwce",
xref: "web-platform",
noRecTrack: true,
localBiblio: {
applinks: {
title: "Handling Android App Links. Android Developers",
href: "https://developer.android.com/training/app-links",
publisher: "Google Inc.",
},
universallinks: {
title: "Allowing Apps and Websites to Link to Your Content. Apple Developer Documentation",
href: "https://developer.apple.com/documentation/uikit/inter-process_communication/allowing_apps_and_websites_to_link_to_your_content",
publisher: "Apple Inc.",
},
didconfiguration: {
title: "Well Known DID Configuration",
href: "https://identity.foundation/specs/did-configuration/",
publisher: "Decentralized Identity Foundation",
},
openidconnect: {
title: "OpenID Connect Core 1.0 incorporating errata set 1",
href: "https://openid.net/specs/openid-connect-core-1_0.html",
publisher: "OpenID Foundation",
},
},
};
</script>
</head>
<body>
<section id="abstract">
<p>
Inter-Wallet Credential Exchange describes a simple way to exchange [=identity=] information in a secure, decentralized, and scalable manner.
It uses standardized data structures, formats, and transport protocols to enable applications (particularly [=identity=] [=wallets=]) from different manufacturers to communicate with each other, without a third party or an intermediary.
The main purpose of this approach is to establish a [=claim=]-based [=identity=] management model in the World Wide Web.
</p>
</section>
<section id="sotd">
<p>This is required.</p>
</section>
<section class="informative">
<h2>Introduction</h2>
<p>
In the real world, [=identity=] could be proofed physically showing the own ID card, driver's license, or student ID to any other person requesting it.
In the digital world, things become more complicated.
Here a way expressing the information of such credentials is needed, also a way of proofing possession and to sending it to a requesting party.
</p>
<p>
The Verifiable Credentials Data Model [[vc-data-model]] is used to solve the first aforementioned challenge.
The ecosystem of this model consists of multiple roles and their actors identifiable by some kinds of [=identifiers=].
These can be [=decentralized identifiers=] (<abbr title="decentralized identifiers">DIDs</abbr>) [[did-core]], [=Uniform Resource Identifiers=] (<abbr title="Uniform Resource Identifiers">URIs</abbr>) [[rfc3986]], [=Uniform Resource Locators=] (<abbr title="Uniform Resource Locators">URLs</abbr>) and so on.
By the use of DIDs and their corresponding [=DID documents=], the [=identifier=] is fully under the control of its owning [=entity=].
Therefore, they are neither trustworthy nor make any statement about their owner itself.
</p>
<p>
To address this problem, [=verifiable credentials=] (<abbr title="verifiable credentials">VCs</abbr>) and their corresponding [=verifiable presentations=] (<abbr title="verifiable presentations">VPs</abbr>) can be used.
VCs are cryptographically signed by a (supposedly) trusted [=issuer=] and make [=claims=] about the aforementioned owner of an [=identifier=].
This owner is referred to as the [=holder=].
If the [=holder=] wishes to prove ownership of a VC, VPs are used.
These are cryptographically signed by the [=holder=] to prove control of the [=identifier=].
Therefore VPs solve the second listed challenge mentioned at the beginning.
</p>
<p>
The Inter-Wallet Credential Exchange uses DIDs, VCs, and VPs in conjunction with HTTPS to transport [=identity=] information between two applications directly.
For optimal decentralization, it is recommended to use special URLs known as Universal-Links [[universallinks]] or App-Links [[applinks]] respectively.
In the case of web applications running on a desktop, in conjunction with a mobile device, these links can be transferred using a QR code.
So Inter-Wallet Credential Exchange proposes a solution to the third listed challenge in the digitalization of credentials.
</p>
</section>
<section>
<h2>Scope</h2>
<p>
This proposal mainly specifies two data structures, their encoding, and transport over HTTPS.
It describes the use of Universal- or App-Links and their advantages in terms of decentralization.
Furthermore, VCs and an additional special data structure are used so that users can reveal only certain personal information, without the complexity of [=zero-knowledge proofs=].
</p>
<p>
Out of scope are any semantics of concrete VCs and related data structures.
Moreover, no detailed implementation instructions are given concerning different development environments, programming languages, and operating systems.
Additionally, the issuing process of a VC isn't addressed.
This process is designed by each service acting as [=issuer=] individually.
It is assumed that corresponding VCs have already been issued to a user in an [=issuer=]'s [=wallet=] application.
</p>
<p>
Inter-Wallet Credential Exchange is not a solution for [=single sign-on=] (SSO) and hence not about the login process currently mostly solved with username and password.
Rather, the aim is to speed up the registration process for new services and to replace the login with passwordless procedures.
The latter takes place exclusively within a service's own domain (see [[[#sds]]] and [[[#anti-correlation]]]).
However, the authentication of devices or applications against their own backend is not the actual concern either.
The DIDs described here or other asymmetric cryptography methods (e.g. Web Authentication) are suitable for this.
For existing systems, it is also conceivable that other authentication methods currently in widespread use, such as the legacy username and password, or centralized schemes such as OAuth [[rfc6749]] or OpenID Connect [[openidconnect]], could be used to authenticate within one's domain.
</p>
</section>
<section class="informative">
<h2>Terminology</h2>
<dl class="termlist" data-sort>
<dt><dfn>blockchain</dfn></dt>
<dd>
Also referred to as <strong><em><dfn data-abbr="DLT">distributed ledger</dfn></em></strong>, is a non-centralized system for recording events. These systems establish sufficient confidence for participants to rely upon the data recorded by others to make operational decisions. They typically use distributed databases where different nodes use a consensus protocol to confirm the ordering of cryptographically signed transactions. The linking of digitally signed transactions over time often makes the history of the ledger effectively immutable.
</dd>
<dt><dfn data-abbr="CAS">content-addressable storage</dfn></dt>
<dd>
Content-addressable storage, also referred to as content-addressed storage or abbreviated CAS, is a way to store information so it can be retrieved based on its content, not its location.
CAS typically uses a cryptographic [=hash=] function's digest generated from the document to identify that document in the storage system.
</dd>
<dt><dfn>credential request</dfn></dt>
<dd>
A data structure to make a request for a [=verifiable presentation=] containing one or more [=verifiable credentials=].
</dd>
<dt><dfn>credential response</dfn></dt>
<dd>
A data structure to make a response to a [=credential request=] containing one [=verifiable presentation=] with one or more [=verifiable credentials=]. Additionally, one or more [=plaintext credentials=] may be provided.
</dd>
<dt><dfn data-abbr="DID">decentralized identifier</dfn></dt>
<dd>
A globally unique URL-based [=identifier=], also known as a DID, associated with an [=entity=].
These [=identifiers=] are mostly used in a [=verifiable credential=] to identify its [=subject=].
</dd>
<dt><dfn>DID document</dfn></dt>
<dd>
A document that is accessible from a [=verifiable data registry=] using a [=DID resolver=] and contains information related to a specific [=decentralized identifier=], such as the associated public key information.
</dd>
<dt><dfn>DID method</dfn></dt>
<dd>
A definition of how a specific DID method scheme is implemented. A DID method is defined by a DID method specification, which specifies the precise operations by which DIDs and [=DID documents=] are created, resolved, updated, and deactivated
</dd>
<dt><dfn>DID resolver</dfn></dt>
<dd>
A DID resolver is a software and/or hardware component that performs the DID resolution function by taking a DID as input and producing a conforming [=DID document=] as output.
</dd>
<dt><dfn>identity</dfn></dt>
<dd>
The means for keeping track of [=entities=] across contexts.
Digital identities enable tracking and customization of [=entity=] interactions across digital contexts, typically using [=identifiers=] and attributes.
</dd>
<dt><dfn>entity</dfn></dt>
<dd>
A thing with distinct and independent existence, such as a person, organization, or device that performs one or more roles in the ecosystem.
</dd>
<dt><dfn>identifier</dfn></dt>
<dd>
An identifier is a name that identifies either a unique object or a unique class of objects, where the "object" or class may be an idea, [=entity=] (or class thereof), physical object (or class thereof), or other.
An identifier may be a word, number, letter, symbol, or any combination of those.
</dd>
<dt><dfn data-abbr="PFS">perfect forward secrecy</dfn></dt>
<dd>
In cryptography, this is a feature of specific key agreement protocols that gives assurances that session keys will not be compromised even if long-term secrets used in the session key exchange are compromised.
For HTTPS, the long-term secret is typically the Private signing key of the server.
Forward secrecy protects past sessions against future compromises of keys or passwords.
</dd>
<dt><dfn>plaintext credential</dfn></dt>
<dd>
A data structure that stores plain values and [=salts=] serving as input to a [=hash=] function. It is used to implement the [=selective disclosure=] feature in a [=verifiable credential=].
</dd>
<dt><dfn data-abbr="PKI">public key infrastructure</dfn></dt>
<dd>
A set of roles, policies, hardware, software, and procedures that are needed to create, manage, distribute, use, store and revoke digital certificates and manage public-key encryption.
</dd>
<dt><dfn data-abbr="SSO">single sign-on</dfn></dt>
<dd>
An authentication scheme that allows a user to log in with a single [=identifier=] and password to any of several related, yet independent, software systems.
</dd>
<dt><dfn data-abbr="TLS">Transport Layer Security</dfn></dt>
<dd>
A cryptographic protocol designed to provide communications security over a computer network. It aims primarily to provide privacy and data integrity between two or more communicating computer applications.
</dd>
<dt><dfn data-abbr="VC">verifiable credential</dfn></dt>
<dd>
A standard data model and representation format for cryptographically-verifiable digital credentials as defined by the W3C Verifiable Credentials specification [[vc-data-model]].
</dd>
<dt><dfn data-abbr="VP">verifiable presentation</dfn></dt>
<dd>
A standard data model and representation format for tamper-evident presentation of data derived from one or more [=verifiable credentials=] as defined by the W3C Verifiable Credentials specification [[vc-data-model]].
</dd>
<dt><dfn>wallet</dfn></dt>
<dd>
A wallet in the context of cryptocurrency or [=identity=] is a device, physical medium, program, or service which stores the public and/or private keys for cryptocurrency transactions or other data structures.
In addition, a wallet usually offers the functionality of encrypting and/or signing data.
</dd>
<dt><dfn>zero-knowledge proof</dfn></dt>
<dd>
In cryptography, a zero-knowledge proof or zero-knowledge protocol is a method by which one party (the prover or [=holder=]) can prove to another party (the [=verifier=]) that they know a value, without conveying any information apart from the fact that they know this value.
</dd>
<dt><dfn>holder</dfn></dt>
<dd>
A role an [=entity=] might perform by possessing one or more [=verifiable credentials=] and generating [= verifiable presentations=] from them.
A holder is usually, but not always, a [=subject=] of the [=verifiable credentials=] they are holding.
</dd>
<dt><dfn>issuer</dfn></dt>
<dd>
A role an [=entity=] can perform by asserting [=claims=] about one or more [=subjects=], creating a [=verifiable credential=] from these [=claims=], and transmitting the [=verifiable credential=] to a [=holder=].
</dd>
<dt><dfn>subject</dfn></dt>
<dd>
A thing about which [=claims=] are made.
</dd>
<dt><dfn>verifier</dfn></dt>
<dd>
A role an [=entity=] performs by receiving one or more [=verifiable credentials=] inside a [=verifiable presentation=] for processing.
Other specifications might refer to this concept as a <dfn>relying party</dfn>.
</dd>
<dt><dfn data-abbr="URI">Uniform Resource Identifier</dfn></dt>
<dd>
A Uniform Resource Identifier, as defined by [[rfc3986]].
A special subtype of an URI is the <strong><em><dfn data-abbr="URL">Uniform Resource Locator</dfn></em></strong>.
</dd>
<dt><dfn>digital signature</dfn></dt>
<dd>
A mathematical scheme for demonstrating the authenticity of a digital message.
</dd>
<dt><dfn>claim</dfn></dt>
<dd>
An assertion made about a [=subject=].
</dd>
<dt><dfn>selective disclosure</dfn></dt>
<dd>
The ability of a [=holder=] to make fine-grained decisions about what information of a [=verifiable credential=] to share.
</dd>
<dt><dfn>verifiable data registry</dfn></dt>
<dd>
A system that facilitates the creation, verification, updating, and/or deactivation of [=decentralized identifiers=] and [=DID documents=]. A verifiable data registry might also be used for other cryptographically verifiable data structures such as [=verifiable credentials=]. For more information, see the W3C Verifiable Credentials specification [[vc-data-model]].
</dd>
<dt><dfn>hash</dfn></dt>
<dd>
The values returned by a hash function are called hash values, hash codes, digests, or simply hashes.
A hash function is any one-way function that can be used to map data of arbitrary size to fixed-size values.
</dd>
<dt><dfn>salt</dfn></dt>
<dd>
In cryptography, a salt is random data that is used as an additional input to a one-way function that [=hashes=] data, a password, or a passphrase.
</dd>
<dt><dfn data-abbr="HTTP">Hypertext Transfer Protocol</dfn></dt>
<dd>
An application layer protocol for distributed, collaborative, hypermedia information systems designed within the framework of the Internet protocol suite.
HTTP resources are identified and located on the network by URLs.
An extension of HTTP is <strong><em><dfn data-abbr="HTTPS">Hypertext Transfer Protocol Secure</dfn></em></strong>, which uses TLS to encrypt the communication protocol.
</dd>
<dt><dfn data-abbr="TTL">Time to live</dfn></dt>
<dd>
A mechanism that limits the lifespan or lifetime of data in a computer or network.
TTL may be implemented as a counter or timestamp attached to or embedded in the data.
</dd>
<dt><dfn data-abbr="UUID">Universally Unique Identifier</dfn></dt>
<dd>
A 128-bit number described by [[rfc4122]] and used to uniquely identify some object or [=entity=] on the Internet.
When generated according to the standard methods, UUIDs are, for practical purposes, unique.
Their uniqueness does not depend on a central registration authority or coordination between the parties generating them.
</dd>
<dt><dfn data-abbr="NAT">Network address translation</dfn></dt>
<dd>
A method of mapping an IP address space into another by modifying network address information in the IP header of packets while they are in transit across a traffic routing device.
</dd>
<dt><dfn>firewall</dfn></dt>
<dd>
A network security system that monitors and controls the incoming and outgoing network traffic based on predetermined security rules.
</dd>
</dl>
</section>
<section>
<h2>Assumptions</h2>
<section class="informative">
<h2>Decentralized Identifiers</h2>
<p>
DIDs as defined in [[did-core]] are a new type of [=identifiers=].
They are generated and controlled by an [=entity=] itself.
Therefore the number of DIDs an [=entity=] can create is unlimited.
Proof of control over a DID is provided by cryptographic methods, e.g. [=digital signatures=].
</p>
<p>
A DID contains the names of a schema and a [=DID method=] as well as the [=identifier=] itself. These parts are separated by a colon:
</p>
<aside class="example">
<pre class="nohighlight">
did:example:123456789abcdefghi
</pre>
</aside>
<p>
The schema denotes that it is a DID. The [=DID method=] identifies the way the [=identifier=] can be created and managed.
The W3C maintains an official list of [=DID methods=] and their specifications for this purpose [[did-spec-registries]].
The specification of a [=DID method=] contains information about all important operations, such as creating, reading, updating, and deleting DIDs.
</p>
<p>
A DID is resolved by a [=DID resolver=] into a [=DID document=] stored on a [=verifiable data registry=].
This can be a [=blockchain=], [=content-addressable storage=] (CAS), or any other (web) server.
The [=DID document=] contains additional information about a DID, such as further public keys, authentication and authorization methods, or so-called service endpoints.
The latter are details of services or storage locations that can be linked to the [=identifier=].
A [=DID document=] never contains personal information.
</p>
<aside class="note" title="DID documents">
<p>
It is important to understand, that [=DID documents=] DO NOT contain any personally identifiable information (PII).
They are only used to describe some technical information about the [=identifier=].
These can be for example public keys, methods for verification, authentication, and assertion, or service endpoints.
</p>
</aside>
<p>
In some [=DID methods=], the [=identifiers=] have cryptographic material or a fingerprint of a public key, just as they do in a [=blockchain=].
In this way, a DID can authenticate directly against a smart contract in the corresponding [=blockchain=].
Furthermore, some [=digital signature=] methods such as the Elliptic Curve Digital Signature Algorithm (ECDSA) allow the recovery of the public key directly from a [=digital signature=].
This feature makes it possible to use a signed message directly for authentication between two hosts.
The method for generating the [=identifier=], e.g. a DID or an address in the context of [=blockchain=], from a public key is usually known.
From this point of view, it is not urgent to keep a [=DID document=] as long as the relationship between private key, public key, and the [=identifier=] is computable.
For example, in the ETHR DID Method (`did:ethr:xyz`) the [=DID document=] is created by the [=DID resolver=].
</p>
</section>
<section class="informative" id="selective-disclosure">
<h2>Verifiable Credentials and Selective Disclosure</h2>
<p>
This proposal makes use of VCs and VPs according to the [[[vc-data-model]]].
VCs are data structures making statements about a person or an object according to the principles of [=claim=]-based [=identity=].
They are cryptographically verifiable because they are signed by an [=issuer=].
The [=claims=] are simple statements associated with an [=identifier=] and some metadata.
Basically, anyone can act as an [=issuer=], e.g., a trusted [=entity=] or even oneself.
The latter type of VCs are called self-issued credentials and are useful, for example, for delegating one's own credential to another [=identifier=].
What should be considered as a trusted [=entity=] for certain statements is not part of this proposal.
</p>
<p>
Additionally to VCs described in the aforementioned specification [[[vc-data-model]]] this proposal supports a special way that implementing the [=selective disclosure=] feature.
This feature allows the credential [=holder=] to choose which attributes should be shown to the [=verifier=].
To achieve this, every attribute value a [=verifiable credential=] contains, is hashed with a cryptographic [=salt=].
The final [=verifiable credential=] will only contain these [=hashes=] - the [=salts=] and the values are stored in a separate JSON data object, called the [=plaintext credential=].
The following examples will show such a [=plaintext credential=] and its corresponding VC.
</p>
<aside class="example">
<p>[=Plaintext credential=]</p>
<pre class="json">
{
"id": "did:example:0x1611994c317bed3102D65A93B667Dbe0591Da41c",
"type": ["HashedPlaintextCredential2021","NameAgeCredential"],
"hashAlg": "keccak-256",
"name": {
"value": "Max",
"salt": "dc0931a0-60c6-4bc8-a27d-b3fd13e62c63",
},
"age": {
"value": 20,
"salt": "3e9bacd3-aa74-42c1-9895-e490e3931a73",
},
}
</pre>
</aside>
<aside class="example">
<p>Corresponding [=verifiable credential=]</p>
<pre class="json">
{
"@context": ["https://www.w3.org/2018/credentials/v1",
"https://some.example.com/credentials/ld-context/"],
"type": ["VerifiableCredential"],
"credentialSubject": {
"id": "did:example:0x1611994c317bed3102D65A93B667Dbe0591Da41c",
"type": "NameAgeCredential",
"name": "0xd8925653ed000200d2b491bcabe2ea69f378abb91f056993a6d3e3b28ad4ccc4",
"age": "0x43bde6fcd11015c6a996206dadd25e149d131c69a7249280bae723c6bad53888"
},
"issuer": "did:example:0x6d32738382c6389eF0D79045a76411C42Fff3a5e",
"issuanceDate": "2020-11-30T11:06:39.423520Z",
"proof": {
"type": "EcdsaSecp256k1RecoverySignature2020",
"proofPurpose": "assertionMethod",
"verificationMethod": "did:example:0x6d32738382c6389eF0D79045a76411C42Fff3a5e",
"created": "2020-11-30T11:06:39.497073Z",
"jws": "ey..E="
}
}
</pre>
</aside>
</section>
<section class="informative">
<h2>Verifiable Credentials and Verifiable Presentations</h2>
<p>
The VCs are issued to a [=subject=] (owned by a [=holder=]) and its [=identifier=], e.g. a DID.
This [=holder=] can generate a VP with one or more VCs, in which he can prove by a [=digital signature=] that he controls the [=identifier=](s) of one or more VCs.
The aggregation of this information typically expresses some aspect of a person, organization, or other [=entity=].
He finally sends the VP to a [=verifier=] that can cryptographically validate the VC's trustworthiness.
</p>
<aside class="example">
<p>Corresponding [=verifiable presentation=]</p>
<pre class="json">
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
],
"type": "VerifiablePresentation",
"verifiableCredential": [{
"@context": ["https://www.w3.org/2018/credentials/v1",
"https://some.example.com/credentials/ld-context/"],
"type": ["VerifiableCredential"],
"credentialSubject": {
"id": "did:example:0x1611994c317bed3102D65A93B667Dbe0591Da41c",
"type": "NameAgeCredential",
"name": "0xd8925653ed000200d2b491bcabe2ea69f378abb91f056993a6d3e3b28ad4ccc4",
"age": "0x43bde6fcd11015c6a996206dadd25e149d131c69a7249280bae723c6bad53888"
},
"issuer": "did:example:0x6d32738382c6389eF0D79045a76411C42Fff3a5e",
"issuanceDate": "2020-11-30T11:06:39.423520Z",
"proof": {
"type": "EcdsaSecp256k1RecoverySignature2020",
"proofPurpose": "assertionMethod",
"verificationMethod": "did:example:0x6d32738382c6389eF0D79045a76411C42Fff3a5e",
"created": "2020-11-30T11:06:39.497073Z",
"jws": "ey..E="
}
}],
"proof": [{
"type": "EcdsaSecp256k1RecoverySignature2020",
"proofPurpose": "authentication",
"verificationMethod": "did:example:0x1611994c317bed3102D65A93B667Dbe0591Da41c",
"challenge": "1f44d55f-f161-4938-a659-f8026467f126",
"created": "2020-11-30T11:06:39.497073Z",
"jws": "ey..n="
}]
}
</pre>
</aside>
<p>
In addition, a VP itself can also have an [=identifier=].
It is also possible for each of the VCs to be issued to a different [=identifier=].
For each of these [=identifiers=] (of each [=subject=]), the corresponding proof can be included in the array of proofs in the VP.
A challenge within one or more proofs authenticates for example a session.
</p>
<aside class="example">
<p>[=Verifiable presentation=] containing an [=identifier=] and several [=verifiable credentials=], as well as their associated proofs</p>
<pre class="nohighlight">
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
],
<span style="color: #008000; font-weight: bold">"id": "did:anotherexample:xyv2-xzpq-q9wa-p7t"</span>,
"type": "VerifiablePresentation",
"verifiableCredential": [{
"@context": ["https://www.w3.org/2018/credentials/v1",
"https://some.example.com/credentials/ld-context/"],
"type": ["VerifiableCredential"],
"credentialSubject": {
<span style="color: #008000; font-weight: bold">"id": "did:example:0x1611994c317bed3102D65A93B667Dbe0591Da41c"</span>,
"type": "NameCredential",
"name": "0xd8925653ed000200d2b491bcabe2ea69f378abb91f056993a6d3e3b28ad4ccc4",
},
"issuer": "did:example:0x6d32738382c6389eF0D79045a76411C42Fff3a5e",
"issuanceDate": "2020-11-30T11:06:39.423520Z",
"proof": {
"type": "EcdsaSecp256k1RecoverySignature2020",
"proofPurpose": "assertionMethod",
"verificationMethod": "did:example:0x6d32738382c6389eF0D79045a76411C42Fff3a5e",
"created": "2020-11-30T11:06:39.497073Z",
"jws": "ey..E="
}
}, {
"@context": ["https://www.w3.org/2018/credentials/v1",
"https://some.example.com/credentials/ld-context/"],
"type": ["VerifiableCredential"],
"credentialSubject": {
<span style="color: #008000; font-weight: bold">"id": "did:example:0x7c0296fb88ec930a2a31361ca1b579603bc18892"</span>,
"type": "AgeCredential",
"age": "0x43bde6fcd11015c6a996206dadd25e149d131c69a7249280bae723c6bad53888"
},
"issuer": "did:example:0x6d32738382c6389eF0D79045a76411C42Fff3a5e",
"issuanceDate": "2020-11-30T11:06:39.423520Z",
"proof": {
"type": "EcdsaSecp256k1RecoverySignature2020",
"proofPurpose": "assertionMethod",
"verificationMethod": "did:example:0x6d32738382c6389eF0D79045a76411C42Fff3a5e",
"created": "2020-11-30T11:06:39.497073Z",
"jws": "ey..G"
}
}],
"proof": [{
"type": "EcdsaSecp256k1RecoverySignature2020",
"proofPurpose": "authentication",
<span style="color: #008000; font-weight: bold">"verificationMethod": "did:example:0x1611994c317bed3102D65A93B667Dbe0591Da41c"</span>,
"challenge": "1f44d55f-f161-4938-a659-f8026467f126",
"created": "2020-11-30T11:06:39.497073Z",
"jws": "ey..v="
}, {
"type": "EcdsaSecp256k1RecoverySignature2020",
"proofPurpose": "authentication",
<span style="color: #008000; font-weight: bold">"verificationMethod": "did:example:0x7c0296fb88ec930a2a31361ca1b579603bc18892"</span>,
"challenge": "1f44d55f-f161-4938-a659-f8026467f126",
"created": "2020-11-30T11:06:39.497073Z",
"jws": "ey..6"
}, {
"type": "EcdsaSecp256k1RecoverySignature2020",
"proofPurpose": "authentication",
<span style="color: #008000; font-weight: bold">"verificationMethod": "did:anotherexample:xyv2-xzpq-q9wa-p7t"</span>,
"challenge": "1f44d55f-f161-4938-a659-f8026467f126",
"created": "2020-11-30T11:06:39.497073Z",
"jws": "ey..r"
}]
}
</pre>
</aside>
</section>
<section class="informative">
<h2>Verifiable Credentials and Revocation</h2>
<p>
In addition to an expiration date (`expirationDate` or `validUntil`) for credentials, [=issuers=] also have the option to revoke it.
For this purpose, the [[[vc-data-model]]] defines the property `credentialStatus`, which links to a revocation list.
This list can be stored on a [=blockchain=], [=content-addressable storage=] (CAS), or any other (web) server.
</p>
<aside class="example">
<p>Expiration date and status in a [=verifiable credential=]</p>
<pre class="json">
{
"expirationDate": "2020-01-01T19:23:24Z",
"credentialStatus": {
"id": "0x06012c8cf97bead5deae237070f9587f8e7a266d",
"type": "EthereumMainnetStatusList2021"
},
}
</pre>
</aside>
</section>
<section class="informative" id="uniapplinks">
<h2>Universal / App Links</h2>
<p>
Universal or app links are a way in mobile operating systems to retrieve certain data from an app using a URL.
For Apple's iOS, they are documented as universal links [[universallinks]], for Google they are called Android App Links [[applinks]].
These links are a form of deep links that are handled specifically in the operating systems.
During the installation of an app, a handler for a specific URL is created in the operating system that uniquely identifies the app.
To prove ownership of a URL, a check is made for a specific machine-readable document that must be provided under the URLs domain.
After this check is successful, requests to this URL are passed directly to the installed app without any further interaction from the user.
Binding to a domain ensures uniqueness and the mandatory use of HTTPS ensures authenticity and secrecy.
</p>
<p>
If a request is made to the URL and there is no corresponding app installed, it will be opened in the browser.
The request, therefore, does not end in an error state but can be answered by the own web server as desired.
For example, the user gets a hint to install the corresponding app or is redirected to an online application.
</p>
</section>
</section>
<section>
<h2>Protocol Flow</h2>
<section>
<h2>Credential Request</h2>
<p>
To request VCs within a VP the following simple JSON data structure MUST be used, which MUST then be encoded with Base64url [[rfc4648]] and attached as a query parameter with key `ìwce` to a URL.
The URIs used comply with the [[[rfc3986]]] specification.
VCs and VPs are compliant with the [[[vc-data-model]]].
</p>
<p>
A [=credential request=] is defined with the following properties:
<dl>
<dt>type</dt>
<dd>
The `type` property is required and MUST be an URI. The value `"CredentialRequest"` MUST be used to determine that it is a [=credential request=].
</dd>
<dt>accept</dt>
<dd>
The `accept` property is required and describes the accepted data of a [=credential response=] to a [=credential request=]. It is defined with the following properties:
<dl>
<dt>type</dt>
<dd>
The `type` property is required and MUST be an URI.
The value `"CredentialResponse"` MUST be used to determine that the requested data has to be provided in the form of a [=credential response=].
</dd>
<dt>verifiablePresentation<dt>
<dd>
The `verifiablePresentation` property is required.
<dl>
<dt>type</dt>
<dd>
The `type` property is required and MUST be an URI.
It denotes the expected type of the [=verifiable presentation=].
</dd>
<dt>credentialTypes</dt>
<dd>
The `credentialTypes` property is required and MUST be an array of URIs.
It denotes the accepted URIs of [=verifiable credential=] types within a [=verifiable presentation=].
</dd>
</dl>
</dd>
<dt>selectiveDisclosure</dt>
<dd>
The `selectiveDisclosure` property is optional. If it is not set, no method for [=selective disclosure=] is accepted.
<dl>
<dt>type</dt>
<dd>
The `type` property is required and MUST be an URI.
It denotes the expected method of the [=selective disclosure=] feature.
</dd>
<dt>requiredProperties</dt>
<dd>
The `requiredProperties` property is type-specific.
For the [=selective disclosure=] feature proposed in section [[[#selective-disclosure]]], the `requiredProperties` property MUST be an object that contains one or more arrays of strings corresponding to the property names of one or more [=plaintext credentials=] mandatorily being disclosed.
To refer to properties in nested objects within the [=plaintext credential=] the notation `parentObjectKey.childPropertyKey` MUST be used.
The key of each set MUST correspond to the credential type specified in property `credentialTypes`.
Which properties are then really returned is not guaranteed and has to be checked in the response.
</dd>
</dl>
</dd>
<dt>endpoint</dt>
<dd>
The `endpoint` property is required. It describes the endpoint to which the requested data has to be sent.
<dl>
<dt>type</dt>
<dd>
The `type` property is required and MUST be an URI.
It can take either the value `"AppLink"` or `"WebAddress"`.
`"AppLink"` determines that the endpoint is a universal or app link and is RECOMMENDED for best decentralization, see section [[[#uniapplinks]]].
The value `"WebAddress"` determines that the endpoint is a normal web resource (web address).
Future types could be e.g. `"DIDComm"` or similar.
</dd>
<dt>location</dt>
<dd>
The `location` property is required and MUST be an URL that links to a resource with HTTPS enabled.
</dd>
</dl>
</dd>
</dl>
</dd>
<dt>challenge</dt>
<dd>
The `challenge` property is required and MUST be a long random number.
It is RECOMMENDED to use at least 128 bits. For example, an UUID [[rfc4122]] might be helpful for this task.
The challenge is computed by the [=verifier=] and MUST have a [=Time to Live=] (TTL).
</dd>
<dt>domain</dt>
<dd>
The `domain` property is optional and MUST be an URI.
It is used to announce domain-specific extensions in a [=credential request=].
</dd>
</dl>
</p>
<aside class="example">
<p>[=Credential request=] data object</p>
<pre class="json">
{
"type": "CredentialRequest",
"accept": {
"type": "CredentialResponse",
"verifiablePresentation": {
"type": "VerifiablePresentation",
"credentialTypes": ["AgeCredential","NameCredential"],
},
"selectiveDisclosure": {
"type": "HashedPlaintextCredential2021",
"requiredProperties": {
"AgeCredential": ["age"]
},
},
"endpoint": {
"type": "AppLink",
"location": "https://verifier-app.another-example.com/responses"
}
},
"challenge": "1f44d55f-f161-4938-a659-f8026467f126",
"domain": "example.com"
}
</pre>
</aside>
<aside class="example">
<p>Encoded [=credential request=]</p>
<pre class="nohighlight">
https://issuer-app.example.com/requests?<span style="color: #008000; font-weight: bold">iwce=eyAidHlwZSI6ICJDc...IgfQ</span>
</pre>
</aside>
<aside class="note" title="QR codes">
<p>
For use with web applications on a desktop, the URL including the encoded [=credential request=] can be represented as a QR code.
Depending on the type used, there may be restrictions on the amount of data that can be encoded.
Since the challenge has a TTL, the QR code has to be rerendered frequently.
</p>
</aside>
</section>
<section>
<h2>Credential Response</h2>
<p>
To respond to a request for a VP the following data structure MUST be used, which MUST be encoded with Base64url [[rfc4648]] and attached as a query parameter with key `iwce` to a URL.
The URIs used comply with the [[[rfc3986]]] specification.
VCs and VPs are compliant with the [[[vc-data-model]]].
</p>
<p>
<dl>
<dt>type</dt>
<dd>
The `type` property is required and MUST be an URI.
The value `"CredentialResponse"` MUST be used to determine that it is a [=credential response=].
</dd>
<dt>verifiablePresentation</dt>
<dd>
The `verifiablePresentation` property is required and defined as an object that contains exactly one [=verifiable presentation=].
The proofs within a [=verifiable presentation=] MUST contain the `challenge` property that was received with a [=credential request=].
The proofs can also contain the `domain` property to announce domain-specific extensions
</dd>
<dt>selectiveDisclosure<dt>
<dd>
The `selectiveDisclosure` property is optional.
If it is not set, no method for [=selective disclosure=] is supported.
<dl>
<dt>type</dt>
<dd>
The `type` property is required and MUST be an URI.
It denotes the expected method of the [=selective disclosure=] feature.
</dd>
<dt>plaintextCredential</dt>
<dd>
The `plaintextCredential` property is type-specific.
The expected return value is data conforming to the `type` information from a [=credential request=].
For the [=selective disclosure=] feature proposed in section [[[#selective-disclosure]]], the `plaintextCredential` property is defined as an array of objects containing one or more [=plaintext credentials=].
</dd>
</dl>
</dd>
</dl>
</p>
<aside class="example">
<p>[=Credential response=] data object</p>
<pre class="json">
{
"type": "CredentialResponse",
"verifiablePresentation": {},
"selectiveDisclosure": {
"type": "HashedPlaintextCredential2021",
"plaintextCredential": [{},{}]
}
}
</pre>
</aside>
<aside class="example">
<p>Encoded [=credential response=]</p>
<pre class="nohighlight">
https://verifier-app.another-example.com/responses?<span style="color: #008000; font-weight: bold">iwce=eyZXJpZmlhYmxlUHJ...JodH</span>
</pre>
</aside>
</section>
</section>
<section id="sds">
<h2>Strict Domain Separation</h2>
<p>
The use of multiple proofs in a VP makes it possible to strictly separate the domains of [=identity=] information.
For best decentralization, VCs SHOULD only be issued within a domain and SHOULD only be stored in a domain's own application.
To be faithful to the concept of Inter-Wallet Credential Exchange, the only way to exchange VCs with external or third-party applications MUST be the use of VPs.
The private key of a [=subject=]'s [=identifier=] MUST NOT leave its own applications within a domain.
This has several advantages:
</p>
<ul>
<li>an [=issuer=] can decide how to store the private keys of a [=subject=] it issues [=verifiable credentials=] to (security levels)</li>
<li>an [=issuer=] can enforce security mechanisms such as two-factor authentication</li>
<li>an [=issuer=] can customize the issuance process to meet its specific needs</li>
<li>areas of responsibility are clearly separated</li>
<li>personal data is managed where it already exists, within a domain</li>
<li>an [=issuer=] can decide for its application which properties a user ([=holder=]) will actually disclose and share across its own domain boundary</li>
</ul>
<p>
Since the proofs in a VP can be made for different [=identifiers=], an [=issuer=]'s application is able to interoperate with different types of [=identifiers=].
For example, the [=identifier=] of a VP can be an address in [=blockchain=] A and the [=identifiers=] of the VCs are DIDs anchored in [=blockchain=] B.
The latter is a [=blockchain=] in the [=issuer=]'s domain, [=blockchain=] A is that of a third-party application.
In that way, a user can prove control over an address in any [=blockchain=] or any other [=identifier=] in combination with verifiable personal information.
For this to work, both, the [=issuer=] and the [=verifier=] MUST implement all DID methods of the [=identifiers=] used.
</p>
<p>
The issuing process is domain-specific and an [=issuer=] decides what types of [=identifiers=] he is using for its own VCs.
An [=issuer=] SHOULD use DIDs as specified in [[[did-core]]] to authenticate a VC on a device (`id` of `credentialSubject`) to the own backend.
An [=issuer=] MAY use DIDs for the `issuer` property to authenticate himself to the [=verifier=].
In that case, the [[[didconfiguration]]] SHOULD be used for trust, see [[[#trust]]] for more details.
</p>
</section>
<section class="informative">
<h2>User Experience</h2>
<p>
Considerations about end-user experience are closely related to the use of app or universal links and VCs/VPs.
App or universal links enable a seamless user experience during the exchange of VPs between apps on the user's device, because, when implemented correctly, they identify the app the operating system should open.
Additionally, these links are normal URLs and can be represented in any form a URL can take, e.g. as a QR code.
Therefore, an exchange between different devices (smartphone and desktop) is possible without a loss in user experience, because the QR code can be scanned with every app capable of doing so and the user is redirected to the requested app.
</p>
<p>
With VCs/VPs it is possible to exchange personal information in a verifiable and data-conserving manner.
In most use cases they simplify the disclosure of this information during for example a registration process.
Using VCs/VPs the user must not input the information by hand but only has to send a VP.
The service requesting the information could rely on them because they are signed by an [=issuer=] (only if the service trusts the [=issuer=]).
</p>
<p>
Additionally, this proposal enables every service provider that has its own app including credential and their exchange functionality without relying on a central [=identity=] [=wallet=] to store the issued credential.
From the user's perspective, he or she only has to rely on the [=issuer=] and its application, not in an intermediary [=wallet=] service or app for storing the credentials.
</p>
</section>
<section class="informative">
<h2>Security Considerations</h2>
<section>
<h2>Perfect Forward Secrecy</h2>
<p>
Because HTTPS is used to transport [=credential requests=] and [=credential responses=] between two applications, [=perfect forward secrecy=] (PFS) is substantial in many of the available implementations.
Note, that this applies only to the network connection while [=credential requests=] or [=credential responses=] are made.
The including VP and its VCs signed by the [=holder=] and one or more [=issuers=] are unaffected.
When using QR codes for a [=credential request=], this security requirement is obsolete.
</p>
<p>
Since [=Transport Layer Security=] (TLS) secures the communication channel before any user data is transmitted, it ensures that the information transferred within a URL is also protected (e.g. the query).
</p>
</section>
<section id="trust">
<h2>Trust</h2>
<p>
Because HTTPS is used to transport [=credential requests=] and [=credential responses=] between two applications, the underlying [=public key infrastructure=] (PKI) of TLS (X.509) [[rfc5280]] builds trust for this connection, in that way, that the communication endpoints are the intended ones.
This is helpful to identify the applications that want to do a credential exchange.
</p>
<p>
Since DIDs are out of trust HTTPS can be used to map a DID to a domain.
This is most useful for [=issuers=] since larger institutions usually use TLS certificates these days anyway.
The [[[didconfiguration]]] specification describes an approach that makes use of Well-Known URIs [[rfc8615]].
</p>
</section>
</section>