-
Notifications
You must be signed in to change notification settings - Fork 61
/
Copy pathOverview.html
16408 lines (16150 loc) · 651 KB
/
Overview.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>Web Cryptography API</title>
<script src="https://www.w3.org/Tools/respec/respec-w3c" class="remove"></script>
<link rel="stylesheet" href="webcrypto.css" type="text/css" />
<script class=remove>
var respecConfig = {
specStatus: "ED",
editors: [
{
name: "Daniel Huigens",
mailto: "[email protected]",
company: "Proton AG",
companyURL: "https://proton.me/"
},
{
name: "Mark Watson",
retiredDate: "2016-11-01",
},
{
name: "Ryan Sleevi",
retiredDate: "2016-01-21",
},
],
github: "https://github.com/w3c/webcrypto",
shortName: "WebCryptoAPI",
group: "webappsec",
xref: ['html', 'dom', 'webidl', 'infra', 'encoding'],
localBiblio: {
"JWA": {
aliasOf: "RFC7518"
},
// TODO: upgrade existing SP800-38D in specref to be in the new format
"NIST-SP800-38D": {
"title": "NIST Special Publication 800-38D: Recommendation for Block Cipher Modes of Operation: Galois/Counter Mode (GCM) and GMAC",
"href": "http://csrc.nist.gov/publications/nistpubs/800-38D/SP-800-38D.pdf",
"publisher": "NIST",
"date": "November 2007"
},
// TODO: move to specref?
"NIST-SP800-38A": {
"title": "NIST Special Publication 800-38A: Recommendation for Block Cipher Modes of Operation, Methods and Techniques",
"href": "http://csrc.nist.gov/publications/nistpubs/800-38a/sp800-38a.pdf",
"publisher": "NIST",
"date": "December 2001"
},
// TODO: move to specref?
"FIPS-198-1": {
"title": "The Keyed-Hash Message Authentication Code (HMAC)",
"href": "http://csrc.nist.gov/publications/fips/fips198-1/FIPS-198-1_final.pdf",
"publisher": "NIST",
"date": "July 2008"
},
// TODO: move to specref (has broken link under SECG1 name)
"SEC1": {
"title": "SEC 1: Elliptic Curve Cryptography",
"publisher": "Certicom Research",
"href": "http://www.secg.org/sec1-v2.pdf"
},
// TODO: move to specref (currently has older version)
"X690": {
"authors":["Justin Uberti","Cullen Jennings","Eric Rescorla"],
"href": "https://tools.ietf.org/html/draft-ietf-rtcweb-jsep/",
"publisher": "ITU-T",
"status": "ITU-T Recommendation",
"title": "Information technology - ASN.1 encoding rules: Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules (DER)",
"date": "November 2008"
}
}
};
</script>
</head>
<body>
<section id="abstract">
<h2>Abstract</h2>
<p>
This specification describes a JavaScript API for performing basic
cryptographic operations in web applications, such as hashing,
signature generation and verification, and encryption and decryption.
Additionally, it describes an API for applications to generate and/or
manage the keying material necessary to perform these operations.
Uses for this API range from user or service authentication, document
or code signing, and the confidentiality and integrity of
communications.
</p>
<!--<?revision-note?>-->
</section>
<section id="sotd">
</section>
<section id="introduction" class="informative">
<h2>Introduction</h2>
<p>
The Web Cryptography API defines a low-level interface to interacting with cryptographic
key material that is managed or exposed by user agents. The API itself is agnostic of
the underlying implementation of key storage, but provides a common set of interfaces
that allow rich web applications to perform operations such as signature generation and
verification, hashing and verification, encryption and decryption, without requiring
access to the raw keying material.
</p>
<p>
Cryptographic transformations are exposed via the
{{SubtleCrypto}} interface, which defines a set of methods
for performing common cryptographic operations. In addition to operations such as signature
generation and verification, hashing and verification, and encryption and decryption,
the API provides interfaces for key generation, key derivation and key import and export.
</p>
</section>
<section id="use-cases" class="informative">
<h2>Use Cases</h2>
<section id="multifactor-authentication">
<h3>Multi-factor Authentication</h3>
<p>
A web application may wish to extend or replace existing username/password based
authentication schemes with authentication methods based on proving that the user has
access to some secret keying material. Rather than using transport-layer authentication,
such as TLS client certificates, the web application may prefer the richer user
experience provided by authenticating within the application itself.
</p>
<p>
Using the Web Cryptography API, the application could locate suitable client keys, which
may have been previously generated via the user agent or pre-provisioned out-of-band by
the web application. It could then perform cryptographic operations such as decrypting an
authentication challenge followed by signing an authentication response.
</p>
<p>
This exchange could be further strengthened by binding the authentication to the TLS
session over which the client is authenticating, by deriving a key based on properties of
the underlying transport.
</p>
<p>
If a user does not already have a key associated with their account, the web application
could direct the user agent to either generate a new key or to re-use an existing key of
the user's choice.
</p>
</section>
<section id="protected-document">
<h3>Protected Document Exchange</h3>
<p>
A web application may wish to limit the viewership of documents that contain sensitive or
personal information, even when these documents have been securely received, such as over
TLS.
</p>
<p>
Using the Web Cryptography API, the application could do so by encrypting the documents
with a secret key, and then wrapping that key with the public keys associated with the
authorized viewers. When a user agent navigates to such a web application, the
application would send the encrypted form of the document. The user agent is then
instructed to unwrap the encryption key, using the user's private key, and from there,
decrypt and display the document.
</p>
</section>
<section id="cloud-storage">
<h3>Cloud Storage</h3>
<p>
A web application may wish to permit users to protect the confidentiality of data and
documents stored with remote service providers prior to uploading.
</p>
<p>
Using the Web Cryptography API, the application may have a user select a private or
secret key, optionally derive an encryption key from the selected key, encrypt the
document, and then upload the encrypted data to the service provider using existing APIs.
</p>
<p>
This use case is similar to the <a href="#protected-document">Protected Document
Exchange</a> use case, with viewership of the document limited to the user themself.
</p>
</section>
<section id="document-signing">
<h3>Document Signing</h3>
<p>
A web application may wish to accept electronic signatures on documents, in lieu of
requiring physical signatures.
</p>
<p>
Using the Web Cryptography API, the application may direct the user to select a key,
which may have been pre-provisioned out-of-band, or generated specifically for the web
application. Using this key, the application may perform a signing operation over some
data, as proof that the user accepts the document.
</p>
</section>
<section id="data-integrity-protection">
<h3>Data Integrity Protection</h3>
<p>
A web application may wish to cache data locally, while ensuring that this data cannot be
modified in an offline attack.
</p>
<p>
Using the Web Cryptography API, the application may use a public key contained within the
application to verify the contents of the data cache. Previously, when data was added to
the cache, it would have been signed by the server with the corresponding private key. By
validating the signature when restoring data from the cache, the client ensures that the
cached data has not been tampered with.
</p>
</section>
<section id="secure-messaging">
<h3>Secure Messaging</h3>
<p>
A web application may wish to employ message layer security using schemes such as
off-the-record (OTR) messaging, even when these messages have been securely received,
such as over TLS.
</p>
<p>
The Web Cryptography API enables OTR and similar message signing schemes, by allowing key
agreement to be performed. The two parties can negotiate shared encryption keys and
message authentication code (MAC) keys, to allow encryption and decryption of messages,
and to prevent tampering.
</p>
</section>
<section id="jose">
<h3>JavaScript Object Signing and Encryption (JOSE)</h3>
<p>
A web application may wish to interact with the structures and message formats defined by
the IETF JavaScript Object Signing and Encryption (JOSE) Working Group.
</p>
<p>
Using the Web Cryptography API, the application may read and import keys encoded in the
JSON key format (JWK), validate messages that have been integrity protected using digital
signatures or MACs (JWS), or decrypt messages that have been encrypted (JWE).
</p>
</section>
</section>
<section id="conformance">
<p>
The following conformance classes are defined by this specification:
</p>
<dl>
<dt><dfn id="dfn-conforming-implementation">conforming user agent</dfn></dt>
<dd>
<p>
A user agent is considered to be a
[= conforming user agent =]
if it satisfies all of the MUST-,
REQUIRED- and SHALL-level
criteria in this specification that apply to implementations. This specification
uses both the terms "conforming user agent" and "user agent" to refer to this
product class.
</p>
</dd>
</dl>
<p>
Conformance requirements phrased as algorithms or specific steps may be implemented in any
manner, so long as the end result is equivalent. (In particular, the algorithms defined in
this specification are intended to be easy to follow, and not intended to be performant.)
</p>
<p>
User agents that use ECMAScript to implement the APIs defined in this specification
MUST implement them in a manner consistent with the
ECMAScript Bindings defined in the Web IDL specification [[WebIDL]]
as this specification uses that specification and terminology.
</p>
<p>
Unless otherwise stated, string comparisons are done in a
[= case-sensitive =] manner. String literals in this specification
written in monospace font like "`this`" do not include the enclosing quotes.
</p>
<section id="extensibility">
<h3>Extensibility</h3>
<p>
Vendor-specific proprietary extensions to this specification are strongly discouraged.
Authors must not use such extensions, as doing so reduces interoperability and fragments
the user base, allowing only users of specific user agents to access the content in
question.
</p>
<p>
If vendor-specific extensions are needed, the members should be prefixed by
vendor-specific strings to prevent clashes with future versions of this specification.
Extensions must be defined so that the use of extensions neither contradicts nor causes
the non-conformance of functionality defined in the specification.
</p>
<p>
When vendor-neutral extensions to this specification are needed, either this
specification can be updated accordingly, or an extension specification can be written
that overrides the requirements in this specification. When someone applying this
specification to their activities decides that they will recognize the requirements of
such an extension specification, it becomes an
<dfn id="dfn-applicable-specification">applicable specification</dfn> for the purposes
of conformance requirements in this specification. Applicable specifications defined
by the W3C Web Cryptography Working Group are listed in the table below.
</p>
<table>
<tbody>
<tr>
<td>Specification</td>
<td>Reference</td>
</tr>
</tbody>
</table>
<div class=note>
Readers are advised to consult the errata to this specification for updates to the table
above.
</div>
</section>
</section>
<section id="scope" class="informative">
<h2>Scope</h2>
<section id="scope-abstraction">
<h3>Level of abstraction</h3>
<p>
The specification attempts to focus on the common functionality and features between
various platform-specific or standardized cryptographic APIs, and avoid features and
functionality that are specific to one or two implementations. As such this API allows
key generation, management, and exchange with a level of abstraction that avoids
developers needing to care about the implementation of the underlying key storage. The
API is focused specifically around CryptoKey objects, as an abstraction for the
underlying raw cryptographic keying material. The intent behind this is to allow an API
that is generic enough to allow conforming user agents to expose keys that are stored
and managed directly by the user agent, that may be stored or managed using isolated
storage APIs such as per-user key stores provided by some operating systems, or within
key storage devices such as secure elements, while allowing rich web applications to
manipulate the keys and without requiring the web application be aware of the nature of
the underlying key storage.
</p>
</section>
<section id="scope-algorithms">
<h3>Cryptographic algorithms</h3>
<p>
Because the underlying cryptographic implementations will vary between conforming user
agents, and may be subject to local policy, including but not limited to concerns such
as government or industry regulation, security best practices, intellectual property
concerns, and constrained operational environments, this specification does not dictate
a mandatory set of algorithms that MUST be implemented.
Instead, it defines a common set of bindings that can be used in an
algorithm-independent manner, a common framework for discovering if a user agent or key
handle supports the underlying algorithm, and a set of conformance requirements for the
behaviors of individual algorithms, if implemented.
</p>
</section>
<section id="scope-out-of-scope">
<h3>Out of scope</h3>
<p>
This API, while allowing applications to generate, retrieve, and manipulate keying
material, does not specifically address the provisioning of keys in particular types of
key storage, such as secure elements or smart cards. This is due to such provisioning
operations often being burdened with vendor-specific details that make defining a
vendor-agnostic interface an unsuitably unbounded task. Additionally, this API does not
deal with or address the discovery of cryptographic modules, as such concepts are
dependent upon the underlying user agent and are not concepts that are portable between
common operating systems, cryptographic libraries, and implementations.
</p>
</section>
</section>
<section id="concepts" class="informative">
<h2>Concepts</h2>
<section id="concepts-underlying-implementation">
<h3>Underlying Cryptographic Implementation</h3>
<p>
This specification assumes, but does not require, that conforming user agents do not
and will not be directly implementing cryptographic operations within the user agent
itself. Historically, many user agents have deferred cryptographic operations, such as
those used within TLS, to existing APIs that are available as part of the underlying
operating system or to third-party modules that are managed independently of the user
agent.
</p>
<p>
The {{CryptoKey}} object represents the bridge between the
JavaScript execution environment and these underlying libraries, through the use of the
internal slot named {{CryptoKey/[[handle]]}}. The handle
represents an opaque type that is implementation specific, which may not be represented
within a JavaScript type, nor is it ever exposed to script authors. In this way, the
{{CryptoKey}} object is the conceptual equivalent to the
JavaScript executing environment as the
{{CryptoKey/[[handle]]}} is to the underlying cryptographic
implementation.
</p>
<p>
These APIs are traditionally built around a notion of cryptographic providers, an
abstraction for a specific implementation of a set of algorithms. The operating system
or library may come with a default provider, and users are frequently allowed to add
additional providers, reconfigure the set of enabled algorithms, or otherwise customize
how cryptographic services are provided.
</p>
<p>
While it is assumed that most user agents will be interacting with a cryptographic
provider that is implemented purely in software, it is not required by this
specification. As a result, the capabilities of some implementations may be limited by
the capabilities of the underlying hardware, and, depending on how the user has
configured the underlying cryptographic library, this may be entirely opaque to the
User Agent.
</p>
</section>
<section id="concepts-key-storage">
<h3>Key Storage</h3>
<p>
This specification does not explicitly provide any new storage mechanisms for
{{CryptoKey}} objects. Instead, by defining
<a href="#cryptokey-interface-serializable">serialization and deserialization steps</a>
for {{CryptoKey}} objects, any existing or future web storage mechanisms that support
storing <a>serializable objects</a> can be used to store {{CryptoKey}} objects.
</p>
<p>
In practice, it is expected that most authors will make use of the
Indexed Database API [[INDEXEDDB]], which allows associative storage of
key/value pairs, where the key is some string identifier meaningful to the application,
and the value is a {{CryptoKey}} object. This allows the
storage and retrieval of key material, without ever exposing that key material to the
application or the JavaScript environment. Additionally, this allows authors
the full flexibility to store any additional metadata with the
{{CryptoKey}} itself.
</p>
</section>
</section>
<section id="security-considerations" class="informative">
<h2>Security considerations</h2>
<section id="security-implementers">
<h2>Security considerations for implementers</h2>
<p>
By not providing an explicit storage mechanism, this specification assumes that
{{CryptoKey}} objects are scoped to the current execution
environment and any storage mechanisms available to that environment (e.g.
Indexed Database API). Application authors rely upon this for
the security of their applications; two origins with the same
{{CryptoKey}} object have full access to the underlying key,
and as such, messages from these applications cannot be distinguished, and messages sent
to these applications can be fully recovered. Implementors should ensure that no
{{CryptoKey}} objects are shared between two origins unless
the author has explicitly chosen to share (e.g., such as through the use of postMessage)
</p>
<p>
A number of algorithms specified within this specification perform computationally
intensive work, such as the generation of significantly large prime numbers, or through
repeated iterations of a particular operation. As such, hostile applications may attempt
to misuse this API and attempt to cause significant amount of work to be performed by
an implementation, denying access or services to other applications that are executing.
Implementations should take steps to mitigate these risks, such as limiting the amount
of operations an implementation performs concurrently, requiring user consent for
operations that may be known to be disruptive for the executing environment, or defining
device-specific limits on attributes such as key sizes or iteration counts.
</p>
</section>
<section id="security-developers">
<h2>Security considerations for authors</h2>
<p>
This specification includes descriptions for a variety of cryptographic operations, some
of which have known weaknesses when used inappropriately. Application developers must
take care and review appropriate and current cryptographic literature, to understand and
mitigate such issues. In general, application developers are <strong>strongly</strong>
discouraged from inventing new cryptographic protocols; as with all applications, users
of this specification will be best served through the use of existing protocols, of
which this specification provides the necessary building blocks to implement.
</p>
<p>
In order to use the APIs defined in this specification to provide any meaningful
cryptographic assurances, authors must be familiar with existing threats to web
applications, as well as the underlying security model employed. Conceptually, issues
such as script injection are the equivalent to remote code execution in other operating
environments, and allowing hostile script to be injected may allow for the exfiltration
of keys or data. Script injection may come from other applications, for which the
judicious use of Content Security Policy may mitigate, or it may come from hostile
network intermediaries, for which the use of Transport Layer Security may mitigate.
</p>
<p>
This specification does not define any specific mechanisms for the storage of
cryptographic keys. By default, unless specific effort is taken by the author to persist
keys, such as through the use of the Indexed Database API, keys
created with this API will only be valid for the duration of the current page (e.g.
until a navigation event). Authors that wish to use the same key across different pages
or multiple browsing sessions must employ existing web storage technologies. Authors
should be aware of the security assumptions of these technologies, such as the
same-origin security model; that is, any application that shares the same scheme, host,
and port have access to the same storage partition, even if other information, such as
the path, may differ. Authors may explicitly choose to relax this security through the
use of inter-origin sharing, such as `postMessage`.
</p>
<p>
Authors should be aware that this specification places no normative requirements on
implementations as to how the underlying cryptographic key material is stored. The only
requirement is that key material is not exposed to script, except through the use of the
{{SubtleCrypto/exportKey}} and {{SubtleCrypto/wrapKey}} operations. In particular, it does
not guarantee that the underlying cryptographic key material will not be persisted to
disk, possibly unencrypted, nor that it will be inaccessible to users or other
applications running with the same privileges as the User Agent. Any application or user
that has access to the device storage may be able to recover the key material, even
through scripts may be prohibited.
</p>
<p>
This specification places no normative requirements on how implementations handle key
material once all references to it go away. That is, conforming user agents are not
required to zeroize key material, and it may still be accessible on device storage or
device memory, even after all references to the {{CryptoKey}}
have gone away.
</p>
<p>
Applications may share a {{CryptoKey}} object across security
boundaries, such as origins, through the use of the structured clone algorithm and APIs
such as `postMessage`. While access to the underlying cryptographic key
material may be restricted, based upon the {{CryptoKey/extractable}}
attribute, once a key is shared with a destination origin, the source origin can not
later restrict or revoke access to the key. As such, authors must be careful to ensure
they trust the destination origin to take the same mitigations against hostile script
that the source origin employs. Further, in the event of script injection on the source
origin, attackers may post the key to an origin under attacker control. Any time that
the user agent visits the attacker's origin, the user agent may be directed to perform
cryptographic operations using that key, such as the decryption of existing messages
or the creation of new, fraudulent messages.
</p>
<p>
Authors should be aware that users may, at any time, choose to clear the storage
associated with an origin, potentially destroying keys. Applications that are meant to
provide long-term storage, such as on the server, should consider techniques such as
key escrow to prevent such data from being inaccessible. Authors should not presume
that keys will be available indefinitely.
</p>
</section>
<section id="security-users">
<h3>Security considerations for users</h3>
<p>
Users of applications that employ the APIs defined in this specification should be aware
that these applications will have full access to all messages exchanged, regardless of
the cryptography employed. That is, for messages that are encrypted, applications that
use these APIs will have full access to the decrypted message as well.
</p>
</section>
</section>
<section id="privacy" class="informative">
<h2>Privacy considerations</h2>
<dl>
<dt>Fingerprinting</dt>
<dd>
By exposing additional APIs that reflect capabilities of the underlying platform, this
specification may allow malicious applications to determine or distinguish different
user agents or devices.
</dd>
<dt>Super-cookies</dt>
<dd>
This specification does not provide any means for malicious applications to create
identifiers that outlive existing web storage technologies. However, care must be taken
when introducing future revisions to this API or additional cryptographic capabilities,
such as those that are hardware backed (e.g.: smart cards or Trusted Platform Modules).
Considering that such storage is designed to prevent any two users from having the same
underlying key data, such APIs may represent a real risk of being used as a permanent
identifier against the user's wishes.
</dd>
<dt>
Use of {{Crypto/randomUUID}} as user ID
</dt>
<dd>
{{Crypto/randomUUID}} is useful for generating <a href=
"https://w3cping.github.io/privacy-threat-model/#user-id">user
IDs</a>, but does not directly give any ability to generate <a href=
"https://w3cping.github.io/privacy-threat-model/#global-identifier">global
identifiers</a>.
</dd>
</dl>
</section>
<section id="dependencies">
<h3>Dependencies</h3>
<p>This specification relies on underlying specifications.</p>
<dl>
<dt>DOM</dt>
<dd>
<p>
A [= conforming user agent =] MUST support at
least the subset of the functionality defined in DOM that this specification relies
upon; in particular, it MUST support {{Promise}}s and
{{DOMException}}.
[[DOM]]
</p>
</dd>
<dt>HTML</dt>
<dd>
<p>
A [= conforming user agent =] MUST support at
least the subset of the functionality defined in HTML that this specification relies
upon; in particular, it MUST support the
{{ArrayBufferView}} typedef and <a>serializable objects</a>.
[[HTML]]
</p>
</dd>
<dt>Web IDL</dt>
<dd>
<p>
A [= conforming user agent =] MUST be a
conforming implementation of the IDL fragments in this specification, as described in
the Web IDL specification. [[WebIDL]]
</p>
</dd>
</dl>
</section>
<section id="terminology">
<h2>Terminology</h2>
<p>
The terms
{{ArrayBuffer}},
{{ArrayBufferView}}, and
<dfn id="dfn-serializable-objects">serializable objects</dfn>,
are defined by the HTML specification [[HTML]].
</p>
<p>
The terms {{DOMString}} and
{{BufferSource}} are defined in [[WEBIDL]].
</p>
<p>
The term [= byte sequence =] is defined in [[Infra]].
</p>
<p>
The <dfn id="dfn-length-in-bits" data-lt="length in bits">length in bits</dfn> of a [= byte sequence =]
is its [= byte sequence/length =] multiplied by 8.
</p>
<p>
A <dfn id="dfn-byte-sequence-containing" data-lt="byte sequence containing">byte sequence containing a bit sequence</dfn> |b| is the
[= byte sequence =] obtained by first appending zero or more
bits of value zero to |b| such that the length of the resulting bit sequence is minimal and an integer multiple of 8
and then considering each consecutive sequence of 8 bits in that string as a byte.
</p>
<p>
When this specification says to <dfn id="dfn-convert-integer-to-byte-sequence">convert a non-negative
integer |i| to a byte sequence of length |n|</dfn>, where |n| * 8
is greater than the logarithm to base 2 of |i|, the user agent must
first calculate the binary representation of |i|, most significant bit first,
prefix this with sufficient zero bits to form a bit sequence of length |n| * 8, and
then return the [= byte sequence =] formed by considering each consecutive
sequence of 8 bits in that bit sequence as a byte.
</p>
<p>
Comparing two strings in a <dfn id="case-sensitive">case-sensitive</dfn>
manner means comparing them exactly, code point for code point.
</p>
<p>
Comparing two strings in a <dfn id="case-insensitive" data-local-lt="case-insensitive">ASCII case-insensitive</dfn> manner
means comparing them exactly, code point for code point, except that the codepoints in
the range U+0041 .. U+005A (i.e. LATIN CAPITAL LETTER A to LATIN CAPITAL LETTER Z) and
the corresponding codepoints in the range U+0061 .. U+007A
(i.e. LATIN SMALL LETTER A to LATIN SMALL LETTER Z) are also considered to match.
</p>
<p>
When this specification says to <dfn id="terminate-the-algorithm">terminate the
algorithm</dfn>, the user agent must terminate the algorithm after finishing the step it
is on. The algorithm referred to is the set of specification-defined processing steps,
rather than the underlying cryptographic algorithm that may be in the midst of processing.
</p>
<p>
When this specification says to <dfn id="concept-parse-an-asn1-structure">parse an ASN.1
structure</dfn>, the user agent must perform the following steps:
</p>
<ol>
<li>
<p>
Let |data| be a sequence of bytes to be parsed.
</p>
</li>
<li>
<p>
Let |structure| be the ASN.1 structure to be parsed.
</p>
</li>
<li>
<p>
Let |exactData| be an optional boolean value. If it is not supplied,
let it be initialized to `true`.
</p>
</li>
<li>
<p>
Parse |data| according to the Distinguished Encoding Rules of
[[X690]], using |structure| as the ASN.1 structure
to be decoded.
</p>
</li>
<li>
<p>
If |exactData| was specified, and all of the bytes of |data| were
not consumed during the parsing phase, then
[= exception/throw =] a
{{DataError}}.
</p>
</li>
<li>
<p>
Return the parsed ASN.1 structure.
</p>
</li>
</ol>
<p>
When this specification says to <dfn id="concept-parse-a-spki">parse a
subjectPublicKeyInfo</dfn>, the user agent must
[= parse an ASN.1 structure =], with
|data| set to the sequence of bytes to be parsed, |structure| as the
ASN.1 structure of subjectPublicKeyInfo, as specified in [[RFC5280]],
and |exactData| set to `true`.
</p>
<p>
When this specification says to <dfn id="concept-parse-a-privateKeyInfo">parse a
PrivateKeyInfo</dfn>, the user agent must [= parse
an ASN.1 structure =] with |data| set to the sequence of bytes to be parsed,
|structure| as the ASN.1 structure of PrivateKeyInfo, as specified in
[[RFC5208]], and |exactData| set to `true`.
</p>
<p>
When this specification says to <dfn id="concept-parse-a-jwk">parse a JWK</dfn>, the user
agent must run the following steps:
</p>
<ol>
<li>
<p>
Let |data| be the sequence of bytes to be parsed.
</p>
</li>
<li>
<p>
Let |json| be the Unicode string that results from interpreting
|data| according to UTF-8.
</p>
</li>
<li>
<p>
Convert |json| to UTF-16.
</p>
</li>
<li>
<p>
Let |result| be the object literal that results from executing the
`JSON.parse` internal function in the context of a new global object,
with `text` argument set to a JavaScript String containing |json|.
</p>
</li>
<li>
<p>
Let |key| be the result of converting |result| to the IDL dictionary
type of {{JsonWebKey}}.
</p>
</li>
<li>
<p>
If the {{JsonWebKey/kty}} field of |key| is not defined, then [= exception/throw =] a {{DataError}}.
</p>
</li>
<li>
<p>
Return |key|.
</p>
</li>
</ol>
<p>
When this specification says to calculate the <dfn id="concept-usage-intersection">usage
intersection</dfn> of two sequences, |a| and |b| the result shall be a
sequence containing each [= recognized key usage value =]
that appears in both |a| and |b|, in the order listed in the list of
[= recognized key usage value=]s, where a value is said
to appear in a sequence if an element of the sequence exists that is a case-sensitive string
match for that value.
</p>
<p>
When this specification says to calculate the <dfn id="concept-normalized-usages" data-local-lt="normalized value">
normalized value of a usages list</dfn>, |usages| the result shall be the
[= usage intersection =] of |usages| and a
sequence containing all [= recognized key usage value =]s.
</p>
<p>
When this specification refers to the <dfn id="concept-cached-object">cached ECMAScript
object</dfn> associated with an internal slot [[<var>slot</var>]] of |object|,
the user agent must run the following steps:
</p>
<ol>
<li>
<dl class="switch">
<dt>
If the [[<var>slot</var>_cached]] internal slot of |object| is undefined:
</dt>
<dd>
Set the [[<var>slot</var>_cached]] internal slot of |object| to the result
of performing type conversion to an ECMAScript object as defined in
[[WebIDL]] to the contents of the [[<var>slot</var>]]
internal slot of |object|.
</dd>
</dl>
</li>
<li>
Return the contents of the [[<var>slot</var>_cached]] internal slot of |object|.
</li>
</ol>
</section>
<section id="crypto-interface">
<h2>Crypto interface</h2>
<p>
The <dfn data-idl id="dfn-Crypto">Crypto</dfn> interface represents an interface to
general purpose cryptographic functionality including a
cryptographically strong pseudo-random number generator seeded with truly random values.
</p>
<pre class=idl>
partial interface mixin WindowOrWorkerGlobalScope {
[SameObject] readonly attribute Crypto crypto;
};
[Exposed=(Window,Worker)]
interface Crypto {
[SecureContext] readonly attribute SubtleCrypto subtle;
ArrayBufferView getRandomValues(ArrayBufferView array);
[SecureContext] DOMString randomUUID();
};
</pre>
<div class=note>
Implementations should generate cryptographically strong random values using
well-established cryptographic pseudo-random number generators seeded with high-quality
entropy, such as from an operating-system entropy source (e.g., "/dev/urandom"). This
specification provides no lower-bound on the information theoretic entropy present in
cryptographically strong random values, but implementations should make a best effort to provide
as much entropy as practicable.
</div>
<div class=note>
This interface defines a synchronous method for obtaining cryptographically strong random
values. While some devices and implementations may support truly random cryptographic
number generators or provide interfaces that block when there is insufficient entropy,
implementations are discouraged from using these sources when implementing
getRandomValues, both for performance and to avoid depleting the system of entropy.
Instead, these sources should be used to seed a cryptographic pseudo-random number
generator that can then return suitable values efficiently.
</div>
<section id="Crypto-interface-methods">
<h3>Methods and Parameters</h3>
<section id="Crypto-method-getRandomValues">
<h4>The getRandomValues method</h4>
<p>
The <dfn id="dfn-Crypto-method-getRandomValues" data-dfn-for=Crypto>getRandomValues</dfn>
method generates cryptographically strong random values. It must act as follows:
</p>
<ol>
<li>
<p>
If |array| is not an {{Int8Array}}, {{Uint8Array}}, {{Uint8ClampedArray}},
{{Int16Array}}, {{Uint16Array}}, {{Int32Array}}, {{Uint32Array}},
{{BigInt64Array}}, or {{BigUint64Array}}, then [= exception/throw =] a
{{TypeMismatchError}} and
[= terminate the algorithm =].
</p>
</li>
<li>
<p>
Let |byteLength| be the [= BufferSource/byte length =] of |array|.
</p>
</li>
<li>
<p>
If |byteLength| is greater than 65536, [= exception/throw =] a
{{QuotaExceededError}} and
[= terminate the algorithm =].
</p>
</li>
<li>
<p>
Let |bytes| be a [= byte sequence =] of length |byteLength|.
</p>
</li>
<li>
<p>
Fill |bytes| with cryptographically secure random bytes.
</p>
</li>
<li>
<p>
[= ArrayBufferView/Write =] |bytes| into |array|.
</p>
</li>
<li>
<p>
Return |array|.
</p>
</li>
</ol>
<div class=note>
<p>
Do not generate keys using the `getRandomValues` method. Use the
{{SubtleCrypto/generateKey}} method
instead.
</p>
</div>
</section>
<section id="Crypto-method-randomUUID">
<h4>The randomUUID method</h4>
<p>
The <dfn id="dfn-Crypto-method-randomUUID" data-dfn-for=Crypto>randomUUID</dfn>
method generates a new <a data-cite="RFC4122#section-4.4">version 4 UUID</a>
and returns its <a data-cite="RFC2141#section-2.2">namespace specific string representation</a>
as described in <a data-cite="RFC4122#section-3">section 3</a> of [[RFC4122]].
To <dfn data-export="">generate a random UUID</dfn>:
</p>
<ol>
<li>
Let |bytes| be a [= byte sequence =] of length 16.
</li>
<li>
Fill |bytes| with cryptographically secure random bytes.
</li>
<li>
Set the 4 most significant bits of |bytes|[6], which represent the
UUID <a data-cite="RFC4122#section-4.1.3">version</a>, to `0100`.
</li>
<li>
Set the 2 most significant bits of |bytes|[8], which represent the
UUID <a data-cite="RFC4122#section-4.1.1">variant</a>, to `10`.
</li>
<li>
<p>
Return the [= string/concatenate | string concatenation =] of «
</p>
<ol style="list-style-type: none">
<li>
[= hexadecimal representation =] of |bytes|[0], [= hexadecimal
representation =] of |bytes|[1], [= hexadecimal representation =] of
|bytes|[2], [= hexadecimal representation =] of |bytes|[3],
</li>
<li>
"`-`",
</li>
<li>
[= hexadecimal representation =] of |bytes|[4], [= hexadecimal
representation =] of |bytes|[5],
</li>
<li>
"`-`",
</li>
<li>
[= hexadecimal representation =] of |bytes|[6], [= hexadecimal
representation =] of |bytes|[7],
</li>
<li>
"`-`",
</li>
<li>
[= hexadecimal representation =] of |bytes|[8], [= hexadecimal
representation =] of |bytes|[9],
</li>
<li>
"`-`",
</li>
<li>
[= hexadecimal representation =] of |bytes|[10], [= hexadecimal
representation =] of |bytes|[11], [= hexadecimal representation =] of
|bytes|[12], [= hexadecimal representation =] of |bytes|[13],
[= hexadecimal representation =] of |bytes|[14], [= hexadecimal
representation =] of |bytes|[15]
</li>
</ol>
<p>
».
</p>
</li>
</ol>
<p>
For the steps described in the algorithm to [= generate a random UUID =],
the <dfn>hexadecimal representation</dfn> of a byte |value| is the
two-character string created by expressing |value| in hexadecimal using
[= ASCII lower hex digits =], left-padded with "`0`" to reach two
[= ASCII lower hex digits =].
</p>
</section>
</section>
<section id="Crypto-interface-attributes">
<h3>Attributes</h3>
<section id="Crypto-attribute-subtle">
<h4>The subtle attribute</h4>
<p>
The <dfn id="dfn-Crypto-attribute-subtle" data-dfn-for=Crypto>subtle</dfn> attribute provides
an instance of the {{SubtleCrypto}} interface which provides
low-level cryptographic primitives and algorithms.
</p>
</section>
</section>
</section>
<section id="algorithm-dictionary">
<h2>Algorithm dictionary</h2>
<p>
The <dfn data-idl id="dfn-Algorithm">Algorithm</dfn> object is a dictionary object [[WEBIDL]]
which is used to specify an algorithm and any additional parameters required to fully
specify the desired operation.
</p>
<dfn id="dfn-HashAlgorithmIdentifier"></dfn>
<pre class=idl id="dfn-AlgorithmIdentifier">
typedef (object or DOMString) AlgorithmIdentifier;
typedef AlgorithmIdentifier HashAlgorithmIdentifier;
dictionary Algorithm {
required DOMString name;
};