Copyright © 2016 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and document use rules apply.
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.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
This document is the 15 December 2016 Proposed Recommendation of the Web Cryptography API specification. The W3C Membership and other interested parties are invited to review the document and send comments to public-webcrypto-comments@w3.org (archived) through 13 January 2017. Advisory Committee Representatives should consult their WBS questionnaires.
This document is produced by the Web Cryptography WG of the W3C.
Changes made to this document can be found in the GitHub repository. The changes since the previous version include:
An implementation report is also available (as well as reports sent to the mailing list).
Web content and browser developers are encouraged to review this draft. Please send comments to public-webcrypto-comments@w3.org, the W3C's public email list for issues related to Web Cryptography. Archives of the public list and archives of the member's-only list are available.
Previous discussion of this specification has taken place on three other mailing lists: whatwg@whatwg.org (archive) , public-websecurity@w3.org (archive), and public-identity@w3.org (archive). Ongoing discussion will be on the public-webcrypto@w3.org mailing list.
Publication as a Proposed Recommendation does not imply endorsement by the W3C Membership. 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.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is governed by the 1 September 2015 W3C Process Document.
This section is non-normative.
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 the SubtleCrypto interface, which defines a set of methods for performing common cryptographic operations. In addition to operations such as signature generation and verification, hashing and verification, and encryption and decryption, the API provides interfaces for key generation, key derivation and key import and export.
This section is non-normative.
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.
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.
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 the Protected Document Exchange use case, with viewership of the document limited to the user themself.
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.
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.
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.
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).
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 keywords MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, RECOMMENDED, MAY, OPTIONAL, in this specification are to be interpreted as described in Key words for use in RFCs to Indicate Requirement Levels [RFC2119].
The following conformance classes are defined by this specification:
A user agent is considered to be a conforming user agent if it satisfies all of the MUST-, REQUIRED- and SHALL-level criteria in this specification that apply to implementations. This specification uses both the terms "conforming user agent" and "user agent" to refer to this product class.
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 specification MUST implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [WebIDL] as this specification uses that specification and terminology.
Unless otherwise stated, string comparisons are done in a
case-sensitive manner. String literals in this specification
written in monospace font like "this"
do not include the enclosing quotes.
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 an applicable specification for the purposes of conformance requirements in this specification. Applicable specifications defined by the W3C Web Cryptography Working Group are listed in the table below.
Specification | Reference |
This section is non-normative.
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.
Because the underlying cryptographic implementations will vary between conforming user agents, and may be subject to local policy, including but not limited to concerns such as government or industry regulation, security best practices, intellectual property concerns, and constrained operational environments, this specification does not dictate a mandatory set of algorithms that MUST be implemented. Instead, it defines a common set of bindings that can be used in an algorithm-independent manner, a common framework for discovering if a user agent or key handle supports the underlying algorithm, and a set of conformance requirements for the behaviors of individual algorithms, if implemented.
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.
This section is non-normative.
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.
The CryptoKey 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, the CryptoKey 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.
This specification does not explicitly provide any new storage mechanisms for CryptoKey objects. Instead, by allowing the CryptoKey to be used with the structured clone algorithm, any existing or future web storage mechanisms that support storing structured clonable objects can be used to store CryptoKey objects.
In practice, it is expected that most authors will make use of the Indexed Database API, which allows associative storage of key/value pairs, where the key is some string identifier meaningful to the application, and the value is a CryptoKey object. This allows the storage and retrieval of key material, without ever exposing that key material to the application or the JavaScript environment. Additionally, this allows authors the full flexibility to store any additional metadata with the CryptoKey itself.
This section is non-normative.
By not providing an explicit storage mechanism, this specification assumes that CryptoKey objects are scoped to the current execution environment and any storage mechanisms available to that environment (e.g. Indexed Database API). Application authors rely upon this for the security of their applications; two origins with the same CryptoKey object have full access to the underlying key, and as such, messages from these applications cannot be distinguished, and messages sent to these applications can be fully recovered. Implementors should ensure that no CryptoKey objects are shared between two origins unless the author has explicitly chosen to share (e.g., such as through the use of postMessage)
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.
This specification includes descriptions for a variety of cryptographic operations, some of which have known weaknesses when used inappropriately. Application developers must take care and review appropriate and current cryptographic literature, to understand and mitigate such issues. In general, application developers are strongly 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 as postMessage
.
Authors should be aware that this specification places no normative requirements on implementations as to how the underlying cryptographic key material is stored. The only requirement is that key material is not exposed to script, except through the use of the exportKey and wrapKey operations. In particular, it does not guarantee that the underlying cryptographic key material will not be persisted to disk, possibly unencrypted, nor that it will be inaccessible to users or other applications running with the same privileges as the User Agent. Any application or user that has access to the device storage may be able to recover the key material, even through scripts may be prohibited.
This specification places no normative requirements on how implementations handle key material once all references to it go away. That is, conforming user agents are not required to zeroize key material, and it may still be accessible on device storage or device memory, even after all references to the CryptoKey have gone away.
Applications may share a CryptoKey object across security
boundaries, such as origins, through the use of the structured clone algorithm and APIs
such as postMessage
. While access to the underlying cryptographic key
material may be restricted, based upon the extractable
attribute, once a key is shared with a destination origin, the source origin can not
later restrict or revoke access to the key. As such, authors must be careful to ensure
they trust the destination origin to take the same mitigations against hostile script
that the source origin employs. Further, in the event of script injection on the source
origin, attackers may post the key to an origin under attacker control. Any time that
the user agent visits the attacker's origin, the user agent may be directed to perform
cryptographic operations using that key, such as the decryption of existing messages
or the creation of new, fraudulent messages.
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.
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.
This section is non-normative.
This specification relies on underlying specifications.
A conforming user agent MUST support at
least the subset of the functionality defined in DOM4 that this specification relies
upon; in particular, it MUST support Promises
and
DOMException.
[DOM4]
A conforming user agent MUST support at least the subset of the functionality defined in HTML that this specification relies upon; in particular, it MUST support the ArrayBufferView typedef and the structured clone algorithm. [HTML]
A conforming user agent MUST be a conforming implementation of the IDL fragments in this specification, as described in the Web IDL specification. [WebIDL]
The terms and algorithms ArrayBuffer, ArrayBufferView, and structured clone, are defined by the HTML specification [HTML].
The terms DOMString and BufferSource are defined in [WebIDL].
An octet string is an ordered sequence of zero or more integers, each in the range 0 to 255 inclusive.
An octet string containing a bit string b is the octet string obtained by first appending zero or more bits of value zero to b such that the length of the resulting bit string is minimal and an integer multiple of 8 and then considering each consecutive sequence of 8 bits in that string as a binary integer, most significant bit first.
When this specification says to convert a non-negative integer i to an octet string of length n, where n * 8 is greater than the logarithm to base 2 of i, the user agent must first calculate the binary representation of i, most significant bit first, prefix this with sufficient zero bits to form a bit string of length n * 8, and then return the octet string formed by considering each consecutive sequence of 8 bits in that bit string as a binary integer, most significant bit first.
Comparing two strings in a case-sensitive manner means comparing them exactly, code point for code point.
Comparing two strings in a ASCII 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 to terminate 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 to parse an ASN.1 structure, the user agent must perform the following steps:
Let data be a sequence of bytes to be parsed.
Let structure be the ASN.1 structure to be parsed.
Let exactData be an optional boolean value. If it is not supplied,
let it be initialized to true
.
Parse data according to the Distinguished Encoding Rules of X.690 (11/08), using structure as the ASN.1 structure to be decoded.
If exactData was specified, and all of the bytes of data were
not consumed during the parsing phase, then
throw a
DataError
.
Return the parsed ASN.1 structure.
When this specification says to parse a
subjectPublicKeyInfo, the user agent must
parse an ASN.1 structure, with
data set to the sequence of bytes to be parsed, structure as the
ASN.1 structure of subjectPublicKeyInfo, as specified in RFC 5280,
and exactData set to true
.
When this specification says to parse a
PrivateKeyInfo, the user agent must parse
an ASN.1 structure with data set to the sequence of bytes to be parsed,
structure as the ASN.1 structure of PrivateKeyInfo, as specified in
RFC 5208, and exactData set to true
.
When this specification says to parse a JWK, the user agent must run the following steps:
Let data be the sequence of bytes to be parsed.
Let json be the Unicode string that results from interpreting data according to UTF-8.
Convert json to UTF-16.
Let result be the object literal that results from executing the
JSON.parse
internal function in the context of a new global object,
with text
argument set to a JavaScript String containing json.
Let key be the result of converting result to the IDL dictionary type of JsonWebKey.
If the "kty"
field of key is not defined, then throw a DataError
.
Return key.
When this specification states to supply the contents of an ArrayBuffer named data to an underlying cryptographic implementation, the User Agent shall supply a contiguous sequence of bytes that is equal to the result of geting a copy of the bytes held data.
When this specification says to calculate the usage intersection of two sequences, a and b the result shall be a sequence containing each recognized key usage value that appears in both a and b, in the order listed in the list of recognized key usage 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 the usage intersection of usages and a sequence containing all recognized key usage values.
When this specification refers to the cached ECMAScript object associated with an internal slot [[slot]] of object, the user agent must run the following steps:
[NoInterfaceObject,Exposed=(Window,Worker)]
interface GlobalCrypto {
readonly attribute Crypto crypto;
};
Window implements GlobalCrypto;
WorkerGlobalScope implements GlobalCrypto;
[Exposed=(Window,Worker)]
interface Crypto {
[SecureContext] readonly attribute SubtleCrypto subtle;
ArrayBufferView getRandomValues(ArrayBufferView array);
};
This section is non-normative.
The Crypto interface represents an interface to general purpose cryptographic functionality including a cryptographically strong pseudo-random number generator seeded with truly random values.
The getRandomValues
method generates cryptographically random values. It must act as follows:
If array is not of an integer type (i.e., Int8Array, Uint8Array,
Int16Array, Uint16Array, Int32Array, Uint32Array or UInt8ClampedArray), throw a
TypeMismatchError
and
terminate the algorithm.
If the byteLength
of array is greater than 65536, throw a
QuotaExceededError
and
terminate the algorithm.
Overwrite all elements of array with cryptographically random values of the appropriate type.
Return array.
Do not generate keys using the getRandomValues
method. Use the
generateKey
method
instead.
The subtle
attribute provides
an instance of the SubtleCrypto interface which provides
low-level cryptographic primitives and algorithms.
The Algorithm object is a dictionary object [WebIDL] which is used to specify an algorithm and any additional parameters required to fully specify the desired operation.
typedef (object or DOMString) AlgorithmIdentifier;
typedef AlgorithmIdentifier HashAlgorithmIdentifier;
dictionary Algorithm {
required DOMString name;
};
name
The KeyAlgorithm dictionary represents information about the contents of a given CryptoKey object.
dictionary KeyAlgorithm {
required DOMString name;
};
This section is non-normative.
The KeyAlgorithm dictionary is provided to aid in documenting how fixed, public properties of a CryptoKey are reflected back to an application. The actual dictionary type is never exposed to applications.
The CryptoKey object represents an opaque reference to keying material that is managed by the user agent.
enum KeyType { "public", "private", "secret" };
enum KeyUsage { "encrypt", "decrypt", "sign", "verify", "deriveKey", "deriveBits", "wrapKey", "unwrapKey" };
[SecureContext,Exposed=(Window,Worker)]
interface CryptoKey {
readonly attribute KeyType type;
readonly attribute boolean extractable;
readonly attribute object algorithm;
readonly attribute object usages;
};
This section is non-normative.
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.
KeyType
"public"
, "private"
and "secret"
.
Opaque keying material, including that used for symmetric algorithms, is represented by
"secret"
, while keys used as part of asymmetric algorithms composed of
public/private keypairs will be either "public"
or "private"
.
KeyUsage
"encrypt"
,
"decrypt"
,
"sign"
,
"verify"
,
"deriveKey"
,
"deriveBits"
,
"wrapKey"
and
"unwrapKey"
.
Every CryptoKey
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 [[ ]].
All CryptoKey
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, a KeyAlgorithm. The contents of the [[usages]] internal slot shall be of type Sequence<KeyUsage>.
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.
type
extractable
algorithm
usages
When a user agent is required to obtain a structured clone of a CryptoKey object, it must run the following steps.
CryptoKey
object, implementations must not allow the
object to be deserialized as a different type. This is normatively required by the
definition of structured clone, but it merits specific attention, as such
deserialization may expose the contents of the [[handle]] internal slot, which in some
implementations may contain cryptographic key data that should not be exposed to
applications.
enum KeyFormat
{ "raw", "spki", "pkcs8", "jwk" };
[SecureContext,Exposed=(Window,Worker)]
interface SubtleCrypto {
Promise<any> encrypt(AlgorithmIdentifier algorithm,
CryptoKey key,
BufferSource data);
Promise<any> decrypt(AlgorithmIdentifier algorithm,
CryptoKey key,
BufferSource data);
Promise<any> sign(AlgorithmIdentifier algorithm,
CryptoKey key,
BufferSource data);
Promise<any> verify(AlgorithmIdentifier algorithm,
CryptoKey key,
BufferSource signature,
BufferSource data);
Promise<any> digest(AlgorithmIdentifier algorithm,
BufferSource data);
Promise<any> generateKey(AlgorithmIdentifier algorithm,
boolean extractable,
sequence<KeyUsage> keyUsages );
Promise<any> deriveKey(AlgorithmIdentifier algorithm,
CryptoKey baseKey,
AlgorithmIdentifier derivedKeyType,
boolean extractable,
sequence<KeyUsage> keyUsages );
Promise<ArrayBuffer> deriveBits(AlgorithmIdentifier algorithm,
CryptoKey baseKey,
unsigned long length);
Promise<CryptoKey> importKey(KeyFormat format,
(BufferSource or JsonWebKey) keyData,
AlgorithmIdentifier algorithm,
boolean extractable,
sequence<KeyUsage> keyUsages );
Promise<any> exportKey(KeyFormat format, CryptoKey key);
Promise<any> wrapKey(KeyFormat format,
CryptoKey key,
CryptoKey wrappingKey,
AlgorithmIdentifier wrapAlgorithm);
Promise<CryptoKey> unwrapKey(KeyFormat format,
BufferSource wrappedKey,
CryptoKey unwrappingKey,
AlgorithmIdentifier unwrapAlgorithm,
AlgorithmIdentifier unwrappedKeyAlgorithm,
boolean extractable,
sequence<KeyUsage> keyUsages );
};
This section is non-normative.
The SubtleCrypto interface provides a set of
methods for dealing with low-level cryptographic primitives and algorithms. It 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 as AES 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.
KeyFormat
"raw"
"pkcs8"
"spki"
"jwk"
Unless otherwise stated, objects created by the methods defined in this section shall be associated with the
relevant global object
of this
[HTML].
All errors are reported asynchronously by rejecting the returned Promise. This includes Web IDL type mapping errors.
The encrypt
method returns a new Promise object that will encrypt data using
the specified
AlgorithmIdentifier
with
the supplied CryptoKey
. It must act
as follows:
Let algorithm and key be the
algorithm
and key
parameters
passed to the encrypt method,
respectively.
Let data be the result of
getting a copy of the bytes held by the data
parameter passed to the
encrypt method.
Let normalizedAlgorithm be the result of
normalizing an algorithm, with
alg
set to algorithm and op
set to
"encrypt"
.
If an error occurred, return a Promise rejected with normalizedAlgorithm.
Let promise be a new Promise.
Return promise and asynchronously perform the remaining steps.
If the following steps or referenced procedures say to throw an error, reject promise with the returned error and then terminate the algorithm.
If the name member of
normalizedAlgorithm is not equal to the
name attribute of the
[[algorithm]] internal slot of
key then throw an InvalidAccessError
.
If the [[usages]] internal slot of
key does not contain an entry that is "encrypt"
, then throw an InvalidAccessError
.
Let ciphertext be the result of performing the encrypt operation specified by normalizedAlgorithm using algorithm and key and with data as plaintext.
Resolve promise with ciphertext.
The decrypt
method returns a new Promise object that will decrypt data using the specified
AlgorithmIdentifier
with
the supplied CryptoKey
. It must act
as follows:
Let algorithm and key be the
algorithm
and key
parameters
passed to the decrypt method,
respectively.
Let data be the result of
getting a copy of the bytes held by the data
parameter passed to the
decrypt method.
Let normalizedAlgorithm be the result of
normalizing an algorithm, with
alg
set to algorithm and op
set to
"decrypt"
.
If an error occurred, return a Promise rejected with normalizedAlgorithm.
Let promise be a new Promise.
Return promise and asynchronously perform the remaining steps.
If the following steps or referenced procedures say to throw an error, reject promise with the returned error and then terminate the algorithm.
If the name member of
normalizedAlgorithm is not equal to the
name attribute of the
[[algorithm]] internal slot of
key then throw an InvalidAccessError
.
If the [[usages]] internal slot of
key does not contain an entry that is "decrypt"
, then throw an InvalidAccessError
.
Let plaintext be the result of performing the decrypt operation specified by normalizedAlgorithm using key and algorithm and with data as ciphertext.
Resolve promise with plaintext.
The sign
method returns a
new Promise object that will sign data using the specified AlgorithmIdentifier
with the supplied
CryptoKey
. It must act as follows:
Let algorithm and key be the
algorithm
and key
parameters
passed to the sign method,
respectively.
Let data be the result of
getting a copy of the bytes held by the data
parameter passed to the
sign method.
Let normalizedAlgorithm be the result of
normalizing an algorithm, with
alg
set to algorithm and op
set to
"sign"
.
If an error occurred, return a Promise rejected with normalizedAlgorithm.
Let promise be a new Promise.
Return promise and asynchronously perform the remaining steps.
If the following steps or referenced procedures say to throw an error, reject promise with the returned error and then terminate the algorithm.
If the name member of
normalizedAlgorithm is not equal to the
name attribute of the
[[algorithm]] internal slot of
key then throw an InvalidAccessError
.
If the [[usages]] internal slot of
key does not contain an entry that is "sign"
, then throw an InvalidAccessError
.
Let result be the result of performing the sign operation specified by normalizedAlgorithm using key and algorithm and with data as message.
Resolve promise with result.
The verify
method returns
a new Promise object that will verify data using the specified AlgorithmIdentifier
with the supplied
CryptoKey
. It must act as follows:
Let algorithm and key
be the algorithm
and key
parameters passed to the
verify method, respectively.
Let signature be the result of
getting a copy of the bytes held by the signature
parameter passed to the
verify method.
Let data be the result of
getting a copy of the bytes held by the data
parameter passed to the
verify method.
Let normalizedAlgorithm be the result of
normalizing an algorithm, with
alg
set to algorithm and op
set to
"verify"
.
If an error occurred, return a Promise rejected with normalizedAlgorithm.
Let promise be a new Promise.
Return promise and asynchronously perform the remaining steps.
If the following steps or referenced procedures say to throw an error, reject promise with the returned error and then terminate the algorithm.
If the name member of
normalizedAlgorithm is not equal to the
name attribute of the
[[algorithm]] internal slot of
key then throw an InvalidAccessError
.
If the [[usages]] internal slot of
key does not contain an entry that is "verify"
, then throw an InvalidAccessError
.
Let result be the result of performing the verify operation specified by normalizedAlgorithm using key, algorithm and signature and with data as message.
Resolve promise with result.
The digest
method returns
a new Promise object that will digest data using the specified
AlgorithmIdentifier
.
It must act as follows:
Let algorithm be the algorithm
parameter passed to the
digest method.
Let data be the result of
getting a copy of the bytes held by the data
parameter passed to the
digest method.
Let normalizedAlgorithm be the result of
normalizing an algorithm, with
alg
set to algorithm and op
set to
"digest"
.
If an error occurred, return a Promise rejected with normalizedAlgorithm.
Let promise be a new Promise.
Return promise and asynchronously perform the remaining steps.
If the following steps or referenced procedures say to throw an error, reject promise with the returned error and then terminate the algorithm.
Let result be the result of performing the digest operation specified by normalizedAlgorithm using algorithm, with data as message.
Resolve promise with result.
When invoked,
generateKey
MUST perform the
following steps:
Let algorithm, extractable and usages
be the algorithm
, extractable
and keyUsages
parameters passed to the
generateKey method,
respectively.
Let normalizedAlgorithm be the result of
normalizing an algorithm, with
alg
set to algorithm and op
set to
"generateKey"
.
If an error occurred, return a Promise rejected with normalizedAlgorithm.
Let promise be a new Promise.
Return promise and asynchronously perform the remaining steps.
If the following steps or referenced procedures say to throw an error, reject promise with the returned error and then terminate the algorithm.
Let result be the result of performing the generate key operation specified by normalizedAlgorithm using algorithm, extractable and usages.
If the [[type]] internal slot of
result is "secret"
or "private"
and
usages is empty, then throw a SyntaxError.
If the [[usages]] internal slot of the privateKey attribute of result is the empty sequence, then throw a SyntaxError.
Resolve promise with result.
When invoked, deriveKey
MUST perform the following steps:
Let algorithm, baseKey, derivedKeyType,
extractable and usages be the algorithm
,
baseKey
, derivedKeyType
, extractable
and
keyUsages
parameters passed to the deriveKey method, respectively.
Let normalizedAlgorithm be the result of
normalizing an algorithm, with
alg
set to algorithm and op
set to
"deriveBits"
.
If an error occurred, return a Promise rejected with normalizedAlgorithm.
Let normalizedDerivedKeyAlgorithmImport be the result of
normalizing an algorithm, with
alg
set to derivedKeyType and op
set to
"importKey"
.
If an error occurred, return a Promise rejected with normalizedDerivedKeyAlgorithmImport.
Let normalizedDerivedKeyAlgorithmLength be the result of
normalizing an algorithm, with
alg
set to derivedKeyType and op
set to
"get key length"
.
If an error occurred, return a Promise rejected with normalizedDerivedKeyAlgorithmLength.
Let promise be a new Promise.
Return promise and asynchronously perform the remaining steps.
If the following steps or referenced procedures say to throw an error, reject promise with the returned error and then terminate the algorithm.
If the name member of
normalizedAlgorithm is not equal to the
name attribute of the
[[algorithm]] internal slot of
baseKey then throw an InvalidAccessError
.
If the [[usages]] internal slot of
baseKey does not contain an entry that is "deriveKey"
,
then throw an InvalidAccessError
.
Let length be the result of performing the get key length algorithm specified by normalizedDerivedKeyAlgorithmLength using derivedKeyType.
Let secret be the result of performing the derive bits operation specified by normalizedAlgorithm using key, algorithm and length.
Let result be the result of performing the import key operation
specified by normalizedDerivedKeyAlgorithmImport using "raw"
as
format, secret as keyData,
derivedKeyType as algorithm and using
extractable and usages.
If the [[type]] internal slot of
result is "secret"
or "private"
and
usages is empty, then throw a SyntaxError.
Resolve promise with result.
When invoked, deriveBits
MUST perform the following steps:
Let algorithm, baseKey and length,
be the algorithm
,
baseKey
and length
parameters passed to the
deriveBits method,
respectively.
Let normalizedAlgorithm be the result of
normalizing an algorithm, with
alg
set to algorithm and op
set to
"deriveBits"
.
If an error occurred, return a Promise rejected with normalizedAlgorithm.
Let promise be a new Promise object.
Return promise and asynchronously perform the remaining steps.
If the following steps or referenced procedures say to throw an error, reject promise with the returned error and then terminate the algorithm.
If the name member of
normalizedAlgorithm is not equal to the
name attribute of the
[[algorithm]] internal slot of
baseKey then throw an InvalidAccessError
.
If the [[usages]] internal slot of
baseKey does not contain an entry that is "deriveBits"
,
then throw an InvalidAccessError
.
Let result be a new ArrayBuffer
associated with the
relevant global object
of this
[HTML], and
containing the result of performing the derive bits operation
specified by normalizedAlgorithm using baseKey,
algorithm and length.
Resolve promise with result.
When invoked, the importKey
method MUST perform the following steps:
Let format, algorithm, extractable and
usages, be the format
, algorithm
,
extractable
and keyUsages
parameters passed to the importKey method, respectively.
"raw"
,
"pkcs8"
, or "spki"
:
If the keyData
parameter passed to the
importKey method is a
JsonWebKey dictionary, throw a
TypeError
.
Let keyData be the result of
getting a copy of the bytes held by the
keyData
parameter passed to the
importKey method.
"jwk"
:
Let normalizedAlgorithm be the result of
normalizing an algorithm, with
alg
set to algorithm and op
set to
"importKey"
.
If an error occurred, return a Promise rejected with normalizedAlgorithm.
Let promise be a new Promise.
Return promise and asynchronously perform the remaining steps.
If the following steps or referenced procedures say to throw an error, reject promise with the returned error and then terminate the algorithm.
Let result be the CryptoKey object that results from performing the import key operation specified by normalizedAlgorithm using keyData, algorithm, format, extractable and usages.
If the [[type]] internal slot of
result is "secret"
or "private"
and
usages is empty, then throw a SyntaxError.
Set the [[extractable]] internal slot of result to extractable.
Set the [[usages]] internal slot of result to the normalized value of usages.
Resolve promise with result.
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.
For structured key formats, "spki"
, "pks8"
and "jwk"
, fields that are not explicitly referred to in the key
import procedures for an algorithm are ignored.
When invoked, the exportKey
method MUST perform the following steps:
Let format and key be the format
and
key
parameters passed to the exportKey method, respectively.
Let promise be a new Promise.
Return promise and asynchronously perform the remaining steps.
If the following steps or referenced procedures say to throw an error, reject promise with the returned error and then terminate the algorithm.
If the name member of of the [[algorithm]] internal slot of
key does not identify a registered algorithm
that supports the export key operation, then throw a NotSupportedError
.
If the [[extractable]] internal slot
of key is false, then throw an InvalidAccessError
.
Let result be the result of performing the export key operation specified by the [[algorithm]] internal slot of key using key and format.
Resolve promise with result.
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.
When invoked, the wrapKey method MUST perform the following steps:
Let format, key, wrappingKey and
algorithm be the format
, key
,
wrappingKey
and wrapAlgorithm
parameters passed to the
wrapKey method,
respectively.
Let normalizedAlgorithm be the result of
normalizing an algorithm, with
alg
set to algorithm and op
set to
"wrapKey"
.
If an error occurred, let normalizedAlgorithm be the result of
normalizing an algorithm, with
alg
set to algorithm and op
set to
"encrypt"
.
If an error occurred, return a Promise rejected with normalizedAlgorithm.
Let promise be a new Promise.
Return promise and asynchronously perform the remaining steps.
If the following steps or referenced procedures say to throw an error, reject promise with the returned error and then terminate the algorithm.
If the name member of
normalizedAlgorithm is not equal to the
name attribute of the
[[algorithm]] internal slot of
wrappingKey then throw an InvalidAccessError
.
If the [[usages]] internal slot of
wrappingKey does not contain an entry that is "wrapKey"
,
then throw an InvalidAccessError
.
If the algorithm identified by the [[algorithm]] internal slot of
key does not support the export key operation, then throw a NotSupportedError
.
If the [[extractable]] internal slot
of key is false, then throw an InvalidAccessError
.
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 the ext
JWK member.
However, the unwrapKey method does support the ext
JWK member,
so that wrapped non-extractable keys created elsewhere, for example by a server, can be
unwrapped using this API.
Let key be the result of performing the export key operation specified the [[algorithm]] internal slot of key using key and format.
"raw"
,
"pkcs8"
, or "spki"
:
"jwk"
:
Convert key to an ECMAScript Object, as specified in [ WebIDL], performing the conversion in the context of a new global object.
Let json be the result of representing key as a
UTF-16 string conforming to the JSON grammar; for example, by executing
the JSON.stringify
algorithm specified in
ECMA262 in the context of a new global object.
Let bytes be the byte sequence the results from converting json, a JavaScript String comprised of UTF-16 code points, to UTF-8 code points.
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.
Let result be the result of performing the wrap key operation specified by normalizedAlgorithm using algorithm, wrappingKey as key and bytes as plaintext.
Let result be the result of performing the encrypt operation specified by normalizedAlgorithm using algorithm, wrappingKey as key and bytes as plaintext.
NotSupportedError
.
Resolve promise with result.
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.
When invoked, the unwrapKey method MUST perform the following steps:
Let format, unwrappingKey,
algorithm, unwrappedKeyAlgorithm,
extractable and usages,
be the format
, unwrappingKey
,
unwrapAlgorithm
, unwrappedKeyAlgorithm
,
extractable
and keyUsages
parameters passed to the
unwrapKey method,
respectively.
Let wrappedKey be the result of
getting a copy of the bytes held by the
wrappedKey
parameter passed to the
unwrapKey method.
Let normalizedAlgorithm be the result of
normalizing an algorithm, with
alg
set to algorithm and op
set to
"unwrapKey"
.
If an error occurred, let normalizedAlgorithm be the result of
normalizing an algorithm, with
alg
set to algorithm and op
set to
"decrypt"
.
If an error occurred, return a Promise rejected with normalizedAlgorithm.
Let normalizedKeyAlgorithm be the result of normalizing an algorithm, with
alg
set to unwrappedKeyAlgorithm and op
set
to "importKey"
.
If an error occurred, return a Promise rejected with normalizedKeyAlgorithm.
Let promise be a new Promise.
Return promise and asynchronously perform the remaining steps.
If the following steps or referenced procedures say to throw an error, reject promise with the returned error and then terminate the algorithm.
If the name member of
normalizedAlgorithm is not equal to the
name attribute of the
[[algorithm]] internal slot of
unwrappingKey then throw an InvalidAccessError
.
If the [[usages]] internal slot of
unwrappingKey does not contain an entry that is
"unwrapKey"
, then throw an InvalidAccessError
.
NotSupportedError
.
"raw"
,
"pkcs8"
, or "spki"
:
"jwk"
:
data
to be parsed.
Let result be the result of performing the import key operation specified by normalizedKeyAlgorithm using unwrappedKeyAlgorithm as algorithm, format, usages and extractable and with bytes as keyData.
If the [[type]] internal slot of
result is "secret"
or "private"
and
usages is empty, then throw a SyntaxError
.
Set the [[extractable]] internal slot of result to extractable.
Set the [[usages]] internal slot of result to the normalized value of usages.
Resolve promise with result.
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.
The methods of the SubtleCrypto interface return errors by rejecting the returned promise with a predefined exception defined in ECMAScript [ECMA-262] or DOMException. The following predefined exceptions are used: TypeError. The following DOMException types from [DOM4] are used:
Name | Description |
---|---|
NotSupportedError |
The algorithm is not supported |
SyntaxError |
A required parameter was missing or out-of-range |
InvalidAccessError |
The requested operation is not valid for the provided key |
DataError |
Data provided to an operation does not meet requirements |
OperationError |
The operation failed for an operation-specific reason |
When this specification says to
throw 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 the
relevant global object
of this
[HTML].
dictionary RsaOtherPrimesInfo {
// The following fields are defined in Section 6.3.2.7 of JSON Web Algorithms
DOMString r;
DOMString d;
DOMString t;
};
dictionary JsonWebKey {
// The following fields are defined in Section 3.1 of JSON Web Key
DOMString kty;
DOMString use;
sequence<DOMString> key_ops;
DOMString alg;
// The following fields are defined in JSON Web Key Parameters Registration
boolean ext;
// The following fields are defined in Section 6 of JSON Web Algorithms
DOMString crv;
DOMString x;
DOMString y;
DOMString d;
DOMString n;
DOMString e;
DOMString p;
DOMString q;
DOMString dp;
DOMString dq;
DOMString qi;
sequence<RsaOtherPrimesInfo> oth;
DOMString k;
};
The following section is non-normative.
The JsonWebKey dictionary provides a way to represent and exchange cryptographic keys represented by the JSON Web Key structure, while allowing native and efficient use within Web Cryptography API applications.
typedef Uint8Array BigInteger;
The BigInteger typedef is a Uint8Array
that
holds an arbitrary magnitude unsigned integer in big-endian order. Values read from
the API SHALL have minimal typed array length (that is, at most 7 leading zero bits,
except the value 0 which shall have length 8 bits). The API SHALL accept values with
any number of leading zero bits, including the empty array, which represents zero.
The CryptoKeyPair dictionary represents an asymmetric key pair that is comprised of both public and private keys.
This section is non-normative.
In addition to providing a common interface to perform cryptographic operations, by way of the SubtleCrypto 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.
Every cryptographic algorithm defined for use with the Web Cryptography API MUST have a unique name, referred to as its recognized algorithm name, such that no other specification defines the same case-insensitive string for use with the Web Cryptography API.
Every cryptographic algorithm defined for use with the Web Cryptography API has a list of supported operations, which are a set of sub-algorithms to be invoked by the SubtleCrypto interface in order to perform the desired cryptographic operation. This specification makes use of the following operations:
If a given algorithm specification does not list a particular operation as supported, or explicitly lists an operation as not-supported, then the User Agent MUST behave as if the invocation of the sub-algorithm threw a NotSupportedError.
Every cryptographic algorithm defined for use with the Web Cryptography API MUST define, for every supported operation, the IDL type to use for algorithm normalization, as well as the IDL type or types of the return values of the sub-algorithms.
Every cryptographic algorithm definition within this specification employs the following specification conventions. A section, titled "Registration", will include the recognized algorithm name. Additionally, it includes a table, which will list each of the supported operations as rows, identified by the Operation column. The contents of the Parameters column for a given row will contain the IDL type to use for algorithm normalization for that operation, and the contents of the Result column for that row indicate the IDL type that results from performing the supported operation.
If a conforming User Agent implements an algorithm, it MUST implement all of the supported operations and MUST return the IDL type specified.
Additionally, upon initialization, conforming User Agents must perform the define an algorithm steps for each of the supported operations, registering their IDL parameter type as indicated.
This section is non-normative.
The AlgorithmIdentifier typedef permits algorithms to either be specified as a DOMString or an object. The usage of DOMString 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 an Algorithm (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 an AlgorithmIdentifier 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.
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:
For each value, v in the List of supported operations, set the v key of the internal object [[supportedAlgorithms]] to a new associative container.
The define 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 name alg, represented as a DOMString, operation name op, represented as a DOMString, and desired IDL dictionary type type. The algorithm behaves as follows:
The normalize 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 name op and an AlgorithmIdentifier alg. Its output is either an IDL dictionary type or an error. It behaves as follows:
Return the result of running the normalize an algorithm algorithm, with
the alg
set to a new Algorithm
dictionary whose name attribute is
alg, and with the op
set to op.
op
key of [[supportedAlgorithms]].
Set algName to the value of the matching key.
Let desiredType be the IDL dictionary type stored at algName in registeredAlgorithms.
NotSupportedError
and terminate this algorithm.
For each dictionary dictionary in dictionaries:
For each dictionary member member declared on dictionary, in order:
alg
set to idlValue and the
op
set to "digest"
.
alg
set to idlValue and the
op
set to the operation defined by the specification
that defines the algorithm identified by algName.
This section is non-normative.
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 following section is non-normative.
The table below contains an overview of the algorithms described within this specification, as well as the set of SubtleCrypto 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:
The encrypt method requires the encrypt operation.
The decrypt method requires the decrypt operation.
The sign method requires the sign operation.
The verify method requires the verify operation.
The generateKey method requires the generateKey operation.
The importKey method requires the importKey operation.
The exportKey method requires the exportKey operation.
The deriveKey method requires the deriveBits operation for the key derivation algorithm and the get key length and importKey operations for the derived key algorithm.
The deriveBits method requires the deriveBits operation for the key derivation algorithm.
The digest method requires the digest operation.
The wrapKey method requires either the encrypt or wrapKey operation for the wrapping algorithm and the exportKey operation for the wrapped key algorithm.
The unwrapKey method requires either the decrypt or unwrapKey operation for the unwrapping algorithm and the importKey operation for the unwrapped key algorithm.
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 the Security considerations for authors section of this document to better understand the risks and concerns that may arise when using certain algorithms.
Algorithm name | encrypt | decrypt | sign | verify | digest | generateKey | deriveKey | deriveBits | importKey | exportKey | wrapKey | unwrapKey |
---|---|---|---|---|---|---|---|---|---|---|---|---|
RSASSA-PKCS1-v1_5 | ✔ | ✔ | ✔ | ✔ | ✔ | |||||||
RSA-PSS | ✔ | ✔ | ✔ | ✔ | ✔ | |||||||
RSA-OAEP | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | |||||
ECDSA | ✔ | ✔ | ✔ | ✔ | ✔ | |||||||
ECDH | ✔ | ✔ | ✔ | ✔ | ✔ | |||||||
AES-CTR | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | |||||
AES-CBC | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | |||||
AES-GCM | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | |||||
AES-KW | ✔ | ✔ | ✔ | ✔ | ✔ | |||||||
HMAC | ✔ | ✔ | ✔ | ✔ | ✔ | |||||||
SHA-1 | ✔ | |||||||||||
SHA-256 | ✔ | |||||||||||
SHA-384 | ✔ | |||||||||||
SHA-512 | ✔ | |||||||||||
HKDF | ✔ | ✔ | ✔ | |||||||||
PBKDF2 | ✔ | ✔ | ✔ |
This section is non-normative.
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 and key import steps and key export steps for RSASSA-PKCS1-v1_5.
The recognized algorithm name for
this algorithm is "RSASSA-PKCS1-v1_5"
.
Operation | Parameters | Result |
---|---|---|
sign | None | ArrayBuffer |
verify | None | boolean |
generateKey | RsaHashedKeyGenParams | CryptoKeyPair |
importKey | RsaHashedImportParams | CryptoKey |
exportKey | None | object |
dictionary RsaKeyGenParams : Algorithm {
// The length, in bits, of the RSA modulus
[EnforceRange] required unsigned long modulusLength;
// The RSA public exponent
required BigInteger publicExponent;
};
dictionary RsaHashedKeyGenParams : RsaKeyGenParams {
// The hash algorithm to use
required HashAlgorithmIdentifier hash;
};
dictionary RsaKeyAlgorithm : KeyAlgorithm {
// The length, in bits, of the RSA modulus
required unsigned long modulusLength;
// The RSA public exponent
required BigInteger publicExponent;
};
dictionary RsaHashedKeyAlgorithm : RsaKeyAlgorithm {
// The hash algorithm that is used with this key
required KeyAlgorithm hash;
};
dictionary RsaHashedImportParams : Algorithm {
// The hash algorithm to use
required HashAlgorithmIdentifier hash;
};
If the [[type]] internal slot of
key is not "private"
, then throw an InvalidAccessError
.
Perform the signature generation operation defined in Section 8.2 of [RFC3447] with the key represented by the [[handle]] internal slot of key as the signer's private key and the contents of message as M and using the hash function specified in the hash attribute of the [[algorithm]] internal slot of key as the Hash option for the EMSA-PKCS1-v1_5 encoding method.
If performing the operation results in an error,
then throw an
OperationError
.
Let signature be the value S that results from performing the operation.
Return a new ArrayBuffer associated with the
relevant global object
of this
[HTML], and containing the
bytes of signature.
If the [[type]] internal slot of
key is not "public"
, then throw an InvalidAccessError
.
Perform the signature verification operation defined in Section 8.2 of [RFC3447] with the key represented by the [[handle]] internal slot of key as the signer's RSA public key and the contents of message as M and the contents of signature as S and using the hash function specified in the hash attribute of the [[algorithm]] internal slot of key as the Hash option for the EMSA-PKCS1-v1_5 encoding method.
Let result be a boolean with value true if the result of the operation was "valid signature" and the value false otherwise.
Return result.
If usages contains an entry which is not
"sign"
or "verify"
,
then throw a
SyntaxError
.
Generate an RSA key pair, as defined in [RFC3447], with RSA modulus length equal to the modulusLength attribute of normalizedAlgorithm and RSA public exponent equal to the publicExponent attribute of normalizedAlgorithm.
If generation of the key pair fails,
then throw an
OperationError
.
Let algorithm be a new RsaHashedKeyAlgorithm dictionary.
Set the name attribute of
algorithm to "RSASSA-PKCS1-v1_5"
.
Set the modulusLength attribute of algorithm to equal the modulusLength attribute of normalizedAlgorithm.
Set the publicExponent attribute of algorithm to equal the publicExponent attribute of normalizedAlgorithm.
Set the hash attribute of algorithm to equal the hash member of normalizedAlgorithm.
Let publicKey be a new CryptoKey
object, associated with the
relevant global object
of this
[HTML], and representing the public key of the generated key pair.
Set the [[type]] internal slot of
publicKey to "public"
Set the [[algorithm]] internal slot of publicKey to algorithm.
Set the [[extractable]] internal slot of publicKey to true.
Set the [[usages]] internal slot of
publicKey to be the usage
intersection of usages and [ "verify" ]
.
Let privateKey be a new CryptoKey associated with the
relevant global object
of this
[HTML], and
representing the private key of the generated key pair.
Set the [[type]] internal slot of
privateKey to "private"
Set the [[algorithm]] internal slot of privateKey to algorithm.
Set the [[extractable]] internal slot of privateKey to extractable.
Set the [[usages]] internal slot of
privateKey to be the usage
intersection of usages and [ "sign" ]
.
Let result be a new CryptoKeyPair dictionary.
Set the publicKey attribute of result to be publicKey.
Set the privateKey attribute of result to be privateKey.
Return result.
Let keyData be the key data to be imported.
"spki"
:
If usages contains an entry which is not
"verify"
,
then throw a
SyntaxError
.
Let spki be the result of running the parse a subjectPublicKeyInfo algorithm over keyData.
Let hash be undefined.
Let alg be the algorithm
object identifier
field of the algorithm
AlgorithmIdentifier field of
spki.
rsaEncryption
OID defined in Section 2.3.1 of RFC 3279:
Let hash be undefined.
sha1WithRSAEncryption
OID defined in Section A.2.4 of
RFC 3279:
Let hash be the string "SHA-1"
.
sha256WithRSAEncryption
OID defined in Section A.2.4 of
RFC 3447:
Let hash be the string "SHA-256"
.
sha384WithRSAEncryption
OID defined in Section A.2.4 of
RFC 3447:
Let hash be the string "SHA-384"
.
sha512WithRSAEncryption
OID defined in Section A.2.4 of
RFC 3447:
Let hash be the string "SHA-512"
.
Perform any key import steps defined by other applicable specifications, passing format, spki and obtaining hash.
If an error occurred or there are no
applicable
specifications,
throw a
DataError
.
Let normalizedHash be the result of
normalize an algorithm
with alg
set to hash and op
set
to digest
.
If normalizedHash is not equal to the
hash member of
normalizedAlgorithm, throw a DataError
.
Let publicKey be the result of performing the parse an ASN.1 structure
algorithm, with data as the
subjectPublicKeyInfo
field of spki,
structure as the RSAPublicKey
structure
specified in Section A.1.1 of RFC 3447, and
exactData set to true.
If an error occurred while parsing, or it can be determined that publicKey
is not a valid public key according to RFC 3447,
then throw a
DataError
.
Let key be a new CryptoKey associated with the
relevant global object
of this
[HTML], and
that represents the RSA public key identified by
publicKey.
Set the [[type]] internal slot
of key to "public"
"pkcs8"
:
If usages contains an entry which is not
"sign"
then throw a
SyntaxError
.
Let privateKeyInfo be the result of running the parse a privateKeyInfo algorithm over keyData.
Let hash be undefined.
Let alg be the algorithm
object identifier
field of the privateKeyAlgorithm
PrivateKeyAlgorithmIdentifier field of privateKeyInfo.
rsaEncryption
OID defined in Section 2.3.1 of RFC 3279:
Let hash be undefined.
sha1WithRSAEncryption
OID defined in Section A.2.4 of
RFC 3279:
Let hash be the string "SHA-1"
.
sha256WithRSAEncryption
OID defined in Section A.2.4 of
RFC 3447:
Let hash be the string "SHA-256"
.
sha384WithRSAEncryption
OID defined in Section A.2.4 of
RFC 3447:
Let hash be the string "SHA-384"
.
sha512WithRSAEncryption
OID defined in Section A.2.4 of
RFC 3447:
Let hash be the string "SHA-512"
.
Perform any key import steps defined by other applicable specifications, passing format, privateKeyInfo and obtaining hash.
If an error occurred or there are no
applicable
specifications,
throw a
DataError
.
Let normalizedHash be the result of
normalize an algorithm
with alg
set to hash and op
set
to digest
.
If normalizedHash is not equal to the
hash member of
normalizedAlgorithm, throw a DataError
.
Let rsaPrivateKey be the result of performing the parse an ASN.1 structure
algorithm, with data as the
privateKey
field of privateKeyInfo,
structure as the RSAPrivateKey
structure
specified in Section A.1.2 of RFC 3447, and
exactData set to true.
If an error occurred while parsing, or if rsaPrivateKey is not
a valid RSA private key according to RFC 3447,
then throw a
DataError
.
Let key be a new CryptoKey associated with the
relevant global object
of this
[HTML], and
that represents the RSA private key identified by
rsaPrivateKey.
Set the [[type]] internal slot
of key to "private"
"jwk"
:Let jwk equal keyData.
If the "d"
field of jwk is present and
usages contains an entry which is not
"sign"
, or, if the "d"
field of jwk
is not present and
usages contains an entry which is not
"verify"
then throw a
SyntaxError
.
If the "kty"
field of jwk is not a
case-sensitive string match to "RSA"
,
then throw a
DataError
.
If usages is non-empty and the "use"
field of jwk is present and is
not a case-sensitive string match to "sig"
,
then throw a
DataError
.
If the "key_ops"
field of jwk is present, and
is invalid according to the requirements of
JSON Web Key or
does not contain all of the specified usages values,
then throw a
DataError
.
If the "ext"
field of jwk is present and
has the value false and extractable is true,
then throw a
DataError
.
Let hash be a be a string whose initial value is undefined.
"alg"
field of jwk is not
present:
Let hash be undefined.
"alg"
field is equal to the string
"RS1"
:
Let hash be the string "SHA-1"
.
"alg"
field is equal to the string
"RS256"
:
Let hash be the string "SHA-256"
.
"alg"
field is equal to the string
"RS384"
:
Let hash be the string "SHA-384"
.
"alg"
field is equal to the string
"RS512"
:
Let hash be the string "SHA-512"
.
Perform any key import steps defined by other applicable specifications, passing format, jwk and obtaining hash.
If an error occurred or there are no
applicable
specifications,
throw a
DataError
.
Let normalizedHash be the result of
normalize an algorithm
with alg
set to hash and op
set
to digest
.
If normalizedHash is not equal to the
hash member of
normalizedAlgorithm, throw a DataError
.
"d"
field of jwk is present:
If jwk does not meet the requirements of
Section 6.3.2 of JSON Web
Algorithms,
then throw a
DataError
.
Let privateKey represents the RSA private key identified by interpreting jwk according to Section 6.3.2 of JSON Web Algorithms.
If privateKey is not a valid RSA private key
according to RFC 3447,
then throw a
DataError
.
Let key be a new CryptoKey object that represents privateKey.
Set the [[type]]
internal slot of key to "private"
If jwk does not meet the requirements of Section
6.3.1 of JSON Web Algorithms, then throw a DataError
.
Let publicKey represent the RSA public key identified by interpreting jwk according to Section 6.3.1 of JSON Web Algorithms.
If publicKey can be determined to not be a valid RSA public key
according to RFC 3447,
then throw a
DataError
.
Let key be a new CryptoKey representing publicKey.
Set the [[type]]
internal slot of key to "public"
NotSupportedError
.
Let algorithm be a new RsaHashedKeyAlgorithm dictionary.
Set the name attribute of
algorithm to "RSASSA-PKCS1-v1_5"
Set the modulusLength attribute of algorithm to the length, in bits, of the RSA public modulus.
Set the publicExponent attribute of algorithm to the BigInteger representation of the RSA public exponent.
Set the hash attribute of algorithm to the hash member of normalizedAlgorithm.
Set the [[algorithm]] internal slot of key to algorithm.
Return key.
Let key be the key to be exported.
If the underlying cryptographic key material represented by the [[handle]] internal slot of key
cannot be accessed, then throw an OperationError
.
"spki"
If the [[type]] internal slot
of key is not "public"
, then throw an InvalidAccessError
.
Let data be an instance of the subjectPublicKeyInfo
ASN.1 structure defined in RFC 5280
with the following properties:
Set the algorithm field to an
AlgorithmIdentifier
ASN.1 type with the following
properties:
Set the algorithm field to the OID
1.2.840.113549.1.1.1
Set the params field to the ASN.1 type NULL.
Set the subjectPublicKey field to the result of
DER-encoding an RSAPublicKey
ASN.1 type, as defined
in RFC 3447, Appendix A.1.1, that
represents the RSA public key represented by the [[handle]] internal slot of
key
Let result be a new ArrayBuffer associated with the
relevant global object
of this
[HTML], and containing
data.
"pkcs8"
:
If the [[type]] internal slot
of key is not "private"
, then throw an InvalidAccessError
.
Let data be the result of encoding a privateKeyInfo structure with the following properties:
Set the version field to 0.
Set the privateKeyAlgorithm field to a
PrivateKeyAlgorithmIdentifier
ASN.1 type with the
following properties:
Set the algorithm field to the OID
1.2.840.113549.1.1.1
Set the params field to the ASN.1 type NULL.
Set the privateKey field to the result of DER-encoding
an RSAPrivateKey
ASN.1 type, as defined in RFC 3447, Appendix A.1.2, that represents the
RSA private key represented by the [[handle]] internal slot of
key
Let result be a new ArrayBuffer associated with the
relevant global object
of this
[HTML], and containing
data.
"jwk"
:Let jwk be a new JsonWebKey dictionary.
Set the kty
attribute of jwk to the string
"RSA"
.
Let hash be the name attribute of the hash attribute of key.
"SHA-1"
:
Set the alg
attribute of jwk to the string
"RS1"
.
"SHA-256"
:
Set the alg
attribute of jwk to the string
"RS256"
.
"SHA-384"
:
Set the alg
attribute of jwk to the string
"RS384"
.
"SHA-512"
:
Set the alg
attribute of jwk to the string
"RS512"
.
Perform any key export steps defined by other applicable specifications, passing format, key and obtaining alg.
If an error occurred or there are no
applicable
specifications,
throw a
NotSupportedError
.
Set the alg
attribute of jwk to alg.
Set the attributes n
and e
of jwk
according to the corresponding definitions in JSON Web
Algorithms, Section 6.3.1.
"private"
:
Set the attributes named d
, p
,
q
, dp
, dq
, and
qi
of jwk according to the
corresponding definitions in JSON Web
Algorithms, Section 6.3.2.
If the underlying RSA private key represented by the [[handle]] internal slot
of key is represented by more than two primes, set
the attribute named oth
of jwk
according to the corresponding definition in JSON Web Algorithms, Section 6.3.2.7
Set the key_ops
attribute of jwk to the usages attribute of key.
Set the ext
attribute of jwk to the [[extractable]] internal slot
of key.
Let result be the result of converting jwk to an ECMAScript Object, as defined by [WebIDL].
Return result.
This section is non-normative.
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 and key import steps and key export steps for RSASSA-PSS.
The recognized algorithm name for
this algorithm is "RSA-PSS"
.
Operation | Parameters | Result |
---|---|---|
sign | RsaPssParams | ArrayBuffer |
verify | RsaPssParams | boolean |
generateKey | RsaHashedKeyGenParams | CryptoKeyPair |
importKey | RsaHashedImportParams | CryptoKey |
exportKey | None | object |
dictionary RsaPssParams : Algorithm {
// The desired length of the random salt
[EnforceRange] required unsigned long saltLength;
};
If the [[type]] internal slot of
key is not "private"
, then throw an InvalidAccessError
.
Perform the signature generation operation defined in Section 8.1 of [RFC3447] with the key represented by the [[handle]] internal slot of key as the signer's private key, K, and the contents of message as the message to be signed, M, and using the hash function specified by the hash attribute of the [[algorithm]] internal slot of key as the Hash option, MGF1 (defined in Section B.2.1 of [RFC3447]) as the MGF option and the saltLength member of normalizedAlgorithm as the salt length option for the EMM-PSS-ENCODE operation.
If performing the operation results in an error,
then throw an
OperationError
.
Let signature be the signature, S, that results from performing the operation.
Return a new ArrayBuffer associated with the
relevant global object
of this
[HTML], and containing the
bytes of signature.
If the [[type]] internal slot of
key is not "public"
, then throw an InvalidAccessError
.
Perform the signature verification operation defined in Section 8.1 of [RFC3447] with the key represented by the [[handle]] internal slot of key as the signer's RSA public key and the contents of message as M and the contents of signature as S and using the hash function specified by the hash attribute of the [[algorithm]] internal slot of key as the Hash option, MGF1 (defined in Section B.2.1 of [RFC3447]) as the MGF option and the saltLength member of normalizedAlgorithm as the salt length option for the EMSA-PSS-VERIFY operation.
Let result be a boolean with the value true if the result of the operation was "valid signature" and the value false otherwise.
If usages contains an entry which is not
"sign"
or "verify"
,
then throw a
SyntaxError
.
Generate an RSA key pair, as defined in [RFC3447], with RSA modulus length equal to the modulusLength member of normalizedAlgorithm and RSA public exponent equal to the publicExponent member of normalizedAlgorithm.
If performing the operation results in an error,
then throw an
OperationError
.
Let algorithm be a new RsaHashedKeyAlgorithm dictionary.
Set the name attribute of
algorithm to "RSA-PSS"
.
Set the modulusLength attribute of algorithm to equal the modulusLength member of normalizedAlgorithm.
Set the publicExponent attribute of algorithm to equal the publicExponent member of normalizedAlgorithm.
Set the hash attribute of algorithm to equal the hash member of normalizedAlgorithm.
Let publicKey be a new CryptoKey associated with the
relevant global object
of this
[HTML], and
representing the public key of the generated key pair.
Set the [[type]] internal slot of
publicKey to "public"
Set the [[algorithm]] internal slot of publicKey to algorithm.
Set the [[extractable]] internal slot of publicKey to true.
Set the [[usages]] internal slot of
publicKey to be the usage
intersection of usages and [ "verify" ]
.
Let privateKey be a new CryptoKey associated with the
relevant global object
of this
[HTML], and
representing the private key of the generated key pair.
Set the [[type]] internal slot of
privateKey to "private"
Set the [[algorithm]] internal slot of privateKey to algorithm.
Set the [[extractable]] internal slot of privateKey to extractable.
Set the [[usages]] internal slot of
privateKey to be the usage
intersection of usages and [ "sign" ]
.
Let result be a new CryptoKeyPair dictionary.
Set the publicKey attribute of result to publicKey.
Set the privateKey attribute of result to privateKey.
Return the result of converting result to an ECMAScript Object, as defined by [WebIDL].
Let keyData be the key data to be imported.
"spki"
:
If usages contains an entry which is not
"verify"
then throw a
SyntaxError
.
Let spki be the result of running the parse a subjectPublicKeyInfo algorithm over keyData.
Let hash be undefined.
Let alg be the algorithm
object identifier
field of the algorithm
AlgorithmIdentifier field of
spki.
rsaEncryption
OID defined in RFC 3447:
Let hash be undefined.
id-RSASSA-PSS
OID defined in
RFC 3447:
Let params be the ASN.1 structure contained within
the parameters
field of the algorithm
AlgorithmIdentifier field of spki.
If params is not defined, or is not an instance of
the RSASSA-PSS-params
ASN.1 type defined in
RFC3447,
throw a
DataError
.
Let hashAlg be the AlgorithmIdentifier ASN.1 type
within the hashAlgorithm
field of params.
algorithm
object identifier field of
hashAlg is equivalent to the id-sha1
OID defined in RFC 3447:
Set hash to the string "SHA-1"
.
algorithm
object identifier field of
hashAlg is equivalent to the id-sha256
OID defined in RFC 3447:
Set hash to the string "SHA-256"
.
algorithm
object identifier field of
hashAlg is equivalent to the id-sha384
OID defined in RFC 3447:
Set hash to the string "SHA-384"
.
algorithm
object identifier field of
hashAlg is equivalent to the id-sha512
OID defined in RFC 3447:
Set hash to the string "SHA-512"
.
Perform any key import steps defined by other applicable specifications, passing format, spki and obtaining hash.
If an error occurred or there are no
applicable
specifications,
throw a
DataError
.
If the algorithm
object identifier field of the
maskGenAlgorithm
field of params is not
equivalent to the OID id-mgf1
defined in RFC 3447, throw a NotSupportedError
.
If the parameters
field of the
maskGenAlgorithm
field of params is not
an instance of the HashAlgorithm
ASN.1 type that is
identical in content to the hashAlglorithm
field of
params, throw a NotSupportedError
.
Let normalizedHash be the result of
normalize an algorithm
with alg
set to hash and op
set
to digest
.
If normalizedHash is not equal to the
hash member of
normalizedAlgorithm, throw a DataError
.
Let publicKey be the result of performing the parse an ASN.1 structure
algorithm, with data as the
subjectPublicKeyInfo
field of spki,
structure as the RSAPublicKey
structure
specified in Section A.1.1 of RFC 3447, and
exactData set to true.
If an error occurred while parsing, or it can be determined that publicKey
is not a valid public key according to RFC 3447,
then throw a
DataError
.
Let key be a new CryptoKey associated with the
relevant global object
of this
[HTML], and
that represents the RSA public key identified by
publicKey.
Set the [[type]] internal slot
of key to "public"
"pkcs8"
:
If usages contains an entry which is not
"sign"
then throw a
SyntaxError
.
Let privateKeyInfo be the result of running the parse a privateKeyInfo algorithm over keyData.
Let hash be undefined.
Let alg be the algorithm
object identifier
field of the privateKeyAlgorithm
PrivateKeyAlgorithmIdentifier field of privateKeyInfo.
rsaEncryption
OID defined in RFC 3447:
Let hash be undefined.
id-RSASSA-PSS
OID
defined in RFC 3447:
Let params be the ASN.1 structure contained within
the parameters
field of the
privateKeyAlgorithm
PrivateKeyAlgorithmIdentifier
field of privateKeyInfo.
If params is not defined, or is not an instance of
the RSASSA-PSS-params
ASN.1 type defined in
RFC3447,
throw a
NotSupportedError
.
Let hashAlg be the AlgorithmIdentifier ASN.1 type
within the hashAlgorithm
field of params.
algorithm
object identifier field of
hashAlg is equivalent to the id-sha1
OID defined in RFC 3447:
Set hash to the string "SHA-1"
.
algorithm
object identifier field of
hashAlg is equivalent to the id-sha256
OID defined in RFC 3447:
Set hash to the string "SHA-256"
.
algorithm
object identifier field of
hashAlg is equivalent to the id-sha384
OID defined in RFC 3447:
Set hash to the string "SHA-384"
.
algorithm
object identifier field of
hashAlg is equivalent to the id-sha512
OID defined in RFC 3447:
Set hash to the string "SHA-512"
.
Perform any key import steps defined by other applicable specifications, passing format, privateKeyInfo and obtaining hash.
If an error occurred or there are no
applicable
specifications,
throw a
DataError
.
If the algorithm
object identifier field of the
maskGenAlgorithm
field of params is not
equivalent to the OID id-mgf1
defined in RFC 3447, throw a NotSupportedError
.
If the parameters
field of the
maskGenAlgorithm
field of params is not
an instance of the HashAlgorithm
ASN.1 type that is
identical in content to the hashAlglorithm
field of
params, throw a NotSupportedError
.
Let normalizedHash be the result of
normalize an algorithm
with alg
set to hash and op
set
to digest
.
If normalizedHash is not equal to the
hash member of
normalizedAlgorithm, throw a DataError
.
Let rsaPrivateKey be the result of performing the parse an ASN.1 structure
algorithm, with data as the
privateKey
field of privateKeyInfo,
structure as the RSAPrivateKey
structure
specified in Section A.1.2 of RFC 3447, and
exactData set to true.
If an error occurred while parsing, or if rsaPrivateKey is not
a valid RSA private key according to RFC 3447,
then throw a
DataError
.
Let key be a new CryptoKey associated with the
relevant global object
of this
[HTML], and
that represents the RSA private key identified by
rsaPrivateKey.
Set the [[type]] internal slot
of key to "private"
"jwk"
:Let jwk equal keyData.
If the "d"
field of jwk is present and
usages contains an entry which is not
"sign"
, or, if the "d"
field of jwk
is not present and
usages contains an entry which is not
"verify"
then throw a
SyntaxError
.
If the "kty"
field of jwk is not a
case-sensitive string match to "RSA"
,
then throw a
DataError
.
If usages is non-empty and the "use"
field of jwk is present and is
not a case-sensitive string match to "sig"
,
then throw a
DataError
.
If the "key_ops"
field of jwk is present, and
is invalid according to the requirements of
JSON Web Key or
does not contain all of the specified usages values,
then throw a
DataError
.
If the "ext"
field of jwk is present and
has the value false and extractable is true,
then throw a
DataError
.
"alg"
field of jwk is not
present:
Let hash be undefined.
"alg"
field is equal to the string
"PS1"
:
Let hash be the string "SHA-1"
.
"alg"
field is equal to the string
"PS256"
:
Let hash be the string "SHA-256"
.
"alg"
field is equal to the string
"PS384"
:
Let hash be the string "SHA-384"
.
"alg"
field is equal to the string
"PS512"
:
Let hash be the string "SHA-512"
.
Perform any key import steps defined by other applicable specifications, passing format, jwk and obtaining hash.
If an error occurred or there are no
applicable
specifications,
throw a
DataError
.
Let normalizedHash be the result of
normalize an algorithm
with alg
set to hash and op
set
to digest
.
If normalizedHash is not equal to the
hash member of
normalizedAlgorithm, throw a DataError
.
"d"
field of jwk is present:
If jwk does not meet the requirements of
Section 6.3.2 of JSON Web
Algorithms,
then throw a
DataError
.
Let privateKey represent the RSA public key identified by interpreting jwk according to Section 6.3.1 of JSON Web Algorithms.
If privateKey can be determined to not be a valid RSA public key
according to RFC 3447,
then throw a
DataError
.
Let key be a new CryptoKey representing privateKey.
Set the [[type]]
internal slot of key to "private"
If jwk does not meet the requirements of Section
6.3.1 of JSON Web Algorithms, then throw a DataError
.
Let publicKey represent the RSA public key identified by interpreting jwk according to Section 6.3.1 of JSON Web Algorithms.
If publicKey can be determined to not be a valid RSA public key
according to RFC 3447,
then throw a
DataError
.
Let key be a new CryptoKey representing publicKey.
Set the [[type]]
internal slot of key to "public"
NotSupportedError
.
Let algorithm be a new RsaHashedKeyAlgorithm dictionary.
Set the name attribute of
algorithm to "RSA-PSS"
Set the modulusLength attribute of algorithm to the length, in bits, of the RSA public modulus.
Set the publicExponent attribute of algorithm to the BigInteger representation of the RSA public exponent.
Set the hash attribute of algorithm to the hash member of normalizedAlgorithm.
Set the [[algorithm]] internal slot of key to algorithm
Return key.
Let key be the key to be exported.
If the underlying cryptographic key material represented by the [[handle]] internal slot of key
cannot be accessed, then throw an OperationError
.
"spki"
If the [[type]] internal slot
of key is not "public"
, then throw an InvalidAccessError
.
Let data be an instance of the subjectPublicKeyInfo
ASN.1 structure defined in RFC 5280
with the following properties:
Set the algorithm field to an
AlgorithmIdentifier
ASN.1 type with the following
properties:
Set the algorithm field to the OID
id-RSASSA-PSS
defined in
RFC 3447.
Set the params field to an instance of the
RSASSA-PSS-params
ASN.1 type with the following
properties:
Set the hashAlgorithm field to an instance of
the HashAlgorithm
ASN.1 type with the
following properties:
"SHA-1"
:
Set the algorithm object identifier
of hashAlgorithm to the
OID id-sha1
defined in RFC 3447.
"SHA-256"
:
Set the algorithm object identifier
of hashAlgorithm to the
OID id-sha256
defined in RFC 3447.
"SHA-384"
:
Set the algorithm object identifier
of hashAlgorithm to the
OID id-sha384
defined in RFC 3447.
"SHA-512"
:
Set the algorithm object identifier
of hashAlgorithm to the
OID id-sha512
defined in RFC 3447.
Perform any key export steps defined by other applicable specifications, passing format and the hash attribute of the [[algorithm]] internal slot of key and obtaining hashOid and hashParams.
Set the algorithm object identifier of hashAlgorithm to hashOid.
Set the params field of hashAlgorithm to hashParams if hashParams is not undefined and omit the params field otherwise.
Set the maskGenAlgorithm field to an instance
of the MaskGenAlgorithm
ASN.1 type with the
following properties:
Set the algorithm field to the OID
id-mgf1
defined in RFC
3447.
Set the params field to an instance of the
HashAlgorithm
ASN.1 type that is
identical to the hashAlgorithm field.
Set the saltLength field to the length in octets of the digest algorithm identified by the name attribute of the hash attribute of the [[algorithm]] internal slot of key.
Set the subjectPublicKey field to the result of
DER-encoding an RSAPublicKey
ASN.1 type, as defined
in RFC 3447, Appendix A.1.1, that
represents the RSA public key represented by the [[handle]] internal slot of
key
Let result be a new ArrayBuffer associated with the
relevant global object
of this
[HTML], and containing
data.
"pkcs8"
:
If the [[type]] internal slot
of key is not "private"
, then throw an InvalidAccessError
.
Let data be the result of encoding a privateKeyInfo structure with the following properties:
Set the version field to 0.
Set the privateKeyAlgorithm field to an
PrivateKeyAlgorithmIdentifier
ASN.1 type with the
following properties:
Set the algorithm field to the OID
id-RSASSA-PSS
defined in
RFC 3447.
Set the params field to an instance of the
RSASSA-PSS-params
ASN.1 type with the following
properties:
Set the hashAlgorithm field to an instance of
the HashAlgorithm
ASN.1 type with the
following properties:
"SHA-1"
:
Set the algorithm object identifier
of hashAlgorithm to the
OID id-sha1
defined in RFC 3447.
"SHA-256"
:
Set the algorithm object identifier
of hashAlgorithm to the
OID id-sha256
defined in RFC 3447.
"SHA-384"
:
Set the algorithm object identifier
of hashAlgorithm to the
OID id-sha384
defined in RFC 3447.
"SHA-512"
:
Set the algorithm object identifier
of hashAlgorithm to the
OID id-sha512
defined in RFC 3447.
Perform any key export steps defined by other applicable specifications, passing format and the hash attribute of the [[algorithm]] internal slot of key and obtaining hashOid and hashParams.
Set the algorithm object identifier of hashAlgorithm to hashOid.
Set the params field of hashAlgorithm to hashParams if hashParams is not undefined and omit the params field otherwise.
Set the maskGenAlgorithm field to an instance
of the MaskGenAlgorithm
ASN.1 type with the
following properties:
Set the algorithm field to the OID
id-mgf1
defined in RFC
3447.
Set the params field to an instance of the
HashAlgorithm
ASN.1 type that is
identical to the hashAlgorithm field.
Set the saltLength field to the length in octets of the digest algorithm identified by the name attribute of the hash attribute of the [[algorithm]] internal slot of key.
Set the privateKey field to the result of DER-encoding
an RSAPrivateKey
ASN.1 type, as defined in RFC 3447, Appendix A.1.2, that represents the
RSA private key represented by the [[handle]] internal slot of
key
Let result be a new ArrayBuffer associated with the
relevant global object
of this
[HTML], and containing
data.
"jwk"
:Let jwk be a new JsonWebKey dictionary.
Set the kty
attribute of jwk to the string
"RSA"
.
Let hash be the name attribute of the hash attribute of the [[algorithm]] internal slot of key.
"SHA-1"
:
Set the alg
attribute of jwk to the string
"PS1"
.
"SHA-256"
:
Set the alg
attribute of jwk to the string
"PS256"
.
"SHA-384"
:
Set the alg
attribute of jwk to the string
"PS384"
.
"SHA-512"
:
Set the alg
attribute of jwk to the string
"PS512"
.
Perform any key export steps defined by other applicable specifications, passing format and the hash attribute of the [[algorithm]] internal slot of key and obtaining alg.
Set the alg
attribute of jwk to alg.
Set the attributes n
and e
of jwk
according to the corresponding definitions in JSON Web
Algorithms, Section 6.3.1.
"private"
:
Set the attributes named d
, p
,
q
, dp
, dq
, and
qi
of jwk according to the
corresponding definitions in JSON Web
Algorithms, Section 6.3.2.
If the underlying RSA private key represented by the [[handle]] internal slot
of key is represented by more than two primes, set
the attribute named oth
of jwk
according to the corresponding definition in JSON Web Algorithms, Section 6.3.2.7
Set the key_ops
attribute of jwk to the usages attribute of key.
Set the ext
attribute of jwk to the [[extractable]] internal slot
of key.
Let result be the result of converting jwk to an ECMAScript Object, as defined by [WebIDL].
Return result.
This section is non-normative.
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 and key import steps and key export steps for RSAES-OAEP.
The recognized algorithm name for
this algorithm is "RSA-OAEP"
.
Operation | Parameters | Result |
---|---|---|
encrypt | RsaOaepParams | ArrayBuffer |
decrypt | RsaOaepParams | ArrayBuffer |
generateKey | RsaHashedKeyGenParams | CryptoKeyPair |
importKey | RsaHashedImportParams | CryptoKey |
exportKey | None | object |
dictionary RsaOaepParams : Algorithm {
// The optional label/application data to associate with the message
BufferSource label;
};
If the [[type]] internal slot of key
is not "public"
,
then throw an
InvalidAccessError
.
Let label be the contents of the label member of normalizedAlgorithm or the empty octet string if the label member of normalizedAlgorithm is not present.
Perform the encryption operation defined in Section 7.1 of [RFC3447] with the key represented by key as the recipient's RSA public key, the contents of plaintext as the message to be encrypted, M and label as the label, L, and with the hash function specified by the hash attribute of the [[algorithm]] internal slot of key 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,
then throw an
OperationError
.
Let ciphertext be the value C that results from performing the operation.
Return a new ArrayBuffer associated with the
relevant global object
of this
[HTML], and
containing ciphertext.
If the [[type]] internal slot of key
is not "private"
,
then throw an
InvalidAccessError
.
Let label be the contents of the label member of normalizedAlgorithm or the empty octet string if the label member of normalizedAlgorithm is not present.
Perform the decryption operation defined in Section 7.1 of [RFC3447] with the key represented by key as the recipient's RSA private key, the contents of ciphertext as the ciphertext to be decrypted, C, and label as the label, L, and with the hash function specified by the hash attribute of the [[algorithm]] internal slot of key 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,
then throw an
OperationError
.
Let plaintext the value M that results from performing the operation.
Return a new ArrayBuffer associated with the
relevant global object
of this
[HTML], and
containing plaintext.
If usages contains an entry which is not
"encrypt"
, "decrypt"
,
"wrapKey"
or "unwrapKey"
,
then throw a
SyntaxError
.
Generate an RSA key pair, as defined in [RFC3447], with RSA modulus length equal to the modulusLength member of normalizedAlgorithm and RSA public exponent equal to the publicExponent member of normalizedAlgorithm.
If performing the operation results in an error,
then throw an
OperationError
.
Let algorithm be a new RsaHashedKeyAlgorithm object.
Set the name attribute of
algorithm to "RSA-OAEP"
.
Set the modulusLength attribute of algorithm to equal the modulusLength member of normalizedAlgorithm.
Set the publicExponent attribute of algorithm to equal the publicExponent member of normalizedAlgorithm.
Set the hash attribute of algorithm to equal the hash member of normalizedAlgorithm.
Let publicKey be a new CryptoKey associated with the
relevant global object
of this
[HTML], and
representing the public key of the generated key pair.
Set the [[type]] internal slot of
publicKey to "public"
Set the [[algorithm]] internal slot of publicKey to algorithm.
Set the [[extractable]] internal slot of publicKey to true.
Set the [[usages]] internal slot of
publicKey to be the
usage intersection of
usages and [ "encrypt", "wrapKey" ]
.
Let privateKey be a new CryptoKey associated with the
relevant global object
of this
[HTML], and
representing the private key of the generated key pair.
Set the [[type]] internal slot of
privateKey to "private"
Set the [[algorithm]] internal slot of privateKey to algorithm.
Set the [[extractable]] internal slot of privateKey to extractable.
Set the [[usages]] internal slot of
privateKey to be the
usage intersection of
usages and [ "decrypt", "unwrapKey" ]
.
Let result be a new CryptoKeyPair dictionary.
Set the publicKey attribute of result to be publicKey.
Set the privateKey attribute of result to be privateKey.
Return the result of converting result to an ECMAScript Object, as defined by [WebIDL].
Let keyData be the key data to be imported.
"spki"
:
If usages contains an entry which is not
"encrypt"
or
"wrapKey"
,
then throw a
SyntaxError
.
Let spki be the result of running the parse a subjectPublicKeyInfo algorithm over keyData.
Let hash be a string whose initial value is undefined.
Let alg be the algorithm
object identifier
field of the algorithm
AlgorithmIdentifier field of
spki.
rsaEncryption
OID defined in RFC 3447:
Let hash be undefined.
id-RSAES-OAEP
OID defined in RFC 3447:
Let params be the ASN.1 structure contained within
the parameters
field of the algorithm
AlgorithmIdentifier field of spki.
If params is not defined, or is not an instance of
the RSAES-OAEP-params
ASN.1 type defined in
RFC3447,
throw a
DataError
.
Let hashAlg be the AlgorithmIdentifier ASN.1 type
within the hashAlgorithm
field of params.
algorithm
object identifier field of
hashAlg is equivalent to the id-sha1
OID defined in RFC 3447:
Set hash to the string "SHA-1"
.
algorithm
object identifier field of
hashAlg is equivalent to the id-sha256
OID defined in RFC 3447:
Set hash to the string "SHA-256"
.
algorithm
object identifier field of
hashAlg is equivalent to the id-sha384
OID defined in RFC 3447:
Set hash to the string "SHA-384"
.
algorithm
object identifier field of
hashAlg is equivalent to the id-sha512
OID defined in RFC 3447:
Set hash to the string "SHA-512"
.
Perform any key import steps defined by other applicable specifications, passing format, spki and obtaining hash.
If an error occured or there are no
applicable
specifications,
throw a
DataError
.
If the algorithm
object identifier field of the
maskGenAlgorithm
field of params is not
equivalent to the OID id-mgf1
defined in RFC 3447, throw a NotSupportedError
.
If the parameters
field of the
maskGenAlgorithm
field of params is not
an instance of the HashAlgorithm
ASN.1 type that is
identical in content to the hashAlglorithm
field of
params, throw a NotSupportedError
.
Let normalizedHash be the result of
normalize an algorithm
with alg
set to hash and op
set
to digest
.
If normalizedHash is not equal to the
hash member of
normalizedAlgorithm, throw a DataError
.
Let publicKey be the result of performing the parse an ASN.1 structure
algorithm, with data as the
subjectPublicKeyInfo
field of spki,
structure as the RSAPublicKey
structure
specified in Section A.1.1 of RFC 3447, and
exactData set to true.
If an error occurred while parsing, or it can be determined that publicKey
is not a valid public key according to RFC 3447,
then throw a
DataError
.
Let key be a new CryptoKey associated with the
relevant global object
of this
[HTML], and
that represents the RSA public key identified by
publicKey.
Set the [[type]] internal slot of
key to "public"
"pkcs8"
:
If usages contains an entry which is not
"decrypt"
or "unwrapKey"
,
then throw a
SyntaxError
.
Let privateKeyInfo be the result of running the parse a privateKeyInfo algorithm over keyData.
Let hash be a string whose initial value is undefined.
Let alg be the algorithm
object identifier
field of the privateKeyAlgorithm
PrivateKeyAlgorithmIdentifier field of privateKeyInfo.
rsaEncryption
OID defined in RFC 3447:
Let hash be undefined.
id-RSAES-OAEP
OID defined in RFC 3447:
Let params be the ASN.1 structure contained within
the parameters
field of the
privateKeyAlgorithm
PrivateKeyAlgorithmIdentifier
field of privateKeyInfo.
If params is not defined, or is not an instance of
the RSAES-OAEP-params
ASN.1 type defined in RFC3447, throw a NotSupportedError
.
Let hashAlg be the AlgorithmIdentifier ASN.1 type
within the hashAlgorithm
field of
params.
algorithm
object identifier field of
hashAlg is equivalent to the id-sha1
OID defined in RFC 3447:
Set hash to the string "SHA-1"
.
algorithm
object identifier field of
hashAlg is equivalent to the
id-sha256
OID defined in RFC
3447:
Set hash to the string "SHA-256"
.
algorithm
object identifier field of
hashAlg is equivalent to the
id-sha384
OID defined in RFC
3447:
Set hash to the string "SHA-384"
.
algorithm
object identifier field of
hashAlg is equivalent to the
id-sha512
OID defined in RFC
3447:
Set hash to the string "SHA-512"
.
Perform any key import steps defined by other applicable specifications, passing format, spki and obtaining hash.
If an error occured or there are no
applicable
specifications,
throw a
DataError
.
If the algorithm
object identifier field of the
maskGenAlgorithm
field of params is not
equivalent to the OID id-mgf1
defined in RFC 3447, throw a NotSupportedError
.
If the parameters
field of the
maskGenAlgorithm
field of params is not
an instance of the HashAlgorithm
ASN.1 type that is
identical in content to the hashAlglorithm
field of
params, throw a NotSupportedError
.
Let normalizedHash be the result of
normalize an algorithm
with alg
set to hash and op
set
to digest
.
If normalizedHash is not equal to the
hash member of
normalizedAlgorithm, throw a DataError
.
Let rsaPrivateKey be the result of performing the parse an ASN.1 structure
algorithm, with data as the
privateKey
field of privateKeyInfo,
structure as the RSAPrivateKey
structure
specified in Section A.1.2 of RFC 3447, and
exactData set to true.
If an error occurred while parsing, or if rsaPrivateKey is not
a valid RSA private key according to RFC 3447,
then throw a
DataError
.
Let key be a new CryptoKey associated with the
relevant global object
of this
[HTML], and
that represents the RSA private key identified by
rsaPrivateKey.
Set the [[type]] internal slot of
key to "private"
"jwk"
:Let jwk equal keyData.
If the "d"
field of jwk is present and
usages contains an entry which is not
"decrypt"
or "unwrapKey"
,
then throw a
SyntaxError
.
If the "d"
field of jwk is not present and
usages contains an entry which is not
"encrypt"
or "wrapKey"
,
then throw a
SyntaxError
.
If the "kty"
field of jwk is not a
case-sensitive string match to "RSA"
,
then throw a
DataError
.
If usages is non-empty and the "use"
field of jwk is present and is
not a case-sensitive string match to "enc"
,
then throw a
DataError
.
If the "key_ops"
field of jwk is present, and
is invalid according to the requirements of
JSON Web Key or
does not contain all of the specified usages values,
then throw a
DataError
.
If the "ext"
field of jwk is present and
has the value false and extractable is true,
then throw a
DataError
.
alg
field of jwk is not present:alg
field of jwk is equal to
"RSA-OAEP"
:
"SHA-1"
.alg
field of jwk is equal to
"RSA-OAEP-256"
:
"SHA-256"
.alg
field of jwk is equal to
"RSA-OAEP-384"
:
"SHA-384"
.alg
field of jwk is equal to
"RSA-OAEP-512"
:
"SHA-512"
.Perform any key import steps defined by other applicable specifications, passing format, jwk and obtaining hash.
If an error occured or there are no
applicable
specifications,
throw a
DataError
.
Let normalizedHash be the result of
normalize an algorithm
with alg
set to hash and op
set
to digest
.
If normalizedHash is not equal to the
hash member of
normalizedAlgorithm, throw a DataError
.
"d"
field of jwk is present:
If jwk does not meet the requirements of Section
6.3.2 of JSON Web Algorithms, then throw a DataError
.
Let privateKey represent the RSA public key identified by interpreting jwk according to Section 6.3.1 of JSON Web Algorithms.
If privateKey can be determined to not be a valid RSA public key
according to RFC 3447,
then throw a
DataError
.
Let key be a new CryptoKey representing privateKey.
Set the [[type]] internal slot of
key to "private"
If jwk does not meet the requirements of Section
6.3.1 of JSON Web Algorithms, then throw a DataError
.
Let publicKey represent the RSA public key identified by interpreting jwk according to Section 6.3.1 of JSON Web Algorithms.
If publicKey can be determined to not be a valid RSA public key
according to RFC 3447,
then throw a
DataError
.
Let key be a new CryptoKey representing publicKey.
Set the [[type]] internal slot of
key to "public"
NotSupportedError
.
Let algorithm be a new RsaHashedKeyAlgorithm.
Set the name attribute of
algorithm to "RSA-OAEP"
Set the modulusLength attribute of algorithm to the length, in bits, of the RSA public modulus.
Set the publicExponent attribute of algorithm to the BigInteger representation of the RSA public exponent.
Set the hash attribute of algorithm to the hash member of normalizedAlgorithm.
Set the [[algorithm]] internal slot of key to algorithm
Return key.
Let key be the key to be exported.
If the underlying cryptographic key material represented by the [[handle]] internal slot of key
cannot be accessed, then throw an OperationError
.
"spki"
If the [[type]] internal slot of
key is not "public"
, then throw an InvalidAccessError
.
Let data be an instance of the subjectPublicKeyInfo
ASN.1 structure defined in RFC 5280
with the following properties:
Set the algorithm field to an
AlgorithmIdentifier
ASN.1 type with the following
properties:
Set the algorithm field to the OID
id-RSAES-OAEP
defined in
RFC 3447.
Set the params field to an instance of the
RSAES-OAEP-params
ASN.1 type with the following
properties:
Set the hashAlgorithm field to an instance of
the HashAlgorithm
ASN.1 type with the
following properties:
"SHA-1"
:
Set the algorithm object identifier
of hashAlgorithm to the
OID id-sha1
defined in RFC 3447.
"SHA-256"
:
Set the algorithm object identifier
of hashAlgorithm to the
OID id-sha256
defined in RFC 3447.
"SHA-384"
:
Set the algorithm object identifier
of hashAlgorithm to the
OID id-sha384
defined in RFC 3447.
"SHA-512"
:
Set the algorithm object identifier
of hashAlgorithm to the
OID id-sha512
defined in RFC 3447.
Perform any key export steps defined by other applicable specifications, passing format and the hash attribute of the [[algorithm]] internal slot of key and obtaining hashOid and hashParams.
Set the algorithm object identifier of hashAlgorithm to hashOid.
Set the params field of hashAlgorithm to hashParams if hashParams is not undefined and omit the params field otherwise.
Set the maskGenAlgorithm field to an instance
of the MaskGenAlgorithm
ASN.1 type with the
following properties:
Set the algorithm field to the OID
id-mgf1
defined in RFC
3447.
Set the params field to an instance of the
HashAlgorithm
ASN.1 type that is
identical to the hashAlgorithm field.
Set the subjectPublicKey field to the result of
DER-encoding an RSAPublicKey
ASN.1 type, as defined
in RFC 3447, Appendix A.1.1, that
represents the RSA public key represented by the [[handle]] internal slot of
key
Let result be a new ArrayBuffer associated with the
relevant global object
of this
[HTML], and containing
data.
"pkcs8"
:
If the [[type]] internal slot of
key is not "private"
, then throw an InvalidAccessError
.
Let data be the result of encoding a privateKeyInfo structure with the following properties:
Set the version field to 0.
Set the privateKeyAlgorithm field to an
PrivateKeyAlgorithmIdentifier
ASN.1 type with the
following properties:
Set the algorithm field to the OID
id-RSAES-OAEP
defined in
RFC 3447.
Set the params field to an instance of the
RSAES-OAEP-params
ASN.1 type with the following
properties:
Set the hashAlgorithm field to an instance of
the HashAlgorithm
ASN.1 type with the
following properties:
"SHA-1"
:
Set the algorithm object identifier
of hashAlgorithm to the
OID id-sha1
defined in RFC 3447.
"SHA-256"
:
Set the algorithm object identifier
of hashAlgorithm to the
OID id-sha256
defined in RFC 3447.
"SHA-384"
:
Set the algorithm object identifier
of hashAlgorithm to the
OID id-sha384
defined in RFC 3447.
"SHA-512"
:
Set the algorithm object identifier
of hashAlgorithm to the
OID id-sha512
defined in RFC 3447.
Perform any key export steps defined by other applicable specifications, passing format and the hash attribute of the [[algorithm]] internal slot of key and obtaining hashOid and hashParams.
Set the algorithm object identifier of hashAlgorithm to hashOid.
Set the params field of hashAlgorithm to hashParams if hashParams is not undefined and omit the params field otherwise.
Set the maskGenAlgorithm field to an instance
of the MaskGenAlgorithm
ASN.1 type with the
following properties:
Set the algorithm field to the OID
id-mgf1
defined in RFC
3447.
Set the params field to an instance of the
HashAlgorithm
ASN.1 type that is
identical to the hashAlgorithm field.
Set the privateKey field to the result of DER-encoding
an RSAPrivateKey
ASN.1 type, as defined in RFC 3447, Appendix A.1.2, that represents the
RSA private key represented by the [[handle]] internal slot of
key
Let result be a new ArrayBuffer associated with the
relevant global object
of this
[HTML], and containing
data.
"jwk"
:Let jwk be a new JsonWebKey dictionary.
Set the kty
attribute of jwk to the string
"RSA"
.
"SHA-1"
:
Set the alg
attribute of jwk to the string
"RSA-OAEP"
.
"SHA-256"
:
Set the alg
attribute of jwk to the string
"RSA-OAEP-256"
.
"SHA-384"
:
Set the alg
attribute of jwk to the string
"RSA-OAEP-384"
.
"SHA-512"
:
Set the alg
attribute of jwk to the string
"RSA-OAEP-512"
.
Perform any key export steps defined by other applicable specifications, passing format and the hash attribute of the [[algorithm]] internal slot of key and obtaining alg.
Set the alg
attribute of jwk to alg.
Set the attributes n
and e
of jwk
according to the corresponding definitions in JSON Web
Algorithms, Section 6.3.1.
"private"
:
Set the attributes named d
, p
,
q
, dp
, dq
, and
qi
of jwk according to the
corresponding definitions in JSON Web
Algorithms, Section 6.3.2.
If the underlying RSA private key represented by the [[handle]] internal slot
of key is represented by more than two primes, set
the attribute named oth
of jwk
according to the corresponding definition in JSON Web Algorithms, Section 6.3.2.7
Set the key_ops
attribute of jwk to the usages attribute of key.
Set the ext
attribute of jwk to the [[extractable]] internal slot
of key.
Let result be the result of converting jwk to an ECMAScript Object, as defined by [WebIDL].
Return result.
This section is non-normative.
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 a registered algorithm that supports the digest operation. To specify an additional elliptic curve a specification must define the curve name, ECDSA signature steps, ECDSA verification steps, ECDSA generation steps, ECDSA key import steps and ECDSA key export steps.
The recognized algorithm name for
this algorithm is "ECDSA"
.
Operation | Parameters | Result |
---|---|---|
sign | EcdsaParams | ArrayBuffer |
verify | EcdsaParams | boolean |
generateKey | EcKeyGenParams | CryptoKeyPair |
importKey | EcKeyImportParams | CryptoKey |
exportKey | None | object |
dictionary EcdsaParams : Algorithm {
// The hash algorithm to use
required HashAlgorithmIdentifier hash;
};
typedef DOMString NamedCurve;
dictionary EcKeyGenParams : Algorithm {
// A named curve
required NamedCurve namedCurve;
};
The NamedCurve 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"
secp256r1
."P-384"
secp384r1
."P-521"
secp521r1
.Other specifications may define additional values.
dictionary EcKeyAlgorithm : KeyAlgorithm {
// The named curve that the key uses
required NamedCurve namedCurve;
};
dictionary EcKeyImportParams : Algorithm {
// A named curve
required NamedCurve namedCurve;
};
If the [[type]] internal slot of
key is not "private"
, then throw an InvalidAccessError
.
Let hashAlgorithm be the hash member of normalizedAlgorithm.
Let M be the result of performing the digest operation specified by hashAlgorithm using message.
Let d be the ECDSA private key associated with key.
Let params be the EC domain parameters associated with key.
"P-256"
, "P-384"
or "P-521"
:
Perform the ECDSA signing process, as specified in RFC6090, Section 5.4, with M as the message, using params as the EC domain parameters, and with d as the private key.
Let r and s be the pair of integers resulting from performing the ECDSA signing process.
Let result be a new empty ArrayBuffer associated with the
relevant global object
of this
[HTML].
Let n be the smallest integer such that n * 8 is greater than the logarithm to base 2 of the order of the base point of the elliptic curve identified by params.
Convert r to an octet string of length n and append this sequence of bytes to result.
Convert s to an octet string of length n and append this sequence of bytes to result.
Perform the ECDSA signature steps specified in that specification, passing in M, params and d and resulting in result.
Return a new ArrayBuffer associated with the
relevant global object
of this
[HTML], and containing the
bytes of result.
If the [[type]] internal slot of
key is not "public"
, then throw an InvalidAccessError
.
Let hashAlgorithm be the hash member of normalizedAlgorithm.
Let M be the result of performing the digest operation specified by hashAlgorithm using message.
Let Q be the ECDSA public key associated with key.
Let params be the EC domain parameters associated with key.
"P-256"
, "P-384"
or "P-521"
:
Perform the ECDSA verifying process, as specified in RFC6090, Section 5.3, with M as the received message, signature as the received signature and using params as the EC domain parameters, and Q as the public key.
Perform the ECDSA verification steps specified in that specification passing in M, signature, params and Q and resulting in an indication of whether or not the purported signature is valid.
Let result be a boolean with the value true
if the signature is valid
and the value false
otherwise.
Return result.
If usages contains a value which is not
one of "sign"
or "verify"
,
then throw a
SyntaxError
.
"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 the namedCurve member of normalizedAlgorithm.
Perform the ECDSA key generation steps specified in that specification, passing in normalizedAlgorithm and resulting in an elliptic curve key pair.
If performing the key generation operation results in an error,
then throw an
OperationError
.
Let algorithm be a new EcKeyAlgorithm object.
Set the name attribute of
algorithm to "ECDSA"
.
Set the namedCurve attribute of algorithm to equal the namedCurve member of normalizedAlgorithm.
Let publicKey be a new CryptoKey associated with the
relevant global object
of this
[HTML], and
representing the public key of the generated key pair.
Set the [[type]] internal slot of
publicKey to "public"
Set the [[algorithm]] internal slot of publicKey to algorithm.
Set the [[extractable]] internal slot of publicKey to true.
Set the [[usages]] internal slot of
publicKey to be the usage
intersection of usages and [ "verify" ]
.
Let privateKey be a new CryptoKey associated with the
relevant global object
of this
[HTML], and
representing the private key of the generated key pair.
Set the [[type]] internal slot of
privateKey to "private"
Set the [[algorithm]] internal slot of privateKey to algorithm.
Set the [[extractable]] internal slot of privateKey to extractable.
Set the [[usages]] internal slot of
privateKey to be the usage
intersection of usages and [ "sign" ]
.
Let result be a new CryptoKeyPair dictionary.
Set the publicKey attribute of result to be publicKey.
Set the privateKey attribute of result to be privateKey.
Return the result of converting result to an ECMAScript Object, as defined by [WebIDL].
Let keyData be the key data to be imported.
"spki"
:
If usages contains a value which is not
"verify"
then throw a
SyntaxError
.
Let spki be the result of running the parse a subjectPublicKeyInfo algorithm over keyData
If the algorithm
object identifier field of the
algorithm
AlgorithmIdentifier field of spki is
not equal to the id-ecPublicKey
object identifier defined in RFC 5480,
then throw a
DataError
.
If the parameters
field of the algorithm
AlgorithmIdentifier field of spki is absent,
then throw a
DataError
.
Let params be the parameters
field of the
algorithm
AlgorithmIdentifier field of spki.
If params is not an instance of the
ECParameters
ASN.1 type defined in
RFC 5480 that specifies a
namedCurve
, then throw a DataError
.
Let namedCurve be a string whose initial value is undefined.
secp256r1
object identifier defined in RFC 5480:
Set namedCurve "P-256"
.
secp384r1
object identifier defined in RFC 5480:
Set namedCurve "P-384"
.
secp521r1
object identifier defined in RFC 5480:
Set namedCurve "P-521"
.
Let publicKey be the Elliptic Curve public key identified by
performing the conversion steps defined in Section 2.3.4 of SEC 1 using the the subjectPublicKey
field of spki.
The uncompressed point format MUST be supported.
If the implementation does not support the compressed point format and
a compressed point is provided,
throw a
DataError
.
If a decode error occurs or an identity point is found,
throw a
DataError
.
Let key be a new CryptoKey associated with the
relevant global object
of this
[HTML], and
that represents publicKey.
Perform any key import steps defined by other applicable specifications, passing format, spki and obtaining namedCurve and key.
If an error occured or there are no
applicable
specifications,
throw a
DataError
.
If namedCurve is defined, and not equal to the namedCurve member of
normalizedAlgorithm, throw a DataError
.
If the public key value is not a valid point on the Elliptic Curve
identified by the namedCurve member of
normalizedAlgorithm throw a DataError
.
Set the [[type]] internal slot
of key to "public"
Let algorithm be a new EcKeyAlgorithm.
Set the name attribute of
algorithm to "ECDSA"
.
Set the namedCurve attribute of algorithm to namedCurve.
Set the [[algorithm]] internal slot of key to algorithm.
"pkcs8"
:
If usages contains a value which is not
"sign"
then throw a
SyntaxError
.
Let privateKeyInfo be the result of running the parse a privateKeyInfo algorithm over keyData.
If the algorithm
object identifier field of the
privateKeyAlgorithm
PrivateKeyAlgorithm field of
privateKeyInfo is not equal to the
id-ecPublicKey
object identifier defined in RFC 5480,
then throw a
DataError
.
If the parameters
field of the
privateKeyAlgorithm
PrivateKeyAlgorithmIdentifier field
of privateKeyInfo is not present,
then throw a
DataError
.
Let params be the parameters
field of the
privateKeyAlgorithm
PrivateKeyAlgorithmIdentifier field
of privateKeyInfo.
If params is not an instance of the
ECParameters
ASN.1 type defined in
RFC 5480 that specifies a
namedCurve
, then throw a DataError
.
Let namedCurve be a string whose initial value is undefined.
secp256r1
object identifier defined in RFC 5480:
Set namedCurve "P-256"
.
secp384r1
object identifier defined in RFC 5480:
Set namedCurve "P-384"
.
secp521r1
object identifier defined in RFC 5480:
Set namedCurve "P-521"
.
Let ecPrivateKey be the result of performing the parse an ASN.1 structure
algorithm, with data as the privateKey
field
of privateKeyInfo, structure as the ASN.1
ECPrivateKey
structure specified in Section 3 of RFC 5915, and exactData set to true.
If the parameters
field of ecPrivateKey is
present, and is not an instance of the namedCurve
ASN.1
type defined in RFC 5480, or does not contain
the same object identifier as the parameters
field of the
privateKeyAlgorithm
PrivateKeyAlgorithmIdentifier field
of privateKeyInfo,
then throw a
DataError
.
Let key be a new CryptoKey associated with the
relevant global object
of this
[HTML], and
that represents the Elliptic Curve private key identified by
performing the conversion steps defined in Section 3 of RFC 5915 using ecPrivateKey.
Perform any key import steps defined by other applicable specifications, passing format, privateKeyInfo and obtaining namedCurve and key.
If an error occured or there are no
applicable
specifications,
throw a
DataError
.
If namedCurve is defined, and not equal to the namedCurve member of
normalizedAlgorithm, throw a DataError
.
If the private key value is not a valid point on the Elliptic Curve
identified by the namedCurve member of
normalizedAlgorithm throw a DataError
.
Set the [[type]] internal slot
of key to "private"
Let algorithm be a new EcKeyAlgorithm.
Set the name attribute of
algorithm to "ECDSA"
.
Set the namedCurve attribute of algorithm to namedCurve.
Set the [[algorithm]] internal slot of key to algorithm.
"jwk"
:Let jwk equal keyData.
If the "d"
field is present and usages contains
a value which is not
"sign"
, or,
if the "d"
field is not present and usages contains
a value which is not
"verify"
then throw a
SyntaxError
.
If the "kty"
field of jwk is not
"EC"
,
then throw a
DataError
.
If usages is non-empty and the "use"
field of jwk is present and is
not "sig"
,
then throw a
DataError
.
If the "key_ops"
field of jwk is present, and
is invalid according to the requirements of JSON Web
Key, or it does not contain all of the specified usages
values,
then throw a
DataError
.
If the "ext"
field of jwk is present and
has the value false and extractable is true,
then throw a
DataError
.
Let namedCurve be a string whose value is equal to the
"crv"
field of jwk.
If namedCurve is not equal to the namedCurve member of
normalizedAlgorithm, throw a DataError
.
"P-256"
,
"P-384"
or "P-521"
:
Let algNamedCurve be a string whose initial value is undefined.
"alg"
field is not present:"alg"
field is equal to the string "ES256":
"P-256"
.
"alg"
field is equal to the string "ES384":
"P-384"
.
"alg"
field is equal to the string "ES512":
"P-521"
.
DataError
.
If algNamedCurve is defined, and is not equal to
namedCurve, throw a DataError
.
"d"
field is present:
If jwk does not meet the requirements of Section
6.2.2 of JSON Web Algorithms, then throw a DataError
.
Let key be a new CryptoKey object that represents the Elliptic Curve private key identified by interpreting jwk according to Section 6.2.2 of JSON Web Algorithms.
Set the [[type]]
internal slot of Key to "private"
.
If jwk does not meet the requirements of Section
6.2.1 of JSON Web Algorithms, then throw a DataError
.
Let key be a new CryptoKey object that represents the Elliptic Curve public key identified by interpreting jwk according to Section 6.2.1 of JSON Web Algorithms.
Set the [[type]]
internal slot of Key to "public"
.
Perform any key import steps defined by other applicable specifications, passing format, jwk and obtaining key.
If an error occured or there are no
applicable
specifications,
throw a
DataError
.
If the key value is not a valid point on the Elliptic Curve
identified by the namedCurve member of
normalizedAlgorithm throw a DataError
.
Let algorithm be a new instance of an EcKeyAlgorithm object.
Set the name attribute of
algorithm to "ECDSA"
.
Set the namedCurve attribute of algorithm to namedCurve.
Set the [[algorithm]] internal slot of key to algorithm.
"raw"
:
If the namedCurve
member of normalizedAlgorithm is not a
named curve,
then throw a
DataError
.
If usages contains a value which is not
"verify"
then throw a
SyntaxError
.
"P-256"
,
"P-384"
or "P-521"
:
Let Q be the elliptic curve point on the curve identified by the namedCurve member of normalizedAlgorithm identified by performing the conversion steps defined in Section 2.3.4 of SEC 1 on keyData.
The uncompressed point format MUST be supported.
If the implementation does not support the compressed point format and
a compressed point is provided,
throw a
DataError
.
If a decode error occurs or an identity point is found,
throw a
DataError
.
Let key be a new CryptoKey associated with the
relevant global object
of this
[HTML], and
that represents Q
Perform any key import steps defined by other applicable specifications, passing format, keyData and obtaining key.
If an error occured or there are no
applicable
specifications,
throw a
DataError
.
Let algorithm be a new EcKeyAlgorithm object.
Set the name attribute of
algorithm to "ECDH"
.
Set the namedCurve attribute of algorithm to equal the namedCurve member of normalizedAlgorithm.
Set the [[type]] internal slot
of key to "public"
Set the [[algorithm]] internal slot of key to algorithm.
Return key
Let key be the CryptoKey to be exported.
If the underlying cryptographic key material represented by the [[handle]] internal slot of key
cannot be accessed, then throw an OperationError
.
"spki"
:
If the [[type]] internal slot
of key is not "public"
, then throw an InvalidAccessError
.
Let data be an instance of the subjectPublicKeyInfo
ASN.1 structure defined in RFC 5280
with the following properties:
Set the algorithm field to an
AlgorithmIdentifier
ASN.1 type with the following
properties:
Set the algorithm object identifier to the OID
1.2.840.10045.2.1
.
Set the parameters field to an instance of the
ECParameters
ASN.1 type defined in
RFC 5480 as follows:
"P-256"
,
"P-384"
or "P-521"
:
Let keyData be the octet string that represents the Elliptic Curve public key represented by the [[handle]] internal slot of key according to the encoding rules specified in Section 2.2 of RFC 5480 and using the uncompressed form. and keyData.
"P-256"
:
Set parameters to the namedCurve
choice
with value equal to the object identifier
secp256r1
defined in RFC
5480
"P-384"
:
Set parameters to the namedCurve
choice
with value equal to the object identifier
secp384r1
defined in RFC
5480
"P-521"
:
Set parameters to the namedCurve
choice
with value equal to the object identifier
secp521r1
defined in RFC
5480
Perform any key export steps defined by other applicable specifications, passing format and the namedCurve attribute of the [[algorithm]] internal slot of key and obtaining namedCurveOid and keyData.
Set parameters to the namedCurve
choice
with value equal to the object identifier namedCurveOid.
Set the subjectPublicKey field to keyData.
Let result be a new ArrayBuffer associated with the
relevant global object
of this
[HTML], and containing
data.
"pkcs8"
:
If the [[type]] internal slot
of key is not "private"
, then throw an InvalidAccessError
.
Let data be an instance of the privateKeyInfo
ASN.1 structure defined in RFC 5280
with the following properties:
Set the version field to 0
.
Set the privateKeyAlgorithm field to an
PrivateKeyAlgorithmIdentifier
ASN.1 type with the
following properties:
Set the algorithm object identifier to the OID
1.2.840.10045.2.1
.
Set the parameters field to an instance of the
ECParameters
ASN.1 type defined in
RFC 5480 as follows:
"P-256"
,
"P-384"
or "P-521"
:
Let keyData be the result of DER-encoding
an instance of the ECPrivateKey
structure defined in
Section 3 of RFC 5915 for the Elliptic
Curve private key represented by the [[handle]] internal slot of
key and that conforms to the following:
The parameters field is present, and is equivalent
to the parameters field of the
privateKeyAlgorithm field of this
PrivateKeyInfo
ASN.1 structure.
The publicKey field is present and represents the Elliptic Curve public key associated with the Elliptic Curve private key represented by the [[handle]] internal slot of key.
"P-256"
:
Set parameters to the namedCurve
choice
with value equal to the object identifier
secp256r1
defined in RFC
5480
"P-384"
:
Set parameters to the namedCurve
choice
with value equal to the object identifier
secp384r1
defined in RFC
5480
"P-521"
:
Set parameters to the namedCurve
choice
with value equal to the object identifier
secp521r1
defined in RFC
5480
Perform any key export steps defined by other applicable specifications, passing format and the namedCurve attribute of the [[algorithm]] internal slot of key and obtaining namedCurveOid and keyData.
Set parameters to the namedCurve
choice
with value equal to the object identifier namedCurveOid.
Set the privateKey field to keyData.
Let result be a new ArrayBuffer associated with the
relevant global object
of this
[HTML], and containing
data.
"jwk"
:Let jwk be a new JsonWebKey dictionary.
Set the kty
attribute of jwk to
"EC"
.
"P-256"
, "P-384"
or
"P-521"
:
"P-256"
:
crv
attribute of jwk to
"P-256"
"P-384"
:
crv
attribute of jwk to
"P-384"
"P-521"
:
crv
attribute of jwk to
"P-521"
Set the x
attribute of jwk according to the
definition in Section 6.2.1.2 of JSON Web
Algorithms.
Set the y
attribute of jwk according to the
definition in Section 6.2.1.3 of JSON Web
Algorithms.
"private"
Set the d
attribute of jwk according to
the definition in Section 6.2.2.1 of JSON Web
Algorithms.
Perform any key export steps defined by other applicable specifications, passing format and the namedCurve attribute of the [[algorithm]] internal slot of key and obtaining namedCurve and a new value of jwk.
Set the crv
attribute of jwk to
namedCurve.
Set the key_ops
attribute of jwk to the usages attribute of key.
Set the ext
attribute of jwk to the [[extractable]] internal slot
of key.
Let result be the result of converting jwk to an ECMAScript Object, as defined by [WebIDL].
"raw"
:
If the [[type]] internal slot
of key is not "public"
, then throw an InvalidAccessError
.
"P-256"
, "P-384"
or "P-521"
:
Let data be an octet string representing the Elliptic Curve point Q represented by [[handle]] internal slot of key according to SEC 1 2.3.3 using the uncompressed format.
Perform any key export steps defined by other applicable specifications, passing format and the namedCurve attribute of the [[algorithm]] internal slot of key and obtaining namedCurve and data.
Let result be a new ArrayBuffer associated with the
relevant global object
of this
[HTML], and containing
data.
Return result.
This section is non-normative.
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 define the curve name, ECDH generation steps, ECDH derivation steps, ECDH key import steps and ECDH key export steps.
The recognized algorithm name for
this algorithm is "ECDH"
.
Operation | Parameters | Result |
---|---|---|
generateKey | EcKeyGenParams | CryptoKeyPair |
deriveBits | EcdhKeyDeriveParams | Octet string |
importKey | EcKeyImportParams | CryptoKey |
exportKey | None | object |
If usages contains an entry which is not
"deriveKey"
or "deriveBits"
then throw a
SyntaxError
.
"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 the namedCurve member of normalizedAlgorithm.
Perform the ECDH key generation steps specified in that specification, passing in normalizedAlgorithm and resulting in an elliptic curve key pair.
If performing the operation results in an error,
then throw a
OperationError
.
Let algorithm be a new EcKeyAlgorithm object.
Set the name member of
algorithm to "ECDH"
.
Set the namedCurve attribute of algorithm to equal the namedCurve member of normalizedAlgorithm.
Let publicKey be a new CryptoKey associated with the
relevant global object
of this
[HTML], and
representing the public key of the generated key pair.
Set the [[type]] internal slot of
publicKey to "public"
Set the [[algorithm]] internal slot of publicKey to algorithm.
Set the [[extractable]] internal slot of publicKey to true.
Set the [[usages]] internal slot of publicKey to be the empty list.
Let privateKey be a new CryptoKey associated with the
relevant global object
of this
[HTML], and
representing the private key of the generated key pair.
Set the [[type]] internal slot of
privateKey to "private"
Set the [[algorithm]] internal slot of privateKey to algorithm.
Set the [[extractable]] internal slot of privateKey to extractable.
Set the [[usages]] internal slot of
privateKey to be the
usage intersection of
usages and [ "deriveKey", "deriveBits" ]
.
Let result be a new CryptoKeyPair dictionary.
Set the publicKey attribute of result to be publicKey.
Set the privateKey attribute of result to be privateKey.
Return the result of converting result to an ECMAScript Object, as defined by [WebIDL].
If the [[type]] internal slot of
key is not "private"
, then throw an InvalidAccessError
.
Let publicKey be the public member of normalizedAlgorithm.
If the [[type]] internal slot of
publicKey is not "public"
, then throw an InvalidAccessError
.
If the name attribute of
the [[algorithm]] internal slot of
publicKey is not equal to the name property of the [[algorithm]] internal slot of
key, then throw an InvalidAccessError
.
If the namedCurve attribute of
the [[algorithm]] internal slot of
publicKey is not equal to the namedCurve property of the [[algorithm]] internal slot of
key, then throw an InvalidAccessError
.
"P-256"
, "P-384"
or "P-521"
:
Perform the ECDH primitive specified in RFC6090 Section 4 with key as the EC private key d and the EC public key represented by the [[handle]] internal slot of publicKey as the EC public key.
Let secret be 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.
Perform the ECDH key derivation steps specified in that specification, passing in key and publicKey and resulting in secret.
If performing the operation results in an error,
then throw a
OperationError
.
OperationError
.
Let keyData be the key data to be imported.
"spki"
:
If usages is not empty
then throw a
SyntaxError
.
Let spki be the result of running the parse a subjectPublicKeyInfo algorithm over keyData
If the algorithm
object identifier field of the
algorithm
AlgorithmIdentifier field of spki is
not equal to the id-ecPublicKey
or id-ecDH
object identifiers defined in RFC 5480,
then throw a
DataError
.
If the parameters
field of the algorithm
AlgorithmIdentifier field of spki is absent,
then throw a
DataError
.
Let params be the parameters
field of the
algorithm
AlgorithmIdentifier field of spki.
If params is not an instance of the
ECParameters
ASN.1 type defined in
RFC 5480 that specifies a
namedCurve
, then throw a DataError
.
Let namedCurve be a string whose initial value is undefined.
secp256r1
object identifier defined in RFC 5480:
Set namedCurve "P-256"
.
secp384r1
object identifier defined in RFC 5480:
Set namedCurve "P-384"
.
secp521r1
object identifier defined in RFC 5480:
Set namedCurve "P-521"
.
Let publicKey be the Elliptic Curve public key identified by
performing the conversion steps defined in Section 2.3.4 of SEC 1 to the subjectPublicKey
field of
spki.
The uncompressed point format MUST be supported.
If the implementation does not support the compressed point format and
a compressed point is provided,
throw a
DataError
.
If a decode error occurs or an identity point is found,
throw a
DataError
.
Let key be a new CryptoKey associated with the
relevant global object
of this
[HTML], and
that represents publicKey.
Perform any key import steps defined by other applicable specifications, passing format, spki and obtaining namedCurve and key.
If an error occured or there are no
applicable
specifications,
throw a
DataError
.
If namedCurve is defined, and not equal to the namedCurve member of
normalizedAlgorithm, throw a DataError
.
If the key value is not a valid point on the Elliptic Curve
identified by the namedCurve member of
normalizedAlgorithm throw a DataError
.
Set the [[type]] internal slot
of key to "public"
Let algorithm be a new EcKeyAlgorithm.
Set the name attribute of
algorithm to "ECDH"
.
Set the namedCurve attribute of algorithm to namedCurve.
Set the [[algorithm]] internal slot of key to algorithm.
"pkcs8"
:
If usages contains an entry which is not
"deriveKey"
or "deriveBits"
then throw a
SyntaxError
.
Let privateKeyInfo be the result of running the parse a privateKeyInfo algorithm over keyData.
If the algorithm
object identifier field of the
privateKeyAlgorithm
PrivateKeyAlgorithm field of
privateKeyInfo is not equal to the
id-ecPublicKey
or id-ecDH
object identifiers
defined in RFC 5480,
throw a
DataError
.
If the parameters
field of the
privateKeyAlgorithm
PrivateKeyAlgorithmIdentifier field
of privateKeyInfo is not present,
throw a
DataError
.
Let params be the parameters
field of the
privateKeyAlgorithm
PrivateKeyAlgorithmIdentifier field
of privateKeyInfo.
If params is not an instance of the
ECParameters
ASN.1 type defined in
RFC 5480 that specifies a
namedCurve
, then throw a DataError
.
Let namedCurve be a string whose initial value is undefined.
secp256r1
object identifier defined in RFC 5480:
Set namedCurve to "P-256"
.
secp384r1
object identifier defined in RFC 5480:
Set namedCurve to "P-384"
.
secp521r1
object identifier defined in RFC 5480:
Set namedCurve to "P-521"
.
Let ecPrivateKey be the result of performing the
parse an ASN.1 structure
algorithm, with data as the privateKey
field
of privateKeyInfo, structure as the ASN.1
ECPrivateKey
structure specified in Section 3 of
RFC 5915, and exactData set to true.
If the parameters
field of ecPrivateKey is
present, and is not an instance of the namedCurve
ASN.1
type defined in RFC 5480, or does not contain
the same object identifier as the parameters
field of the
privateKeyAlgorithm
PrivateKeyAlgorithmIdentifier field
of privateKeyInfo,
throw a
DataError
.
Let key be a new CryptoKey associated with the
relevant global object
of this
[HTML], and
that represents the Elliptic Curve private key identified by
performing the conversion steps defined in Section 3 of RFC 5915 using ecPrivateKey.
Perform any key import steps defined by other applicable specifications, passing format, privateKeyInfo and obtaining namedCurve and key.
If an error occured or there are no
applicable
specifications,
throw a
DataError
.
If namedCurve is defined, and not equal to the namedCurve member of
normalizedAlgorithm, throw a DataError
.
If the key value is not a valid point on the Elliptic Curve
identified by the namedCurve member of
normalizedAlgorithm throw a DataError
.
Set the [[type]] internal slot
of key to "private"
.
Let algorithm be a new EcKeyAlgorithm.
Set the name attribute of
algorithm to "ECDH"
.
Set the namedCurve attribute of algorithm to namedCurve.
Set the [[algorithm]] internal slot of key to algorithm.
"jwk"
:Let jwk equal keyData.
If the "d"
field is present and if usages
contains an entry which is not
"deriveKey"
or "deriveBits"
then throw a
SyntaxError
.
If the "d"
field is not present and if usages is not
empty
then throw a
SyntaxError
.
If the "kty"
field of jwk is
not "EC"
,
then throw a
DataError
.
If usages is non-empty and the "use"
field of jwk is present
and is not equal to "enc"
then throw a
DataError
.
If the "key_ops"
field of jwk is present, and
is invalid according to the requirements of JSON Web
Key, or it does not contain all of the specified usages
values, then throw a DataError
.
If the "ext"
field of jwk is present and
has the value false and extractable is true,
then throw a
DataError
.
Let namedCurve be a string whose value is equal to the
"crv"
field of jwk.
If namedCurve is not equal to the namedCurve member of
normalizedAlgorithm, throw a DataError
.
"P-256"
,
"P-384"
or "P-521"
:
"d"
field is present:
If jwk does not meet the requirements of Section
6.2.2 of JSON Web Algorithms, then throw a DataError
.
Let key be a new CryptoKey object that represents the Elliptic Curve private key identified by interpreting jwk according to Section 6.2.2 of JSON Web Algorithms.
Set the [[type]]
internal slot of Key to "private"
.
If jwk does not meet the requirements of Section
6.2.1 of JSON Web Algorithms, then throw a DataError
.
Let key be a new CryptoKey object that represents the Elliptic Curve public key identified by interpreting jwk according to Section 6.2.1 of JSON Web Algorithms.
Set the [[type]]
internal slot of Key to "public"
.
Perform any key import steps defined by other applicable specifications, passing format, jwk and obtaining key.
If an error occured or there are no
applicable
specifications,
throw a
DataError
.
If the key value is not a valid point on the Elliptic Curve
identified by the namedCurve member of
normalizedAlgorithm throw a DataError
.
Let algorithm be a new instance of an EcKeyAlgorithm object.
Set the name attribute of
algorithm to "ECDH"
.
Set the namedCurve attribute of algorithm to namedCurve.
Set the [[algorithm]] internal slot of key to algorithm.
"raw"
:
If the namedCurve
member of normalizedAlgorithm is not a
named curve,
then throw a
DataError
.
If usages is not the empty list,
then throw a
SyntaxError
.
"P-256"
,
"P-384"
or "P-521"
:
Let Q be the Elliptic Curve public key on the curve identified by the namedCurve member of normalizedAlgorithm identified by performing the conversion steps defined in Section 2.3.4 of SEC 1 to keyData.
The uncompressed point format MUST be supported.
If the implementation does not support the compressed point format and
a compressed point is provided,
throw a
DataError
.
If a decode error occurs or an identity point is found,
throw a
DataError
.
Let key be a new CryptoKey associated with the
relevant global object
of this
[HTML], and
that represents Q.
Perform any key import steps defined by other applicable specifications, passing format, keyData and obtaining key.
If an error occured or there are no
applicable
specifications,
throw a
DataError
.
Let algorithm be a new EcKeyAlgorithm object.
Set the name attribute of
algorithm to "ECDH"
.
Set the namedCurve attribute of algorithm to equal the namedCurve member of normalizedAlgorithm.
Set the [[type]] internal slot
of key to "public"
Set the [[algorithm]] internal slot of key to algorithm.
Return key
Let key be the CryptoKey to be exported.
If the underlying cryptographic key material represented by the [[handle]] internal slot of key
cannot be accessed, then throw an OperationError
.
"spki"
:
If the [[type]] internal slot
of key is not "public"
, then throw an InvalidAccessError
.
Let data be an instance of the subjectPublicKeyInfo
ASN.1 structure defined in RFC 5280
with the following properties:
Set the algorithm field to an
AlgorithmIdentifier
ASN.1 type with the following
properties:
Set the algorithm object identifier to the OID
1.3.132.1.12
.
Set the parameters field to an instance of the
ECParameters
ASN.1 type defined in
RFC 5480 as follows:
"P-256"
,
"P-384"
or "P-521"
:
Let keyData be the octet string that represents the Elliptic Curve public key represented by the [[handle]] internal slot of key according to the encoding rules specified in Section 2.3.3 of SEC 1 and using the uncompressed form.
"P-256"
:
Set parameters to the namedCurve choice
with value equal to the object identifier
secp256r1
defined in RFC
5480
"P-384"
:
Set parameters to the namedCurve choice
with value equal to the object identifier
secp384r1
defined in RFC
5480
"P-521"
:
Set parameters to the namedCurve choice
with value equal to the object identifier
secp521r1
defined in RFC
5480
Perform any key export steps defined by other applicable specifications, passing format and the namedCurve attribute of the [[algorithm]] internal slot of key and obtaining namedCurveOid and keyData.
Set parameters to the namedCurve
choice
with value equal to the object identifier namedCurveOid.
Set the subjectPublicKey field to keyData
"pkcs8"
:
If the [[type]] internal slot
of key is not "private"
, then throw an InvalidAccessError
.
Let data be an instance of the privateKeyInfo
ASN.1 structure defined in RFC 5280
with the following properties:
Set the version field to 0
.
Set the privateKeyAlgorithm field to an
PrivateKeyAlgorithmIdentifier
ASN.1 type with the
following properties:
Set the algorithm object identifier to the OID
1.3.132.1.12
.
Set the parameters field to an instance of the
ECParameters
ASN.1 type defined in
RFC 5480 as follows:
"P-256"
,
"P-384"
or "P-521"
:
Let keyData be the result of DER-encoding
an instance of the ECPrivateKey
structure defined in
Section 3 of RFC 5915 for the Elliptic
Curve private key represented by the [[handle]] internal slot of
key and that conforms to the following:
The parameters field is present, and is equivalent
to the parameters field of the
privateKeyAlgorithm field of this
PrivateKeyInfo
ASN.1 structure.
The publicKey field is present and represents the Elliptic Curve public key associated with the Elliptic Curve private key represented by the [[handle]] internal slot of key.
"P-256"
:
Set parameters to the namedCurve choice
with value equal to the object identifier
secp256r1
defined in RFC
5480
"P-384"
:
Set parameters to the namedCurve choice
with value equal to the object identifier
secp384r1
defined in RFC
5480
"P-521"
:
Set parameters to the namedCurve choice
with value equal to the object identifier
secp521r1
defined in RFC
5480
Perform any key export steps defined by other applicable specifications, passing format and the namedCurve attribute of the [[algorithm]] internal slot of key and obtaining namedCurveOid and keyData.
Set parameters to the namedCurve
choice
with value equal to the object identifier namedCurveOid.
Set the privateKey field to keyData.
"jwk"
:Let jwk be a new JsonWebKey dictionary.
Set the kty
attribute of jwk to
"EC"
.
"P-256"
, "P-384"
or "P-521"
:
"P-256"
:
crv
attribute of jwk to
"P-256"
"P-384"
:
crv
attribute of jwk to
"P-384"
"P-521"
:
crv
attribute of jwk to
"P-521"
Set the x
attribute of jwk according to the
definition in Section 6.2.1.2 of JSON Web
Algorithms.
Set the y
attribute of jwk according to the
definition in Section 6.2.1.3 of JSON Web
Algorithms.
"private"
Set the d
attribute of jwk according to the
definition in Section 6.2.2.1 of JSON Web
Algorithms.
Perform any key export steps defined by other applicable specifications, passing format and the namedCurve attribute of the [[algorithm]] internal slot of key and obtaining namedCurve and a new value of jwk.
Set the crv
attribute of jwk to
namedCurve.
Set the key_ops
attribute of jwk to the
usages attribute of key.
Set the ext
attribute of jwk to the [[extractable]] internal slot
of key.
Let result be the result of converting jwk to an ECMAScript Object, as defined by [WebIDL].
"raw"
:
If the [[type]] internal slot
of key is not "public"
, then throw an InvalidAccessError
.
"P-256"
, "P-384"
or "P-521"
:
Let data be the octet string that represents the Elliptic Curve public key represented by the [[handle]] internal slot of key according to the encoding rules specified in Section 2.3.3 of SEC 1 and using the uncompressed form.
Perform any key export steps defined by other applicable specifications, passing format and the namedCurve attribute of the [[algorithm]] internal slot of key and obtaining namedCurve and data.
Let result be a new ArrayBuffer associated with the
relevant global object
of this
[HTML], and containing
data.
Return result.
This section is non-normative.
The "AES-CTR"
algorithm identifier is used to perform
encryption and decryption using AES in Counter mode,
as described in [NIST SP800-38A].
The recognized algorithm name for
this algorithm is "AES-CTR"
.
Operation | Parameters | Result |
---|---|---|
encrypt | AesCtrParams | ArrayBuffer |
decrypt | AesCtrParams | ArrayBuffer |
generateKey | AesKeyGenParams | CryptoKey |
importKey | None | CryptoKey |
exportKey | None | object |
get key length | AesDerivedKeyParams | Integer |
dictionary AesCtrParams : Algorithm {
// The initial value of the counter block. counter MUST 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.
required BufferSource counter;
// The length, in bits, of the rightmost part of the counter block
// that is incremented.
[EnforceRange] required octet length;
};
dictionary AesKeyAlgorithm : KeyAlgorithm {
// The length, in bits, of the key.
required unsigned short length;
};
dictionary AesKeyGenParams : Algorithm {
// The length, in bits, of the key.
[EnforceRange] required unsigned short length;
};
dictionary AesDerivedKeyParams : Algorithm {
// The length, in bits, of the key.
[EnforceRange] required unsigned short length;
};
If the counter member of
normalizedAlgorithm does not have length 16
bytes,
then throw an
OperationError
.
If the length member of
normalizedAlgorithm is zero or is greater
than 128,
then throw an
OperationError
.
Let ciphertext be the result of performing the CTR Encryption operation described in Section 6.5 of [NIST SP800-38A] using AES as the block cipher, the contents of the counter member of normalizedAlgorithm as the initial value of the counter block, the length member of normalizedAlgorithm as the input parameter m to the standard counter block incrementing function defined in Appendix B.1 of [NIST SP800-38A] and the contents of plaintext as the input plaintext.
Return a new ArrayBuffer associated with the
relevant global object
of this
[HTML], and
containing ciphertext.
If the counter member of
normalizedAlgorithm does not have length 16
bytes,
then throw an
OperationError
.
If the length member of
normalizedAlgorithm is zero or is greater
than 128,
then throw an
OperationError
.
Let plaintext be the result of performing the CTR Decryption operation described in Section 6.5 of [NIST SP800-38A] using AES as the block cipher, the contents of the counter member of normalizedAlgorithm as the initial value of the counter block, the length member of normalizedAlgorithm as the input parameter m to the standard counter block incrementing function defined in Appendix B.1 of [NIST SP800-38A] and the contents of ciphertext as the input ciphertext.
Return a new ArrayBuffer associated with the
relevant global object
of this
[HTML], and
containing plaintext.
If usages contains any entry which is not
one of "encrypt"
, "decrypt"
,
"wrapKey"
or "unwrapKey"
,
then throw a
SyntaxError
.
If the length member of
normalizedAlgorithm is not equal to one of
128, 192 or 256,
then throw an
OperationError
.
Generate an AES key of length equal to the length member of normalizedAlgorithm.
If the key generation step fails,
then throw an
OperationError
.
Let key be a new CryptoKey object representing the generated AES key.
Let algorithm be a new AesKeyAlgorithm.
Set the name attribute of
algorithm to "AES-CTR"
.
Set the length attribute of algorithm to equal the length member of normalizedAlgorithm.
Set the [[algorithm]] internal slot of key to algorithm.
Set the [[extractable]] internal slot of key to be extractable.
Set the [[usages]] internal slot of key to be usages.
Return key.
If usages contains an entry which is not
one of "encrypt"
, "decrypt"
,
"wrapKey"
or "unwrapKey"
,
then throw a
SyntaxError
.
"raw"
:Let data be the octet string contained in keyData.
If the length in bits of data is not 128, 192 or 256
then throw a
DataError
.
"jwk"
:Let jwk equal keyData.
If the "kty"
field of jwk is not
"oct"
,
then throw a
DataError
.
If jwk does not meet the requirements of
Section 6.4 of JSON Web Algorithms,
then throw a
DataError
.
Let data be the octet string obtained by decoding the
"k"
field of jwk.
"alg"
field of jwk is present, and is
not "A128CTR"
, then throw a DataError
.
"alg"
field of jwk is present, and is
not "A192CTR"
, then throw a DataError
.
"alg"
field of jwk is present, and is
not "A256CTR"
, then throw a DataError
.
DataError
.
If usages is non-empty and the "use"
field of jwk is present and is
not "enc"
,
then throw a
DataError
.
If the "key_ops"
field of jwk is present, and
is invalid according to the requirements of
JSON Web Key or
does not contain all of the specified usages values,
then throw a
DataError
.
If the "ext"
field of jwk is present and
has the value false and extractable is true,
then throw a
DataError
.
NotSupportedError
.
Let key be a new CryptoKey
object representing an AES key with
value data.
Let algorithm be a new AesKeyAlgorithm.
Set the name attribute of
algorithm to "AES-CTR"
.
Set the length attribute of algorithm to the length, in bits, of data.
Set the [[algorithm]] internal slot of key to algorithm.
Return key.
If the underlying cryptographic key material represented by the [[handle]] internal slot of key
cannot be accessed, then throw an OperationError
.
"raw"
:Let data be the raw octets of the key represented by [[handle]] internal slot of key.
Let result be a new ArrayBuffer associated with the
relevant global object
of this
[HTML], and containing
data.
"jwk"
:Let jwk be a new JsonWebKey dictionary.
Set the kty
attribute of jwk to the
string "oct"
.
Set the k
attribute of jwk to be a string
containing the raw octets of the key represented by [[handle]] internal slot of
key, encoded according to Section 6.4 of JSON Web Algorithms.
Set the key_ops
attribute of jwk to equal the
[[usages]] internal slot of
key.
Set the ext
attribute of jwk to equal the [[extractable]] internal slot
of key.
Let result be the result of converting jwk to an ECMAScript Object, as defined by [WebIDL].
Return result.
If the length member of
normalizedDerivedKeyAlgorithm is not 128, 192 or 256,
then throw a
OperationError
.
Return the length member of normalizedDerivedKeyAlgorithm.
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].
The recognized algorithm name for
this algorithm is "AES-CBC"
.
Operation | Parameters | Result |
---|---|---|
encrypt | AesCbcParams | ArrayBuffer |
decrypt | AesCbcParams | ArrayBuffer |
generateKey | AesKeyGenParams | CryptoKey |
importKey | None | CryptoKey |
exportKey | None | object |
get key length | AesDerivedKeyParams | Integer |
dictionary AesCbcParams : Algorithm {
// The initialization vector. MUST be 16 bytes.
required BufferSource iv;
};
If the iv member of
normalizedAlgorithm does not have length 16
bytes,
then throw an
OperationError
.
Let paddedPlaintext be the result of adding padding octets to the contents of ciphertext according to the procedure defined in Section 10.3 of [RFC2315], step 2, with a value of k of 16.
Let ciphertext be the result of performing the CBC Encryption operation described in Section 6.2 of [NIST SP800-38A] using AES as the block cipher, the contents of the iv member of normalizedAlgorithm as the IV input parameter and paddedPlaintext as the input plaintext.
Return a new ArrayBuffer associated with the
relevant global object
of this
[HTML], and
containing ciphertext.
If the iv member of
normalizedAlgorithm does not have length 16
bytes,
then throw an
OperationError
.
Let paddedPlaintext be the result of performing the CBC Decryption operation described in Section 6.2 of [NIST SP800-38A] using AES as the block cipher, the contents of the iv member of normalizedAlgorithm as the IV input parameter and the contents of ciphertext as the input ciphertext.
Let p be the value of the last octet of paddedPlaintext.
If p is zero or greater than 16, or if any of the last p
octets of paddedPlaintext have a value which is not p,
then throw an
OperationError
.
Let plaintext be the result of removing p octets from the end of paddedPlaintext.
Return a new ArrayBuffer associated with the
relevant global object
of this
[HTML], and
containing plaintext.
If usages contains any entry which is not
one of "encrypt"
, "decrypt"
,
"wrapKey"
or "unwrapKey"
,
then throw a
SyntaxError
.
If the length member of
normalizedAlgorithm is not equal to one of
128, 192 or 256,
then throw an
OperationError
.
Generate an AES key of length equal to the length member of normalizedAlgorithm.
If the key generation step fails,
then throw an
OperationError
.
Let key be a new CryptoKey object representing the generated AES key.
Let algorithm be a new AesKeyAlgorithm.
Set the name attribute of
algorithm to "AES-CBC"
.
Set the length attribute of algorithm to equal the length member of normalizedAlgorithm.
Set the [[algorithm]] internal slot of key to algorithm.
Set the [[extractable]] internal slot of key to be extractable.
Set the [[usages]] internal slot of key to be usages.
Return key.
If usages contains an entry which is not
one of "encrypt"
, "decrypt"
,
"wrapKey"
or "unwrapKey"
,
then throw a
SyntaxError
.
"raw"
:Let data be the octet string contained in keyData.
If the length in bits of data is not 128, 192 or 256
then throw a
DataError
.
"jwk"
:Let jwk equal keyData.
If the "kty"
field of jwk is not
"oct"
,
then throw a
DataError
.
If jwk does not meet the requirements of
Section 6.4 of JSON Web Algorithms,
then throw a
DataError
.
Let data be the octet string obtained by decoding the
"k"
field of jwk.
"alg"
field of jwk is present, and is
not "A128CBC"
,
then throw a
DataError
."alg"
field of jwk is present, and is
not "A192CBC"
,
then throw a
DataError
."alg"
field of jwk is present, and is
not "A256CBC"
,
then throw a
DataError
.DataError
.
If usages is non-empty and the "use"
field of jwk is present and is
not "enc"
,
then throw a
DataError
.
If the "key_ops"
field of jwk is present, and
is invalid according to the requirements of
JSON Web Key or
does not contain all of the specified usages values,
then throw a
DataError
.
If the "ext"
field of jwk is present and
has the value false and extractable is true,
then throw a
DataError
.
NotSupportedError
Let key be a new CryptoKey
object representing an AES key with value data.
Let algorithm be a new AesKeyAlgorithm.
Set the name attribute of
algorithm to "AES-CBC"
.
Set the length attribute of algorithm to the length, in bits, of data.
Set the [[algorithm]] internal slot of key to algorithm.
Return key.
If the underlying cryptographic key material represented by the [[handle]] internal slot of key
cannot be accessed, then throw an OperationError
.
"raw"
:Let data be the raw octets of the key represented by [[handle]] internal slot of key.
Let result be a new ArrayBuffer associated with the
relevant global object
of this
[HTML], and containing
data.
"jwk"
:Let jwk equal keyData.
Set the kty
attribute of jwk to the
string "oct"
.
Set the k
attribute of jwk to be a string
containing the raw octets of the key represented by [[handle]] internal slot of
key, encoded according to Section 6.4 of JSON Web Algorithms.
Set the key_ops
attribute of jwk to equal the
usages attribute of key.
Set the ext
attribute of jwk to equal the [[extractable]] internal slot
of key.
Let result be the result of converting jwk to an ECMAScript Object, as defined by [WebIDL].
Return result.
If the length member of
normalizedDerivedKeyAlgorithm is not 128, 192 or 256,
then throw an
OperationError
.
Return the length member of normalizedDerivedKeyAlgorithm.
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 SP 800-38D].
The recognized algorithm name for
this algorithm is "AES-GCM"
.
Operation | Parameters | Result |
---|---|---|
encrypt | AesGcmParams | ArrayBuffer |
decrypt | AesGcmParams | ArrayBuffer |
generateKey | AesKeyGenParams | CryptoKey |
importKey | None | CryptoKey |
exportKey | None | object |
get key length | AesDerivedKeyParams | Integer |
dictionary AesGcmParams : Algorithm {
// The initialization vector to use. May be up to 2^64-1 bytes long.
required BufferSource iv;
// The additional authentication data to include.
BufferSource additionalData;
// The desired length of the authentication tag. May be 0 - 128.
[EnforceRange] octet tagLength;
};
If plaintext has a length greater than 2^39 - 256
bytes,
then throw an
OperationError
.
If the iv member of
normalizedAlgorithm has a length greater than 2^64 - 1
bytes,
then throw an
OperationError
.
If the additionalData member
of normalizedAlgorithm is present and has a length
greater than 2^64 - 1 bytes,
then throw an
OperationError
.
OperationError
.
Let additionalData be the contents of the additionalData member of normalizedAlgorithm if present or the empty octet string otherwise.
Let C and T 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, the contents of the iv member of normalizedAlgorithm as the IV input parameter, the contents of additionalData as the A input parameter, tagLength as the t pre-requisite and the contents of plaintext as the input plaintext.
Let ciphertext be equal to C | T, where '|' denotes concatenation.
Return a new ArrayBuffer associated with the
relevant global object
of this
[HTML], and
containing ciphertext.
OperationError
.
If plaintext has a length less than tagLength bits,
then throw an
OperationError
.
If the iv member of
normalizedAlgorithm has a length greater than 2^64 - 1
bytes,
then throw an
OperationError
.
If the additionalData member
of normalizedAlgorithm is present and has a length
greater than 2^64 - 1
bytes,
then throw an
OperationError
.
Let tag be the last tagLength bits of ciphertext.
Let actualCiphertext be the result of removing the last tagLength bits from ciphertext.
Let additionalData be the contents of the additionalData member of normalizedAlgorithm if present or the empty octet string otherwise.
Perform the Authenticated Decryption Function described in Section 7.2 of [NIST SP800-38D] using AES as the block cipher, the contents of the iv member of normalizedAlgorithm as the IV input parameter, the contents of additionalData as the A input parameter, tagLength as the t pre-requisite, the contents of actualCiphertext as the input ciphertext, C and the contents of tag as the authentication tag, T.
OperationError
Return a new ArrayBuffer associated with the
relevant global object
of this
[HTML], and
containing plaintext.
If usages contains any entry which is not
one of "encrypt"
, "decrypt"
,
"wrapKey"
or "unwrapKey"
,
then throw a
SyntaxError
.
If the length member of
normalizedAlgorithm is not equal to one of
128, 192 or 256,
then throw an
OperationError
.
Generate an AES key of length equal to the length member of normalizedAlgorithm.
If the key generation step fails,
then throw an
OperationError
.
Let key be a new CryptoKey object representing the generated AES key.
Let algorithm be a new AesKeyAlgorithm.
Set the name attribute of
algorithm to "AES-GCM"
.
Set the length attribute of algorithm to equal the length member of normalizedAlgorithm.
Set the [[algorithm]] internal slot of key to algorithm.
Set the [[extractable]] internal slot of key to be extractable.
Set the [[usages]] internal slot of key to be usages.
Return key.
If usages contains an entry which is not
one of "encrypt"
, "decrypt"
,
"wrapKey"
or "unwrapKey"
,
then throw a
SyntaxError
.
"raw"
:Let data be the octet string contained in keyData.
If the length in bits of data is not 128, 192 or 256
then throw a
DataError
.
"jwk"
:Let jwk equal keyData.
If the "kty"
field of jwk is not
"oct"
,
then throw a
DataError
.
If jwk does not meet the requirements of
Section 6.4 of JSON Web Algorithms,
then throw a
DataError
.
Let data be the octet string obtained by decoding the
"k"
field of jwk.
"alg"
field of jwk is present, and is
not "A128GCM"
,
then throw a
DataError
."alg"
field of jwk is present, and is
not "A192GCM"
,
then throw a
DataError
."alg"
field of jwk is present, and is
not "A256GCM"
,
then throw a
DataError
.DataError
.
If usages is non-empty and the "use"
field of jwk is present and is
not "enc"
,
then throw a
DataError
.
If the "key_ops"
field of jwk is present, and
is invalid according to the requirements of
JSON Web Key or
does not contain all of the specified usages values,
then throw a
DataError
.
If the "ext"
field of jwk is present and
has the value false and extractable is true,
then throw a
DataError
.
NotSupportedError
.
Let key be a new CryptoKey
object representing an AES key with value data.
Let algorithm be a new AesKeyAlgorithm.
Set the name attribute of
algorithm to "AES-GCM"
.
Set the length attribute of algorithm to the length, in bits, of data.
Set the [[algorithm]] internal slot of key to algorithm.
Return key.
If the underlying cryptographic key material represented by the [[handle]] internal slot of key
cannot be accessed, then throw an OperationError
.
"raw"
:Let data be the raw octets of the key represented by [[handle]] internal slot of key.
Let result be a new ArrayBuffer associated with the
relevant global object
of this
[HTML], and containing
data.
"jwk"
:Let jwk be a new JsonWebKey dictionary.
Set the kty
attribute of jwk to the
string "oct"
.
Set the k
attribute of jwk to be a string
containing the raw octets of the key represented by [[handle]] internal slot of
key, encoded according to Section 6.4 of JSON Web Algorithms.
Set the key_ops
attribute of jwk to equal the
usages attribute of
key.
Set the ext
attribute of jwk to equal the [[extractable]] internal slot
of key.
Let result be the result of converting jwk to an ECMAScript Object, as defined by [WebIDL].
Return result.
If the length member of
normalizedDerivedKeyAlgorithm is not 128, 192 or 256, then throw an OperationError
.
Return the length member of normalizedDerivedKeyAlgorithm.
This section is non-normative.
The "AES-KW"
algorithm identifier is used to perform
key wrapping using AES, as
described in [RFC3394].
The recognized algorithm name for
this algorithm is "AES-KW"
.
Operation | Parameters | Result |
---|---|---|
wrapKey | None | ArrayBuffer |
unwrapKey | None | ArrayBuffer |
generateKey | AesKeyGenParams | CryptoKey |
importKey | None | CryptoKey |
exportKey | None | object |
get key length | AesDerivedKeyParams | Integer |
If plaintext is not a multiple of 64 bits in length,
then throw an
OperationError
.
Let ciphertext be the result of performing the Key Wrap operation described in Section 2.2.1 of [RFC3394] with plaintext as the plaintext to be wrapped and using the default Initial Value defined in Section 2.2.3.1 of the same document.
Return ciphertext.
Let plaintext be the result of performing the Key Unwrap operation described in Section 2.2.2 of [RFC3394] with ciphertext as the input ciphertext and using the default Initial Value defined in Section 2.2.3.1 of the same document.
If the Key Unwrap operation returns an error,
then throw an
OperationError
.
Return plaintext.
If usages contains any entry which is not one of
"wrapKey"
or "unwrapKey"
, then throw a SyntaxError
.
If the length property of
normalizedAlgorithm is not equal to one of 128, 192 or 256, then throw an OperationError
.
If the key generation step fails,
then throw an
OperationError
.
Let key be a new CryptoKey object representing the generated AES key.
Let algorithm be a new AesKeyAlgorithm.
Set the name attribute of
algorithm to "AES-KW"
.
Set the length attribute of algorithm to equal the length property of normalizedAlgorithm.
Set the [[algorithm]] internal slot of key to algorithm.
Set the [[extractable]] internal slot of key to be extractable.
Set the [[usages]] internal slot of key to be usages.
Return key.
If usages contains an entry which is not
one of "wrapKey"
or "unwrapKey"
,
then throw a
SyntaxError
.
"raw"
:Let data be the octet string contained in keyData.
If the length in bits of data is not 128, 192 or 256
then throw a
DataError
.
"jwk"
:Let jwk equal keyData.
If the "kty"
field of jwk is not
"oct"
,
then throw a
DataError
.
If jwk does not meet the requirements of
Section 6.4 of JSON Web Algorithms,
then throw a
DataError
.
Let data be the octet string obtained by decoding the
"k"
field of jwk.
"alg"
field of jwk is present, and is
not "A128KW"
,
then throw a
DataError
."alg"
field of jwk is present, and is
not "A192KW"
,
then throw a
DataError
."alg"
field of jwk is present, and is
not "A256KW"
,
then throw a
DataError
.DataError
.
If usages is non-empty and the "use"
field of jwk is present and is
not "enc"
,
then throw a
DataError
.
If the "key_ops"
field of jwk is present, and
is invalid according to the requirements of
JSON Web Key or
does not contain all of the specified usages values,
then throw a
DataError
.
If the "ext"
field of jwk is present and
has the value false and extractable is true,
then throw a
DataError
.
NotSupportedError
.
Let key be a new CryptoKey associated with the
relevant global object
of this
[HTML], and
representing an AES key with value data.
Let algorithm be a new AesKeyAlgorithm.
Set the name attribute of
algorithm to "AES-KW"
.
Set the length attribute of algorithm to the length, in bits, of data.
Set the [[algorithm]] internal slot of key to algorithm.
Return key.
If the underlying cryptographic key material represented by the [[handle]] internal slot of key
cannot be accessed, then throw an OperationError
.
"raw"
:Let data be the raw octets of the key represented by [[handle]] internal slot of key.
Let result be a new ArrayBuffer associated with the
relevant global object
of this
[HTML], and containing
data.
"jwk"
:Let jwk be a new JsonWebKey dictionary.
Set the kty
attribute of jwk to the
string "oct"
.
Set the k
attribute of jwk to be a string
containing the raw octets of the key represented by [[handle]] internal slot of
key, encoded according to Section 6.4 of JSON Web Algorithms.
Set the key_ops
attribute of jwk to equal the
usages attribute of key.
Set the ext
attribute of jwk to equal the [[extractable]] internal slot
of key.
Let result be the result of converting jwk to an ECMAScript Object, as defined by [WebIDL].
Return result.
If the length member of
normalizedDerivedKeyAlgorithm is not 128, 192 or 256, then throw an OperationError
.
Return the length member of normalizedDerivedKeyAlgorithm.
This section is non-normative.
The HMAC
algorithm calculates and verifies hash-based message
authentication codes according to [FIPS PUB 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 and key import steps and key export steps for HMAC.
The recognized algorithm name for
this algorithm is "HMAC"
.
Operation | Parameters | Result |
---|---|---|
sign | None | ArrayBuffer |
verify | None | boolean |
generateKey | HmacKeyGenParams | CryptoKey |
importKey | HmacImportParams | CryptoKey |
exportKey | None | object |
get key length | HmacImportParams | Integer |
dictionary HmacImportParams : Algorithm {
// The inner hash function to use.
required HashAlgorithmIdentifier hash;
// The length (in bits) of the key.
[EnforceRange] unsigned long length;
};
dictionary HmacKeyAlgorithm : KeyAlgorithm {
// The inner hash function to use.
required KeyAlgorithm hash;
// The length (in bits) of the key.
required unsigned long length;
};
dictionary HmacKeyGenParams : Algorithm {
// The inner hash function to use.
required HashAlgorithmIdentifier hash;
// 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.
[EnforceRange] unsigned long length;
};
Let mac be the result of performing the MAC Generation operation described in Section 4 of [FIPS PUB 198-1] using the key represented by [[handle]] internal slot of key, the hash function identified by the hash attribute of the [[algorithm]] internal slot of key and message as the input data text.
Return a new ArrayBuffer object, associated with the
relevant global object
of this
[HTML], and containing the
bytes of mac.
Let mac be the result of performing the MAC Generation operation described in Section 4 of [FIPS PUB 198-1] using the key represented by [[handle]] internal slot of key, the hash function identified by the hash attribute of the [[algorithm]] internal slot of key and message as the input data text.
Return true if mac is equal to signature and false otherwise.
If usages contains any entry which is not "sign"
or
"verify"
, then throw a SyntaxError
.
OperationError
.
Generate a key of length length bits.
If the key generation step fails,
then throw an
OperationError
.
Let key be a new CryptoKey object representing the generated key.
Let algorithm be a new HmacKeyAlgorithm.
Set the name attribute of
algorithm to "HMAC"
.
Let hash be a new KeyAlgorithm.
Set the name attribute of hash to equal the name member of the hash member of normalizedAlgorithm.
Set the hash attribute of algorithm to hash.
Set the [[algorithm]] internal slot of key to algorithm.
Set the [[extractable]] internal slot of key to be extractable.
Set the [[usages]] internal slot of key to be usages.
Return key.
Let keyData be the key data to be imported.
If usages contains an entry which is not
"sign"
or "verify"
,
then throw a
SyntaxError
.
Let hash be a new KeyAlgorithm.
"raw"
:Let data be the octet string contained in keyData.
Set hash to equal the hash member of normalizedAlgorithm.
"jwk"
:Let jwk equal keyData.
If the "kty"
field of jwk is not
"oct"
,
then throw a
DataError
.
If jwk does not meet the requirements of
Section 6.4 of JSON Web Algorithms,
then throw a
DataError
.
Let data be the octet string obtained by decoding the
"k"
field of jwk.
Set the hash to equal the hash member of normalizedAlgorithm.
"SHA-1"
:
"alg"
field of jwk is present
and is not "HS1"
,
then throw a
DataError
.
"SHA-256"
:
"alg"
field of jwk is present
and is not "HS256"
,
then throw a
DataError
.
"SHA-384"
:
"alg"
field of jwk is present
and is not "HS384"
,
then throw a
DataError
.
"SHA-512"
:
"alg"
field of jwk is present
and is not "HS512"
,
then throw a
DataError
.
If usages is non-empty and the "use"
field of jwk is present and is
not "sign"
,
then throw a
DataError
.
If the "key_ops"
field of jwk is present, and
is invalid according to the requirements of
JSON Web Key or
does not contain all of the specified usages values,
then throw a
DataError
.
If the "ext"
field of jwk is present and
has the value false and extractable is true,
then throw a
DataError
.
NotSupportedError
.
Let length be equivalent to the length, in octets, of data, multiplied by 8.
Let key be a new CryptoKey
object representing an HMAC key with the first length
bits of data.
Let algorithm be a new HmacKeyAlgorithm.
Set the name attribute of
algorithm to "HMAC"
.
Set the length attribute of algorithm to length.
Set the hash attribute of algorithm to hash.
Set the [[algorithm]] internal slot of key to algorithm.
Return key.
If the underlying cryptographic key material represented by the [[handle]] internal slot of key
cannot be accessed, then throw an OperationError
.
Let bits be the raw bits of the key represented by [[handle]] internal slot of key.
Let data be an octet string containing bits.
"raw"
:
Let result be a new ArrayBuffer associated with the
relevant global object
of this
[HTML], and containing data.
"jwk"
:Let jwk be a new JsonWebKey dictionary.
Set the kty
attribute of jwk to the
string "oct"
.
Set the k
attribute of jwk to be a string
containing data, encoded according to Section 6.4 of JSON Web Algorithms.
Let algorithm be the [[algorithm]] internal slot of key.
Let hash be the hash attribute of algorithm.
"SHA-1"
:alg
attribute of jwk to
the string "HS1"
."SHA-256"
:alg
attribute of jwk to
the string "HS256"
."SHA-384"
:alg
attribute of jwk to
the string "HS384"
."SHA-512"
:alg
attribute of jwk to
the string "HS512"
.Perform any key export steps defined by other applicable specifications, passing format and key and obtaining alg.
Set the alg
attribute of jwk to
alg.
Set the key_ops
attribute of jwk to equal the
usages attribute of key.
Set the ext
attribute of jwk to equal the [[extractable]] internal slot
of key.
Let result be the result of converting jwk to an ECMAScript Object, as defined by [WebIDL].
Return result.
Let length be the block size in bytes of the hash function identified by the hash member of normalizedDerivedKeyAlgorithm.
TypeError
.
Return length.
This section is non-normative.
This describes the SHA-1 and SHA-2 families, as specified by [FIPS PUB 180-4].
The following algorithms are added as recognized algorithm names:
"SHA-1"
"SHA-256"
"SHA-384"
"SHA-512"
Operation | Parameters | Result |
---|---|---|
digest | None | ArrayBuffer |
"SHA-1"
:
"SHA-256"
:
"SHA-384"
:
"SHA-512"
:
If performing the operation results in an error, then throw an OperationError
.
Return a new ArrayBuffer containing result.
This section is non-normative.
The "HKDF"
algorithm identifier is used to
perform key derivation using the extraction-then-expansion approach described in
[RFC 5869] 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 recognized algorithm name
for this algorithm is "HKDF"
.
Operation | Parameters | Result |
---|---|---|
deriveBits | HkdfParams | ArrayBuffer |
importKey | None | CryptoKey |
Get key length | None | null |
dictionary HkdfParams : Algorithm {
// The algorithm to use with HMAC (e.g.: SHA-256)
required HashAlgorithmIdentifier hash;
// A bit string that corresponds to the salt used in the extract step.
required BufferSource salt;
// A bit string that corresponds to the context and application specific context for the derived keying material.
required BufferSource info;
};
If length is null, then throw an OperationError
.
Let extractKey be a key equal to n zero bits where n is the size of the output of the hash function described by the hash member of normalizedAlgorithm.
Let keyDerivationKey be the secret represented by [[handle]] internal slot of key as the message.
Let result be the result of performing the HKDF extract and then the HKDF expand step described in Section 2 of [RFC 5869] using:
the hash member of normalizedAlgorithm as Hash,
keyDerivationKey as the input keying material, IKM,
the contents of the salt member of normalizedAlgorithm as salt,
the contents of the info member of normalizedAlgorithm as info,
length as the value of L,
If the key derivation operation fails,
then throw an
OperationError
.
Return result.
Let keyData be the key data to be imported.
"raw"
:
If usages contains a value that is not
"deriveKey"
or "deriveBits"
,
then throw a
SyntaxError
.
If extractable is not false
,
then throw a
SyntaxError
.
Let key be a new CryptoKey associated with the
relevant global object
of this
[HTML], and
representing the key data provided in keyData.
Set the [[type]] internal slot of
key to "secret"
.
Set the [[extractable]] internal slot of
key to false
.
Let algorithm be a new KeyAlgorithm object.
Set the name attribute of
algorithm to "HKDF"
.
Set the [[algorithm]] internal slot of key to algorithm.
Return key.
NotSupportedError
.
Return null.
This section is non-normative.
The "PBKDF2"
algorithm identifier is used to
perform key derivation using the PKCS#5 password-based key
derivation function version 2.0, as defined in
[RFC2898] 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.
The recognized algorithm name for
this algorithm is "PBKDF2"
.
Operation | Parameters | Result |
---|---|---|
deriveBits | Pbkdf2Params | ArrayBuffer |
importKey | None | CryptoKey |
Get key length | None | Integer or null |
dictionary Pbkdf2Params : Algorithm {
required BufferSource salt;
[EnforceRange] required unsigned long iterations;
required HashAlgorithmIdentifier hash;
};
If length is null or is not a multiple of 8, then throw an OperationError
.
Let prf be the MAC Generation function described in Section 4 of [FIPS PUB 198-1] using the hash function described by the hash member of normalizedAlgorithm.
Let result be the result of performing the PBKDF2 operation defined in Section 5.2 of [RFC2898] using prf as the pseudo-random function, PRF, the password represented by [[handle]] internal slot of key as the password, P, the contents of the salt attribute of normalizedAlgorithm as the salt, S, the value of the iterations attribute of normalizedAlgorithm as the iteration count, c, and length divided by 8 as the intended key length, dkLen.
If the key derivation operation fails,
then throw an
OperationError
.
Return result
If format is not "raw"
, throw a NotSupportedError
If usages contains a value that is not
"deriveKey"
or "deriveBits"
, then
throw a SyntaxError
.
If extractable is not false
,
then throw a
SyntaxError
.
Let key be a new CryptoKey associated with the
relevant global object
of this
[HTML], and
representing keyData.
Set the [[type]] internal slot of
key to "secret"
.
Set the [[extractable]] internal slot of
key to false
.
Let algorithm be a new KeyAlgorithm object.
Set the name attribute of
algorithm to "PBKDF2"
.
Set the [[algorithm]] internal slot of key to algorithm.
Return key.
Return null.
var encoder = new TextEncoder('utf-8');
// Algorithm Object
var algorithmKeyGen = {
name: "RSASSA-PKCS1-v1_5",
// RsaHashedKeyGenParams
modulusLength: 2048,
publicExponent: new Uint8Array([0x01, 0x00, 0x01]), // Equivalent to 65537
hash: {
name: "SHA-256"
}
};
var algorithmSign = {
name: "RSASSA-PKCS1-v1_5"
};
window.crypto.subtle.generateKey(algorithmKeyGen, false, ["sign"]).then(
function(key) {
var dataPart1 = encoder.encode("hello,");
var dataPart2 = encoder.encode(" world!");
return window.crypto.subtle.sign(algorithmSign, key.privateKey, [dataPart1, dataPart2]);
},
console.error.bind(console, "Unable to generate a key")
).then(
console.log.bind(console, "The signature is: "),
console.error.bind(console, "Unable to sign")
);
var encoder = new TextEncoder('utf-8');
var clearDataArrayBufferView = encoder.encode("Plain Text Data");
var aesAlgorithmKeyGen = {
name: "AES-CBC",
// AesKeyGenParams
length: 128
};
var aesAlgorithmEncrypt = {
name: "AES-CBC",
// AesCbcParams
iv: window.crypto.getRandomValues(new Uint8Array(16))
};
// Create a key generator to produce a one-time-use AES key to encrypt some data
window.crypto.subtle.generateKey(aesAlgorithmKeyGen, false, ["encrypt"]).then(
function(aesKey) {
return window.crypto.subtle.encrypt(aesAlgorithmEncrypt, aesKey, [ clearDataArrayBufferView ]);
}
).then(console.log.bind(console, "The ciphertext is: "),
console.error.bind(console, "Unable to encrypt"));
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.
Thanks are due especially to Ryan Sleevi, the original author and editor of this document.
The editor would like to thank 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.
Thanks to the W3C Web Cryptography WG, and to participants on the public-webcrypto@w3.org mailing list.
The W3C would like to thank the Northrop Grumman Cybersecurity Research Consortium for supporting W3C/MIT.
The getRandomValues
method in the Crypto
interface was originally proposed by Adam Barth to the
WHATWG.
The following section is non-normative. Refer to algorithm-specific sections for the normative requirements of importing and exporting JWK.
JSON Web Key | AlgorithmIdentifier |
---|---|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
The following section is non-normative. Refer to algorithm-specific sections for the normative requirements of importing and exporting SPKI.
Algorithm OID | subjectPublicKey ASN.1 structure | AlgorithmIdentifier | Reference |
---|---|---|---|
rsaEncryption (1.2.840.113549.1.1.1) | RSAPublicKey |
"RSASSA-PKCS1-v1_5" ,
"RSA-PSS" , or
"RSA-OAEP"
|
RFC 3279, RFC 4055, RFC 5756 |
id-RSASSA-PSS (1.2.840.113549.1.1.10) | RSAPublicKey | "RSA-PSS" |
RFC 4055, RFC 5756 |
id-RSAES-OAEP (1.2.840.113549.1.1.7) | RSAPublicKey | "RSA-OAEP" |
RFC 4055, RFC 5756 |
id-ecPublicKey (1.2.840.10045.2.1) | ECPoint | "ECDH" or "ECDSA" |
RFC 5480 |
id-ecDH (1.3.132.1.12) | ECPoint | "ECDH" |
RFC 5480 |
id-dsa (1.2.840.10040.4.1) | DSAPublicKey | "DSA" |
RFC 3279 |
For "id-RSASSA-PSS" and "id-RSAES-OAEP",
RFC 5756 recommends implementations should not include parameters
when PSS is used with a subjectPublicKeyInfo
, and MUST NOT include parameters when OAEP
is used. However, when OAEP is used as part of a key transport (as an AlgorithmIdentifier
),
implementations MUST include the parameters.
The "spki"
key format in this specification implies
subjectPublicKeyInfo
and thus may not be appropriate when what is needed is an
AlgorithmIdentifier
for transport.
The following section is non-normative. Refer to algorithm-specific sections for the normative requirements of importing and exporting PKCS#8 PrivateKeyInfo.
privateKeyAlgorithm | privateKey format | AlgorithmIdentifier | Reference |
---|---|---|---|
rsaEncryption (1.2.840.113549.1.1.1) | RSAPrivateKey |
"RSASSA-PKCS1-v1_5" ,
"RSA-PSS" , or
"RSA-OAEP"
|
RFC 3447, RFC 5958 |
id-RSASSA-PSS (1.2.840.113549.1.1.10) | RSAPrivateKey | "RSA-PSS" |
RFC 3447, RFC 4055, RFC 5958 |
id-RSAES-OAEP (1.2.840.113549.1.1.7) | RSAPrivateKey | "RSA-OAEP" |
RFC 3447, RFC 4055, RFC 5958 |
id-ecPublicKey (1.2.840.10045.2.1) | ECPrivateKey | "ECDH" or "ECDSA" |
RFC 5480, RFC 5915, RFC 5958 |
id-ecDH (1.3.132.1.12) | ECPrivateKey | "ECDH" |
RFC 5480, RFC 5915, RFC 5958 |
id-dsa (1.2.840.10040.4.1) | INTEGER | "DSA" |
RFC 5958 |