forked from w3c-ccg/webkms
-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.html
427 lines (377 loc) · 16.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
419
420
421
422
423
424
425
426
427
<!DOCTYPE html>
<html>
<head>
<title>WebKMS v0.1</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: "webkms",
// subtitle for the spec
subtitle: "Cryptographic Key Management Systems for the Web",
// 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: "CG-DRAFT",
//previousPublishDate: "2019-02-08",
// 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/webkms/",
includePermalinks: false,
// if there a publicly available Editor's Draft, this is the link
edDraftURI: "https://digitalbazaar.github.io/webkms/",
// 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: "https://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://digitalbazaar.com/",
company: "Digital Bazaar", companyURL: "https://digitalbazaar.com/"},
{ name: "Manu Sporny", url: "https://digitalbazaar.com/",
company: "Digital Bazaar", companyURL: "https://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;
}
</style>
</head>
<body>
<section id='abstract'>
<p>
Cryptographic authentication systems enable machines, individuals, and
organizations to more securely interact with one another. These systems often
use public-private key cryptography or encryption mechanisms in order to
manage cryptographic material as well as operations utilizing that material.
This specification provides a common data model and interface for interacting
with these systems enabling one to perform secure cryptographic operations
such as keypair creation, wrapping and unwrapping, signing, encrypting,
and decrypting.
</p>
</section>
<section id='sotd'>
<p>
Comments regarding all aspects of this document are welcome.
Please file issues
directly on <a href="https://github.com/digitalbazaar/webkms/issues/">GitHub</a>,
or send them to
<a href="mailto:[email protected]">[email protected]</a>
(<a href="mailto:[email protected]?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>
Cryptographic authentication systems enable machines, individuals, and
organizations to more securely interact with one another. These systems often
use public-private key cryptography or encryption mechanisms in order to manage
cryptographic material as well as operations utilizing that material. There are
a variety of these sorts of cryptographic systems in use today, sometimes
referred to as Key Management Systems. While many of these sorts of systems
exist, there is no common interface for accessing and using these systems.
</p>
<p>
The creation of a common interface for accessing Key Management Systems would
enable software to be written once to interact with these systems such that
systems with different implementations and properties could be switched
without affecting the client software that utilizes such systems. A common API
would shift the burden of interacting with each implementation to the vendors
of those systems, while eliminating the burden for application developers.
</p>
<p>
While there are a variety of proprietary enterprise grade Key Management Systems today
that would benefit from a common interface, personal Key Management Systems
such as those created through the Fast Identity Online (FIDO) initiative could
also benefit.
</p>
<p>
If the interface is provided as a Web-based interface, then Web-based
applications could be written against such an API. Similarly, Web-based
applications could provide choice in Key Management Systems -- potentially
allowing customers to bring their own Key Management Systems with them just as
they bring their own devices today.
</p>
<section class="informative">
<h3>Ecosystem Overview</h3>
<p>
This section describes the roles of the core actors and the relationships
between them in an ecosystem where this specification is expected
to be useful. A role is an abstraction that might be implemented in many
different ways. The separation of roles suggests likely interfaces and
protocols for standardization. The following roles are introduced in this
specification:
</p>
<dl>
<dt>controller</dt>
<dd>
A role an <a>entity</a> might perform by demonstrating control of
cryptographic key material in order to authenticate itself with a system.
</dd>
<dt>key management client</dt>
<dd>
A role an <a>entity</a> might perform by communicating with a Key Management
System.
</dd>
<dt>key management system</dt>
<dd>
A role an <a>entity</a> might perform by providing an interface to
the management of cryptographic material and the execution of cryptographic
operations.
</dd>
</dl>
</section>
<section class="informative">
<h3>Use Cases and Requirements</h3>
<p>
The following use cases outline a number of key scenarios that readers might
find useful:
</p>
<ul>
<li>
Manage Keystore - Edwin would like to enable his application to create
and delete keystores. Each keystore will have one or more controllers that
are capable of controlling the keystore, and keys within the keystore.
Controllers of the individual keys might not be the same as the controllers
for the keystore.
</li>
<li>
Sign Data - Padthmini instructs her application to digitally sign a document
using a hardware-backed cryptographic key. Her application forwards the
authorized request to a hardware-backed key management system that performs the
operation and returns the digital signature.
</li>
<li>
Verify Data - Haneda has received a document with a digital signature. He
uses an application to verify the digital signature. The application provides
the signed cryptographic hash, the public key used to sign the hash, and
the digital signature to verify. The key management system responds to the
request noting the status of the verification.
</li>
<li>
Wrap and Unwrap Key - Mimi would like to exchange messages with BanPo without
worrying about people that might intercept the messages. Mimi uses her
application to set up a secure communication link to BanPo. The application
requests the creation of an encryption key that is then wrapped and encrypted
in a way that only BanPo can extract. The wrapped encryption key is sent to
BanPo's application, which then unwraps and stores the encryption key. The
exchange is done in such a way where neither Mimi, nor BanPo, nor any
intermediaries have access to the encryption key (only the keystores can
see and use the encryption key).
</li>
<li>
Encrypt and Decrypt Data - Mimi would like to exchange messages with BanPo
without worrying about people that might intercept the messages. They have
already exchanged symmetric encryption keys. Mimi uses her application to
encrypt a message, which is then sent to BanPo. BanPo uses his application
to decrypt the message. This is done without BanPo having access to the
decryption key, only the keystore has access to the decryption key.
</li>
<li>
Bring Your Own Keystore - Kuwele would like to write his application to use a
variety of 3rd party key management systems without having to manage drivers for
each key management system. He finds a set of keystores using a common API and
writes his application to use the common API. As new key management systems
support the common API, he is able to easily integrate these new systems.
</li>
</ul>
<p>
As a result of documenting and analyzing the use cases, the following
desirable ecosystem characteristics were identified for this specification:
</p>
<ul>
<li>
A standard data model for Web-based Key Management Systems MUST be defined.
</li>
<li>
A standard HTTP API MUST be defined.
</li>
<li>
Common key operations such as create, sign, verify, wrap, unwrap, encrypt,
and decrypt MUST be supported.
</li>
<li>
Utilizing private key material MUST be supported without the need to
exfiltrate the key.
</li>
<li>
Executing cryptographic functions MUST be delegatable on a per-key basis.
</li>
<li>
Each keystore MUST be able to support one or more controller.
</li>
</ul>
</section>
<section id="conformance" class="normative">
<p>
TBD
</p>
</section>
</section>
<section class="informative">
<h2>Terminology</h2>
<div data-include="./terms.html"
data-oninclude="restrictReferences">
</div>
</section>
<section class="informative">
<h2>Core Concepts</h2>
<p>
There is a relatively small set of common cryptographic operations that Key
Management Systems provide. These operations include: generate, wrap, unwrap,
sign, verify, encrypt, and decrypt. These cryptographic operations can be
thought of as <em>functions</em> that operate on <em>objects</em>, in this case
cryptographic keys, in a remote execution environment.
</p>
<p class="issue">
Ensure that the list is updated from
<a href="https://github.com/digitalbazaar/web-kms-switch/tree/http-sig/lib/schemas">here</a>.
</p>
<p>
The Authorization Capabilities for Linked Data [ZCAP-LD] specification, also
know as ZCAPs, outlines how remote execution environments can be manipulated by
demonstrating cryptographic control of <em>functions</em> and <em>objects</em>.
The ZCAP-LD specification enables one to grant authority to remote clients to
call functions on specific objects. This technology enables a Key Management
System to provide a Web-based API that enables clients to create keys and
execute cryptographic operations using those keys by invoking ZCAPs.
</p>
<p>
The WebKMS API enables clients to create keystores, a type of <em>object</em>,
that they control. That is, the client is the controller of the keystore.
The client may also generate a key, another type of <em>object</em>, and
associate it with a keystore. Each keystore is identified by a URI. In
addition, the controller of a keystore can be changed to enable the transfer
of keys without requiring the exfiltration of the key. Other entities can
also be added as controllers of the keystore such that multiple parties might
control the keystore without having access to the raw key material.
</p>
<p>
Each key in the keystore has an associated set of <em>functions</em> according
to the type of key that it is. Examples of key types include keys used for
performing asymmetric cryptographic operations such as digital signatures and
keys used for performing symmetric cryptographic operations such as
encryption and decryption. These <em>functions</em> can be remotely executed
via the use of ZCAPs such that the cryptographic key material never
needs to be exfiltrated in order to use the key. In many hardware-backed
cryptographic key management systems, the exfiltration of keys is not
supported and the system itself is hardened against tampering with the
intent to exfiltrate the keys.
</p>
<p>
In order to execute a <em>function</em> on a key, a <code>KmsOperation</code>
of a specific type can be applied to the key, including a ZCAP that
invokes the capability that demonstrates the authorization to perform the
operation. For example, a KmsOperation might be constructed and POSTed to
the key URL with an invocation of a ZCAP performed via HTTP Signatures.
</p>
</section>
<section class="normative">
<h2>Data Model</h2>
</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>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>
</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>
</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>
</section>
</body>
</html>