-
Notifications
You must be signed in to change notification settings - Fork 5
/
Copy pathindex.html
418 lines (359 loc) · 14.7 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
<!DOCTYPE html>
<html>
<head>
<title>Ecdsa Secp256k1 Signature 2019</title>
<meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
<!--
=== NOTA BENE ===
For the three scripts below, if your spec resides on dev.w3 you can check them
out in the same tree and use relative links so that they'll work offline,
-->
<script src='//www.w3.org/Tools/respec/respec-w3c-common' 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: "lds-ecdsa-secp256k1-2019",
// if you wish the publication date to be other than today, set this
// publishDate: "2009-08-06",
// if there is a previously published draft, uncomment this and set its YYYY-MM-DD date
// and its maturity status
// previousPublishDate: "1977-03-15",
// previousMaturity: "WD",
// if there a publicly available Editor's Draft, this is the link
edDraftURI: "https://w3c-ccg.github.io/lds-ecdsa-secp256k1-2019/",
// if this is a LCWD, uncomment and set the end of its review period
// lcEnd: "2009-08-05",
// if you want to have extra CSS, append them to this list
// it is recommended that the respec.css stylesheet be kept
//extraCSS: ["spec.css", "prettify.css"],
// editors, add as many as you like
// only "name" is required
editors: [
{ name: "Orie Steele", url: "https://transmute.industries/",
company: "Transmute Industries, Inc.", companyURL: "https://transmute.industries" }
],
// 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: "Orie Steele", url: "https://transmute.industries/",
company: "Transmute Industries, Inc.", companyURL: "https://transmute.industries/" }
],
// extend the bibliography entries
//localBiblio: webpayments.localBiblio,
// name of the WG
wg: "W3C Digital Verification Community Group",
// URI of the public WG page
wgURI: "https://www.w3.org/community/digital-verification/",
// name (with the @w3c.org) of the public mailing to which comments are due
wgPublicList: "public-digital-verification",
otherLinks: [{
key: "Source control",
data: [{
value: "https://github.com/w3c-ccg/lds-ecdsa-secp256k1-2019/",
href: "https://github.com/w3c-ccg/lds-ecdsa-secp256k1-2019/"
}]
}, {
key: "Issue Tracker",
data: [{
value: "https://github.com/w3c-ccg/lds-ecdsa-secp256k1-2019/issues/",
href: "https://github.com/w3c-ccg/lds-ecdsa-secp256k1-2019/issues/"
}]
}],
// URI of the patent status for this WG, for Rec-track documents
// !!!! IMPORTANT !!!!
// This is important for Rec-track documents, do not copy a patent URI from a random
// document unless you know what you're doing. If in doubt ask your friendly neighbourhood
// Team Contact.
wgPatentURI: "",
maxTocLevel: 4,
/*preProcess: [ webpayments.preProcess ],
alternateFormats: [ {uri: "diff-20111214.html", label: "diff to previous version"} ],
*/
localBiblio: {
"RDF-DATASET-CANONICALIZATION": {
title: "RDF Dataset Canonicalization",
href: "https://json-ld.github.io/rdf-dataset-canonicalization/spec/",
authors: ["David Longley", "Manu Sporny"],
status: "Draft Community Group Report",
publisher: "JSON-LD Community Group"
},
"SECURITY-VOCABULARY": {
title: "Security Linked Data Vocabulary",
href: "https://web-payments.org/vocabs/security",
authors: ["Manu Sporny","David Longley"],
status: "Draft Community Group Report",
publisher: "Web Payments Community Group"
},
"LD-SIGNATURES": {
title: "Linked Data Signatures 1.0",
href: "https://w3c-ccg.github.io/ld-signatures/",
authors: ["David Longley", "Manu Sporny"],
status: "Draft Community Group Report",
publisher: "Digital Verification Community Group"
}
}
};
</script>
</head>
<body>
<section id='abstract'>
<p>
This specification describes the Ecdsa Secp256k1 Signature created in 2019 for the
Linked Data Signatures specification.
</p>
</section>
<section id='sotd'>
<p>
This is an experimental specification and is undergoing regular revisions. It
is not fit for production deployment.
</p>
</section>
<section>
<h2>Introduction</h2>
<p>
This specification describes the Ecdsa Secp256k1 Signature created in 2019 for the
Linked Data Signatures [[LD-SIGNATURES]] specification. It uses the RDF
Dataset CANONICALIZATION Algorithm [[RDF-DATASET-CANONICALIZATION]] to transform the
input document into its canonical form. It uses SHA-256 [[RFC6234]] as the
<a>message digest algorithm</a> and ES256K JWS with Unencoded Payload Option defined in [[rfc7797]] as the <a>signature algorithm</a>.
</p>
</section>
<section>
<h2>Terminology</h2>
<p>
The following terms are used to describe concepts involved in the
generation and verification of the Linked Data Signature 2019
<a>signature suite</a>.
</p>
<dl>
<dt><dfn>signature suite</dfn></dt>
<dd>
A specified set of cryptographic primitives typically consisting of
a canonicalization algorithm, a message digest algorithm, and a signature
algorithm that are bundled together by cryptographers for developers
for the purposes of safety and convenience.
</dd>
<dt><dfn>canonicalization algorithm</dfn></dt>
<dd>
An algorithm that takes an input document that has more than one possible
representation and always transforms it into a canonical form. This process is
sometimes also called CANONICALIZATION.
</dd>
<dt><dfn>message digest algorithm</dfn></dt>
<dd>
An algorithm that takes an input message and produces a cryptographic
output message that is often many orders of magnitude smaller than the
input message. These algorithms are often 1) very fast, 2)
non-reversible, 3) cause the output to change significantly when even one
bit of the input message changes, and 4) make it infeasible to find two
different inputs for the same output.
</dd>
<dt><dfn>signature algorithm</dfn></dt>
<dd>
An algorithm that takes an input message and produces an output value where the
receiver of the message can mathematically verify that the message has not
been modified in transit and came from someone possessing a particular secret.
</dd>
</dl>
<section>
<h2>Linked Data Signature Terms</h2>
<p>
The following terms are used to describe concepts involved in the
generation and verification of signatures according to EcdsaSecp256k1Signature2019.
</p>
<dl>
<dt><dfn>EcdsaSecp256k1Signature2019</dfn></dt>
<dd>
A JSON-LD Document has been signed with EcdsaSecp256k1Signature2019,
when it contains a proof field, and that proof field contains a jws, as
is defined by this spec.
</dd>
<dt><dfn>EcdsaSecp256k1VerificationKey2019</dfn></dt>
<dd>
A secp256k1 public key. If the key is embedded in a controller with property name publicKeyJwk, the key must be a valid JWK. If the key is embeded as publicKeyHex, it must be a compressed public key, and must be converted to JWK before being used to verify signatures according to JWS.
</dd>
</dl>
</section>
</section>
<section>
<h2>Key Format</h2>
<section>
<h2>Examples</h2>
<p>
JWK encoded public key example:
</p>
<pre class="example highlight">
{
"@context": ["https://w3id.org/security/v1"],
"id": "did:example:123456789abcdefghi#keys-1",
"type": "EcdsaSecp256k1VerificationKey2019",
"controller": "did:example:123456789abcdefghi",
"expires": "2017-02-08T16:02:20Z",
"publicKeyJwk" : {
"crv": "secp256k1",
"kid": "JUvpllMEYUZ2joO59UNui_XYDqxVqiFLLAJ8klWuPBw",
"kty": "EC",
"x": "dWCvM4fTdeM0KmloF57zxtBPXTOythHPMm1HCLrdd3A",
"y": "36uMVGM7hnw-N6GnjFcihWE3SkrhMLzzLCdPMXPEXlA",
}
}
</pre>
<p>Note: The <code>publicKeyJwk</code> property contains a key in JWK format.</p>
<p>
Hex encoded public key example:
</p>
<pre class="example highlight">
{
"@context": ["https://w3id.org/security/v1"],
"id": "did:example:123456789abcdefghi#keys-1",
"type": "EcdsaSecp256k1VerificationKey2019",
"controller": "did:example:123456789abcdefghi",
"expires": "2017-02-08T16:02:20Z",
"publicKeyHex" : "034ee0f670fc96bb75e8b89c068a1665007a41c98513d6a911b6137e2d16f1d300"
}
</pre>
<p>Note: The <code>publicKeyHex</code> MUST be converted to publicKeyJwk before it can be used to verify JWS.</p>
<p>Note: The <code>publicKeyHex</code> property contains a hex encoded compressed secp256k1 public key.</p>
</section>
</section>
<section>
<h2>Signature Format</h2>
<p>
The 2019 Ecdsa Secp256k1 Signature <a>signature suite</a> MUST be used in
conjunction with the signing and verification algorithms in the
Linked Data Signatures [[LD-SIGNATURES]] specification. The suite consists of
the following algorithms:
</p>
<table class="simple">
<thead>
<th>Parameter</th>
<th>Value</th>
<th>Specification</th>
</thead>
<tbody>
<tr>
<td>canonicalizationAlgorithm</td>
<td>https://w3id.org/security#GCA2015</td>
<td>[[RDF-DATASET-CANONICALIZATION]]</td>
</tr>
<tr>
<td>digestAlgorithm</td>
<td>https://www.ietf.org/assignments/jwa-parameters#SHA256</td>
<td>[[RFC6234]]</td>
</tr>
<tr>
<td>signatureAlgorithm</td>
<td><a href='https://tools.ietf.org/id/draft-jones-webauthn-secp256k1-00.html'>ES256K</a></td>
<td>[[rfc6979]]</td>
</tr>
</tbody>
</table>
<section>
<h2>Modification to Algorithms</h2>
<p>
This signature suite uses ECDSA over secp256k1 as described in [[rfc6979]].
The signature algorithm relies on
JWK encoded keys, and this flexibility supports integration with JOSE.
The steps to construct and verify the digital signature are defined below.
<p>
<section>
<h3>Modifications to Signature Algorithm</h3>
<p>
The <var>digital signature algorithm</var> defined:
Signature Algorithm takes <var>tbs</var>, a <var>privateKey</var>,
and </var><var>options</var> as inputs and produces a
<var>signatureValue</var> as output.
</p>
<ol class="algorithm">
<li>
Take <var>tbs</var>, which is the data to be signed, an private key and options dictionary as input to the signature suite.
</li>
<li>
Perform the
<a href="https://tools.ietf.org/html/draft-ietf-cose-webauthn-algorithms-01#section-3.2">sign</a> digital signature algorithm specified of
[[rfc7797]] and return the result encoded as <em>jws</em>.
</li>
<li>
The <em>jws</em> will contain ".." per [[rfc7797]]:
<code>WpQlDT-K5bSPQwFkEKszo0XE1esubvol3K6UMe_...</code>.
</li>
</ol>
</section>
<section>
<h3>Modifications to Signature Verification Algorithm</h3>
<p>
The <var>digital signature algorithm</var> defined
Signature Verification Algorithm takes the value to be verified,
<em>tbv</em>, the <em>public key</em> to the signature algorithm
and returns a boolean value.
</p>
<ol class="algorithm">
<li>
Take <var>tbv</var> and perform the
<a href="https://tools.ietf.org/html/rfc7797">Sign</a>
digital signature verification algorithm specified in <a href="https://tools.ietf.org/html/draft-ietf-cose-webauthn-algorithms-01#section-3.2">ES26K JOSE DRAFT</a>. If the result is a valid signature, return
<code>true</code>, otherwise return <code>false</code>.
</li>
</ol>
</section>
</section>
<section>
<h2>Security Considerations</h2>
<p>
The following section describes security considerations that developers
implementing this specification should be aware of in order to create secure
software.
</p>
<div class="issue">TODO: We need to add a complete list of security
considerations.</div>
<ol class="security_considerations">
<li>
This Signature Suite relies on the security and assumptions made by ECDSA over secp256k1.
We assume specifcally that sign and verify are implemented safely.
</li>
</ol>
</section>
<section class="appendix">
<h2>Examples</h2>
<p>
A simple example:
</p>
<pre class="example highlight">
{
"@context": "https://w3id.org/security/v2",
"http://schema.org/action": "AuthenticateMe",
"proof": {
"challenge": "abc",
"created": "2019-01-16T20:13:10Z",
"domain": "example.com",
"proofPurpose": "authentication",
"verificationMethod": "https://example.com/i/alice/keys/2",
"type": "EcdsaSecp256k1Signature2019",
"jws": "eyJhbGciOiJFUzI1NksiLCJiNjQiOmZhbHNlLCJjcml0IjpbImI2NCJdfQ..QgbRWT8w1LJet_KFofNfz_TVs27z4pwdPwUHhXYUaFlKicBQp6U1H5Kx-mST6uFvIyOqrYTJifDijZbtAfi0MA"
}
}
</pre>
<p>
An example using DIDs:
</p>
<pre class="example highlight">
{
"@context": "https://w3id.org/security/v2",
"http://schema.org/action": "AuthenticateMe",
"proof": {
"challenge": "abc",
"created": "2019-01-16T20:13:10Z",
"domain": "example.com",
"proofPurpose": "authentication",
"verificationMethod": "did:example:123#kid=JUvpllMEYUZ2joO59UNui_XYDqxVqiFLLAJ8klWuPBw",
"type": "EcdsaSecp256k1Signature2019",
"jws": "eyJhbGciOiJFUzI1NksiLCJiNjQiOmZhbHNlLCJjcml0IjpbImI2NCJdfQ..QgbRWT8w1LJet_KFofNfz_TVs27z4pwdPwUHhXYUaFlKicBQp6U1H5Kx-mST6uFvIyOqrYTJifDijZbtAfi0MA"
}
}
</pre>
</section>
</body>
</html>