-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathindex.html
279 lines (254 loc) · 10.4 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
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<title>Verifiable Credentials with JSON Web Signatures</title>
<script src="https://www.w3.org/Tools/respec/respec-w3c" class="remove" defer></script>
<script class="remove">
var respecConfig = {
specStatus: "unofficial",
editors: [
{
name: "Orie Steele",
company: "Transmute",
companyURL: "https://www.transmute.industries/",
w3cid: 109171,
},
{
name: "Michael Prorock",
company: "mesur.io",
companyURL: "https://mesur.io/",
w3cid: 130636,
},
],
github: "transmute-industries/vc-jws",
shortName: "vc-jws",
// group: "vc",
localBiblio: {
// OAS: {
// title: "OpenAPI Specification",
// href: "https://swagger.io/specification/",
// authors: [
// "Darrel Miller",
// "Jeremy Whitlock",
// "Marsh Gardiner ",
// "Mike Ralphson",
// "Ron Ratovsky",
// "Uri Sarid",
// ],
// status: "unofficial",
// publisher: "OpenAPI Initiative",
// },
},
xref: {
specs: ["DID-CORE", "VC-DATA-MODEL", "JSON-LD"],
profile: "web-platform",
},
otherLinks: [
{
key: "Related Documents",
data: [
{
value: "Decentralized Identifiers (DIDs) v1.0",
href: "https://www.w3.org/TR/did-core/",
},
{
value: "Verifiable Credentials Data Model v1.1",
href: "https://www.w3.org/TR/vc-data-model/",
},
],
},
],
};
</script>
</head>
<body>
<section id="abstract">
<p>
This specification defines new
<a data-cite="VC-DATA-MODEL#proof-formats">proof format</a>
for use with
<a data-cite="VC-DATA-MODEL#credentials">Verifiable Credentials</a>
</p>
<p>
In addition to meeting the requirements defined in [[RFC7515]]. We
introduce some additional constraints to eliminate optionality and
improve interoperability between implementations.
</p>
</section>
<section id="sotd">
<!-- This is required. -->
</section>
<section>
<h2>Introduction</h2>
<p>
<a data-cite="VC-DATA-MODEL#credentials">Verifiable Credentials </a> defines
a JSON Web Token (JWT) proof format which requires the issuer and verifier to map
JWT <a data-cite="RFC7519#section-4.1">Registered Claim Names</a> and the
<a data-cite="VC-DATA-MODEL#terminology">Verifiable Credentials Terminology</a>.
</p>
<p>
This mapping process can be complex, and requires problematic operations such as type
conversions for datetime fields. As a result of this complexity, this mapping can be
implemented differently by <a data-cite="VC-DATA-MODEL#issuer">issuers</a>
and <a data-cite="VC-DATA-MODEL#dfn-verifier">verifiers</a> which often leads to cases
where to interoperability is not present, or unexpected security issues are introduced.
</p>
<p>
This specification introduces a <a data-cite="RFC7519#section-5.2">(Content Type) Header Parameter</a>
that is used to define the content type for <a data-cite="VC-DATA-MODEL#credentials">Verifiable Credentials</a>
that utilize <a data-cite="RFC7515#section-3.1">JSON Web Signatures</a> to provide signing and
verification in a <a data-cite="VC-DATA-MODEL#credentials">Verifiable Credential</a>.
</p>
<p>
This approach, of utilizing to a <a data-cite="RFC7519#section-5.2">(Content Type) Header Parameter</a>
to specify a discrete set of mappings and expected behaviors in translation between formats
or representations of data is used commonly in other groups to secure arbitrary content using COSE
and other document and data encoding formats. This approach is extensible to other data encodings
and may be extended to provide a mechanism for use of CBOR encodings for <a data-cite="VC-DATA-MODEL#credentials">Verifiable Credentials</a>.
</p>
</section>
<section>
<h2>Producing</h2>
<p>This specification uses normal approaches to the production and consumption of a JWS. For additional
details, please see the full breakdown of the process in <a data-cite="RFC7515#section-5">Producing and Consuming JWSs</a>.</p>
<p>Specifically related to use of JWS with VCs the following normative requirements MUST
be considered in production of a JWS.</p>
<ul>
<li>
<p>
<a data-cite="RFC7515#section-4.1.4">kid</a> MUST be present in the
<a data-cite="RFC7515#section-4">JOSE Header</a>.
</p>
<p>
The value of <a data-cite="RFC7515#section-4.1.4">kid</a> MUST be
one of the following:
<ul>
<li>
<p>
An <a data-cite="DID-CORE#did-url-syntax">absolute DID URL</a> that
<a data-cite="DID-CORE#did-url-dereferencing">dereferences</a> to a
<a data-cite="DID-CORE#verification-material">verification method</a>
with public key material in <a data-cite="DID-CORE#dfn-publickeyjwk">publicKeyJwk</a>.
</p>
</li>
<li>
<p>
An <a data-cite="DID-CORE#relative-did-urls">relative DID URL</a> that
<strong>when combined with <code>iss</code></strong>
<a data-cite="DID-CORE#did-url-dereferencing">dereferences</a> to a
<a data-cite="DID-CORE#verification-material">verification method</a>
with public key material in <a data-cite="DID-CORE#dfn-publickeyjwk">publicKeyJwk</a>.
</p>
</li>
<li>
<p>
If <a data-cite="RFC7515#section-4.1.4">kid</a> is a <a data-cite="DID-CORE#relative-did-urls">relative
DID URL</a> in the
<a data-cite="RFC7515#section-4">JOSE Header</a>, then
<a data-cite="RFC7515#section-4.1.4">iss</a> MUST be present in the
<a data-cite="RFC7515#section-4">JOSE Header</a>.
</p>
</li>
<li>
<p>
The <a data-cite="DID-CORE#dfn-publickeyjwk">publicKeyJwk</a> is expected to verify the JWS.
</p>
</li>
</ul>
</p>
</li>
<li>
<p>
<a data-cite="RFC7519#section-5.3">iss</a> MAY be present in <a data-cite="RFC7515#section-4.1">JOSE Header</a>,
and MUST match the <a data-cite="DID-CORE#verification-methods">controller</a> of the dereferenced <a data-cite="DID-CORE#dfn-publickeyjwk">publicKeyJwk</a>.
</p>
</li>
<li>
<p>
<a data-cite="RFC7515#section-4.1.1">alg</a> MUST be present in <a data-cite="RFC7515#section-4.1">JOSE Header</a>,
and MUST match the <a data-cite="RFC7517#section-4.4">alg</a> in the dereferenced <a data-cite="DID-CORE#dfn-publickeyjwk">publicKeyJwk</a>.
</p>
</li>
<li>
<p>
<a data-cite="RFC7519#section-5.2">content type (cty)</a> MUST be present in <a data-cite="RFC7515#section-4.1">JOSE Header</a>,
and MUST be <code>application/credential+ld+json</code>.
</p>
</li>
<aside
class="example"
title="Using content type to identify payload types."
>
<p>Source: <a data-cite="rfc7517#appendix-C.2">RFC7517</a></p>
<pre class="example" title="">
{
"alg":"PBES2-HS256+A128KW",
"p2s":"2WCTcJZ1Rvd_CJuJripQ1w",
"p2c":4096,
"enc":"A128CBC-HS256",
"cty":"jwk+json"
}
</pre>
</aside>
<li>
<p>
The <a data-cite="RFC7515#section-2">JWS Payload</a> MUST be a sequence of octets representing the UTF-8 JSON
encoding
of the <a data-cite="VC-DATA-MODEL#dfn-credential">credential</a>.
</p>
</li>
</ul>
</section>
<section>
<h2>Consuming</h2>
<p>This specification uses normal approaches to the consumption of a JWS. For additional
details, please see the full breakdown of the process in <a data-cite="RFC7515#section-5">Producing and Consuming JWSs</a>.</p>
<p>As a part of ensuring interoperability with VCs secured in the manner described in this specification,
resolution of public key material must be considered, as a verifier may not have access to the public key.</p>
<p>
In order to verify a <a data-cite="VC-DATA-MODEL#credentials">Verifiable Credential</a> using a JWS proof,
the public key associated with the signature needs to be obtained.
If the verifier does not already have the public key, it can be obtained through the following process:
</p>
<ul>
<li>
Decode the <a data-cite="RFC7515#section-4">JOSE Header</a>.
</li>
<li>
Construct an <a data-cite="DID-CORE#did-url-syntax">absolute DID URL</a>
from the <a data-cite="RFC7515#section-4.1.4">kid</a> and <a data-cite="RFC7515#section-4.1.4">iss</a> if iss is present.
</li>
<li>
<a data-cite="DID-CORE#did-url-dereferencing">Dereferences</a> the <a data-cite="DID-CORE#did-url-syntax">absolute DID URL</a>
to obtain a <a data-cite="DID-CORE#verification-material">verification method</a> which contains a <a data-cite="DID-CORE#dfn-publickeyjwk">publicKeyJwk</a>.
</li>
<li>
Follow the process for <a data-cite="RFC7515#section-5.2">Message Signature or MAC Validation</a>.
</li>
</ul>
</section>
<section>
<h2>Example</h2>
<aside
class="example"
title="A credential for a University Degree"
>
<p>An <code>application/credential+ld+json</code> example that will have an external proof.</p>
<pre data-include="./credential.json" data-include-format="json"></pre>
</aside>
<aside
class="example"
title="A verifiable credential for a University Degree with an external proof"
>
<p>This verifiable credential is encoded, decode it with <a href="https://jwt.io/">jwt.io</a>.</p>
<pre data-include="./verifiable-credential.jws" data-include-format="text"></pre>
</aside>
</section>
<section id="conformance">
<p>
This is required for specifications that contain normative material.
</p>
</section>
</body>
</html>