This specification describes a JavaScript API for performing basic cryptographic operations in web applications, such as hashing, signature generation and verification, and encryption and decryption. Additionally, it describes an API for applications to generate and/or manage the keying material necessary to perform these operations. Uses for this API range from user or service authentication, document or code signing, and the confidentiality and integrity of communications.
Publication as a First Public Working Draft does not imply endorsement byW3C and its Members.
This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
The Web Cryptography API defines a low-level interface to interacting with cryptographic key material that is managed or exposed by user agents. The API itself is agnostic of the underlying implementation of key storage, but provides a common set of interfaces that allow rich web applications to perform operations such as signature generation and verification, hashing and verification, encryption and decryption, without requiring access to the raw keying material.
Cryptographic transformations are exposed via theSubtleCrypto interface, which defines a set of methods for performing common cryptographic operations. In addition to operations such as signature generation and verification, hashing and verification, and encryption and decryption, the API provides interfaces for key generation, key derivation and key import and export.
2.Use Cases
This section is non-normative.
2.1Multi-factor Authentication
A web application may wish to extend or replace existing username/password based authentication schemes with authentication methods based on proving that the user has access to some secret keying material. Rather than using transport-layer authentication, such as TLS client certificates, the web application may prefer the richer user experience provided by authenticating within the application itself.
Using the Web Cryptography API, the application could locate suitable client keys, which may have been previously generated via the user agent or pre-provisioned out-of-band by the web application. It could then perform cryptographic operations such as decrypting an authentication challenge followed by signing an authentication response.
This exchange could be further strengthened by binding the authentication to the TLS session over which the client is authenticating, by deriving a key based on properties of the underlying transport.
If a user does not already have a key associated with their account, the web application could direct the user agent to either generate a new key or to re-use an existing key of the user's choice.
2.2Protected Document Exchange
A web application may wish to limit the viewership of documents that contain sensitive or personal information, even when these documents have been securely received, such as over TLS.
Using the Web Cryptography API, the application could do so by encrypting the documents with a secret key, and then wrapping that key with the public keys associated with the authorized viewers. When a user agent navigates to such a web application, the application would send the encrypted form of the document. The user agent is then instructed to unwrap the encryption key, using the user's private key, and from there, decrypt and display the document.
2.3Cloud Storage
A web application may wish to permit users to protect the confidentiality of data and documents stored with remote service providers prior to uploading.
Using the Web Cryptography API, the application may have a user select a private or secret key, optionally derive an encryption key from the selected key, encrypt the document, and then upload the encrypted data to the service provider using existing APIs.
This use case is similar to theProtected Document Exchange use case, with viewership of the document limited to the user themself.
2.4Document Signing
A web application may wish to accept electronic signatures on documents, in lieu of requiring physical signatures.
Using the Web Cryptography API, the application may direct the user to select a key, which may have been pre-provisioned out-of-band, or generated specifically for the web application. Using this key, the application may perform a signing operation over some data, as proof that the user accepts the document.
2.5Data Integrity Protection
A web application may wish to cache data locally, while ensuring that this data cannot be modified in an offline attack.
Using the Web Cryptography API, the application may use a public key contained within the application to verify the contents of the data cache. Previously, when data was added to the cache, it would have been signed by the server with the corresponding private key. By validating the signature when restoring data from the cache, the client ensures that the cached data has not been tampered with.
2.6Secure Messaging
A web application may wish to employ message layer security using schemes such as off-the-record (OTR) messaging, even when these messages have been securely received, such as over TLS.
The Web Cryptography API enables OTR and similar message signing schemes, by allowing key agreement to be performed. The two parties can negotiate shared encryption keys and message authentication code (MAC) keys, to allow encryption and decryption of messages, and to prevent tampering.
2.7JavaScript Object Signing and Encryption (JOSE)
A web application may wish to interact with the structures and message formats defined by the IETF JavaScript Object Signing and Encryption (JOSE) Working Group.
Using the Web Cryptography API, the application may read and import keys encoded in the JSON key format (JWK), validate messages that have been integrity protected using digital signatures or MACs (JWS), or decrypt messages that have been encrypted (JWE).
3.Conformance
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key wordsMUST,REQUIRED, andSHALL in this document are to be interpreted as described inBCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
The following conformance classes are defined by this specification:
conforming user agent
A user agent is considered to be aconforming user agent if it satisfies all of theMUST-,REQUIRED- andSHALL-level criteria in this specification that apply to implementations. This specification uses both the terms "conforming user agent" and "user agent" to refer to this product class.
Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)
User agents that use ECMAScript to implement the APIs defined in this specificationMUST implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [WebIDL] as this specification uses that specification and terminology.
Unless otherwise stated, string comparisons are done in acase-sensitive manner. String literals in this specification written in monospace font like "this" do not include the enclosing quotes.
3.1Extensibility
Vendor-specific proprietary extensions to this specification are strongly discouraged. Authors must not use such extensions, as doing so reduces interoperability and fragments the user base, allowing only users of specific user agents to access the content in question.
If vendor-specific extensions are needed, the members should be prefixed by vendor-specific strings to prevent clashes with future versions of this specification. Extensions must be defined so that the use of extensions neither contradicts nor causes the non-conformance of functionality defined in the specification.
When vendor-neutral extensions to this specification are needed, either this specification can be updated accordingly, or an extension specification can be written that overrides the requirements in this specification. When someone applying this specification to their activities decides that they will recognize the requirements of such an extension specification, it becomes anapplicable specification for the purposes of conformance requirements in this specification. Applicable specifications defined by theW3C Web Cryptography Working Group are listed in the table below.
Specification
Reference
Note
Readers are advised to consult the errata to this specification for updates to the table above.
4.Scope
This section is non-normative.
4.1Level of abstraction
The specification attempts to focus on the common functionality and features between various platform-specific or standardized cryptographic APIs, and avoid features and functionality that are specific to one or two implementations. As such this API allows key generation, management, and exchange with a level of abstraction that avoids developers needing to care about the implementation of the underlying key storage. The API is focused specifically around CryptoKey objects, as an abstraction for the underlying raw cryptographic keying material. The intent behind this is to allow an API that is generic enough to allow conforming user agents to expose keys that are stored and managed directly by the user agent, that may be stored or managed using isolated storage APIs such as per-user key stores provided by some operating systems, or within key storage devices such as secure elements, while allowing rich web applications to manipulate the keys and without requiring the web application be aware of the nature of the underlying key storage.
4.2Cryptographic algorithms
Because the underlying cryptographic implementations will vary between conforming user agents, and may be subject to local policy, including but not limited to concerns such as government or industry regulation, security best practices, intellectual property concerns, and constrained operational environments, this specification does not dictate a mandatory set of algorithms thatMUST be implemented. Instead, it defines a common set of bindings that can be used in an algorithm-independent manner, a common framework for discovering if a user agent or key handle supports the underlying algorithm, and a set of conformance requirements for the behaviors of individual algorithms, if implemented.
4.3Out of scope
This API, while allowing applications to generate, retrieve, and manipulate keying material, does not specifically address the provisioning of keys in particular types of key storage, such as secure elements or smart cards. This is due to such provisioning operations often being burdened with vendor-specific details that make defining a vendor-agnostic interface an unsuitably unbounded task. Additionally, this API does not deal with or address the discovery of cryptographic modules, as such concepts are dependent upon the underlying user agent and are not concepts that are portable between common operating systems, cryptographic libraries, and implementations.
5.Concepts
This section is non-normative.
5.1Underlying Cryptographic Implementation
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.
TheCryptoKey object represents the bridge between the JavaScript execution environment and these underlying libraries, through the use of the internal slot named[[handle]]. The handle represents an opaque type that is implementation specific, which may not be represented within a JavaScript type, nor is it ever exposed to script authors. In this way, theCryptoKey object is the conceptual equivalent to the JavaScript executing environment as the[[handle]] is to the underlying cryptographic implementation.
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.
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.
In practice, it is expected that most authors will make use of the Indexed Database API [INDEXEDDB], which allows associative storage of key/value pairs, where the key is some string identifier meaningful to the application, and the value is aCryptoKey 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 theCryptoKey itself.
6.Security considerations
This section is non-normative.
6.1Security considerations for implementers
By not providing an explicit storage mechanism, this specification assumes thatCryptoKey objects are scoped to the current execution environment and any storage mechanisms available to that environment (e.g. Indexed Database API). Application authors rely upon this for the security of their applications; two origins with the sameCryptoKey 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 noCryptoKey objects are shared between two origins unless the author has explicitly chosen to share (e.g., such as through the use of postMessage)
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.
6.2Security considerations for authors
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 arestrongly 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.
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.
This specification does not define any specific mechanisms for the storage of cryptographic keys. By default, unless specific effort is taken by the author to persist keys, such as through the use of the Indexed Database API, keys created with this API will only be valid for the duration of the current page (e.g. until a navigation event). Authors that wish to use the same key across different pages or multiple browsing sessions must employ existing web storage technologies. Authors should be aware of the security assumptions of these technologies, such as the same-origin security model; that is, any application that shares the same scheme, host, and port have access to the same storage partition, even if other information, such as the path, may differ. Authors may explicitly choose to relax this security through the use of inter-origin sharing, such aspostMessage.
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 theexportKey andwrapKey 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.
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 theCryptoKey have gone away.
Applications may share aCryptoKey object across security boundaries, such as origins, through the use of the structured clone algorithm and APIs such aspostMessage. While access to the underlying cryptographic key material may be restricted, based upon theextractable 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.
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.
6.3Security considerations for users
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.
7.Privacy considerations
This section is non-normative.
Fingerprinting
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.
Super-cookies
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.
This specification relies on underlying specifications.
DOM
Aconforming user agentMUST support at least the subset of the functionality defined in DOM that this specification relies upon; in particular, itMUST supportPromises andDOMException. [DOM]
Aconforming user agentMUST be a conforming implementation of the IDL fragments in this specification, as described in the Web IDL specification. [WebIDL]
Abyte sequence containing a bit sequenceb is thebyte sequence obtained by first appending zero or more bits of value zero tob such that the length of the resulting bit sequence is minimal and an integer multiple of 8 and then considering each consecutive sequence of 8 bits in that string as a byte.
When this specification says toconvert a non-negative integeri to a byte sequence of lengthn, wheren * 8 is greater than the logarithm to base 2 ofi, the user agent must first calculate the binary representation ofi, most significant bit first, prefix this with sufficient zero bits to form a bit sequence of lengthn * 8, and then return thebyte sequence formed by considering each consecutive sequence of 8 bits in that bit sequence as a byte.
Comparing two strings in acase-sensitive manner means comparing them exactly, code point for code point.
Comparing two strings in aASCII case-insensitive manner means comparing them exactly, code point for code point, except that the codepoints in the range U+0041 .. U+005A (i.e. LATIN CAPITAL LETTER A to LATIN CAPITAL LETTER Z) and the corresponding codepoints in the range U+0061 .. U+007A (i.e. LATIN SMALL LETTER A to LATIN SMALL LETTER Z) are also considered to match.
When this specification says toterminate the algorithm, the user agent must terminate the algorithm after finishing the step it is on. The algorithm referred to is the set of specification-defined processing steps, rather than the underlying cryptographic algorithm that may be in the midst of processing.
When this specification says toparse an ASN.1 structure, the user agent must perform the following steps:
Letdata be a sequence of bytes to be parsed.
Letstructure be the ASN.1 structure to be parsed.
LetexactData be an optional boolean value. If it is not supplied, let it be initialized totrue.
Parsedata according to the Distinguished Encoding Rules of [X690], usingstructure as the ASN.1 structure to be decoded.
IfexactData was specified, and all of the bytes ofdata were not consumed during the parsing phase, thenthrow aDataError.
Return the parsed ASN.1 structure.
When this specification says toparse a subjectPublicKeyInfo, the user agent mustparse an ASN.1 structure, withdata set to the sequence of bytes to be parsed,structure as the ASN.1 structure of subjectPublicKeyInfo, as specified in [RFC5280], andexactData set totrue.
When this specification says toparse a PrivateKeyInfo, the user agent mustparse an ASN.1 structure withdata set to the sequence of bytes to be parsed,structure as the ASN.1 structure of PrivateKeyInfo, as specified in [RFC5208], andexactData set totrue.
When this specification says toparse a JWK, the user agent must run the following steps:
Letdata be the sequence of bytes to be parsed.
Letjson be the Unicode string that results from interpretingdata according to UTF-8.
Convertjson to UTF-16.
Letresult be the object literal that results from executing theJSON.parse internal function in the context of a new global object, withtext argument set to a JavaScript String containingjson.
Letkey be the result of convertingresult to the IDL dictionary type ofJsonWebKey.
When this specification says to calculate theusage intersection of two sequences,a andb the result shall be a sequence containing eachrecognized key usage value that appears in botha andb, in the order listed in the list ofrecognized key usage values, where a value is said to appear in a sequence if an element of the sequence exists that is a case-sensitive string match for that value.
When this specification says to calculate the normalized value of a usages list,usages the result shall be theusage intersection ofusages and a sequence containing allrecognized key usage values.
When this specification refers to thecached ECMAScript object associated with an internal slot [[slot]] ofobject, the user agent must run the following steps:
If the [[slot_cached]] internal slot ofobject is undefined:
Set the [[slot_cached]] internal slot ofobject to the result of performing type conversion to an ECMAScript object as defined in [WebIDL] to the contents of the [[slot]] internal slot ofobject.
Return the contents of the [[slot_cached]] internal slot ofobject.
10.Crypto interface
TheCrypto interface represents an interface to general purpose cryptographic functionality including a cryptographically strong pseudo-random number generator seeded with truly random values.
Implementations should generate cryptographically strong random values using well-established cryptographic pseudo-random number generators seeded with high-quality entropy, such as from an operating-system entropy source (e.g., "/dev/urandom"). This specification provides no lower-bound on the information theoretic entropy present in cryptographically strong random values, but implementations should make a best effort to provide as much entropy as practicable.
Note
This interface defines a synchronous method for obtaining cryptographically strong random values. While some devices and implementations may support truly random cryptographic number generators or provide interfaces that block when there is insufficient entropy, implementations are discouraged from using these sources when implementing getRandomValues, both for performance and to avoid depleting the system of entropy. Instead, these sources should be used to seed a cryptographic pseudo-random number generator that can then return suitable values efficiently.
10.1Methods and Parameters
10.1.1The getRandomValues method
ThegetRandomValues method generates cryptographically strong random values. It must act as follows:
For the steps described in the algorithm togenerate a random UUID, thehexadecimal representation of a bytevalue is the two-character string created by expressingvalue in hexadecimal usingASCII lower hex digits, left-padded with "0" to reach twoASCII lower hex digits.
10.2Attributes
10.2.1The subtle attribute
Thesubtle attribute provides an instance of theSubtleCrypto interface which provides low-level cryptographic primitives and algorithms.
11.Algorithm dictionary
TheAlgorithm object is a dictionary object [WEBIDL] which is used to specify an algorithm and any additional parameters required to fully specify the desired operation.
TheKeyAlgorithm dictionary is provided to aid in documenting how fixed, public properties of aCryptoKey are reflected back to an application. The actual dictionary type is never exposed to applications.
12.2KeyAlgorithm dictionary members
name
The name of the algorithm used to generate theCryptoKey
13.CryptoKey interface
TheCryptoKey object represents an opaque reference to keying material that is managed by the user agent.
This specification provides a uniform interface for many different kinds of keying material managed by the user agent. This may include keys that have been generated by the user agent, derived from other keys by the user agent, imported to the user agent through user actions or using this API, pre-provisioned within software or hardware to which the user agent has access or made available to the user agent in other ways. The term key refers broadly to any keying material including actual keys for cryptographic operations and secret values obtained within key derivation or exchange operations.
The CryptoKey object is not required to directly interface with the underlying key storage mechanism, and may instead simply be a reference for the user agent to understand how to obtain the keying material when needed, e.g. when performing a cryptographic operation.
13.2Key interface data types
KeyType
The type of a key. Therecognized key type values are "public", "private" and "secret". Opaque keying material, including that used for symmetric algorithms, is represented bysecret, while keys used as part of asymmetric algorithms composed of public/private keypairs will be eitherpublic orprivate.
KeyUsage
A type of operation that may be performed using a key. Therecognized key usage values areencrypt,decrypt,sign,verify,deriveKey,deriveBits,wrapKey andunwrapKey.
13.3CryptoKey internal slots
EveryCryptoKey object has a set of internal slots that store information about the key. These slots are not exposed as part of this specification; they represent internal state that an implementation uses to implement this specification. The notational convention used in [ECMA-262] is re-used here; internal slots are identified by names enclosed in double square brackets [[ ]].
AllCryptoKey objects have internal slots named[[type]],[[extractable]],[[algorithm]],[[algorithm_cached]],[[usages]],[[usages_cached]], and[[handle]].
The contents of the[[algorithm]] internal slot shall be, or be derived from, aKeyAlgorithm. The contents of the[[usages]] internal slot shall be of type Sequence<KeyUsage>.
Note
The[[handle]] slot is an opaque type that contains whatever data the underlying cryptographic implementation uses to represent a logical key. Different cryptographic implementations may use different types, ranging from opaque identifiers represented as integers, pointer types, or structures that provide identifying information. These handles are never exposed to applications.
13.4CryptoKey interface members
type
Reflects the[[type]] internal slot, which contains the type of the underlying key.
extractable
Reflects the[[extractable]] internal slot, which indicates whether or not the raw keying material may be exported by the application.
Returns thecached ECMAScript object associated with the[[usages]] internal slot, which indicates which cryptographic operations are permissible to be used with this key.
When deserializing a serializedCryptoKey object, it is important that the object is not deserialized as a different type. This is normatively required by the definition of thedeserialization steps, but it merits specific attention, as such deserialization may expose the contents of the key material, which in some cases (such as when the[[extractable]] internal slot is false) should not be exposed to applications.
14.SubtleCrypto interface
TheSubtleCrypto interface provides a set of methods for dealing with low-level cryptographic primitives and algorithms.
TheSubtleCrypto interface is named "SubtleCrypto" to reflect the fact that many of these algorithms have subtle usage requirements in order to provide the required algorithmic security guarantees.
For example, the direct use of an unauthenticated encryption scheme, such asAES in counter mode, gives potential attackers the ability to manipulate bits in the output by manipulating bits in the input, compromising the integrity of the message. However, AES-CTR can be used securely in combination with other cryptographic primitives, such as message authentication codes, to ensure the integrity of the protected message, but only when the message authentication code is constructed over the encrypted message and IV.
Developers making use of the SubtleCrypto interface are expected to be aware of the security concerns associated with both the design and implementation of the various algorithms provided. The raw algorithms are provided in order to allow developers maximum flexibility in implementing a variety of protocols and applications, each of which may represent the composition and security parameters in a unique manner that necessitate the use of the raw algorithms.
14.1Data Types
KeyFormat
Specifies a serialization format for a key. Therecognized key format values are:
raw
An unformatted sequence of bytes. Intended for secret keys.
pkcs8
The DER encoding of the PrivateKeyInfo structure from [RFC5208].
spki
The DER encoding of the SubjectPublicKeyInfo structure from [RFC5280].
jwk
The key is aJsonWebKey dictionary encoded as a JavaScript object
14.2Task Source
Thecrypto task source
Thistask source is used to queue tasks to resolve or reject promises created in response to calls to methods ofSubtleCrypto.
Note
This specification makes no specific requirements on the ordering of responses to calls to methods ofSubtleCrypto, neither between multiple calls, nor between calls and tasks from othertask sources. This task source is merely used toqueue a task to resolve or reject the relevant promise whenever the cryptographic operation is completed, in order toprevent race conditions.
14.3Methods and Parameters
Note
All errors are reported asynchronously by rejecting the returned Promise. This includes Web IDL type mapping errors.
14.3.1The encrypt method
Theencrypt method returns a new Promise object that will encrypt data using the specifiedAlgorithmIdentifier with the suppliedCryptoKey. It must act as follows:
Letalgorithm andkey be thealgorithm andkey parameters passed to theencrypt() method, respectively.
Letresult be the result ofcreating anArrayBuffer inrealm, containingciphertext.
Resolvepromise withresult.
14.3.2The decrypt method
Thedecrypt method returns a new Promise object that will decrypt data using the specifiedAlgorithmIdentifier with the suppliedCryptoKey. It must act as follows:
Letalgorithm andkey be thealgorithm andkey parameters passed to thedecrypt() method, respectively.
Letresult be the result ofcreating anArrayBuffer inrealm, containingplaintext.
Resolvepromise withresult.
14.3.3The sign method
Thesign method returns a new Promise object that will sign data using the specifiedAlgorithmIdentifier with the suppliedCryptoKey. It must act as follows:
Letalgorithm andkey be thealgorithm andkey parameters passed to thesign() method, respectively.
Letresult be the result ofcreating anArrayBuffer inrealm, containingsignature.
Resolvepromise withresult.
14.3.4The verify method
Theverify method returns a new Promise object that will verify data using the specifiedAlgorithmIdentifier with the suppliedCryptoKey. It must act as follows:
Letalgorithm andkey be thealgorithm andkey parameters passed to theverify() method, respectively.
Letlength be the result of performing the get key length algorithm specified bynormalizedDerivedKeyAlgorithmLength usingderivedKeyType.
Letsecret be the result of performing the derive bits operation specified bynormalizedAlgorithm usingkey,algorithm andlength.
Letresult be the result of performing the import key operation specified bynormalizedDerivedKeyAlgorithmImport using "raw" asformat,secret askeyData,derivedKeyType asalgorithm and usingextractable andusages.
Letresult be theCryptoKey object that results from performing the import key operation specified bynormalizedAlgorithm usingkeyData,algorithm,format,extractable andusages.
Letresult be the result of convertingresult to an ECMAScript Object inrealm, as defined by [WebIDL].
Resolvepromise withresult.
Note
Support of "raw" key formats is encouraged for interoperability. Web developers should consult the test-suite for detailed information on implementations support of other key formats.
Note
For structured key formats, "spki", "pkcs8" and "jwk", fields that are not explicitly referred to in the key import procedures for an algorithm are ignored.
14.3.10The exportKey method
When invoked, theexportKey methodMUST perform the following steps:
Letformat andkey be theformat andkey parameters passed to theexportKey() method, respectively.
Letresult be the result of convertingresult to an ECMAScript Object inrealm, as defined by [WebIDL].
Resolvepromise withresult.
Note
Support of "raw" key formats is encouraged for interoperability. Web developers should consult the test-suite for detailed information on implementations support of other key formats.
14.3.11The wrapKey method
When invoked, thewrapKey methodMUST perform the following steps:
Letformat,key,wrappingKey andalgorithm be theformat,key,wrappingKey andwrapAlgorithm parameters passed to thewrapKey() method, respectively.
LetnormalizedAlgorithm be the result ofnormalizing an algorithm, withalg set toalgorithm andop set to "wrapKey".
If an error occurred, letnormalizedAlgorithm be the result ofnormalizing an algorithm, withalg set toalgorithm andop set to "encrypt".
If an error occurred, return a Promise rejected withnormalizedAlgorithm.
Because the wrapKey method effectively exports the key, only keys marked as extractable may be wrapped. In particular, this means that this API cannot create a wrapped JWK key that is marked as non-extractable using theext JWK member.
However, the unwrapKey methoddoes support theext JWK member, so that wrapped non-extractable keys created elsewhere, for example by a server, can be unwrapped using this API.
LetexportedKey be the result of performing the export key operation specified by the[[algorithm]] internal slot ofkey usingkey andformat.
Ifformat is equal to the strings "raw", "pkcs8", or "spki":
Letjson be the result of representingexportedKey as a UTF-16 string conforming to the JSON grammar; for example, by executing theJSON.stringify algorithm specified in [ECMA-262] in the context of a new global object.
The key wrapping operations for some algorithms place constraints on the payload size. For example AES-KW requires the payload to be a multiple of 8 bytes in length and RSA-OAEP places a restriction on the length. For key formats that offer flexibility in serialization of a given key (for example JWK), implementations may choose to adapt the serialization to the constraints of the wrapping algorithm. This is why JSON.stringify is not normatively required, as otherwise it would prohibit implementations from introducing added padding.
IfnormalizedAlgorithm supports the wrap key operation:
Letresult be the result of performing the wrap key operation specified bynormalizedAlgorithm usingalgorithm,wrappingKey askey andbytes asplaintext.
Otherwise, ifnormalizedAlgorithm supports the encrypt operation:
Letresult be the result of performing the encrypt operation specified bynormalizedAlgorithm usingalgorithm,wrappingKey askey andbytes asplaintext.
Support of "raw" key formats is encouraged for interoperability. Web developers should consult the test-suite for detailed information on implementations support of other key formats.
14.3.12The unwrapKey method
When invoked, theunwrapKey methodMUST perform the following steps:
Letformat,unwrappingKey,algorithm,unwrappedKeyAlgorithm,extractable andusages, be theformat,unwrappingKey,unwrapAlgorithm,unwrappedKeyAlgorithm,extractable andkeyUsages parameters passed to theunwrapKey() method, respectively.
IfnormalizedAlgorithm supports an unwrap key operation:
Letbytes be the result of performing the unwrap key operation specified bynormalizedAlgorithm usingalgorithm,unwrappingKey askey andwrappedKey asciphertext.
Otherwise, ifnormalizedAlgorithm supports a decrypt operation:
Letbytes be the result of performing the decrypt operation specified bynormalizedAlgorithm usingalgorithm,unwrappingKey askey andwrappedKey asciphertext.
Letkey be the result of executing theparse a JWK algorithm, withbytes as thedata to be parsed.
Letresult be the result of performing the import key operation specified bynormalizedKeyAlgorithm usingunwrappedKeyAlgorithm asalgorithm,format,usages andextractable and withkey askeyData.
Letresult be the result of convertingresult to an ECMAScript Object inrealm, as defined by [WebIDL].
Resolvepromise withresult.
Note
Support of "raw" key formats is encouraged for interoperability. Web developers should consult the test-suite for detailed information on implementations support of other key formats.
14.4Exceptions
The methods of theSubtleCrypto interface return errors by rejecting the returned promise with a predefined exception defined in ECMAScript [ECMA-262] orDOMException. The following predefined exceptions are used:TypeError. The following DOMException types from [DOM] are used:
The operation failed for an operation-specific reason
When this specification says tothrow an error, the user agent must throw an error as described in [WebIDL]. When this occurs in a sub-algorithm, this results in termination of execution of the sub-algorithm and all ancestor algorithms until one is reached that explicitly describes procedures for catching exceptions. The error object thrown shall be associated with therelevant realm ofthis.
TheJsonWebKey dictionary provides a way to represent and exchange cryptographic keys represented by the JSON Web Key [JWK] structure, while allowing native and efficient use within Web Cryptography API applications.
The members of theRsaOtherPrimesInfo are defined in Section 6.3.2.7 of JSON Web Algorithms.
TheBigInteger typedef is aUint8Array that holds an arbitrary magnitude unsigned integer in big-endian order. Values read from the APISHALL have minimal typed array length (that is, at most 7 leading zero bits, except the value 0 which shall have length 8 bits). The APISHALL accept values with any number of leading zero bits, including the empty array, which represents zero.
Note
Since the integer is unsigned, the highest order bit is NOT a sign bit. Implementors should take care when mapping to big integer implementations that expected signed integers.
TheCryptoKeyPair dictionary represents an asymmetric key pair that is comprised of both public (publicKey) and private (privateKey) keys.
18.Algorithms
18.1Overview
This section is non-normative.
In addition to providing a common interface to perform cryptographic operations, by way of theSubtleCrypto interface, this specification also provides descriptions for a variety of algorithms that authors may wish to use and that User Agents may choose to implement. This includes a selection of commonly-deployed symmetric and asymmetric algorithms, key derivation mechanisms, and methods for wrapping and unwrapping keys. Further, this specification defines a process to allow additional specifications to introduce additional cryptographic algorithms.
18.2Concepts
18.2.1Naming
Every cryptographic algorithm defined for use with the Web Cryptography APIMUST have a unique name, referred to as itsrecognized algorithm name, such that no other specification defines the same case-insensitive string for use with the Web Cryptography API.
18.2.2Supported Operations
Every cryptographic algorithm defined for use with the Web Cryptography API has a list ofsupported operations, which are a set of sub-algorithms to be invoked by theSubtleCrypto interface in order to perform the desired cryptographic operation. This specification makes use of the following operations:
encrypt
decrypt
sign
verify
digest
deriveBits
wrapKey
unwrapKey
generateKey
importKey
exportKey
get key length
If a given algorithm specification does not list a particular operation as supported, or explicitly lists an operation as not-supported, then the User AgentMUST behave as if the invocation of the sub-algorithm threw a NotSupportedError.
18.2.3Normalization
Every cryptographic algorithm defined for use with the Web Cryptography APIMUST define, for everysupported operation, the IDL type to use foralgorithm normalization, as well as the IDL type or types of the return values of the sub-algorithms.
18.3Specification Conventions
Every cryptographic algorithm definition within this specification employs the following specification conventions. A section, titled"Registration", will include therecognized algorithm name. Additionally, it includes a table, which will list each of thesupported operations as rows, identified by theOperation column. The contents of theParameters column for a given row will contain the IDL type to use foralgorithm normalization for that operation, and the contents of theResult column for that row indicate the IDL type that results from performing the supported operation.
If a conforming User Agent implements an algorithm, itMUST implement all of the supported operations andMUST return the IDL type specified.
Additionally, upon initialization, conforming User Agents must perform thedefine an algorithm steps for each of the supported operations, registering their IDL parameter type as indicated.
Unless otherwise stated, objects created by the operations defined in this specification shall be associated with therelevant realm ofthis.
18.4Algorithm Normalization
18.4.1Description
This section is non-normative.
TheAlgorithmIdentifier typedef permits algorithms to either be specified as aDOMString or an object. The usage ofDOMString is to permit authors a short-hand for noting algorithms that have no parameters (e.g. SHA-1). The usage of object is to allow anAlgorithm (or appropriate subclass) to be specified, which contains all of the associated parameters for an object.
Because of this, it's necessary to define the algorithm for converting anAlgorithmIdentifier into an appropriate dictionary that is usable with this API. This algorithm must be extensible, so as to allow new cryptographic algorithms to be added, and consistent, so that Web IDL type mapping can occur before any control is returned to the calling script, which would potentially allow the mutation of parameters or the script environment.
18.4.2Internal State Objects
This specification makes use of an internal object,supportedAlgorithms. This internal object is not exposed to applications.
Because this value is not exposed to applications, the exact type is not specified. It is only required to behave as an associative container of key/value pairs, where comparisons of keys are performed in a case-sensitive manner.
The initial contents of this internal object are as follows:
Thedefine an algorithm algorithm is used by specification authors to indicate how a user agent should normalize arguments for a particular algorithm. Its input is an algorithm namealg, represented as a DOMString, operation nameop, represented as a DOMString, and desired IDL dictionary typetype. The algorithm behaves as follows:
LetregisteredAlgorithms be the associative container stored at theop key ofsupportedAlgorithms.
Set thealg key ofregisteredAlgorithms to the IDL dictionary typetype.
18.4.4Normalizing an algorithm
Thenormalize an algorithm algorithm defines a process for coercing inputs to a targeted IDL dictionary type, after Web IDL conversion has occurred. It is designed to be extensible, to allow future specifications to define additional algorithms, as well as safe for use with Promises. Its input is an operation nameop and anAlgorithmIdentifieralg. Its output is either an IDL dictionary type or an error. It behaves as follows:
Ifalg is an instance of a DOMString:
Return the result of running thenormalize an algorithm algorithm, with thealg set to a newAlgorithm dictionary whosename attribute isalg, and with theop set toop.
Ifalg is an object:
LetregisteredAlgorithms be the associative container stored at theop key ofsupportedAlgorithms.
LetinitialAlg be the result of converting the ECMAScript object represented byalg to the IDL dictionary typeAlgorithm, as defined by [WebIDL].
If an error occurred, return the error and terminate this algorithm.
LetalgName be the value of thename attribute ofinitialAlg.
IfregisteredAlgorithms contains a key that is acase-insensitive string match foralgName:
SetalgName to the value of the matching key.
LetdesiredType be the IDL dictionary type stored atalgName inregisteredAlgorithms.
Otherwise:
Return a newNotSupportedError and terminate this algorithm.
LetnormalizedAlgorithm be the result of converting the ECMAScript object represented byalg to the IDL dictionary typedesiredType, as defined by [WebIDL].
Set thename attribute ofnormalizedAlgorithm toalgName.
If an error occurred, return the error and terminate this algorithm.
Letdictionaries be a list consisting of the IDL dictionary typedesiredType and all ofdesiredType's inherited dictionaries, in order from least to most derived.
For each dictionarydictionary indictionaries:
For each dictionary membermember declared ondictionary, in order:
Letkey be the identifier ofmember.
LetidlValue be the value of the dictionary member with key name ofkey onnormalizedAlgorithm.
Ifmember is of the typeBufferSource and is present:
Set the dictionary member onnormalizedAlgorithm with key namekey to the result ofgetting a copy of the bytes held byidlValue, replacing the current value.
Set the dictionary member onnormalizedAlgorithm with key namekey to the result ofnormalizing an algorithm, with thealg set toidlValue and theop set to "digest".
Set the dictionary member onnormalizedAlgorithm with key namekey to the result ofnormalizing an algorithm, with thealg set toidlValue and theop set to the operation defined by the specification that defines the algorithm identified byalgName.
If an error occurred, return the error and terminate this algorithm.
ReturnnormalizedAlgorithm.
18.5Recommendations
This section is non-normative.
18.5.1For Authors
As this API is meant to be extensible, in order to keep up with future developments within cryptography, there are no algorithms that conforming user agents are required to implement. As such, authors should check to see what algorithms are currently recommended and supported by implementations.
As highlighted in theSecurity Considerations, even cryptographic algorithms that might be considered strong for one purpose may be insufficient when used with another purpose. Authors should therefore proceed with extreme caution before inventing new cryptographic protocols.
Additionally, this specification includes several algorithms which, in their default usage, can result in cryptographic vulnerabilities. While these concerns may be mitigated, such as through the combination and composition with additional algorithms provided by this specification, authors should proceed with caution and review the relevant cryptographic literature before using a given algorithm. The inclusion of algorithms within this specification is not an indicator of their suitability for any or all purpose, and instead merely serve to provide as a specification for how a conforming User Agent must implement the given algorithm, if it choses to implement the algorithm.
18.5.2For Implementers
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:
The table below contains an overview of the algorithms described within this specification, as well as the set ofSubtleCrypto methods the algorithm may be used with. In order for an algorithm to be used with a method the corresponding operation or operations, as defined in the procedures for the method, must be defined in the algorithm specification. Note that this mapping of methods to underlying operations is not one-to-one:
ThegenerateKey method requires the generateKey operation.
TheimportKey method requires the importKey operation.
TheexportKey method requires the exportKey operation.
ThederiveKey method requires the deriveBits operation for the key derivation algorithm and the get key length and importKey operations for the derived key algorithm.
ThederiveBits method requires the deriveBits operation for the key derivation algorithm.
ThewrapKey method requires either the encrypt or wrapKey operation for the wrapping algorithm and the exportKey operation for the wrapped key algorithm.
TheunwrapKey method requires either the decrypt or unwrapKey operation for the unwrapping algorithm and the importKey operation for the unwrapped key algorithm.
Note
Application developers and script authors should not interpret this table as a recommendation for the use of particular algorithms. Instead, it simply documents what methods are supported. Authors should refer to theSecurity considerations for authors section of this document to better understand the risks and concerns that may arise when using certain algorithms.
The "RSASSA-PKCS1-v1_5" algorithm identifier is used to perform signing and verification using the RSASSA-PKCS1-v1_5 algorithm specified in [RFC3447] and using the SHA hash functions defined in this specification.
Other specifications may specify the use of additional hash algorithms with RSASSA-PKCS1-v1_5. Such specifications must define the digest operations for the additional hash algorithms andkey import steps andkey export steps for RSASSA-PKCS1-v1_5.
Perform the signature generation operation defined in Section 8.2 of [RFC3447] with the key represented by the[[handle]] internal slot ofkey as the signer's private key andmessage asM and using the hash function specified in thehash attribute of the[[algorithm]] internal slot ofkey as the Hash option for the EMSA-PKCS1-v1_5 encoding method.
If performing the operation results in an error, thenthrow anOperationError.
Letsignature be the valueS that results from performing the operation.
Perform the signature verification operation defined in Section 8.2 of [RFC3447] with the key represented by the[[handle]] internal slot ofkey as the signer's RSA public key andmessage asM andsignature asS and using the hash function specified in thehash attribute of the[[algorithm]] internal slot ofkey as the Hash option for the EMSA-PKCS1-v1_5 encoding method.
Letresult be a boolean with value true if the result of the operation was "valid signature" and the value false otherwise.
Returnresult.
20.8.3Generate Key
Ifusages contains an entry which is not "sign" or "verify", thenthrow aSyntaxError.
Generate an RSA key pair, as defined in [RFC3447], with RSA modulus length equal to themodulusLength attribute ofnormalizedAlgorithm and RSA public exponent equal to thepublicExponent attribute ofnormalizedAlgorithm.
If an error occurred while parsing, thenthrow aDataError.
If thealgorithm object identifier field of thealgorithm AlgorithmIdentifier field ofspki is not equal to thersaEncryption object identifier defined in [RFC3447], thenthrow aDataError.
LetpublicKey be the result of performing theparse an ASN.1 structure algorithm, withdata as thesubjectPublicKeyInfo field ofspki,structure as theRSAPublicKey structure specified in Section A.1.1 of [RFC3447], andexactData set to true.
If an error occurred while parsing, or it can be determined thatpublicKey is not a valid public key according to [RFC3447], thenthrow aDataError.
Letkey be a newCryptoKey that represents the RSA public key identified bypublicKey.
Ifusages contains an entry which is not "sign" thenthrow aSyntaxError.
LetprivateKeyInfo be the result of running theparse a privateKeyInfo algorithm overkeyData.
If an error occurred while parsing, thenthrow aDataError.
If thealgorithm object identifier field of theprivateKeyAlgorithm PrivateKeyAlgorithm field ofprivateKeyInfo is not equal to thersaEncryption object identifier defined in [RFC3447], thenthrow aDataError.
LetrsaPrivateKey be the result of performing theparse an ASN.1 structure algorithm, withdata as theprivateKey field ofprivateKeyInfo,structure as theRSAPrivateKey structure specified in Section A.1.2 of [RFC3447], andexactData set to true.
If an error occurred while parsing, or ifrsaPrivateKey is not a valid RSA private key according to [RFC3447], thenthrow aDataError.
Letkey be a newCryptoKey that represents the RSA private key identified byrsaPrivateKey.
If thed field ofjwk is present andusages contains an entry which is not "sign", or, if thed field ofjwk is not present andusages contains an entry which is not "verify" thenthrow aSyntaxError.
If thekty field ofjwk is not a case-sensitive string match to "RSA", thenthrow aDataError.
Ifusages is non-empty and theuse field ofjwk is present and is not a case-sensitive string match to "sig", thenthrow aDataError.
If thekey_ops field ofjwk is present, and is invalid according to the requirements of JSON Web Key [JWK] or does not contain all of the specifiedusages values, thenthrow aDataError.
If theext field ofjwk is present and has the value false andextractable is true, thenthrow aDataError.
Lethash be a be a string whose initial value is undefined.
Letdata be an instance of theSubjectPublicKeyInfo ASN.1 structure defined in [RFC5280] with the following properties:
Set thealgorithm field to anAlgorithmIdentifier ASN.1 type with the following properties:
Set thealgorithm field to the OIDrsaEncryption defined in [RFC3447].
Set theparams field to the ASN.1 type NULL.
Set thesubjectPublicKey field to the result of DER-encoding anRSAPublicKey ASN.1 type, as defined in [RFC3447], Appendix A.1.1, that represents the RSA public key represented by the[[handle]] internal slot ofkey
Letdata be an instance of thePrivateKeyInfo ASN.1 structure defined in [RFC5208] with the following properties:
Set theversion field to0.
Set theprivateKeyAlgorithm field to aPrivateKeyAlgorithmIdentifier ASN.1 type with the following properties:
Set thealgorithm field to the OIDrsaEncryption defined in [RFC3447].
Set theparams field to the ASN.1 type NULL.
Set theprivateKey field to the result of DER-encoding anRSAPrivateKey ASN.1 type, as defined in [RFC3447], Appendix A.1.2, that represents the RSA private key represented by the[[handle]] internal slot ofkey
Note
[RFC5208] specifies that the encoding of this field should beBER encoded in Section 5 (as a "for example"). However, to avoid requiring WebCrypto implementations support BER-encoding and BER-decoding, onlyDER encodings are produced or accepted.
Set the attributes namedd,p,q,dp,dq, andqi ofjwk according to the corresponding definitions in JSON Web Algorithms [JWA], Section 6.3.2.
If the underlying RSA private key represented by the[[handle]] internal slot ofkey is represented by more than two primes, set the attribute namedoth ofjwk according to the corresponding definition in JSON Web Algorithms [JWA], Section 6.3.2.7
Set thekey_ops attribute ofjwk to theusages attribute ofkey.
Set theext attribute ofjwk to the[[extractable]] internal slot ofkey.
The "RSA-PSS" algorithm identifier is used to perform signing and verification using the RSASSA-PSS algorithm specified in [RFC3447], using the SHA hash functions defined in this specification and the mask generation formula MGF1.
Other specifications may specify the use of additional hash algorithms with RSASSA-PSS. Such specifications must define the digest operation for the additional hash algorithms andkey import steps andkey export steps for RSASSA-PSS.
Perform the signature generation operation defined in Section 8.1 of [RFC3447] with the key represented by the[[handle]] internal slot ofkey as the signer's private key,K, andmessage as the message to be signed,M, and using the hash function specified by thehash attribute of the[[algorithm]] internal slot ofkey as the Hash option, MGF1 (defined in Section B.2.1 of [RFC3447]) as the MGF option and thesaltLength member ofnormalizedAlgorithm as the salt length option for the EMSA-PSS-ENCODE operation.
If performing the operation results in an error, thenthrow anOperationError.
Letsignature be the signature, S, that results from performing the operation.
Perform the signature verification operation defined in Section 8.1 of [RFC3447] with the key represented by the[[handle]] internal slot ofkey as the signer's RSA public key andmessage asM andsignature asS and using the hash function specified by thehash attribute of the[[algorithm]] internal slot ofkey as the Hash option, MGF1 (defined in Section B.2.1 of [RFC3447]) as the MGF option and thesaltLength member ofnormalizedAlgorithm as the salt length option for the EMSA-PSS-VERIFY operation.
Letresult be a boolean with the value true if the result of the operation was "valid signature" and the value false otherwise.
21.4.3Generate Key
Ifusages contains an entry which is not "sign" or "verify", thenthrow aSyntaxError.
Generate an RSA key pair, as defined in [RFC3447], with RSA modulus length equal to themodulusLength member ofnormalizedAlgorithm and RSA public exponent equal to thepublicExponent member ofnormalizedAlgorithm.
If performing the operation results in an error, thenthrow anOperationError.
If an error occurred while parsing, thenthrow aDataError.
If thealgorithm object identifier field of thealgorithm AlgorithmIdentifier field ofspki is not equal to thersaEncryption object identifier defined in [RFC3447], thenthrow aDataError.
LetpublicKey be the result of performing theparse an ASN.1 structure algorithm, withdata as thesubjectPublicKeyInfo field ofspki,structure as theRSAPublicKey structure specified in Section A.1.1 of [RFC3447], andexactData set to true.
If an error occurred while parsing, or it can be determined thatpublicKey is not a valid public key according to [RFC3447], thenthrow aDataError.
Letkey be a newCryptoKey that represents the RSA public key identified bypublicKey.
Ifusages contains an entry which is not "sign" thenthrow aSyntaxError.
LetprivateKeyInfo be the result of running theparse a privateKeyInfo algorithm overkeyData.
If an error occurred while parsing, thenthrow aDataError.
If thealgorithm object identifier field of theprivateKeyAlgorithm PrivateKeyAlgorithm field ofprivateKeyInfo is not equal to thersaEncryption object identifier defined in [RFC3447], thenthrow aDataError.
LetrsaPrivateKey be the result of performing theparse an ASN.1 structure algorithm, withdata as theprivateKey field ofprivateKeyInfo,structure as theRSAPrivateKey structure specified in Section A.1.2 of [RFC3447], andexactData set to true.
If an error occurred while parsing, or ifrsaPrivateKey is not a valid RSA private key according to [RFC3447], thenthrow aDataError.
Letkey be a newCryptoKey that represents the RSA private key identified byrsaPrivateKey.
If thed field ofjwk is present andusages contains an entry which is not "sign", or, if thed field ofjwk is not present andusages contains an entry which is not "verify" thenthrow aSyntaxError.
If thekty field ofjwk is not a case-sensitive string match to "RSA", thenthrow aDataError.
Ifusages is non-empty and theuse field ofjwk is present and is not a case-sensitive string match to "sig", thenthrow aDataError.
If thekey_ops field ofjwk is present, and is invalid according to the requirements of JSON Web Key [JWK] or does not contain all of the specifiedusages values, thenthrow aDataError.
If theext field ofjwk is present and has the value false andextractable is true, thenthrow aDataError.
Letdata be an instance of theSubjectPublicKeyInfo ASN.1 structure defined in [RFC5280] with the following properties:
Set thealgorithm field to anAlgorithmIdentifier ASN.1 type with the following properties:
Set thealgorithm field to the OIDrsaEncryption defined in [RFC3447].
Set theparams field to the ASN.1 type NULL.
Set thesubjectPublicKey field to the result of DER-encoding anRSAPublicKey ASN.1 type, as defined in [RFC3447], Appendix A.1.1, that represents the RSA public key represented by the[[handle]] internal slot ofkey
Letdata be an instance of thePrivateKeyInfo ASN.1 structure defined in [RFC5208] with the following properties:
Set theversion field to0.
Set theprivateKeyAlgorithm field to aPrivateKeyAlgorithmIdentifier ASN.1 type with the following properties:
Set thealgorithm field to the OIDrsaEncryption defined in [RFC3447].
Set theparams field to the ASN.1 type NULL.
Set theprivateKey field to the result of DER-encoding anRSAPrivateKey ASN.1 type, as defined in [RFC3447], Appendix A.1.2, that represents the RSA private key represented by the[[handle]] internal slot ofkey
Note
[RFC5208] specifies that the encoding of this field should beBER encoded in Section 5 (as a "for example"). However, to avoid requiring WebCrypto implementations support BER-encoding and BER-decoding, onlyDER encodings are produced or accepted.
Set the attributes namedd,p,q,dp,dq, andqi ofjwk according to the corresponding definitions in JSON Web Algorithms [JWA], Section 6.3.2.
If the underlying RSA private key represented by the[[handle]] internal slot ofkey is represented by more than two primes, set the attribute namedoth ofjwk according to the corresponding definition in JSON Web Algorithms [JWA], Section 6.3.2.7
Set thekey_ops attribute ofjwk to theusages attribute ofkey.
Set theext attribute ofjwk to the[[extractable]] internal slot ofkey.
The "RSA-OAEP" algorithm identifier is used to perform encryption and decryption ordering to the RSAES-OAEP algorithm specified in [RFC3447], using the SHA hash functions defined in this specification and using the mask generation function MGF1.
Other specifications may specify the use of additional hash algorithms with RSAES-OAEP. Such specifications must define the digest operation for the additional hash algorithm andkey import steps andkey export steps for RSAES-OAEP.
Letlabel be thelabel member ofnormalizedAlgorithm or the empty byte sequence if thelabel member ofnormalizedAlgorithm is not present.
Perform the encryption operation defined in Section 7.1 of [RFC3447] with the key represented bykey as the recipient's RSA public key,plaintext as the message to be encrypted,M andlabel as the label,L, and with the hash function specified by thehash attribute of the[[algorithm]] internal slot ofkey as the Hash option and MGF1 (defined in Section B.2.1 of [RFC3447]) as the MGF option.
If performing the operation results in an error, thenthrow anOperationError.
Letciphertext be the valueC that results from performing the operation.
Letlabel be thelabel member ofnormalizedAlgorithm or the empty byte sequence if thelabel member ofnormalizedAlgorithm is not present.
Perform the decryption operation defined in Section 7.1 of [RFC3447] with the key represented bykey as the recipient's RSA private key,ciphertext as the ciphertext to be decrypted, C, andlabel as the label,L, and with the hash function specified by thehash attribute of the[[algorithm]] internal slot ofkey as the Hash option and MGF1 (defined in Section B.2.1 of [RFC3447]) as the MGF option.
If performing the operation results in an error, thenthrow anOperationError.
Letplaintext the valueM that results from performing the operation.
Returnplaintext.
22.4.3Generate Key
Ifusages contains an entry which is not "encrypt", "decrypt", "wrapKey" or "unwrapKey", thenthrow aSyntaxError.
Generate an RSA key pair, as defined in [RFC3447], with RSA modulus length equal to themodulusLength member ofnormalizedAlgorithm and RSA public exponent equal to thepublicExponent member ofnormalizedAlgorithm.
If performing the operation results in an error, thenthrow anOperationError.
If an error occurred while parsing, thenthrow aDataError.
If thealgorithm object identifier field of thealgorithm AlgorithmIdentifier field ofspki is not equal to thersaEncryption object identifier defined in [RFC3447], thenthrow aDataError.
LetpublicKey be the result of performing theparse an ASN.1 structure algorithm, withdata as thesubjectPublicKeyInfo field ofspki,structure as theRSAPublicKey structure specified in Section A.1.1 of [RFC3447], andexactData set to true.
If an error occurred while parsing, or it can be determined thatpublicKey is not a valid public key according to [RFC3447], thenthrow aDataError.
Letkey be a newCryptoKey that represents the RSA public key identified bypublicKey.
Ifusages contains an entry which is not "decrypt" or "unwrapKey", thenthrow aSyntaxError.
LetprivateKeyInfo be the result of running theparse a privateKeyInfo algorithm overkeyData.
If an error occurred while parsing, thenthrow aDataError.
If thealgorithm object identifier field of theprivateKeyAlgorithm PrivateKeyAlgorithm field ofprivateKeyInfo is not equal to thersaEncryption object identifier defined in [RFC3447], thenthrow aDataError.
LetrsaPrivateKey be the result of performing theparse an ASN.1 structure algorithm, withdata as theprivateKey field ofprivateKeyInfo,structure as theRSAPrivateKey structure specified in Section A.1.2 of [RFC3447], andexactData set to true.
If an error occurred while parsing, or ifrsaPrivateKey is not a valid RSA private key according to [RFC3447], thenthrow aDataError.
Letkey be a newCryptoKey that represents the RSA private key identified byrsaPrivateKey.
If thed field ofjwk is present andusages contains an entry which is not "decrypt" or "unwrapKey", thenthrow aSyntaxError.
If thed field ofjwk is not present andusages contains an entry which is not "encrypt" or "wrapKey", thenthrow aSyntaxError.
If thekty field ofjwk is not a case-sensitive string match to "RSA", thenthrow aDataError.
Ifusages is non-empty and theuse field ofjwk is present and is not a case-sensitive string match to "enc", thenthrow aDataError.
If thekey_ops field ofjwk is present, and is invalid according to the requirements of JSON Web Key [JWK] or does not contain all of the specifiedusages values, thenthrow aDataError.
If theext field ofjwk is present and has the value false andextractable is true, thenthrow aDataError.
Letdata be an instance of theSubjectPublicKeyInfo ASN.1 structure defined in [RFC5280] with the following properties:
Set thealgorithm field to anAlgorithmIdentifier ASN.1 type with the following properties:
Set thealgorithm field to the OIDrsaEncryption defined in [RFC3447].
Set theparams field to the ASN.1 type NULL.
Set thesubjectPublicKey field to the result of DER-encoding anRSAPublicKey ASN.1 type, as defined in [RFC3447], Appendix A.1.1, that represents the RSA public key represented by the[[handle]] internal slot ofkey
Letdata be an instance of thePrivateKeyInfo ASN.1 structure defined in [RFC5208] with the following properties:
Set theversion field to0.
Set theprivateKeyAlgorithm field to aPrivateKeyAlgorithmIdentifier ASN.1 type with the following properties:
Set thealgorithm field to the OIDrsaEncryption defined in [RFC3447].
Set theparams field to the ASN.1 type NULL.
Set theprivateKey field to the result of DER-encoding anRSAPrivateKey ASN.1 type, as defined in [RFC3447], Appendix A.1.2, that represents the RSA private key represented by the[[handle]] internal slot ofkey
Note
[RFC5208] specifies that the encoding of this field should beBER encoded in Section 5 (as a "for example"). However, to avoid requiring WebCrypto implementations support BER-encoding and BER-decoding, onlyDER encodings are produced or accepted.
Set the attributes namedd,p,q,dp,dq, andqi ofjwk according to the corresponding definitions in JSON Web Algorithms [JWA], Section 6.3.2.
If the underlying RSA private key represented by the[[handle]] internal slot ofkey is represented by more than two primes, set the attribute namedoth ofjwk according to the corresponding definition in JSON Web Algorithms [JWA], Section 6.3.2.7
Set thekey_ops attribute ofjwk to theusages attribute ofkey.
Set theext attribute ofjwk to the[[extractable]] internal slot ofkey.
The "ECDSA" algorithm identifier is used to perform signing and verification using the ECDSA algorithm specified in [RFC6090] and using the SHA hash functions and elliptic curves defined in this specification.
Other specifications may specify the use of additional elliptic curves and hash algorithms with ECDSA. To specify additional hash algorithms to be used with ECDSA, a specification must define aregistered algorithm that supports the digest operation. To specify an additional elliptic curve a specification must definethe curve name,ECDSA signature steps,ECDSA verification steps,ECDSA generation steps,ECDSA key import steps andECDSA key export steps.
TheNamedCurve type represents named elliptic curves, which are a convenient way to specify the domain parameters of well-known elliptic curves. The following values defined by this specification:
"P-256"
NIST recommended curve P-256, also known assecp256r1.
"P-384"
NIST recommended curve P-384, also known assecp384r1.
"P-521"
NIST recommended curve P-521, also known assecp521r1.
LethashAlgorithm be thehash member ofnormalizedAlgorithm.
LetM be the result of performing the digest operation specified byhashAlgorithm usingmessage.
Letd be the ECDSA private key associated withkey.
Letparams be the EC domain parameters associated withkey.
If thenamedCurve attribute of the[[algorithm]] internal slot ofkey is "P-256", "P-384" or "P-521":
Perform the ECDSA signing process, as specified in [RFC6090], Section 5.4, withM as the message, usingparams as the EC domain parameters, and withd as the private key.
Letr ands be the pair of integers resulting from performing the ECDSA signing process.
Letn be the smallest integer such thatn * 8 is greater than the logarithm to base 2 of the order of the base point of the elliptic curve identified byparams.
LethashAlgorithm be thehash member ofnormalizedAlgorithm.
LetM be the result of performing the digest operation specified byhashAlgorithm usingmessage.
LetQ be the ECDSA public key associated withkey.
Letparams be the EC domain parameters associated withkey.
If thenamedCurve attribute of the[[algorithm]] internal slot ofkey is "P-256", "P-384" or "P-521":
Perform the ECDSA verifying process, as specified in [RFC6090], Section 5.3, withM as the received message,signature as the received signature and usingparams as the EC domain parameters, andQ as the public key.
Perform theECDSA verification steps specified in that specification passing inM,signature,params andQ and resulting in an indication of whether or not the purported signature is valid.
Letresult be a boolean with the valuetrue if the signature is valid and the valuefalse otherwise.
Returnresult.
23.7.3Generate Key
Ifusages contains a value which is not one of "sign" or "verify", thenthrow aSyntaxError.
If thenamedCurve member ofnormalizedAlgorithm is "P-256", "P-384" or "P-521":
Generate an Elliptic Curve key pair, as defined in [RFC6090] with domain parameters for the curve identified by thenamedCurve member ofnormalizedAlgorithm.
If an error occurred while parsing, thenthrow aDataError.
If thealgorithm object identifier field of thealgorithm AlgorithmIdentifier field ofspki is not equal to theid-ecPublicKey object identifier defined in [RFC5480], thenthrow aDataError.
If theparameters field of thealgorithm AlgorithmIdentifier field ofspki is absent, thenthrow aDataError.
Letparams be theparameters field of thealgorithm AlgorithmIdentifier field ofspki.
Ifparams is not an instance of theECParameters ASN.1 type defined in [RFC5480] that specifies anamedCurve, thenthrow aDataError.
LetnamedCurve be a string whose initial value is undefined.
Ifparams is equivalent to thesecp256r1 object identifier defined in [RFC5480]:
SetnamedCurve "P-256".
Ifparams is equivalent to thesecp384r1 object identifier defined in [RFC5480]:
SetnamedCurve "P-384".
Ifparams is equivalent to thesecp521r1 object identifier defined in [RFC5480]:
SetnamedCurve "P-521".
IfnamedCurve is not undefined:
LetpublicKey be the Elliptic Curve public key identified by performing the conversion steps defined in Section 2.3.4 of [SEC1] using thesubjectPublicKey field ofspki.
The uncompressed point formatMUST be supported.
If the implementation does not support the compressed point format and a compressed point is provided,throw aDataError.
If a decode error occurs or an identity point is found,throw aDataError.
Letkey be a newCryptoKey that representspublicKey.
If thealgorithm object identifier field of theprivateKeyAlgorithm PrivateKeyAlgorithm field ofprivateKeyInfo is not equal to theid-ecPublicKey object identifier defined in [RFC5480], thenthrow aDataError.
If theparameters field of theprivateKeyAlgorithm PrivateKeyAlgorithmIdentifier field ofprivateKeyInfo is not present, thenthrow aDataError.
Letparams be theparameters field of theprivateKeyAlgorithm PrivateKeyAlgorithmIdentifier field ofprivateKeyInfo.
Ifparams is not an instance of theECParameters ASN.1 type defined in [RFC5480] that specifies anamedCurve, thenthrow aDataError.
LetnamedCurve be a string whose initial value is undefined.
Ifparams is equivalent to thesecp256r1 object identifier defined in [RFC5480]:
SetnamedCurve "P-256".
Ifparams is equivalent to thesecp384r1 object identifier defined in [RFC5480]:
SetnamedCurve "P-384".
Ifparams is equivalent to thesecp521r1 object identifier defined in [RFC5480]:
SetnamedCurve "P-521".
IfnamedCurve is not undefined:
LetecPrivateKey be the result of performing theparse an ASN.1 structure algorithm, withdata as theprivateKey field ofprivateKeyInfo,structure as the ASN.1ECPrivateKey structure specified in Section 3 of [RFC5915], andexactData set to true.
If an error occurred while parsing, thenthrow aDataError.
If theparameters field ofecPrivateKey is present, and is not an instance of thenamedCurve ASN.1 type defined in [RFC5480], or does not contain the same object identifier as theparameters field of theprivateKeyAlgorithm PrivateKeyAlgorithmIdentifier field ofprivateKeyInfo, thenthrow aDataError.
Letkey be a newCryptoKey that represents the Elliptic Curve private key identified by performing the conversion steps defined in Section 3 of [RFC5915] usingecPrivateKey.
If thed field is present andusages contains a value which is not "sign", or, if thed field is not present andusages contains a value which is not "verify" thenthrow aSyntaxError.
Ifusages is non-empty and theuse field ofjwk is present and is not "sig", thenthrow aDataError.
If thekey_ops field ofjwk is present, and is invalid according to the requirements of JSON Web Key [JWK], or it does not contain all of the specifiedusages values, thenthrow aDataError.
If theext field ofjwk is present and has the value false andextractable is true, thenthrow aDataError.
LetnamedCurve be a string whose value is equal to thecrv field ofjwk.
Ifjwk does not meet the requirements of Section 6.2.2 of JSON Web Algorithms [JWA], thenthrow aDataError.
Letkey be a newCryptoKey object that represents the Elliptic Curve private key identified by interpretingjwk according to Section 6.2.2 of JSON Web Algorithms [JWA].
Ifjwk does not meet the requirements of Section 6.2.1 of JSON Web Algorithms [JWA], thenthrow aDataError.
Letkey be a newCryptoKey object that represents the Elliptic Curve public key identified by interpretingjwk according to Section 6.2.1 of JSON Web Algorithms [JWA].
Ifusages contains a value which is not "verify" thenthrow aSyntaxError.
IfnamedCurve is "P-256", "P-384" or "P-521":
LetQ be the elliptic curve point on the curve identified by thenamedCurve member ofnormalizedAlgorithm identified by performing the conversion steps defined in Section 2.3.4 of [SEC1] onkeyData.
The uncompressed point formatMUST be supported.
If the implementation does not support the compressed point format and a compressed point is provided,throw aDataError.
If a decode error occurs or an identity point is found,throw aDataError.
Letdata be an instance of theSubjectPublicKeyInfo ASN.1 structure defined in [RFC5280] with the following properties:
Set thealgorithm field to anAlgorithmIdentifier ASN.1 type with the following properties:
Set thealgorithm field to the OIDid-ecPublicKey defined in [RFC5480].
Set theparameters field to an instance of theECParameters ASN.1 type defined in [RFC5480] as follows:
If thenamedCurve attribute of the[[algorithm]] internal slot ofkey is "P-256", "P-384" or "P-521":
LetkeyData be thebyte sequence that represents the Elliptic Curve public key represented by the[[handle]] internal slot ofkey according to the encoding rules specified in Section 2.2 of [RFC5480] and using the uncompressed form. andkeyData.
Letdata be an instance of thePrivateKeyInfo ASN.1 structure defined in [RFC5208] with the following properties:
Set theversion field to0.
Set theprivateKeyAlgorithm field to aPrivateKeyAlgorithmIdentifier ASN.1 type with the following properties:
Set thealgorithm field to the OIDid-ecPublicKey defined in [RFC5480].
Set theparameters field to an instance of theECParameters ASN.1 type defined in [RFC5480] as follows:
If thenamedCurve attribute of the[[algorithm]] internal slot ofkey is "P-256", "P-384" or "P-521":
LetkeyData be the result of DER-encoding an instance of theECPrivateKey structure defined in Section 3 of [RFC5915] for the Elliptic Curve private key represented by the[[handle]] internal slot ofkey and that conforms to the following:
Theparameters field is present, and is equivalent to theparameters field of theprivateKeyAlgorithm field of thisPrivateKeyInfo ASN.1 structure.
ThepublicKey field is present and represents the Elliptic Curve public key associated with the Elliptic Curve private key represented by the[[handle]] internal slot ofkey.
If thenamedCurve attribute of the[[algorithm]] internal slot ofkey is "P-256", "P-384" or "P-521":
Letdata be abyte sequence representing the Elliptic Curve pointQ represented by the[[handle]] internal slot ofkey according to [SEC1] 2.3.3 using the uncompressed format.
This describes using Elliptic Curve Diffie-Hellman (ECDH) for key generation and key agreement, as specified by [RFC6090].
Other specifications may specify the use of additional elliptic curves with ECDH. To specify an additional elliptic curve a specification must definethe curve name,ECDH generation steps,ECDH derivation steps,ECDH key import steps andECDH key export steps.
Thepublic member represents the peer's EC public key.
24.4Operations
24.4.1Generate Key
Ifusages contains an entry which is not "deriveKey" or "deriveBits" thenthrow aSyntaxError.
If thenamedCurve member ofnormalizedAlgorithm is "P-256", "P-384" or "P-521":
Generate an Elliptic Curve key pair, as defined in [RFC6090] with domain parameters for the curve identified by thenamedCurve member ofnormalizedAlgorithm.
If thenamedCurve member ofnormalizedAlgorithm is a value specified in anapplicable specification that specifies the use of that value with ECDH:
Perform theECDH generation steps specified in that specification, passing innormalizedAlgorithm and resulting in an elliptic curve key pair.
If thenamedCurve property of the[[algorithm]] internal slot ofkey is "P-256", "P-384" or "P-521":
Perform the ECDH primitive specified in [RFC6090] Section 4 withkey as the EC private keyd and the EC public key represented by the[[handle]] internal slot ofpublicKey as the EC public key.
Letsecret be abyte sequence containing the result of applying the field element to octet string conversion defined in Section 6.2 of [RFC6090] to the output of the ECDH primitive.
If an error occurred while parsing, thenthrow aDataError.
If thealgorithm object identifier field of thealgorithm AlgorithmIdentifier field ofspki is not equal to theid-ecPublicKey object identifier defined in [RFC5480], thenthrow aDataError.
If theparameters field of thealgorithm AlgorithmIdentifier field ofspki is absent, thenthrow aDataError.
Letparams be theparameters field of thealgorithm AlgorithmIdentifier field ofspki.
Ifparams is not an instance of theECParameters ASN.1 type defined in [RFC5480] that specifies anamedCurve, thenthrow aDataError.
LetnamedCurve be a string whose initial value is undefined.
Ifparams is equivalent to thesecp256r1 object identifier defined in [RFC5480]:
SetnamedCurve "P-256".
Ifparams is equivalent to thesecp384r1 object identifier defined in [RFC5480]:
SetnamedCurve "P-384".
Ifparams is equivalent to thesecp521r1 object identifier defined in [RFC5480]:
SetnamedCurve "P-521".
IfnamedCurve is not undefined:
LetpublicKey be the Elliptic Curve public key identified by performing the conversion steps defined in Section 2.3.4 of [SEC1] to thesubjectPublicKey field ofspki.
The uncompressed point formatMUST be supported.
If the implementation does not support the compressed point format and a compressed point is provided,throw aDataError.
If a decode error occurs or an identity point is found,throw aDataError.
Letkey be a newCryptoKey that representspublicKey.
If thealgorithm object identifier field of theprivateKeyAlgorithm PrivateKeyAlgorithm field ofprivateKeyInfo is not equal to theid-ecPublicKey object identifier defined in [RFC5480],throw aDataError.
If theparameters field of theprivateKeyAlgorithm PrivateKeyAlgorithmIdentifier field ofprivateKeyInfo is not present,throw aDataError.
Letparams be theparameters field of theprivateKeyAlgorithm PrivateKeyAlgorithmIdentifier field ofprivateKeyInfo.
Ifparams is not an instance of theECParameters ASN.1 type defined in [RFC5480] that specifies anamedCurve, thenthrow aDataError.
LetnamedCurve be a string whose initial value is undefined.
Ifparams is equivalent to thesecp256r1 object identifier defined in [RFC5480]:
SetnamedCurve to "P-256".
Ifparams is equivalent to thesecp384r1 object identifier defined in [RFC5480]:
SetnamedCurve to "P-384".
Ifparams is equivalent to thesecp521r1 object identifier defined in [RFC5480]:
SetnamedCurve to "P-521".
IfnamedCurve is not undefined:
LetecPrivateKey be the result of performing theparse an ASN.1 structure algorithm, withdata as theprivateKey field ofprivateKeyInfo,structure as the ASN.1ECPrivateKey structure specified in Section 3 of [RFC5915], andexactData set to true.
If an error occurred while parsing, thenthrow aDataError.
If theparameters field ofecPrivateKey is present, and is not an instance of thenamedCurve ASN.1 type defined in [RFC5480], or does not contain the same object identifier as theparameters field of theprivateKeyAlgorithm PrivateKeyAlgorithmIdentifier field ofprivateKeyInfo,throw aDataError.
Letkey be a newCryptoKey that represents the Elliptic Curve private key identified by performing the conversion steps defined in Section 3 of [RFC5915] usingecPrivateKey.
Ifusages is non-empty and theuse field ofjwk is present and is not equal to "enc" thenthrow aDataError.
If thekey_ops field ofjwk is present, and is invalid according to the requirements of JSON Web Key [JWK], or it does not contain all of the specifiedusages values, thenthrow aDataError.
If theext field ofjwk is present and has the value false andextractable is true, thenthrow aDataError.
LetnamedCurve be a string whose value is equal to thecrv field ofjwk.
Ifjwk does not meet the requirements of Section 6.2.2 of JSON Web Algorithms [JWA], thenthrow aDataError.
Letkey be a newCryptoKey object that represents the Elliptic Curve private key identified by interpretingjwk according to Section 6.2.2 of JSON Web Algorithms [JWA].
Ifjwk does not meet the requirements of Section 6.2.1 of JSON Web Algorithms [JWA], thenthrow aDataError.
Letkey be a newCryptoKey object that represents the Elliptic Curve public key identified by interpretingjwk according to Section 6.2.1 of JSON Web Algorithms [JWA].
LetQ be the Elliptic Curve public key on the curve identified by thenamedCurve member ofnormalizedAlgorithm identified by performing the conversion steps defined in Section 2.3.4 of [SEC1] tokeyData.
The uncompressed point formatMUST be supported.
If the implementation does not support the compressed point format and a compressed point is provided,throw aDataError.
If a decode error occurs or an identity point is found,throw aDataError.
Letdata be an instance of theSubjectPublicKeyInfo ASN.1 structure defined in [RFC5280] with the following properties:
Set thealgorithm field to anAlgorithmIdentifier ASN.1 type with the following properties:
Set thealgorithm field to the OIDid-ecPublicKey defined in [RFC5480].
Set theparameters field to an instance of theECParameters ASN.1 type defined in [RFC5480] as follows:
If thenamedCurve attribute of the[[algorithm]] internal slot ofkey is "P-256", "P-384" or "P-521":
LetkeyData be thebyte sequence that represents the Elliptic Curve public key represented by the[[handle]] internal slot ofkey according to the encoding rules specified in Section 2.3.3 of [SEC1] and using the uncompressed form.
Letdata be an instance of thePrivateKeyInfo ASN.1 structure defined in [RFC5208] with the following properties:
Set theversion field to0.
Set theprivateKeyAlgorithm field to aPrivateKeyAlgorithmIdentifier ASN.1 type with the following properties:
Set thealgorithm field to the OIDid-ecPublicKey defined in [RFC5480].
Set theparameters field to an instance of theECParameters ASN.1 type defined in [RFC5480] as follows:
If thenamedCurve attribute of the[[algorithm]] internal slot ofkey is "P-256", "P-384" or "P-521":
LetkeyData be the result of DER-encoding an instance of theECPrivateKey structure defined in Section 3 of [RFC5915] for the Elliptic Curve private key represented by the[[handle]] internal slot ofkey and that conforms to the following:
Theparameters field is present, and is equivalent to theparameters field of theprivateKeyAlgorithm field of thisPrivateKeyInfo ASN.1 structure.
ThepublicKey field is present and represents the Elliptic Curve public key associated with the Elliptic Curve private key represented by the[[handle]] internal slot ofkey.
If thenamedCurve attribute of the[[algorithm]] internal slot ofkey is "P-256", "P-384" or "P-521":
Letdata be thebyte sequence that represents the Elliptic Curve public key represented by the[[handle]] internal slot ofkey according to the encoding rules specified in Section 2.3.3 of [SEC1] and using the uncompressed form.
Letresult be the result of performing the Ed25519 signing process, as specified in [RFC8032], Section 5.1.6, withmessage asM, using the Ed25519 private key associated withkey.
If the point R, encoded in the first half ofsignature, represents an invalid point or a small-order element on the Elliptic Curve of Ed25519, returnfalse.
Perform the Ed25519 verification steps, as specified in [RFC8032], Section 5.1.7, using the cofactorless (unbatched) equation,[S]B = R + [k]A', on thesignature, withmessage asM, using the Ed25519 public key associated withkey.
Letresult be a boolean with the valuetrue if the signature is valid and the valuefalse otherwise.
Returnresult.
25.3.3Generate Key
Ifusages contains a value which is not one of "sign" or "verify", thenthrow aSyntaxError.
Generate an Ed25519 key pair, as defined in [RFC8032], section 5.1.5.
If an error occurred while parsing, thenthrow aDataError.
If thealgorithm object identifier field of thealgorithm AlgorithmIdentifier field ofspki is not equal to theid-Ed25519 object identifier defined in [RFC8410], thenthrow aDataError.
If theparameters field of thealgorithm AlgorithmIdentifier field ofspki is present, thenthrow aDataError.
LetpublicKey be the Ed25519 public key identified by thesubjectPublicKey field ofspki.
Letkey be a newCryptoKey that representspublicKey.
If thealgorithm object identifier field of theprivateKeyAlgorithm PrivateKeyAlgorithm field ofprivateKeyInfo is not equal to theid-Ed25519 object identifier defined in [RFC8410], thenthrow aDataError.
If theparameters field of theprivateKeyAlgorithm PrivateKeyAlgorithmIdentifier field ofprivateKeyInfo is present, thenthrow aDataError.
LetcurvePrivateKey be the result of performing theparse an ASN.1 structure algorithm, withdata as theprivateKey field ofprivateKeyInfo,structure as the ASN.1CurvePrivateKey structure specified in Section 7 of [RFC8410], andexactData set to true.
If an error occurred while parsing, thenthrow aDataError.
Letkey be a newCryptoKey that represents the Ed25519 private key identified bycurvePrivateKey.
If thed field is present andusages contains a value which is not "sign", or, if thed field is not present andusages contains a value which is not "verify" thenthrow aSyntaxError.
If thealg field ofjwk is present and is not "Ed25519" or "EdDSA", thenthrow aDataError.
Ifusages is non-empty and theuse field ofjwk is present and is not "sig", thenthrow aDataError.
If thekey_ops field ofjwk is present, and is invalid according to the requirements of JSON Web Key [JWK], or it does not contain all of the specifiedusages values, thenthrow aDataError.
If theext field ofjwk is present and has the value false andextractable is true, thenthrow aDataError.
Letdata be an instance of thePrivateKeyInfo ASN.1 structure defined in [RFC5208] with the following properties:
Set theversion field to0.
Set theprivateKeyAlgorithm field to aPrivateKeyAlgorithmIdentifier ASN.1 type with the following properties:
Set thealgorithm object identifier to theid-Ed25519 OID defined in [RFC8410].
Set theprivateKey field to the result of DER-encoding aCurvePrivateKey ASN.1 type, as defined in Section 7 of [RFC8410], that represents the Ed25519 private key represented by the[[handle]] internal slot ofkey
Letsecret be the result of performing the X25519 function specified in [RFC7748] Section 5 withkey as the X25519 private keyk and the X25519 public key represented by the[[handle]] internal slot ofpublicKey as the X25519 public keyu.
Ifsecret is the all-zero value, thenthrow aOperationError. This check must be performed in constant-time, as per [RFC7748] Section 6.1.
Iflength is null:
Returnsecret
Otherwise:
If the length ofsecret in bits is less thanlength:
If an error occurred while parsing, thenthrow aDataError.
If thealgorithm object identifier field of thealgorithm AlgorithmIdentifier field ofspki is not equal to theid-X25519 object identifier defined in [RFC8410], thenthrow aDataError.
If theparameters field of thealgorithm AlgorithmIdentifier field ofspki is present, thenthrow aDataError.
LetpublicKey be the X25519 public key identified by thesubjectPublicKey field ofspki.
Letkey be a newCryptoKey that representspublicKey.
If thealgorithm object identifier field of theprivateKeyAlgorithm PrivateKeyAlgorithm field ofprivateKeyInfo is not equal to theid-X25519 object identifier defined in [RFC8410], thenthrow aDataError.
If theparameters field of theprivateKeyAlgorithm PrivateKeyAlgorithmIdentifier field ofprivateKeyInfo is present, thenthrow aDataError.
LetcurvePrivateKey be the result of performing theparse an ASN.1 structure algorithm, withdata as theprivateKey field ofprivateKeyInfo,structure as the ASN.1CurvePrivateKey structure specified in Section 7 of [RFC8410], andexactData set to true.
If an error occurred while parsing, thenthrow aDataError.
Letkey be a newCryptoKey that represents the X25519 private key identified bycurvePrivateKey.
Ifusages is non-empty and theuse field ofjwk is present and is not equal to "enc" thenthrow aDataError.
If thekey_ops field ofjwk is present, and is invalid according to the requirements of JSON Web Key [JWK], or it does not contain all of the specifiedusages values, thenthrow aDataError.
If theext field ofjwk is present and has the value false andextractable is true, thenthrow aDataError.
Letdata be an instance of thePrivateKeyInfo ASN.1 structure defined in [RFC5208] with the following properties:
Set theversion field to0.
Set theprivateKeyAlgorithm field to aPrivateKeyAlgorithmIdentifier ASN.1 type with the following properties:
Set thealgorithm object identifier to theid-X25519 OID defined in [RFC8410].
Set theprivateKey field to the result of DER-encoding aCurvePrivateKey ASN.1 type, as defined in Section 7 of [RFC8410], that represents the X25519 private key represented by the[[handle]] internal slot ofkey
Thecounter member contains the initial value of the counter block.counterMUST be 16 bytes (the AES block size). The counter bits are the rightmost length bits of the counter block. The rest of the counter block is for the nonce. The counter bits are incremented using the standard incrementing function specified in NIST SP 800-38A Appendix B.1: the counter bits are interpreted as a big-endian integer and incremented by one.
Thelength member contains the length, in bits, of the rightmost part of the counter block that is incremented.
If thelength member ofnormalizedAlgorithm is zero or is greater than 128, thenthrow anOperationError.
Letciphertext be the result of performing the CTR Encryption operation described in Section 6.5 of [NIST-SP800-38A] using AES as the block cipher, thecounter member ofnormalizedAlgorithm as the initial value of the counter block, thelength member ofnormalizedAlgorithm as the input parameterm to the standard counter block incrementing function defined in Appendix B.1 of [NIST-SP800-38A] andplaintext as the input plaintext.
If thelength member ofnormalizedAlgorithm is zero or is greater than 128, thenthrow anOperationError.
Letplaintext be the result of performing the CTR Decryption operation described in Section 6.5 of [NIST-SP800-38A] using AES as the block cipher, thecounter member ofnormalizedAlgorithm as the initial value of the counter block, thelength member ofnormalizedAlgorithm as the input parameterm to the standard counter block incrementing function defined in Appendix B.1 of [NIST-SP800-38A] andciphertext as the input ciphertext.
Returnplaintext.
27.7.3Generate Key
Ifusages contains any entry which is not one of "encrypt", "decrypt", "wrapKey" or "unwrapKey", thenthrow aSyntaxError.
If thelength member ofnormalizedAlgorithm is not equal to one of 128, 192 or 256, thenthrow anOperationError.
Generate an AES key of length equal to thelength member ofnormalizedAlgorithm.
Ifusages is non-empty and theuse field ofjwk is present and is not "enc", thenthrow aDataError.
If thekey_ops field ofjwk is present, and is invalid according to the requirements of JSON Web Key [JWK] or does not contain all of the specifiedusages values, thenthrow aDataError.
If theext field ofjwk is present and has the value false andextractable is true, thenthrow aDataError.
Set thek attribute ofjwk to be a string containing the raw octets of the key represented by the[[handle]] internal slot ofkey, encoded according to Section 6.4 of JSON Web Algorithms [JWA].
If thelength member ofnormalizedDerivedKeyAlgorithm is not 128, 192 or 256, thenthrow aOperationError.
Return thelength member ofnormalizedDerivedKeyAlgorithm.
28.AES-CBC
28.1Description
This section is non-normative.
The "AES-CBC" algorithm identifier is used to perform encryption and decryption using AES in Cipher Block Chaining mode, as described in [NIST-SP800-38A].
When operating in CBC mode, messages that are not exact multiples of the AES block size (16 bytes) can be padded under a variety of padding schemes. In the Web Crypto API, the only padding mode that is supported is that of PKCS#7, as described by Section 10.3, step 2, of [RFC2315].
LetpaddedPlaintext be the result of adding padding octets toplaintext according to the procedure defined in Section 10.3 of [RFC2315], step 2, with a value ofk of 16.
Letciphertext be the result of performing the CBC Encryption operation described in Section 6.2 of [NIST-SP800-38A] using AES as the block cipher, theiv member ofnormalizedAlgorithm as theIV input parameter andpaddedPlaintext as the input plaintext.
If the length ofciphertext is zero or is not a multiple of 16 bytes, thenthrow anOperationError.
LetpaddedPlaintext be the result of performing the CBC Decryption operation described in Section 6.2 of [NIST-SP800-38A] using AES as the block cipher, theiv member ofnormalizedAlgorithm as theIV input parameter andciphertext as the input ciphertext.
Letp be the value of the last octet ofpaddedPlaintext.
Ifp is zero or greater than 16, or if any of the lastp octets ofpaddedPlaintext have a value which is notp, thenthrow anOperationError.
Letplaintext be the result of removingp octets from the end ofpaddedPlaintext.
Returnplaintext.
28.4.3Generate Key
Ifusages contains any entry which is not one of "encrypt", "decrypt", "wrapKey" or "unwrapKey", thenthrow aSyntaxError.
If thelength member ofnormalizedAlgorithm is not equal to one of 128, 192 or 256, thenthrow anOperationError.
Generate an AES key of length equal to thelength member ofnormalizedAlgorithm.
Ifusages is non-empty and theuse field ofjwk is present and is not "enc", thenthrow aDataError.
If thekey_ops field ofjwk is present, and is invalid according to the requirements of JSON Web Key [JWK] or does not contain all of the specifiedusages values, thenthrow aDataError.
If theext field ofjwk is present and has the value false andextractable is true, thenthrow aDataError.
Set thek attribute ofjwk to be a string containing the raw octets of the key represented by the[[handle]] internal slot ofkey, encoded according to Section 6.4 of JSON Web Algorithms [JWA].
If thelength member ofnormalizedDerivedKeyAlgorithm is not 128, 192 or 256, thenthrow anOperationError.
Return thelength member ofnormalizedDerivedKeyAlgorithm.
29.AES-GCM
29.1Description
This section is non-normative.
The "AES-GCM" algorithm identifier is used to perform authenticated encryption and decryption using AES in Galois/Counter Mode mode, as described in [NIST-SP800-38D].
LetadditionalData be theadditionalData member ofnormalizedAlgorithm if present or an emptybyte sequence otherwise.
LetC andT be the outputs that result from performing the Authenticated Encryption Function described in Section 7.1 of [NIST-SP800-38D] using AES as the block cipher, theiv member ofnormalizedAlgorithm as theIV input parameter,additionalData as theA input parameter,tagLength as thet pre-requisite andplaintext as the input plaintext.
Letciphertext be equal toC |T, where '|' denotes concatenation.
Returnciphertext.
29.4.2Decrypt
If thetagLength member ofnormalizedAlgorithm is not present:
LettagLength be 128.
If thetagLength member ofnormalizedAlgorithm is one of 32, 64, 96, 104, 112, 120 or 128:
LettagLength be equal to thetagLength member ofnormalizedAlgorithm
LetactualCiphertext be the result of removing the lasttagLength bits fromciphertext.
LetadditionalData be theadditionalData member ofnormalizedAlgorithm if present or an emptybyte sequence otherwise.
Perform the Authenticated Decryption Function described in Section 7.2 of [NIST-SP800-38D] using AES as the block cipher, theiv member ofnormalizedAlgorithm as theIV input parameter,additionalData as theA input parameter,tagLength as thet pre-requisite,actualCiphertext as the input ciphertext,C andtag as the authentication tag,T.
If the result of the algorithm is the indication of inauthenticity, "FAIL":
Ifusages is non-empty and theuse field ofjwk is present and is not "enc", thenthrow aDataError.
If thekey_ops field ofjwk is present, and is invalid according to the requirements of JSON Web Key [JWK] or does not contain all of the specifiedusages values, thenthrow aDataError.
If theext field ofjwk is present and has the value false andextractable is true, thenthrow aDataError.
Set thek attribute ofjwk to be a string containing the raw octets of the key represented by the[[handle]] internal slot ofkey, encoded according to Section 6.4 of JSON Web Algorithms [JWA].
Ifplaintext is not a multiple of 64 bits in length, thenthrow anOperationError.
Letciphertext be the result of performing the Key Wrap operation described in Section 2.2.1 of [RFC3394] withplaintext as the plaintext to be wrapped and using the default Initial Value defined in Section 2.2.3.1 of the same document.
Returnciphertext.
30.3.2Unwrap Key
Letplaintext be the result of performing the Key Unwrap operation described in Section 2.2.2 of [RFC3394] withciphertext as the input ciphertext and using the default Initial Value defined in Section 2.2.3.1 of the same document.
Ifusages is non-empty and theuse field ofjwk is present and is not "enc", thenthrow aDataError.
If thekey_ops field ofjwk is present, and is invalid according to the requirements of JSON Web Key [JWK] or does not contain all of the specifiedusages values, thenthrow aDataError.
If theext field ofjwk is present and has the value false andextractable is true, thenthrow aDataError.
Set thek attribute ofjwk to be a string containing the raw octets of the key represented by the[[handle]] internal slot ofkey, encoded according to Section 6.4 of JSON Web Algorithms [JWA].
If thelength member ofnormalizedDerivedKeyAlgorithm is not 128, 192 or 256, thenthrow anOperationError.
Return thelength member ofnormalizedDerivedKeyAlgorithm.
31.HMAC
31.1Description
This section is non-normative.
TheHMAC algorithm calculates and verifies hash-based message authentication codes according to [FIPS-198-1] using the SHA hash functions defined in this specification.
Other specifications may specify the use of additional hash algorithms with HMAC. Such specifications must define the digest operation for the additional hash algorithms andkey import steps andkey export steps for HMAC.
Thehash member represents the inner hash function to use.
Thelength member represent the length (in bits) of the key to generate. If unspecified, the recommended length will be used, which is the size of the associated hash function's block size.
31.6Operations
31.6.1Sign
Letmac be the result of performing the MAC Generation operation described in Section 4 of [FIPS-198-1] using the key represented by the[[handle]] internal slot ofkey, the hash function identified by thehash attribute of the[[algorithm]] internal slot ofkey andmessage as the input datatext.
Returnmac.
31.6.2Verify
Letmac be the result of performing the MAC Generation operation described in Section 4 of [FIPS-198-1] using the key represented by the[[handle]] internal slot ofkey, the hash function identified by thehash attribute of the[[algorithm]] internal slot ofkey andmessage as the input datatext.
Return true ifmac is equal tosignature and false otherwise.
31.6.3Generate Key
Ifusages contains any entry which is not "sign" or "verify", thenthrow aSyntaxError.
If thelength member ofnormalizedAlgorithm is not present:
Letlength be the block size in bits of the hash function identified by thehash member ofnormalizedAlgorithm.
Otherwise, if thelength member ofnormalizedAlgorithm is non-zero:
Letlength be equal to thelength member ofnormalizedAlgorithm.
Ifusages is non-empty and theuse field ofjwk is present and is not "sign", thenthrow aDataError.
If thekey_ops field ofjwk is present, and is invalid according to the requirements of JSON Web Key [JWK] or does not contain all of the specifiedusages values, thenthrow aDataError.
If theext field ofjwk is present and has the value false andextractable is true, thenthrow aDataError.
If thename member ofnormalizedAlgorithm is a cases-sensitive string match for "SHA-1":
Letresult be the result of performing the SHA-1 hash function defined in Section 6.1 of [FIPS-180-4] usingmessage as the input message,M.
If thename member ofnormalizedAlgorithm is a cases-sensitive string match for "SHA-256":
Letresult be the result of performing the SHA-256 hash function defined in Section 6.2 of [FIPS-180-4] usingmessage as the input message,M.
If thename member ofnormalizedAlgorithm is a cases-sensitive string match for "SHA-384":
Letresult be the result of performing the SHA-384 hash function defined in Section 6.5 of [FIPS-180-4] usingmessage as the input message,M.
If thename member ofnormalizedAlgorithm is a cases-sensitive string match for "SHA-512":
Letresult be the result of performing the SHA-512 hash function defined in Section 6.4 of [FIPS-180-4] usingmessage as the input message,M.
If performing the operation results in an error, thenthrow anOperationError.
Returnresult.
33.HKDF
33.1Description
This section is non-normative.
The "HKDF" algorithm identifier is used to perform key derivation using the extraction-then-expansion approach described in [RFC5869] and using the SHA hash functions defined in this specification.
Other specifications may specify the use of additional hash algorithms with HKDF. Such specifications must define the digest operation for the additional hash algorithms.
The "PBKDF2" algorithm identifier is used to perform key derivation using the PKCS#5 password-based key derivation function version 2, as defined in [RFC8018] using HMAC as the pseudo-random function, using the SHA hash functions defined in this specification.
Other specifications may specify the use of additional hash algorithms with PBKDF2. Such specifications must define the digest operation for the additional hash algorithms.
Letprf be the MAC Generation function described in Section 4 of [FIPS-198-1] using the hash function described by thehash member ofnormalizedAlgorithm.
Letresult be the result of performing the PBKDF2 operation defined in Section 5.2 of [RFC8018] usingprf as the pseudo-random function,PRF, the password represented by the[[handle]] internal slot ofkey as the password,P, thesalt attribute ofnormalizedAlgorithm as the salt,S, the value of theiterations attribute ofnormalizedAlgorithm as the iteration count,c, andlength divided by 8 as the intended key length,dkLen.
Set the[[algorithm]] internal slot ofkey toalgorithm.
Returnkey.
34.4.3Get key length
Return null.
35.JavaScript Example Code
35.1Generate two key pairs, derive a shared key, encrypt some data
This example generates two X25519 key pairs, one for Alice and one for Bob, performs a key agreement between them, derives a 256-bit AES-GCM key from the result using HKDF with SHA-256, and encrypts and decrypts some data with it.
// Generate a key pair for Alice.const alice_x25519_key =await crypto.subtle.generateKey('X25519',false/* extractable */, ['deriveKey']);const alice_private_key = alice_x25519_key.privateKey;// Normally, the public key would be sent by Bob to Alice in advance over some authenticated channel.// In this example, we'll generate another key pair and use its public key instead.const bob_x25519_key =await crypto.subtle.generateKey('X25519',false/* extractable */, ['deriveKey']);const bob_public_key = bob_x25519_key.publicKey;// Perform the key agreement.const alice_x25519_params = {name:'X25519',public: bob_public_key };const alice_shared_key =await crypto.subtle.deriveKey(alice_x25519_params, alice_private_key,'HKDF',false/* extractable */, ['deriveKey']);// Derive a symmetric key from the result.const salt = crypto.getRandomValues(newUint8Array(32));const info =newTextEncoder().encode('X25519 key agreement for an AES-GCM-256 key');const hkdf_params = {name:'HKDF',hash:'SHA-256', salt, info };const gcm_params = {name:'AES-GCM',length:256 };const alice_symmetric_key =await crypto.subtle.deriveKey(hkdf_params, alice_shared_key, gcm_params,false/* extractable */, ['encrypt','decrypt']);// Encrypt some data with the symmetric key, and send it to Bob. The IV must be passed along as well.const iv = crypto.getRandomValues(newUint8Array(12));const message =newTextEncoder().encode('Hi Bob!');const encrypted =await crypto.subtle.encrypt({ ...gcm_params, iv }, alice_symmetric_key, message);// On Bob's side, Alice's public key and Bob's private key are used, instead.// To get the same result, Alice and Bob must agree on using the same salt and info.const alice_public_key = alice_x25519_key.publicKey;const bob_private_key = bob_x25519_key.privateKey;const bob_x25519_params = {name:'X25519',public: alice_public_key };const bob_shared_key =await crypto.subtle.deriveKey(bob_x25519_params, bob_private_key,'HKDF',false/* extractable */, ['deriveKey']);const bob_symmetric_key =await crypto.subtle.deriveKey(hkdf_params, bob_shared_key, gcm_params,false/* extractable */, ['encrypt','decrypt']);// On Bob's side, the data can be decrypted.const decrypted =await crypto.subtle.decrypt({ ...gcm_params, iv }, bob_symmetric_key, encrypted);const decrypted_message =newTextDecoder().decode(decrypted);
36.1JSON Web Signature and Encryption Algorithms Registration
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 'Implementation Requirements' field in the template refers to use with JSON Web Signature and JSON Web Encryption specifically, in which case use of unauthenticated encryption is prohibited.
Algorithm Name: "RS1"
Algorithm Description: RSASSA-PKCS1-v1_5 with SHA-1
Thanks are due especially to Ryan Sleevi, the original author and editor, and Mark Watson, the former editor of this document.
Thanks to Adam Barth, Alex Russell, Ali Asad, Arun Ranganathan, Brian Smith, Brian Warner, Channy Yun, Charles Engelke, Eric Roman, Glenn Adams, Jim Schaad, Kai Engert, Michael Hutchinson, Michael B. Jones, Nick Van den Bleeken, Richard Barnes, Ryan Hurst, Tim Taubert, Vijay Bharadwaj, Virginie Galindo, and Wan-Teh Chang for their technical feedback and assistance.
The object identifiers used by this specification do not include information about the specific algorithm and hash that the key is intended to be used with. If this is required, it's recommended that the "jwk" key format is used instead.
C.Mapping between Algorithm and PKCS#8 PrivateKeyInfo
This section is non-normative.
Refer to algorithm-specific sections for the normative requirements of importing and exporting PKCS#8 PrivateKeyInfo.