-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathindex.html
911 lines (863 loc) · 36.1 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
<!DOCTYPE html>
<html>
<head>
<title>WebKMS v0.7</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' 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: "UNOFFICIAL",
previousPublishDate: "2020-12-29",
// extend the bibliography entries
localBiblio: ccg.localBiblio,
doJsonLd: true,
github: "https://github.com/w3c-ccg/webkms/",
includePermalinks: false,
// if there a publicly available Editor's Draft, this is the link
edDraftURI: "https://w3c-ccg.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
group: "credentials",
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 more secure interactions among
machines, individuals, and organizations. These systems often use public-private
key cryptography or encryption mechanisms to manage both cryptographic material
and 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 on keypairs such as creating, wrapping, 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/w3c-ccg/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">
</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/master/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>
<h2>HTTP API</h2>
<dl>
<dt><a href="#webkms_generateKey">generateKey(options)</a> ⇒ <code><map></code></dt>
<dd>
<p>Generates a new cryptographic key in the keystore.</p>
</dd>
<dt><a href="#webkms_getKeyDescription">getKeyDescription(options)</a> ⇒ <code><map></code></dt>
<dd>
<p>Gets the key description for the given key ID.</p>
</dd>
<dt><a href="#webkms_revokeCapability">revokeCapability(options)</a> ⇒ <code><map></code></dt>
<dd>
<p>Store a capability revocation.</p>
</dd>
<dt><a href="#webkms_wrapKey">wrapKey(options)</a> ⇒ <code><string></code></dt>
<dd>
<p>Wraps a cryptographic key using a key encryption key (KEK).</p>
</dd>
<dt><a href="#webkms_unwrapKey">unwrapKey(options)</a> ⇒ <code><(Uint8Array|null)></code></dt>
<dd>
<p>Unwraps a cryptographic key using a key encryption key (KEK).</p>
</dd>
<dt><a href="#webkms_sign">sign(options)</a> ⇒ <code><string></code></dt>
<dd>
<p>Signs some data. Note that the data will be sent to the server, so if
this data is intended to be secret it should be hashed first. However,
hashing the data first may present interoperability issues so choose
wisely.
</p>
</dd>
<dt><a href="#webkms_verify">verify(options)</a> ⇒ <code><boolean></code></dt>
<dd>
<p>Verifies some data. Note that the data will be sent to the server, so if
this data is intended to be secret it should be hashed first. However,
hashing the data first may present interoperability issues so choose
wisely.
</p>
</dd>
<dt><a href="#webkms_deriveSecret">deriveSecret(options)</a> ⇒ <code><Uint8Array></code></dt>
<dd>
<p>Derives a shared secret via the given peer public key, typically for use
as one parameter for computing a shared key. It should not be used as
a shared key itself, but rather input into a key derivation function (KDF)
to produce a shared key.
</p>
</dd>
<dt><a href="#webkms_enableCapability">enableCapability(options)</a> ⇒ <code><map></code></dt>
<dd>
<p>Stores a delegated authorization capability, enabling it to be invoked by
its designated invoker.
</p>
</dd>
<dt><a href="#webkms_disableCapability">disableCapability(options)</a> ⇒ <code><boolean></code></dt>
<dd>
<p>Removes a previously stored delegated authorization capability, preventing
it from being invoked by its designated invoker.
</p>
</dd>
<dt><a href="#webkms_createKeystore">createKeystore(options)</a> ⇒ <code><map></code></dt>
<dd>
<p>Creates a new keystore using the given configuration.</p>
</dd>
<dt><a href="#webkms_getKeystore">getKeystore(options)</a> ⇒ <code><map></code></dt>
<dd>
<p>Gets the configuration for a keystore by its ID.</p>
</dd>
<dt><a href="#webkms_findKeystore">findKeystore(options)</a> ⇒ <code><map></code></dt>
<dd>
<p>Finds the configuration for a keystore by its controller and reference ID.</p>
</dd>
</dl>
<section><h3 name="webkms_generateKey">generateKey(options) ⇒ <code><map></code></h3>
<p>Generates a new cryptographic key in the keystore.</p>
<p><strong>Response</strong>: HTTP 200 - <code><map></code> - The key description for the key.</p>
<table class="simple">
<thead>
<tr>
<th>Param</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>options.kmsModule</td>
<td><code>string</code></td>
<td>The KMS module to use.</td>
</tr>
<tr>
<td>options.type</td>
<td><code>string</code></td>
<td>The key type (e.g. 'AesKeyWrappingKey2019').</td>
</tr>
<tr>
<td>[options.capability]</td>
<td><code>string</code></td>
<td>The zCAP-LD authorization capability to use to authorize the invocation of this operation.</td>
</tr>
<tr>
<td>options.invocationSigner</td>
<td><code>map</code></td>
<td>An API with an <code>id</code> property and a <code>sign</code> function for signing a capability invocation.</td>
</tr>
</tbody>
</table>
<p><a name="webkms_getKeyDescription"></a></p>
</section><section><h3 id="getkeydescription-options-code-lt-map-gt-code-">getKeyDescription(options) ⇒ <code><map></code></h3>
<p>Gets the key description for the given key ID.</p>
<p><strong>Response</strong>: HTTP 200 - <code><map></code> - The key description.</p>
<table class="simple">
<thead>
<tr>
<th>Param</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>[options.keyId]</td>
<td><code>string</code></td>
<td>The ID of the key.</td>
</tr>
<tr>
<td>[options.capability]</td>
<td><code>string</code></td>
<td>The zCAP-LD authorization capability to use to authorize the invocation of this operation.</td>
</tr>
<tr>
<td>options.invocationSigner</td>
<td><code>map</code></td>
<td>An API with an <code>id</code> property and a <code>sign</code> function for signing a capability invocation.</td>
</tr>
</tbody>
</table>
<p><a name="webkms_revokeCapability"></a></p>
</section><section><h3 id="revokecapability-options-code-lt-map-gt-code-">revokeCapability(options) ⇒ <code><map></code></h3>
<p>Store a capability revocation.</p>
<p><strong>Response</strong>: HTTP 200 - <code><map></code> - Resolves once the operation completes.</p>
<table class="simple">
<thead>
<tr>
<th>Param</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>options.capabilityToRevoke</td>
<td><code>map</code></td>
<td>The capability to enable.</td>
</tr>
<tr>
<td>[options.capability]</td>
<td><code>string</code></td>
<td>The zcap authorization capability to use to authorize the invocation of this operation.</td>
</tr>
<tr>
<td>options.invocationSigner</td>
<td><code>map</code></td>
<td>An API with an <code>id</code> property and a <code>sign</code> function for signing a capability invocation.</td>
</tr>
</tbody>
</table>
<p><a name="webkms_wrapKey"></a></p>
</section><section><h3 id="wrapkey-options-code-lt-string-gt-code-">wrapKey(options) ⇒ <code><string></code></h3>
<p>Wraps a cryptographic key using a key encryption key (KEK).</p>
<p><strong>Response</strong>: HTTP 200 - <code><string></code> - The base64url-encoded wrapped key bytes.</p>
<table class="simple">
<thead>
<tr>
<th>Param</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>options.kekId</td>
<td><code>string</code></td>
<td>The ID of the wrapping key to use.</td>
</tr>
<tr>
<td>options.unwrappedKey</td>
<td><code>Uint8Array</code></td>
<td>The unwrapped key material as a Uint8Array.</td>
</tr>
<tr>
<td>[options.capability]</td>
<td><code>string</code></td>
<td>The zCAP-LD authorization capability to use to authorize the invocation of this operation.</td>
</tr>
<tr>
<td>options.invocationSigner</td>
<td><code>map</code></td>
<td>An API with an <code>id</code> property and a <code>sign</code> function for signing a capability invocation.</td>
</tr>
</tbody>
</table>
<p><a name="webkms_unwrapKey"></a></p>
</section><section><h3 id="unwrapkey-options-code-lt-uint8array-null-gt-code-">unwrapKey(options) ⇒ <code><(Uint8Array|null)></code></h3>
<p>Unwraps a cryptographic key using a key encryption key (KEK).</p>
<p><strong>Response</strong>: HTTP 200 - <code><(Uint8Array|null)></code> - Resolves to the unwrapped key material
or null if the unwrapping failed because the key did not match.
</p>
<table class="simple">
<thead>
<tr>
<th>Param</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>options.kekId</td>
<td><code>string</code></td>
<td>The ID of the unwrapping key to use.</td>
</tr>
<tr>
<td>options.wrappedKey</td>
<td><code>string</code></td>
<td>The wrapped key material as a base64url-encoded string.</td>
</tr>
<tr>
<td>[options.capability]</td>
<td><code>string</code></td>
<td>The zCAP-LD authorization capability to use to authorize the invocation of this operation.</td>
</tr>
<tr>
<td>options.invocationSigner</td>
<td><code>map</code></td>
<td>An API with an <code>id</code> property and a <code>sign</code> function for signing a capability invocation.</td>
</tr>
</tbody>
</table>
<p><a name="webkms_sign"></a></p>
</section><section><h3 id="sign-options-code-lt-string-gt-code-">sign(options) ⇒ <code><string></code></h3>
<p>Signs some data. Note that the data will be sent to the server, so if
this data is intended to be secret it should be hashed first. However,
hashing the data first may present interoperability issues so choose
wisely.
</p>
<p><strong>Response</strong>: HTTP 200 - <code><string></code> - The base64url-encoded signature.</p>
<table class="simple">
<thead>
<tr>
<th>Param</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>options.keyId</td>
<td><code>string</code></td>
<td>The ID of the signing key to use.</td>
</tr>
<tr>
<td>options.data</td>
<td><code>Uint8Array</code></td>
<td>The data to sign as a Uint8Array.</td>
</tr>
<tr>
<td>[options.capability]</td>
<td><code>string</code></td>
<td>The zCAP-LD authorization capability to use to authorize the invocation of this operation.</td>
</tr>
<tr>
<td>options.invocationSigner</td>
<td><code>map</code></td>
<td>An API with an <code>id</code> property and a <code>sign</code> function for signing a capability invocation.</td>
</tr>
</tbody>
</table>
<p><a name="webkms_verify"></a></p>
</section><section><h3 id="verify-options-code-lt-boolean-gt-code-">verify(options) ⇒ <code><boolean></code></h3>
<p>Verifies some data. Note that the data will be sent to the server, so if
this data is intended to be secret it should be hashed first. However,
hashing the data first may present interoperability issues so choose
wisely.
</p>
<p><strong>Response</strong>: HTTP 200 - <code><boolean></code> - <code>true</code> if verified, <code>false</code> if not.</p>
<table class="simple">
<thead>
<tr>
<th>Param</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>options.keyId</td>
<td><code>string</code></td>
<td>The ID of the signing key to use.</td>
</tr>
<tr>
<td>options.data</td>
<td><code>Uint8Array</code></td>
<td>The data to verify as a Uint8Array.</td>
</tr>
<tr>
<td>options.signature</td>
<td><code>string</code></td>
<td>The base64url-encoded signature to verify.</td>
</tr>
<tr>
<td>[options.capability]</td>
<td><code>string</code></td>
<td>The zCAP-LD authorization capability to use to authorize the invocation of this operation.</td>
</tr>
<tr>
<td>options.invocationSigner</td>
<td><code>map</code></td>
<td>An API with an <code>id</code> property and a <code>sign</code> function for signing a capability invocation.</td>
</tr>
</tbody>
</table>
<p><a name="webkms_deriveSecret"></a></p>
</section><section><h3 id="derivesecret-options-code-lt-uint8array-gt-code-">deriveSecret(options) ⇒ <code><Uint8Array></code></h3>
<p>Derives a shared secret via the given peer public key, typically for use
as one parameter for computing a shared key. It should not be used as
a shared key itself, but rather input into a key derivation function (KDF)
to produce a shared key.
</p>
<p><strong>Response</strong>: HTTP 200 - <code><Uint8Array></code> - The shared secret bytes.</p>
<table class="simple">
<thead>
<tr>
<th>Param</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>options.keyId</td>
<td><code>string</code></td>
<td>The ID of the key agreement key to use.</td>
</tr>
<tr>
<td>options.publicKey</td>
<td><code>map</code></td>
<td>The public key to compute the shared secret against; the public key type must match the key agreement key's type.</td>
</tr>
<tr>
<td>[options.capability]</td>
<td><code>string</code></td>
<td>The zCAP-LD authorization capability to use to authorize the invocation of this operation.</td>
</tr>
<tr>
<td>options.invocationSigner</td>
<td><code>map</code></td>
<td>An API with an <code>id</code> property and a <code>sign</code> function for signing a capability invocation.</td>
</tr>
</tbody>
</table>
<p><a name="webkms_enableCapability"></a></p>
</section><section><h3 id="enablecapability-options-code-lt-map-gt-code-">enableCapability(options) ⇒ <code><map></code></h3>
<p>Stores a delegated authorization capability, enabling it to be invoked by
its designated invoker.
</p>
<p><strong>Response</strong>: HTTP 200 - <code><map></code> - Resolves once the operation completes.</p>
<table class="simple">
<thead>
<tr>
<th>Param</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>options.capabilityToEnable</td>
<td><code>map</code></td>
<td>The capability to enable.</td>
</tr>
<tr>
<td>[options.capability]</td>
<td><code>string</code></td>
<td>The zCAP-LD authorization capability to use to authorize the invocation of this operation.</td>
</tr>
<tr>
<td>options.invocationSigner</td>
<td><code>map</code></td>
<td>An API with an <code>id</code> property and a <code>sign</code> function for signing a capability invocation.</td>
</tr>
</tbody>
</table>
<p><a name="webkms_disableCapability"></a></p>
</section><section><h3 id="disablecapability-options-code-lt-boolean-gt-code-">disableCapability(options) ⇒ <code><boolean></code></h3>
<p>Removes a previously stored delegated authorization capability, preventing
it from being invoked by its designated invoker.
</p>
<p><strong>Response</strong>: HTTP 200 - <code><boolean></code> - Resolves to <code>true</code> if the document was deleted
and <code>false</code> if it did not exist.
</p>
<table class="simple">
<thead>
<tr>
<th>Param</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>options.id</td>
<td><code>map</code></td>
<td>The ID of the capability to revoke.</td>
</tr>
<tr>
<td>[options.capability]</td>
<td><code>string</code></td>
<td>The zCAP-LD authorization capability to use to authorize the invocation of this operation.</td>
</tr>
<tr>
<td>options.invocationSigner</td>
<td><code>map</code></td>
<td>An API with an <code>id</code> property and a <code>sign</code> function for signing a capability invocation.</td>
</tr>
</tbody>
</table>
<p><a name="webkms_createKeystore"></a></p>
</section><section><h3 id="createkeystore-options-code-lt-map-gt-code-">createKeystore(options) ⇒ <code><map></code></h3>
<p>Creates a new keystore using the given configuration.</p>
<p><strong>Response</strong>: HTTP 200 - <code><map></code> - Resolves to the configuration for the newly
created keystore.
</p>
<table class="simple">
<thead>
<tr>
<th>Param</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>options.url</td>
<td><code>string</code></td>
<td>The url to post the configuration to.</td>
</tr>
<tr>
<td>options.config</td>
<td><code>string</code></td>
<td>The keystore's configuration.</td>
</tr>
</tbody>
</table>
<p><a name="webkms_getKeystore"></a></p>
</section><section><h3 id="getkeystore-options-code-lt-map-gt-code-">getKeystore(options) ⇒ <code><map></code></h3>
<p>Gets the configuration for a keystore by its ID.</p>
<p><strong>Response</strong>: HTTP 200 - <code><map></code> - Resolves to the configuration for the keystore.</p>
<table class="simple">
<thead>
<tr>
<th>Param</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>options.id</td>
<td><code>string</code></td>
<td>The keystore's ID.</td>
</tr>
</tbody>
</table>
<p><a name="webkms_findKeystore"></a></p>
</section><section><h3 id="findkeystore-options-code-lt-map-gt-code-">findKeystore(options) ⇒ <code><map></code></h3>
<p>Finds the configuration for a keystore by its controller and reference ID.</p>
<p><strong>Response</strong>: HTTP 200 - <code><map></code> - Resolves to the configuration for the keystore.</p>
<table class="simple">
<thead>
<tr>
<th>Param</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>[options.url]</td>
<td><code>string</code></td>
<td>The url to query.</td>
</tr>
<tr>
<td>options.controller</td>
<td><code>string</code></td>
<td>The keystore's controller.</td>
</tr>
<tr>
<td>options.referenceId</td>
<td><code>string</code></td>
<td>The keystore's reference ID.</td>
</tr>
</tbody>
</table>
</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>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>