| CARVIEW |
Web Cryptography Level 2
W3C First Public Working Draft
More details about this document
- This version:
- https://www.w3.org/TR/2025/WD-webcrypto-2-20250422/
- Latest published version:
- https://www.w3.org/TR/webcrypto-2/
- Latest editor's draft:
- https://w3c.github.io/webcrypto/
- History:
- https://www.w3.org/standards/history/webcrypto-2/
- Commit history
- Editor:
- Daniel Huigens (Proton AG)
- Former editors:
- Mark Watson - Until
- Ryan Sleevi - Until
- Feedback:
- GitHub w3c/webcrypto (pull requests, new issue, open issues)
Copyright © 2025 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.
Abstract
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.
Status of This Document
This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C standards and drafts index at https://www.w3.org/TR/.
This document was published by the Web Application Security Working Group as a First Public Working Draft using the Recommendation track.
Publication as a First Public Working Draft does not imply endorsement by W3C and its Members.
This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the 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 03 November 2023 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 key words MUST, REQUIRED, and SHALL in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
The following conformance classes are defined by this specification:
- conforming user agent
-
A user agent is considered to be 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 defining
serialization and deserialization steps
for CryptoKey objects, any existing or future web storage mechanisms that support
storing serializable objects can be used to store CryptoKey objects.
In practice, it is expected that most authors will make use of the
Indexed Database API [INDEXEDDB], which allows associative storage of
key/value pairs, where the key is some string identifier meaningful to the application,
and the value is a CryptoKey object. This allows the
storage and retrieval of key material, without ever exposing that key material to the
application or the JavaScript environment. Additionally, this allows authors
the full flexibility to store any additional metadata with the
CryptoKey itself.
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.
- Fingerprinting
- By exposing additional APIs that reflect capabilities of the underlying platform, this specification may allow malicious applications to determine or distinguish different user agents or devices.
- Super-cookies
- This specification does not provide any means for malicious applications to create identifiers that outlive existing web storage technologies. However, care must be taken when introducing future revisions to this API or additional cryptographic capabilities, such as those that are hardware backed (e.g.: smart cards or Trusted Platform Modules). Considering that such storage is designed to prevent any two users from having the same underlying key data, such APIs may represent a real risk of being used as a permanent identifier against the user's wishes.
-
Use of
randomUUIDas user ID -
randomUUIDis useful for generating user IDs, but does not directly give any ability to generate global identifiers.
This specification relies on underlying specifications.
- DOM
-
A conforming user agent MUST support at least the subset of the functionality defined in DOM that this specification relies upon; in particular, it MUST support
Promises andDOMException. [DOM] - HTML
-
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
ArrayBufferViewtypedef and serializable objects. [HTML] - Web IDL
-
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
ArrayBuffer,
ArrayBufferView, and
serializable objects,
are defined by the HTML specification [HTML].
The terms DOMString and
BufferSource are defined in [WEBIDL].
The term byte sequence is defined in [Infra].
The length in bits of a byte sequence is its length multiplied by 8.
A byte sequence containing a bit sequence b is the byte sequence obtained by first appending zero or more bits of value zero to b such that the length of the resulting bit sequence is minimal and an integer multiple of 8 and then considering each consecutive sequence of 8 bits in that string as a byte.
When this specification says to convert a non-negative integer i to a byte sequence 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 sequence of length n * 8, and then return the byte sequence formed by considering each consecutive sequence of 8 bits in that bit sequence as a byte.
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 [X690], 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 [RFC5280],
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
[RFC5208], 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.parseinternal function in the context of a new global object, withtextargument set to a JavaScript String containing json. -
Let key be the result of converting result to the IDL dictionary type of
JsonWebKey. -
If the
ktyfield of key is not defined, then throw aDataError. -
Return key.
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:
-
- If the [[slot_cached]] internal slot of object is undefined:
- Set the [[slot_cached]] internal slot of object to the result of performing type conversion to an ECMAScript object as defined in [WebIDL] to the contents of the [[slot]] internal slot of object.
- Return the contents of the [[slot_cached]] internal slot of object.
The Crypto interface represents an interface to
general purpose cryptographic functionality including a
cryptographically strong pseudo-random number generator seeded with truly random values.
WebIDLpartial interface mixin WindowOrWorkerGlobalScope {
[SameObject] readonly attribute Crypto crypto;
};
[Exposed=(Window,Worker)]
interface Crypto {
[SecureContext] readonly attribute SubtleCrypto subtle;
ArrayBufferView getRandomValues(ArrayBufferView array);
[SecureContext] DOMString randomUUID();
};
The getRandomValues
method generates cryptographically strong random values. It must act as follows:
-
If array is not an
Int8Array,Uint8Array,Uint8ClampedArray,Int16Array,Uint16Array,Int32Array,Uint32Array,BigInt64Array, orBigUint64Array, then throw aTypeMismatchErrorand terminate the algorithm. -
Let byteLength be the byte length of array.
-
If byteLength is greater than 65536, throw a
QuotaExceededErrorand terminate the algorithm. -
Let bytes be a byte sequence of length byteLength.
-
Fill bytes with cryptographically secure random bytes.
-
Write bytes into array.
-
Return array.
Do not generate keys using the getRandomValues method. Use the
generateKey method
instead.
The randomUUID
method generates a new version 4 UUID
and returns its namespace specific string representation
as described in section 3 of [RFC4122].
To generate a random UUID:
- Let bytes be a byte sequence of length 16.
- Fill bytes with cryptographically secure random bytes.
-
Set the 4 most significant bits of bytes[6], which represent the
UUID version, to
0100. -
Set the 2 most significant bits of bytes[8], which represent the
UUID variant, to
10. -
Return the string concatenation of «
- hexadecimal representation of bytes[0], hexadecimal representation of bytes[1], hexadecimal representation of bytes[2], hexadecimal representation of bytes[3],
-
"
-", - hexadecimal representation of bytes[4], hexadecimal representation of bytes[5],
-
"
-", - hexadecimal representation of bytes[6], hexadecimal representation of bytes[7],
-
"
-", - hexadecimal representation of bytes[8], hexadecimal representation of bytes[9],
-
"
-", - hexadecimal representation of bytes[10], hexadecimal representation of bytes[11], hexadecimal representation of bytes[12], hexadecimal representation of bytes[13], hexadecimal representation of bytes[14], hexadecimal representation of bytes[15]
».
For the steps described in the algorithm to generate a random UUID,
the hexadecimal representation of a byte value is the
two-character string created by expressing value in hexadecimal using
ASCII lower hex digits, left-padded with "0" to reach two
ASCII lower hex digits.
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.
WebIDLtypedef (object or DOMString) AlgorithmIdentifier;
typedef AlgorithmIdentifier HashAlgorithmIdentifier;
dictionary Algorithm {
required DOMString name;
};
11.1 Algorithm Dictionary Members
-
name - The name of the registered algorithm to use.
The KeyAlgorithm dictionary represents information about the contents of a given
CryptoKey object.
WebIDLdictionary 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.
name-
The name of the algorithm used to generate the
CryptoKey
The CryptoKey object represents an opaque reference to keying material that is managed by
the user agent.
WebIDLenum KeyType { "public", "private", "secret" };
enum KeyUsage { "encrypt", "decrypt", "sign", "verify", "deriveKey", "deriveBits", "wrapKey", "unwrapKey" };
[SecureContext,Exposed=(Window,Worker),Serializable]
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-
The type of a key. The recognized key type values
are "
public", "private" and "secret". Opaque keying material, including that used for symmetric algorithms, is represented bysecret, while keys used as part of asymmetric algorithms composed of public/private keypairs will be eitherpublicorprivate. KeyUsage-
A type of operation that may be performed using a key. The
recognized key usage values are
encrypt,decrypt,sign,verify,deriveKey,deriveBits,wrapKeyandunwrapKey.
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-
Reflects the
[[type]]internal slot, which contains the type of the underlying key. extractable-
Reflects the
[[extractable]]internal slot, which indicates whether or not the raw keying material may be exported by the application. algorithm-
Returns the cached ECMAScript object
associated with the
[[algorithm]]internal slot. usages-
Returns the cached ECMAScript object
associated with the
[[usages]]internal slot, which indicates which cryptographic operations are permissible to be used with this key.
CryptoKey objects are serializable objects. Their serialization steps,
given value and serialized, are:
-
Set serialized.[[Type]] to the
[[type]]internal slot of value. -
Set serialized.[[Extractable]] to the
[[extractable]]internal slot of value. -
Set serialized.[[Algorithm]] to the sub-serialization of the
[[algorithm]]internal slot of value. -
Set serialized.[[Usages]] to the sub-serialization of the
[[usages]]internal slot of value. -
Set serialized.[[Handle]] to the
[[handle]]internal slot of value.
Their deserialization steps, given serialized and value, are:
-
Initialize the
[[type]]internal slot of value to serialized.[[Type]]. -
Initialize the
[[extractable]]internal slot of value to serialized.[[Extractable]]. -
Initialize the
[[algorithm]]internal slot of value to the sub-deserialization of serialized.[[Algorithm]]. -
Initialize the
[[usages]]internal slot of value to the sub-deserialization of serialized.[[Usages]]. -
Initialize the
[[handle]]internal slot of value to serialized.[[Handle]].
CryptoKey object, it is important that the
object is not deserialized as a different type. This is normatively required by the
definition of the deserialization steps, but it merits specific attention, as
such deserialization may expose the contents of the key material, which in some
cases (such as when the [[extractable]] internal slot is false) should not
be exposed to applications.
The SubtleCrypto interface provides a set of
methods for dealing with low-level cryptographic primitives and algorithms.
WebIDLenum KeyFormat { "raw", "spki", "pkcs8", "jwk" };
[SecureContext,Exposed=(Window,Worker)]
interface SubtleCrypto {
Promise<ArrayBuffer> encrypt(
AlgorithmIdentifier algorithm,
CryptoKey key,
BufferSource data
);
Promise<ArrayBuffer> decrypt(
AlgorithmIdentifier algorithm,
CryptoKey key,
BufferSource data
);
Promise<ArrayBuffer> sign(
AlgorithmIdentifier algorithm,
CryptoKey key,
BufferSource data
);
Promise<boolean> verify(
AlgorithmIdentifier algorithm,
CryptoKey key,
BufferSource signature,
BufferSource data
);
Promise<ArrayBuffer> digest(
AlgorithmIdentifier algorithm,
BufferSource data
);
Promise<(CryptoKey or CryptoKeyPair)> generateKey(
AlgorithmIdentifier algorithm,
boolean extractable,
sequence<KeyUsage> keyUsages
);
Promise<CryptoKey> deriveKey(
AlgorithmIdentifier algorithm,
CryptoKey baseKey,
AlgorithmIdentifier derivedKeyType,
boolean extractable,
sequence<KeyUsage> keyUsages
);
Promise<ArrayBuffer> deriveBits(
AlgorithmIdentifier algorithm,
CryptoKey baseKey,
optional unsigned long? length = null
);
Promise<CryptoKey> importKey(
KeyFormat format,
(BufferSource or JsonWebKey) keyData,
AlgorithmIdentifier algorithm,
boolean extractable,
sequence<KeyUsage> keyUsages
);
Promise<(ArrayBuffer or JsonWebKey)> exportKey(
KeyFormat format,
CryptoKey key
);
Promise<ArrayBuffer> 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
);
};
The SubtleCrypto interface is named "SubtleCrypto" to reflect the fact that many
of these algorithms have subtle usage requirements in order to provide the required
algorithmic security guarantees.
For example, the direct use of an unauthenticated encryption scheme, such 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-
Specifies a serialization format for a key. The recognized key format values are:
raw- An unformatted sequence of bytes. Intended for secret keys.
pkcs8- The DER encoding of the PrivateKeyInfo structure from [RFC5208].
spki- The DER encoding of the SubjectPublicKeyInfo structure from [RFC5280].
jwk- The key is a
JsonWebKeydictionary encoded as a JavaScript object
- The crypto task source
-
This task source is used to queue tasks to resolve
or reject promises created in response to calls to methods
of
SubtleCrypto.
SubtleCrypto,
neither between multiple calls, nor between calls and tasks
from other task sources.
This task source is merely used to queue a task to
resolve or reject the relevant promise whenever the
cryptographic operation is completed, in order to
prevent race conditions.
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
algorithmandkeyparameters passed to theencrypt()method, respectively. -
Let data be the result of getting a copy of the bytes held by the
dataparameter passed to theencrypt()method. -
Let normalizedAlgorithm be the result of normalizing an algorithm, with
algset to algorithm andopset to "encrypt". -
If an error occurred, return a Promise rejected with normalizedAlgorithm.
-
Let realm be the relevant realm of this.
-
Let promise be a new Promise.
-
Return promise and perform the remaining steps in parallel.
-
If the following steps or referenced procedures say to throw an error, queue a global task on the crypto task source, given realm's global object, to reject promise with the returned error; and then terminate the algorithm.
-
If the
namemember of normalizedAlgorithm is not equal to thenameattribute of the[[algorithm]]internal slot of key then throw anInvalidAccessError. -
If the
[[usages]]internal slot of key does not contain an entry that is "encrypt", then throw anInvalidAccessError. -
Let ciphertext be the result of performing the encrypt operation specified by normalizedAlgorithm using algorithm and key and with data as plaintext.
-
Queue a global task on the crypto task source, given realm's global object, to perform the remaining steps.
-
Let result be the result of creating an
ArrayBufferin realm, containing ciphertext. -
Resolve promise with result.
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
algorithmandkeyparameters passed to thedecrypt()method, respectively. -
Let data be the result of getting a copy of the bytes held by the
dataparameter passed to thedecrypt()method. -
Let normalizedAlgorithm be the result of normalizing an algorithm, with
algset to algorithm andopset to "decrypt". -
If an error occurred, return a Promise rejected with normalizedAlgorithm.
-
Let realm be the relevant realm of this.
-
Let promise be a new Promise.
-
Return promise and perform the remaining steps in parallel.
-
If the following steps or referenced procedures say to throw an error, queue a global task on the crypto task source, given realm's global object, to reject promise with the returned error; and then terminate the algorithm.
-
If the
namemember of normalizedAlgorithm is not equal to thenameattribute of the[[algorithm]]internal slot of key then throw anInvalidAccessError. -
If the
[[usages]]internal slot of key does not contain an entry that is "decrypt", then throw anInvalidAccessError. -
Let plaintext be the result of performing the decrypt operation specified by normalizedAlgorithm using key and algorithm and with data as ciphertext.
-
Queue a global task on the crypto task source, given realm's global object, to perform the remaining steps.
-
Let result be the result of creating an
ArrayBufferin realm, containing plaintext. -
Resolve promise with result.
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
algorithmandkeyparameters passed to thesign()method, respectively. -
Let data be the result of getting a copy of the bytes held by the
dataparameter passed to thesign()method. -
Let normalizedAlgorithm be the result of normalizing an algorithm, with
algset to algorithm andopset to "sign". -
If an error occurred, return a Promise rejected with normalizedAlgorithm.
-
Let realm be the relevant realm of this.
-
Let promise be a new Promise.
-
Return promise and perform the remaining steps in parallel.
-
If the following steps or referenced procedures say to throw an error, queue a global task on the crypto task source, given realm's global object, to reject promise with the returned error; and then terminate the algorithm.
-
If the
namemember of normalizedAlgorithm is not equal to thenameattribute of the[[algorithm]]internal slot of key then throw anInvalidAccessError. -
If the
[[usages]]internal slot of key does not contain an entry that is "sign", then throw anInvalidAccessError. -
Let signature be the result of performing the sign operation specified by normalizedAlgorithm using key and algorithm and with data as message.
-
Queue a global task on the crypto task source, given realm's global object, to perform the remaining steps.
-
Let result be the result of creating an
ArrayBufferin realm, containing signature. -
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
algorithmandkeyparameters passed to theverify()method, respectively. -
Let signature be the result of getting a copy of the bytes held by the
signatureparameter passed to theverify()method. -
Let data be the result of getting a copy of the bytes held by the
dataparameter passed to theverify()method. -
Let normalizedAlgorithm be the result of normalizing an algorithm, with
algset to algorithm andopset to "verify". -
If an error occurred, return a Promise rejected with normalizedAlgorithm.
-
Let realm be the relevant realm of this.
-
Let promise be a new Promise.
-
Return promise and perform the remaining steps in parallel.
-
If the following steps or referenced procedures say to throw an error, queue a global task on the crypto task source, given realm's global object, to reject promise with the returned error; and then terminate the algorithm.
-
If the
namemember of normalizedAlgorithm is not equal to thenameattribute of the[[algorithm]]internal slot of key then throw anInvalidAccessError. -
If the
[[usages]]internal slot of key does not contain an entry that is "verify", then throw anInvalidAccessError. -
Let result be the result of performing the verify operation specified by normalizedAlgorithm using key, algorithm and signature and with data as message.
-
Queue a global task on the crypto task source, given realm's global object, to perform the remaining steps.
-
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
algorithmparameter passed to thedigest()method. -
Let data be the result of getting a copy of the bytes held by the
dataparameter passed to thedigest()method. -
Let normalizedAlgorithm be the result of normalizing an algorithm, with
algset to algorithm andopset to "digest". -
If an error occurred, return a Promise rejected with normalizedAlgorithm.
-
Let realm be the relevant realm of this.
-
Let promise be a new Promise.
-
Return promise and perform the remaining steps in parallel.
-
If the following steps or referenced procedures say to throw an error, queue a global task on the crypto task source, given realm's global object, to reject promise with the returned error; and then terminate the algorithm.
-
Let digest be the result of performing the digest operation specified by normalizedAlgorithm using algorithm, with data as message.
-
Queue a global task on the crypto task source, given realm's global object, to perform the remaining steps.
-
Let result be the result of creating an
ArrayBufferin realm, containing digest. -
Resolve promise with result.
When invoked, generateKey MUST perform the
following steps:
-
Let algorithm, extractable and usages be the
algorithm,extractableandkeyUsagesparameters passed to thegenerateKey()method, respectively. -
Let normalizedAlgorithm be the result of normalizing an algorithm, with
algset to algorithm andopset to "generateKey". -
If an error occurred, return a Promise rejected with normalizedAlgorithm.
-
Let realm be the relevant realm of this.
-
Let promise be a new Promise.
-
Return promise and perform the remaining steps in parallel.
-
If the following steps or referenced procedures say to throw an error, queue a global task on the crypto task source, given realm's global object, to 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 result is a
CryptoKeyobject: -
If the
[[type]]internal slot of result is "secret" or "private" and usages is empty, then throw aSyntaxError. - If result is a
CryptoKeyPairobject: -
If the
[[usages]]internal slot of theprivateKeyattribute of result is the empty sequence, then throw aSyntaxError.
- If result is a
-
Queue a global task on the crypto task source, given realm's global object, to perform the remaining steps.
-
Let result be the result of converting result to an ECMAScript Object in realm, as defined by [WebIDL].
-
Resolve promise with result.
When invoked, deriveKey
MUST perform the following steps:
-
Let algorithm, baseKey, derivedKeyType, extractable and usages be the
algorithm,baseKey,derivedKeyType,extractableandkeyUsagesparameters passed to thederiveKey()method, respectively. -
Let normalizedAlgorithm be the result of normalizing an algorithm, with
algset to algorithm andopset to "deriveBits". -
If an error occurred, return a Promise rejected with normalizedAlgorithm.
-
Let normalizedDerivedKeyAlgorithmImport be the result of normalizing an algorithm, with
algset to derivedKeyType andopset to "importKey". -
If an error occurred, return a Promise rejected with normalizedDerivedKeyAlgorithmImport.
-
Let normalizedDerivedKeyAlgorithmLength be the result of normalizing an algorithm, with
algset to derivedKeyType andopset to "get key length". -
If an error occurred, return a Promise rejected with normalizedDerivedKeyAlgorithmLength.
-
Let realm be the relevant realm of this.
-
Let promise be a new Promise.
-
Return promise and perform the remaining steps in parallel.
-
If the following steps or referenced procedures say to throw an error, queue a global task on the crypto task source, given realm's global object, to reject promise with the returned error; and then terminate the algorithm.
-
If the
namemember of normalizedAlgorithm is not equal to thenameattribute of the[[algorithm]]internal slot of baseKey then throw anInvalidAccessError. -
If the
[[usages]]internal slot of baseKey does not contain an entry that is "deriveKey", then throw anInvalidAccessError. -
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 aSyntaxError. -
Set the
[[extractable]]internal slot of result to extractable. -
Set the
[[usages]]internal slot of result to the normalized value of usages. -
Queue a global task on the crypto task source, given realm's global object, to perform the remaining steps.
-
Let result be the result of converting result to an ECMAScript Object in realm, as defined by [WebIDL].
-
Resolve promise with result.
When invoked, deriveBits
MUST perform the following steps:
-
Let algorithm, baseKey and length, be the
algorithm,baseKeyandlengthparameters passed to thederiveBits()method, respectively. -
Let normalizedAlgorithm be the result of normalizing an algorithm, with
algset to algorithm andopset to "deriveBits". -
If an error occurred, return a Promise rejected with normalizedAlgorithm.
-
Let realm be the relevant realm of this.
-
Let promise be a new Promise.
-
Return promise and perform the remaining steps in parallel.
-
If the following steps or referenced procedures say to throw an error, queue a global task on the crypto task source, given realm's global object, to reject promise with the returned error; and then terminate the algorithm.
-
If the
namemember of normalizedAlgorithm is not equal to thenameattribute of the[[algorithm]]internal slot of baseKey then throw anInvalidAccessError. -
If the
[[usages]]internal slot of baseKey does not contain an entry that is "deriveBits", then throw anInvalidAccessError. -
Let bits be the result of performing the derive bits operation specified by normalizedAlgorithm using baseKey, algorithm and length.
-
Queue a global task on the crypto task source, given realm's global object, to perform the remaining steps.
-
Let result be the result of creating an
ArrayBufferin realm, containing bits. -
Resolve promise with result.
When invoked, the importKey method MUST perform the following steps:
-
Let format, algorithm, extractable and usages, be the
format,algorithm,extractableandkeyUsagesparameters passed to theimportKey()method, respectively. -
-
If format is equal to the string "
raw", "pkcs8", or "spki": -
-
If the
keyDataparameter passed to theimportKey()method is aJsonWebKeydictionary, throw aTypeError. -
Let keyData be the result of getting a copy of the bytes held by the
keyDataparameter passed to theimportKey()method.
-
-
If format is equal to the string "
jwk": -
-
If the
keyDataparameter passed to theimportKey()method is not aJsonWebKeydictionary, throw aTypeError. -
Let keyData be the
keyDataparameter passed to theimportKey()method.
-
-
If format is equal to the string "
-
Let normalizedAlgorithm be the result of normalizing an algorithm, with
algset to algorithm andopset to "importKey". -
If an error occurred, return a Promise rejected with normalizedAlgorithm.
-
Let realm be the relevant realm of this.
-
Let promise be a new Promise.
-
Return promise and perform the remaining steps in parallel.
-
If the following steps or referenced procedures say to throw an error, queue a global task on the crypto task source, given realm's global object, to reject promise with the returned error; and then terminate the algorithm.
-
Let result be the
CryptoKeyobject 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 aSyntaxError. -
Set the
[[extractable]]internal slot of result to extractable. -
Set the
[[usages]]internal slot of result to the normalized value of usages. -
Queue a global task on the crypto task source, given realm's global object, to perform the remaining steps.
-
Let result be the result of converting result to an ECMAScript Object in realm, as defined by [WebIDL].
-
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 exportKey method MUST perform the following steps:
-
Let format and key be the
formatandkeyparameters passed to theexportKey()method, respectively. -
Let realm be the relevant realm of this.
-
Let promise be a new Promise.
-
Return promise and perform the remaining steps in parallel.
-
If the following steps or referenced procedures say to throw an error, queue a global task on the crypto task source, given realm's global object, to reject promise with the returned error; and then terminate the algorithm.
-
If the
namemember of the[[algorithm]]internal slot of key does not identify a registered algorithm that supports the export key operation, then throw aNotSupportedError. -
If the
[[extractable]]internal slot of key is false, then throw anInvalidAccessError. -
Let result be the result of performing the export key operation specified by the
[[algorithm]]internal slot of key using key and format. -
Queue a global task on the crypto task source, given realm's global object, to perform the remaining steps.
-
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,wrappingKeyandwrapAlgorithmparameters passed to thewrapKey()method, respectively. -
Let normalizedAlgorithm be the result of normalizing an algorithm, with
algset to algorithm andopset to "wrapKey". -
If an error occurred, let normalizedAlgorithm be the result of normalizing an algorithm, with
algset to algorithm andopset to "encrypt". -
If an error occurred, return a Promise rejected with normalizedAlgorithm.
-
Let realm be the relevant realm of this.
-
Let promise be a new Promise.
-
Return promise and perform the remaining steps in parallel.
-
If the following steps or referenced procedures say to throw an error, queue a global task on the crypto task source, given realm's global object, to reject promise with the returned error; and then terminate the algorithm.
-
If the
namemember of normalizedAlgorithm is not equal to thenameattribute of the[[algorithm]]internal slot of wrappingKey then throw anInvalidAccessError. -
If the
[[usages]]internal slot of wrappingKey does not contain an entry that is "wrapKey", then throw anInvalidAccessError. -
If the algorithm identified by the
[[algorithm]]internal slot of key does not support the export key operation, then throw aNotSupportedError. -
If the
[[extractable]]internal slot of key is false, then throw anInvalidAccessError.NoteBecause 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
extJWK member.However, the unwrapKey method does support the
extJWK member, so that wrapped non-extractable keys created elsewhere, for example by a server, can be unwrapped using this API. -
Let exportedKey be the result of performing the export key operation specified by the
[[algorithm]]internal slot of key using key and format. -
-
If format is equal to the strings "
raw", "pkcs8", or "spki": - Let bytes be exportedKey.
-
If format is equal to the string "
jwk": -
-
Let json be the result of representing exportedKey as a UTF-16 string conforming to the JSON grammar; for example, by executing the
JSON.stringifyalgorithm specified in [ECMA-262] in the context of a new global object. -
Let bytes be the result of UTF-8 encoding json.
-
NoteThe 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.
-
If format is equal to the strings "
-
- If normalizedAlgorithm supports the wrap key operation:
-
Let result be the result of performing the wrap key operation specified by normalizedAlgorithm using algorithm, wrappingKey as key and bytes as plaintext.
- Otherwise, if normalizedAlgorithm supports the encrypt operation:
-
Let result be the result of performing the encrypt operation specified by normalizedAlgorithm using algorithm, wrappingKey as key and bytes as plaintext.
- Otherwise:
-
throw a
NotSupportedError.
-
Queue a global task on the crypto task source, given realm's global object, to perform the remaining steps.
-
Let result be the result of creating an
ArrayBufferin realm, containing result. -
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,extractableandkeyUsagesparameters passed to theunwrapKey()method, respectively. -
Let wrappedKey be the result of getting a copy of the bytes held by the
wrappedKeyparameter passed to theunwrapKey()method. -
Let normalizedAlgorithm be the result of normalizing an algorithm, with
algset to algorithm andopset to "unwrapKey". -
If an error occurred, let normalizedAlgorithm be the result of normalizing an algorithm, with
algset to algorithm andopset to "decrypt". -
If an error occurred, return a Promise rejected with normalizedAlgorithm.
-
Let normalizedKeyAlgorithm be the result of normalizing an algorithm, with
algset to unwrappedKeyAlgorithm andopset to "importKey". -
If an error occurred, return a Promise rejected with normalizedKeyAlgorithm.
-
Let realm be the relevant realm of this.
-
Let promise be a new Promise.
-
Return promise and perform the remaining steps in parallel.
-
If the following steps or referenced procedures say to throw an error, queue a global task on the crypto task source, given realm's global object, to reject promise with the returned error; and then terminate the algorithm.
-
If the
namemember of normalizedAlgorithm is not equal to thenameattribute of the[[algorithm]]internal slot of unwrappingKey then throw anInvalidAccessError. -
If the
[[usages]]internal slot of unwrappingKey does not contain an entry that is "unwrapKey", then throw anInvalidAccessError. -
- If normalizedAlgorithm supports an unwrap key operation:
- Let bytes be the result of performing the unwrap key operation specified by normalizedAlgorithm using algorithm, unwrappingKey as key and wrappedKey as ciphertext.
- Otherwise, if normalizedAlgorithm supports a decrypt operation:
- Let bytes be the result of performing the decrypt operation specified by normalizedAlgorithm using algorithm, unwrappingKey as key and wrappedKey as ciphertext.
- Otherwise:
-
throw a
NotSupportedError.
-
-
If format is equal to the strings "
raw", "pkcs8", or "spki": - Let key be bytes.
-
If format is equal to the string "
jwk": -
Let key be the result of executing the
parse a JWK algorithm, with bytes
as the
datato be parsed.
-
If format is equal to the strings "
-
Let result be the result of performing the import key operation specified by normalizedKeyAlgorithm using unwrappedKeyAlgorithm as algorithm, format, usages and extractable and with key as keyData.
-
If the
[[type]]internal slot of result is "secret" or "private" and usages is empty, then throw aSyntaxError. -
Set the
[[extractable]]internal slot of result to extractable. -
Set the
[[usages]]internal slot of result to the normalized value of usages. -
Queue a global task on the crypto task source, given realm's global object, to perform the remaining steps.
-
Let result be the result of converting result to an ECMAScript Object in realm, as defined by [WebIDL].
-
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
[DOM] 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 realm of this.
WebIDLdictionary 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 JsonWebKey dictionary provides a way to represent
and exchange cryptographic keys represented by the JSON Web Key [JWK]
structure, while allowing native and efficient use within Web Cryptography API
applications.
The members of the RsaOtherPrimesInfo are defined in Section 6.3.2.7 of JSON Web Algorithms.
WebIDLtypedef 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.
WebIDLdictionary CryptoKeyPair {
CryptoKey publicKey;
CryptoKey privateKey;
};
The CryptoKeyPair dictionary represents an
asymmetric key pair that is comprised of both public (publicKey) and private (privateKey) 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:
- encrypt
- decrypt
- sign
- verify
- digest
- deriveBits
- wrapKey
- unwrapKey
- generateKey
- importKey
- exportKey
- get key length
If a given algorithm specification does not list a particular operation as supported, or explicitly lists an operation as not-supported, then the User 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.
Unless otherwise stated, objects created by the operations defined in this specification shall be associated with the relevant realm of this.
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
supportedAlgorithmsto 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:
-
Let registeredAlgorithms be the associative container stored at the
op key of
supportedAlgorithms. - Set the alg key of registeredAlgorithms to the IDL dictionary type type.
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:
- If alg is an instance of a DOMString:
-
Return the result of running the normalize an algorithm algorithm, with the
algset to a newAlgorithmdictionary whosenameattribute is alg, and with theopset to op. - If alg is an object:
-
-
Let registeredAlgorithms be the associative container stored at the
opkey ofsupportedAlgorithms. -
Let initialAlg be the result of converting the ECMAScript object
represented by alg to the IDL dictionary type
Algorithm, as defined by [WebIDL]. - If an error occurred, return the error and terminate this algorithm.
-
Let algName be the value of the
nameattribute of initialAlg. -
- If registeredAlgorithms contains a key that is a case-insensitive string match for algName:
-
-
Set algName to the value of the matching key.
-
Let desiredType be the IDL dictionary type stored at algName in registeredAlgorithms.
-
- Otherwise:
-
Return a new
NotSupportedErrorand terminate this algorithm.
- Let normalizedAlgorithm be the result of converting the ECMAScript object represented by alg to the IDL dictionary type desiredType, as defined by [WebIDL].
-
Set the
nameattribute of normalizedAlgorithm to algName. - If an error occurred, return the error and terminate this algorithm.
- Let dictionaries be a list consisting of the IDL dictionary type desiredType and all of desiredType's inherited dictionaries, in order from least to most derived.
-
For each dictionary dictionary in dictionaries:
-
For each dictionary member member declared on dictionary, in order:
- Let key be the identifier of member.
- Let idlValue be the value of the dictionary member with key name of key on normalizedAlgorithm.
-
-
If member is of the type
BufferSourceand is present: - Set the dictionary member on normalizedAlgorithm with key name key to the result of getting a copy of the bytes held by idlValue, replacing the current value.
-
If member is of the type
HashAlgorithmIdentifier: -
Set the dictionary member on normalizedAlgorithm with key
name key to the result of
normalizing an algorithm,
with the
algset to idlValue and theopset to "digest". -
If member is of the type
AlgorithmIdentifier: -
Set the dictionary member on normalizedAlgorithm with key
name key to the result of
normalizing an algorithm,
with the
algset to idlValue and theopset to the operation defined by the specification that defines the algorithm identified by algName.
-
If member is of the type
- If an error occurred, return the error and terminate this algorithm.
-
- Return normalizedAlgorithm.
-
Let registeredAlgorithms be the associative container stored at the
This section is non-normative.
As this API is meant to be extensible, in order to keep up with future developments within cryptography, there are no algorithms that conforming user agents are required to implement. As such, authors should check to see what algorithms are currently recommended and supported by implementations.
As highlighted in the Security Considerations, even cryptographic algorithms that might be considered strong for one purpose may be insufficient when used with another purpose. Authors should therefore proceed with extreme caution before inventing new cryptographic protocols.
Additionally, this specification includes several algorithms which, in their default usage, can result in cryptographic vulnerabilities. While these concerns may be mitigated, such as through the combination and composition with additional algorithms provided by this specification, authors should proceed with caution and review the relevant cryptographic literature before using a given algorithm. The inclusion of algorithms within this specification is not an indicator of their suitability for any or all purpose, and instead merely serve to provide as a specification for how a conforming User Agent must implement the given algorithm, if it choses to implement the algorithm.
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:
This 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
encryptmethod requires the encrypt operation. -
The
decryptmethod requires the decrypt operation. -
The
signmethod requires the sign operation. -
The
verifymethod requires the verify operation. -
The
generateKeymethod requires the generateKey operation. -
The
importKeymethod requires the importKey operation. -
The
exportKeymethod requires the exportKey operation. -
The
deriveKeymethod requires the deriveBits operation for the key derivation algorithm and the get key length and importKey operations for the derived key algorithm. -
The
deriveBitsmethod requires the deriveBits operation for the key derivation algorithm. -
The
digestmethod requires the digest operation. -
The
wrapKeymethod requires either the encrypt or wrapKey operation for the wrapping algorithm and the exportKey operation for the wrapped key algorithm. -
The
unwrapKeymethod 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 | ✔ | ✔ | ✔ | ✔ | ✔ | |||||||
| Ed25519 | ✔ | ✔ | ✔ | ✔ | ✔ | |||||||
| X25519 | ✔ | ✔ | ✔ | ✔ | ✔ | |||||||
| 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 | byte sequence |
| verify | None | boolean |
| generateKey | RsaHashedKeyGenParams |
CryptoKeyPair |
| importKey | RsaHashedImportParams |
CryptoKey |
| exportKey | None | object |
WebIDLdictionary RsaKeyGenParams : Algorithm {
required [EnforceRange] unsigned long modulusLength;
required BigInteger publicExponent;
};
The modulusLength member contains the length, in bits, of the RSA modulus.
The publicExponent member contains the RSA public exponent.
WebIDLdictionary RsaHashedKeyGenParams : RsaKeyGenParams {
required HashAlgorithmIdentifier hash;
};
The hash member represents the hash algorithm to use.
WebIDLdictionary RsaKeyAlgorithm : KeyAlgorithm {
required unsigned long modulusLength;
required BigInteger publicExponent;
};
The modulusLength member contains the length, in bits, of the RSA modulus.
The publicExponent member contains the RSA public exponent.
WebIDLdictionary RsaHashedKeyAlgorithm : RsaKeyAlgorithm {
required KeyAlgorithm hash;
};
The hash member describes the hash algorithm that is used with this key.
WebIDLdictionary RsaHashedImportParams : Algorithm {
required HashAlgorithmIdentifier hash;
};
The hash member describes the hash algorithm to use.
-
If the
[[type]]internal slot of key is not "private", then throw anInvalidAccessError. -
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 message as M and using the hash function specified in thehashattribute 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 signature.
-
If the
[[type]]internal slot of key is not "public", then throw anInvalidAccessError. -
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 message as M and signature as S and using the hash function specified in thehashattribute 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 aSyntaxError. -
Generate an RSA key pair, as defined in [RFC3447], with RSA modulus length equal to the
modulusLengthattribute of normalizedAlgorithm and RSA public exponent equal to thepublicExponentattribute of normalizedAlgorithm. -
If generation of the key pair fails, then throw an
OperationError. -
Let algorithm be a new
RsaHashedKeyAlgorithmdictionary. -
Set the
nameattribute of algorithm to "RSASSA-PKCS1-v1_5". -
Set the
modulusLengthattribute of algorithm to equal themodulusLengthattribute of normalizedAlgorithm. -
Set the
publicExponentattribute of algorithm to equal thepublicExponentattribute of normalizedAlgorithm. -
Set the
hashattribute of algorithm to equal thehashmember of normalizedAlgorithm. -
Let publicKey be a new
CryptoKeyrepresenting 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
CryptoKeyrepresenting the private key of the generated key pair. -
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
CryptoKeyPairdictionary. -
Set the
publicKeyattribute of result to be publicKey. -
Set the
privateKeyattribute of result to be privateKey. -
Return result.
-
Let keyData be the key data to be imported.
-
- If format is "
spki": -
-
If usages contains an entry which is not "
verify", then throw aSyntaxError. -
Let spki be the result of running the parse a subjectPublicKeyInfo algorithm over keyData.
-
If the
algorithmobject identifier field of thealgorithmAlgorithmIdentifier field of spki is not equal to thersaEncryptionobject identifier defined in [RFC3447], then throw aDataError. -
Let publicKey be the result of performing the parse an ASN.1 structure algorithm, with data as the
subjectPublicKeyInfofield of spki, structure as theRSAPublicKeystructure specified in Section A.1.1 of [RFC3447], 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 [RFC3447], then throw a
DataError. -
Let key be a new
CryptoKeythat represents the RSA public key identified by publicKey. -
Set the
[[type]]internal slot of key to "public"
-
- If format is "
pkcs8": -
-
If usages contains an entry which is not "
sign" then throw aSyntaxError. -
Let privateKeyInfo be the result of running the parse a privateKeyInfo algorithm over keyData.
-
If the
algorithmobject identifier field of theprivateKeyAlgorithmPrivateKeyAlgorithm field of privateKeyInfo is not equal to thersaEncryptionobject identifier defined in [RFC3447], then throw aDataError. -
Let rsaPrivateKey be the result of performing the parse an ASN.1 structure algorithm, with data as the
privateKeyfield of privateKeyInfo, structure as theRSAPrivateKeystructure specified in Section A.1.2 of [RFC3447], and exactData set to true. -
If an error occurred while parsing, or if rsaPrivateKey is not a valid RSA private key according to [RFC3447], then throw a
DataError. -
Let key be a new
CryptoKeythat represents the RSA private key identified by rsaPrivateKey.
-
- If format is "
jwk": -
-
- If keyData is a
JsonWebKeydictionary: Let jwk equal keyData.
- Otherwise:
- If keyData is a
-
If the
dfield of jwk is present and usages contains an entry which is not "sign", or, if thedfield of jwk is not present and usages contains an entry which is not "verify" then throw aSyntaxError. -
If the
ktyfield of jwk is not a case-sensitive string match to "RSA", then throw aDataError. -
If usages is non-empty and the
usefield of jwk is present and is not a case-sensitive string match to "sig", then throw aDataError. -
If the
key_opsfield of jwk is present, and is invalid according to the requirements of JSON Web Key [JWK] or does not contain all of the specified usages values, then throw aDataError. -
If the
extfield of jwk is present and has the value false and extractable is true, then throw aDataError. -
Let hash be a be a string whose initial value is undefined.
-
-
If the
algfield of jwk is not present: -
Let hash be undefined.
-
If the
algfield is equal to the string "RS1": -
Let hash be the string "
SHA-1". -
If the
algfield is equal to the string "RS256": -
Let hash be the string "
SHA-256". -
If the
algfield is equal to the string "RS384": -
Let hash be the string "
SHA-384". -
If the
algfield is equal to the string "RS512": -
Let hash be the string "
SHA-512". - Otherwise:
-
-
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.
-
-
If the
-
- If hash is not undefined:
-
-
Let normalizedHash be the result of normalize an algorithm with
algset to hash andopset todigest. -
If normalizedHash is not equal to the
hashmember of normalizedAlgorithm, throw aDataError.
-
-
- If the
dfield of jwk is present: -
-
If jwk does not meet the requirements of Section 6.3.2 of JSON Web Algorithms [JWA], 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 [JWA].
-
If privateKey is not a valid RSA private key according to [RFC3447], then throw a
DataError. -
Let key be a new
CryptoKeyobject that represents privateKey.
-
- Otherwise:
-
-
If jwk does not meet the requirements of Section 6.3.1 of JSON Web Algorithms [JWA], 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 [JWA].
-
If publicKey can be determined to not be a valid RSA public key according to [RFC3447], then throw a
DataError. -
Let key be a new
CryptoKeyrepresenting publicKey. -
Set the
[[type]]internal slot of key to "public"
-
- If the
-
- Otherwise:
-
throw a
NotSupportedError.
- If format is "
-
Let algorithm be a new
RsaHashedKeyAlgorithmdictionary. -
Set the
nameattribute of algorithm to "RSASSA-PKCS1-v1_5" -
Set the
modulusLengthattribute 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
hashattribute of algorithm to thehashmember 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 anOperationError. -
- If format is "
spki" -
-
If the
[[type]]internal slot of key is not "public", then throw anInvalidAccessError. -
Let data be an instance of the
SubjectPublicKeyInfoASN.1 structure defined in [RFC5280] with the following properties:-
Set the algorithm field to an
AlgorithmIdentifierASN.1 type with the following properties:-
Set the algorithm field to the OID
rsaEncryptiondefined in [RFC3447]. -
Set the params field to the ASN.1 type NULL.
-
-
Set the subjectPublicKey field to the result of DER-encoding an
RSAPublicKeyASN.1 type, as defined in [RFC3447], Appendix A.1.1, that represents the RSA public key represented by the[[handle]]internal slot of key
-
-
Let result be the result of DER-encoding data.
-
- If format is "
pkcs8": -
-
If the
[[type]]internal slot of key is not "private", then throw anInvalidAccessError. -
Let data be an instance of the
PrivateKeyInfoASN.1 structure defined in [RFC5208] with the following properties:-
Set the version field to
0. -
Set the privateKeyAlgorithm field to a
PrivateKeyAlgorithmIdentifierASN.1 type with the following properties:-
Set the algorithm field to the OID
rsaEncryptiondefined in [RFC3447]. -
Set the params field to the ASN.1 type NULL.
-
-
Set the privateKey field to the result of DER-encoding an
RSAPrivateKeyASN.1 type, as defined in [RFC3447], Appendix A.1.2, that represents the RSA private key represented by the[[handle]]internal slot of keyNote[RFC5208] specifies that the encoding of this field should be BER encoded in Section 5 (as a "for example"). However, to avoid requiring WebCrypto implementations support BER-encoding and BER-decoding, only DER encodings are produced or accepted.
-
-
Let result be the result of DER-encoding data.
-
- If format is "
jwk": -
-
Let jwk be a new
JsonWebKeydictionary. -
Set the
ktyattribute of jwk to the string "RSA". -
Let hash be the
nameattribute of thehashattribute of the[[algorithm]]internal slot of key. -
- If hash is "
SHA-1": -
Set the
algattribute of jwk to the string "RS1". - If hash is "
SHA-256": -
Set the
algattribute of jwk to the string "RS256". - If hash is "
SHA-384": -
Set the
algattribute of jwk to the string "RS384". - If hash is "
SHA-512": -
Set the
algattribute of jwk to the string "RS512". - Otherwise:
-
-
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
algattribute of jwk to alg.
-
- If hash is "
-
Set the attributes
nandeof jwk according to the corresponding definitions in JSON Web Algorithms [JWA], Section 6.3.1. -
-
If the
[[type]]internal slot of key is "private": -
-
Set the attributes named
d,p,q,dp,dq, andqiof jwk according to the corresponding definitions in JSON Web Algorithms [JWA], Section 6.3.2. -
If the underlying RSA private key represented by the
[[handle]]internal slot of key is represented by more than two primes, set the attribute namedothof jwk according to the corresponding definition in JSON Web Algorithms [JWA], Section 6.3.2.7
-
-
If the
-
Set the
key_opsattribute of jwk to the usages attribute of key. -
Set the
extattribute of jwk to the[[extractable]]internal slot of key. -
Let result be jwk.
-
- Otherwise
- If format is "
-
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 |
byte sequence |
| verify | RsaPssParams |
boolean |
| generateKey | RsaHashedKeyGenParams |
CryptoKeyPair |
| importKey | RsaHashedImportParams |
CryptoKey |
| exportKey | None | object |
WebIDLdictionary RsaPssParams : Algorithm {
required [EnforceRange] unsigned long saltLength;
};
The saltLength member represents the desired length of the random salt in bytes.
-
If the
[[type]]internal slot of key is not "private", then throw anInvalidAccessError. -
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 message as the message to be signed, M, and using the hash function specified by thehashattribute 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-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 signature.
-
If the
[[type]]internal slot of key is not "public", then throw anInvalidAccessError. -
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 message as M and signature as S and using the hash function specified by thehashattribute 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 aSyntaxError. -
Generate an RSA key pair, as defined in [RFC3447], with RSA modulus length equal to the
modulusLengthmember of normalizedAlgorithm and RSA public exponent equal to thepublicExponentmember of normalizedAlgorithm. -
If performing the operation results in an error, then throw an
OperationError. -
Let algorithm be a new
RsaHashedKeyAlgorithmdictionary. -
Set the
nameattribute of algorithm to "RSA-PSS". -
Set the
modulusLengthattribute of algorithm to equal themodulusLengthmember of normalizedAlgorithm. -
Set the
publicExponentattribute of algorithm to equal thepublicExponentmember of normalizedAlgorithm. -
Set the
hashattribute of algorithm to equal thehashmember of normalizedAlgorithm. -
Let publicKey be a new
CryptoKeyrepresenting 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
CryptoKeyrepresenting the private key of the generated key pair. -
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
CryptoKeyPairdictionary. -
Set the
publicKeyattribute of result to publicKey. -
Set the
privateKeyattribute of result to privateKey. -
Return result.
-
Let keyData be the key data to be imported.
-
- If format is "
spki": -
-
If usages contains an entry which is not "
verify" then throw aSyntaxError. -
Let spki be the result of running the parse a subjectPublicKeyInfo algorithm over keyData.
-
If the
algorithmobject identifier field of thealgorithmAlgorithmIdentifier field of spki is not equal to thersaEncryptionobject identifier defined in [RFC3447], then throw aDataError. -
Let publicKey be the result of performing the parse an ASN.1 structure algorithm, with data as the
subjectPublicKeyInfofield of spki, structure as theRSAPublicKeystructure specified in Section A.1.1 of [RFC3447], 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 [RFC3447], then throw a
DataError. -
Let key be a new
CryptoKeythat represents the RSA public key identified by publicKey. -
Set the
[[type]]internal slot of key to "public"
-
- If format is "
pkcs8": -
-
If usages contains an entry which is not "
sign" then throw aSyntaxError. -
Let privateKeyInfo be the result of running the parse a privateKeyInfo algorithm over keyData.
-
If the
algorithmobject identifier field of theprivateKeyAlgorithmPrivateKeyAlgorithm field of privateKeyInfo is not equal to thersaEncryptionobject identifier defined in [RFC3447], then throw aDataError. -
Let rsaPrivateKey be the result of performing the parse an ASN.1 structure algorithm, with data as the
privateKeyfield of privateKeyInfo, structure as theRSAPrivateKeystructure specified in Section A.1.2 of [RFC3447], and exactData set to true. -
If an error occurred while parsing, or if rsaPrivateKey is not a valid RSA private key according to [RFC3447], then throw a
DataError. -
Let key be a new
CryptoKeythat represents the RSA private key identified by rsaPrivateKey.
-
- If format is "
jwk": -
-
- If keyData is a
JsonWebKeydictionary: Let jwk equal keyData.
- Otherwise:
- If keyData is a
-
If the
dfield of jwk is present and usages contains an entry which is not "sign", or, if thedfield of jwk is not present and usages contains an entry which is not "verify" then throw aSyntaxError. -
If the
ktyfield of jwk is not a case-sensitive string match to "RSA", then throw aDataError. -
If usages is non-empty and the
usefield of jwk is present and is not a case-sensitive string match to "sig", then throw aDataError. -
If the
key_opsfield of jwk is present, and is invalid according to the requirements of JSON Web Key [JWK] or does not contain all of the specified usages values, then throw aDataError. -
If the
extfield of jwk is present and has the value false and extractable is true, then throw aDataError. -
-
If the
algfield of jwk is not present: -
Let hash be undefined.
-
If the
algfield is equal to the string "PS1": -
Let hash be the string "
SHA-1". -
If the
algfield is equal to the string "PS256": -
Let hash be the string "
SHA-256". -
If the
algfield is equal to the string "PS384": -
Let hash be the string "
SHA-384". -
If the
algfield is equal to the string "PS512": -
Let hash be the string "
SHA-512". - Otherwise:
-
-
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.
-
-
If the
-
- If hash is not undefined:
-
-
Let normalizedHash be the result of normalize an algorithm with
algset to hash andopset todigest. -
If normalizedHash is not equal to the
hashmember of normalizedAlgorithm, throw aDataError.
-
-
- If the
dfield of jwk is present: -
-
If jwk does not meet the requirements of Section 6.3.2 of JSON Web Algorithms [JWA], then throw a
DataError. -
Let privateKey represent the RSA private key identified by interpreting jwk according to Section 6.3.2 of JSON Web Algorithms [JWA].
-
If privateKey can be determined to not be a valid RSA private key according to [RFC3447], then throw a
DataError. -
Let key be a new
CryptoKeyrepresenting privateKey.
-
- Otherwise:
-
-
If jwk does not meet the requirements of Section 6.3.1 of JSON Web Algorithms [JWA], 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 [JWA].
-
If publicKey can be determined to not be a valid RSA public key according to [RFC3447], then throw a
DataError. -
Let key be a new
CryptoKeyrepresenting publicKey. -
Set the
[[type]]internal slot of key to "public"
-
- If the
-
- Otherwise:
-
throw a
NotSupportedError.
- If format is "
-
Let algorithm be a new
RsaHashedKeyAlgorithmdictionary. -
Set the
nameattribute of algorithm to "RSA-PSS" -
Set the
modulusLengthattribute of algorithm to the length, in bits, of the RSA public modulus. -
Set the
publicExponentattribute of algorithm to theBigIntegerrepresentation of the RSA public exponent. -
Set the
hashattribute of algorithm to thehashmember 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 anOperationError. -
- If format is "
spki" -
-
If the
[[type]]internal slot of key is not "public", then throw anInvalidAccessError. -
Let data be an instance of the
SubjectPublicKeyInfoASN.1 structure defined in [RFC5280] with the following properties:-
Set the algorithm field to an
AlgorithmIdentifierASN.1 type with the following properties:-
Set the algorithm field to the OID
rsaEncryptiondefined in [RFC3447]. -
Set the params field to the ASN.1 type NULL.
-
-
Set the subjectPublicKey field to the result of DER-encoding an
RSAPublicKeyASN.1 type, as defined in [RFC3447], Appendix A.1.1, that represents the RSA public key represented by the[[handle]]internal slot of key
-
-
Let result be the result of DER-encoding data.
-
- If format is "
pkcs8": -
-
If the
[[type]]internal slot of key is not "private", then throw anInvalidAccessError. -
Let data be an instance of the
PrivateKeyInfoASN.1 structure defined in [RFC5208] with the following properties:-
Set the version field to
0. -
Set the privateKeyAlgorithm field to a
PrivateKeyAlgorithmIdentifierASN.1 type with the following properties:-
Set the algorithm field to the OID
rsaEncryptiondefined in [RFC3447]. -
Set the params field to the ASN.1 type NULL.
-
-
Set the privateKey field to the result of DER-encoding an
RSAPrivateKeyASN.1 type, as defined in [RFC3447], Appendix A.1.2, that represents the RSA private key represented by the[[handle]]internal slot of keyNote[RFC5208] specifies that the encoding of this field should be BER encoded in Section 5 (as a "for example"). However, to avoid requiring WebCrypto implementations support BER-encoding and BER-decoding, only DER encodings are produced or accepted.
-
-
Let result be the result of DER-encoding data.
-
- If format is "
jwk": -
-
Let jwk be a new
JsonWebKeydictionary. -
Set the
ktyattribute of jwk to the string "RSA". -
Let hash be the
nameattribute of thehashattribute of the[[algorithm]]internal slot of key. -
- If hash is "
SHA-1": -
Set the
algattribute of jwk to the string "PS1". - If hash is "
SHA-256": -
Set the
algattribute of jwk to the string "PS256". - If hash is "
SHA-384": -
Set the
algattribute of jwk to the string "PS384". - If hash is "
SHA-512": -
Set the
algattribute of jwk to the string "PS512". - Otherwise:
-
-
Perform any key export steps defined by other applicable specifications, passing format and the
hashattribute of the[[algorithm]]internal slot of key and obtaining alg. -
Set the
algattribute of jwk to alg.
-
- If hash is "
-
Set the attributes
nandeof jwk according to the corresponding definitions in JSON Web Algorithms [JWA], Section 6.3.1. -
-
If the
[[type]]internal slot of key is "private": -
-
Set the attributes named
d,p,q,dp,dq, andqiof jwk according to the corresponding definitions in JSON Web Algorithms [JWA], Section 6.3.2. -
If the underlying RSA private key represented by the
[[handle]]internal slot of key is represented by more than two primes, set the attribute namedothof jwk according to the corresponding definition in JSON Web Algorithms [JWA], Section 6.3.2.7
-
-
If the
-
Set the
key_opsattribute of jwk to theusagesattribute of key. -
Set the
extattribute of jwk to the[[extractable]]internal slot of key. -
Let result be jwk.
-
- Otherwise
- If format is "
-
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 |
byte sequence |
| decrypt | RsaOaepParams |
byte sequence |
| generateKey | RsaHashedKeyGenParams |
CryptoKeyPair |
| importKey | RsaHashedImportParams |
CryptoKey |
| exportKey | None | object |
WebIDLdictionary RsaOaepParams : Algorithm {
BufferSource label;
};
The label member represents the optional label/application data to associate with the message.
-
If the
[[type]]internal slot of key is not "public", then throw anInvalidAccessError. -
Let label be the
labelmember of normalizedAlgorithm or the empty byte sequence if thelabelmember 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, plaintext as the message to be encrypted, M and label as the label, L, and with the hash function specified by the
hashattribute 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 ciphertext.
-
If the
[[type]]internal slot of key is not "private", then throw anInvalidAccessError. -
Let label be the
labelmember of normalizedAlgorithm or the empty byte sequence if thelabelmember 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, ciphertext as the ciphertext to be decrypted, C, and label as the label, L, and with the hash function specified by the
hashattribute 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 plaintext.
-
If usages contains an entry which is not "
encrypt", "decrypt", "wrapKey" or "unwrapKey", then throw aSyntaxError. -
Generate an RSA key pair, as defined in [RFC3447], with RSA modulus length equal to the
modulusLengthmember of normalizedAlgorithm and RSA public exponent equal to thepublicExponentmember of normalizedAlgorithm. -
If performing the operation results in an error, then throw an
OperationError. -
Let algorithm be a new
RsaHashedKeyAlgorithmobject. -
Set the
nameattribute of algorithm to "RSA-OAEP". -
Set the
modulusLengthattribute of algorithm to equal themodulusLengthmember of normalizedAlgorithm. -
Set the
publicExponentattribute of algorithm to equal thepublicExponentmember of normalizedAlgorithm. -
Set the
hashattribute of algorithm to equal thehashmember of normalizedAlgorithm. -
Let publicKey be a new
CryptoKeyrepresenting 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
CryptoKeyrepresenting the private key of the generated key pair. -
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
CryptoKeyPairdictionary. -
Set the
publicKeyattribute of result to be publicKey. -
Set the
privateKeyattribute of result to be privateKey. -
Return result.
-
Let keyData be the key data to be imported.
-
- If format is "
spki": -
-
If usages contains an entry which is not "
encrypt" or "wrapKey", then throw aSyntaxError. -
Let spki be the result of running the parse a subjectPublicKeyInfo algorithm over keyData.
-
If the
algorithmobject identifier field of thealgorithmAlgorithmIdentifier field of spki is not equal to thersaEncryptionobject identifier defined in [RFC3447], then throw aDataError. -
Let publicKey be the result of performing the parse an ASN.1 structure algorithm, with data as the
subjectPublicKeyInfofield of spki, structure as theRSAPublicKeystructure specified in Section A.1.1 of [RFC3447], 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 [RFC3447], then throw a
DataError. -
Let key be a new
CryptoKeythat represents the RSA public key identified by publicKey. -
Set the
[[type]]internal slot of key to "public"
-
- If format is "
pkcs8": -
-
If usages contains an entry which is not "
decrypt" or "unwrapKey", then throw aSyntaxError. -
Let privateKeyInfo be the result of running the parse a privateKeyInfo algorithm over keyData.
-
If the
algorithmobject identifier field of theprivateKeyAlgorithmPrivateKeyAlgorithm field of privateKeyInfo is not equal to thersaEncryptionobject identifier defined in [RFC3447], then throw aDataError. -
Let rsaPrivateKey be the result of performing the parse an ASN.1 structure algorithm, with data as the
privateKeyfield of privateKeyInfo, structure as theRSAPrivateKeystructure specified in Section A.1.2 of [RFC3447], and exactData set to true. -
If an error occurred while parsing, or if rsaPrivateKey is not a valid RSA private key according to [RFC3447], then throw a
DataError. -
Let key be a new
CryptoKeythat represents the RSA private key identified by rsaPrivateKey.
-
- If format is "
jwk": -
-
- If keyData is a
JsonWebKeydictionary: Let jwk equal keyData.
- Otherwise:
- If keyData is a
-
If the
dfield of jwk is present and usages contains an entry which is not "decrypt" or "unwrapKey", then throw aSyntaxError. -
If the
dfield of jwk is not present and usages contains an entry which is not "encrypt" or "wrapKey", then throw aSyntaxError. -
If the
ktyfield of jwk is not a case-sensitive string match to "RSA", then throw aDataError. -
If usages is non-empty and the
usefield of jwk is present and is not a case-sensitive string match to "enc", then throw aDataError. -
If the
key_opsfield of jwk is present, and is invalid according to the requirements of JSON Web Key [JWK] or does not contain all of the specified usages values, then throw aDataError. -
If the
extfield of jwk is present and has the value false and extractable is true, then throw aDataError. -
- If the
algfield of jwk is not present: - Let hash be undefined.
-
If the
algfield of jwk is equal to "RSA-OAEP": - Let hash be the string "
SHA-1". -
If the
algfield of jwk is equal to "RSA-OAEP-256": - Let hash be the string "
SHA-256". -
If the
algfield of jwk is equal to "RSA-OAEP-384": - Let hash be the string "
SHA-384". -
If the
algfield of jwk is equal to "RSA-OAEP-512": - Let hash be the string "
SHA-512". - Otherwise:
-
-
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.
-
- If the
-
- If hash is not undefined:
-
-
Let normalizedHash be the result of normalize an algorithm with
algset to hash andopset todigest. -
If normalizedHash is not equal to the
hashmember of normalizedAlgorithm, throw aDataError.
-
-
- If the
dfield of jwk is present: -
-
If jwk does not meet the requirements of Section 6.3.2 of JSON Web Algorithms [JWA], then throw a
DataError. -
Let privateKey represent the RSA private key identified by interpreting jwk according to Section 6.3.2 of JSON Web Algorithms [JWA].
-
If privateKey can be determined to not be a valid RSA private key according to [RFC3447], then throw a
DataError. -
Let key be a new
CryptoKeyrepresenting privateKey.
-
- Otherwise:
-
-
If jwk does not meet the requirements of Section 6.3.1 of JSON Web Algorithms [JWA], 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 [JWA].
-
If publicKey can be determined to not be a valid RSA public key according to [RFC3447], then throw a
DataError. -
Let key be a new
CryptoKeyrepresenting publicKey. -
Set the
[[type]]internal slot of key to "public"
-
- If the
-
- Otherwise:
-
throw a
NotSupportedError.
- If format is "
-
Let algorithm be a new
RsaHashedKeyAlgorithm. -
Set the
nameattribute of algorithm to "RSA-OAEP" -
Set the
modulusLengthattribute of algorithm to the length, in bits, of the RSA public modulus. -
Set the
publicExponentattribute of algorithm to theBigIntegerrepresentation of the RSA public exponent. -
Set the
hashattribute of algorithm to thehashmember 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 anOperationError. -
- If format is "
spki" -
-
If the
[[type]]internal slot of key is not "public", then throw anInvalidAccessError. -
Let data be an instance of the
SubjectPublicKeyInfoASN.1 structure defined in [RFC5280] with the following properties:-
Set the algorithm field to an
AlgorithmIdentifierASN.1 type with the following properties:-
Set the algorithm field to the OID
rsaEncryptiondefined in [RFC3447]. -
Set the params field to the ASN.1 type NULL.
-
-
Set the subjectPublicKey field to the result of DER-encoding an
RSAPublicKeyASN.1 type, as defined in [RFC3447], Appendix A.1.1, that represents the RSA public key represented by the[[handle]]internal slot of key
-
-
Let result be the result of DER-encoding data.
-
- If format is "
pkcs8": -
-
If the
[[type]]internal slot of key is not "private", then throw anInvalidAccessError. -
Let data be an instance of the
PrivateKeyInfoASN.1 structure defined in [RFC5208] with the following properties:-
Set the version field to
0. -
Set the privateKeyAlgorithm field to a
PrivateKeyAlgorithmIdentifierASN.1 type with the following properties:-
Set the algorithm field to the OID
rsaEncryptiondefined in [RFC3447]. -
Set the params field to the ASN.1 type NULL.
-
-
Set the privateKey field to the result of DER-encoding an
RSAPrivateKeyASN.1 type, as defined in [RFC3447], Appendix A.1.2, that represents the RSA private key represented by the[[handle]]internal slot of keyNote[RFC5208] specifies that the encoding of this field should be BER encoded in Section 5 (as a "for example"). However, to avoid requiring WebCrypto implementations support BER-encoding and BER-decoding, only DER encodings are produced or accepted.
-
-
Let result be the result of DER-encoding data.
-
- If format is "
jwk": -
-
Let jwk be a new
JsonWebKeydictionary. -
Set the
ktyattribute of jwk to the string "RSA". -
Let hash be the
nameattribute of thehashattribute of the[[algorithm]]internal slot of key. -
-
If hash is "
SHA-1": -
Set the
algattribute of jwk to the string "RSA-OAEP". -
If hash is "
SHA-256": -
Set the
algattribute of jwk to the string "RSA-OAEP-256". -
If hash is "
SHA-384": -
Set the
algattribute of jwk to the string "RSA-OAEP-384". -
If hash is "
SHA-512": -
Set the
algattribute of jwk to the string "RSA-OAEP-512". - Otherwise:
-
-
Perform any key export steps defined by other applicable specifications, passing format and the
hashattribute of the[[algorithm]]internal slot of key and obtaining alg. -
Set the
algattribute of jwk to alg.
-
-
If hash is "
-
Set the attributes
nandeof jwk according to the corresponding definitions in JSON Web Algorithms [JWA], Section 6.3.1. -
-
If the
[[type]]internal slot of key is "private": -
-
Set the attributes named
d,p,q,dp,dq, andqiof jwk according to the corresponding definitions in JSON Web Algorithms [JWA], Section 6.3.2. -
If the underlying RSA private key represented by the
[[handle]]internal slot of key is represented by more than two primes, set the attribute namedothof jwk according to the corresponding definition in JSON Web Algorithms [JWA], Section 6.3.2.7
-
-
If the
-
Set the
key_opsattribute of jwk to theusagesattribute of key. -
Set the
extattribute of jwk to the[[extractable]]internal slot of key. -
Let result be jwk.
-
- Otherwise
- If format is "
-
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 |
byte sequence |
| verify | EcdsaParams |
boolean |
| generateKey | EcKeyGenParams |
CryptoKeyPair |
| importKey | EcKeyImportParams |
CryptoKey |
| exportKey | None | object |
WebIDLdictionary EcdsaParams : Algorithm {
required HashAlgorithmIdentifier hash;
};
The hash member represents the hash algorithm to use.
WebIDLtypedef DOMString NamedCurve;
dictionary EcKeyGenParams : Algorithm {
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" - NIST recommended curve P-256, also known as
secp256r1. - "
P-384" - NIST recommended curve P-384, also known as
secp384r1. - "
P-521" - NIST recommended curve P-521, also known as
secp521r1.
Other specifications may define additional values.
The namedCurve member of the EcKeyGenParams dictionary represents a named curve.
WebIDLdictionary EcKeyAlgorithm : KeyAlgorithm {
required NamedCurve namedCurve;
};
The namedCurve member represents the named curve that the key uses.
WebIDLdictionary EcKeyImportParams : Algorithm {
required NamedCurve namedCurve;
};
The namedCurve member represents a named curve.
-
If the
[[type]]internal slot of key is not "private", then throw anInvalidAccessError. -
Let hashAlgorithm be the
hashmember 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.
-
-
If the
namedCurveattribute of the[[algorithm]]internal slot of key is "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 an empty byte sequence.
-
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 a byte sequence of length n and append it to result.
-
Convert s to a byte sequence of length n and append it to result.
-
-
Otherwise, the
namedCurveattribute of the[[algorithm]]internal slot of key is a value specified in an applicable specification: -
Perform the ECDSA signature steps specified in that specification, passing in M, params and d and resulting in result.
-
If the
-
Return result.
-
If the
[[type]]internal slot of key is not "public", then throw anInvalidAccessError. -
Let hashAlgorithm be the
hashmember 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.
-
-
If the
namedCurveattribute of the[[algorithm]]internal slot of key is "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.
-
Otherwise, the
namedCurveattribute of the[[algorithm]]internal slot of key is a value specified in an applicable specification: -
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.
-
If the
-
Let result be a boolean with the value
trueif the signature is valid and the valuefalseotherwise. -
Return result.
-
If usages contains a value which is not one of "
sign" or "verify", then throw aSyntaxError. -
-
If the
namedCurvemember of normalizedAlgorithm is "P-256", "P-384" or "P-521": -
Generate an Elliptic Curve key pair, as defined in [RFC6090] with domain parameters for the curve identified by the
namedCurvemember of normalizedAlgorithm. -
If the
namedCurvemember of normalizedAlgorithm is a value specified in an applicable specification: -
Perform the ECDSA generation steps specified in that specification, passing in normalizedAlgorithm and resulting in an elliptic curve key pair.
- Otherwise:
-
If the
-
If performing the key generation operation results in an error, then throw an
OperationError. -
Let algorithm be a new
EcKeyAlgorithmobject. -
Set the
nameattribute of algorithm to "ECDSA". -
Set the
namedCurveattribute of algorithm to equal thenamedCurvemember of normalizedAlgorithm. -
Let publicKey be a new
CryptoKeyrepresenting 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
CryptoKeyrepresenting the private key of the generated key pair. -
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
CryptoKeyPairdictionary. -
Set the
publicKeyattribute of result to be publicKey. -
Set the
privateKeyattribute of result to be privateKey. -
Return result.
-
Let keyData be the key data to be imported.
-
- If format is "
spki": -
-
If usages contains a value which is not "
verify" then throw aSyntaxError. -
Let spki be the result of running the parse a subjectPublicKeyInfo algorithm over keyData
-
If the
algorithmobject identifier field of thealgorithmAlgorithmIdentifier field of spki is not equal to theid-ecPublicKeyobject identifier defined in [RFC5480], then throw aDataError. -
If the
parametersfield of thealgorithmAlgorithmIdentifier field of spki is absent, then throw aDataError. -
Let params be the
parametersfield of thealgorithmAlgorithmIdentifier field of spki. -
If params is not an instance of the
ECParametersASN.1 type defined in [RFC5480] that specifies anamedCurve, then throw aDataError. -
Let namedCurve be a string whose initial value is undefined.
-
-
If params is equivalent to the
secp256r1object identifier defined in [RFC5480]: -
Set namedCurve "
P-256". -
If params is equivalent to the
secp384r1object identifier defined in [RFC5480]: -
Set namedCurve "
P-384". -
If params is equivalent to the
secp521r1object identifier defined in [RFC5480]: -
Set namedCurve "
P-521".
-
If params is equivalent to the
-
- If namedCurve is not undefined:
-
-
Let publicKey be the Elliptic Curve public key identified by performing the conversion steps defined in Section 2.3.4 of [SEC1] using the
subjectPublicKeyfield 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
CryptoKeythat represents publicKey.
-
- Otherwise:
-
-
Perform any key import steps defined by other applicable specifications, passing format, spki and obtaining namedCurve and key.
-
If an error occurred or there are no applicable specifications, throw a
DataError.
-
-
If namedCurve is defined, and not equal to the
namedCurvemember of normalizedAlgorithm, throw aDataError. -
If the public key value is not a valid point on the Elliptic Curve identified by the
namedCurvemember of normalizedAlgorithm throw aDataError. -
Set the
[[type]]internal slot of key to "public" -
Let algorithm be a new
EcKeyAlgorithm. -
Set the
nameattribute of algorithm to "ECDSA". -
Set the
namedCurveattribute of algorithm to namedCurve. -
Set the
[[algorithm]]internal slot of key to algorithm.
-
- If format is "
pkcs8": -
-
If usages contains a value which is not "
sign" then throw aSyntaxError. -
Let privateKeyInfo be the result of running the parse a privateKeyInfo algorithm over keyData.
-
If the
algorithmobject identifier field of theprivateKeyAlgorithmPrivateKeyAlgorithm field of privateKeyInfo is not equal to theid-ecPublicKeyobject identifier defined in [RFC5480], then throw aDataError. -
If the
parametersfield of theprivateKeyAlgorithmPrivateKeyAlgorithmIdentifier field of privateKeyInfo is not present, then throw aDataError. -
Let params be the
parametersfield of theprivateKeyAlgorithmPrivateKeyAlgorithmIdentifier field of privateKeyInfo. -
If params is not an instance of the
ECParametersASN.1 type defined in [RFC5480] that specifies anamedCurve, then throw aDataError. -
Let namedCurve be a string whose initial value is undefined.
-
-
If params is equivalent to the
secp256r1object identifier defined in [RFC5480]: -
Set namedCurve "
P-256". -
If params is equivalent to the
secp384r1object identifier defined in [RFC5480]: -
Set namedCurve "
P-384". -
If params is equivalent to the
secp521r1object identifier defined in [RFC5480]: -
Set namedCurve "
P-521".
-
If params is equivalent to the
-
- If namedCurve is not undefined:
-
-
Let ecPrivateKey be the result of performing the parse an ASN.1 structure algorithm, with data as the
privateKeyfield of privateKeyInfo, structure as the ASN.1ECPrivateKeystructure specified in Section 3 of [RFC5915], and exactData set to true. -
If the
parametersfield of ecPrivateKey is present, and is not an instance of thenamedCurveASN.1 type defined in [RFC5480], or does not contain the same object identifier as theparametersfield of theprivateKeyAlgorithmPrivateKeyAlgorithmIdentifier field of privateKeyInfo, then throw aDataError. -
Let key be a new
CryptoKeythat represents the Elliptic Curve private key identified by performing the conversion steps defined in Section 3 of [RFC5915] using ecPrivateKey.
-
- Otherwise:
-
-
Perform any key import steps defined by other applicable specifications, passing format, privateKeyInfo and obtaining namedCurve and key.
-
If an error occurred or there are no applicable specifications, throw a
DataError.
-
-
If namedCurve is defined, and not equal to the
namedCurvemember of normalizedAlgorithm, throw aDataError. -
If the private key value is not a valid point on the Elliptic Curve identified by the
namedCurvemember of normalizedAlgorithm throw aDataError. -
Let algorithm be a new
EcKeyAlgorithm. -
Set the
nameattribute of algorithm to "ECDSA". -
Set the
namedCurveattribute of algorithm to namedCurve. -
Set the
[[algorithm]]internal slot of key to algorithm.
-
- If format is "
jwk": -
-
- If keyData is a
JsonWebKeydictionary: Let jwk equal keyData.
- Otherwise:
- If keyData is a
-
If the
dfield is present and usages contains a value which is not "sign", or, if thedfield is not present and usages contains a value which is not "verify" then throw aSyntaxError. -
If the
ktyfield of jwk is not "EC", then throw aDataError. -
If usages is non-empty and the
usefield of jwk is present and is not "sig", then throw aDataError. -
If the
key_opsfield of jwk is present, and is invalid according to the requirements of JSON Web Key [JWK], or it does not contain all of the specified usages values, then throw aDataError. -
If the
extfield of jwk is present and has the value false and extractable is true, then throw aDataError. -
Let namedCurve be a string whose value is equal to the
crvfield of jwk. -
If namedCurve is not equal to the
namedCurvemember of normalizedAlgorithm, throw aDataError. -
-
If namedCurve is equal to "
P-256", "P-384" or "P-521": -
-
Let algNamedCurve be a string whose initial value is undefined.
-
- If the
algfield is not present: - Let algNamedCurve be undefined.
-
If the
algfield is equal to the string "ES256": -
Let algNamedCurve be the string "
P-256". -
If the
algfield is equal to the string "ES384": -
Let algNamedCurve be the string "
P-384". -
If the
algfield is equal to the string "ES512": -
Let algNamedCurve be the string "
P-521". - otherwise:
-
throw a
DataError.
- If the
-
If algNamedCurve is defined, and is not equal to namedCurve, throw a
DataError. -
- If the
dfield is present: - Otherwise:
-
-
If jwk does not meet the requirements of Section 6.2.1 of JSON Web Algorithms [JWA], then throw a
DataError. -
Let key be a new
CryptoKeyobject that represents the Elliptic Curve public key identified by interpreting jwk according to Section 6.2.1 of JSON Web Algorithms [JWA]. -
Set the
[[type]]internal slot of Key to "public".
-
- If the
-
- Otherwise:
-
-
Perform any key import steps defined by other applicable specifications, passing format, jwk and obtaining key.
-
If an error occurred or there are no applicable specifications, throw a
DataError.
-
-
If namedCurve is equal to "
-
If the key value is not a valid point on the Elliptic Curve identified by the
namedCurvemember of normalizedAlgorithm throw aDataError. -
Let algorithm be a new instance of an
EcKeyAlgorithmobject. -
Set the
nameattribute of algorithm to "ECDSA". -
Set the
namedCurveattribute of algorithm to namedCurve. -
Set the
[[algorithm]]internal slot of key to algorithm.
-
- If format is "
raw": -
-
If the
namedCurvemember of normalizedAlgorithm is not a named curve, then throw aDataError. -
If usages contains a value which is not "
verify" then throw aSyntaxError. -
-
If namedCurve is "
P-256", "P-384" or "P-521": -
-
Let Q be the elliptic curve point on the curve identified by the
namedCurvemember of normalizedAlgorithm identified by performing the conversion steps defined in Section 2.3.4 of [SEC1] 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
CryptoKeythat represents Q.
-
- Otherwise:
-
-
Perform any key import steps defined by other applicable specifications, passing format, keyData and obtaining key.
-
If an error occurred or there are no applicable specifications, throw a
DataError.
-
-
If namedCurve is "
-
Let algorithm be a new
EcKeyAlgorithmobject. -
Set the
nameattribute of algorithm to "ECDSA". -
Set the
namedCurveattribute of algorithm to equal thenamedCurvemember of normalizedAlgorithm. -
Set the
[[type]]internal slot of key to "public" -
Set the
[[algorithm]]internal slot of key to algorithm.
-
- Otherwise:
- If format is "
-
Return key
-
Let key be the
CryptoKeyto be exported. -
If the underlying cryptographic key material represented by the
[[handle]]internal slot of key cannot be accessed, then throw anOperationError. -
- If format is "
spki": -
-
If the
[[type]]internal slot of key is not "public", then throw anInvalidAccessError. -
Let data be an instance of the
SubjectPublicKeyInfoASN.1 structure defined in [RFC5280] with the following properties:-
Set the algorithm field to an
AlgorithmIdentifierASN.1 type with the following properties:-
Set the algorithm field to the OID
id-ecPublicKeydefined in [RFC5480]. -
Set the parameters field to an instance of the
ECParametersASN.1 type defined in [RFC5480] as follows:-
If the
namedCurveattribute of the[[algorithm]]internal slot of key is "P-256", "P-384" or "P-521": -
Let keyData be the byte sequence 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 [RFC5480] and using the uncompressed form. and keyData.-
If the
namedCurveattribute of the[[algorithm]]internal slot of key is "P-256": -
Set parameters to the
namedCurvechoice with value equal to the object identifiersecp256r1defined in [RFC5480] -
If the
namedCurveattribute of the[[algorithm]]internal slot of key is "P-384": -
Set parameters to the
namedCurvechoice with value equal to the object identifiersecp384r1defined in [RFC5480] -
If the
namedCurveattribute of the[[algorithm]]internal slot of key is "P-521": -
Set parameters to the
namedCurvechoice with value equal to the object identifiersecp521r1defined in [RFC5480]
-
If the
- Otherwise:
-
-
Perform any key export steps defined by other applicable specifications, passing format and the
namedCurveattribute of the[[algorithm]]internal slot of key and obtaining namedCurveOid and keyData. -
Set parameters to the
namedCurvechoice with value equal to the object identifier namedCurveOid.
-
-
If the
-
-
Set the subjectPublicKey field to keyData.
-
-
Let result be the result of DER-encoding data.
-
- If format is "
pkcs8": -
-
If the
[[type]]internal slot of key is not "private", then throw anInvalidAccessError. -
Let data be an instance of the
PrivateKeyInfoASN.1 structure defined in [RFC5208] with the following properties:-
Set the version field to
0. -
Set the privateKeyAlgorithm field to a
PrivateKeyAlgorithmIdentifierASN.1 type with the following properties:-
Set the algorithm field to the OID
id-ecPublicKeydefined in [RFC5480]. -
Set the parameters field to an instance of the
ECParametersASN.1 type defined in [RFC5480] as follows:-
If the
namedCurveattribute of the[[algorithm]]internal slot of key is "P-256", "P-384" or "P-521": -
Let keyData be the result of DER-encoding an instance of the
ECPrivateKeystructure defined in Section 3 of [RFC5915] 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
PrivateKeyInfoASN.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.
-
If the
namedCurveattribute of the[[algorithm]]internal slot of key is "P-256": -
Set parameters to the
namedCurvechoice with value equal to the object identifiersecp256r1defined in [RFC5480] -
If the
namedCurveattribute of the[[algorithm]]internal slot of key is "P-384": -
Set parameters to the
namedCurvechoice with value equal to the object identifiersecp384r1defined in [RFC5480] -
If the
namedCurveattribute of the[[algorithm]]internal slot of key is "P-521": -
Set parameters to the
namedCurvechoice with value equal to the object identifiersecp521r1defined in [RFC5480]
-
- Otherwise:
-
-
Perform any key export steps defined by other applicable specifications, passing format and the
namedCurveattribute of the[[algorithm]]internal slot of key and obtaining namedCurveOid and keyData. -
Set parameters to the
namedCurvechoice with value equal to the object identifier namedCurveOid.
-
-
If the
-
-
Set the privateKey field to keyData.
-
-
Let result be the result of DER-encoding data.
-
- If format is "
jwk": -
-
Let jwk be a new
JsonWebKeydictionary. -
Set the
ktyattribute of jwk to "EC". -
-
If the
namedCurveattribute of the[[algorithm]]internal slot of key is "P-256", "P-384" or "P-521": -
-
-
If the
namedCurveattribute of the[[algorithm]]internal slot of key is "P-256": -
Set the
crvattribute of jwk to "P-256" -
If the
namedCurveattribute of the[[algorithm]]internal slot of key is "P-384": -
Set the
crvattribute of jwk to "P-384" -
If the
namedCurveattribute of the[[algorithm]]internal slot of key is "P-521": -
Set the
crvattribute of jwk to "P-521"
-
If the
-
Set the
xattribute of jwk according to the definition in Section 6.2.1.2 of JSON Web Algorithms [JWA]. -
Set the
yattribute of jwk according to the definition in Section 6.2.1.3 of JSON Web Algorithms [JWA].
-
- Otherwise:
-
-
Perform any key export steps defined by other applicable specifications, passing format and the
namedCurveattribute of the[[algorithm]]internal slot of key and obtaining namedCurve and a new value of jwk. -
Set the
crvattribute of jwk to namedCurve.
-
-
If the
-
Set the
key_opsattribute of jwk to theusagesattribute of key. -
Set the
extattribute of jwk to the[[extractable]]internal slot of key. -
Let result be jwk.
-
-
If format is "
raw": -
-
If the
[[type]]internal slot of key is not "public", then throw anInvalidAccessError. -
-
If the
namedCurveattribute of the[[algorithm]]internal slot of key is "P-256", "P-384" or "P-521": -
Let data be a byte sequence representing the Elliptic Curve point Q represented by the
[[handle]]internal slot of key according to [SEC1] 2.3.3 using the uncompressed format. - Otherwise:
-
Perform any key export steps defined by other applicable specifications, passing format and the
namedCurveattribute of the[[algorithm]]internal slot of key and obtaining namedCurve and data.
-
If the
-
Let result be data.
-
- Otherwise:
- If format is "
-
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 |
byte sequence |
| importKey | EcKeyImportParams |
CryptoKey |
| exportKey | None | object |
WebIDLdictionary EcdhKeyDeriveParams : Algorithm {
required CryptoKey public;
};
The public member represents the peer's EC public key.
-
If usages contains an entry which is not "
deriveKey" or "deriveBits" then throw aSyntaxError. -
-
If the
namedCurvemember of normalizedAlgorithm is "P-256", "P-384" or "P-521": -
Generate an Elliptic Curve key pair, as defined in [RFC6090] with domain parameters for the curve identified by the
namedCurvemember of normalizedAlgorithm. -
If the
namedCurvemember of normalizedAlgorithm is a value specified in an applicable specification that specifies the use of that value with ECDH: -
Perform the ECDH generation steps specified in that specification, passing in normalizedAlgorithm and resulting in an elliptic curve key pair.
- Otherwise:
-
If the
-
If performing the operation results in an error, then throw a
OperationError. -
Let algorithm be a new
EcKeyAlgorithmobject. -
Set the
namemember of algorithm to "ECDH". -
Set the
namedCurveattribute of algorithm to equal thenamedCurvemember of normalizedAlgorithm. -
Let publicKey be a new
CryptoKeyrepresenting 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
CryptoKeyrepresenting the private key of the generated key pair. -
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
CryptoKeyPairdictionary. -
Set the
publicKeyattribute of result to be publicKey. -
Set the
privateKeyattribute of result to be privateKey. -
Return result.
-
If the
[[type]]internal slot of key is not "private", then throw anInvalidAccessError. -
Let publicKey be the
publicmember of normalizedAlgorithm. -
If the
[[type]]internal slot of publicKey is not "public", then throw anInvalidAccessError. -
If the
nameattribute of the[[algorithm]]internal slot of publicKey is not equal to thenameproperty of the[[algorithm]]internal slot of key, then throw anInvalidAccessError. -
If the
namedCurveattribute of the[[algorithm]]internal slot of publicKey is not equal to thenamedCurveproperty of the[[algorithm]]internal slot of key, then throw anInvalidAccessError. -
-
If the
namedCurveproperty of the[[algorithm]]internal slot of key is "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 a byte sequence containing the result of applying the field element to octet string conversion defined in Section 6.2 of [RFC6090] to the output of the ECDH primitive.
-
-
If the
namedCurveproperty of the[[algorithm]]internal slot of key is a value specified in an applicable specification that specifies the use of that value with ECDH: -
Perform the ECDH derivation steps specified in that specification, passing in key and publicKey and resulting in secret.
- Otherwise:
-
If the
-
If performing the operation results in an error, then throw a
OperationError. -
- If length is null:
- Return secret
- Otherwise:
-
- If the length in bits of secret is less than length:
-
throw an
OperationError. - Otherwise:
- Return a byte sequence containing the first length bits of secret.
-
Let keyData be the key data to be imported.
-
- If format is "
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
algorithmobject identifier field of thealgorithmAlgorithmIdentifier field of spki is not equal to theid-ecPublicKeyobject identifier defined in [RFC5480], then throw aDataError. -
If the
parametersfield of thealgorithmAlgorithmIdentifier field of spki is absent, then throw aDataError. -
Let params be the
parametersfield of thealgorithmAlgorithmIdentifier field of spki. -
If params is not an instance of the
ECParametersASN.1 type defined in [RFC5480] that specifies anamedCurve, then throw aDataError. -
Let namedCurve be a string whose initial value is undefined.
-
-
If params is equivalent to the
secp256r1object identifier defined in [RFC5480]: -
Set namedCurve "
P-256". -
If params is equivalent to the
secp384r1object identifier defined in [RFC5480]: -
Set namedCurve "
P-384". -
If params is equivalent to the
secp521r1object identifier defined in [RFC5480]: -
Set namedCurve "
P-521".
-
If params is equivalent to the
-
- If namedCurve is not undefined:
-
-
Let publicKey be the Elliptic Curve public key identified by performing the conversion steps defined in Section 2.3.4 of [SEC1] to the
subjectPublicKeyfield 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
CryptoKeythat represents publicKey.
-
- Otherwise:
-
-
Perform any key import steps defined by other applicable specifications, passing format, spki and obtaining namedCurve and key.
-
If an error occurred or there are no applicable specifications, throw a
DataError.
-
-
If namedCurve is defined, and not equal to the
namedCurvemember of normalizedAlgorithm, throw aDataError. -
If the key value is not a valid point on the Elliptic Curve identified by the
namedCurvemember of normalizedAlgorithm throw aDataError. -
Set the
[[type]]internal slot of key to "public" -
Let algorithm be a new
EcKeyAlgorithm. -
Set the
nameattribute of algorithm to "ECDH". -
Set the
namedCurveattribute of algorithm to namedCurve. -
Set the
[[algorithm]]internal slot of key to algorithm.
-
- If format is "
pkcs8": -
-
If usages contains an entry which is not "
deriveKey" or "deriveBits" then throw aSyntaxError. -
Let privateKeyInfo be the result of running the parse a privateKeyInfo algorithm over keyData.
-
If the
algorithmobject identifier field of theprivateKeyAlgorithmPrivateKeyAlgorithm field of privateKeyInfo is not equal to theid-ecPublicKeyobject identifier defined in [RFC5480], throw aDataError. -
If the
parametersfield of theprivateKeyAlgorithmPrivateKeyAlgorithmIdentifier field of privateKeyInfo is not present, throw aDataError. -
Let params be the
parametersfield of theprivateKeyAlgorithmPrivateKeyAlgorithmIdentifier field of privateKeyInfo. -
If params is not an instance of the
ECParametersASN.1 type defined in [RFC5480] that specifies anamedCurve, then throw aDataError. -
Let namedCurve be a string whose initial value is undefined.
-
-
If params is equivalent to the
secp256r1object identifier defined in [RFC5480]: -
Set namedCurve to "
P-256". -
If params is equivalent to the
secp384r1object identifier defined in [RFC5480]: -
Set namedCurve to "
P-384". -
If params is equivalent to the
secp521r1object identifier defined in [RFC5480]: -
Set namedCurve to "
P-521".
-
If params is equivalent to the
-
- If namedCurve is not undefined:
-
-
Let ecPrivateKey be the result of performing the parse an ASN.1 structure algorithm, with data as the
privateKeyfield of privateKeyInfo, structure as the ASN.1ECPrivateKeystructure specified in Section 3 of [RFC5915], and exactData set to true. -
If the
parametersfield of ecPrivateKey is present, and is not an instance of thenamedCurveASN.1 type defined in [RFC5480], or does not contain the same object identifier as theparametersfield of theprivateKeyAlgorithmPrivateKeyAlgorithmIdentifier field of privateKeyInfo, throw aDataError. -
Let key be a new
CryptoKeythat represents the Elliptic Curve private key identified by performing the conversion steps defined in Section 3 of [RFC5915] using ecPrivateKey.
-
- Otherwise:
-
-
Perform any key import steps defined by other applicable specifications, passing format, privateKeyInfo and obtaining namedCurve and key.
-
If an error occurred or there are no applicable specifications, throw a
DataError.
-
-
If namedCurve is defined, and not equal to the
namedCurvemember of normalizedAlgorithm, throw aDataError. -
If the key value is not a valid point on the Elliptic Curve identified by the
namedCurvemember of normalizedAlgorithm throw aDataError. -
Let algorithm be a new
EcKeyAlgorithm. -
Set the
nameattribute of algorithm to "ECDH". -
Set the
namedCurveattribute of algorithm to namedCurve. -
Set the
[[algorithm]]internal slot of key to algorithm.
-
- If format is "
jwk": -
-
- If keyData is a
JsonWebKeydictionary: Let jwk equal keyData.
- Otherwise:
- If keyData is a
-
If the
dfield is present and if usages contains an entry which is not "deriveKey" or "deriveBits" then throw aSyntaxError. -
If the
dfield is not present and if usages is not empty then throw aSyntaxError. -
If the
ktyfield of jwk is not "EC", then throw aDataError. -
If usages is non-empty and the
usefield of jwk is present and is not equal to "enc" then throw aDataError. -
If the
key_opsfield of jwk is present, and is invalid according to the requirements of JSON Web Key [JWK], or it does not contain all of the specified usages values, then throw aDataError. -
If the
extfield of jwk is present and has the value false and extractable is true, then throw aDataError. -
Let namedCurve be a string whose value is equal to the
crvfield of jwk. -
If namedCurve is not equal to the
namedCurvemember of normalizedAlgorithm, throw aDataError. -
-
If namedCurve is "
P-256", "P-384" or "P-521": -
- If the
dfield is present: - Otherwise:
-
-
If jwk does not meet the requirements of Section 6.2.1 of JSON Web Algorithms [JWA], then throw a
DataError. -
Let key be a new
CryptoKeyobject that represents the Elliptic Curve public key identified by interpreting jwk according to Section 6.2.1 of JSON Web Algorithms [JWA]. -
Set the
[[type]]internal slot of Key to "public".
-
- If the
- Otherwise
-
-
Perform any key import steps defined by other applicable specifications, passing format, jwk and obtaining key.
-
If an error occurred or there are no applicable specifications, throw a
DataError.
-
-
If namedCurve is "
-
If the key value is not a valid point on the Elliptic Curve identified by the
namedCurvemember of normalizedAlgorithm throw aDataError. -
Let algorithm be a new instance of an
EcKeyAlgorithmobject. -
Set the
nameattribute of algorithm to "ECDH". -
Set the
namedCurveattribute of algorithm to namedCurve. -
Set the
[[algorithm]]internal slot of key to algorithm.
-
- If format is "
raw": -
-
If the
namedCurvemember of normalizedAlgorithm is not a named curve, then throw aDataError. -
If usages is not the empty list, then throw a
SyntaxError. -
-
If namedCurve is "
P-256", "P-384" or "P-521": -
-
Let Q be the Elliptic Curve public key on the curve identified by the
namedCurvemember of normalizedAlgorithm identified by performing the conversion steps defined in Section 2.3.4 of [SEC1] 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
CryptoKeythat represents Q.
-
- Otherwise:
-
-
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.
-
-
If namedCurve is "
-
Let algorithm be a new
EcKeyAlgorithmobject. -
Set the
nameattribute of algorithm to "ECDH". -
Set the
namedCurveattribute of algorithm to equal thenamedCurvemember of normalizedAlgorithm. -
Set the
[[type]]internal slot of key to "public" -
Set the
[[algorithm]]internal slot of key to algorithm.
-
- If format is "
-
Return key
-
Let key be the
CryptoKeyto be exported. -
If the underlying cryptographic key material represented by the
[[handle]]internal slot of key cannot be accessed, then throw anOperationError. -
- If format is "
spki": -
-
If the
[[type]]internal slot of key is not "public", then throw anInvalidAccessError. -
Let data be an instance of the
SubjectPublicKeyInfoASN.1 structure defined in [RFC5280] with the following properties:-
Set the algorithm field to an
AlgorithmIdentifierASN.1 type with the following properties:-
Set the algorithm field to the OID
id-ecPublicKeydefined in [RFC5480]. -
Set the parameters field to an instance of the
ECParametersASN.1 type defined in [RFC5480] as follows:-
If the
namedCurveattribute of the[[algorithm]]internal slot of key is "P-256", "P-384" or "P-521": -
Let keyData be the byte sequence 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 [SEC1] and using the uncompressed form.-
If the
namedCurveattribute of the[[algorithm]]internal slot of key is "P-256": -
Set parameters to the namedCurve choice with value equal to the object identifier
secp256r1defined in [RFC5480] -
If the
namedCurveattribute of the[[algorithm]]internal slot of key is "P-384": -
Set parameters to the namedCurve choice with value equal to the object identifier
secp384r1defined in [RFC5480] -
If the
namedCurveattribute of the[[algorithm]]internal slot of key is "P-521": -
Set parameters to the namedCurve choice with value equal to the object identifier
secp521r1defined in [RFC5480]
-
If the
- Otherwise:
-
-
Perform any key export steps defined by other applicable specifications, passing format and the
namedCurveattribute of the[[algorithm]]internal slot of key and obtaining namedCurveOid and keyData. -
Set parameters to the
namedCurvechoice with value equal to the object identifier namedCurveOid.
-
-
If the
-
-
Set the subjectPublicKey field to keyData
-
-
- If format is "
pkcs8": -
-
If the
[[type]]internal slot of key is not "private", then throw anInvalidAccessError. -
Let data be an instance of the
PrivateKeyInfoASN.1 structure defined in [RFC5208] with the following properties:-
Set the version field to
0. -
Set the privateKeyAlgorithm field to a
PrivateKeyAlgorithmIdentifierASN.1 type with the following properties:-
Set the algorithm field to the OID
id-ecPublicKeydefined in [RFC5480]. -
Set the parameters field to an instance of the
ECParametersASN.1 type defined in [RFC5480] as follows:-
If the
namedCurveattribute of the[[algorithm]]internal slot of key is "P-256", "P-384" or "P-521": -
Let keyData be the result of DER-encoding an instance of the
ECPrivateKeystructure defined in Section 3 of [RFC5915] 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
PrivateKeyInfoASN.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.
-
If the
namedCurveattribute of the[[algorithm]]internal slot of key is "P-256": -
Set parameters to the namedCurve choice with value equal to the object identifier
secp256r1defined in [RFC5480] -
If the
namedCurveattribute of the[[algorithm]]internal slot of key is "P-384": -
Set parameters to the namedCurve choice with value equal to the object identifier
secp384r1defined in [RFC5480] -
If the
namedCurveattribute of the[[algorithm]]internal slot of key is "P-521": -
Set parameters to the namedCurve choice with value equal to the object identifier
secp521r1defined in [RFC5480]
-
- Otherwise:
-
-
Perform any key export steps defined by other applicable specifications, passing format and the
namedCurveattribute of the[[algorithm]]internal slot of key and obtaining namedCurveOid and keyData. -
Set parameters to the
namedCurvechoice with value equal to the object identifier namedCurveOid.
-
-
If the
-
-
Set the privateKey field to keyData.
-
-
- If format is "
jwk": -
-
Let jwk be a new
JsonWebKeydictionary. -
Set the
ktyattribute of jwk to "EC". -
-
If the
namedCurveattribute of the[[algorithm]]internal slot of key is "P-256", "P-384" or "P-521": -
-
-
If the
namedCurveattribute of the[[algorithm]]internal slot of key is "P-256": -
Set the
crvattribute of jwk to "P-256" -
If the
namedCurveattribute of the[[algorithm]]internal slot of key is "P-384": -
Set the
crvattribute of jwk to "P-384" -
If the
namedCurveattribute of the[[algorithm]]internal slot of key is "P-521": -
Set the
crvattribute of jwk to "P-521"
-
If the
-
Set the
xattribute of jwk according to the definition in Section 6.2.1.2 of JSON Web Algorithms [JWA]. -
Set the
yattribute of jwk according to the definition in Section 6.2.1.3 of JSON Web Algorithms [JWA].
-
- Otherwise:
-
-
Perform any key export steps defined by other applicable specifications, passing format and the
namedCurveattribute of the[[algorithm]]internal slot of key and obtaining namedCurve and a new value of jwk. -
Set the
crvattribute of jwk to namedCurve.
-
-
If the
-
Set the
key_opsattribute of jwk to theusagesattribute of key. -
Set the
extattribute of jwk to the[[extractable]]internal slot of key. -
Let result be jwk.
-
-
If format is "
raw": -
-
If the
[[type]]internal slot of key is not "public", then throw anInvalidAccessError. -
-
If the
namedCurveattribute of the[[algorithm]]internal slot of key is "P-256", "P-384" or "P-521": -
Let data be the byte sequence 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 [SEC1] and using the uncompressed form. - Otherwise:
-
Perform any key export steps defined by other applicable specifications, passing format and the
namedCurveattribute of the[[algorithm]]internal slot of key and obtaining namedCurve and data.
-
If the
-
Let result be data.
-
- If format is "
-
Return result.
This section is non-normative.
The "Ed25519" algorithm identifier is used to perform signing
and verification using the Ed25519 algorithm specified in
[RFC8032].
The recognized algorithm name for
this algorithm is "Ed25519".
| Operation | Parameters | Result |
|---|---|---|
| sign | None | byte sequence |
| verify | None | boolean |
| generateKey | None | CryptoKeyPair |
| importKey | None | CryptoKey |
| exportKey | None | object |
-
If the
[[type]]internal slot of key is not "private", then throw anInvalidAccessError. -
Let result be the result of performing the Ed25519 signing process, as specified in [RFC8032], Section 5.1.6, with message as M, using the Ed25519 private key associated with key.
Issue 1Some implementations may (wish to) generate randomized signatures as per draft-irtf-cfrg-det-sigs-with-noise instead of deterministic signatures as per [RFC8032].
-
Return result.
-
If the
[[type]]internal slot of key is not "public", then throw anInvalidAccessError. -
If the key data of key represents an invalid point or a small-order element on the Elliptic Curve of Ed25519, return
false.Issue 2Not all implementations perform this check.
-
If the point R, encoded in the first half of signature, represents an invalid point or a small-order element on the Elliptic Curve of Ed25519, return
false.Issue 3Not all implementations perform this check.
-
Perform the Ed25519 verification steps, as specified in [RFC8032], Section 5.1.7, using the cofactorless (unbatched) equation,
[S]B = R + [k]A', on the signature, with message as M, using the Ed25519 public key associated with key. -
Let result be a boolean with the value
trueif the signature is valid and the valuefalseotherwise. -
Return result.
-
If usages contains a value which is not one of "
sign" or "verify", then throw aSyntaxError. -
Generate an Ed25519 key pair, as defined in [RFC8032], section 5.1.5.
-
Let algorithm be a new
KeyAlgorithmobject. -
Set the
nameattribute of algorithm to "Ed25519". -
Let publicKey be a new
CryptoKeyrepresenting 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
CryptoKeyrepresenting the private key of the generated key pair. -
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
CryptoKeyPairdictionary. -
Set the
publicKeyattribute of result to be publicKey. -
Set the
privateKeyattribute of result to be privateKey. -
Return result.
-
Let keyData be the key data to be imported.
-
- If format is "
spki": -
-
If usages contains a value which is not "
verify" then throw aSyntaxError. -
Let spki be the result of running the parse a subjectPublicKeyInfo algorithm over keyData.
-
If the
algorithmobject identifier field of thealgorithmAlgorithmIdentifier field of spki is not equal to theid-Ed25519object identifier defined in [RFC8410], then throw aDataError. -
If the
parametersfield of thealgorithmAlgorithmIdentifier field of spki is present, then throw aDataError. -
Let publicKey be the Ed25519 public key identified by the
subjectPublicKeyfield of spki. -
Let key be a new
CryptoKeythat represents publicKey. -
Set the
[[type]]internal slot of key to "public" -
Let algorithm be a new
KeyAlgorithm. -
Set the
nameattribute of algorithm to "Ed25519". -
Set the
[[algorithm]]internal slot of key to algorithm.
-
- If format is "
pkcs8": -
-
If usages contains a value which is not "
sign" then throw aSyntaxError. -
Let privateKeyInfo be the result of running the parse a privateKeyInfo algorithm over keyData.
-
If the
algorithmobject identifier field of theprivateKeyAlgorithmPrivateKeyAlgorithm field of privateKeyInfo is not equal to theid-Ed25519object identifier defined in [RFC8410], then throw aDataError. -
If the
parametersfield of theprivateKeyAlgorithmPrivateKeyAlgorithmIdentifier field of privateKeyInfo is present, then throw aDataError. -
Let curvePrivateKey be the result of performing the parse an ASN.1 structure algorithm, with data as the
privateKeyfield of privateKeyInfo, structure as the ASN.1CurvePrivateKeystructure specified in Section 7 of [RFC8410], and exactData set to true. -
Let key be a new
CryptoKeythat represents the Ed25519 private key identified by curvePrivateKey. -
Let algorithm be a new
KeyAlgorithm. -
Set the
nameattribute of algorithm to "Ed25519". -
Set the
[[algorithm]]internal slot of key to algorithm.
-
- If format is "
jwk": -
-
- If keyData is a
JsonWebKeydictionary: Let jwk equal keyData.
- Otherwise:
- If keyData is a
-
If the
dfield is present and usages contains a value which is not "sign", or, if thedfield is not present and usages contains a value which is not "verify" then throw aSyntaxError. -
If the
ktyfield of jwk is not "OKP", then throw aDataError. -
If the
crvfield of jwk is not "Ed25519", then throw aDataError. -
If the
algfield of jwk is present and is not "Ed25519" or "EdDSA", then throw aDataError. -
If usages is non-empty and the
usefield of jwk is present and is not "sig", then throw aDataError. -
If the
key_opsfield of jwk is present, and is invalid according to the requirements of JSON Web Key [JWK], or it does not contain all of the specified usages values, then throw aDataError. -
If the
extfield of jwk is present and has the value false and extractable is true, then throw aDataError. -
- If the
dfield is present: - Otherwise:
- If the
-
Let algorithm be a new instance of a
KeyAlgorithmobject. -
Set the
nameattribute of algorithm to "Ed25519". -
Set the
[[algorithm]]internal slot of key to algorithm.
-
- If format is "
raw": -
-
If usages contains a value which is not "
verify" then throw aSyntaxError. -
Let algorithm be a new
KeyAlgorithmobject. -
Set the
nameattribute of algorithm to "Ed25519". -
Let key be a new
CryptoKeyrepresenting the key data provided in keyData. -
Set the
[[type]]internal slot of key to "public" -
Set the
[[algorithm]]internal slot of key to algorithm.
-
- Otherwise:
- If format is "
-
Return key
-
Let key be the
CryptoKeyto be exported. -
If the underlying cryptographic key material represented by the
[[handle]]internal slot of key cannot be accessed, then throw anOperationError. -
- If format is "
spki": -
-
If the
[[type]]internal slot of key is not "public", then throw anInvalidAccessError. -
Let data be an instance of the
SubjectPublicKeyInfoASN.1 structure defined in [RFC5280] with the following properties:-
Set the algorithm field to an
AlgorithmIdentifierASN.1 type with the following properties:-
Set the algorithm object identifier to the
id-Ed25519OID defined in [RFC8410].
-
-
Set the subjectPublicKey field to keyData.
-
-
Let result be the result of DER-encoding data.
-
- If format is "
pkcs8": -
-
If the
[[type]]internal slot of key is not "private", then throw anInvalidAccessError. -
Let data be an instance of the
PrivateKeyInfoASN.1 structure defined in [RFC5208] with the following properties:-
Set the version field to
0. -
Set the privateKeyAlgorithm field to a
PrivateKeyAlgorithmIdentifierASN.1 type with the following properties:-
Set the algorithm object identifier to the
id-Ed25519OID defined in [RFC8410].
-
-
Set the privateKey field to the result of DER-encoding a
CurvePrivateKeyASN.1 type, as defined in Section 7 of [RFC8410], that represents the Ed25519 private key represented by the[[handle]]internal slot of key
-
-
Let result be the result of DER-encoding data.
-
- If format is "
jwk": -
-
Let jwk be a new
JsonWebKeydictionary. -
Set the
ktyattribute of jwk to "OKP". -
Set the
algattribute of jwk to "Ed25519". -
Set the
crvattribute of jwk to "Ed25519". -
Set the
xattribute of jwk according to the definition in Section 2 of [RFC8037]. -
Set the
key_opsattribute of jwk to theusagesattribute of key. -
Set the
extattribute of jwk to the[[extractable]]internal slot of key. -
Let result be jwk.
-
-
If format is "
raw": -
-
If the
[[type]]internal slot of key is not "public", then throw anInvalidAccessError. -
Let data be a byte sequence representing the Ed25519 public key represented by the
[[handle]]internal slot of key. -
Let result be data.
-
- Otherwise:
- If format is "
-
Return result.
This section is non-normative.
The "X25519" algorithm identifier is used to perform
key agreement using the X25519 algorithm specified in
[RFC7748].
The recognized algorithm name for
this algorithm is "X25519".
| Operation | Parameters | Result |
|---|---|---|
| deriveBits | EcdhKeyDeriveParams |
byte sequence |
| generateKey | None | CryptoKeyPair |
| importKey | None | CryptoKey |
| exportKey | None | object |
-
If the
[[type]]internal slot of key is not "private", then throw anInvalidAccessError. -
Let publicKey be the
publicmember of normalizedAlgorithm. -
If the
[[type]]internal slot of publicKey is not "public", then throw anInvalidAccessError. -
If the
nameattribute of the[[algorithm]]internal slot of publicKey is not equal to thenameproperty of the[[algorithm]]internal slot of key, then throw anInvalidAccessError. -
Let secret be the result of performing the X25519 function specified in [RFC7748] Section 5 with key as the X25519 private key k and the X25519 public key represented by the
[[handle]]internal slot of publicKey as the X25519 public key u. -
If secret is the all-zero value, then throw a
OperationError. This check must be performed in constant-time, as per [RFC7748] Section 6.1. -
- If length is null:
- Return secret
- Otherwise:
-
- If the length of secret in bits is less than length:
-
throw an
OperationError. - Otherwise:
- Return a byte sequence containing the first length bits of secret.
-
If usages contains an entry which is not "
deriveKey" or "deriveBits" then throw aSyntaxError. -
Generate an X25519 key pair, with the private key being 32 random bytes, and the public key being
X25519(a, 9), as defined in [RFC7748], section 6.1. -
Let algorithm be a new
KeyAlgorithmobject. -
Set the
nameattribute of algorithm to "X25519". -
Let publicKey be a new
CryptoKeyrepresenting 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
CryptoKeyrepresenting the private key of the generated key pair. -
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
CryptoKeyPairdictionary. -
Set the
publicKeyattribute of result to be publicKey. -
Set the
privateKeyattribute of result to be privateKey. -
Return result.
-
Let keyData be the key data to be imported.
-
- If format is "
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
algorithmobject identifier field of thealgorithmAlgorithmIdentifier field of spki is not equal to theid-X25519object identifier defined in [RFC8410], then throw aDataError. -
If the
parametersfield of thealgorithmAlgorithmIdentifier field of spki is present, then throw aDataError. -
Let publicKey be the X25519 public key identified by the
subjectPublicKeyfield of spki. -
Let key be a new
CryptoKeythat represents publicKey. -
Set the
[[type]]internal slot of key to "public" -
Let algorithm be a new
KeyAlgorithm. -
Set the
nameattribute of algorithm to "X25519". -
Set the
[[algorithm]]internal slot of key to algorithm.
-
- If format is "
pkcs8": -
-
If usages contains an entry which is not "
deriveKey" or "deriveBits" then throw aSyntaxError. -
Let privateKeyInfo be the result of running the parse a privateKeyInfo algorithm over keyData.
-
If the
algorithmobject identifier field of theprivateKeyAlgorithmPrivateKeyAlgorithm field of privateKeyInfo is not equal to theid-X25519object identifier defined in [RFC8410], then throw aDataError. -
If the
parametersfield of theprivateKeyAlgorithmPrivateKeyAlgorithmIdentifier field of privateKeyInfo is present, then throw aDataError. -
Let curvePrivateKey be the result of performing the parse an ASN.1 structure algorithm, with data as the
privateKeyfield of privateKeyInfo, structure as the ASN.1CurvePrivateKeystructure specified in Section 7 of [RFC8410], and exactData set to true. -
Let key be a new
CryptoKeythat represents the X25519 private key identified by curvePrivateKey. -
Let algorithm be a new
KeyAlgorithm. -
Set the
nameattribute of algorithm to "X25519". -
Set the
[[algorithm]]internal slot of key to algorithm.
-
- If format is "
jwk": -
-
- If keyData is a
JsonWebKeydictionary: Let jwk equal keyData.
- Otherwise:
- If keyData is a
-
If the
dfield is present and if usages contains an entry which is not "deriveKey" or "deriveBits" then throw aSyntaxError. -
If the
dfield is not present and if usages is not empty then throw aSyntaxError. -
If the
ktyfield of jwk is not "OKP", then throw aDataError. -
If the
crvfield of jwk is not "X25519", then throw aDataError. -
If usages is non-empty and the
usefield of jwk is present and is not equal to "enc" then throw aDataError. -
If the
key_opsfield of jwk is present, and is invalid according to the requirements of JSON Web Key [JWK], or it does not contain all of the specified usages values, then throw aDataError. -
If the
extfield of jwk is present and has the value false and extractable is true, then throw aDataError. -
- If the
dfield is present: - Otherwise:
- If the
-
Let algorithm be a new instance of a
KeyAlgorithmobject. -
Set the
nameattribute of algorithm to "X25519". -
Set the
[[algorithm]]internal slot of key to algorithm.
-
- If format is "
raw": -
-
If usages is not empty then throw a
SyntaxError. -
Let algorithm be a new
KeyAlgorithmobject. -
Set the
nameattribute of algorithm to "X25519". -
Let key be a new
CryptoKeyrepresenting the key data provided in keyData. -
Set the
[[type]]internal slot of key to "public" -
Set the
[[algorithm]]internal slot of key to algorithm.
-
- Otherwise:
- If format is "
-
Return key
-
Let key be the
CryptoKeyto be exported. -
If the underlying cryptographic key material represented by the
[[handle]]internal slot of key cannot be accessed, then throw anOperationError. -
- If format is "
spki": -
-
If the
[[type]]internal slot of key is not "public", then throw anInvalidAccessError. -
Let data be an instance of the
SubjectPublicKeyInfoASN.1 structure defined in [RFC5280] with the following properties:-
Set the algorithm field to an
AlgorithmIdentifierASN.1 type with the following properties:-
Set the algorithm object identifier to the
id-X25519OID defined in [RFC8410].
-
-
Set the subjectPublicKey field to keyData.
-
-
Let result be the result of DER-encoding data.
-
- If format is "
pkcs8": -
-
If the
[[type]]internal slot of key is not "private", then throw anInvalidAccessError. -
Let data be an instance of the
PrivateKeyInfoASN.1 structure defined in [RFC5208] with the following properties:-
Set the version field to
0. -
Set the privateKeyAlgorithm field to a
PrivateKeyAlgorithmIdentifierASN.1 type with the following properties:-
Set the algorithm object identifier to the
id-X25519OID defined in [RFC8410].
-
-
Set the privateKey field to the result of DER-encoding a
CurvePrivateKeyASN.1 type, as defined in Section 7 of [RFC8410], that represents the X25519 private key represented by the[[handle]]internal slot of key
-
-
Let result be the result of DER-encoding data.
-
- If format is "
jwk": -
-
Let jwk be a new
JsonWebKeydictionary. -
Set the
ktyattribute of jwk to "OKP". -
Set the
crvattribute of jwk to "X25519". -
Set the
xattribute of jwk according to the definition in Section 2 of [RFC8037]. -
Set the
key_opsattribute of jwk to theusagesattribute of key. -
Set the
extattribute of jwk to the[[extractable]]internal slot of key. -
Let result be jwk.
-
-
If format is "
raw": -
-
If the
[[type]]internal slot of key is not "public", then throw anInvalidAccessError. -
Let data be a byte sequence representing the X25519 public key represented by the
[[handle]]internal slot of key. -
Let result be data.
-
- Otherwise:
- If format is "
-
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 |
byte sequence |
| decrypt | AesCtrParams |
byte sequence |
| generateKey | AesKeyGenParams |
CryptoKey |
| importKey | None | CryptoKey |
| exportKey | None | object |
| get key length | AesDerivedKeyParams |
Integer |
WebIDLdictionary AesCtrParams : Algorithm {
required BufferSource counter;
required [EnforceRange] octet length;
};
The counter member contains 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.
The length member contains the length, in bits, of the rightmost part of the counter block that is incremented.
WebIDLdictionary AesKeyAlgorithm : KeyAlgorithm {
required unsigned short length;
};
The length member represents the length, in bits, of the key.
WebIDLdictionary AesKeyGenParams : Algorithm {
required [EnforceRange] unsigned short length;
};
The length member represents the length, in bits, of the key.
WebIDLdictionary AesDerivedKeyParams : Algorithm {
required [EnforceRange] unsigned short length;
};
The length member represents the length, in bits, of the key.
-
If the
countermember of normalizedAlgorithm does not have a length of 16 bytes, then throw anOperationError. -
If the
lengthmember of normalizedAlgorithm is zero or is greater than 128, then throw anOperationError. -
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
countermember of normalizedAlgorithm as the initial value of the counter block, thelengthmember of normalizedAlgorithm as the input parameter m to the standard counter block incrementing function defined in Appendix B.1 of [NIST-SP800-38A] and plaintext as the input plaintext. -
Return ciphertext.
-
If the
countermember of normalizedAlgorithm does not have a length of 16 bytes, then throw anOperationError. -
If the
lengthmember of normalizedAlgorithm is zero or is greater than 128, then throw anOperationError. -
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
countermember of normalizedAlgorithm as the initial value of the counter block, thelengthmember of normalizedAlgorithm as the input parameter m to the standard counter block incrementing function defined in Appendix B.1 of [NIST-SP800-38A] and ciphertext as the input ciphertext. -
Return plaintext.
-
If usages contains any entry which is not one of "
encrypt", "decrypt", "wrapKey" or "unwrapKey", then throw aSyntaxError. -
If the
lengthmember of normalizedAlgorithm is not equal to one of 128, 192 or 256, then throw anOperationError. -
Generate an AES key of length equal to the
lengthmember of normalizedAlgorithm. -
If the key generation step fails, then throw an
OperationError. -
Let key be a new
CryptoKeyobject representing the generated AES key. -
Let algorithm be a new
AesKeyAlgorithm. -
Set the
nameattribute of algorithm to "AES-CTR". -
Set the
lengthattribute of algorithm to equal thelengthmember 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 aSyntaxError. -
- If format is "
raw": -
-
Let data be keyData.
-
If the length in bits of data is not 128, 192 or 256 then throw a
DataError.
-
- If format is "
jwk": -
-
- If keyData is a
JsonWebKeydictionary: Let jwk equal keyData.
- Otherwise:
- If keyData is a
-
If the
ktyfield of jwk is not "oct", then throw aDataError. -
If jwk does not meet the requirements of Section 6.4 of JSON Web Algorithms [JWA], then throw a
DataError. -
Let data be the byte sequence obtained by decoding the
kfield of jwk. -
- If the length in bits of data is 128:
-
If the
algfield of jwk is present, and is not "A128CTR", then throw aDataError. - If the length in bits of data is 192:
-
If the
algfield of jwk is present, and is not "A192CTR", then throw aDataError. - If the length in bits of data is 256:
-
If the
algfield of jwk is present, and is not "A256CTR", then throw aDataError. - Otherwise:
-
throw a
DataError.
-
If usages is non-empty and the
usefield of jwk is present and is not "enc", then throw aDataError. -
If the
key_opsfield of jwk is present, and is invalid according to the requirements of JSON Web Key [JWK] or does not contain all of the specified usages values, then throw aDataError. -
If the
extfield of jwk is present and has the value false and extractable is true, then throw aDataError.
-
- Otherwise:
-
throw a
NotSupportedError.
- If format is "
-
Let key be a new
CryptoKeyobject representing an AES key with value data. -
Let algorithm be a new
AesKeyAlgorithm. -
Set the
nameattribute of algorithm to "AES-CTR". -
Set the
lengthattribute 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 anOperationError. -
- If format is "
raw": -
-
Let data be a byte sequence containing the raw octets of the key represented by the
[[handle]]internal slot of key. -
Let result be data.
-
- If format is "
jwk": -
-
Let jwk be a new
JsonWebKeydictionary. -
Set the
ktyattribute of jwk to the string "oct". -
Set the
kattribute of jwk to be a string containing the raw octets of the key represented by the[[handle]]internal slot of key, encoded according to Section 6.4 of JSON Web Algorithms [JWA]. -
Set the
key_opsattribute of jwk to equal the[[usages]]internal slot of key. -
Set the
extattribute of jwk to equal the[[extractable]]internal slot of key. -
Let result be jwk.
-
- Otherwise:
- If format is "
-
Return result.
-
If the
lengthmember of normalizedDerivedKeyAlgorithm is not 128, 192 or 256, then throw aOperationError. -
Return the
lengthmember 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 |
byte sequence |
| decrypt | AesCbcParams |
byte sequence |
| generateKey | AesKeyGenParams |
CryptoKey |
| importKey | None | CryptoKey |
| exportKey | None | object |
| get key length | AesDerivedKeyParams |
Integer |
WebIDLdictionary AesCbcParams : Algorithm {
required BufferSource iv;
};
The iv member represents the initialization vector. It MUST be 16 bytes.
-
If the
ivmember of normalizedAlgorithm does not have a length of 16 bytes, then throw anOperationError. -
Let paddedPlaintext be the result of adding padding octets to plaintext 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
ivmember of normalizedAlgorithm as the IV input parameter and paddedPlaintext as the input plaintext. -
Return ciphertext.
-
If the
ivmember of normalizedAlgorithm does not have a length of 16 bytes, then throw anOperationError. -
If the length of ciphertext is zero or is not a multiple of 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
ivmember of normalizedAlgorithm as the IV input parameter and 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 plaintext.
-
If usages contains any entry which is not one of "
encrypt", "decrypt", "wrapKey" or "unwrapKey", then throw aSyntaxError. -
If the
lengthmember of normalizedAlgorithm is not equal to one of 128, 192 or 256, then throw anOperationError. -
Generate an AES key of length equal to the
lengthmember of normalizedAlgorithm. -
If the key generation step fails, then throw an
OperationError. -
Let key be a new
CryptoKeyobject representing the generated AES key. -
Let algorithm be a new
AesKeyAlgorithm. -
Set the
nameattribute of algorithm to "AES-CBC". -
Set the
lengthattribute of algorithm to equal thelengthmember 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 aSyntaxError. -
- If format is "
raw": -
-
Let data be keyData.
-
If the length in bits of data is not 128, 192 or 256 then throw a
DataError.
-
- If format is "
jwk": -
-
- If keyData is a
JsonWebKeydictionary: Let jwk equal keyData.
- Otherwise:
- If keyData is a
-
If the
ktyfield of jwk is not "oct", then throw aDataError. -
If jwk does not meet the requirements of Section 6.4 of JSON Web Algorithms [JWA], then throw a
DataError. -
Let data be the byte sequence obtained by decoding the
kfield of jwk. -
- If the length in bits of data is 128:
- If the
algfield of jwk is present, and is not "A128CBC", then throw aDataError. - If the length in bits of data is 192:
- If the
algfield of jwk is present, and is not "A192CBC", then throw aDataError. - If the length in bits of data is 256:
- If the
algfield of jwk is present, and is not "A256CBC", then throw aDataError. - Otherwise:
-
throw a
DataError.
-
If usages is non-empty and the
usefield of jwk is present and is not "enc", then throw aDataError. -
If the
key_opsfield of jwk is present, and is invalid according to the requirements of JSON Web Key [JWK] or does not contain all of the specified usages values, then throw aDataError. -
If the
extfield of jwk is present and has the value false and extractable is true, then throw aDataError.
-
- Otherwise:
-
throw a
NotSupportedError
- If format is "
-
Let key be a new
CryptoKeyobject representing an AES key with value data. -
Let algorithm be a new
AesKeyAlgorithm. -
Set the
nameattribute of algorithm to "AES-CBC". -
Set the
lengthattribute 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 anOperationError. -
- If format is "
raw": -
-
Let data be a byte sequence containing the raw octets of the key represented by the
[[handle]]internal slot of key. -
Let result be data.
-
- If format is "
jwk": -
-
Let jwk be a new
JsonWebKeydictionary. -
Set the
ktyattribute of jwk to the string "oct". -
Set the
kattribute of jwk to be a string containing the raw octets of the key represented by the[[handle]]internal slot of key, encoded according to Section 6.4 of JSON Web Algorithms [JWA]. -
Set the
key_opsattribute of jwk to equal theusagesattribute of key. -
Set the
extattribute of jwk to equal the[[extractable]]internal slot of key. -
Let result be jwk.
-
- Otherwise:
- If format is "
-
Return result.
-
If the
lengthmember of normalizedDerivedKeyAlgorithm is not 128, 192 or 256, then throw anOperationError. -
Return the
lengthmember 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-SP800-38D].
The recognized algorithm name for
this algorithm is "AES-GCM".
| Operation | Parameters | Result |
|---|---|---|
| encrypt | AesGcmParams |
byte sequence |
| decrypt | AesGcmParams |
byte sequence |
| generateKey | AesKeyGenParams |
CryptoKey |
| importKey | None | CryptoKey |
| exportKey | None | object |
| get key length | AesDerivedKeyParams |
Integer |
WebIDLdictionary AesGcmParams : Algorithm {
required BufferSource iv;
BufferSource additionalData;
[EnforceRange] octet tagLength;
};
The iv member represents the initialization vector to use. May be up to 2^64-1 bytes long.
The additionalData member represents the additional authentication data to include.
The tagLength member represents the desired length of the authentication tag. May be 0 - 128.
-
If plaintext has a length greater than 2^39 - 256 bytes, then throw an
OperationError. -
If the
ivmember of normalizedAlgorithm has a length greater than 2^64 - 1 bytes, then throw anOperationError. -
If the
additionalDatamember of normalizedAlgorithm is present and has a length greater than 2^64 - 1 bytes, then throw anOperationError. -
- If the
tagLengthmember of normalizedAlgorithm is not present: - Let tagLength be 128.
- If the
tagLengthmember of normalizedAlgorithm is one of 32, 64, 96, 104, 112, 120 or 128: - Let tagLength be equal to the
tagLengthmember of normalizedAlgorithm - Otherwise:
-
throw an
OperationError.
- If the
-
Let additionalData be the
additionalDatamember of normalizedAlgorithm if present or an empty byte sequence 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
ivmember of normalizedAlgorithm as the IV input parameter, additionalData as the A input parameter, tagLength as the t pre-requisite and plaintext as the input plaintext. -
Let ciphertext be equal to C | T, where '|' denotes concatenation.
-
Return ciphertext.
-
- If the
tagLengthmember of normalizedAlgorithm is not present: - Let tagLength be 128.
- If the
tagLengthmember of normalizedAlgorithm is one of 32, 64, 96, 104, 112, 120 or 128: - Let tagLength be equal to the
tagLengthmember of normalizedAlgorithm - Otherwise:
-
throw an
OperationError.
- If the
-
If ciphertext has a length in bits less than tagLength, then throw an
OperationError. -
If the
ivmember of normalizedAlgorithm has a length greater than 2^64 - 1 bytes, then throw anOperationError. -
If the
additionalDatamember of normalizedAlgorithm is present and has a length greater than 2^64 - 1 bytes, then throw anOperationError. -
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
additionalDatamember of normalizedAlgorithm if present or an empty byte sequence otherwise. -
Perform the Authenticated Decryption Function described in Section 7.2 of [NIST-SP800-38D] using AES as the block cipher, the
ivmember of normalizedAlgorithm as the IV input parameter, additionalData as the A input parameter, tagLength as the t pre-requisite, actualCiphertext as the input ciphertext, C and tag as the authentication tag, T.- If the result of the algorithm is the indication of inauthenticity, "FAIL":
-
throw an
OperationError - Otherwise:
- Let plaintext be the output P of the Authenticated Decryption Function.
-
Return plaintext.
-
If usages contains any entry which is not one of "
encrypt", "decrypt", "wrapKey" or "unwrapKey", then throw aSyntaxError. -
If the
lengthmember of normalizedAlgorithm is not equal to one of 128, 192 or 256, then throw anOperationError. -
Generate an AES key of length equal to the
lengthmember of normalizedAlgorithm. -
If the key generation step fails, then throw an
OperationError. -
Let key be a new
CryptoKeyobject representing the generated AES key. -
Let algorithm be a new
AesKeyAlgorithm. -
Set the
nameattribute of algorithm to "AES-GCM". -
Set the
lengthattribute of algorithm to equal thelengthmember 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 aSyntaxError. -
- If format is "
raw": -
-
Let data be keyData.
-
If the length in bits of data is not 128, 192 or 256 then throw a
DataError.
-
- If format is "
jwk": -
-
- If keyData is a
JsonWebKeydictionary: Let jwk equal keyData.
- Otherwise:
- If keyData is a
-
If the
ktyfield of jwk is not "oct", then throw aDataError. -
If jwk does not meet the requirements of Section 6.4 of JSON Web Algorithms [JWA], then throw a
DataError. -
Let data be the byte sequence obtained by decoding the
kfield of jwk. -
- If the length in bits of data is 128:
- If the
algfield of jwk is present, and is not "A128GCM", then throw aDataError. - If the length in bits of data is 192:
- If the
algfield of jwk is present, and is not "A192GCM", then throw aDataError. - If the length in bits of data is 256:
- If the
algfield of jwk is present, and is not "A256GCM", then throw aDataError. - Otherwise:
-
throw a
DataError.
-
If usages is non-empty and the
usefield of jwk is present and is not "enc", then throw aDataError. -
If the
key_opsfield of jwk is present, and is invalid according to the requirements of JSON Web Key [JWK] or does not contain all of the specified usages values, then throw aDataError. -
If the
extfield of jwk is present and has the value false and extractable is true, then throw aDataError.
-
- Otherwise:
-
throw a
NotSupportedError.
- If format is "
-
Let key be a new
CryptoKeyobject representing an AES key with value data. -
Let algorithm be a new
AesKeyAlgorithm. -
Set the
nameattribute of algorithm to "AES-GCM". -
Set the
lengthattribute 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 anOperationError. -
- If format is "
raw": -
-
Let data be a byte sequence containing the raw octets of the key represented by the
[[handle]]internal slot of key. -
Let result be data.
-
- If format is "
jwk": -
-
Let jwk be a new
JsonWebKeydictionary. -
Set the
ktyattribute of jwk to the string "oct". -
Set the
kattribute of jwk to be a string containing the raw octets of the key represented by the[[handle]]internal slot of key, encoded according to Section 6.4 of JSON Web Algorithms [JWA]. -
Set the
key_opsattribute of jwk to equal theusagesattribute of key. -
Set the
extattribute of jwk to equal the[[extractable]]internal slot of key. -
Let result be jwk.
-
- Otherwise:
- If format is "
-
Return result.
-
If the
lengthmember of normalizedDerivedKeyAlgorithm is not 128, 192 or 256, then throw anOperationError. -
Return the
lengthmember 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 | byte sequence |
| unwrapKey | None | byte sequence |
| 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 aSyntaxError. -
If the
lengthproperty of normalizedAlgorithm is not equal to one of 128, 192 or 256, then throw anOperationError. -
Generate an AES key of length equal to the
lengthmember of normalizedAlgorithm. -
If the key generation step fails, then throw an
OperationError. -
Let key be a new
CryptoKeyobject representing the generated AES key. -
Let algorithm be a new
AesKeyAlgorithm. -
Set the
nameattribute of algorithm to "AES-KW". -
Set the
lengthattribute of algorithm to equal thelengthproperty 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 aSyntaxError. -
- If format is "
raw": -
-
Let data be keyData.
-
If the length in bits of data is not 128, 192 or 256 then throw a
DataError.
-
- If format is "
jwk": -
-
- If keyData is a
JsonWebKeydictionary: Let jwk equal keyData.
- Otherwise:
- If keyData is a
-
If the
ktyfield of jwk is not "oct", then throw aDataError. -
If jwk does not meet the requirements of Section 6.4 of JSON Web Algorithms [JWA], then throw a
DataError. -
Let data be the byte sequence obtained by decoding the
kfield of jwk. -
- If the length in bits of data is 128:
- If the
algfield of jwk is present, and is not "A128KW", then throw aDataError. - If the length in bits of data is 192:
- If the
algfield of jwk is present, and is not "A192KW", then throw aDataError. - If the length in bits of data is 256:
- If the
algfield of jwk is present, and is not "A256KW", then throw aDataError. - Otherwise:
-
throw a
DataError.
-
If usages is non-empty and the
usefield of jwk is present and is not "enc", then throw aDataError. -
If the
key_opsfield of jwk is present, and is invalid according to the requirements of JSON Web Key [JWK] or does not contain all of the specified usages values, then throw aDataError. -
If the
extfield of jwk is present and has the value false and extractable is true, then throw aDataError.
-
- Otherwise:
-
throw a
NotSupportedError.
- If format is "
-
Let key be a new
CryptoKeyrepresenting an AES key with value data. -
Let algorithm be a new
AesKeyAlgorithm. -
Set the
nameattribute of algorithm to "AES-KW". -
Set the
lengthattribute 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 anOperationError. -
- If format is "
raw": -
-
Let data be a byte sequence containing the raw octets of the key represented by the
[[handle]]internal slot of key. -
Let result be data.
-
- If format is "
jwk": -
-
Let jwk be a new
JsonWebKeydictionary. -
Set the
ktyattribute of jwk to the string "oct". -
Set the
kattribute of jwk to be a string containing the raw octets of the key represented by the[[handle]]internal slot of key, encoded according to Section 6.4 of JSON Web Algorithms [JWA]. -
Set the
key_opsattribute of jwk to equal theusagesattribute of key. -
Set the
extattribute of jwk to equal the[[extractable]]internal slot of key. -
Let result be jwk.
-
- Otherwise:
- If format is "
-
Return result.
-
If the
lengthmember of normalizedDerivedKeyAlgorithm is not 128, 192 or 256, then throw anOperationError. -
Return the
lengthmember of normalizedDerivedKeyAlgorithm.
This section is non-normative.
The HMAC algorithm calculates and verifies hash-based message
authentication codes according to [FIPS-198-1]
using the SHA hash functions defined in this specification.
Other specifications may specify the use of additional hash algorithms with HMAC. Such specifications must define the digest operation for the additional hash algorithms and key import steps and key export steps for HMAC.
The recognized algorithm name for
this algorithm is "HMAC".
| Operation | Parameters | Result |
|---|---|---|
| sign | None | byte sequence |
| verify | None | boolean |
| generateKey | HmacKeyGenParams |
CryptoKey |
| importKey | HmacImportParams |
CryptoKey |
| exportKey | None | object |
| get key length | HmacImportParams |
Integer |
WebIDLdictionary HmacImportParams : Algorithm {
required HashAlgorithmIdentifier hash;
[EnforceRange] unsigned long length;
};
The hash member represents the inner hash function to use.
The length member represent the length (in bits) of the key.
WebIDLdictionary HmacKeyAlgorithm : KeyAlgorithm {
required KeyAlgorithm hash;
required unsigned long length;
};
The hash member represents the inner hash function to use.
The length member represent the length (in bits) of the key.
WebIDLdictionary HmacKeyGenParams : Algorithm {
required HashAlgorithmIdentifier hash;
[EnforceRange] unsigned long length;
};
The hash member represents the inner hash function to use.
The length member represent the length (in bits) of the key to generate. If unspecified, the recommended length will be used, which is the size of the associated hash function's block size.
-
Let mac be the result of performing the MAC Generation operation described in Section 4 of [FIPS-198-1] using the key represented by the
[[handle]]internal slot of key, the hash function identified by thehashattribute of the[[algorithm]]internal slot of key and message as the input data text. -
Return mac.
-
Let mac be the result of performing the MAC Generation operation described in Section 4 of [FIPS-198-1] using the key represented by the
[[handle]]internal slot of key, the hash function identified by thehashattribute 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 aSyntaxError. -
-
If the
lengthmember of normalizedAlgorithm is not present: -
Let length be the block size in bits of the hash function
identified by the
hashmember of normalizedAlgorithm. -
Otherwise, if the
lengthmember of normalizedAlgorithm is non-zero: -
Let length be equal to the
lengthmember of normalizedAlgorithm. - Otherwise:
-
throw an
OperationError.
-
If the
-
Generate a key of length length bits.
-
If the key generation step fails, then throw an
OperationError. -
Let key be a new
CryptoKeyobject representing the generated key. -
Let algorithm be a new
HmacKeyAlgorithm. -
Set the
nameattribute of algorithm to "HMAC". -
Set the
lengthattribute of algorithm to length. -
Let hash be a new
KeyAlgorithm. -
Set the
nameattribute of hash to equal thenamemember of thehashmember of normalizedAlgorithm. -
Set the
hashattribute 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 aSyntaxError. -
Let hash be a new
KeyAlgorithm. -
- If format is "
raw": -
-
Let data be keyData.
-
Set hash to equal the
hashmember of normalizedAlgorithm.
-
- If format is "
jwk": -
-
- If keyData is a
JsonWebKeydictionary: Let jwk equal keyData.
- Otherwise:
- If keyData is a
-
If the
ktyfield of jwk is not "oct", then throw aDataError. -
If jwk does not meet the requirements of Section 6.4 of JSON Web Algorithms [JWA], then throw a
DataError. -
Let data be the byte sequence obtained by decoding the
kfield of jwk. -
Set the hash to equal the
hashmember of normalizedAlgorithm. -
-
If the
nameattribute of hash is "SHA-1": -
If the
algfield of jwk is present and is not "HS1", then throw aDataError. -
If the
nameattribute of hash is "SHA-256": -
If the
algfield of jwk is present and is not "HS256", then throw aDataError. -
If the
nameattribute of hash is "SHA-384": -
If the
algfield of jwk is present and is not "HS384", then throw aDataError. -
If the
nameattribute of hash is "SHA-512": -
If the
algfield of jwk is present and is not "HS512", then throw aDataError. -
Otherwise, if the
nameattribute of hash is defined in another applicable specification: - Perform any key import steps defined by other applicable specifications, passing format, jwk and hash and obtaining hash.
-
If the
-
If usages is non-empty and the
usefield of jwk is present and is not "sign", then throw aDataError. -
If the
key_opsfield of jwk is present, and is invalid according to the requirements of JSON Web Key [JWK] or does not contain all of the specified usages values, then throw aDataError. -
If the
extfield of jwk is present and has the value false and extractable is true, then throw aDataError.
-
- Otherwise:
-
throw a
NotSupportedError.
- If format is "
-
Let length be the length in bits of data.
-
-
If the
lengthmember of normalizedAlgorithm is present:
-
If the
-
Let key be a new
CryptoKeyobject representing an HMAC key with the first length bits of data. -
Let algorithm be a new
HmacKeyAlgorithm. -
Set the
nameattribute of algorithm to "HMAC". -
Set the
lengthattribute of algorithm to length. -
Set the
hashattribute 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 anOperationError. -
Let bits be the raw bits of the key represented by the
[[handle]]internal slot of key. -
Let data be a byte sequence containing bits.
-
- If format is "
raw": -
-
Let result be data.
-
- If format is "
jwk": -
-
Let jwk be a new
JsonWebKeydictionary. -
Set the
ktyattribute of jwk to the string "oct". -
Set the
kattribute of jwk to be a string containing data, encoded according to Section 6.4 of JSON Web Algorithms [JWA]. -
Let algorithm be the
[[algorithm]]internal slot of key. -
Let hash be the
hashattribute of algorithm. -
- If the
nameattribute of hash is "SHA-1": - Set the
algattribute of jwk to the string "HS1". - If the
nameattribute of hash is "SHA-256": - Set the
algattribute of jwk to the string "HS256". - If the
nameattribute of hash is "SHA-384": - Set the
algattribute of jwk to the string "HS384". - If the
nameattribute of hash is "SHA-512": - Set the
algattribute of jwk to the string "HS512". -
Otherwise, the
nameattribute of hash is defined in another applicable specification: -
-
Perform any key export steps defined by other applicable specifications, passing format and key and obtaining alg.
-
Set the
algattribute of jwk to alg.
-
- If the
-
Set the
key_opsattribute of jwk to equal theusagesattribute of key. -
Set the
extattribute of jwk to equal the[[extractable]]internal slot of key. -
Let result be jwk.
-
- Otherwise:
- If format is "
-
Return result.
-
-
If the
lengthmember of normalizedDerivedKeyAlgorithm is not present: -
Let length be the block size in bits of the hash function identified by the
hashmember of normalizedDerivedKeyAlgorithm. -
Otherwise, if the
lengthmember of normalizedDerivedKeyAlgorithm is non-zero: -
Let length be equal to the
lengthmember of normalizedDerivedKeyAlgorithm. - Otherwise:
-
throw a
TypeError.
-
If the
-
Return length.
This section is non-normative.
This describes the SHA-1 and SHA-2 families, as specified by [FIPS-180-4].
The recognized algorithm names are
"SHA-1",
"SHA-256",
"SHA-384", and
"SHA-512" for the respective SHA algorithms.
| Operation | Parameters | Result |
|---|---|---|
| digest | None | byte sequence |
-
-
If the
namemember of normalizedAlgorithm is a cases-sensitive string match for "SHA-1": - Let result be the result of performing the SHA-1 hash function defined in Section 6.1 of [FIPS-180-4] using message as the input message, M.
-
If the
namemember of normalizedAlgorithm is a cases-sensitive string match for "SHA-256": - Let result be the result of performing the SHA-256 hash function defined in Section 6.2 of [FIPS-180-4] using message as the input message, M.
-
If the
namemember of normalizedAlgorithm is a cases-sensitive string match for "SHA-384": - Let result be the result of performing the SHA-384 hash function defined in Section 6.5 of [FIPS-180-4] using message as the input message, M.
-
If the
namemember of normalizedAlgorithm is a cases-sensitive string match for "SHA-512": - Let result be the result of performing the SHA-512 hash function defined in Section 6.4 of [FIPS-180-4] using message as the input message, M.
-
If the
-
If performing the operation results in an error, then throw an
OperationError. -
Return result.
This section is non-normative.
The "HKDF" algorithm identifier is used to
perform key derivation using the extraction-then-expansion approach described in
[RFC5869] and
using the SHA hash functions defined in this specification.
Other specifications may specify the use of additional hash algorithms with HKDF. Such specifications must define the digest operation for the additional hash algorithms.
The recognized algorithm name
for this algorithm is "HKDF".
| Operation | Parameters | Result |
|---|---|---|
| deriveBits | HkdfParams |
byte sequence |
| importKey | None | CryptoKey |
| Get key length | None | null |
WebIDLdictionary HkdfParams : Algorithm {
required HashAlgorithmIdentifier hash;
required BufferSource salt;
required BufferSource info;
};
The hash member represents the algorithm to use with HMAC (e.g.: SHA-256).
The salt member represents the salt used in the extract step.
The info member represents application specific context for the derived keying material.
-
If length is null or is not a multiple of 8, then throw an
OperationError. -
Let keyDerivationKey be the secret represented by the
[[handle]]internal slot of key. -
Let result be the result of performing the HKDF extract and then the HKDF expand step described in Section 2 of [RFC5869] using:
-
If the key derivation operation fails, then throw an
OperationError. -
Return result.
-
Let keyData be the key data to be imported.
-
-
If format is "
raw": -
-
If usages contains a value that is not "
deriveKey" or "deriveBits", then throw aSyntaxError. -
If extractable is not
false, then throw aSyntaxError. -
Let key be a new
CryptoKeyrepresenting the key data provided in keyData. -
Let algorithm be a new
KeyAlgorithmobject. -
Set the
nameattribute of algorithm to "HKDF". -
Set the
[[algorithm]]internal slot of key to algorithm. -
Return key.
-
- Otherwise:
-
throw a
NotSupportedError.
-
If format is "
-
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, as defined in
[RFC8018] using HMAC as the pseudo-random function,
using the SHA hash functions defined
in this specification.
Other specifications may specify the use of additional hash algorithms with PBKDF2. Such specifications must define the digest operation for the additional hash algorithms.
The recognized algorithm name for
this algorithm is "PBKDF2".
| Operation | Parameters | Result |
|---|---|---|
| deriveBits | Pbkdf2Params |
byte sequence |
| importKey | None | CryptoKey |
| Get key length | None | null |
WebIDLdictionary Pbkdf2Params : Algorithm {
required BufferSource salt;
required [EnforceRange] unsigned long iterations;
required HashAlgorithmIdentifier hash;
};
The Pbkdf2Params dictionary has a salt member, a iterations member, and a hash member.
-
If length is null or is not a multiple of 8, then throw an
OperationError. -
If the
iterationsmember of normalizedAlgorithm is zero, then throw anOperationError. -
If length is zero, return an empty byte sequence.
-
Let prf be the MAC Generation function described in Section 4 of [FIPS-198-1] using the hash function described by the
hashmember of normalizedAlgorithm. -
Let result be the result of performing the PBKDF2 operation defined in Section 5.2 of [RFC8018] using prf as the pseudo-random function, PRF, the password represented by the
[[handle]]internal slot of key as the password, P, thesaltattribute of normalizedAlgorithm as the salt, S, the value of theiterationsattribute 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 aNotSupportedError -
If usages contains a value that is not "
deriveKey" or "deriveBits", then throw aSyntaxError. -
If extractable is not
false, then throw aSyntaxError. -
Let key be a new
CryptoKeyrepresenting keyData. -
Let algorithm be a new
KeyAlgorithmobject. -
Set the
nameattribute of algorithm to "PBKDF2". -
Set the
[[algorithm]]internal slot of key to algorithm. -
Return key.
-
Return null.
This example generates two X25519 key pairs, one for Alice and one for Bob, performs a key agreement between them, derives a 256-bit AES-GCM key from the result using HKDF with SHA-256, and encrypts and decrypts some data with it.
// Generate a key pair for Alice.
const alice_x25519_key = await crypto.subtle.generateKey('X25519', false /* extractable */, ['deriveKey']);
const alice_private_key = alice_x25519_key.privateKey;
// Normally, the public key would be sent by Bob to Alice in advance over some authenticated channel.
// In this example, we'll generate another key pair and use its public key instead.
const bob_x25519_key = await crypto.subtle.generateKey('X25519', false /* extractable */, ['deriveKey']);
const bob_public_key = bob_x25519_key.publicKey;
// Perform the key agreement.
const alice_x25519_params = { name: 'X25519', public: bob_public_key };
const alice_shared_key = await crypto.subtle.deriveKey(alice_x25519_params, alice_private_key, 'HKDF', false /* extractable */, ['deriveKey']);
// Derive a symmetric key from the result.
const salt = crypto.getRandomValues(new Uint8Array(32));
const info = new TextEncoder().encode('X25519 key agreement for an AES-GCM-256 key');
const hkdf_params = { name: 'HKDF', hash: 'SHA-256', salt, info };
const gcm_params = { name: 'AES-GCM', length: 256 };
const alice_symmetric_key = await crypto.subtle.deriveKey(hkdf_params, alice_shared_key, gcm_params, false /* extractable */, ['encrypt', 'decrypt']);
// Encrypt some data with the symmetric key, and send it to Bob. The IV must be passed along as well.
const iv = crypto.getRandomValues(new Uint8Array(12));
const message = new TextEncoder().encode('Hi Bob!');
const encrypted = await crypto.subtle.encrypt({ ...gcm_params, iv }, alice_symmetric_key, message);
// On Bob's side, Alice's public key and Bob's private key are used, instead.
// To get the same result, Alice and Bob must agree on using the same salt and info.
const alice_public_key = alice_x25519_key.publicKey;
const bob_private_key = bob_x25519_key.privateKey;
const bob_x25519_params = { name: 'X25519', public: alice_public_key };
const bob_shared_key = await crypto.subtle.deriveKey(bob_x25519_params, bob_private_key, 'HKDF', false /* extractable */, ['deriveKey']);
const bob_symmetric_key = await crypto.subtle.deriveKey(hkdf_params, bob_shared_key, gcm_params, false /* extractable */, ['encrypt', 'decrypt']);
// On Bob's side, the data can be decrypted.
const decrypted = await crypto.subtle.decrypt({ ...gcm_params, iv }, bob_symmetric_key, encrypted);
const decrypted_message = new TextDecoder().decode(decrypted);const data = new TextEncoder().encode('Hello, world!');
const key = await crypto.subtle.generateKey('Ed25519', false, ['sign']);
const signature = await crypto.subtle.sign('Ed25519', key.privateKey, data);const data = new TextEncoder().encode('Hello, world!');
const aesAlgorithmKeyGen = {
name: 'AES-GCM',
// AesKeyGenParams
length: 256
};
const aesAlgorithmEncrypt = {
name: 'AES-GCM',
// AesGcmParams
iv: crypto.getRandomValues(new Uint8Array(16))
};
const key = await crypto.subtle.generateKey(aesAlgorithmKeyGen, false, ['encrypt']);
const encrypted = await crypto.subtle.encrypt(aesAlgorithmEncrypt, key, data);const filename = `${crypto.randomUUID()}.txt`;This section registers the following algorithm identifiers in the IANA JSON Web Signature and Encryption Algorithms Registry for use with JSON Web Key. Note that the 'Implementation Requirements' field in the template refers to use with JSON Web Signature and JSON Web Encryption specifically, in which case use of unauthenticated encryption is prohibited.
- Algorithm Name: "RS1"
- Algorithm Description: RSASSA-PKCS1-v1_5 with SHA-1
- Algorithm Usage Location(s): "JWK"
- JOSE Implementation Requirements: Prohibited
- Change Controller: W3C Web Cryptography Working Group
- Specification Document(s): [[ This Document ]]
- Algorithm Name: "RSA-OAEP-384"
- Algorithm Description: RSA-OAEP using SHA-384 and MGF1 with SHA-384
- Algorithm Usage Location(s): "alg"
- JOSE Implementation Requirements: Optional
- Change Controller: W3C Web Cryptography Working Group
- Specification Document(s): [[ This Document ]]
- Algorithm Name: "RSA-OAEP-512"
- Algorithm Description: RSA-OAEP using SHA-512 and MGF1 with SHA-512
- Algorithm Usage Location(s): "alg"
- JOSE Implementation Requirements: Optional
- Change Controller: W3C Web Cryptography Working Group
- Specification Document(s): [[ This Document ]]
- Algorithm Name: "A128CBC"
- Algorithm Description: AES CBC using 128 bit key
- Algorithm Usage Location(s): "JWK"
- JOSE Implementation Requirements: Prohibited
- Change Controller: W3C Web Cryptography Working Group
- Specification Document(s): [[ This Document ]]
- Algorithm Name: "A192CBC"
- Algorithm Description: AES CBC using 192 bit key
- Algorithm Usage Location(s): "JWK"
- JOSE Implementation Requirements: Prohibited
- Change Controller: W3C Web Cryptography Working Group
- Specification Document(s): [[ This Document ]]
- Algorithm Name: "A256CBC"
- Algorithm Description: AES CBC using 256 bit key
- Algorithm Usage Location(s): "JWK"
- JOSE Implementation Requirements: Prohibited
- Change Controller: W3C Web Cryptography Working Group
- Specification Document(s): [[ This Document ]]
- Algorithm Name: "A128CTR"
- Algorithm Description: AES CTR using 128 bit key
- Algorithm Usage Location(s): "JWK"
- JOSE Implementation Requirements: Prohibited
- Change Controller: W3C Web Cryptography Working Group
- Specification Document(s): [[ This Document ]]
- Algorithm Name: "A192CTR"
- Algorithm Description: AES CTR using 192 bit key
- Algorithm Usage Location(s): "JWK"
- JOSE Implementation Requirements: Prohibited
- Change Controller: W3C Web Cryptography Working Group
- Specification Document(s): [[ This Document ]]
- Algorithm Name: "A256CTR"
- Algorithm Description: AES CTR using 256 bit key
- Algorithm Usage Location(s): "JWK"
- JOSE Implementation Requirements: Prohibited
- Change Controller: W3C Web Cryptography Working Group
- Specification Document(s): [[ This Document ]]
- Algorithm Name: "HS1"
- Algorithm Description: HMAC using SHA-1
- Algorithm Usage Location(s): "JWK"
- JOSE Implementation Requirements: Prohibited
- Change Controller: W3C Web Cryptography Working Group
- Specification Document(s): [[ This Document ]]
- Parameter Name: "ext"
- Parameter Description: Extractable
- Used with "kty" Value(s): *
- Parameter Information Class: Public
- Change Controller: W3C Web Cryptography Working Group
- Specification Document(s): [[ This Document ]]
Thanks are due especially to Ryan Sleevi, the original author and editor, and Mark Watson, the former editor of this document.
Thanks to Adam Barth, Alex Russell, Ali Asad, Arun Ranganathan, Brian Smith, Brian Warner, Channy Yun, Charles Engelke, Eric Roman, Glenn Adams, Jim Schaad, Kai Engert, Michael Hutchinson, Michael B. Jones, Nick Van den Bleeken, Richard Barnes, Ryan Hurst, Tim Taubert, Vijay Bharadwaj, Virginie Galindo, and Wan-Teh Chang for their technical feedback and assistance.
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.
This section is non-normative.
Refer to algorithm-specific sections for the normative requirements of importing and exporting JWK.
| JSON Web Key | AlgorithmIdentifier |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
This 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"
|
[RFC3447] |
| id-ecPublicKey (1.2.840.10045.2.1) | ECPoint | "ECDH" or "ECDSA" |
[RFC5480] |
| id-Ed25519 (1.3.101.112) | BIT STRING |
"Ed25519"
|
[RFC8410] |
| id-X25519 (1.3.101.110) | BIT STRING |
"X25519"
|
[RFC8410] |
The object identifiers used by this specification do not
include information about the specific algorithm and hash
that the key is intended to be used with. If this is
required, it's recommended that the "jwk"
key format is used instead.
This 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"
|
[RFC3447] |
| id-ecPublicKey (1.2.840.10045.2.1) | ECPrivateKey | "ECDH" or "ECDSA" |
[RFC5480] |
| id-Ed25519 (1.3.101.112) | CurvePrivateKey |
"Ed25519"
|
[RFC8410] |
| id-X25519 (1.3.101.110) | CurvePrivateKey |
"X25519"
|
[RFC8410] |
- [DOM]
- DOM Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://dom.spec.whatwg.org/
- [ECMA-262]
- ECMAScript Language Specification. Ecma International. URL: https://tc39.es/ecma262/multipage/
- [encoding]
- Encoding Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://encoding.spec.whatwg.org/
- [FIPS-180-4]
- FIPS PUB 180-4: Secure Hash Standard (SHS). U.S. Department of Commerce/National Institute of Standards and Technology. August 2015. National Standard. URL: https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf
- [FIPS-198-1]
- The Keyed-Hash Message Authentication Code (HMAC). NIST. July 2008. URL: https://csrc.nist.gov/publications/fips/fips198-1/FIPS-198-1_final.pdf
- [HTML]
- HTML Standard. Anne van Kesteren; Domenic Denicola; Dominic Farolino; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/
- [Infra]
- Infra Standard. Anne van Kesteren; Domenic Denicola. WHATWG. Living Standard. URL: https://infra.spec.whatwg.org/
- [JWA]
- JSON Web Algorithms (JWA). M. Jones. IETF. May 2015. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7518
- [JWK]
- JSON Web Key (JWK). M. Jones. IETF. May 2015. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7517
- [NIST-SP800-38A]
- NIST Special Publication 800-38A: Recommendation for Block Cipher Modes of Operation, Methods and Techniques. NIST. December 2001. URL: https://csrc.nist.gov/publications/nistpubs/800-38a/sp800-38a.pdf
- [NIST-SP800-38D]
- NIST Special Publication 800-38D: Recommendation for Block Cipher Modes of Operation: Galois/Counter Mode (GCM) and GMAC. NIST. November 2007. URL: https://csrc.nist.gov/publications/nistpubs/800-38D/SP-800-38D.pdf
- [RFC2119]
- Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
- [RFC2141]
- URN Syntax. R. Moats. IETF. May 1997. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc2141
- [RFC2315]
- PKCS #7: Cryptographic Message Syntax Version 1.5. B. Kaliski. IETF. March 1998. Informational. URL: https://www.rfc-editor.org/rfc/rfc2315
- [RFC3394]
- Advanced Encryption Standard (AES) Key Wrap Algorithm. J. Schaad; R. Housley. IETF. September 2002. Informational. URL: https://www.rfc-editor.org/rfc/rfc3394
- [RFC3447]
- Public-Key Cryptography Standards (PKCS) #1: RSA Cryptography Specifications Version 2.1. J. Jonsson; B. Kaliski. IETF. February 2003. Informational. URL: https://www.rfc-editor.org/rfc/rfc3447
- [RFC4122]
- A Universally Unique IDentifier (UUID) URN Namespace. P. Leach; M. Mealling; R. Salz. IETF. July 2005. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc4122
- [RFC5208]
- Public-Key Cryptography Standards (PKCS) #8: Private-Key Information Syntax Specification Version 1.2. B. Kaliski. IETF. May 2008. Informational. URL: https://www.rfc-editor.org/rfc/rfc5208
- [RFC5280]
- Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile. D. Cooper; S. Santesson; S. Farrell; S. Boeyen; R. Housley; W. Polk. IETF. May 2008. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc5280
- [RFC5480]
- Elliptic Curve Cryptography Subject Public Key Information. S. Turner; D. Brown; K. Yiu; R. Housley; T. Polk. IETF. March 2009. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc5480
- [RFC5869]
- HMAC-based Extract-and-Expand Key Derivation Function (HKDF). H. Krawczyk; P. Eronen. IETF. May 2010. Informational. URL: https://www.rfc-editor.org/rfc/rfc5869
- [RFC5915]
- Elliptic Curve Private Key Structure. S. Turner; D. Brown. IETF. June 2010. Informational. URL: https://www.rfc-editor.org/rfc/rfc5915
- [RFC6090]
- Fundamental Elliptic Curve Cryptography Algorithms. D. McGrew; K. Igoe; M. Salter. IETF. February 2011. Informational. URL: https://www.rfc-editor.org/rfc/rfc6090
- [RFC7748]
- Elliptic Curves for Security. A. Langley; M. Hamburg; S. Turner. IETF. January 2016. Informational. URL: https://www.rfc-editor.org/rfc/rfc7748
- [RFC8018]
- PKCS #5: Password-Based Cryptography Specification Version 2.1. K. Moriarty, Ed.; B. Kaliski; A. Rusch. IETF. January 2017. Informational. URL: https://www.rfc-editor.org/rfc/rfc8018
- [RFC8032]
- Edwards-Curve Digital Signature Algorithm (EdDSA). S. Josefsson; I. Liusvaara. IETF. January 2017. Informational. URL: https://www.rfc-editor.org/rfc/rfc8032
- [RFC8037]
- CFRG Elliptic Curve Diffie-Hellman (ECDH) and Signatures in JSON Object Signing and Encryption (JOSE). I. Liusvaara. IETF. January 2017. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc8037
- [RFC8174]
- Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
- [RFC8410]
- Algorithm Identifiers for Ed25519, Ed448, X25519, and X448 for Use in the Internet X.509 Public Key Infrastructure. S. Josefsson; J. Schaad. IETF. August 2018. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc8410
- [SEC1]
- SEC 1: Elliptic Curve Cryptography. Certicom Research. URL: https://www.secg.org/sec1-v2.pdf
- [WebIDL]
- Web IDL Standard. Edgar Chen; Timothy Gu. WHATWG. Living Standard. URL: https://webidl.spec.whatwg.org/
- [X690]
- Information technology - ASN.1 encoding rules: Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules (DER). Justin Uberti; Cullen Jennings; Eric Rescorla. ITU-T. November 2008. ITU-T Recommendation. URL: https://tools.ietf.org/html/draft-ietf-rtcweb-jsep/
- [INDEXEDDB]
- Indexed Database API. Nikunj Mehta; Jonas Sicking; Eliot Graff; Andrei Popescu; Jeremy Orlow; Joshua Bell. W3C. 8 January 2015. W3C Recommendation. URL: https://www.w3.org/TR/IndexedDB/
Referenced in:
- § 20.1 Description
- § 20.8.4 Import Key (2)
- § 20.8.5 Export Key (2)
- § 21.1 Description
- § 21.4.4 Import Key (2)
- § 21.4.5 Export Key
- § 22.1 Description
- § 22.4.4 Import Key (2)
- § 22.4.5 Export Key
- § 23.1 Description
- § 23.4 EcKeyGenParams dictionary
- § 23.7.1 Sign
- § 23.7.2 Verify
- § 23.7.3 Generate Key
- § 23.7.4 Import Key (2) (3) (4) (5) (6) (7) (8)
- § 23.7.5 Export Key (2) (3) (4)
- § 24.1 Description
- § 24.4.1 Generate Key
- § 24.4.2 Derive Bits
- § 24.4.3 Import Key (2) (3) (4) (5) (6) (7) (8)
- § 24.4.4 Export Key (2) (3) (4)
- § 31.1 Description
- § 31.6.4 Import Key (2)
- § 31.6.5 Export Key (2)
- § 33.1 Description
- § 34.1 Description
Referenced in:
Referenced in:
Referenced in:
- § 10.1.1 The getRandomValues method (2)
- § 14.3.1 The encrypt method
- § 14.3.2 The decrypt method
- § 14.3.3 The sign method
- § 14.3.4 The verify method
- § 14.3.5 The digest method
- § 14.3.6 The generateKey method
- § 14.3.7 The deriveKey method
- § 14.3.8 The deriveBits method
- § 14.3.9 The importKey method
- § 14.3.10 The exportKey method
- § 14.3.11 The wrapKey method
- § 14.3.12 The unwrapKey method
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
- § 11. Algorithm dictionary
- § 11.1 Algorithm Dictionary Members
- § 18.4.1 Description
- § 18.4.4 Normalizing an algorithm (2)
- § 20.3 RsaKeyGenParams dictionary
- § 20.7 RsaHashedImportParams dictionary
- § 21.3 RsaPssParams dictionary
- § 22.3 RsaOaepParams dictionary
- § 23.3 EcdsaParams dictionary
- § 23.4 EcKeyGenParams dictionary
- § 23.6 EcKeyImportParams dictionary
- § 24.3 EcdhKeyDeriveParams dictionary
- § 27.3 AesCtrParams dictionary
- § 27.5 AesKeyGenParams dictionary
- § 27.6 AesDerivedKeyParams dictionary
- § 28.3 AesCbcParams dictionary
- § 29.3 AesGcmParams dictionary
- § 31.3 HmacImportParams dictionary
- § 31.5 HmacKeyGenParams dictionary
- § 33.3 HkdfParams dictionary
- § 34.3 Pbkdf2Params dictionary
Referenced in:
- § 11. Algorithm dictionary
- § 14. SubtleCrypto interface (2) (3) (4) (5) (6) (7) (8) (9) (10) (11) (12) (13)
- § 14.3.1 The encrypt method
- § 14.3.2 The decrypt method
- § 14.3.3 The sign method
- § 14.3.4 The verify method
- § 14.3.5 The digest method
- § 18.4.1 Description (2)
- § 18.4.4 Normalizing an algorithm (2)
Referenced in:
Referenced in:
- § 11. Algorithm dictionary
- § 14.3.1 The encrypt method
- § 14.3.2 The decrypt method
- § 14.3.3 The sign method
- § 14.3.4 The verify method
- § 14.3.7 The deriveKey method
- § 14.3.8 The deriveBits method
- § 14.3.10 The exportKey method
- § 14.3.11 The wrapKey method
- § 14.3.12 The unwrapKey method
- § 18.4.4 Normalizing an algorithm (2)
- § 24.4.1 Generate Key
- § 31.6.3 Generate Key
- § 32.3.1 Digest (2) (3) (4)
Referenced in:
- § 12. KeyAlgorithm dictionary
- § 12.1 Description
- § 13.3 CryptoKey internal slots
- § 20.5 RsaKeyAlgorithm dictionary
- § 20.6 RsaHashedKeyAlgorithm dictionary
- § 23.5 EcKeyAlgorithm dictionary
- § 25.3.3 Generate Key
- § 25.3.4 Import Key (2) (3) (4)
- § 26.3.2 Generate Key
- § 26.3.3 Import Key (2) (3) (4)
- § 27.4 AesKeyAlgorithm dictionary
- § 31.4 HmacKeyAlgorithm dictionary (2)
- § 31.6.3 Generate Key
- § 31.6.4 Import Key
- § 33.4.2 Import key
- § 34.4.2 Import key
Referenced in:
- § 12. KeyAlgorithm dictionary
- § 14.3.1 The encrypt method
- § 14.3.2 The decrypt method
- § 14.3.3 The sign method
- § 14.3.4 The verify method
- § 14.3.7 The deriveKey method
- § 14.3.8 The deriveBits method
- § 14.3.11 The wrapKey method
- § 14.3.12 The unwrapKey method
- § 18.4.4 Normalizing an algorithm
- § 20.8.3 Generate Key
- § 20.8.4 Import Key
- § 20.8.5 Export Key
- § 21.4.3 Generate Key
- § 21.4.4 Import Key
- § 21.4.5 Export Key
- § 22.4.3 Generate Key
- § 22.4.4 Import Key
- § 22.4.5 Export Key
- § 23.7.3 Generate Key
- § 23.7.4 Import Key (2) (3) (4)
- § 24.4.2 Derive Bits (2)
- § 24.4.3 Import Key (2) (3) (4)
- § 25.3.3 Generate Key
- § 25.3.4 Import Key (2) (3) (4)
- § 26.3.1 Derive Bits (2)
- § 26.3.2 Generate Key
- § 26.3.3 Import Key (2) (3) (4)
- § 27.7.3 Generate Key
- § 27.7.4 Import Key
- § 28.4.3 Generate Key
- § 28.4.4 Import Key
- § 29.4.3 Generate Key
- § 29.4.4 Import Key
- § 30.3.3 Generate Key
- § 30.3.4 Import Key
- § 31.6.3 Generate Key (2)
- § 31.6.4 Import Key (2) (3) (4) (5) (6)
- § 31.6.5 Export Key (2) (3) (4) (5)
- § 33.4.2 Import key
- § 34.4.2 Import key
Referenced in:
- § 5.1 Underlying Cryptographic Implementation (2)
- § 5.2 Key Storage (2) (3) (4) (5)
- § 6.1 Security considerations for implementers (2) (3)
- § 6.2 Security considerations for authors (2)
- § 12. KeyAlgorithm dictionary
- § 12.1 Description
- § 12.2 KeyAlgorithm dictionary members
- § 13. CryptoKey interface
- § 13.3 CryptoKey internal slots (2)
- § 13.5 Serialization and deserialization steps (2)
- § 14. SubtleCrypto interface (2) (3) (4) (5) (6) (7) (8) (9) (10) (11) (12) (13) (14)
- § 14.3.1 The encrypt method
- § 14.3.2 The decrypt method
- § 14.3.3 The sign method
- § 14.3.4 The verify method
- § 14.3.6 The generateKey method
- § 14.3.9 The importKey method
- § 17. CryptoKeyPair dictionary (2)
- § 20.2 Registration
- § 20.8.3 Generate Key (2)
- § 20.8.4 Import Key (2) (3) (4)
- § 21.2 Registration
- § 21.4.3 Generate Key (2)
- § 21.4.4 Import Key (2) (3) (4)
- § 22.2 Registration
- § 22.4.3 Generate Key (2)
- § 22.4.4 Import Key (2) (3) (4)
- § 23.2 Registration
- § 23.7.3 Generate Key (2)
- § 23.7.4 Import Key (2) (3) (4) (5)
- § 23.7.5 Export Key
- § 24.2 Registration
- § 24.3 EcdhKeyDeriveParams dictionary
- § 24.4.1 Generate Key (2)
- § 24.4.3 Import Key (2) (3) (4) (5)
- § 24.4.4 Export Key
- § 25.2 Registration
- § 25.3.3 Generate Key (2)
- § 25.3.4 Import Key (2) (3) (4) (5)
- § 25.3.5 Export Key
- § 26.2 Registration
- § 26.3.2 Generate Key (2)
- § 26.3.3 Import Key (2) (3) (4) (5)
- § 26.3.4 Export Key
- § 27.2 Registration (2)
- § 27.7.3 Generate Key
- § 27.7.4 Import Key
- § 28.2 Registration (2)
- § 28.4.3 Generate Key
- § 28.4.4 Import Key
- § 29.2 Registration (2)
- § 29.4.3 Generate Key
- § 29.4.4 Import Key
- § 30.2 Registration (2)
- § 30.3.3 Generate Key
- § 30.3.4 Import Key
- § 31.2 Registration (2)
- § 31.6.3 Generate Key
- § 31.6.4 Import Key
- § 33.2 Registration
- § 33.4.2 Import key
- § 34.2 Registration
- § 34.4.2 Import key
Referenced in:
- § 13. CryptoKey interface
- § 14.3.6 The generateKey method
- § 14.3.7 The deriveKey method
- § 14.3.9 The importKey method
- § 14.3.12 The unwrapKey method
- § 27.7.3 Generate Key
- § 27.7.4 Import Key
- § 28.4.3 Generate Key
- § 28.4.4 Import Key
- § 29.4.3 Generate Key
- § 29.4.4 Import Key
- § 30.3.3 Generate Key
- § 30.3.4 Import Key
- § 31.6.3 Generate Key
- § 31.6.4 Import Key
- § 33.4.2 Import key
- § 34.4.2 Import key
Referenced in:
Referenced in:
- § 13. CryptoKey interface
- § 14.3.6 The generateKey method
- § 14.3.7 The deriveKey method
- § 14.3.9 The importKey method
- § 14.3.12 The unwrapKey method
- § 20.8.1 Sign
- § 20.8.3 Generate Key
- § 20.8.4 Import Key (2)
- § 20.8.5 Export Key (2)
- § 21.4.1 Sign
- § 21.4.3 Generate Key
- § 21.4.4 Import Key (2)
- § 21.4.5 Export Key (2)
- § 22.4.2 Decrypt
- § 22.4.3 Generate Key
- § 22.4.4 Import Key (2)
- § 22.4.5 Export Key (2)
- § 23.7.1 Sign
- § 23.7.3 Generate Key
- § 23.7.4 Import Key (2)
- § 23.7.5 Export Key (2)
- § 24.4.1 Generate Key
- § 24.4.2 Derive Bits
- § 24.4.3 Import Key (2)
- § 24.4.4 Export Key (2)
- § 25.3.1 Sign
- § 25.3.3 Generate Key
- § 25.3.4 Import Key (2)
- § 25.3.5 Export Key (2)
- § 26.3.1 Derive Bits
- § 26.3.2 Generate Key
- § 26.3.3 Import Key (2)
- § 26.3.4 Export Key (2)
Referenced in:
Referenced in:
- § 13.4 CryptoKey interface members
- § 13.5 Serialization and deserialization steps (2)
- § 14.3.6 The generateKey method
- § 14.3.7 The deriveKey method
- § 14.3.9 The importKey method
- § 14.3.12 The unwrapKey method
- § 20.8.1 Sign
- § 20.8.2 Verify
- § 20.8.3 Generate Key (2)
- § 20.8.4 Import Key (2) (3) (4)
- § 20.8.5 Export Key (2) (3)
- § 21.4.1 Sign
- § 21.4.2 Verify
- § 21.4.3 Generate Key (2)
- § 21.4.4 Import Key (2) (3) (4)
- § 21.4.5 Export Key (2) (3)
- § 22.4.1 Encrypt
- § 22.4.2 Decrypt
- § 22.4.3 Generate Key (2)
- § 22.4.4 Import Key (2) (3) (4)
- § 22.4.5 Export Key (2) (3)
- § 23.7.1 Sign
- § 23.7.2 Verify
- § 23.7.3 Generate Key (2)
- § 23.7.4 Import Key (2) (3) (4) (5)
- § 23.7.5 Export Key (2) (3) (4)
- § 24.4.1 Generate Key (2)
- § 24.4.2 Derive Bits (2)
- § 24.4.3 Import Key (2) (3) (4) (5)
- § 24.4.4 Export Key (2) (3) (4)
- § 25.3.1 Sign
- § 25.3.2 Verify
- § 25.3.3 Generate Key (2)
- § 25.3.4 Import Key (2) (3) (4) (5)
- § 25.3.5 Export Key (2) (3) (4)
- § 26.3.1 Derive Bits (2)
- § 26.3.2 Generate Key (2)
- § 26.3.3 Import Key (2) (3) (4) (5)
- § 26.3.4 Export Key (2) (3) (4)
- § 27.7.3 Generate Key
- § 27.7.4 Import Key
- § 28.4.3 Generate Key
- § 28.4.4 Import Key
- § 29.4.3 Generate Key
- § 29.4.4 Import Key
- § 30.3.3 Generate Key
- § 30.3.4 Import Key
- § 31.6.3 Generate Key
- § 31.6.4 Import Key
- § 33.4.2 Import key
- § 34.4.2 Import key
Referenced in:
- § 13.4 CryptoKey interface members
- § 13.5 Serialization and deserialization steps (2) (3)
- § 14.3.7 The deriveKey method
- § 14.3.9 The importKey method
- § 14.3.10 The exportKey method
- § 14.3.11 The wrapKey method
- § 14.3.12 The unwrapKey method
- § 20.8.3 Generate Key (2)
- § 20.8.5 Export Key
- § 21.4.3 Generate Key (2)
- § 21.4.5 Export Key
- § 22.4.3 Generate Key (2)
- § 22.4.5 Export Key
- § 23.7.3 Generate Key (2)
- § 23.7.5 Export Key
- § 24.4.1 Generate Key (2)
- § 24.4.4 Export Key
- § 25.3.3 Generate Key (2)
- § 25.3.5 Export Key
- § 26.3.2 Generate Key (2)
- § 26.3.4 Export Key
- § 27.7.3 Generate Key
- § 27.7.5 Export Key
- § 28.4.3 Generate Key
- § 28.4.5 Export Key
- § 29.4.3 Generate Key
- § 29.4.5 Export Key
- § 30.3.3 Generate Key
- § 30.3.5 Export Key
- § 31.6.3 Generate Key
- § 31.6.5 Export Key
Referenced in:
- § 13.3 CryptoKey internal slots
- § 13.4 CryptoKey interface members
- § 13.5 Serialization and deserialization steps (2)
- § 14.3.1 The encrypt method
- § 14.3.2 The decrypt method
- § 14.3.3 The sign method
- § 14.3.4 The verify method
- § 14.3.7 The deriveKey method
- § 14.3.8 The deriveBits method
- § 14.3.10 The exportKey method (2)
- § 14.3.11 The wrapKey method (2) (3)
- § 14.3.12 The unwrapKey method
- § 20.8.1 Sign
- § 20.8.2 Verify
- § 20.8.3 Generate Key (2)
- § 20.8.4 Import Key
- § 20.8.5 Export Key
- § 21.4.1 Sign
- § 21.4.2 Verify
- § 21.4.3 Generate Key (2)
- § 21.4.4 Import Key
- § 21.4.5 Export Key (2)
- § 22.4.1 Encrypt
- § 22.4.2 Decrypt
- § 22.4.3 Generate Key (2)
- § 22.4.4 Import Key
- § 22.4.5 Export Key (2)
- § 23.7.1 Sign (2)
- § 23.7.2 Verify (2)
- § 23.7.3 Generate Key (2)
- § 23.7.4 Import Key (2) (3) (4)
- § 23.7.5 Export Key (2) (3) (4) (5) (6) (7) (8) (9) (10) (11) (12) (13) (14) (15) (16) (17)
- § 24.4.1 Generate Key (2)
- § 24.4.2 Derive Bits (2) (3) (4) (5) (6)
- § 24.4.3 Import Key (2) (3) (4)
- § 24.4.4 Export Key (2) (3) (4) (5) (6) (7) (8) (9) (10) (11) (12) (13) (14) (15) (16) (17)
- § 25.3.3 Generate Key (2)
- § 25.3.4 Import Key (2) (3) (4)
- § 26.3.1 Derive Bits (2)
- § 26.3.2 Generate Key (2)
- § 26.3.3 Import Key (2) (3) (4)
- § 27.7.3 Generate Key
- § 27.7.4 Import Key
- § 28.4.3 Generate Key
- § 28.4.4 Import Key
- § 29.4.3 Generate Key
- § 29.4.4 Import Key
- § 30.3.3 Generate Key
- § 30.3.4 Import Key
- § 31.6.1 Sign
- § 31.6.2 Verify
- § 31.6.3 Generate Key
- § 31.6.4 Import Key
- § 31.6.5 Export Key
- § 33.4.2 Import key
- § 34.4.2 Import key
Referenced in:
- § 13.3 CryptoKey internal slots
- § 13.4 CryptoKey interface members
- § 13.5 Serialization and deserialization steps (2)
- § 14.3.1 The encrypt method
- § 14.3.2 The decrypt method
- § 14.3.3 The sign method
- § 14.3.4 The verify method
- § 14.3.6 The generateKey method
- § 14.3.7 The deriveKey method (2)
- § 14.3.8 The deriveBits method
- § 14.3.9 The importKey method
- § 14.3.11 The wrapKey method
- § 14.3.12 The unwrapKey method (2)
- § 20.8.3 Generate Key (2)
- § 21.4.3 Generate Key (2)
- § 22.4.3 Generate Key (2)
- § 23.7.3 Generate Key (2)
- § 24.4.1 Generate Key (2)
- § 25.3.3 Generate Key (2)
- § 26.3.2 Generate Key (2)
- § 27.7.3 Generate Key
- § 27.7.5 Export Key
- § 28.4.3 Generate Key
- § 29.4.3 Generate Key
- § 30.3.3 Generate Key
- § 31.6.3 Generate Key
Referenced in:
- § 5.1 Underlying Cryptographic Implementation (2)
- § 13.3 CryptoKey internal slots
- § 13.5 Serialization and deserialization steps (2)
- § 20.8.1 Sign
- § 20.8.2 Verify
- § 20.8.5 Export Key (2) (3) (4)
- § 21.4.1 Sign
- § 21.4.2 Verify
- § 21.4.5 Export Key (2) (3) (4)
- § 22.4.5 Export Key (2) (3) (4)
- § 23.7.5 Export Key (2) (3) (4) (5)
- § 24.4.2 Derive Bits
- § 24.4.4 Export Key (2) (3) (4) (5)
- § 25.3.5 Export Key (2) (3)
- § 26.3.1 Derive Bits
- § 26.3.4 Export Key (2) (3)
- § 27.7.5 Export Key (2) (3)
- § 28.4.5 Export Key (2) (3)
- § 29.4.5 Export Key (2) (3)
- § 30.3.5 Export Key (2) (3)
- § 31.6.1 Sign
- § 31.6.2 Verify
- § 31.6.5 Export Key (2)
- § 33.4.1 Derive Bits
- § 34.4.1 Derive Bits
Referenced in:
Referenced in:
Referenced in:
Referenced in:
- § 14. SubtleCrypto interface
- § 14.3.9 The importKey method (2)
- § 14.3.10 The exportKey method (2)
- § 14.3.11 The wrapKey method (2)
- § 14.3.12 The unwrapKey method (2)
- § 23.7.4 Import Key
- § 23.7.5 Export Key
- § 24.4.3 Import Key
- § 24.4.4 Export Key
- § 25.3.4 Import Key
- § 25.3.5 Export Key
- § 26.3.3 Import Key
- § 26.3.4 Export Key
- § 27.7.4 Import Key
- § 27.7.5 Export Key
- § 28.4.4 Import Key
- § 28.4.5 Export Key
- § 29.4.4 Import Key
- § 29.4.5 Export Key
- § 30.3.4 Import Key
- § 30.3.5 Export Key
- § 31.6.4 Import Key
- § 31.6.5 Export Key
- § 33.4.2 Import key
- § 34.4.2 Import key
Referenced in:
- § 14. SubtleCrypto interface
- § 14.3.9 The importKey method (2)
- § 14.3.10 The exportKey method
- § 14.3.11 The wrapKey method
- § 14.3.12 The unwrapKey method
- § 20.8.4 Import Key
- § 20.8.5 Export Key
- § 21.4.4 Import Key
- § 21.4.5 Export Key
- § 22.4.4 Import Key
- § 22.4.5 Export Key
- § 23.7.4 Import Key
- § 23.7.5 Export Key
- § 24.4.3 Import Key
- § 24.4.4 Export Key
- § 25.3.4 Import Key
- § 25.3.5 Export Key
- § 26.3.3 Import Key
- § 26.3.4 Export Key
Referenced in:
- § 14. SubtleCrypto interface
- § 14.3.9 The importKey method (2)
- § 14.3.10 The exportKey method
- § 14.3.11 The wrapKey method
- § 14.3.12 The unwrapKey method
- § 20.8.4 Import Key
- § 20.8.5 Export Key
- § 21.4.4 Import Key
- § 21.4.5 Export Key
- § 22.4.4 Import Key
- § 22.4.5 Export Key
- § 23.7.4 Import Key
- § 23.7.5 Export Key
- § 24.4.3 Import Key
- § 24.4.4 Export Key
- § 25.3.4 Import Key
- § 25.3.5 Export Key
- § 26.3.3 Import Key
- § 26.3.4 Export Key
Referenced in:
- § 14. SubtleCrypto interface
- § 14.3.9 The importKey method (2)
- § 14.3.10 The exportKey method
- § 14.3.11 The wrapKey method
- § 14.3.12 The unwrapKey method
- § 20.8.4 Import Key
- § 20.8.5 Export Key
- § 21.4.4 Import Key
- § 21.4.5 Export Key
- § 22.4.4 Import Key
- § 22.4.5 Export Key
- § 23.7.4 Import Key
- § 23.7.5 Export Key
- § 24.4.3 Import Key
- § 24.4.4 Export Key
- § 25.3.4 Import Key
- § 25.3.5 Export Key
- § 26.3.3 Import Key
- § 26.3.4 Export Key
- § 27.7.4 Import Key
- § 27.7.5 Export Key
- § 28.4.4 Import Key
- § 28.4.5 Export Key
- § 29.4.4 Import Key
- § 29.4.5 Export Key
- § 30.3.4 Import Key
- § 30.3.5 Export Key
- § 31.6.4 Import Key
- § 31.6.5 Export Key
- § B. Mapping between Algorithm and SubjectPublicKeyInfo
Referenced in:
- § 14.3.1 The encrypt method (2)
- § 14.3.2 The decrypt method (2)
- § 14.3.3 The sign method (2)
- § 14.3.4 The verify method (2)
- § 14.3.5 The digest method (2)
- § 14.3.6 The generateKey method (2)
- § 14.3.7 The deriveKey method (2)
- § 14.3.8 The deriveBits method (2)
- § 14.3.9 The importKey method (2)
- § 14.3.10 The exportKey method (2)
- § 14.3.11 The wrapKey method (2)
- § 14.3.12 The unwrapKey method (2)
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
- § 20.8.4 Import Key (2) (3)
- § 20.8.5 Export Key
- § 21.4.4 Import Key (2) (3)
- § 21.4.5 Export Key
- § 22.4.4 Import Key (2) (3)
- § 22.4.5 Export Key
- § 23.7.4 Import Key (2) (3)
- § 23.7.5 Export Key
- § 24.4.3 Import Key (2) (3)
- § 24.4.4 Export Key
- § 25.3.4 Import Key (2) (3)
- § 25.3.5 Export Key
- § 26.3.3 Import Key (2) (3)
- § 26.3.4 Export Key
Referenced in:
Referenced in:
- § 9. Terminology
- § 14. SubtleCrypto interface (2)
- § 14.1 Data Types
- § 14.3.9 The importKey method (2)
- § 15. JsonWebKey dictionary
- § 20.8.4 Import Key
- § 20.8.5 Export Key
- § 21.4.4 Import Key
- § 21.4.5 Export Key
- § 22.4.4 Import Key
- § 22.4.5 Export Key
- § 23.7.4 Import Key
- § 23.7.5 Export Key
- § 24.4.3 Import Key
- § 24.4.4 Export Key
- § 25.3.4 Import Key
- § 25.3.5 Export Key
- § 26.3.3 Import Key
- § 26.3.4 Export Key
- § 27.7.4 Import Key
- § 27.7.5 Export Key
- § 28.4.4 Import Key
- § 28.4.5 Export Key
- § 29.4.4 Import Key
- § 29.4.5 Export Key
- § 30.3.4 Import Key
- § 30.3.5 Export Key
- § 31.6.4 Import Key
- § 31.6.5 Export Key
Referenced in:
Referenced in:
- § 14. SubtleCrypto interface
- § 14.3.6 The generateKey method
- § 17. CryptoKeyPair dictionary
- § 20.2 Registration
- § 20.8.3 Generate Key
- § 21.2 Registration
- § 21.4.3 Generate Key
- § 22.2 Registration
- § 22.4.3 Generate Key
- § 23.2 Registration
- § 23.7.3 Generate Key
- § 24.2 Registration
- § 24.4.1 Generate Key
- § 25.2 Registration
- § 25.3.3 Generate Key
- § 26.2 Registration
- § 26.3.2 Generate Key
Referenced in:
Referenced in:
Referenced in:
- § 18.3 Specification Conventions
- § 20.2 Registration
- § 21.2 Registration
- § 22.2 Registration
- § 23.2 Registration
- § 24.2 Registration
- § 25.2 Registration
- § 26.2 Registration
- § 27.2 Registration
- § 28.2 Registration
- § 29.2 Registration
- § 30.2 Registration
- § 31.2 Registration
- § 32.2 Registration
- § 33.2 Registration
- § 34.2 Registration
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
- § 14.3.1 The encrypt method
- § 14.3.2 The decrypt method
- § 14.3.3 The sign method
- § 14.3.4 The verify method
- § 14.3.5 The digest method
- § 14.3.6 The generateKey method
- § 14.3.7 The deriveKey method (2) (3)
- § 14.3.8 The deriveBits method
- § 14.3.9 The importKey method
- § 14.3.11 The wrapKey method (2)
- § 14.3.12 The unwrapKey method (2) (3)
- § 18.4.4 Normalizing an algorithm (2) (3)
- § 20.8.4 Import Key
- § 21.4.4 Import Key
- § 22.4.4 Import Key
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
- § 20.6 RsaHashedKeyAlgorithm dictionary
- § 20.8.1 Sign
- § 20.8.2 Verify
- § 20.8.3 Generate Key
- § 20.8.4 Import Key
- § 20.8.5 Export Key
- § 21.4.1 Sign
- § 21.4.2 Verify
- § 21.4.3 Generate Key
- § 21.4.4 Import Key
- § 21.4.5 Export Key (2)
- § 22.4.1 Encrypt
- § 22.4.2 Decrypt
- § 22.4.3 Generate Key
- § 22.4.4 Import Key
- § 22.4.5 Export Key (2)
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
- § 23.5 EcKeyAlgorithm dictionary
- § 23.7.1 Sign (2)
- § 23.7.2 Verify (2)
- § 23.7.3 Generate Key
- § 23.7.4 Import Key (2) (3) (4)
- § 23.7.5 Export Key (2) (3) (4) (5) (6) (7) (8) (9) (10) (11) (12) (13) (14) (15) (16) (17)
- § 24.4.1 Generate Key
- § 24.4.2 Derive Bits (2) (3) (4)
- § 24.4.3 Import Key (2) (3) (4)
- § 24.4.4 Export Key (2) (3) (4) (5) (6) (7) (8) (9) (10) (11) (12) (13) (14) (15) (16) (17)
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
- § 27.4 AesKeyAlgorithm dictionary
- § 27.7.3 Generate Key
- § 27.7.4 Import Key
- § 27.7.5 Export Key (2) (3)
- § 28.4.3 Generate Key
- § 28.4.4 Import Key
- § 28.4.5 Export Key (2) (3)
- § 29.4.3 Generate Key
- § 29.4.4 Import Key
- § 29.4.5 Export Key (2) (3)
- § 30.3.3 Generate Key
- § 30.3.4 Import Key
- § 30.3.5 Export Key (2) (3)
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in: