--- a/spec/Overview-WebCryptoAPI.xml Mon Jun 16 00:00:00 2014 -0700
+++ b/spec/Overview-WebCryptoAPI.xml Mon Jun 16 00:00:00 2014 -0700
@@ -385,117 +385,203 @@
</div>
</div>
+
+ <div class='section' id='concepts'>
+ <h2>Concepts</h2>
+ <p class='norm'>This section is non-normative.</p>
+ <div class='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 <a href="#dfn-CryptoKey">CryptoKey</a> object represents the bridge between the
+ JavaScript execution environment and these underlying libraries, through the use of the
+ internal slot named [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]]. 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
+ <a href="#dfn-CryptoKey">CryptoKey</a> object is the conceptual equivalent to the
+ JavaScript executing environment as the
+ [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] 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>
+ </div>
+ <div class='section' id='concepts-key-storage'>
+ <h3>Key Storage</h3>
+ <p>
+ This specification does not explicitly provide any new storage mechanisms for
+ <a href="#dfn-CryptoKey">CryptoKey</a> objects. Instead, by allowing the
+ <a href="#dfn-CryptoKey">CryptoKey</a> to be used with the structured clone algorithm,
+ any existing or future web storage mechanisms that support storing structured clonable
+ objects can be used to store <a href="#dfn-CryptoKey">CryptoKey</a> objects.
+ </p>
+ <p>
+ In practice, it is expected that most authors will make use of the
+ <a href="#IndexedDB">Indexed Database API</a>, which allows associative storage of
+ key/value pairs, where the key is some string identifier meaningful to the application,
+ and the value is a <a href="#dfn-CryptoKey">CryptoKey</a> 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
+ <a href="#dfn-CryptoKey">CryptoKey</a> itself.
+ </p>
+ </div>
+ </div>
+
<div id="security" class="section">
<h2>Security considerations</h2>
<p class='norm'>This section is non-normative.</p>
<div id="security-implementers" class="section">
<h2>Security considerations for implementers</h2>
<p>
- User agents should take care before exposing keys that were not explicitly generated
- via the API in this specification or exposing keys that were generated in the
- context of other origins. Two applications with access to the same key handle may be
- able to spoof messages to each other, as both valid and hostile messages will appear
- to be valid for the given key. Because of this, user agents are recommended to obtain
- express permission from the user before re-using keys, unless there is a prearranged
- trust relationship.
- </p>
- <p>
- User agents should be aware of the security considerations of each algorithm
- implemented and exposed to applications. For a number of algorithms, their
- cryptographic strength is relative to the amount of work necessary to compute the
- result, whether this be through the generation of significantly large prime numbers or
- through the repeatedly iterating through the same algorithm to reduce its
- susceptibility to brute force. Implementations should therefore take measures to
- ensure against misuse. Such measures may include requiring express user permission to
- compute some expensive operations, rate limiting the number of times the application
- may call certain APIs/algorithms, and defining implementation-specific upper limits
- for inputs such as key sizes or iteration counts, as appropriate for the device on
- which the implementation executes.
- </p>
- <p>
- In some cases, the same underlying cryptographic key material may be re-usable for
- multiple algorithms. One such example is an RSA key, which may be used for both
- signing and encryption, or with RSA-PKCS1v1.5 and RSA-PSS. In some cases, the re-use
- of this key material may undermine the security properties of the key and allow
- applications to recover the raw material.
- </p>
- <div class="ednote">
- <ul>
- <li>
- <a href="https://www.w3.org/2012/webcrypto/track/issues/33">ISSUE-33</a>
- One proposed technical solution for user agents is to implement "key tainting", in
- which it records how a particular key has been used (eg: algorithms, parameters),
- and prevents it from being re-used in a manner that is unsafe or contrary to the
- security - such as preventing a PKCS1-v1.5 key from being used with RSA-PSS, or
- preventing an RSA-OAEP w/ MGF1-SHA1 from being used with RSA-OAEP w/ MGF1-SHA256.
- Questions exist about whether this should be encouraged or permitted, and the
- interoperability concerns it might cause.
- </li>
- </ul>
- </div>
+ By not providing an explicit storage mechanism, this specification assumes that
+ <a href="#dfn-CryptoKey">CryptoKey</a> objects are scoped to the current execution
+ environment and any storage mechanisms available to that environment (e.g.
+ <a href="#IndexedDB">Indexed Database API</a>). Application authors rely upon this for
+ the security of their applications; two origins with the same
+ <a href="#dfn-CryptoKey">CryptoKey</a> 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
+ <a href="#dfn-CryptoKey">CryptoKey</a> 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>
</div>
<div id="security-developers" class="section">
<h2>Security considerations for authors</h2>
<p>
- While this API provides important functionality for the development of secure
- applications, it does not attempt to provide a mitigation for existing threats to
- the web security model, such as script injection or hostile intermediaries. As such,
- application developers must take care to ensure applications are secured against
- common and traditional attacks, such as script injection, by making use of appropriate
- existing functionality such as Content Security Policy and the use of TLS.
- </p>
- <p>
- This API includes a variety of cryptographic operations, some of which may have known
- security issues when used inappropriately. Application developers should take care to
- review the appropriate cryptographic literature before making use of certain algorithms,
- and should avoid attempting to develop new cryptographic protocols whenever possible.
- </p>
- <p>
- While the API in this specification provides a means to protect keys from future access
- by web applications, it makes no statements as to how the actual keying material will be
- stored by an implementation. As such, although a key may be inaccessible to web content,
- it should not be presumed that it is inaccessible to end-users. For example, a
- conforming user agent may choose to implement key storage by storing key material in
- plain text on device storage. Although the user agent prevents access to the raw keying
- material to web applications, any user with access to device storage may be able to
- recover the key.
+ 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 <a href="#IndexedDB">Indexed Database API</a>, 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 <code>postMessage</code>.
+ </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
+ <a href="#dfn-SubtleCrypto-method-exportKey">exportKey</a> and <a
+ href="#dfn-SubtleCrypto-method-wrapKey">wrapKey</a> 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 <a href="#dfn-CryptoKey">CryptoKey</a>
+ have gone away.
+ </p>
+ <p>
+ Applications may share a <a href="#dfn-CryptoKey">CryptoKey</a> object across security
+ boundaries, such as origins, through the use of the structured clone algorithm and APIs
+ such as <code>postMessage</code>. While access to the underlying cryptographic key
+ material may be restricted, based upon the <a href="#dfn-CryptoKey-extractable">extractable</a>
+ 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>
+ </div>
+ <div class='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>
</div>
</div>
<div id="privacy" class="section">
<h2>Privacy considerations</h2>
- <p class='norm'>This section is non-normative.</p>
+ <p class="norm">This section is non-normative.</p>
<dl>
<dt>Fingerprinting</dt>
<dd>
- Malicious applications may be able to fingerprint users or user agents by detecting or
- enumerating the list of algorithms that are supported. This is especially true if an
- implementation exposes details about users' smart cards or secure element storage, as
- the combination of algorithms supported by such devices may be used to fingerprint
- devices more accurately than just the particular user agent.
- </dd>
- <dt>Tracking</dt>
- <dd>
- If user agents permit keys to be re-used between origins, without performing any
- secondary operations such as key derivation that includes the origin, then it may be
- possible for two origins to collude and track a unique user by recording their ability
- to access a common key.
+ 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>
- With the exception of ephemeral keys, its often desirable for applications to strongly
- associate users with keys. These associations may be used to enhance the security of
- authenticating to the application, such as using a key stored in a secure element as a
- second factor, or may be used by users to assert some identity, such as an e-mail
- signing identity. As such, these keys often live longer than their counterparts such as
- usernames and passwords, and it may be undesirable or prohibitive for users to revoke
- these keys.
- Because of this, keys may exist longer than the lifetime of the browsing context
- [<a href="#HTML">HTML</a>] and beyond the lifetime of items such as cookies, thus
- presenting a risk that a user may be tracked even after clearing such data. This is
- especially true for keys that were pre-provisioned for particular origins and for which
- no user interaction was provided.
+ 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>
</dl>
</div>
@@ -3032,11 +3118,22 @@
As the API is meant to be extensible in order to keep up with future developments within
cryptography and to provide flexibility, there are no strictly required algorithms. Thus
users of this API should check to see what algorithms are currently recommended and
- supported by implementations.
- </p>
- <p>
- However, in order to promote interoperability for developers, there are a number of
- recommended algorithms. The recommended algorithms are:
+ supported by implementations. As highlighted in the <a href="#security">Security
+ Considerations</a>, even strong cryptographic algorithms may be combined in insecure
+ ways. Users should therefore proceed with extreme caution when inventing new
+ cryptographic protocols.
+ </p>
+ <p>
+ Implementers should carefully review their support for different algorithms based on the
+ evolving state of the cryptographic literature. It is expected that the set of
+ widely-accepted algorithms will change over time as new advances are made.
+ </p>
+ <p>
+ With the above caveats in mind, in order to promote interoperability for developers,
+ this specification includes a list of suggested algorithms. These are considered to be
+ the most widely used algorithms in practice at the time of writing, and therefore
+ provide a good starting point for initial implementations of this specification. The
+ suggested algorithms are:
</p>
<ul>
<li>
@@ -16605,6 +16702,11 @@
<cite><a href="http://www.w3.org/TR/FileAPI/">File API</a></cite>,
A. Ranganathan, J. Sicking. W3C.
</dd>
+ <dt id="IndexedDB">Indexed Database API</dt>
+ <dd>
+ <cite><a href="http://www.w3.org/TR/IndexedDB/">Indexed Database API</a></cite>,
+ N. Mehta, J. Sicking, E. Graff, A. Popescu, J. Orlow, J. Bell. W3C.
+ </dd>
<dt id="PKCS11">PKCS11</dt>
<dd>
<cite><a href="http://www.rsa.com/rsalabs/node.asp?id=2133">PKCS #11: Cryptographic
--- a/spec/Overview.html Mon Jun 16 00:00:00 2014 -0700
+++ b/spec/Overview.html Mon Jun 16 00:00:00 2014 -0700
@@ -44,7 +44,7 @@
communications.
</p>
- <div class="ednote"><div class="ednoteHeader">Editorial note</div><p>There are 15 further editorial notes in the document.</p></div>
+ <div class="ednote"><div class="ednoteHeader">Editorial note</div><p>There are 14 further editorial notes in the document.</p></div>
</div>
<div class="section">
@@ -134,7 +134,7 @@
<div id="toc">
<h2>Table of Contents</h2>
- <div class="toc"><ul><li><a href="#introduction">1. Introduction</a></li><li><a href="#use-cases">2. Use Cases</a><ul><li><a href="#multifactor-authentication">2.1. Multi-factor Authentication</a></li><li><a href="#protected-document">2.2. Protected Document Exchange</a></li><li><a href="#cloud-storage">2.3. Cloud Storage</a></li><li><a href="#document-signing">2.4. Document Signing</a></li><li><a href="#data-integrity-protection">2.5. Data Integrity Protection</a></li><li><a href="#secure-messaging">2.6. Secure Messaging</a></li><li><a href="#jose">2.7. Javascript Object Signing and Encryption (JOSE)</a></li></ul></li><li><a href="#conformance">3. Conformance</a></li><li><a href="#scope">4. Scope</a><ul><li><a href="#scope-abstraction">4.1. Level of abstraction</a></li><li><a href="#scope-algorithms">4.2. Cryptographic algorithms</a></li><li><a href="#scope-operations">4.3. Operations</a></li><li><a href="#scope-out-of-scope">4.4. Out of scope</a></li></ul></li><li><a href="#security">5. Security considerations</a><ul><li><a href="#security-implementers">5.1. Security considerations for implementers</a></li><li><a href="#security-developers">5.2. Security considerations for authors</a></li></ul></li><li><a href="#privacy">6. Privacy considerations</a></li><li><a href="#dependencies">7. Dependencies</a></li><li><a href="#terminology">8. Terminology</a></li><li><a href="#RandomSource-interface">9. RandomSource interface</a><ul><li><a href="#RandomSource-description">9.1. Description</a></li><li><a href="#RandomSource-interface-methods">9.2. Methods and Parameters</a><ul><li><a href="#RandomSource-method-getRandomValues">9.2.1. The getRandomValues method</a></li></ul></li></ul></li><li><a href="#algorithm-dictionary">10. Algorithm dictionary</a><ul><li><a href="#algorithm-dictionary-members">10.1. Algorithm Dictionary Members</a></li></ul></li><li><a href="#key-algorithm-dictionary">11. KeyAlgorithm dictionary</a><ul><li><a href="#key-algorithm-dictionary-description">11.1. Description</a></li><li><a href="#key-algorithm-dictionary-members">11.2. KeyAlgorithm dictionary members</a></li></ul></li><li><a href="#cryptokey-interface">12. CryptoKey interface</a><ul><li><a href="#cryptokey-interface-description">12.1. Description</a></li><li><a href="#cryptokey-interface-types">12.2. Key interface data types</a></li><li><a href="#cryptokey-interface-internal-slots">12.3. CryptoKey internal slots</a></li><li><a href="#cryptokey-interface-members">12.4. CryptoKey interface members</a></li><li><a href="#cryptokey-interface-clone">12.5. Structured clone algorithm</a></li></ul></li><li><a href="#crypto-interface">13. Crypto interface</a></li><li><a href="#subtlecrypto-interface">14. SubtleCrypto interface</a><ul><li><a href="#subtlecrypto-interface-description">14.1. Description</a></li><li><a href="#subtlecrypto-interface-datatypes">14.2. Data Types</a></li><li><a href="#subtlecrypto-interface-methods">14.3. Methods and Parameters</a><ul><li><a href="#SubtleCrypto-method-encrypt">14.3.1. The encrypt method</a></li><li><a href="#SubtleCrypto-method-decrypt">14.3.2. The decrypt method</a></li><li><a href="#SubtleCrypto-method-sign">14.3.3. The sign method</a></li><li><a href="#SubtleCrypto-method-verify">14.3.4. The verify method</a></li><li><a href="#SubtleCrypto-method-digest">14.3.5. The digest method</a></li><li><a href="#SubtleCrypto-method-generateKey">14.3.6. The generateKey method</a></li><li><a href="#SubtleCrypto-method-deriveKey">14.3.7. The deriveKey method</a></li><li><a href="#SubtleCrypto-method-deriveBits">14.3.8. The deriveBits method</a></li><li><a href="#SubtleCrypto-method-importKey">14.3.9. The importKey method</a></li><li><a href="#SubtleCrypto-method-exportKey">14.3.10. The exportKey method</a></li><li><a href="#SubtleCrypto-method-wrapKey">14.3.11. The wrapKey method</a></li><li><a href="#SubtleCrypto-method-unwrapKey">14.3.12. The unwrapKey method</a></li></ul></li><li><a href="#SubtleCrypto-Exceptions">14.4. Exceptions</a></li></ul></li><li><a href="#JsonWebKey-dictionary">15. JsonWebKey dictionary</a></li><li><a href="#WorkerCrypto-interface">16. WorkerCrypto interface</a><ul><li><a href="#WorkerCrypto-description">16.1. Description</a></li></ul></li><li><a href="#big-integer">17. BigInteger</a></li><li><a href="#keypair">18. CryptoKeyPair dictionary</a></li><li><a href="#algorithms">19. Algorithms</a><ul><li><a href="#algorithms-index">19.1. Registered algorithms</a></li><li><a href="#recommended-algorithms">19.2. Recommended algorithms</a></li><li><a href="#defining-an-algorithm">19.3. Defining an algorithm</a><ul><li><a href="#recognized-algorithm-name">19.3.1. Recognized algorithm name</a></li><li><a href="#supported-operations">19.3.2. Supported operations</a></li><li><a href="#algorithm-specific-params">19.3.3. Algorithm-specific parameters</a></li><li><a href="#algorithm-result">19.3.4. Algorithm results</a></li><li><a href="#algorithm-alias">19.3.5. Algorithm aliases</a></li></ul></li><li><a href="#rsassa-pkcs1">19.4. RSASSA-PKCS1-v1_5</a><ul><li><a href="#rsassa-pkcs1-description">19.4.1. Description</a></li><li><a href="#rsassa-pkcs1-registration">19.4.2. Registration</a></li><li><a href="#RsaHashedKeyGenParams-dictionary">19.4.3. RsaHashedKeyGenParams dictionary</a></li><li><a href="#RsaHashedKeyAlgorithm-dictionary">19.4.4. RsaHashedKeyAlgorithm dictionary</a></li><li><a href="#RsaHashedImportParams-dictionary">19.4.5. RsaHashedImportParams dictionary</a></li><li><a href="#rsassa-pkcs1-operations">19.4.6. Operations</a></li></ul></li><li><a href="#rsa-pss">19.5. RSA-PSS</a><ul><li><a href="#rsa-pss-description">19.5.1. Description</a></li><li><a href="#rsa-pss-registration">19.5.2. Registration</a></li><li><a href="#RsaPssParams-dictionary">19.5.3. RsaPssParams dictionary</a></li><li><a href="#rsa-pss-operations">19.5.4. Operations</a></li></ul></li><li><a href="#rsa-oaep">19.6. RSA-OAEP</a><ul><li><a href="#rsa-oaep-description">19.6.1. Description</a></li><li><a href="#rsa-oaep-registration">19.6.2. Registration</a></li><li><a href="#rsa-oaep-params">19.6.3. RsaOaepParams dictionary</a></li><li><a href="#rsa-oaep-operations">19.6.4. Operations</a></li></ul></li><li><a href="#ecdsa">19.7. ECDSA</a><ul><li><a href="#ecdsa-description">19.7.1. Description</a></li><li><a href="#ecdsa-registration">19.7.2. Registration</a></li><li><a href="#EcdsaParams-dictionary">19.7.3. EcdsaParams dictionary</a></li><li><a href="#EcKeyGenParams-dictionary">19.7.4. EcKeyGenParams dictionary</a></li><li><a href="#EcKeyAlgorithm-dictionary">19.7.5. EcKeyAlgorithm dictionary</a></li><li><a href="#EcKeyImportParams-dictionary">19.7.6. EcKeyImportParams dictionary</a></li><li><a href="#ecdsa-operations">19.7.7. Operations</a></li></ul></li><li><a href="#ecdh">19.8. ECDH</a><ul><li><a href="#ecdh-description">19.8.1. Description</a></li><li><a href="#ecdh-registration">19.8.2. Registration</a></li><li><a href="#dh-EcdhKeyDeriveParams">19.8.3. EcdhKeyDeriveParams dictionary</a></li><li><a href="#ecdh-operations">19.8.4. Operations</a></li></ul></li><li><a href="#aes-ctr">19.9. AES-CTR</a><ul><li><a href="#aes-ctr-description">19.9.1. Description</a></li><li><a href="#aes-ctr-registration">19.9.2. Registration</a></li><li><a href="#aes-ctr-params">19.9.3. AesCtrParams dictionary</a></li><li><a href="#AesKeyAlgorithm-dictionary">19.9.4. </a></li><li><a href="#aes-keygen-params">19.9.5. AesKeyGenParams dictionary</a></li><li><a href="#aes-derivedkey-params">19.9.6. AesDerivedKeyParams dictionary</a></li><li><a href="#aes-ctr-operations">19.9.7. Operations</a></li></ul></li><li><a href="#aes-cbc">19.10. AES-CBC</a><ul><li><a href="#aes-cbc-description">19.10.1. Description</a></li><li><a href="#aes-cbc-registration">19.10.2. Registration</a></li><li><a href="#aes-cbc-params">19.10.3. AesCbcParams dictionary</a></li><li><a href="#aes-cbc-operations">19.10.4. Operations</a></li></ul></li><li><a href="#aes-cmac">19.11. AES-CMAC</a><ul><li><a href="#aes-cmac-description">19.11.1. Description</a></li><li><a href="#aes-cmac-registration">19.11.2. Registration</a></li><li><a href="#aes-cmac-params">19.11.3. AesCmacParams dictionary</a></li><li><a href="#aes-cmac-operations">19.11.4. Operations</a></li></ul></li><li><a href="#aes-gcm">19.12. AES-GCM</a><ul><li><a href="#aes-gcm-description">19.12.1. Description</a></li><li><a href="#aes-gcm-registration">19.12.2. Registration</a></li><li><a href="#aes-gcm-params">19.12.3. AesGcmParams dictionary</a></li><li><a href="#aes-gcm-operations">19.12.4. Operations</a></li></ul></li><li><a href="#aes-cfb">19.13. AES-CFB</a><ul><li><a href="#aes-cfb-description">19.13.1. Description</a></li><li><a href="#aes-cfb-registration">19.13.2. Registration</a></li><li><a href="#aes-cfb-params">19.13.3. AesCfbParams dictionary</a></li><li><a href="#aes-cfb-operations">19.13.4. Operations</a></li></ul></li><li><a href="#aes-kw">19.14. AES-KW</a><ul><li><a href="#aes-kw-description">19.14.1. Description</a></li><li><a href="#aes-kw-registration">19.14.2. Registration</a></li><li><a href="#aes-kw-operations">19.14.3. Operations</a></li></ul></li><li><a href="#hmac">19.15. HMAC</a><ul><li><a href="#hmac-description">19.15.1. Description</a></li><li><a href="#hmac-registration">19.15.2. Registration</a></li><li><a href="#hmac-importparams">19.15.3. HmacImportParams dictionary</a></li><li><a href="#HmacKeyAlgorithm-dictionary">19.15.4. HmacKeyAlgorithm dictionary</a></li><li><a href="#hmac-keygen-params">19.15.5. HmacKeyGenParams dictionary</a></li><li><a href="#hmac-derivedkey-params">19.15.6. HmacDerivedKeyParams dictionary</a></li><li><a href="#hmac-operations">19.15.7. Operations</a></li></ul></li><li><a href="#dh">19.16. Diffie-Hellman</a><ul><li><a href="#dh-description">19.16.1. Description</a></li><li><a href="#dh-registration">19.16.2. Registration</a></li><li><a href="#dh-DhKeyGenParams">19.16.3. DhKeyGenParams dictionary</a></li><li><a href="#dh-DhKeyAlgorithm">19.16.4. DhKeyAlgorithm dictionary</a></li><li><a href="#dh-DhKeyDeriveParams">19.16.5. DhKeyDeriveParams dictionary</a></li><li><a href="#dh-DhImportKeyParams">19.16.6. DhImportKeyParams dictionary</a></li><li><a href="#dh-operations">19.16.7. Operations</a></li></ul></li><li><a href="#sha">19.17. SHA</a><ul><li><a href="#sha-description">19.17.1. Description</a></li><li><a href="#sha-registration">19.17.2. Registration</a></li><li><a href="#sha-operations">19.17.3. Operations</a></li></ul></li><li><a href="#concatkdf">19.18. Concat KDF</a><ul><li><a href="#concatkdf-description">19.18.1. Description</a></li><li><a href="#concatkdf-registration">19.18.2. Registration</a></li><li><a href="#concat-params">19.18.3. ConcatParams dictionary</a></li><li><a href="#concat-operations">19.18.4. Operations</a></li></ul></li><li><a href="#hkdf-ctr">19.19. HKDF-CTR</a><ul><li><a href="#hkdf-ctr-description">19.19.1. Description</a></li><li><a href="#hkdf-ctr-registration">19.19.2. Registration</a></li><li><a href="#hkdf-ctr-params">19.19.3. HkdfCtrParams dictionary</a></li><li><a href="#hkdf2-ctr-operations">19.19.4. Operations</a></li></ul></li><li><a href="#pbkdf2">19.20. PBKDF2</a><ul><li><a href="#pbkdf2-description">19.20.1. Description</a></li><li><a href="#pbkdf2-registration">19.20.2. Registration</a></li><li><a href="#pbkdf2-params">19.20.3. Pbkdf2Params dictionary</a></li><li><a href="#pbkdf2-operations">19.20.4. Operations</a></li></ul></li></ul></li><li><a href="#algorithm-normalizing-rules">20. Algorithm normalizing rules</a></li><li><a href="#examples-section">21. JavaScript Example Code</a><ul><li><a href="#examples-signing">21.1. Generate a signing key pair, sign some data</a></li><li><a href="#examples-symmetric-encryption">21.2. Symmetric Encryption</a></li></ul></li><li><a href="#iana-section">22. IANA Considerations</a><ul><li><a href="#iana-section-jws-jwa">22.1. JSON Web Signature and Encryption Algorithms Registration</a></li><li><a href="#iana-section-jwk">22.2. JSON Web Key Parameters Registration</a></li></ul></li><li><a href="#acknowledgements-section">23. Acknowledgements</a></li><li><a href="#references">24. References</a><ul><li><a href="#normative-references">24.1. Normative References</a></li><li><a href="#informative-references">24.2. Informative References</a></li></ul></li></ul><ul><li><a href="#jwk-mapping">A. Mapping between JSON Web Key / JSON Web Algorithm</a><ul><li><a href="#jwk-mapping-alg">A.1. Algorithm mappings</a></li><li><a href="#jwk-mapping-usage">A.2. Usage mapping</a></li></ul></li><li><a href="#spki-mapping">B. Mapping between Algorithm and SubjectPublicKeyInfo</a></li><li><a href="#pkcs8-mapping">C. Mapping between Algorithm and PKCS#8 PrivateKeyInfo</a></li></ul></div>
+ <div class="toc"><ul><li><a href="#introduction">1. Introduction</a></li><li><a href="#use-cases">2. Use Cases</a><ul><li><a href="#multifactor-authentication">2.1. Multi-factor Authentication</a></li><li><a href="#protected-document">2.2. Protected Document Exchange</a></li><li><a href="#cloud-storage">2.3. Cloud Storage</a></li><li><a href="#document-signing">2.4. Document Signing</a></li><li><a href="#data-integrity-protection">2.5. Data Integrity Protection</a></li><li><a href="#secure-messaging">2.6. Secure Messaging</a></li><li><a href="#jose">2.7. Javascript Object Signing and Encryption (JOSE)</a></li></ul></li><li><a href="#conformance">3. Conformance</a></li><li><a href="#scope">4. Scope</a><ul><li><a href="#scope-abstraction">4.1. Level of abstraction</a></li><li><a href="#scope-algorithms">4.2. Cryptographic algorithms</a></li><li><a href="#scope-operations">4.3. Operations</a></li><li><a href="#scope-out-of-scope">4.4. Out of scope</a></li></ul></li><li><a href="#concepts">5. Concepts</a><ul><li><a href="#concepts-underlying-implementation">5.1. Underlying Cryptographic Implementation</a></li><li><a href="#concepts-key-storage">5.2. Key Storage</a></li></ul></li><li><a href="#security">6. Security considerations</a><ul><li><a href="#security-implementers">6.1. Security considerations for implementers</a></li><li><a href="#security-developers">6.2. Security considerations for authors</a></li><li><a href="#security-users">6.3. Security considerations for users</a></li></ul></li><li><a href="#privacy">7. Privacy considerations</a></li><li><a href="#dependencies">8. Dependencies</a></li><li><a href="#terminology">9. Terminology</a></li><li><a href="#RandomSource-interface">10. RandomSource interface</a><ul><li><a href="#RandomSource-description">10.1. Description</a></li><li><a href="#RandomSource-interface-methods">10.2. Methods and Parameters</a><ul><li><a href="#RandomSource-method-getRandomValues">10.2.1. The getRandomValues method</a></li></ul></li></ul></li><li><a href="#algorithm-dictionary">11. Algorithm dictionary</a><ul><li><a href="#algorithm-dictionary-members">11.1. Algorithm Dictionary Members</a></li></ul></li><li><a href="#key-algorithm-dictionary">12. KeyAlgorithm dictionary</a><ul><li><a href="#key-algorithm-dictionary-description">12.1. Description</a></li><li><a href="#key-algorithm-dictionary-members">12.2. KeyAlgorithm dictionary members</a></li></ul></li><li><a href="#cryptokey-interface">13. CryptoKey interface</a><ul><li><a href="#cryptokey-interface-description">13.1. Description</a></li><li><a href="#cryptokey-interface-types">13.2. Key interface data types</a></li><li><a href="#cryptokey-interface-internal-slots">13.3. CryptoKey internal slots</a></li><li><a href="#cryptokey-interface-members">13.4. CryptoKey interface members</a></li><li><a href="#cryptokey-interface-clone">13.5. Structured clone algorithm</a></li></ul></li><li><a href="#crypto-interface">14. Crypto interface</a></li><li><a href="#subtlecrypto-interface">15. SubtleCrypto interface</a><ul><li><a href="#subtlecrypto-interface-description">15.1. Description</a></li><li><a href="#subtlecrypto-interface-datatypes">15.2. Data Types</a></li><li><a href="#subtlecrypto-interface-methods">15.3. Methods and Parameters</a><ul><li><a href="#SubtleCrypto-method-encrypt">15.3.1. The encrypt method</a></li><li><a href="#SubtleCrypto-method-decrypt">15.3.2. The decrypt method</a></li><li><a href="#SubtleCrypto-method-sign">15.3.3. The sign method</a></li><li><a href="#SubtleCrypto-method-verify">15.3.4. The verify method</a></li><li><a href="#SubtleCrypto-method-digest">15.3.5. The digest method</a></li><li><a href="#SubtleCrypto-method-generateKey">15.3.6. The generateKey method</a></li><li><a href="#SubtleCrypto-method-deriveKey">15.3.7. The deriveKey method</a></li><li><a href="#SubtleCrypto-method-deriveBits">15.3.8. The deriveBits method</a></li><li><a href="#SubtleCrypto-method-importKey">15.3.9. The importKey method</a></li><li><a href="#SubtleCrypto-method-exportKey">15.3.10. The exportKey method</a></li><li><a href="#SubtleCrypto-method-wrapKey">15.3.11. The wrapKey method</a></li><li><a href="#SubtleCrypto-method-unwrapKey">15.3.12. The unwrapKey method</a></li></ul></li><li><a href="#SubtleCrypto-Exceptions">15.4. Exceptions</a></li></ul></li><li><a href="#JsonWebKey-dictionary">16. JsonWebKey dictionary</a></li><li><a href="#WorkerCrypto-interface">17. WorkerCrypto interface</a><ul><li><a href="#WorkerCrypto-description">17.1. Description</a></li></ul></li><li><a href="#big-integer">18. BigInteger</a></li><li><a href="#keypair">19. CryptoKeyPair dictionary</a></li><li><a href="#algorithms">20. Algorithms</a><ul><li><a href="#algorithms-index">20.1. Registered algorithms</a></li><li><a href="#recommended-algorithms">20.2. Recommended algorithms</a></li><li><a href="#defining-an-algorithm">20.3. Defining an algorithm</a><ul><li><a href="#recognized-algorithm-name">20.3.1. Recognized algorithm name</a></li><li><a href="#supported-operations">20.3.2. Supported operations</a></li><li><a href="#algorithm-specific-params">20.3.3. Algorithm-specific parameters</a></li><li><a href="#algorithm-result">20.3.4. Algorithm results</a></li><li><a href="#algorithm-alias">20.3.5. Algorithm aliases</a></li></ul></li><li><a href="#rsassa-pkcs1">20.4. RSASSA-PKCS1-v1_5</a><ul><li><a href="#rsassa-pkcs1-description">20.4.1. Description</a></li><li><a href="#rsassa-pkcs1-registration">20.4.2. Registration</a></li><li><a href="#RsaHashedKeyGenParams-dictionary">20.4.3. RsaHashedKeyGenParams dictionary</a></li><li><a href="#RsaHashedKeyAlgorithm-dictionary">20.4.4. RsaHashedKeyAlgorithm dictionary</a></li><li><a href="#RsaHashedImportParams-dictionary">20.4.5. RsaHashedImportParams dictionary</a></li><li><a href="#rsassa-pkcs1-operations">20.4.6. Operations</a></li></ul></li><li><a href="#rsa-pss">20.5. RSA-PSS</a><ul><li><a href="#rsa-pss-description">20.5.1. Description</a></li><li><a href="#rsa-pss-registration">20.5.2. Registration</a></li><li><a href="#RsaPssParams-dictionary">20.5.3. RsaPssParams dictionary</a></li><li><a href="#rsa-pss-operations">20.5.4. Operations</a></li></ul></li><li><a href="#rsa-oaep">20.6. RSA-OAEP</a><ul><li><a href="#rsa-oaep-description">20.6.1. Description</a></li><li><a href="#rsa-oaep-registration">20.6.2. Registration</a></li><li><a href="#rsa-oaep-params">20.6.3. RsaOaepParams dictionary</a></li><li><a href="#rsa-oaep-operations">20.6.4. Operations</a></li></ul></li><li><a href="#ecdsa">20.7. ECDSA</a><ul><li><a href="#ecdsa-description">20.7.1. Description</a></li><li><a href="#ecdsa-registration">20.7.2. Registration</a></li><li><a href="#EcdsaParams-dictionary">20.7.3. EcdsaParams dictionary</a></li><li><a href="#EcKeyGenParams-dictionary">20.7.4. EcKeyGenParams dictionary</a></li><li><a href="#EcKeyAlgorithm-dictionary">20.7.5. EcKeyAlgorithm dictionary</a></li><li><a href="#EcKeyImportParams-dictionary">20.7.6. EcKeyImportParams dictionary</a></li><li><a href="#ecdsa-operations">20.7.7. Operations</a></li></ul></li><li><a href="#ecdh">20.8. ECDH</a><ul><li><a href="#ecdh-description">20.8.1. Description</a></li><li><a href="#ecdh-registration">20.8.2. Registration</a></li><li><a href="#dh-EcdhKeyDeriveParams">20.8.3. EcdhKeyDeriveParams dictionary</a></li><li><a href="#ecdh-operations">20.8.4. Operations</a></li></ul></li><li><a href="#aes-ctr">20.9. AES-CTR</a><ul><li><a href="#aes-ctr-description">20.9.1. Description</a></li><li><a href="#aes-ctr-registration">20.9.2. Registration</a></li><li><a href="#aes-ctr-params">20.9.3. AesCtrParams dictionary</a></li><li><a href="#AesKeyAlgorithm-dictionary">20.9.4. </a></li><li><a href="#aes-keygen-params">20.9.5. AesKeyGenParams dictionary</a></li><li><a href="#aes-derivedkey-params">20.9.6. AesDerivedKeyParams dictionary</a></li><li><a href="#aes-ctr-operations">20.9.7. Operations</a></li></ul></li><li><a href="#aes-cbc">20.10. AES-CBC</a><ul><li><a href="#aes-cbc-description">20.10.1. Description</a></li><li><a href="#aes-cbc-registration">20.10.2. Registration</a></li><li><a href="#aes-cbc-params">20.10.3. AesCbcParams dictionary</a></li><li><a href="#aes-cbc-operations">20.10.4. Operations</a></li></ul></li><li><a href="#aes-cmac">20.11. AES-CMAC</a><ul><li><a href="#aes-cmac-description">20.11.1. Description</a></li><li><a href="#aes-cmac-registration">20.11.2. Registration</a></li><li><a href="#aes-cmac-params">20.11.3. AesCmacParams dictionary</a></li><li><a href="#aes-cmac-operations">20.11.4. Operations</a></li></ul></li><li><a href="#aes-gcm">20.12. AES-GCM</a><ul><li><a href="#aes-gcm-description">20.12.1. Description</a></li><li><a href="#aes-gcm-registration">20.12.2. Registration</a></li><li><a href="#aes-gcm-params">20.12.3. AesGcmParams dictionary</a></li><li><a href="#aes-gcm-operations">20.12.4. Operations</a></li></ul></li><li><a href="#aes-cfb">20.13. AES-CFB</a><ul><li><a href="#aes-cfb-description">20.13.1. Description</a></li><li><a href="#aes-cfb-registration">20.13.2. Registration</a></li><li><a href="#aes-cfb-params">20.13.3. AesCfbParams dictionary</a></li><li><a href="#aes-cfb-operations">20.13.4. Operations</a></li></ul></li><li><a href="#aes-kw">20.14. AES-KW</a><ul><li><a href="#aes-kw-description">20.14.1. Description</a></li><li><a href="#aes-kw-registration">20.14.2. Registration</a></li><li><a href="#aes-kw-operations">20.14.3. Operations</a></li></ul></li><li><a href="#hmac">20.15. HMAC</a><ul><li><a href="#hmac-description">20.15.1. Description</a></li><li><a href="#hmac-registration">20.15.2. Registration</a></li><li><a href="#hmac-importparams">20.15.3. HmacImportParams dictionary</a></li><li><a href="#HmacKeyAlgorithm-dictionary">20.15.4. HmacKeyAlgorithm dictionary</a></li><li><a href="#hmac-keygen-params">20.15.5. HmacKeyGenParams dictionary</a></li><li><a href="#hmac-derivedkey-params">20.15.6. HmacDerivedKeyParams dictionary</a></li><li><a href="#hmac-operations">20.15.7. Operations</a></li></ul></li><li><a href="#dh">20.16. Diffie-Hellman</a><ul><li><a href="#dh-description">20.16.1. Description</a></li><li><a href="#dh-registration">20.16.2. Registration</a></li><li><a href="#dh-DhKeyGenParams">20.16.3. DhKeyGenParams dictionary</a></li><li><a href="#dh-DhKeyAlgorithm">20.16.4. DhKeyAlgorithm dictionary</a></li><li><a href="#dh-DhKeyDeriveParams">20.16.5. DhKeyDeriveParams dictionary</a></li><li><a href="#dh-DhImportKeyParams">20.16.6. DhImportKeyParams dictionary</a></li><li><a href="#dh-operations">20.16.7. Operations</a></li></ul></li><li><a href="#sha">20.17. SHA</a><ul><li><a href="#sha-description">20.17.1. Description</a></li><li><a href="#sha-registration">20.17.2. Registration</a></li><li><a href="#sha-operations">20.17.3. Operations</a></li></ul></li><li><a href="#concatkdf">20.18. Concat KDF</a><ul><li><a href="#concatkdf-description">20.18.1. Description</a></li><li><a href="#concatkdf-registration">20.18.2. Registration</a></li><li><a href="#concat-params">20.18.3. ConcatParams dictionary</a></li><li><a href="#concat-operations">20.18.4. Operations</a></li></ul></li><li><a href="#hkdf-ctr">20.19. HKDF-CTR</a><ul><li><a href="#hkdf-ctr-description">20.19.1. Description</a></li><li><a href="#hkdf-ctr-registration">20.19.2. Registration</a></li><li><a href="#hkdf-ctr-params">20.19.3. HkdfCtrParams dictionary</a></li><li><a href="#hkdf2-ctr-operations">20.19.4. Operations</a></li></ul></li><li><a href="#pbkdf2">20.20. PBKDF2</a><ul><li><a href="#pbkdf2-description">20.20.1. Description</a></li><li><a href="#pbkdf2-registration">20.20.2. Registration</a></li><li><a href="#pbkdf2-params">20.20.3. Pbkdf2Params dictionary</a></li><li><a href="#pbkdf2-operations">20.20.4. Operations</a></li></ul></li></ul></li><li><a href="#algorithm-normalizing-rules">21. Algorithm normalizing rules</a></li><li><a href="#examples-section">22. JavaScript Example Code</a><ul><li><a href="#examples-signing">22.1. Generate a signing key pair, sign some data</a></li><li><a href="#examples-symmetric-encryption">22.2. Symmetric Encryption</a></li></ul></li><li><a href="#iana-section">23. IANA Considerations</a><ul><li><a href="#iana-section-jws-jwa">23.1. JSON Web Signature and Encryption Algorithms Registration</a></li><li><a href="#iana-section-jwk">23.2. JSON Web Key Parameters Registration</a></li></ul></li><li><a href="#acknowledgements-section">24. Acknowledgements</a></li><li><a href="#references">25. References</a><ul><li><a href="#normative-references">25.1. Normative References</a></li><li><a href="#informative-references">25.2. Informative References</a></li></ul></li></ul><ul><li><a href="#jwk-mapping">A. Mapping between JSON Web Key / JSON Web Algorithm</a><ul><li><a href="#jwk-mapping-alg">A.1. Algorithm mappings</a></li><li><a href="#jwk-mapping-usage">A.2. Usage mapping</a></li></ul></li><li><a href="#spki-mapping">B. Mapping between Algorithm and SubjectPublicKeyInfo</a></li><li><a href="#pkcs8-mapping">C. Mapping between Algorithm and PKCS#8 PrivateKeyInfo</a></li></ul></div>
</div>
<div id="sections">
@@ -393,123 +393,208 @@
</div>
</div>
+
+ <div class="section" id="concepts">
+ <h2>5. Concepts</h2>
+ <p class="norm">This section is non-normative.</p>
+ <div class="section" id="concepts-underlying-implementation">
+ <h3>5.1. 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 <a href="#dfn-CryptoKey">CryptoKey</a> object represents the bridge between the
+ JavaScript execution environment and these underlying libraries, through the use of the
+ internal slot named [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]]. 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
+ <a href="#dfn-CryptoKey">CryptoKey</a> object is the conceptual equivalent to the
+ JavaScript executing environment as the
+ [[<a href="#dfn-CryptoKey-slot-handle">handle</a>]] 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>
+ </div>
+ <div class="section" id="concepts-key-storage">
+ <h3>5.2. Key Storage</h3>
+ <p>
+ This specification does not explicitly provide any new storage mechanisms for
+ <a href="#dfn-CryptoKey">CryptoKey</a> objects. Instead, by allowing the
+ <a href="#dfn-CryptoKey">CryptoKey</a> to be used with the structured clone algorithm,
+ any existing or future web storage mechanisms that support storing structured clonable
+ objects can be used to store <a href="#dfn-CryptoKey">CryptoKey</a> objects.
+ </p>
+ <p>
+ In practice, it is expected that most authors will make use of the
+ <a href="#IndexedDB">Indexed Database API</a>, which allows associative storage of
+ key/value pairs, where the key is some string identifier meaningful to the application,
+ and the value is a <a href="#dfn-CryptoKey">CryptoKey</a> 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
+ <a href="#dfn-CryptoKey">CryptoKey</a> itself.
+ </p>
+ </div>
+ </div>
+
<div id="security" class="section">
- <h2>5. Security considerations</h2>
+ <h2>6. Security considerations</h2>
<p class="norm">This section is non-normative.</p>
<div id="security-implementers" class="section">
- <h2>5.1. Security considerations for implementers</h2>
- <p>
- User agents should take care before exposing keys that were not explicitly generated
- via the API in this specification or exposing keys that were generated in the
- context of other origins. Two applications with access to the same key handle may be
- able to spoof messages to each other, as both valid and hostile messages will appear
- to be valid for the given key. Because of this, user agents are recommended to obtain
- express permission from the user before re-using keys, unless there is a prearranged
- trust relationship.
- </p>
- <p>
- User agents should be aware of the security considerations of each algorithm
- implemented and exposed to applications. For a number of algorithms, their
- cryptographic strength is relative to the amount of work necessary to compute the
- result, whether this be through the generation of significantly large prime numbers or
- through the repeatedly iterating through the same algorithm to reduce its
- susceptibility to brute force. Implementations should therefore take measures to
- ensure against misuse. Such measures may include requiring express user permission to
- compute some expensive operations, rate limiting the number of times the application
- may call certain APIs/algorithms, and defining implementation-specific upper limits
- for inputs such as key sizes or iteration counts, as appropriate for the device on
- which the implementation executes.
- </p>
- <p>
- In some cases, the same underlying cryptographic key material may be re-usable for
- multiple algorithms. One such example is an RSA key, which may be used for both
- signing and encryption, or with RSA-PKCS1v1.5 and RSA-PSS. In some cases, the re-use
- of this key material may undermine the security properties of the key and allow
- applications to recover the raw material.
- </p>
- <div class="ednote"><div class="ednoteHeader">Editorial note</div>
- <ul>
- <li>
- <a href="https://www.w3.org/2012/webcrypto/track/issues/33">ISSUE-33</a>
- One proposed technical solution for user agents is to implement "key tainting", in
- which it records how a particular key has been used (eg: algorithms, parameters),
- and prevents it from being re-used in a manner that is unsafe or contrary to the
- security - such as preventing a PKCS1-v1.5 key from being used with RSA-PSS, or
- preventing an RSA-OAEP w/ MGF1-SHA1 from being used with RSA-OAEP w/ MGF1-SHA256.
- Questions exist about whether this should be encouraged or permitted, and the
- interoperability concerns it might cause.
- </li>
- </ul>
- </div>
+ <h2>6.1. Security considerations for implementers</h2>
+ <p>
+ By not providing an explicit storage mechanism, this specification assumes that
+ <a href="#dfn-CryptoKey">CryptoKey</a> objects are scoped to the current execution
+ environment and any storage mechanisms available to that environment (e.g.
+ <a href="#IndexedDB">Indexed Database API</a>). Application authors rely upon this for
+ the security of their applications; two origins with the same
+ <a href="#dfn-CryptoKey">CryptoKey</a> 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
+ <a href="#dfn-CryptoKey">CryptoKey</a> 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>
</div>
<div id="security-developers" class="section">
- <h2>5.2. Security considerations for authors</h2>
- <p>
- While this API provides important functionality for the development of secure
- applications, it does not attempt to provide a mitigation for existing threats to
- the web security model, such as script injection or hostile intermediaries. As such,
- application developers must take care to ensure applications are secured against
- common and traditional attacks, such as script injection, by making use of appropriate
- existing functionality such as Content Security Policy and the use of TLS.
- </p>
- <p>
- This API includes a variety of cryptographic operations, some of which may have known
- security issues when used inappropriately. Application developers should take care to
- review the appropriate cryptographic literature before making use of certain algorithms,
- and should avoid attempting to develop new cryptographic protocols whenever possible.
- </p>
- <p>
- While the API in this specification provides a means to protect keys from future access
- by web applications, it makes no statements as to how the actual keying material will be
- stored by an implementation. As such, although a key may be inaccessible to web content,
- it should not be presumed that it is inaccessible to end-users. For example, a
- conforming user agent may choose to implement key storage by storing key material in
- plain text on device storage. Although the user agent prevents access to the raw keying
- material to web applications, any user with access to device storage may be able to
- recover the key.
+ <h2>6.2. 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 <a href="#IndexedDB">Indexed Database API</a>, 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 <code>postMessage</code>.
+ </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
+ <a href="#dfn-SubtleCrypto-method-exportKey">exportKey</a> and <a href="#dfn-SubtleCrypto-method-wrapKey">wrapKey</a> 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 <a href="#dfn-CryptoKey">CryptoKey</a>
+ have gone away.
+ </p>
+ <p>
+ Applications may share a <a href="#dfn-CryptoKey">CryptoKey</a> object across security
+ boundaries, such as origins, through the use of the structured clone algorithm and APIs
+ such as <code>postMessage</code>. While access to the underlying cryptographic key
+ material may be restricted, based upon the <a href="#dfn-CryptoKey-extractable">extractable</a>
+ 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>
+ </div>
+ <div class="section" id="security-users">
+ <h3>6.3. 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>
</div>
</div>
<div id="privacy" class="section">
- <h2>6. Privacy considerations</h2>
+ <h2>7. Privacy considerations</h2>
<p class="norm">This section is non-normative.</p>
<dl>
<dt>Fingerprinting</dt>
<dd>
- Malicious applications may be able to fingerprint users or user agents by detecting or
- enumerating the list of algorithms that are supported. This is especially true if an
- implementation exposes details about users' smart cards or secure element storage, as
- the combination of algorithms supported by such devices may be used to fingerprint
- devices more accurately than just the particular user agent.
- </dd>
- <dt>Tracking</dt>
- <dd>
- If user agents permit keys to be re-used between origins, without performing any
- secondary operations such as key derivation that includes the origin, then it may be
- possible for two origins to collude and track a unique user by recording their ability
- to access a common key.
+ 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>
- With the exception of ephemeral keys, its often desirable for applications to strongly
- associate users with keys. These associations may be used to enhance the security of
- authenticating to the application, such as using a key stored in a secure element as a
- second factor, or may be used by users to assert some identity, such as an e-mail
- signing identity. As such, these keys often live longer than their counterparts such as
- usernames and passwords, and it may be undesirable or prohibitive for users to revoke
- these keys.
- Because of this, keys may exist longer than the lifetime of the browsing context
- [<a href="#HTML">HTML</a>] and beyond the lifetime of items such as cookies, thus
- presenting a risk that a user may be tracked even after clearing such data. This is
- especially true for keys that were pre-provisioned for particular origins and for which
- no user interaction was provided.
+ 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>
</dl>
</div>
<div id="dependencies" class="section">
- <h3>7. Dependencies</h3>
+ <h3>8. Dependencies</h3>
<p>This specification relies on underlying specifications.</p>
<dl>
<dt>DOM</dt>
@@ -545,7 +630,7 @@
</div>
<div id="terminology" class="section">
- <h2>8. Terminology</h2>
+ <h2>9. Terminology</h2>
<p>
The terms and algorithms
<dfn id="arraybufferview">ArrayBufferView</dfn>, and
@@ -759,7 +844,7 @@
</div>
<div id="RandomSource-interface" class="section">
- <h2>9. RandomSource interface</h2>
+ <h2>10. RandomSource interface</h2>
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
[NoInterfaceObject]
interface <dfn id="dfn-RandomSource">RandomSource</dfn> {
@@ -767,7 +852,7 @@
};
</code></pre></div></div>
<div id="RandomSource-description" class="section">
- <h3>9.1. Description</h3>
+ <h3>10.1. Description</h3>
<p>
The <a href="#dfn-RandomSource">RandomSource</a> interface represents an interface to a
cryptographically strong pseudo-random number generator seeded with truly random values.
@@ -791,9 +876,9 @@
</div>
</div>
<div id="RandomSource-interface-methods" class="section">
- <h3>9.2. Methods and Parameters</h3>
+ <h3>10.2. Methods and Parameters</h3>
<div id="RandomSource-method-getRandomValues" class="section">
- <h4>9.2.1. The getRandomValues method</h4>
+ <h4>10.2.1. The getRandomValues method</h4>
<p>
The <dfn id="dfn-RandomSource-method-getRandomValues"><code>getRandomValues</code></dfn>
method generates cryptographically random values. It must act as follows:
@@ -838,7 +923,7 @@
</div>
<div id="algorithm-dictionary" class="section">
- <h2>10. Algorithm dictionary</h2>
+ <h2>11. Algorithm dictionary</h2>
<p>
The Algorithm object is a dictionary object [<cite><a href="#WebIDL">WEBIDL</a></cite>]
which is used to specify an algorithm and any additional parameters required to fully
@@ -853,7 +938,7 @@
};
</code></pre></div></div>
<div id="algorithm-dictionary-members" class="section">
- <h3>10.1. <a href="#dfn-Algorithm">Algorithm</a> Dictionary Members</h3>
+ <h3>11.1. <a href="#dfn-Algorithm">Algorithm</a> Dictionary Members</h3>
<dl>
<dt id="dfn-Algorithm-name">
<code>name</code>
@@ -866,7 +951,7 @@
</div>
<div id="key-algorithm-dictionary" class="section">
- <h2>11. KeyAlgorithm dictionary</h2>
+ <h2>12. KeyAlgorithm dictionary</h2>
<p>
The KeyAlgorithm dictionary represents information about the contents of a given
<a href="#dfn-CryptoKey">CryptoKey</a> object.
@@ -877,7 +962,7 @@
};
</code></pre></div></div>
<div id="key-algorithm-dictionary-description" class="section">
- <h3>11.1. Description</h3>
+ <h3>12.1. Description</h3>
<p class="norm">This section is non-normative</p>
<p>
The <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a> dictionary is provided to aid in
@@ -887,7 +972,7 @@
</p>
</div>
<div id="key-algorithm-dictionary-members" class="section">
- <h3>11.2. KeyAlgorithm dictionary members</h3>
+ <h3>12.2. KeyAlgorithm dictionary members</h3>
<dl>
<dt id="dfn-KeyAlgorithm-name">name</dt>
<dd>
@@ -898,7 +983,7 @@
</div>
<div id="cryptokey-interface" class="section">
- <h2>12. CryptoKey interface</h2>
+ <h2>13. CryptoKey interface</h2>
<p>
The CryptoKey object represents an opaque reference to keying material that is managed by
the user agent.
@@ -916,7 +1001,7 @@
};
</code></pre></div></div>
<div id="cryptokey-interface-description" class="section">
- <h3>12.1. Description</h3>
+ <h3>13.1. Description</h3>
<p class="norm">This section is non-normative</p>
<p>
This specification provides a uniform interface for many different kinds of keying
@@ -936,7 +1021,7 @@
</div>
<div id="cryptokey-interface-types" class="section">
- <h3>12.2. Key interface data types</h3>
+ <h3>13.2. Key interface data types</h3>
<dl>
<dt id="dfn-KeyType"><code>KeyType</code></dt>
<dd>
@@ -963,7 +1048,7 @@
</div>
<div id="cryptokey-interface-internal-slots" class="section">
- <h3>12.3. CryptoKey internal slots</h3>
+ <h3>13.3. CryptoKey internal slots</h3>
<p>
Every <code>CryptoKey</code> object has a set of internal slots that store information
about the key. These slots are not exposed as part of this specification; they
@@ -984,7 +1069,7 @@
</div>
<div id="cryptokey-interface-members" class="section">
- <h3>12.4. CryptoKey interface members</h3>
+ <h3>13.4. CryptoKey interface members</h3>
<dl>
<dt id="dfn-CryptoKey-type"><code>type</code></dt>
<dd>
@@ -1014,7 +1099,7 @@
</div>
<div id="cryptokey-interface-clone" class="section">
- <h3>12.5. Structured clone algorithm</h3>
+ <h3>13.5. Structured clone algorithm</h3>
<p>
When a user agent is required to obtain a <a href="#structured-clone">structured clone</a>
of a <a href="#dfn-CryptoKey">CryptoKey</a> object, it must run the following steps.
@@ -1056,7 +1141,7 @@
</div>
<div id="crypto-interface" class="section">
- <h2>13. Crypto interface</h2>
+ <h2>14. Crypto interface</h2>
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
interface <dfn id="dfn-Crypto">Crypto</dfn> {
readonly attribute <a href="#dfn-SubtleCrypto">SubtleCrypto</a> subtle;
@@ -1071,7 +1156,7 @@
</div>
<div id="subtlecrypto-interface" class="section">
- <h2>14. SubtleCrypto interface</h2>
+ <h2>15. SubtleCrypto interface</h2>
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
typedef DOMString <a href="#dfn-KeyFormat"><code>KeyFormat</code></a>;
@@ -1140,7 +1225,7 @@
</ul>
</div>
<div id="subtlecrypto-interface-description" class="section">
- <h3>14.1. Description</h3>
+ <h3>15.1. Description</h3>
<p class="norm">This section is non-normative.</p>
<p>
The <a href="#dfn-SubtleCrypto">SubtleCrypto</a> interface provides a set of
@@ -1169,7 +1254,7 @@
</div>
<div id="subtlecrypto-interface-datatypes" class="section">
- <h3>14.2. Data Types</h3>
+ <h3>15.2. Data Types</h3>
<dl>
<dt id="dfn-KeyFormat"><code>KeyFormat</code></dt>
<dd>
@@ -1189,7 +1274,7 @@
</div>
<div id="subtlecrypto-interface-methods" class="section">
- <h3>14.3. Methods and Parameters</h3>
+ <h3>15.3. Methods and Parameters</h3>
<div class="note"><div class="noteHeader">Note</div>
<p>
All errors are reported asynchronously by calling the reject handler of the returned
@@ -1197,7 +1282,7 @@
</p>
</div>
<div id="SubtleCrypto-method-encrypt" class="section">
- <h4>14.3.1. The encrypt method</h4>
+ <h4>15.3.1. The encrypt method</h4>
<p>
The <dfn id="dfn-SubtleCrypto-method-encrypt"><code>encrypt</code></dfn>
method returns a new Promise object that will encrypt data using
@@ -1287,7 +1372,7 @@
</div>
<div id="SubtleCrypto-method-decrypt" class="section">
- <h4>14.3.2. The decrypt method</h4>
+ <h4>15.3.2. The decrypt method</h4>
<p>
The <dfn id="dfn-SubtleCrypto-method-decrypt"><code>decrypt</code></dfn>
method returns a new Promise object that will decrypt data using the specified
@@ -1377,7 +1462,7 @@
</div>
<div id="SubtleCrypto-method-sign" class="section">
- <h4>14.3.3. The sign method</h4>
+ <h4>15.3.3. The sign method</h4>
<p>
The <dfn id="dfn-SubtleCrypto-method-sign"><code>sign</code></dfn> method returns a
new Promise object that will sign data using the specified <a href="#dfn-AlgorithmIdentifier"><code>AlgorithmIdentifier</code></a> with the supplied
@@ -1464,7 +1549,7 @@
</div>
<div id="SubtleCrypto-method-verify" class="section">
- <h4>14.3.4. The verify method</h4>
+ <h4>15.3.4. The verify method</h4>
<p>
The <dfn id="dfn-SubtleCrypto-method-verify"><code>verify</code></dfn> method returns
a new Promise object that will verify data using the specified <a href="#dfn-AlgorithmIdentifier"><code>AlgorithmIdentifier</code></a> with the supplied
@@ -1558,7 +1643,7 @@
</div>
<div id="SubtleCrypto-method-digest" class="section">
- <h4>14.3.5. The digest method</h4>
+ <h4>15.3.5. The digest method</h4>
<p>
The <dfn id="dfn-SubtleCrypto-method-digest"><code>digest</code></dfn> method returns
a new Promise object that will digest data using the specified
@@ -1639,7 +1724,7 @@
</div>
<div id="SubtleCrypto-method-generateKey" class="section">
- <h4>14.3.6. The generateKey method</h4>
+ <h4>15.3.6. The generateKey method</h4>
<p>
When invoked, <dfn id="dfn-SubtleCrypto-method-generateKey">
<code>generateKey</code></dfn> <span class="RFC2119">MUST</span> perform the
@@ -1722,7 +1807,7 @@
</div>
<div id="SubtleCrypto-method-deriveKey" class="section">
- <h4>14.3.7. The deriveKey method</h4>
+ <h4>15.3.7. The deriveKey method</h4>
<p>
When invoked, <dfn id="dfn-SubtleCrypto-method-deriveKey"><code>deriveKey</code></dfn>
<span class="RFC2119">MUST</span> perform the following steps:
@@ -1845,7 +1930,7 @@
</div>
<div id="SubtleCrypto-method-deriveBits" class="section">
- <h4>14.3.8. The deriveBits method</h4>
+ <h4>15.3.8. The deriveBits method</h4>
<p>
When invoked, <dfn id="dfn-SubtleCrypto-method-deriveBits"><code>deriveBits</code></dfn>
<span class="RFC2119">MUST</span> perform the following steps:
@@ -1928,7 +2013,7 @@
</div>
<div id="SubtleCrypto-method-importKey" class="section">
- <h4>14.3.9. The <a href="#dfn-SubtleCrypto-method-importKey">importKey</a> method</h4>
+ <h4>15.3.9. The <a href="#dfn-SubtleCrypto-method-importKey">importKey</a> method</h4>
<p>
When invoked, the <dfn id="dfn-SubtleCrypto-method-importKey"><code>importKey</code></dfn> method <span class="RFC2119">MUST</span> perform the following steps:
</p>
@@ -2043,7 +2128,7 @@
</div>
<div id="SubtleCrypto-method-exportKey" class="section">
- <h4>14.3.10. The <a href="#dfn-SubtleCrypto-method-exportKey">exportKey</a> method</h4>
+ <h4>15.3.10. The <a href="#dfn-SubtleCrypto-method-exportKey">exportKey</a> method</h4>
<p>
When invoked, the <dfn id="dfn-SubtleCrypto-method-exportKey"><code>exportKey</code></dfn> method <span class="RFC2119">MUST</span> perform the following steps:
</p>
@@ -2128,7 +2213,7 @@
</div>
<div id="SubtleCrypto-method-wrapKey" class="section">
- <h4>14.3.11. The wrapKey method</h4>
+ <h4>15.3.11. The wrapKey method</h4>
<p>
When invoked, the <dfn id="dfn-SubtleCrypto-method-wrapKey">wrapKey</dfn> method <span class="RFC2119">MUST</span> perform the following steps:
</p>
@@ -2309,7 +2394,7 @@
</div>
<div id="SubtleCrypto-method-unwrapKey" class="section">
- <h4>14.3.12. The unwrapKey method</h4>
+ <h4>15.3.12. The unwrapKey method</h4>
<p>
When invoked, the <dfn id="dfn-SubtleCrypto-method-unwrapKey">unwrapKey</dfn> method
<span class="RFC2119">MUST</span> perform the following steps:
@@ -2484,7 +2569,7 @@
</div>
</div>
<div id="SubtleCrypto-Exceptions" class="section">
- <h3>14.4. Exceptions</h3>
+ <h3>15.4. Exceptions</h3>
<p>
The methods of the <a href="#dfn-SubtleCrypto">SubtleCrypto</a> interface return errors
by calling the reject handler of the returned promise with a
@@ -2550,7 +2635,7 @@
</div>
<div id="JsonWebKey-dictionary" class="section">
- <h2>15. JsonWebKey dictionary</h2>
+ <h2>16. JsonWebKey dictionary</h2>
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
dictionary <dfn id="dfn-RsaOtherPrimesInfo">RsaOtherPrimesInfo</dfn> {
<span class="comment">// The following fields are defined in Section 6.3.2.7 of <a href="#jwa">JSON Web Algorithms</a></span>
@@ -2598,7 +2683,7 @@
</div>
<div id="WorkerCrypto-interface" class="section">
- <h2>16. WorkerCrypto interface</h2>
+ <h2>17. WorkerCrypto interface</h2>
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
interface <dfn id="dfn-WorkerCrypto">WorkerCrypto</dfn> {
readonly attribute <a href="#dfn-SubtleCrypto">SubtleCrypto</a> <dfn id="dfn-WorkerCrypto-subtle">subtle</dfn>;
@@ -2611,7 +2696,7 @@
};
</code></pre></div></div>
<div id="WorkerCrypto-description" class="section">
- <h3>16.1. Description</h3>
+ <h3>17.1. Description</h3>
<p>
The <a href="#dfn-WorkerCrypto">WorkerCrypto</a> interface provides cryptographic
functionality for background scripts, as specified by Web Workers [
@@ -2621,7 +2706,7 @@
</div>
<div id="big-integer" class="section">
- <h2>17. BigInteger</h2>
+ <h2>18. BigInteger</h2>
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
typedef Uint8Array <dfn id="dfn-BigInteger">BigInteger</dfn>;
</code></pre></div></div>
@@ -2641,7 +2726,7 @@
</div>
<div id="keypair" class="section">
- <h2>18. CryptoKeyPair dictionary</h2>
+ <h2>19. CryptoKeyPair dictionary</h2>
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
dictionary <dfn id="dfn-CryptoKeyPair">CryptoKeyPair</dfn> {
<a href="#dfn-CryptoKey">CryptoKey</a> <dfn id="dfn-CryptoKey-publicKey">publicKey</dfn>;
@@ -2655,7 +2740,7 @@
</div>
<div id="algorithms" class="section">
- <h2>19. Algorithms</h2>
+ <h2>20. Algorithms</h2>
<div class="ednote"><div class="ednoteHeader">Editorial note</div>
<p>
Note: All algorithms listed should be considered as "features at risk",
@@ -2670,7 +2755,7 @@
</p>
</div>
<div id="algorithms-index" class="section">
- <h3>19.1. Registered algorithms</h3>
+ <h3>20.1. Registered algorithms</h3>
<table>
<thead>
<tr>
@@ -2994,17 +3079,28 @@
</table>
</div>
<div id="recommended-algorithms" class="section">
- <h3>19.2. Recommended algorithms</h3>
+ <h3>20.2. Recommended algorithms</h3>
<p class="norm">This section is non-normative</p>
<p>
As the API is meant to be extensible in order to keep up with future developments within
cryptography and to provide flexibility, there are no strictly required algorithms. Thus
users of this API should check to see what algorithms are currently recommended and
- supported by implementations.
- </p>
- <p>
- However, in order to promote interoperability for developers, there are a number of
- recommended algorithms. The recommended algorithms are:
+ supported by implementations. As highlighted in the <a href="#security">Security
+ Considerations</a>, even strong cryptographic algorithms may be combined in insecure
+ ways. Users should therefore proceed with extreme caution when inventing new
+ cryptographic protocols.
+ </p>
+ <p>
+ Implementers should carefully review their support for different algorithms based on the
+ evolving state of the cryptographic literature. It is expected that the set of
+ widely-accepted algorithms will change over time as new advances are made.
+ </p>
+ <p>
+ With the above caveats in mind, in order to promote interoperability for developers,
+ this specification includes a list of suggested algorithms. These are considered to be
+ the most widely used algorithms in practice at the time of writing, and therefore
+ provide a good starting point for initial implementations of this specification. The
+ suggested algorithms are:
</p>
<ul>
<li>
@@ -3037,7 +3133,7 @@
</p>
</div>
<div id="defining-an-algorithm" class="section">
- <h3>19.3. Defining an algorithm</h3>
+ <h3>20.3. Defining an algorithm</h3>
<p>
Each algorithm that is to be exposed via the Web Cryptography API
<span class="RFC2119">SHOULD</span> be registered via the Web Cryptography working group,
@@ -3046,7 +3142,7 @@
<span class="RFC2119">MUST</span> be processed as if the sections had been defined.
</p>
<div id="recognized-algorithm-name" class="section">
- <h4>19.3.1. Recognized algorithm name</h4>
+ <h4>20.3.1. Recognized algorithm name</h4>
<p>
Each registered algorithm <span class="RFC2119">MUST</span> have a canonical name
for which applications can refer to the algorithm. The canonical name
@@ -3057,14 +3153,14 @@
</p>
</div>
<div id="supported-operations" class="section">
- <h4>19.3.2. Supported operations</h4>
+ <h4>20.3.2. Supported operations</h4>
<p>
Each registered algorithm <span class="RFC2119">MUST</span> define the operations
that it supports.
</p>
</div>
<div id="algorithm-specific-params" class="section">
- <h4>19.3.3. Algorithm-specific parameters</h4>
+ <h4>20.3.3. Algorithm-specific parameters</h4>
<p>
Each registered algorithm <span class="RFC2119">MUST</span> define the expected
parameters, if any, that should be exposed via the <a href="#dfn-Algorithm">Algorithm</a>
@@ -3072,7 +3168,7 @@
</p>
</div>
<div id="algorithm-result" class="section">
- <h4>19.3.4. Algorithm results</h4>
+ <h4>20.3.4. Algorithm results</h4>
<p>
Each registered algorithm <span class="RFC2119">MUST</span> define the contents
of the result of performing the underlying cryptographic operation for every
@@ -3080,7 +3176,7 @@
</p>
</div>
<div id="algorithm-alias" class="section">
- <h4>19.3.5. <dfn id="dfn-algorithm-alias">Algorithm aliases</dfn></h4>
+ <h4>20.3.5. <dfn id="dfn-algorithm-alias">Algorithm aliases</dfn></h4>
<p>
Each registered algorithm <span class="RFC2119">MAY</span> define one or more aliases
that may define a fully normalized <a href="#dfn-Algorithm">Algorithm</a> object.
@@ -3093,9 +3189,9 @@
</div>
<div id="rsassa-pkcs1" class="section">
- <h3>19.4. RSASSA-PKCS1-v1_5</h3>
+ <h3>20.4. RSASSA-PKCS1-v1_5</h3>
<div id="rsassa-pkcs1-description" class="section">
- <h4>19.4.1. Description</h4>
+ <h4>20.4.1. Description</h4>
<p>
The <code>"RSASSA-PKCS1-v1_5"</code> algorithm identifier is used to perform
signing and verification using the RSASSA-PKCS1-v1_5 algorithm specified in
@@ -3103,7 +3199,7 @@
</p>
</div>
<div id="rsassa-pkcs1-registration" class="section">
- <h4>19.4.2. Registration</h4>
+ <h4>20.4.2. Registration</h4>
<p>
The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
this algorithm is <code>"RSASSA-PKCS1-v1_5"</code>.
@@ -3146,7 +3242,7 @@
</table>
</div>
<div id="RsaHashedKeyGenParams-dictionary" class="section">
- <h4>19.4.3. RsaHashedKeyGenParams dictionary</h4>
+ <h4>20.4.3. RsaHashedKeyGenParams dictionary</h4>
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
dictionary <dfn id="dfn-RsaHashedKeyGenParams">RsaHashedKeyGenParams</dfn> : <a href="#dfn-RsaKeyGenParams">RsaKeyGenParams</a> {
<span class="comment">// The hash algorithm to use</span>
@@ -3155,7 +3251,7 @@
</code></pre></div></div>
</div>
<div id="RsaHashedKeyAlgorithm-dictionary" class="section">
- <h4>19.4.4. RsaHashedKeyAlgorithm dictionary</h4>
+ <h4>20.4.4. RsaHashedKeyAlgorithm dictionary</h4>
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
dictionary <dfn id="dfn-RsaHashedKeyAlgorithm">RsaHashedKeyAlgorithm</dfn> : <a href="#dfn-RsaKeyAlgorithm">RsaKeyAlgorithm</a> {
<span class="comment">// The hash algorithm that is used with this key</span>
@@ -3164,7 +3260,7 @@
</code></pre></div></div>
</div>
<div id="RsaHashedImportParams-dictionary" class="section">
- <h4>19.4.5. RsaHashedImportParams dictionary</h4>
+ <h4>20.4.5. RsaHashedImportParams dictionary</h4>
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
dictionary <dfn id="dfn-RsaHashedImportParams">RsaHashedImportParams</dfn> {
<span class="comment">// The hash algorithm to use</span>
@@ -3179,7 +3275,7 @@
</div>
</div>
<div id="rsassa-pkcs1-operations" class="section">
- <h4>19.4.6. Operations</h4>
+ <h4>20.4.6. Operations</h4>
<dl>
<dt>Sign</dt>
<dd>
@@ -4198,9 +4294,9 @@
</div>
<div id="rsa-pss" class="section">
- <h3>19.5. RSA-PSS</h3>
+ <h3>20.5. RSA-PSS</h3>
<div id="rsa-pss-description" class="section">
- <h4>19.5.1. Description</h4>
+ <h4>20.5.1. Description</h4>
<p>
The <code>"RSA-PSS"</code> algorithm identifier is used to perform signing
and verification using the RSASSA-PSS algorithm specified in
@@ -4209,7 +4305,7 @@
</p>
</div>
<div id="rsa-pss-registration" class="section">
- <h4>19.5.2. Registration</h4>
+ <h4>20.5.2. Registration</h4>
<p>
The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
this algorithm is <code>"RSA-PSS"</code>.
@@ -4252,7 +4348,7 @@
</table>
</div>
<div id="RsaPssParams-dictionary" class="section">
- <h4>19.5.3. RsaPssParams dictionary</h4>
+ <h4>20.5.3. RsaPssParams dictionary</h4>
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
dictionary <dfn id="dfn-RsaPssParams">RsaPssParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
<span class="comment">// The desired length of the random salt</span>
@@ -4261,7 +4357,7 @@
</code></pre></div></div>
</div>
<div id="rsa-pss-operations" class="section">
- <h4>19.5.4. Operations</h4>
+ <h4>20.5.4. Operations</h4>
<dl>
<dt>Sign</dt>
<dd>
@@ -5609,9 +5705,9 @@
</div>
<div id="rsa-oaep" class="section">
- <h3>19.6. RSA-OAEP</h3>
+ <h3>20.6. RSA-OAEP</h3>
<div id="rsa-oaep-description" class="section">
- <h4>19.6.1. Description</h4>
+ <h4>20.6.1. Description</h4>
<p>
The <code>"RSA-OAEP"</code> algorithm identifier is used to perform encryption
and decryption ordering to the RSAES-OAEP algorithm specified in
@@ -5620,7 +5716,7 @@
</p>
</div>
<div id="rsa-oaep-registration" class="section">
- <h4>19.6.2. Registration</h4>
+ <h4>20.6.2. Registration</h4>
<p>
The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
this algorithm is <code>"RSA-OAEP"</code>.
@@ -5664,7 +5760,7 @@
</div>
<div id="rsa-oaep-params" class="section">
- <h4>19.6.3. RsaOaepParams dictionary</h4>
+ <h4>20.6.3. RsaOaepParams dictionary</h4>
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
dictionary <dfn id="dfn-RsaOaepParams">RsaOaepParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
<span class="comment">// The optional label/application data to associate with the message</span>
@@ -5673,7 +5769,7 @@
</code></pre></div></div>
</div>
<div id="rsa-oaep-operations" class="section">
- <h4>19.6.4. Operations</h4>
+ <h4>20.6.4. Operations</h4>
<dl>
<dt>Encrypt</dt>
<dd>
@@ -6987,9 +7083,9 @@
</div>
<div id="ecdsa" class="section">
- <h3>19.7. ECDSA</h3>
+ <h3>20.7. ECDSA</h3>
<div id="ecdsa-description" class="section">
- <h4>19.7.1. Description</h4>
+ <h4>20.7.1. Description</h4>
<p>
The <code>"ECDSA"</code> algorithm identifier is used to perform signing
and verification using the ECDSA algorithm specified in
@@ -6997,7 +7093,7 @@
</p>
</div>
<div id="ecdsa-registration" class="section">
- <h4>19.7.2. Registration</h4>
+ <h4>20.7.2. Registration</h4>
<p>
The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
this algorithm is <code>"ECDSA"</code>.
@@ -7041,7 +7137,7 @@
</table>
</div>
<div id="EcdsaParams-dictionary" class="section">
- <h4>19.7.3. EcdsaParams dictionary</h4>
+ <h4>20.7.3. EcdsaParams dictionary</h4>
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
dictionary <dfn id="dfn-EcdsaParams">EcdsaParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
<span class="comment">// The hash algorithm to use</span>
@@ -7050,7 +7146,7 @@
</code></pre></div></div>
</div>
<div id="EcKeyGenParams-dictionary" class="section">
- <h4>19.7.4. EcKeyGenParams dictionary</h4>
+ <h4>20.7.4. EcKeyGenParams dictionary</h4>
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
typedef DOMString <a href="#dfn-NamedCurve">NamedCurve</a>;
@@ -7074,7 +7170,7 @@
</dl>
</div>
<div id="EcKeyAlgorithm-dictionary" class="section">
- <h4>19.7.5. EcKeyAlgorithm dictionary</h4>
+ <h4>20.7.5. EcKeyAlgorithm dictionary</h4>
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
dictionary <dfn id="dfn-EcKeyAlgorithm">EcKeyAlgorithm</dfn> : <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a> {
<span class="comment">// The named curve that the key uses</span>
@@ -7083,7 +7179,7 @@
</code></pre></div></div>
</div>
<div id="EcKeyImportParams-dictionary" class="section">
- <h4>19.7.6. EcKeyImportParams dictionary</h4>
+ <h4>20.7.6. EcKeyImportParams dictionary</h4>
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
dictionary <dfn id="dfn-EcKeyImportParams">EcKeyImportParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
<span class="comment">// A named curve</span>
@@ -7093,7 +7189,7 @@
</div>
<div id="ecdsa-operations" class="section">
- <h4>19.7.7. Operations</h4>
+ <h4>20.7.7. Operations</h4>
<dl>
<dt>Sign</dt>
<dd>
@@ -8273,16 +8369,16 @@
</div>
<div id="ecdh" class="section">
- <h3>19.8. ECDH</h3>
+ <h3>20.8. ECDH</h3>
<div id="ecdh-description" class="section">
- <h4>19.8.1. Description</h4>
+ <h4>20.8.1. Description</h4>
<p>
This describes using Elliptic Curve Diffie-Hellman (ECDH) for key generation and key
agreement, as specified by <a href="#X9.63">X9.63</a>.
</p>
</div>
<div id="ecdh-registration" class="section">
- <h4>19.8.2. Registration</h4>
+ <h4>20.8.2. Registration</h4>
<p>
The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
this algorithm is <code>"ECDH"</code>.
@@ -8320,7 +8416,7 @@
</table>
</div>
<div id="dh-EcdhKeyDeriveParams" class="section">
- <h4>19.8.3. EcdhKeyDeriveParams dictionary</h4>
+ <h4>20.8.3. EcdhKeyDeriveParams dictionary</h4>
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
typedef Uint8Array <dfn id="dfn-ECPoint">ECPoint</dfn>;
@@ -8331,7 +8427,7 @@
</code></pre></div></div>
</div>
<div id="ecdh-operations" class="section">
- <h4>19.8.4. Operations</h4>
+ <h4>20.8.4. Operations</h4>
<dl>
<dt>Generate Key</dt>
<dd>
@@ -9506,9 +9602,9 @@
</div>
<div id="aes-ctr" class="section">
- <h3>19.9. AES-CTR</h3>
+ <h3>20.9. AES-CTR</h3>
<div id="aes-ctr-description" class="section">
- <h4>19.9.1. Description</h4>
+ <h4>20.9.1. Description</h4>
<p class="norm">This section is non-normative.</p>
<p>
The <code>"AES-CTR"</code> algorithm identifier is used to perform
@@ -9517,7 +9613,7 @@
</p>
</div>
<div id="aes-ctr-registration" class="section">
- <h4>19.9.2. Registration</h4>
+ <h4>20.9.2. Registration</h4>
<p>
The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
this algorithm is <code>"AES-CTR"</code>.
@@ -9566,7 +9662,7 @@
</div>
<div id="aes-ctr-params" class="section">
- <h4>19.9.3. AesCtrParams dictionary</h4>
+ <h4>20.9.3. AesCtrParams dictionary</h4>
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
dictionary <dfn id="dfn-AesCtrParams">AesCtrParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
<span class="comment">// The initial value of the counter block. counter <span class="RFC2119">MUST</span> be 16 bytes
@@ -9592,7 +9688,7 @@
</code></pre></div></div>
</div>
<div id="aes-keygen-params" class="section">
- <h4>19.9.5. AesKeyGenParams dictionary</h4>
+ <h4>20.9.5. AesKeyGenParams dictionary</h4>
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
dictionary <dfn id="dfn-AesKeyGenParams">AesKeyGenParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
<span class="comment">// The length, in bits, of the key.</span>
@@ -9601,7 +9697,7 @@
</code></pre></div></div>
</div>
<div id="aes-derivedkey-params" class="section">
- <h4>19.9.6. AesDerivedKeyParams dictionary</h4>
+ <h4>20.9.6. AesDerivedKeyParams dictionary</h4>
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
dictionary <dfn id="dfn-AesDerivedKeyParams">AesDerivedKeyParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
<span class="comment">// The length, in bits, of the key.</span>
@@ -9611,7 +9707,7 @@
</div>
<div id="aes-ctr-operations" class="section">
- <h4>19.9.7. Operations</h4>
+ <h4>20.9.7. Operations</h4>
<dl>
<dt>Encrypt</dt>
<dd>
@@ -10132,9 +10228,9 @@
</div>
<div id="aes-cbc" class="section">
- <h3>19.10. AES-CBC</h3>
+ <h3>20.10. AES-CBC</h3>
<div id="aes-cbc-description" class="section">
- <h4>19.10.1. Description</h4>
+ <h4>20.10.1. Description</h4>
<p class="norm">This section is non-normative.</p>
<p>
The <code>"AES-CBC"</code> algorithm identifier is used to perform
@@ -10150,7 +10246,7 @@
</p>
</div>
<div id="aes-cbc-registration" class="section">
- <h4>19.10.2. Registration</h4>
+ <h4>20.10.2. Registration</h4>
<p>
The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
this algorithm is <code>"AES-CBC"</code>.
@@ -10198,7 +10294,7 @@
</table>
</div>
<div id="aes-cbc-params" class="section">
- <h4>19.10.3. AesCbcParams dictionary</h4>
+ <h4>20.10.3. AesCbcParams dictionary</h4>
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
dictionary <dfn id="dfn-AesCbcParams">AesCbcParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
<span class="comment">// The initialization vector. <span class="RFC2119">MUST</span> be 16 bytes.</span>
@@ -10207,7 +10303,7 @@
</code></pre></div></div>
</div>
<div id="aes-cbc-operations" class="section">
- <h4>19.10.4. Operations</h4>
+ <h4>20.10.4. Operations</h4>
<dl>
<dt>Encrypt</dt>
<dd>
@@ -10729,9 +10825,9 @@
</div>
<div id="aes-cmac" class="section">
- <h3>19.11. AES-CMAC</h3>
+ <h3>20.11. AES-CMAC</h3>
<div id="aes-cmac-description" class="section">
- <h4>19.11.1. Description</h4>
+ <h4>20.11.1. Description</h4>
<p class="norm">This section is non-normative.</p>
<p>
The <code>"AES-CMAC"</code> algorithm identifier is used to perform
@@ -10740,7 +10836,7 @@
</p>
</div>
<div id="aes-cmac-registration" class="section">
- <h4>19.11.2. Registration</h4>
+ <h4>20.11.2. Registration</h4>
<p>
The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
this algorithm is <code>"AES-CMAC"</code>.
@@ -10788,7 +10884,7 @@
</table>
</div>
<div id="aes-cmac-params" class="section">
- <h4>19.11.3. AesCmacParams dictionary</h4>
+ <h4>20.11.3. AesCmacParams dictionary</h4>
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
dictionary <dfn id="dfn-AesCmacParams">AesCmacParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
<span class="comment">// The length, in bits, of the MAC.</span>
@@ -10797,7 +10893,7 @@
</code></pre></div></div>
</div>
<div id="aes-cmac-operations" class="section">
- <h4>19.11.4. Operations</h4>
+ <h4>20.11.4. Operations</h4>
<dl>
<dt>Sign</dt>
<dd>
@@ -11278,9 +11374,9 @@
</div>
</div>
<div id="aes-gcm" class="section">
- <h3>19.12. AES-GCM</h3>
+ <h3>20.12. AES-GCM</h3>
<div id="aes-gcm-description" class="section">
- <h4>19.12.1. Description</h4>
+ <h4>20.12.1. Description</h4>
<p class="norm">This section is non-normative.</p>
<p>
The <code>"AES-GCM"</code> algorithm identifier is used to perform
@@ -11289,7 +11385,7 @@
</p>
</div>
<div id="aes-gcm-registration" class="section">
- <h4>19.12.2. Registration</h4>
+ <h4>20.12.2. Registration</h4>
<p>
The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
this algorithm is <code>"AES-GCM"</code>.
@@ -11337,7 +11433,7 @@
</table>
</div>
<div id="aes-gcm-params" class="section">
- <h4>19.12.3. AesGcmParams dictionary</h4>
+ <h4>20.12.3. AesGcmParams dictionary</h4>
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
dictionary <dfn id="dfn-AesGcmParams">AesGcmParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
<span class="comment">// The initialization vector to use. May be up to 2^64-1 bytes long.</span>
@@ -11350,7 +11446,7 @@
</code></pre></div></div>
</div>
<div id="aes-gcm-operations" class="section">
- <h4>19.12.4. Operations</h4>
+ <h4>20.12.4. Operations</h4>
<dl>
<dt>Encrypt</dt>
<dd>
@@ -11966,9 +12062,9 @@
</div>
<div id="aes-cfb" class="section">
- <h3>19.13. AES-CFB</h3>
+ <h3>20.13. AES-CFB</h3>
<div id="aes-cfb-description" class="section">
- <h4>19.13.1. Description</h4>
+ <h4>20.13.1. Description</h4>
<p class="norm">This section is non-normative.</p>
<p>
The <code>"AES-CFB-8"</code> algorithm identifier is used to perform
@@ -11978,7 +12074,7 @@
</p>
</div>
<div id="aes-cfb-registration" class="section">
- <h4>19.13.2. Registration</h4>
+ <h4>20.13.2. Registration</h4>
<p>
The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
this algorithm is <code>"AES-CFB-8"</code>.
@@ -12026,7 +12122,7 @@
</table>
</div>
<div id="aes-cfb-params" class="section">
- <h4>19.13.3. AesCfbParams dictionary</h4>
+ <h4>20.13.3. AesCfbParams dictionary</h4>
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
dictionary <dfn id="dfn-AesCfbParams">AesCfbParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
<span class="comment">// The initialization vector. <span class="RFC2119">MUST</span> be 16 bytes.</span>
@@ -12035,7 +12131,7 @@
</code></pre></div></div>
</div>
<div id="aes-cfb-operations" class="section">
- <h4>19.13.4. Operations</h4>
+ <h4>20.13.4. Operations</h4>
<dl>
<dt>Encrypt</dt>
<dd>
@@ -12533,9 +12629,9 @@
</div>
<div id="aes-kw" class="section">
- <h3>19.14. AES-KW</h3>
+ <h3>20.14. AES-KW</h3>
<div id="aes-kw-description" class="section">
- <h4>19.14.1. Description</h4>
+ <h4>20.14.1. Description</h4>
<p class="norm">This section is non-normative.</p>
<p>
The <code>"AES-KW"</code> algorithm identifier is used to perform
@@ -12544,7 +12640,7 @@
</p>
</div>
<div id="aes-kw-registration" class="section">
- <h4>19.14.2. Registration</h4>
+ <h4>20.14.2. Registration</h4>
<p>
The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
this algorithm is <code>"AES-KW"</code>.
@@ -12592,7 +12688,7 @@
</table>
</div>
<div id="aes-kw-operations" class="section">
- <h4>19.14.3. Operations</h4>
+ <h4>20.14.3. Operations</h4>
<dl>
<dt>Wrap Key</dt>
<dd>
@@ -13045,9 +13141,9 @@
</div>
<div id="hmac" class="section">
- <h3>19.15. HMAC</h3>
+ <h3>20.15. HMAC</h3>
<div id="hmac-description" class="section">
- <h4>19.15.1. Description</h4>
+ <h4>20.15.1. Description</h4>
<p class="norm">This section is non-normative.</p>
<p>
The <code>HMAC</code> algorithm calculates and verifies hash-based message
@@ -13055,7 +13151,7 @@
</p>
</div>
<div id="hmac-registration" class="section">
- <h4>19.15.2. Registration</h4>
+ <h4>20.15.2. Registration</h4>
<p>
The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
this algorithm is <code>"HMAC"</code>.
@@ -13103,7 +13199,7 @@
</table>
</div>
<div id="hmac-importparams" class="section">
- <h4>19.15.3. HmacImportParams dictionary</h4>
+ <h4>20.15.3. HmacImportParams dictionary</h4>
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
dictionary <dfn id="dfn-HmacImportParams">HmacImportParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
<span class="comment">// The inner hash function to use.</span>
@@ -13114,7 +13210,7 @@
</code></pre></div></div>
</div>
<div id="HmacKeyAlgorithm-dictionary" class="section">
- <h4>19.15.4. HmacKeyAlgorithm dictionary</h4>
+ <h4>20.15.4. HmacKeyAlgorithm dictionary</h4>
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
dictionary <dfn id="dfn-HmacKeyAlgorithm">HmacKeyAlgorithm</dfn> : <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a> {
<span class="comment">// The inner hash function to use.</span>
@@ -13125,7 +13221,7 @@
</code></pre></div></div>
</div>
<div id="hmac-keygen-params" class="section">
- <h4>19.15.5. HmacKeyGenParams dictionary</h4>
+ <h4>20.15.5. HmacKeyGenParams dictionary</h4>
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
dictionary <dfn id="dfn-HmacKeyGenParams">HmacKeyGenParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
<span class="comment">// The inner hash function to use.</span>
@@ -13138,7 +13234,7 @@
</code></pre></div></div>
</div>
<div id="hmac-derivedkey-params" class="section">
- <h4>19.15.6. HmacDerivedKeyParams dictionary</h4>
+ <h4>20.15.6. HmacDerivedKeyParams dictionary</h4>
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
dictionary <dfn id="dfn-HmacDerivedKeyParams">HmacDerivedKeyParams</dfn> : <a href="#dfn-HmacImportParams">HmacImportParams</a> {
<span class="comment">// The length (in bits) of the key to generate. If unspecified, the
@@ -13149,7 +13245,7 @@
</code></pre></div></div>
</div>
<div id="hmac-operations" class="section">
- <h4>19.15.7. Operations</h4>
+ <h4>20.15.7. Operations</h4>
<dl>
<dt>Sign</dt>
<dd>
@@ -13834,9 +13930,9 @@
</div>
</div>
<div id="dh" class="section">
- <h3>19.16. Diffie-Hellman</h3>
+ <h3>20.16. Diffie-Hellman</h3>
<div id="dh-description" class="section">
- <h4>19.16.1. Description</h4>
+ <h4>20.16.1. Description</h4>
<p class="norm">This section is non-normative.</p>
<p>
This describes using Diffie-Hellman for key generation and key agreement, as specified
@@ -13844,7 +13940,7 @@
</p>
</div>
<div id="dh-registration" class="section">
- <h4>19.16.2. Registration</h4>
+ <h4>20.16.2. Registration</h4>
<p>
The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
this algorithm is <code>"DH"</code>.
@@ -13882,7 +13978,7 @@
</table>
</div>
<div id="dh-DhKeyGenParams" class="section">
- <h4>19.16.3. DhKeyGenParams dictionary</h4>
+ <h4>20.16.3. DhKeyGenParams dictionary</h4>
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
dictionary <dfn id="dfn-DhKeyGenParams">DhKeyGenParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
<span class="comment">// The prime p.</span>
@@ -13893,7 +13989,7 @@
</code></pre></div></div>
</div>
<div id="dh-DhKeyAlgorithm" class="section">
- <h4>19.16.4. DhKeyAlgorithm dictionary</h4>
+ <h4>20.16.4. DhKeyAlgorithm dictionary</h4>
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
dictionary <dfn id="dfn-DhKeyAlgorithm">DhKeyAlgorithm</dfn> : <a href="#dfn-KeyAlgorithm">KeyAlgorithm</a> {
<span class="comment">// The prime p.</span>
@@ -13904,7 +14000,7 @@
</code></pre></div></div>
</div>
<div id="dh-DhKeyDeriveParams" class="section">
- <h4>19.16.5. DhKeyDeriveParams dictionary</h4>
+ <h4>20.16.5. DhKeyDeriveParams dictionary</h4>
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
dictionary <dfn id="dfn-DhKeyDeriveParams">DhKeyDeriveParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
<span class="comment">// The peer's public value.</span>
@@ -13913,7 +14009,7 @@
</code></pre></div></div>
</div>
<div id="dh-DhImportKeyParams" class="section">
- <h4>19.16.6. DhImportKeyParams dictionary</h4>
+ <h4>20.16.6. DhImportKeyParams dictionary</h4>
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
dictionary <dfn id="dfn-DhImportKeyParams">DhImportKeyParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
<span class="comment">// The prime p.</span>
@@ -13924,7 +14020,7 @@
</code></pre></div></div>
</div>
<div id="dh-operations" class="section">
- <h4>19.16.7. Operations</h4>
+ <h4>20.16.7. Operations</h4>
<dl>
<dt>Generate Key</dt>
<dd>
@@ -14731,16 +14827,16 @@
</div>
</div>
<div id="sha" class="section">
- <h3>19.17. SHA</h3>
+ <h3>20.17. SHA</h3>
<div id="sha-description" class="section">
- <h4>19.17.1. Description</h4>
+ <h4>20.17.1. Description</h4>
<p>
This describes the SHA-1 and SHA-2 families, as specified by
[<a href="#FIPS180-4">FIPS PUB 180-4</a>].
</p>
</div>
<div id="sha-registration" class="section">
- <h4>19.17.2. Registration</h4>
+ <h4>20.17.2. Registration</h4>
<p>
The following algorithms are added as <a href="#recognized-algorithm-name">
recognized algorithm names</a>:
@@ -14773,7 +14869,7 @@
</table>
</div>
<div id="sha-operations" class="section">
- <h4>19.17.3. Operations</h4>
+ <h4>20.17.3. Operations</h4>
<dl>
<dt>Digest</dt>
<dd>
@@ -14845,9 +14941,9 @@
</div>
</div>
<div id="concatkdf" class="section">
- <h3>19.18. Concat KDF</h3>
+ <h3>20.18. Concat KDF</h3>
<div id="concatkdf-description" class="section">
- <h4>19.18.1. Description</h4>
+ <h4>20.18.1. Description</h4>
<p>
The <code>"CONCAT"</code> algorithm identifier is used to perform key derivation
using the key derivation algorithm defined in Section 5.8.1 of NIST SP 800-56A
@@ -14855,7 +14951,7 @@
</p>
</div>
<div id="concatkdf-registration" class="section">
- <h4>19.18.2. Registration</h4>
+ <h4>20.18.2. Registration</h4>
<p>
The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
this algorithm is <code>"CONCAT"</code>.
@@ -14888,7 +14984,7 @@
</table>
</div>
<div id="concat-params" class="section">
- <h4>19.18.3. ConcatParams dictionary</h4>
+ <h4>20.18.3. ConcatParams dictionary</h4>
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
dictionary <dfn id="dfn-ConcatParams">ConcatParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
<span class="comment">// The digest method to use to derive the keying material.</span>
@@ -14910,7 +15006,7 @@
</code></pre></div></div>
</div>
<div id="concat-operations" class="section">
- <h4>19.18.4. Operations</h4>
+ <h4>20.18.4. Operations</h4>
<dl>
<dt>Derive Bits</dt>
<dd>
@@ -15058,9 +15154,9 @@
</div>
</div>
<div id="hkdf-ctr" class="section">
- <h3>19.19. HKDF-CTR</h3>
+ <h3>20.19. HKDF-CTR</h3>
<div id="hkdf-ctr-description" class="section">
- <h4>19.19.1. Description</h4>
+ <h4>20.19.1. Description</h4>
<p class="norm">This section is non-normative.</p>
<p>
The <code>"HKDF-CTR"</code> algorithm identifier is used to
@@ -15071,7 +15167,7 @@
</p>
</div>
<div id="hkdf-ctr-registration" class="section">
- <h4>19.19.2. Registration</h4>
+ <h4>20.19.2. Registration</h4>
<p>
The <a href="#recognized-algorithm-name">recognized algorithm name</a>
for this algorithm is <code>"HKDF-CTR"</code>.
@@ -15104,7 +15200,7 @@
</table>
</div>
<div id="hkdf-ctr-params" class="section">
- <h4>19.19.3. HkdfCtrParams dictionary</h4>
+ <h4>20.19.3. HkdfCtrParams dictionary</h4>
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
dictionary <dfn id="dfn-HkdfCtrParams">HkdfCtrParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
<span class="comment">// The algorithm to use with HMAC (e.g.: <a href="#sha-256">SHA-256</a>)</span>
@@ -15128,7 +15224,7 @@
</div>
</div>
<div id="hkdf2-ctr-operations" class="section">
- <h4>19.19.4. Operations</h4>
+ <h4>20.19.4. Operations</h4>
<dl>
<dt>Derive Bits</dt>
<dd>
@@ -15338,9 +15434,9 @@
</div>
<div id="pbkdf2" class="section">
- <h3>19.20. PBKDF2</h3>
+ <h3>20.20. PBKDF2</h3>
<div id="pbkdf2-description" class="section">
- <h4>19.20.1. Description</h4>
+ <h4>20.20.1. Description</h4>
<p class="norm">This section is non-normative.</p>
<p>
The <code>"PBKDF2"</code> algorithm identifier is used to
@@ -15350,7 +15446,7 @@
</p>
</div>
<div id="pbkdf2-registration" class="section">
- <h4>19.20.2. Registration</h4>
+ <h4>20.20.2. Registration</h4>
<p>
The <a href="#recognized-algorithm-name">recognized algorithm name</a> for
this algorithm is <code>"PBKDF2"</code>.
@@ -15388,7 +15484,7 @@
</table>
</div>
<div id="pbkdf2-params" class="section">
- <h4>19.20.3. Pbkdf2Params dictionary</h4>
+ <h4>20.20.3. Pbkdf2Params dictionary</h4>
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
dictionary <dfn id="dfn-Pbkdf2Params">Pbkdf2Params</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
CryptoOperationData <dfn id="dfn-Pbkdf2Params-salt">salt</dfn>;
@@ -15398,7 +15494,7 @@
</code></pre></div></div>
</div>
<div id="pbkdf2-operations" class="section">
- <h4>19.20.4. Operations</h4>
+ <h4>20.20.4. Operations</h4>
<dl>
<dt>Derive bits</dt>
<dd>
@@ -15617,7 +15713,7 @@
</div>
<div id="algorithm-normalizing-rules" class="section">
- <h2>20. Algorithm normalizing rules</h2>
+ <h2>21. Algorithm normalizing rules</h2>
<p>
The <a href="#dfn-AlgorithmIdentifier">AlgorithmIdentifier</a> typedef permits algorithms
to be specified as either an <a href="#dfn-Algorithm">Algorithm</a> dictionary or a <a href="#dfn-DOMString">DOMString</a>. The <a href="#dfn-DOMString">DOMString</a> option
@@ -15703,9 +15799,9 @@
</ol>
</div>
<div id="examples-section" class="section">
- <h2>21. JavaScript Example Code</h2>
+ <h2>22. JavaScript Example Code</h2>
<div id="examples-signing" class="section">
- <h3>21.1. Generate a signing key pair, sign some data</h3>
+ <h3>22.1. Generate a signing key pair, sign some data</h3>
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">ECMAScript</span></div><div class="blockContent"><pre class="code"><code class="es-code">
<span class="comment">// Algorithm Object</span>
@@ -15739,7 +15835,7 @@
</code></pre></div></div>
</div>
<div id="examples-symmetric-encryption" class="section">
- <h3>21.2. Symmetric Encryption</h3>
+ <h3>22.2. Symmetric Encryption</h3>
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">ECMAScript</span></div><div class="blockContent"><pre class="code"><code class="es-code">
var clearDataArrayBufferView = convertPlainTextToArrayBufferView("Plain Text Data");
<span class="comment">// TODO: create example utility function that converts text -> ArrayBufferView</span>
@@ -15767,9 +15863,9 @@
</div>
</div>
<div id="iana-section" class="section">
- <h2>22. IANA Considerations</h2>
+ <h2>23. IANA Considerations</h2>
<div id="iana-section-jws-jwa" class="section">
- <h3>22.1. JSON Web Signature and Encryption Algorithms Registration</h3>
+ <h3>23.1. JSON Web Signature and Encryption Algorithms Registration</h3>
<p>
This section registers the following algorithm identifiers in the IANA JSON Web
Signature and Encryption Algorithms Registry for use with JSON Web Key. Note that the
@@ -15907,7 +16003,7 @@
</ul>
</div>
<div id="iana-section-jwk" class="section">
- <h3>22.2. JSON Web Key Parameters Registration</h3>
+ <h3>23.2. JSON Web Key Parameters Registration</h3>
<ul>
<li>Parameter Name: "ext"</li>
<li>Parameter Description: Extractable</li>
@@ -15919,7 +16015,7 @@
</div>
</div>
<div id="acknowledgements-section" class="section">
- <h2>23. Acknowledgements</h2>
+ <h2>24. Acknowledgements</h2>
<p>
The editors would like to thank Adam Barth, Alex Russell, Ali Asad, Arun Ranganathan,
Brian Smith, Brian Warner, Channy Yun, Eric Roman, Glenn Adams, Jim Schaad, Kai Engert,
@@ -15942,9 +16038,9 @@
</p>
</div>
<div id="references" class="section">
- <h2>24. References</h2>
+ <h2>25. References</h2>
<div id="normative-references" class="section">
- <h3>24.1. Normative References</h3>
+ <h3>25.1. Normative References</h3>
<dl>
<dt id="DOM4">DOM4</dt>
<dd>
@@ -16037,7 +16133,7 @@
</dl>
</div>
<div id="informative-references" class="section">
- <h3>24.2. Informative References</h3>
+ <h3>25.2. Informative References</h3>
<dl>
<dt id="CDSA">CDSA</dt>
<dd>
@@ -16064,6 +16160,11 @@
<cite><a href="http://www.w3.org/TR/FileAPI/">File API</a></cite>,
A. Ranganathan, J. Sicking. W3C.
</dd>
+ <dt id="IndexedDB">Indexed Database API</dt>
+ <dd>
+ <cite><a href="http://www.w3.org/TR/IndexedDB/">Indexed Database API</a></cite>,
+ N. Mehta, J. Sicking, E. Graff, A. Popescu, J. Orlow, J. Bell. W3C.
+ </dd>
<dt id="PKCS11">PKCS11</dt>
<dd>
<cite><a href="http://www.rsa.com/rsalabs/node.asp?id=2133">PKCS #11: Cryptographic