Send feedback to public-webcrypto-comments@w3.org (archives), or file a bug (see existing bugs).
Copyright © 2014 W3C® (MIT, ERCIM, Keio, Beihang), All Rights Reserved. W3C liability, trademark and document use rules apply.
This specification describes a JavaScript API for performing basic cryptographic operations in web applications, such as hashing, signature generation and verification, and encryption and decryption. Additionally, it describes an API for applications to generate and/or manage the keying material necessary to perform these operations. Uses for this API range from user or service authentication, document or code signing, and the confidentiality and integrity of communications.
There are 19 further editorial notes in the document.
Publication as a Last Call Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This document is the 25 March 2014 Last Call Working Draft of the Web Cryptography API specification. Please send comments about this document to public-webcrypto-comments@w3.org (archived).
This document is produced by the Web Cryptography WG of the W3C.
Implementors should be aware that this specification is not stable. Implementors who are not taking part in the discussions are likely to find the specification changing out from under them in incompatible ways. Vendors interested in implementing this specification before it eventually reaches the Candidate Recommendation stage should join the mailing lists that follow and take part in the discussions.
This document was published by the Web Cryptography Working Group as a Last Call Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-webcrypto-comments@w3.org, the W3C's public email list for issues related to Web Cryptography. Archives of the public list and archives of the member's-only list are available. The Last Call period ends 20 May 2014. All comments are welcome.
In particular, the Web Cryptography Working Group invites discussion and feedback on this draft document by web developers, companies, standardization bodies or forums interested in deployment of secure services with web applications. Specifically, Web Cryptography Working Group is looking for priority feedback on:
Changes made to this document can be found in the W3C public Mercurial server.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This 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 common set of methods and events for dealing with initialization, processing data, and completing the operation to yield the final output. 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, key import and export, and key discovery.
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 wish to provide a rich user experience by providing authentication within the application itself.
Using the Web Cryptography API, such an 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.
Further, the authentication data could be further enhanced by binding the authentication to the TLS session that the client is authenticating over, by deriving a key based on properties of the underlying transport.
If a user did 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 choosing.
When exchanging documents that may contain sensitive or personal information, a web application may wish to ensure that only certain users can view the documents, even after they have been securely received, such as over TLS. One way that a web application can do so is by encrypting the documents with a secret key, and then wrapping that key with the public keys associated with authorized users.
When a user agent navigates to such a web application, the application may 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.
When storing data with remote service providers, users may wish to protect the confidentiality of their documents and data prior to uploading them. The Web Cryptography API allows an application to have a user select a private or secret key, to either derive encryption keys from the selected key or to directly encrypt documents using this key, and then to upload the transformed/encrypted data to the service provider using existing APIs.
This use case is similar to the Protected Document Exchange use case because Cloud Storage can be considered as a user exchanging protected data with himself in the future.
A web application may wish to accept electronic signatures on documents, in lieu of requiring physical signatures. An authorized signature may use a key that was pre-provisioned out-of-band by the web application, or it may be using a key that the client generated specifically for the web application.
The web application must be able to locate any appropriate keys for signatures, then direct the user to perform a signing operation over some data, as proof that they accept the document.
When caching data locally, an application may wish to ensure that this data cannot be modified in an offline attack. In such a case, the server may sign the data that it intends the client to cache, with a private key held by the server. The web application that subsequently uses this cached data may contain a public key that enables it to validate that the cache contents have not been modified by anyone else.
In addition to a number of web applications already offering chat based services, the rise of WebSockets and RTCWEB allows a great degree of flexibility in inter-user-agent messaging. While TLS/DTLS may be used to protect messages to web applications, users may wish to directly secure messages using schemes such as off-the-record (OTR) messaging.
The Web Cryptography API enables OTR, by allowing key agreement to be performed so that 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 of messages through the MACs.
A web application wishes to make use of the structures and format of messages defined by the IETF Javascript Object Signing and Encryption (JOSE) Working Group. The web application wishes to manipulate public keys encoded in the JSON key format (JWK), messages that have been integrity protected using digital signatures or MACs (JWS), or that have been encrypted (JWE).
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The keywords MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, RECOMMENDED, MAY, OPTIONAL, in this specification are to be interpreted as described in Key words for use in RFCs to Indicate Requirement Levels [RFC2119].
The following conformance classes are defined by this specification:
A user agent is considered to be a conforming user agent if it satisfies all of the MUST-, REQUIRED- and SHALL-level criteria in this specification that apply to implementations. This specification uses both the terms "conforming user agent" and "user agent" to refer to this product class.
User agents MAY implement algorithms in this specification in any way desired, so long as the end result is indistinguishable from the result that would be obtained from the specification's algorithms.
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.
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 Key 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 behaviours of individual algorithms, if implemented.
Although the API does not expose the notion of cryptographic providers or modules, each key is internally bound to a cryptographic provider or module, so web applications can rest assured that the right cryptographic provider or module will be used to perform cryptographic operations involving that key.
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.
User agents should take care before exposing keys that were not explicitly generated via the API in this specification or exposing keys that were generated in the context of other origins. Two applications with access to the same key handle may be able to spoof messages to each other, as both valid and hostile messages will appear to be valid for the given key. Because of this, user agents are recommended to obtain express permission from the user before re-using keys, unless there is a prearranged trust relationship.
User agents should be aware of the security considerations of each algorithm implemented and exposed to applications. For a number of algorithms, their cryptographic strength is relative to the amount of work necessary to compute the result, whether this be through the generation of significantly large prime numbers or through the repeatedly iterating through the same algorithm to reduce its susceptibility to brute force. Implementations should therefore take measures to ensure against misuse. Such measures may include requiring express user permission to compute some expensive operations, rate limiting the number of times the application may call certain APIs/algorithms, and defining implementation-specific upper limits for inputs such as key sizes or iteration counts, as appropriate for the device on which the implementation executes.
In some cases, the same underlying cryptographic key material may be re-usable for multiple algorithms. One such example is an RSA key, which may be used for both signing and encryption, or with RSA-PKCS1v1.5 and RSA-PSS. In some cases, the re-use of this key material may undermine the security properties of the key and allow applications to recover the raw material.
While this API provides important functionality for the development of secure applications, it does not attempt to provide a mitigation for existing threats to the web security model, such as script injection or hostile intermediaries. As such, application developers must take care to ensure applications are secured against common and traditional attacks, such as script injection, by making use of appropriate existing functionality such as Content Security Policy and the use of TLS.
This API includes a variety of cryptographic operations, some of which may have known security issues when used inappropriately. Application developers should take care to review the appropriate cryptographic literature before making use of certain algorithms, and should avoid attempting to develop new cryptographic protocols whenever possible.
While the API in this specification provides a means to protect keys from future access by web applications, it makes no statements as to how the actual keying material will be stored by an implementation. As such, although a key may be inaccessible to web content, it should not be presumed that it is inaccessible to end-users. For example, a conforming user agent may choose to implement key storage by storing key material in plain text on device storage. Although the user agent prevents access to the raw keying material to web applications, any user with access to device storage may be able to recover the key.
This section is non-normative.
This specification relies on underlying specifications.
A conforming user agent MUST support at
least the subset of the functionality defined in DOM4 that this specification relies
upon; in particular, it MUST support Promises
.
[DOM4]
A conforming user agent MUST support at least the subset of the functionality defined in HTML that this specification relies upon; in particular, it MUST support event loops and event handler IDL attributes. [HTML]
A conforming user agent MUST be a conforming implementation of the IDL fragments in this specification, as described in the Web IDL specification. [WebIDL]
A conforming user agent MUST support the Typed Arrays specification [TypedArrays].
The terms and algorithms document, event handler IDL attributes, event handler event type, origin, same origin, URL, event loops, task, task source, queue a task, and structured clone, are defined by the HTML specification [HTML].
Comparing two strings in a case-sensitive manner means comparing them exactly, code point for code point.
When this specification says to terminate the algorithm, the user agent must terminate the algorithm after finishing the step it is on. The algorithm referred to is the set of specification-defined processing steps, rather than the underlying cryptographic algorithm that may be in the midst of processing.
When this specification says to parse an ASN.1 structure, the user agent must perform the following steps:
Let data be a sequence of bytes to be parsed.
Let structure be the ASN.1 structure to be parsed.
Let exactData be an optional boolean value. If it is not supplied,
let it be initialized to true
.
Parse data according to the Distinguished Encoding Rules of X.690 (11/08), using structure as the ASN.1 structure to be decoded.
If exactData was specified, and all of the bytes of data were
not consumed during the parsing phase, then
return an error named
DataError
.
Return the parsed ASN.1 structure.
When this specification says to parse a
subjectPublicKeyInfo, the user agent must
parse an ASN.1 structure, with
data set to the sequence of bytes to be parsed, structure as the
ASN.1 structure of subjectPublicKeyInfo, as specified in RFC 5280,
and exactData set to true
.
When this specification says to parse a
PrivateKeyInfo, the user agent must parse
an ASN.1 structure with data set to the sequence of bytes to be parsed,
structure as the ASN.1 structure of PrivateKeyInfo, as specified in
RFC 5208, and exactData set to true
.
When this specification says to parse a JWK, the user agent must run the following steps:
Let data be the sequence of bytes to be parsed.
Let json be the unicode string that results from interpreting data according to UTF-8.
Let result be the result of translating json into an internal object using the grammar specified in Section 15.12 of ECMA 262.
If result does not describe an Object type,
then return an error named
DataError
.
If the "kty"
field of result is not present, or is not a
string value, then return an error named
DataError
.
Return result.
When this specification says to calculate the usage intersection of two arrays, a and b the result shall be an array containing each recognised key usage value that appears in both a and b, in the order listed in the list of recognised key usage values, where a value is said to appear in an array if an element of the array exists that is a case-sensistive 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 an array containing all recognised key usage values.
[NoInterfaceObject]
interface RandomSource {
ArrayBufferView getRandomValues(ArrayBufferView array);
};
The RandomSource interface represents an interface to a cryptographically strong pseudo-random number generator seeded with truly random values.
The getRandomValues
method generates cryptographically random values. It must act as follows:
If array is not of an integer type (i.e., Int8Array, Uint8Array,
Int16Array, Uint16Array, Int32Array, or Uint32Array), throw a
TypeMismatchError
and
terminate the algorithm.
If the byteLength
of array is greater than 65536, throw a
QuotaExceededError
and
terminate the algorithm.
Overwrite all elements of array with cryptographically random values of the appropriate type.
Return array.
Do not generate keys using the getRandomValues
method. Use the
generateKey
method
instead.
The 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.
name
The KeyAlgorithm interface represents information about the contents of a given Key object.
[NoInterfaceObject]
interface KeyAlgorithm {
readonly attribute DOMString name
};
This section is non-normative
The KeyAlgorithm interface is a supplemental interface used to reflect the static, public properties of a Key back to an application. These properties can be used for determination of strength (e.g.: an attribute that indicates the size of the key or the parameters of its creation) as well as for protocol negotiations (e.g.: a particular instance of an inner hash).
The Key object represents an opaque reference to keying material that is managed by the user agent.
typedef DOMString KeyType;
typedef DOMString KeyUsage;
interface Key {
readonly attribute KeyType type;
readonly attribute boolean extractable;
readonly attribute KeyAlgorithm algorithm;
readonly attribute KeyUsage[] 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 Key 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, eg. when performing a cryptographic operation.
KeyType
"public"
, "private"
and "secret"
.
Opaque keying material, including that used for symmetric algorithms, is represented by
"secret"
, while keys used as part of asymmetric algorithms composed of
public/private keypairs will be either "public"
or "private"
.
KeyUsage
"encrypt"
,
"decrypt"
,
"sign"
,
"verify"
,
"deriveKey"
,
"deriveBits"
,
"wrapKey"
and
"unwrapKey"
.
type
extractable
algorithm
KeyAlgorithm
used to generate the key.
usages
Array
of KeyUsages
that
indicate what cryptographic operations may be used with this key.
When a user agent is required to obtain a structured clone of a Key object, it must run the following steps.
Key
object, it is important that the underlying cryptographic key
material not be exposed to a JavaScript implementation. Such a situation may arise if an
implementation fails to implement the structured clone algorithm correctly, such as by
allowing a Key
object to be serialized as part of a structured clone
implementation, but then deserializing it as a DOMString
, rather than as a
Key
object.
interface Crypto {
readonly attribute SubtleCrypto subtle;
};
Crypto implements RandomSource;
partial interface Window {
readonly attribute Crypto crypto;
};
typedef DOMString KeyFormat
;
typedef (ArrayBuffer or ArrayBufferView) CryptoOperationData;
interface SubtleCrypto {
Promise<any> encrypt(AlgorithmIdentifier algorithm,
Key key,
CryptoOperationData data);
Promise<any> decrypt(AlgorithmIdentifier algorithm,
Key key,
CryptoOperationData data);
Promise<any> sign(AlgorithmIdentifier algorithm,
Key key,
CryptoOperationData data);
Promise<any> verify(AlgorithmIdentifier algorithm,
Key key,
CryptoOperationData signature,
CryptoOperationData data);
Promise<any> digest(AlgorithmIdentifier algorithm,
CryptoOperationData data);
Promise<any> generateKey(AlgorithmIdentifier algorithm,
boolean extractable,
KeyUsage[] keyUsages );
Promise<any> deriveKey(AlgorithmIdentifier algorithm,
Key baseKey,
AlgorithmIdentifier derivedKeyType,
boolean extractable,
KeyUsage[] keyUsages );
Promise<any> deriveBits(AlgorithmIdentifier algorithm,
Key baseKey,
unsigned long length);
// TBD: ISSUE-35
Promise<any> importKey(KeyFormat format,
CryptoOperationData keyData,
AlgorithmIdentifier? algorithm,
boolean extractable,
KeyUsage[] keyUsages );
Promise<any> exportKey(KeyFormat format, Key key);
// Note: wrapKey and unwrapKey remain "Features at Risk"
Promise<any> wrapKey(KeyFormat format,
Key key,
Key wrappingKey,
AlgorithmIdentifier wrapAlgorithm);
Promise<any> unwrapKey(KeyFormat format,
CryptoOperationData wrappedKey,
Key unwrappingKey,
AlgorithmIdentifier unwrapAlgorithm,
AlgorithmIdentifier? unwrappedKeyAlgorithm,
boolean extractable,
KeyUsage[] keyUsages );
};
This section is non-normative.
The SubtleCrypto interface provides a set of
methods for dealing with low-level cryptographic primitives and algorithms. It is
named SubtleCrypto
to reflect the fact that many of these algorithms
have subtle usage requirements in order to provide the required algorithmic
security guarantees.
For example, the direct use of an unauthenticated encryption scheme, such as AES in counter mode, gives potential attackers the ability to manipulate bits in the output by manipulating bits in the input, compromising the integrity of the message. However, AES-CTR can be used securely in combination with other cryptographic primitives, such as message authentication codes, to ensure the integrity of the protected message, but only when the message authentication code is constructed over the encrypted message and IV.
Developers making use of the SubtleCrypto interface are expected to be aware of the security concerns associated with both the design and implementation of the various algorithms provided. The raw algorithms are provided in order to allow developers maximum flexibility in implementing a variety of protocols and applications, each of which may represent the composition and security parameters in a unique manner that necessitate the use of the raw algorithms.
KeyFormat
All errors are reported asynchronously by calling the reject handler of the returned Promise. This includes WebIDL type mapping errors.
The encrypt
method returns a new Promise object that will encrypt data using
the specified
AlgorithmIdentifier
with
the supplied Key
. It must act
as follows:
Let algorithm, key and data be the
algorithm
, key
and data
parameters
passed to the encrypt method,
respectively.
Let promise be a new Promise object and resolver its associated resolver object.
Return promise and asynchronously perform the remaining steps.
If the following steps or referenced procedures say to
return an error,
execute resolver's reject(value)
algorithm, with
the returned error as the value
argument and then
terminate the algorithm.
Perform type mapping as specified in [WEBIDL] for key and data.
Let normalizedAlgorithm be the result of normalizing algorithm to Algorithm.
If the name member of
normalizedAlgorithm does not identify a
registered algorithm that supports the
encrypt operation, then return an error named
NotSupportedError
.
If the usages attribute of key does not
contain an entry that is "encrypt"
,
then return an error named
InvalidAccessError
.
Let ciphertext be the result of performing the encrypt operation specified by normalizedAlgorithm using algorithm and key and with data as plaintext.
Execute resolver's resolve(value)
algorithm, with
ciphertext as value.
The decrypt
method returns a new Promise object that will decrypt data using the specified
AlgorithmIdentifier
with
the supplied Key
. It must act
as follows:
Let algorithm, key and data be the
algorithm
, key
and data
parameters
passed to the decrypt method,
respectively.
Let promise be a new Promise object and resolver its associated resolver object.
Return promise and asynchronously perform the remaining steps.
If the following steps or referenced procedures say to
return an error,
execute resolver's reject(value)
algorithm, with
the returned error as the value
argument and then
terminate the algorithm.
Perform type mapping as specified in [WEBIDL] for key and data.
Let normalizedAlgorithm be the result of normalizing algorithm to Algorithm.
If the name member of
normalizedAlgorithm does not identify a
registered algorithm that supports the decrypt
operation, then return an error named
NotSupportedError
.
If the usages attribute of key does not
contain an entry that is "decrypt"
,
then return an error named
InvalidAccessError
.
Let plaintext be the result of performing the decrypt operation specified by normalizedAlgorithm using key and algorithm and with data as ciphertext.
Execute resolver's resolve(value)
algorithm, with
plaintext as value.
The sign
method
returns a new Promise object that will sign data using the specified
AlgorithmIdentifier
with
the supplied Key
. It must act as follows:
Let algorithm, key and data be the
algorithm
, key
and data
parameters
passed to the sign method,
respectively.
Let promise be a new Promise object and resolver its associated resolver object.
Return promise and asynchronously perform the remaining steps.
If the following steps or referenced procedures say to
return an error,
execute resolver's reject(value)
algorithm, with
the returned error as the value
argument and then
terminate the algorithm.
Perform type mapping as specified in [WEBIDL] for key and data.
Let normalizedAlgorithm be the result of normalizing algorithm to Algorithm.
If the name member of
normalizedAlgorithm does not identify a
registered algorithm that supports the sign
operation, then return an error named
NotSupportedError
.
If the usages attribute of key does not
contain an entry that is "sign"
,
then return an error named
InvalidAccessError
.
Let result be the result of performing the sign operation specified by normalizedAlgorithm uaing key and algorithm and with data as message.
Execute resolver's resolve(value)
algorithm, with
result as value.
The verify
method
returns a new Promise object that will verify data using the specified
AlgorithmIdentifier
with
the supplied Key
. It must act as follows:
Let algorithm, key, signature and data
be the algorithm
, key
, signature
and
data
parameters passed to the
verify method, respectively.
Let promise be a new Promise object and resolver its associated resolver object.
Return promise and asynchronously perform the remaining steps.
If the following steps or referenced procedures say to
return an error,
execute resolver's reject(value)
algorithm, with
the returned error as the value
argument and then
terminate the algorithm.
Perform type mapping as specified in [WEBIDL] for key, data and signature.
Let normalizedAlgorithm be the result of normalizing algorithm to Algorithm.
If the name member of
normalizedAlgorithm does not identify a
registered algorithm that supports the verify
operation, then return an error named
NotSupportedError
.
If the usages attribute of key does not
contain an entry that is "verify"
,
then return an error named
InvalidAccessError
.
Let result be the result of performing the verify operation specified by normalizedAlgorithm using key, algorithm and signature and with data as message.
Execute resolver's resolve(value)
algorithm, with
result as value.
The digest
method returns
a new Promise object that will digest data using the specified
AlgorithmIdentifier
.
It must act as follows:
Let algorithm and data
be the algorithm
and data
parameters passed to the
digest method, respectively.
Let promise be a new Promise object and resolver its associated resolver object.
Return promise and asynchronously perform the remaining steps.
If the following steps or referenced procedures say to
return an error,
execute resolver's reject(value)
algorithm, with
the returned error as the value
argument and then
terminate the algorithm.
Perform type mapping as specified in [WEBIDL] for data.
Let normalizedAlgorithm be the result of normalizing algorithm to Algorithm.
If the name member of
normalizedAlgorithm does not identify a
registered algorithm that supports the digest
operation, then return an error named
NotSupportedError
.
Let result be the result of performing the digest operation specified by normalizedAlgorithm using algorithm, with data as message.
Execute resolver's resolve(value)
algorithm, with
result as value.
When invoked,
generateKey
MUST perform the
following steps:
Let algorithm, extractable and usages
be the algorithm
, extractable
and keyUsages
parameters passed to the
generateKey method,
respectively.
Let promise be a new Promise object and resolver its associated resolver object.
Return promise and asynchronously perform the remaining steps.
If the following steps or referenced procedures say to
return an error,
execute resolver's reject(value)
algorithm, with
the returned error as the value
argument and then
terminate the algorithm.
Perform type mapping as specified in [WEBIDL] for extractable and usages.
Let normalizedAlgorithm be the result of normalizing algorithm to Algorithm.
If the name member of
normalizedAlgorithm does not identify a
registered algorithm that supports the generate
key operation, then return an error named
NotSupportedError
.
If usages includes a value that is not a
recognized key usage value,
then return an error named
InvalidAccessError
.
Let result be the result of executing the generate key operation specified by normalizedAlgorithm using algorithm, extractable and usages.
Execute resolver's resolve(value)
algorithm, with
result as the value
argument.
When invoked, deriveKey
MUST perform the following steps:
Let algorithm, baseKey, derivedKeyType,
extractable and usages be the algorithm
,
baseKey
, derivedKeyType
, extractable
and
keyUsages
parameters passed to the
deriveKey method,
respectively.
Let promise be a new Promise object and resolver its associated resolver object.
Return promise and asynchronously perform the remaining steps.
If the following steps or referenced procedures say to
return an error,
execute resolver's reject(value)
algorithm, with
the returned error as the value
argument and then
terminate the algorithm.
Perform type mapping as specified in [WEBIDL] for baseKey, extractable and usages.
Let normalizedAlgorithm be the result of normalizing algorithm to Algorithm.
If the name member of
normalizedAlgorithm does not identify a
registered algorithm that supports the derive bits
operation, then return an error named
NotSupportedError
.
Let normalizedDerivedKeyAlgorithm be the result of normalizing derivedKeyType to Algorithm.
If the name member of
normalizedDerivedKeyAlgorithm does not identify a
registered algorithm that supports the get key length
and import key operations, then return an error named
NotSupportedError
.
If the usages attribute of baseKey does not
contain an entry that is "deriveKey"
,
then return an error named
InvalidAccessError
.
If usages includes a value that is not a
recognized key usage value,
then return an error named
SyntaxError
.
Let length be the result of executing the get key length algorithm specified by normalizedDerivedKeyAlgorithm using derivedKeyType.
Let secret be the result of executing the derive bits operation specified by normalizedAlgorithm using key, algorithm and length.
Let result be the result of executing the import key operation
specified by normalizedDerivedKeyAlgorithm using "raw"
as
format, secret as keyData,
derivedKeyType as algorithm and using
extractable and usages.
Execute resolver's resolve(value)
algorithm, with
result as the value
argument.
When invoked, deriveBits
MUST perform the following steps:
Let algorithm, baseKey and length,
be the algorithm
,
baseKey
and length
parameters passed to the
deriveBits method,
respectively.
Let promise be a new Promise object and resolver its associated resolver object.
Return promise and asynchronously perform the remaining steps.
If the following steps or referenced procedures say to
return an error,
execute resolver's reject(value)
algorithm, with
the returned error as the value
argument and then
terminate the algorithm.
Perform type mapping as specified in [WEBIDL] for baseKey and length.
Let normalizedAlgorithm be the result of normalizing algorithm to Algorithm.
If the name member of
normalizedAlgorithm does not identify a
registered algorithm that supports the derive bits
operation, then return an error named
NotSupportedError
.
If the usages attribute of baseKey does not
contain an entry that is "deriveBits"
,
then return an error named
InvalidAccessError
.
Let result be a new ArrayBuffer containing the result of executing the derive bits operation specified by normalizedAlgorithm using baseKey, algorithm and length.
Execute resolver's resolve(value)
algorithm, with
result as the value
argument.
When invoked, the importKey method MUST perform the following steps:
Let format, keyData, algorithm,
extractable and usages,
be the format
, keyData
, algorithm
,
extractable
and keyUsages
parameters passed to the
importKey method,
respectively.
Let promise be a new Promise object and resolver its associated resolver object.
Return promise and asynchronously perform the remaining steps.
If the following steps or referenced procedures say to
return an error,
execute resolver's reject(value)
algorithm, with
the returned error as the value
argument and then
terminate the algorithm.
Perform type mapping as specified in [WEBIDL] for format, keyData, extractable and usages.
Let normalizedAlgorithm be the result of normalizing algorithm to Algorithm.
If the name member of
normalizedAlgorithm does not identify a
registered algorithm that supports the import key
operation, then return an error named
NotSupportedError
.
If format is not
a recognized key
format value, then return an error named
SyntaxError
.
If usages includes a value that is not a
recognized key usage value,
then return an error named
SyntaxError
.
Let result be the Key object that results from performing the import key operation specified by normalizedAlgorithm using keyData, algorithm, format, extractable and usages.
Execute resolver's resolve(value)
algorithm, with
result as the value
argument.
jwk
. As currently specified, it is a
JSON-encoded Javascript object, converted to a UTF-8 byte sequence, with the
raw bytes provided via CryptoOperationData
. A separate
proposal exists to handle this via IDL, permitting importing JavaScript
objects directly when importing with jwk
.
When invoked, the exportKey method MUST perform the following steps:
Let format and key be the format
and key
parameters passed to the
importKey method,
respectively.
Let promise be a new Promise object and resolver its associated resolver object.
Return promise and asynchronously perform the remaining steps.
If the following steps or referenced procedures say to
return an error,
execute resolver's reject(value)
algorithm, with
the returned error as the value
argument and then
terminate the algorithm.
Perform type mapping as specified in [WEBIDL] for format and key.
If format is not a
recognized key
format value, then return an error named
SyntaxError
.
If the name member of
normalizedAlgorithm does not identify a
registered algorithm that supports the export key
operation, then return an error named
NotSupportedError
.
If the extractable attribute of key
is false, then return an error named
InvalidAccessError
.
Let result be the result of performing the export key operation specified by the algorithm attribute of key using key and format.
Execute resolver's resolve(value)
algorithm, with
result as the value
argument.
jwk
. As currently specified, the result
is a JSON-encoded Javascript object, converted to a UTF-8 byte
sequence, with the raw bytes provided via an ArrayBuffer. A separate
proposal exists to return an actual Javascript object when exporting
with jwk
.
When invoked, the wrapKey method MUST perform the following steps:
Let format, key, wrappingKey and
algorithm be the format
, key
,
wrappingKey
and wrapAlgorithm
parameters passed to the
wrapKey method,
respectively.
Let promise be a new Promise object and resolver its associated resolver object.
Return promise and asynchronously perform the remaining steps.
If the following steps or referenced procedures say to
return an error,
execute resolver's reject(value)
algorithm, with
the returned error as the value
argument and then
terminate the algorithm.
Perform type mapping as specified in [WEBIDL] for format, key and wrappingKey.
Let normalizedAlgorithm be the result of normalizing algorithm to Algorithm.
If the name member of
normalizedAlgorithm does not identify a
registered algorithm that supports the encrypt or wrap
key operation, then return an error named
NotSupportedError
.
If format is not algorithm a
recognized key
format value, then return an error named
SyntaxError
.
If the usages attribute of wrappingKey
does not contain an entry that is
"wrapKey"
, then return an error named
InvalidAccessError
.
If the algorithm identified by the algorithm
attibute of key does not support the export key operation,
then return an error named
NotSupportedError
.
If the extractable attribute of key
is false, then return an error named
InvalidAccessError
.
Let bytes be the result of performing the export key operation specified the algorithm attribute of key using key and format.
This note is non-normative.
The key wrapping operations for some algorithms place constraints on the payload size. For example AES-KW requires the payload to be a multiple of 8 bytes in length and RSA-OAEP places a restriction on the length. For key formats that offer flexibility in serialization of a given key (for example JWK), implementations may choose to adapt the serialization to the constraints of the wrapping algorithm.
Let result be the result of performing the wrap key operation specified by normalizedAlgorithm using algorithm, wrappingKey as key and bytes as plaintext.
Let result be the result of performing the encrypt operation specified by normalizedAlgorithm using algorithm, wrappingKey as key and bytes as plaintext.
NotSupportedError
.
Execute resolver's resolve(value)
algorithm, with
result as the value
argument.
When invoked, the unwrapKey method MUST perform the following steps:
Let format, wrappedKey, unwrappingKey,
algorithm, unwrappedKeyAlgorithm,
extractable and usages,
be the format
, wrappedKey
, unwrappingKey
,
unwrapAlgorithm
, unwrappedKeyAlgorithm
,
extractable
and keyUsages
parameters passed to the
unwrapKey method,
respectively.
Let promise be a new Promise object and resolver its associated resolver object.
Return promise and asynchronously perform the remaining steps.
If the following steps or referenced procedures say to
return an error,
execute resolver's reject(value)
algorithm, with
the returned error as the value
argument and then
terminate the algorithm.
Perform type mapping as specified in [WEBIDL] for format, wrappedKey, unwrappingKey, extractable and usages.
Let normalizedAlgorithm be the result of normalizing algorithm to Algorithm.
If the name member of
normalizedAlgorithm does not identify a
registered algorithm that supports the unwrap key or
decrypt
operation, then return an error named
NotSupportedError
.
Let normalizedKeyAlgorithm be the result of normalizing unwrappedKeyAlgorithm to Algorithm.
If the name member of
normalizedKeyAlgorithm does not identify a
registered algorithm that supports the importKey
operation, then return an error named
NotSupportedError
.
If the usages attribute of unwrappingKey
does not contain an entry that is
"unwrapKey"
, then return an error named
InvalidAccessError
.
If format is not a
recognized key
format value, then return an error named
SyntaxError
.
If usages includes a value that is not a
recognized key usage value,
then return an error named
SyntaxError
.
NotSupportedError
.
Let result be the result of performing the import key operation specified by normalizedKeyAlgorithm using unwrappedKeyAlgorithm as algorithm, format, usages and extractable and with bytes as keyData.
Execute resolver's resolve(value)
algorithm, with
result as the value
argument.
The methods of the SubtleCrypto interface return errors by calling the reject handler of the returned promise with a DOMException. The following DOMException types from [DOM4] are used with messages as shown in the following table:
Type | Message (optional) |
---|---|
NotSupportedError |
The algorithm is not supported |
SyntaxError |
A required parameter was missing our out-of-range |
InvalidStateError |
The requested operation is not value for the current state of the provided key. |
InvalidAccessError |
The requested operation is not valid for the provided key |
The following new DOMException types are defined by this specification:
Type | Message (optional) |
---|---|
UnknownError |
The operation failed for an unknown transient reason (e.g. out of memory) |
DataError |
Data provided to an operation does not meet requirements |
OperationError |
The operation failed for an operation-specific reason |
When this specification says to return an error named error, where error is one of the above error names, the user agent must return a DOMException with name error and message as defined in the above two tables.
interface WorkerCrypto {
readonly attribute SubtleCrypto subtle;
};
WorkerCrypto implements RandomSource;
partial interface WorkerGlobalScope {
readonly attribute WorkerCrypto crypto;
};
The WorkerCrypto interface provides cryptographic functionality for background scripts, as specified by Web Workers [ Web Workers].
typedef Uint8Array BigInteger;
The BigInteger typedef is a Uint8Array
that
holds an arbitrary magnitude unsigned integer in big-endian order. Values read from
the API SHALL have minimal typed array length (that is, at most 7 leading zero bits,
except the value 0 which shall have length 8 bits). The API SHALL accept values with
any number of leading zero bits, including the empty array, which represents zero.
The KeyPair interface represents an asymmetric key pair that is comprised of both public and private keys.
Note: All algorithms listed should be considered as "features at risk", barring implementors adopting them. Their inclusion in the Last Call Working Draft reflects requests for their inclusion by members of the community, and are included as an exercise to ensure the robustness of the API defined in this specification.
As such, the list of algorithms, and the recommendations, may be significantly altered in future revisions.
Algorithm name | encrypt | decrypt | sign | verify | digest | generateKey | deriveKey | deriveBits | importKey | exportKey | wrapKey | unwrapKey |
---|---|---|---|---|---|---|---|---|---|---|---|---|
RSAES-PKCS1-v1_5 | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | |||||
RSASSA-PKCS1-v1_5 | ✔ | ✔ | ✔ | ✔ | ✔ | |||||||
RSA-PSS | ✔ | ✔ | ✔ | ✔ | ✔ | |||||||
RSA-OAEP | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | |||||
ECDSA | ✔ | ✔ | ✔ | ✔ | ✔ | |||||||
ECDH | ✔ | ✔ | ✔ | ✔ | ✔ | |||||||
AES-CTR | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | |||||
AES-CBC | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | |||||
AES-CMAC | ✔ | ✔ | ✔ | ✔ | ✔ | |||||||
AES-GCM | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | |||||
AES-CFB | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | |||||
AES-KW | ✔ | ✔ | ✔ | ✔ | ✔ | |||||||
HMAC | ✔ | ✔ | ✔ | ✔ | ✔ | |||||||
DH | ✔ | ✔ | ✔ | ✔ | ✔ | |||||||
SHA-1 | ✔ | |||||||||||
SHA-256 | ✔ | |||||||||||
SHA-384 | ✔ | |||||||||||
SHA-512 | ✔ | |||||||||||
CONCAT | ✔ | ✔ | ||||||||||
HKDF-CTR | ✔ | ✔ | ||||||||||
PBKDF2 | ✔ | ✔ |
This section is non-normative
As the API is meant to be extensible in order to keep up with future developments within cryptography and to provide flexibility, there are no strictly required algorithms. Thus users of this API should check to see what algorithms are currently recommended and supported by implementations.
However, in order to promote interoperability for developers, there are a number of recommended algorithms. The recommended algorithms are:
Results will be provided in the form of test-cases between implementations, by the time the this document reaches Candidate Recommendation.
Each algorithm that is to be exposed via the Web Cryptography API SHOULD be registered via the Web Cryptography working group, and MUST include all of the following details. Algorithms that are not registered via these means, but are exposed via this API, MUST be processed as if the sections had been defined.
Each registered algorithm MUST have a canonical name for which applications can refer to the algorithm. The canonical name MUST contain only ASCII characters and MUST NOT equal any other canonical name or algorithm alias when every character in both names are converted to lower case.
Each registered algorithm MUST define the operations that it supports.
Each registered algorithm MUST define the expected parameters, if any, that should be exposed via the Algorithm dictionary for every supported operation.
Each registered algorithm MUST define the contents of the result of performing the underlying cryptographic operation for every supported operation.
Each registered algorithm MAY define one or more aliases that may define a fully normalized Algorithm object.
Each algorithm alias MUST follow the same naming rules as the recognized algorithm name.
The "RSAES-PKCS1-v1_5"
algorithm identifier is used to perform encryption
and decryption ordering to the RSAES-PKCS1-v1_5 algorithm specified in
[RFC3447].
The recognized algorithm name for
this algorithm is "RSAES-PKCS1-v1_5"
.
Operation | Parameters | Result |
---|---|---|
encrypt | None | ArrayBuffer |
decrypt | None | ArrayBuffer |
generateKey | RsaKeyGenParams | KeyPair |
importKey | None | Key |
exportKey | None | ArrayBuffer |
dictionary RsaKeyGenParams : Algorithm {
// The length, in bits, of the RSA modulus
[EnforceRange] unsigned long modulusLength;
// The RSA public exponent
BigInteger publicExponent;
};
interface RsaKeyAlgorithm : KeyAlgorithm {
// The length, in bits, of the RSA modulus
readonly attribute unsigned long modulusLength;
// The RSA public exponent
readonly attribute BigInteger publicExponent;
};
If the type attribute of key
is not "public"
,
then return an error named
InvalidAccessError
.
Perform the encrytion operation defined in Section 7.2 of [RFC3447] with the key represented by key as the recipient's RSA public key and the contents of plaintext as M.
If performing the operation results in an error,
then return an error named
OperationError
.
Let ciphertext be a new ArrayBuffer containing the value C that results from performing the operation.
If the type attribute of key
is not "private"
,
then return an error named
InvalidAccessError
Perform the decryption operation defined in Section 7.2 of [RFC3447] with the key represented by key as the recipient's RSA private key and the contents of ciphertext as C.
If performing the operation results in an error,
then return an error named
OperationError
.
Let plaintext be a new ArrayBuffer containing the value M that results from performing the operation.
Let normalizedAlgorithm be the result of normalizing algorithm to RsaKeyGenParams.
If any of the members of RsaKeyGenParams are
not present in normalizedAlgorithm,
then return an error named
SyntaxError
.
If usages contains an entry which is not
"encrypt"
, "decrypt"
,
"wrapKey"
or "unwrapKey"
,
then return an error named
DataError
.
Generate an RSA key pair, as defined in [RFC3447], with RSA modulus length equal to the modulusLength member of normalizedAlgorithm and RSA public exponent equal to the publicExponent member of normalizedAlgorithm.
If generation of the key pair fails,
then return an error named
OperationError
.
Let algorithm be a new RsaKeyAlgorithm object.
Set the name attribute of
algorithm to "RSAES-PKCS1-v1_5"
.
Set the modulusLength attribute of algorithm to equal the modulusLength attribute of normalizedAlgorithm.
Set the publicExponent attribute of algorithm to equal the publicExponent attribute of normalizedAlgorithm.
Let publicKey be a new Key object representing the public key of the generated key pair.
Set the type attribute of publicKey
to "public"
Set the algorithm attribute of publicKey to be algorithm.
Set the extractable attribute of publicKey to true.
Set the usages attribute of
publicKey to be the
usage intersection of
usages and [ "encrypt", "wrapKey" ]
.
Let privateKey be a new Key object representing the private key of the generated key pair.
Set the type attribute of privateKey
to "private"
Set the algorithm attribute of privateKey to be algorithm.
Set the extractable attribute of privateKey to extractable.
Set the usages attribute of
privateKey to be the
usage intersection of
usages and [ "decrypt", "unwrapKey" ]
.
Let result be a new KeyPair object.
Set the publicKey attribute of result to be publicKey.
Set the privateKey attribute of result to be privateKey.
Return result.
Let keyData be the key data to be imported.
"spki"
:Let spki be the result of running the parse a subjectPublicKeyInfo algorithm over keyData.
If an error occurred while parsing,
then return an error named
DataError
.
If the algorithm
object identifier field of the
algorithm
AlgorithmIdentifier field of spki
is not equivalent to the rsaEncryption
OID defined in
Section 2.3.1 of RFC 3279,
then return an error named
DataError
.
Let publicKey be the result of performing the parse an ASN.1 structure
algorithm, with data as the
subjectPublicKeyInfo
field of spki,
structure as the RSAPublicKey
structure
specified in Section A.1.1 of RFC 3447, and
exactData set to true.
If an error occurred while parsing,
then return an error named
DataError
.
Let key be a new Key object that represents the RSA public key identified by publicKey.
Set the type attribute of key
to "public"
"pkcs8"
:Let privateKeyInfo be the result of running the parse a privateKeyInfo algorithm over keyData.
If an error occurred while parsing,
then return an error named
DataError
.
If the algorithm
object identifier field of the
privateKeyAlgorithm
PrivateKeyAlgorithmIdentifier field
of privateKeyInfo is not equivalent to the
rsaEncryption
OID defined in Section 2.3.1 of
RFC 3279,
then return an error named
DataError
.
Let rsaPrivateKey be the result of performing the parse an ASN.1 structure
algorithm, with data as the
privateKey
field of privateKeyInfo,
structure as the RSAPrivateKey
structure
specified in Section A.1.2 of RFC 3447, and
exactData set to true.
If an error occurred while parsing,
then return an error named
DataError
.
Let key be a new Key object that represents the RSA private key identified by rsaPrivateKey.
Set the type attribute of key
to "private"
"jwk"
:Let jwk be the result of running the parse a jwk algorithm over keyData.
If the "kty"
field of jwk is not
"RSA"
,
then return an error named
DataError
.
If the "use"
field of jwk is present, and is
not "enc"
,
then return an error named
DataError
.
If the "key_ops"
field of jwk is present, and
is invalid according to the requirements of
JSON Web Key or
does not contain all of the specified usages values,
then return an error named
DataError
.
If the "alg"
field of jwk is present, and is
not "RSA1_5"
,
then return an error named
DataError
.
"d"
field of jwk is present:
If jwk does not meet the requirements of
Section 6.3.2 of JSON Web
Algorithms,
then return an error named
DataError
.
Let key be a new Key object that represents the RSA private key identified by interpreting jwk according to Section 6.3.2 of JSON Web Algorithms.
Set the type attribute of
key to "private"
If jwk does not meet the requirements of
Section 6.3.1 of JSON Web
Algorithms,
then return an error named
DataError
.
Let key be a new Key object that represents the RSA public key identified by interpreting jwk according to Section 6.3.1 of JSON Web Algorithms.
Set the type attribute of
key to "public"
NotSupportedError
.
Let algorithm be a new RsaKeyAlgorithm.
Set the name attribute of
algorithm to "RSAES-PKCS1-v1_5"
Set the modulusLength attribute of algorithm to the length, in bits, of the RSA public modulus.
Set the publicExponent attribute of algorithm to the BigInteger representation of the RSA public exponent.
Set the algorithm attribute of key to algorithm
Return key.
Let key be the key to be exported.
"spki"
If the type attribute of key is
not "public"
,
then return an error named
InvalidAccessError
.
Let result be the result of encoding a subjectPublicKeyInfo with the following properties:
Set the algorithm field to an
AlgorithmIdentifier
ASN.1 type with the following
properties:
Set the algorithm field to the OID
1.2.840.113549.1.1
Set the params field to the ASN.1 type NULL.
Set the subjectPublicKey field to the result of
DER-encoding an RSAPublicKey
ASN.1 type, as defined
in RFC 3447, Appendix A.1.1, that
represents the RSA public key identified by key
"pkcs8"
:
If the type attribute of key is
not "private"
,
then return an error named
InvalidAccessError
.
Let result be the result of encoding a privateKeyInfo with the following properties:
Set the version field to 0.
Set the privateKeyAlgorithm field to a
PrivateKeyAlgorithmIdentifier
ASN.1 type with the
following properties:
Set the algorithm field to the OID
1.2.840.113549.1.1
Set the params field to the ASN.1 type NULL.
Set the privateKey field to the result of
DER-encoding an RSAPrivateKey
ASN.1 type, as defined
in RFC 3447, Appendix A.1.2, that
represents the RSA private key identified by key
"jwk"
:Let jwk be a new internal object.
Set the kty
property of jwk to the string
"RSA"
.
Set the alg
property of jwk to the string
"RSA1_5"
.
Set the properties n
and e
of jwk
according to the corresponding definitions in JSON Web
Algorithms, Section 6.3.1.
"private"
:
Set the properties named d
, p
,
q
, dp
, dq
, and
qi
of jwk according to the
corresponding definitions in JSON Web
Algorithms, Section 6.3.2.
If the underlying RSA private key represented by
key is represented by more than two primes, set the
member named oth
of jwk according to
the corresponding definition in JSON Web
Algorithms, Section 6.3.2.7
Set the key_ops
property of jwk to the usages attribute of key.
Set the ext
property of jwk to the extractable attribute of
key.
Let stringifiedJwk be the result of encoding jwk according to the grammar specified in Section 15.12 of ECMA262.
Let result be the UTF-8 encoding of stringifiedJwk.
Return an error named
NotSupportedError
.
Let data be a new ArrayBuffer
containing
result.
Return data.
The "RSASSA-PKCS1-v1_5"
algorithm identifier is used to perform
signing and verification using the RSASSA-PKCS1-v1_5 algorithm specified in
[RFC3447].
The recognized algorithm name for
this algorithm is "RSASSA-PKCS1-v1_5"
.
Operation | Parameters | Result |
---|---|---|
sign | None | ArrayBuffer |
verify | None | boolean |
generateKey | RsaHashedKeyGenParams | KeyPair |
importKey | RsaHashedImportParams | Key |
exportKey | None | ArrayBuffer |
dictionary RsaHashedKeyGenParams : RsaKeyGenParams {
// The hash algorithm to use
AlgorithmIdentifier hash;
};
[NoInterfaceObject]
interface RsaHashedKeyAlgorithm : RsaKeyAlgorithm {
// The hash algorithm that is used with this key
readonly attribute KeyAlgorithm hash;
};
dictionary RsaHashedImportParams {
// The hash algorithm to use
AlgorithmIdentifier hash;
};
Should this be folded into RsaHashedKeyGenParams and rely on the optional nature of the dictionary fields?
If the type attribute of key
is not "private"
,
then return an error named
InvalidAccessError
.
Perform the signature generation operation defined in Section 8.2 of [RFC3447] with the key represented by key as the signer's private key and the contents of message as M and using the hash function specified in the hash attribute of the algorithm attribute of key as the Hash option for the EMSA-PKCS1-v1_5 encoding method.
If performing the operation results in an error,
then return an error named
OperationError
.
Let signature be the value S that results from performing the operation.
If the type attribute of key
is not "public"
,
then return an error named
InvalidAccessError
.
Perform the signature verification operation defined in Section 8.2 of [RFC3447] with the key represented by key as the signer's RSA public key and the contents of message as M and signature as S and using the hash function specified in the hash attribute of the algorithm attribute of key as the Hash option for the EMSA-PKCS1-v1_5 encoding method.
If performing the operation results in an error,
then return an error named
OperationError
.
Let result be a boolean with value true if the result of the operations was "valid signature" and a boolean with value false otherwise.
Let normalizedAlgorithm be the result of normalizing algorithm to RsaHashedKeyGenParams.
If any of the members of
RsaHashedKeyGenParams are not present
in normalizedAlgorithm,
then return an error named
SyntaxError
.
If usages contains an entry which is not
"sign"
or "verify"
,
then return an error named
DataError
.
Generate an RSA key pair, as defined in [RFC3447], with RSA modulus length equal to the modulusLength attribute of normalizedAlgorithm and RSA public exponent equal to the publicExponent attribute of normalizedAlgorithm.
If generation of the key pair fails,
then return an error named
OperationError
.
Let algorithm be a new RsaHashedKeyAlgorithm object.
Set the name attribute of
algorithm to "RSASSA-PKCS1-v1_5"
.
Set the modulusLength attribute of algorithm to equal the modulusLength attribute of normalizedAlgorithm.
Set the publicExponent attribute of algorithm to equal the publicExponent attribute of normalizedAlgorithm.
Set the hash attribute of algorithm to equal the hash member of normalizedAlgorithm.
Let publicKey be a new Key object representing the public key of the generated key pair.
Set the type attribute of publicKey
to "public"
Set the algorithm attribute of publicKey to be algorithm.
Set the extractable attribute of publicKey to true.
Set the usages attribute of
publicKey to be the
usage intersection of
usages and [ "verify" ]
.
Let privateKey be a new Key object representing the private key of the generated key pair.
Set the type attribute of privateKey
to "private"
Set the algorithm attribute of privateKey to be algorithm.
Set the extractable attribute of privateKey to extractable.
Set the usages attribute of
privateKey to be the
usage intersection of
usages and [ "sign" ]
.
Let result be a new KeyPair object.
Set the publicKey attribute of result to be publicKey.
Set the privateKey attribute of result to be privateKey.
Return result.
TODO: Specify the mapping between key.algorithm.hash and the appropriate Hash functions (and back to OID).
Let keyData be the key data to be imported.
Let normalizedAlgorithm be the result of normalizing algorithm to RsaHashedImportParams.
If any of the members of RsaHashedImportParams are not present in
normalizedAlgorithm then return
an error named SyntaxError
.
"spki"
:Let spki be the result of running the parse a subjectPublicKeyInfo algorithm over keyData.
If an error occurred while parsing,
then return an error named
DataError
.
Let hash be a string whose initial value is undefined.
Let alg be the algorithm
object identifier
field of the algorithm
AlgorithmIdentifier field of
spki.
rsaEncryption
OID defined in Section 2.3.1 of RFC 3279:
Let hash be undefined.
sha1WithRSAEncryption
OID defined in Section A.2.4 of
RFC 3279:
Let hash be the string SHA-1
.
sha256WithRSAEncryption
OID defined in Section A.2.4 of
RFC 3279:
Let hash be the string SHA-256
.
sha384WithRSAEncryption
OID defined in Section A.2.4 of
RFC 3279:
Let hash be the string SHA-384
.
sha512WithRSAEncryption
OID defined in Section A.2.4 of
RFC 3279:
Let hash be the string SHA-512
.
Return an error named
DataError
.
If hash is defined, and is not equal to the name member of the hash member of
normalizedAlgorithm, return an error named DataError
.
Set hash to the name member of the hash member of normalizedAlgorithm.
Let publicKey be the result of performing the parse an ASN.1 structure
algorithm, with data as the
subjectPublicKeyInfo
field of spki,
structure as the RSAPublicKey
structure
specified in Section A.1.1 of RFC 3447, and
exactData set to true.
If an error occurred while parsing,
then return an error named
DataError
.
Let key be a new Key object that represents the RSA public key identified by publicKey.
Set the type attribute of key
to "public"
"pkcs8"
:Let privateKeyInfo be the result of running the parse a privateKeyInfo algorithm over keyData.
If an error occurred while parsing,
then return an error named
DataError
.
Let hash be a string whose initial value is undefined.
Let alg be the algorithm
object identifier
field of the privateKeyAlgorithm
PrivateKeyAlgorithmIdentifier field of privateKeyInfo.
rsaEncryption
OID defined in Section 2.3.1 of RFC 3279:
Let hash be undefined.
sha1WithRSAEncryption
OID defined in Section A.2.4 of
RFC 3279:
Let hash be the string SHA-1
.
sha256WithRSAEncryption
OID defined in Section A.2.4 of
RFC 3279:
Let hash be the string SHA-256
.
sha384WithRSAEncryption
OID defined in Section A.2.4 of
RFC 3279:
Let hash be the string SHA-384
.
sha512WithRSAEncryption
OID defined in Section A.2.4 of
RFC 3279:
Let hash be the string SHA-512
.
Return an error named
DataError
.
If hash is defined, and is not equal to the name member of the hash member of
normalizedAlgorithm, return an error named DataError
.
Set hash to the name member of the hash member of normalizedAlgorithm.
Let rsaPrivateKey be the result of performing the parse an ASN.1 structure
algorithm, with data as the
privateKey
field of privateKeyInfo,
structure as the RSAPrivateKey
structure
specified in Section A.1.2 of RFC 3447, and
exactData set to true.
If an error occurred while parsing,
then return an error named
DataError
.
Let key be a new Key object that represents the RSA private key identified by rsaPrivateKey.
Set the type attribute of key
to "private"
"jwk"
:Let jwk be the result of running the parse a jwk algorithm over keyData.
If the "kty"
field of jwk is not a
case-sensitive string match to "RSA"
,
then return an error named
DataError
.
If the "use"
field of jwk is present, and is
not a case-sensitive string match to "enc"
,
then return an error named
DataError
.
If the "key_ops"
field of jwk is present, and
is invalid according to the requirements of
JSON Web Key or
does not contain all of the specified usages values,
then return an error named
DataError
.
Let hash be a be a string whose initial value is undefined.
"alg"
field of jwk is not
present:
Let hash be undefined.
"alg"
field is equal to the string
"RS1"
:
Let hash be the string SHA-1
.
"alg"
field is equal to the string
"RS256"
:
Let hash be the string SHA-256
.
"alg"
field is equal to the string
"RS384"
:
Let hash be the string SHA-384
.
"alg"
field is equal to the string
"RS512"
:
Let hash be the string SHA-512
.
Return an error named
DataError
.
"d"
field of jwk is present:
If jwk does not meet the requirements of
Section 6.3.2 of JSON Web
Algorithms,
then return an error named
DataError
.
Let key be a new Key object that represents the RSA private key identified by interpreting jwk according to Section 6.3.2 of JSON Web Algorithms.
Set the type attribute of
key to "private"
If jwk does not meet the requirements of Section
6.3.1 of JSON Web Algorithms, then return an error named DataError
.
Let key be a new Key object that represents the RSA public key identified by interpreting jwk according to Section 6.3.1 of JSON Web Algorithms.
Set the type attribute of
key to "public"
NotSupportedError
.
Let algorithm be a new RsaHashedKeyAlgorithm.
Set the name attribute of
algorithm to "RSASSA-PKCS1-v1_5"
Set the modulusLength attribute of algorithm to the length, in bits, of the RSA public modulus.
Set the publicExponent attribute of algorithm to the BigInteger representation of the RSA public exponent.
Set the hash attribute of algorithm to a new KeyAlgorithm whose name attribute is hash.
Set the algorithm attribute of key to algorithm
Return key.
Let key be the key to be exported.
"spki"
If the type attribute of key is
not "public"
,
then return an error named
InvalidAccessError
.
Let result be the result of encoding a subjectPublicKeyInfo with the following properties:
Set the algorithm field to an
AlgorithmIdentifier
ASN.1 type with the following
properties:
Set the algorithm field to the OID
1.2.840.113549.1.1
Set the params field to the ASN.1 type NULL.
Set the subjectPublicKey field to the result of
DER-encoding an RSAPublicKey
ASN.1 type, as defined
in RFC 3447, Appendix A.1.1, that
represents the RSA public key identified by key
"pkcs8"
:
If the type attribute of key is
not "private"
,
then return an error named
InvalidAccessError
.
Let result be the result of encoding a privateKeyInfo with the following properties:
Set the version field to 0.
Set the privateKeyAlgorithm field to a
PrivateKeyAlgorithmIdentifier
ASN.1 type with the
following properties:
Set the algorithm field to the OID
1.2.840.113549.1.1
Set the params field to the ASN.1 type NULL.
Set the privateKey field to the result of
DER-encoding an RSAPrivateKey
ASN.1 type, as defined
in RFC 3447, Appendix A.1.2, that
represents the RSA private key identified by key
"jwk"
:Let jwk be a new internal object.
Set the kty
field of jwk to the string
"RSA"
.
Let hash be the name attribute of the hash attribute of key.
SHA-1
:
Set the alg
field of jwk to the string
RS1
.
SHA-256
:
Set the alg
field of jwk to the string
RS256
.
SHA-384
:
Set the alg
field of jwk to the string
RS384
.
SHA-512
:
Set the alg
field of jwk to the string
RS512
.
Return an error named
NotSupportedError
.
Set the alg
field of jwk to the string
"RSA1_5"
.
Set the fields n
and e
of jwk
according to the corresponding definitions in JSON Web
Algorithms, Section 6.3.1.
"private"
:
Set the fields named d
, p
,
q
, dp
, dq
, and
qi
of jwk according to the
corresponding definitions in JSON Web
Algorithms, Section 6.3.2.
If the underlying RSA private key represented by
key is represented by more than two primes, set the
field named oth
of jwk according to
the corresponding definition in JSON Web
Algorithms, Section 6.3.2.7
Set the key_ops
field of jwk to the usages attribute of key.
Set the ext
field of jwk to the extractable attribute of
key.
Let stringifiedJwk be the result of encoding jwk according to the grammar specified in Section 15.12 of ECMA262.
Let result be the UTF-8 encoding of stringifiedJwk.
Return an error named
NotSupportedError
.
Let data be a new ArrayBuffer
containing
result.
Return data.
The "RSA-PSS"
algorithm identifier is used to perform signing
and verification using the RSASSA-PSS algorithm specified in
[RFC3447], using the mask generation
formula MGF1.
The recognized algorithm name for
this algorithm is "RSA-PSS"
.
Operation | Parameters | Result |
---|---|---|
sign | RsaPssParams | ArrayBuffer |
verify | RsaPssParams | boolean |
generateKey | RsaHashedKeyGenParams | KeyPair |
importKey | RsaHashedImportParams | Key |
exportKey | None | ArrayBuffer |
dictionary RsaPssParams : Algorithm {
// The desired length of the random salt
[EnforceRange] unsigned long saltLength;
};
If the type attribute of key
is not "private"
,
then return an error named
InvalidAccessError
.
Let normalizedAlgorithm be the result of normalizing algorithm to RsaPssParams.
If any of the members of RsaPssParams are not
present in normalizedAlgorithm,
then return an error named
SyntaxError
.
Perform the signature generation operation defined in Section 8.1 of [RFC3447] with the key represented by key as the signer's private key, K, and the contents of message as the message to be signed, M, and using the hash function specified by the hash attribute of the algorithm attribute of key as the Hash option, MGF1 (defined in Section B.2.1 of [RFC3447]) as the MGF option and the saltLength member of normalizedAlgorithm as the salt length option for the EMM-PSS-ENCODE operation.
If performing the operation results in an error,
then return an error named
OperationError
.
Let signature be a new ArrayBuffer
containing the
signature, S, that results from performing the operation.
If the type attribute of key
is not "public"
,
then return an error named
InvalidAccessError
.
Let normalizedAlgorithm be the result of normalizing algorithm to RsaPssParams.
If any of the members of RsaPssParams are not
present in normalizedAlgorithm,
then return an error named
SyntaxError
.
Perform the signature verification operation defined in Section 8.1 of [RFC3447] with the key represented by key as the signer's RSA public key and the contents of message as M and the contents of signature as S and using the hash function specified by the hash attribute of the algorithm attribute 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.
If performing the operation results in an error,
then return an error named
OperationError
.
Let result be a boolean with value true if the result of the operation was "valid signature" and a boolean with value false otherwise.
Let normalizedAlgorithm be the result of normalizing algorithm to RsaHashedKeyGenParams.
If any of the members of
RsaHashedKeyGenParams are not present
in normalizedAlgorithm,
then return an error named
SyntaxError
.
If usages contains an entry which is not
"sign"
or "verify"
,
then return an error named
SyntaxError
.
Generate an RSA key pair, as defined in [RFC3447], with RSA modulus length equal to the modulusLength member of normalizedAlgorithm and RSA public exponent equal to the publicExponent member of normalizedAlgorithm.
If performing the operation results in an error,
then return an error named
OperationError
.
Let algorithm be a new RsaHashedKeyAlgorithm object.
Set the name attribute of
algorithm to "RSA-PSS"
.
Set the modulusLength attribute of algorithm to equal the modulusLength member of normalizedAlgorithm.
Set the publicExponent attribute of algorithm to equal the publicExponent member of normalizedAlgorithm.
Set the hash attribute of algorithm to equal the hash member of normalizedAlgorithm.
Let publicKey be a new Key object representing the public key of the generated key pair.
Set the type attribute of publicKey
to "public"
Set the algorithm attribute of publicKey to be algorithm.
Set the extractable attribute of publicKey to true.
Set the usages attribute of
publicKey to be the
usage intersection of
usages and [ "verify" ]
.
Let privateKey be a new Key object representing the private key of the generated key pair.
Set the type attribute of privateKey
to "private"
Set the algorithm attribute of privateKey to be algorithm.
Set the extractable attribute of privateKey to extractable.
Set the usages attribute of
privateKey to be the
usage intersection of
usages and [ "sign" ]
.
Let result be a new KeyPair object.
Set the publicKey attribute of result to be publicKey.
Set the privateKey attribute of result to be privateKey.
Return result.
Let keyData be the key data to be imported.
Let normalizedAlgorithm be the result of normalizing algorithm to RsaHashedImportParams.
If any of the members of RsaHashedImportParams are not present in
normalizedAlgorithm then return
an error named SyntaxError
.
"spki"
:Let spki be the result of running the parse a subjectPublicKeyInfo algorithm over keyData.
If an error occurred while parsing,
then return an error named
DataError
.
Let hash be a string whose initial value is undefined.
Let alg be the algorithm
object identifier
field of the algorithm
AlgorithmIdentifier field of
spki.
rsaEncryption
OID defined in RFC 3447:
Let hash be undefined.
id-RSASSA-PSS
OID defined in
RFC 3447:
Let params be the ASN.1 structure contained within
the parameters
field of the algorithm
AlgorithmIdentifier field of spki.
If params is not defined, or is not an instance of
the RSASSA-PSS-params
ASN.1 type defined in
RFC3447,
return an error named
DataError
.
Let hashAlg be the AlgorithmIdentifier ASN.1 type
within the hashAlgorithm
field of params.
algorithm
object identifier field of
hashAlg is equivalent to the id-sha1
OID defined in RFC 3447:
Set hash to the string SHA-1
.
algorithm
object identifier field of
hashAlg is equivalent to the id-sha256
OID defined in RFC 3447:
Set hash to the string SHA-256
.
algorithm
object identifier field of
hashAlg is equivalent to the id-sha384
OID defined in RFC 3447:
Set hash to the string SHA-384
.
algorithm
object identifier field of
hashAlg is equivalent to the id-sha512
OID defined in RFC 3447:
Set hash to the string SHA-512
.
Return an error named
NotSupportedError
.
If the algorithm
object identifier field of the
maskGenAlgorithm
field of params is not
equivalent to the OID id-mgf1
defined in RFC 3447, return an error named NotSupportedError
.
If the parameters
field of the
maskGenAlgorithm
field of params is not
an instance of the HashAlgorithm
ASN.1 type that is
identical in content to the hashAlglorithm
field of
params, return an
error named NotSupportedError
.
Return an error named
DataError
.
If hash is defined, and is not equal to the name member of the hash member of
normalizedAlgorithm, return an error named DataError
.
Set hash to the name member of the hash member of normalizedAlgorithm.
Let publicKey be the result of performing the parse an ASN.1 structure
algorithm, with data as the
subjectPublicKeyInfo
field of spki,
structure as the RSAPublicKey
structure
specified in Section A.1.1 of RFC 3447, and
exactData set to true.
If an error occurred while parsing,
then return an error named
DataError
.
Let key be a new Key object that represents the RSA public key identified by publicKey.
Set the type attribute of key
to "public"
"pkcs8"
:Let privateKeyInfo be the result of running the parse a privateKeyInfo algorithm over keyData.
If an error occurred while parsing, then return an error named DataError
.
Let hash be a string whose initial value is undefined.
Let alg be the algorithm
object identifier
field of the privateKeyAlgorithm
PrivateKeyAlgorithmIdentifier field of privateKeyInfo.
rsaEncryption
OID defined in RFC 3447:
Let hash be undefined.
id-RSASSA-PSS
OID
defined in RFC 3447:
Let params be the ASN.1 structure contained within
the parameters
field of the
privateKeyAlgorithm
PrivateKeyAlgorithmIdentifier
field of privateKeyInfo.
If params is not defined, or is not an instance of
the RSASSA-PSS-params
ASN.1 type defined in
RFC3447,
return an error named
NotSupportedError
.
Let hashAlg be the AlgorithmIdentifier ASN.1 type
within the hashAlgorithm
field of params.
algorithm
object identifier field of
hashAlg is equivalent to the id-sha1
OID defined in RFC 3447:
Set hash to the string SHA-1
.
algorithm
object identifier field of
hashAlg is equivalent to the id-sha256
OID defined in RFC 3447:
Set hash to the string SHA-256
.
algorithm
object identifier field of
hashAlg is equivalent to the id-sha384
OID defined in RFC 3447:
Set hash to the string SHA-384
.
algorithm
object identifier field of
hashAlg is equivalent to the id-sha512
OID defined in RFC 3447:
Set hash to the string SHA-512
.
Return an error named
NotSupportedError
.
If the algorithm
object identifier field of the
maskGenAlgorithm
field of params is not
equivalent to the OID id-mgf1
defined in RFC 3447, return an error named NotSupportedError
.
If the parameters
field of the
maskGenAlgorithm
field of params is not
an instance of the HashAlgorithm
ASN.1 type that is
identical in content to the hashAlglorithm
field of
params, return an
error named NotSupportedError
.
Return an error named
DataError
.
If hash is defined, and is not equal to the name member of the hash member of
normalizedAlgorithm, return an error named DataError
.
Set hash to the name member of the hash member of normalizedAlgorithm.
Let rsaPrivateKey be the result of performing the parse an ASN.1 structure
algorithm, with data as the
privateKey
field of privateKeyInfo,
structure as the RSAPrivateKey
structure
specified in Section A.1.2 of RFC 3447, and
exactData set to true.
If an error occurred while parsing,
then return an error named
DataError
.
Let key be a new Key object that represents the RSA private key identified by rsaPrivateKey.
Set the type attribute of key
to "private"
"jwk"
:Let jwk be the result of running the parse a jwk algorithm over keyData.
If the "kty"
field of jwk is not a
case-sensitive string match to "RSA"
,
then return an error named
DataError
.
If the "use"
field of jwk is present, and is
not a case-sensitive string match to "enc"
,
then return an error named
DataError
.
If the "key_ops"
field of jwk is present, and
is invalid according to the requirements of
JSON Web Key or
does not contain all of the specified usages values,
then return an error named
DataError
.
Let hash be a be a string whose initial value is undefined.
"alg"
field of jwk is not
present:
Let hash be undefined.
"alg"
field is equal to the string
"PS1"
:
Let hash be the string SHA-1
.
"alg"
field is equal to the string
"PS256"
:
Let hash be the string SHA-256
.
"alg"
field is equal to the string
"PS384"
:
Let hash be the string SHA-384
.
"alg"
field is equal to the string
"PS512"
:
Let hash be the string SHA-512
.
Return an error named
DataError
.
"d"
field of jwk is present:
If jwk does not meet the requirements of
Section 6.3.2 of JSON Web
Algorithms,
then return an error named
DataError
.
Let key be a new Key object that represents the RSA private key identified by interpreting jwk according to Section 6.3.2 of JSON Web Algorithms.
Set the type attribute of
key to "private"
If jwk does not meet the requirements of Section
6.3.1 of JSON Web Algorithms, then return an error named DataError
.
Let key be a new Key object that represents the RSA public key identified by interpreting jwk according to Section 6.3.1 of JSON Web Algorithms.
Set the type attribute of
key to "public"
NotSupportedError
.
Let algorithm be a new RsaHashedKeyAlgorithm.
Set the name attribute of
algorithm to "RSA-PSS"
Set the modulusLength attribute of algorithm to the length, in bits, of the RSA public modulus.
Set the publicExponent attribute of algorithm to the BigInteger representation of the RSA public exponent.
Set the hash attribute of algorithm to a new KeyAlgorithm whose name attribute is hash.
Set the algorithm attribute of key to algorithm
Return key.
Let key be the key to be exported.
"spki"
If the type attribute of key is
not "public"
,
then return an error named
InvalidAccessError
.
Let result be the result of encoding a subjectPublicKeyInfo with the following properties:
Set the algorithm field to an
AlgorithmIdentifier
ASN.1 type with the following
properties:
Set the algorithm field to the OID
id-RSASSA-PSS
defined in
RFC 3447.
Set the params field to an instance of the
RSASSA-PSS-params
ASN.1 type with the following
properties:
Set the hashAlgorithm field to an instance of
the HashAlgorithm
ASN.1 type with the
following properties:
SHA-1
:
Set the algorithm object identifier to the
OID id-sha1
defined in RFC 3447.
SHA-256
:
Set the algorithm object identifier to the
OID id-sha256
defined in RFC 3447.
SHA-384
:
Set the algorithm object identifier to the
OID id-sha384
defined in RFC 3447.
SHA-512
:
Set the algorithm object identifier to the
OID id-sha512
defined in RFC 3447.
Set the maskGenAlgorithm field to an instance
of the MaskGenAlgorithm
ASN.1 type with the
following properties:
Set the algorithm field to the OID
id-mgf1
defined in RFC
3447.
Set the params field to an instance of the
HashAlgorithm
ASN.1 type that is
identical to the hashAlgorithm field.
Set the saltLength field to the length in octets of the digest algorithm identified by the name attribute of the hash attribute of the algorithm attribute of key.
Set the subjectPublicKey field to the result of
DER-encoding an RSAPublicKey
ASN.1 type, as defined
in RFC 3447, Appendix A.1.1, that
represents the RSA public key identified by key
"pkcs8"
:
If the type attribute of key is
not "private"
,
then return an error named
InvalidAccessError
.
Let result be the result of encoding a privateKeyInfo with the following properties:
Set the version field to 0.
Set the privateKeyAlgorithm field to an
PrivateKeyAlgorithmIdentifier
ASN.1 type with the
following properties:
Set the algorithm field to the OID
id-RSASSA-PSS
defined in
RFC 3447.
Set the params field to an instance of the
RSASSA-PSS-params
ASN.1 type with the following
properties:
Set the hashAlgorithm field to an instance of
the HashAlgorithm
ASN.1 type with the
following properties:
SHA-1
:
Set the algorithm object identifier to the
OID id-sha1
defined in RFC 3447.
SHA-256
:
Set the algorithm object identifier to the
OID id-sha256
defined in RFC 3447.
SHA-384
:
Set the algorithm object identifier to the
OID id-sha384
defined in RFC 3447.
SHA-512
:
Set the algorithm object identifier to the
OID id-sha512
defined in RFC 3447.
Set the maskGenAlgorithm field to an instance
of the MaskGenAlgorithm
ASN.1 type with the
following properties:
Set the algorithm field to the OID
id-mgf1
defined in RFC
3447.
Set the params field to an instance of the
HashAlgorithm
ASN.1 type that is
identical to the hashAlgorithm field.
Set the saltLength field to the length in octets of the digest algorithm identified by the name attribute of the hash attribute of the algorithm attribute of key.
Set the privateKey field to the result of
DER-encoding an RSAPrivateKey
ASN.1 type, as defined
in RFC 3447, Appendix A.1.2, that
represents the RSA private key identified by key
"jwk"
:Let jwk be a new internal object.
Set the kty
field of jwk to the string
"RSA"
.
Let hash be the name attribute of the hash attribute of the algorithm attribute of key.
SHA-1
:
Set the alg
field of jwk to the string
PS1
.
SHA-256
:
Set the alg
field of jwk to the string
PS256
.
SHA-384
:
Set the alg
field of jwk to the string
PS384
.
SHA-512
:
Set the alg
field of jwk to the string
PS512
.
Return an error named
NotSupportedError
.
Set the fields n
and e
of jwk
according to the corresponding definitions in JSON Web
Algorithms, Section 6.3.1.
"private"
:
Set the fields named d
, p
,
q
, dp
, dq
, and
qi
of jwk according to the
corresponding definitions in JSON Web
Algorithms, Section 6.3.2.
If the underlying RSA private key represented by
key is represented by more than two primes, set the
field named oth
of jwk according to
the corresponding definition in JSON Web
Algorithms, Section 6.3.2.7
Set the key_ops
field of jwk to the usages attribute of key.
Set the ext
field of jwk to the extractable attribute of
key.
Let stringifiedJwk be the result of encoding jwk according to the grammar specified in Section 15.12 of ECMA262.
Let result be the UTF-8 encoding of stringifiedJwk.
Return an error named
NotSupportedError
.
Let data be a new ArrayBuffer
containing
result.
Return data.
The "RSA-OAEP"
algorithm identifier is used to perform encryption
and decryption ordering to the RSAES-OAEP algorithm specified in
[RFC3447], using the mask
generation function MGF1.
The recognized algorithm name for
this algorithm is "RSA-OAEP"
.
Operation | Parameters | Result |
---|---|---|
encrypt | RsaOaepParams | ArrayBuffer |
decrypt | RsaOaepParams | ArrayBuffer |
generateKey | RsaHashedKeyGenParams | KeyPair |
importKey | RsaHashedImportParams | Key |
exportKey | None | ArrayBuffer |
dictionary RsaOaepParams : Algorithm {
// The optional label/application data to associate with the message
CryptoOperationData? label;
};
If the type attribute of key
is not "public"
,
then return an error named
InvalidAccessError
.
Let normalizedAlgorithm be the result of normalizing algorithm to RsaOaepParams.
If any of the members of RsaOaepParams are
not present in normalizedAlgorithm,
then return an error named
SyntaxError
.
Perform the encrytion operation defined in Section 7.1 of [RFC3447] with the key represented by key as the recipient's RSA public key, the contents of plaintext as the message to be encrypted, M and the label member of normalizedAlgorithm as the label, L, and with the hash function specified by the hash attribute of the algorithm attribute 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 return an error named
OperationError
.
Let ciphertext be a new ArrayBuffer
containing the value C that results from performing the
operation.
If the type attribute of key
is not "private"
,
then return an error named
InvalidAccessError
.
Let normalizedAlgorithm be the result of normalizing algorithm to RsaOaepParams.
If any of the members of RsaOaepParams are
not present in normalizedAlgorithm,
then return an error named
SyntaxError
.
Perform the decryption operation defined in Section 7.1 of [RFC3447] with the key represented by key as the recipient's RSA private key, the contents of ciphertext as the cipertext to be decrypted, C, and the label member of normalizedAlgorithm as the label, L, and with the hash function specified by the hash attribute of the algorithm attribute 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 return an error named
OperationError
.
Let plaintext be a new ArrayBuffer
containing the value M that results from performing the
operation.
Let normalizedAlgorithm be the result of normalizing algorithm to RsaHashedKeyGenParams.
If any of the members of
RsaHashedKeyGenParams are not present
in normalizedAlgorithm,
then return an error named
SyntaxError
.
If usages contains an entry which is not
"encrypt"
, "decrypt
,
wrapKey
or unwrapKey
,
then return an error named
InvalidAccessError
.
Generate an RSA key pair, as defined in [RFC3447], with RSA modulus length equal to the modulusLength member of normalizedAlgorithm and RSA public exponent equal to the publicExponent member of normalizedAlgorithm.
If performing the operation results in an error,
then return an error named
OperationError
.
Let algorithm be a new RsaHashedKeyAlgorithm object.
Set the name attribute of
algorithm to "RSA-OAEP"
.
Set the modulusLength attribute of algorithm to equal the modulusLength member of normalizedAlgorithm.
Set the publicExponent attribute of algorithm to equal the publicExponent member of normalizedAlgorithm.
Set the hash attribute of algorithm to equal the hash member of normalizedAlgorithm.
Let publicKey be a new Key object representing the public key of the generated key pair.
Set the type attribute of publicKey
to "public"
Set the algorithm attribute of publicKey to be algorithm.
Set the extractable attribute of publicKey to true.
Set the usages attribute of
publicKey to be the
usage intersection of
usages and [ "encrypt", "wrapKey" ]
.
Let privateKey be a new Key object representing the private key of the generated key pair.
Set the type attribute of privateKey
to "private"
Set the algorithm attribute of privateKey to be algorithm.
Set the extractable attribute of privateKey to extractable.
Set the usages attribute of
privateKey to be the
usage intersection of
usages and [ "decrypt", "unwrapKey" ]
.
Let result be a new KeyPair object.
Set the publicKey attribute of result to be publicKey.
Set the privateKey attribute of result to be privateKey.
Return result.
Let keyData be the key data to be imported.
Let normalizedAlgorithm be the result of normalizing algorithm to RsaHashedImportParams.
If any of the members of RsaHashedImportParams are not present in
normalizedAlgorithm then return
an error named SyntaxError
.
"spki"
:Let spki be the result of running the parse a subjectPublicKeyInfo algorithm over keyData.
If an error occurred while parsing,
then return an error named
DataError
.
Let hash be a string whose initial value is undefined.
Let alg be the algorithm
object identifier
field of the algorithm
AlgorithmIdentifier field of
spki.
rsaEncryption
OID defined in RFC 3447:
Let hash be undefined.
id-RSAES-OAEP
OID defined in RFC 3447:
Let params be the ASN.1 structure contained within
the parameters
field of the algorithm
AlgorithmIdentifier field of spki.
If params is not defined, or is not an instance of
the RSAES-OAEP-params
ASN.1 type defined in
RFC3447,
return an error named
DataError
.
Let hashAlg be the AlgorithmIdentifier ASN.1 type
within the hashAlgorithm
field of params.
algorithm
object identifier field of
hashAlg is equivalent to the id-sha1
OID defined in RFC 3447:
Set hash to the string SHA-1
.
algorithm
object identifier field of
hashAlg is equivalent to the id-sha256
OID defined in RFC 3447:
Set hash to the string SHA-256
.
algorithm
object identifier field of
hashAlg is equivalent to the id-sha384
OID defined in RFC 3447:
Set hash to the string SHA-384
.
algorithm
object identifier field of
hashAlg is equivalent to the id-sha512
OID defined in RFC 3447:
Set hash to the string SHA-512
.
Return an error named
NotSupportedError
.
If the algorithm
object identifier field of the
maskGenAlgorithm
field of params is not
equivalent to the OID id-mgf1
defined in RFC 3447, return an error named NotSupportedError
.
If the parameters
field of the
maskGenAlgorithm
field of params is not
an instance of the HashAlgorithm
ASN.1 type that is
identical in content to the hashAlglorithm
field of
params, return an
error named NotSupportedError
.
Return an error named
DataError
.
If hash is defined, and is not equal to the name member of the hash member of
normalizedAlgorithm, return an error named DataError
.
Set hash to the name member of the hash member of normalizedAlgorithm.
Let publicKey be the result of performing the parse an ASN.1 structure
algorithm, with data as the
subjectPublicKeyInfo
field of spki,
structure as the RSAPublicKey
structure
specified in Section A.1.1 of RFC 3447, and
exactData set to true.
If an error occurred while parsing,
then return an error named
DataError
.
Let key be a new Key object that represents the RSA public key identified by publicKey.
Set the type attribute of key
to "public"
"pkcs8"
:Let privateKeyInfo be the result of running the parse a privateKeyInfo algorithm over keyData.
If an error occurred while parsing, then return an error named DataError
.
Let hash be a string whose initial value is undefined.
Let alg be the algorithm
object identifier
field of the privateKeyAlgorithm
PrivateKeyAlgorithmIdentifier field of privateKeyInfo.
rsaEncryption
OID defined in RFC 3447:
Let hash be undefined.
id-RSAES-OAEP
OID defined in RFC 3447:
Let params be the ASN.1 structure contained within
the parameters
field of the
privateKeyAlgorithm
PrivateKeyAlgorithmIdentifier
field of privateKeyInfo.
If params is not defined, or is not an instance of
the RSAES-OAEP-params
ASN.1 type defined in RFC3447, return an error named NotSupportedError
.
Let hashAlg be the AlgorithmIdentifier ASN.1 type
within the hashAlgorithm
field of
params.
algorithm
object identifier field of
hashAlg is equivalent to the id-sha1
OID defined in RFC 3447:
Set hash to the string SHA-1
.
algorithm
object identifier field of
hashAlg is equivalent to the
id-sha256
OID defined in RFC
3447:
Set hash to the string SHA-256
.
algorithm
object identifier field of
hashAlg is equivalent to the
id-sha384
OID defined in RFC
3447:
Set hash to the string SHA-384
.
algorithm
object identifier field of
hashAlg is equivalent to the
id-sha512
OID defined in RFC
3447:
Set hash to the string SHA-512
.
Return an error named
NotSupportedError
.
If the algorithm
object identifier field of the
maskGenAlgorithm
field of params is not
equivalent to the OID id-mgf1
defined in RFC 3447, return an error named NotSupportedError
.
If the parameters
field of the
maskGenAlgorithm
field of params is not
an instance of the HashAlgorithm
ASN.1 type that is
identical in content to the hashAlglorithm
field of
params, return an
error named NotSupportedError
.
Return an error named
DataError
.
If hash is defined, and is not equal to the name member of the hash member of
normalizedAlgorithm, return an error named DataError
.
Set hash to the name member of the hash member of normalizedAlgorithm.
Let rsaPrivateKey be the result of performing the parse an ASN.1 structure
algorithm, with data as the
privateKey
field of privateKeyInfo,
structure as the RSAPrivateKey
structure
specified in Section A.1.2 of RFC 3447, and
exactData set to true.
If an error occurred while parsing,
then return an error named
DataError
.
Let key be a new Key object that represents the RSA private key identified by rsaPrivateKey.
Set the type attribute of key
to "private"
"jwk"
:Let jwk be the result of running the parse a jwk algorithm over keyData.
If the "kty"
field of jwk is not a
case-sensitive string match to "RSA"
,
then return an error named
DataError
.
If the "use"
field of jwk is present, and is
not a case-sensitive string match to "enc"
,
then return an error named
DataError
.
If the "key_ops"
field of jwk is present, and
is invalid according to the requirements of
JSON Web Key or
does not contain all of the specified usages values,
then return an error named
DataError
.
If the alg
field of jwk is present,
and is not RSA-OAEP
,
return an error named
DataError
.
Set hash to the name member of the hash member of normalizedAlgorithm.
"d"
field of jwk is present:
If jwk does not meet the requirements of
Section 6.3.2 of JSON Web
Algorithms,
then return an error named
DataError
.
Let key be a new Key object that represents the RSA private key identified by interpreting jwk according to Section 6.3.2 of JSON Web Algorithms.
Set the type attribute of
key to "private"
If jwk does not meet the requirements of Section
6.3.1 of JSON Web Algorithms, then return an error named DataError
.
Let key be a new Key object that represents the RSA public key identified by interpreting jwk according to Section 6.3.1 of JSON Web Algorithms.
Set the type attribute of
key to "public"
NotSupportedError
.
Let algorithm be a new RsaHashedKeyAlgorithm.
Set the name attribute of
algorithm to "RSA-OAEP"
Set the modulusLength attribute of algorithm to the length, in bits, of the RSA public modulus.
Set the publicExponent attribute of algorithm to the BigInteger representation of the RSA public exponent.
Set the hash attribute of algorithm to a new KeyAlgorithm whose name attribute is hash.
Set the algorithm attribute of key to algorithm
Return key.
Let key be the key to be exported.
"spki"
If the type attribute of key is
not "public"
,
then return an error named
InvalidAccessError
.
Let result be the result of encoding a subjectPublicKeyInfo with the following properties:
Set the algorithm field to an
AlgorithmIdentifier
ASN.1 type with the following
properties:
Set the algorithm field to the OID
id-RSAES-OAEP
defined in
RFC 3447.
Set the params field to an instance of the
RSAES-OAEP-params
ASN.1 type with the following
properties:
Set the hashAlgorithm field to an instance of
the HashAlgorithm
ASN.1 type with the
following properties:
SHA-1
:
Set the algorithm object identifier to the
OID id-sha1
defined in RFC 3447.
SHA-256
:
Set the algorithm object identifier to the
OID id-sha256
defined in RFC 3447.
SHA-384
:
Set the algorithm object identifier to the
OID id-sha384
defined in RFC 3447.
SHA-512
:
Set the algorithm object identifier to the
OID id-sha512
defined in RFC 3447.
Set the maskGenAlgorithm field to an instance
of the MaskGenAlgorithm
ASN.1 type with the
following properties:
Set the algorithm field to the OID
id-mgf1
defined in RFC
3447.
Set the params field to an instance of the
HashAlgorithm
ASN.1 type that is
identical to the hashAlgorithm field.
Set the subjectPublicKey field to the result of
DER-encoding an RSAPublicKey
ASN.1 type, as defined
in RFC 3447, Appendix A.1.1, that
represents the RSA public key identified by key
"pkcs8"
:
If the type attribute of key is
not "private"
,
then return an error named
InvalidAccessError
.
Let result be the result of encoding a privateKeyInfo with the following properties:
Set the version field to 0.
Set the privateKeyAlgorithm field to an
PrivateKeyAlgorithmIdentifier
ASN.1 type with the
following properties:
Set the algorithm field to the OID
id-RSAES-OAEP
defined in
RFC 3447.
Set the params field to an instance of the
RSAES-OAEP-params
ASN.1 type with the following
properties:
Set the hashAlgorithm field to an instance of
the HashAlgorithm
ASN.1 type with the
following properties:
SHA-1
:
Set the algorithm object identifier to the
OID id-sha1
defined in RFC 3447.
SHA-256
:
Set the algorithm object identifier to the
OID id-sha256
defined in RFC 3447.
SHA-384
:
Set the algorithm object identifier to the
OID id-sha384
defined in RFC 3447.
SHA-512
:
Set the algorithm object identifier to the
OID id-sha512
defined in RFC 3447.
Set the maskGenAlgorithm field to an instance
of the MaskGenAlgorithm
ASN.1 type with the
following properties:
Set the algorithm field to the OID
id-mgf1
defined in RFC
3447.
Set the params field to an instance of the
HashAlgorithm
ASN.1 type that is
identical to the hashAlgorithm field.
Set the privateKey field to the result of
DER-encoding an RSAPrivateKey
ASN.1 type, as defined
in RFC 3447, Appendix A.1.2, that
represents the RSA private key identified by key
"jwk"
:Let jwk be a new internal object.
Set the kty
field of jwk to the string
"RSA"
.
Set the alg
field of jwk to the string
RSA-OAEP
.
Set the fields n
and e
of jwk
according to the corresponding definitions in JSON Web
Algorithms, Section 6.3.1.
"private"
:
Set the fields named d
, p
,
q
, dp
, dq
, and
qi
of jwk according to the
corresponding definitions in JSON Web
Algorithms, Section 6.3.2.
If the underlying RSA private key represented by
key is represented by more than two primes, set the
field named oth
of jwk according to
the corresponding definition in JSON Web
Algorithms, Section 6.3.2.7
Set the key_ops
field of jwk to the usages attribute of key.
Set the ext
field of jwk to the extractable attribute of
key.
Let stringifiedJwk be the result of encoding jwk according to the grammar specified in Section 15.12 of ECMA262.
Let result be the UTF-8 encoding of stringifiedJwk.
Return an error named
NotSupportedError
.
Let data be a new ArrayBuffer
containing
result.
Return data.
The "ECDSA"
algorithm identifier is used to perform signing
and verification using the ECDSA algorithm specified in
[X9.62].
The recognized algorithm name for
this algorithm is "ECDSA"
.
Operation | Parameters | Result |
---|---|---|
sign | EcdsaParams | ArrayBuffer |
verify | EcdsaParams | boolean |
generateKey | EcKeyGenParams | KeyPair |
importKey | None | Key |
exportKey | None | ArrayBuffer |
dictionary EcdsaParams : Algorithm {
// The hash algorithm to use
AlgorithmIdentifier hash;
};
typedef DOMString NamedCurve;
dictionary EcKeyGenParams : Algorithm {
// A named curve
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 are recognized:
P-256
secp256r1
.P-384
secp384r1
.P-521
secp521r1
.
[NoInterfaceObject]
interface EcKeyAlgorithm : KeyAlgorithm {
// The named curve that the key uses
readonly attribute NamedCurve namedCurve;
};
dictionary EcKeyImportParams : Algorithm {
// A named curve
NamedCurve namedCurve;
};
If the type attribute of key
is not "private"
,
then return an error named
InvalidAccessError
.
Let normalizedAlgorithm be the result of normalizing algorithm to EcdsaParams.
If any of the properties of EcdsaParams are
not present in normalizedAlgorithm,
then return an error named
SyntaxError
.
Let hashAlgorithm be the hash member of normalizedAlgorithm.
If hashAlgorithm does not describe a
registered algorithm that supports the digest
operation,
then return an error named
NotSupportedError
.
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.
Perform the ECDSA signing process, as specified in X9.62, Section 7.3, with M as the message, using params as the EC domain parameters, and with d as the private key.
Let r and s be the pair of integers resulting from performing the ECDSA signing process.
Let result be a new ArrayBuffer
.
Convert r to a bitstring and append the sequence of bytes to result.
Convert s to a bitstring and append the sequence of bytes to result.
Return result.
If the type attribute of key
is not "public"
,
then return an error named
InvalidAccessError
.
Let normalizedAlgorithm be the result of normalizing algorithm to EcdsaParams.
If any of the properties of EcdsaParams are
not present in normalizedAlgorithm,
then return an error named
SyntaxError
.
Let hashAlgorithm be the hash member of normalizedAlgorithm.
If hashAlgorithm does not describe a
registered algorithm that supports the digest
operation,
then return an error named
NotSupportedError
.
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.
Perform the ECDSA verifying process, as specified in X9.62, Section 7.4, with M as the received message, signatire as the received signature and using params as the EC domain parameters, and Q as the public key.
Let result be a boolean indicating whether or not the purported
signature is valid, with true
indicating the signature is valid
and false
indicating it is invalid.
Return result.
Let normalizedAlgorithm be the result of normalizing algorithm to EcKeyGenParams.
If any of the members of EcKeyGenParams are
not present in normalizedAlgorithm,
then return an error named
SyntaxError
.
If usages contains a value which is not
one of "sign"
or "verify"
,
then return an error named
InvalidAccessError
.
Generate an Eliptic Curve key pair, as defined in [X9.62] with domain parameters for the curve identified by the namedCurve member of normalizedAlgorithm.
If performing the key generation operation results in an error,
then return an error named
OperationError
.
Let algorithm be a new EcKeyAlgorithm object.
Set the name attribute of
algorithm to "ECDSA"
.
Set the namedCurve attribute of algorithm to equal the namedCurve member of normalizedAlgorithm.
Let publicKey be a new Key object representing the public key of the generated key pair.
Set the type attribute of publicKey
to "public"
Set the algorithm attribute of publicKey to be algorithm.
Set the extractable attribute of publicKey to true.
Set the usages attribute of publicKey to be the empty list.
Let privateKey be a new Key object representing the private key of the generated key pair.
Set the type attribute of privateKey
to "private"
Set the algorithm attribute of privateKey to be algorithm.
Set the extractable attribute of privateKey to extractable.
Set the usages attribute of
privateKey to be the
usage intersection of
usages and [ "sign", "verify" ]
.
Let result be a new KeyPair object.
Set the publicKey attribute of result to be publicKey.
Set the privateKey attribute of result to be privateKey.
Return result.
Let keyData be the key data to be imported.
"spki"
:Let spki be the result of running the parse a subjectPublicKeyInfo algorithm over keyData
If an error occurred while parsing,
then return an error named
DataError
.
If the algorithm
object identifier field of the
algorithm
AlgorithmIdentifier field of spki is
not equal to the id-ecPublicKey
object identifier defined in RFC 5480,
then return an error named
DataError
.
If the parameters
field of the algorithm
AlgorithmIdentifier field of spki is absent,
then return an error named
DataError
.
Let params be the parameters
field of the
algorithm
AlgorithmIdentifier field of spki.
If params is not an instance of the
namedCurve
ASN.1 type defined in RFC
5480,
then return an error named
DataError
.
Let key be a new Key object that represents the Elliptic Curve public key identified by performing the conversion steps defined in Section 2.2 of RFC 5480.
Set the type attribute of key
to "public"
Let algorithm be a new EcKeyAlgorithm.
Set the name attribute of
algorithm to "ECDSA"
.
secp256r1
object identifier defined in RFC 5480:
Set the namedCurve
attribute of algorithm to "P-256"
.
secp384r1
object identifier defined in RFC 5480:
Set the namedCurve
attribute of algorithm to "P-384"
.
secp521r1
object identifier defined in RFC 5480:
Set the namedCurve
attribute of algorithm to "P-521"
.
Return an error named
DataError
.
Set the algorithm attribute of key to algorithm.
"pkcs8"
:Let privateKeyInfo be the result of running the parse a privateKeyInfo algorithm over keyData.
If an error occurs while parsing,
then return an error named
DataError
.
If the algorithm
object identifier field of the
privateKeyAlgorithm
PrivateKeyAlgorithm field of
privateKeyInfo is not equal to the
id-ecPublicKey
object identifier defined in RFC 5480,
then return an error named
DataError
.
If the parameters
field of the
privateKeyAlgorithm
PrivateKeyAlgorithmIdentifier field
of privateKeyInfo is not present,
then return an error named
DataError
.
Let params be the parameters
field of the
privateKeyAlgorithm
PrivateKeyAlgorithmIdentifier field
of privateKeyInfo.
If the params is not an instance of the
namedCurve
ASN.1 type defined in RFC
5480,
then return an error named
DataError
.
Let ecPrivateKey be the result of performing the parse an ASN.1 structure
algorithm, with data as the privateKey
field
of privateKeyInfo, structure as the ASN.1
ECPrivateKey
structure specified in Section 3 of RFC 5915, and exactData set to true.
If an error occurred while parsing,
then return an error named
DataError
.
If the parameters
field of ecPrivateKey is
present, and is not an instance of the namedCurve
ASN.1
type defined in RFC 5480, or does not contain
the same object identifier as the parameters
field of the
privateKeyAlgorithm
PrivateKeyAlgorithmIdentifier field
of privateKeyInfo,
then return an error named
DataError
.
Let key be a new Key object that represents the Elliptic Curve private key identified by performing the conversion steps defined in Section 3 of RFC 5915.
Set the type attribute of key
to "private"
Let algorithm be a new EcKeyAlgorithm.
Set the name attribute of
algorithm to "ECDSA"
.
secp256r1
object identifier defined in RFC 5480:
Set the namedCurve
attribute of algorithm to "P-256"
.
secp384r1
object identifier defined in RFC 5480:
Set the namedCurve
attribute of algorithm to "P-384"
.
secp521r1
object identifier defined in RFC 5480:
Set the namedCurve
attribute of algorithm to "P-521"
.
Return an error named
DataError
.
Set the algorithm attribute of key to algorithm.
"jwk"
:Let jwk be the result of running the parse a JWK algorithm over keyData.
If an error occurred while parsing,
then return an error named
DataError
.
If the "kty"
field of jwk is not
"EC"
,
then return an error named
DataError
.
If the "use"
field of jwk is present, and is
not "sig"
,
then return an error named
DataError
.
If the "key_ops"
field of jwk is present, and
is invalid according to the requirements of JSON Web
Key, or it does not contain all of the specified usages
values,
then return an error named
DataError
.
If the "ext"
field of jwk is present and
has the value false and extractable is true,
then return an error named
DataError
.
"d"
field is present:
If jwk does not meet the requirements of Section
6.2.2 of JSON Web Algorithms,
then return an error named
DataError
.
Let key be a new Key object that represents the Elliptic Curve private key identified by interpreting jwk according to Section 6.2.2 of JSON Web Algorithms.
Set the type attribute of
Key to "private"
.
If jwk does not meet the requirements of Section
6.2.1 of JSON Web Algorithms,
then return an error named
DataError
.
Let key be a new Key object that represents the Elliptic Curve public key identified by interpreting jwk according to Section 6.2.1 of JSON Web Algorithms.
Set the type attribute of
Key to "public"
.
Let algorithm be a new instance of an EcKeyAlgorithm object.
Set the name attribute of
algorithm to "ECDSA"
.
"crv"
field of jwk is
"P-256"
Set the namedCurve
attribute of algorithm to "P-256"
.
"crv"
field of jwk is
"P-384"
Set the namedCurve
attribute of algorithm to "P-384"
.
"crv"
field of jwk is
to "P-521"
Set the namedCurve
attribute of algorithm to "P-521"
.
Return an error named
DataError
.
Set the algorithm attribute of key to algorithm.
Return an error named
NotSupportedError
.
Return key
Let key be the Key to be exported.
"spki"
:
If the type attribute of key is
not "public"
,
then return an error named
InvalidAccessError
.
Let result be the result of >encoding a subjectPublicKeyInfo with the following properties:
Set the algorithm field to an
AlgorithmIdentifier
ASN.1 type with the following
properties:
Set the algorithm object identifier to the OID
1.2.840.10045.2.1
.
Set the parameters field to an instance of the
namedCurve
ASN.1 type as follows:
"P-256"
:
Let the namedCurve be the object identifier
secp256r1
defined in RFC
5480
"P-384"
:
Let the namedCurve be the object identifier
secp384r1
defined in RFC
5480
"P-521"
:
Let the namedCurve be the object identifier
secp521r1
defined in RFC
5480
Set the subjectPublicKey field to the octet string that represents the Elliptic Curve public key identified by key according to the encoding rules specified in Section 2.2 of RFC 5480 and using the uncompressed form.
"pkcs8"
:
If the type attribute of key
is not "private"
,
then return an error named
InvalidAccessError
.
Let result be the result of encoding a privateKeyInfo with the following properties:
Set the version field to 0
.
Set the privateKeyAlgorithm field to an
PrivateKeyAlgorithmIdentifier
ASN.1 type with the
following properties:
Set the algorithm object identifier to the OID
1.2.840.10045.2.1
.
Set the parameters field to an instance of the
namedCurve
ASN.1 type as follows:
"P-256"
:
Let the namedCurve be the object identifier
secp256r1
defined in RFC
5480
"P-384"
:
Let the namedCurve be the object identifier
secp384r1
defined in RFC
5480
"P-521"
:
Let the namedCurve be the object identifier
secp521r1
defined in RFC
5480
Set the privateKey field to the result of DER-encoding
an instance of the ECPrivateKey
structure defined in
Section 3 of RFC 5915 for the Elliptic
Curve private key represented by key and that conforms
to the following:
The parameters field is present, and is equivalent
to the parameters field of the
privateKeyAlgorithm field of this
PrivateKeyInfo
ASN.1 structure.
The publicKey field is present and represents the Elliptic Curve public key associated with the Elliptic Curve private key represented by key.
"jwk"
:Let jwk be a new internal object.
Set the kty
property of jwk to
"EC"
.
P-256
:
crv
property of jwk to
"P-256"
P-384
:
crv
property of jwk to
"P-384"
P-521
:
crv
property of jwk to
"P-521"
Set the x
property of jwk according to the
definition in Section 6.2.1.2 of JSON Web
Algorithms.
Set the y
property of jwk according to the
definition in Section 6.2.1.3 of JSON Web
Algorithms.
private
Set the d
property of jwk according to the
definition in Section 6.2.2.1 of JSON Web
Algorithms.
Set the key_ops
property of jwk to the
usages attribute of key.
Set the ext
property of jwk to the extractable attribute of
key.
Let stringifiedJwk be the result of encoding jwk into a string according to the grammer specified in Section 15.12 of ECMA262.
Let data be the UTF-8 encoding of stringifiedJwk.
Return an error named
NotSupportedError
.
Let data be a new ArrayBuffer
that contains
result.
Return data.
OPEN ISSUE: The import/export of JWK ignores the "alg" field, because it does not provide a 1:1 mapping between ECDSA (which choses the hash at sign/verify time, because it is safe to do so) and the JWS alg (which incorporates the hash algorithm).
This describes using Elliptic Curve Diffie-Hellman (ECDH) for key generation and key agreement, as specified by X9.63.
The recognized algorithm name for
this algorithm is "ECDH"
.
Operation | Parameters | Result |
---|---|---|
generateKey | EcKeyGenParams | KeyPair |
deriveBits | EcdhKeyDeriveParams | Octet string |
importKey | EcKeyImportParams | Key |
exportKey | None | ArrayBuffer |
Let normalizedAlgorithm be the result of normalizing algorithm to EcKeyGenParams.
If any of the members of EcKeyGenParams are
not present in normalizedAlgorithm,
then return an error named
SyntaxError
.
If usages contains a value which is not
one of "deriveKey"
or "deriveBits"
,
then return an error named
InvalidAccessError
.
Generate an Elliptic Curve key pair, as defined in [X9.63] with domain parameters for the curve identified by the namedCurve member of normalizedAlgorithm.
If performing the operation results in an error,
then return an error named
OperationError
.
Let algorithm be a new EcKeyAlgorithm object.
Set the name member of
algorithm to "ECDH"
.
Set the namedCurve attribute of algorithm to equal the namedCurve member of normalizedAlgorithm.
Let publicKey be a new Key object representing the public key of the generated key pair.
Set the type attribute of publicKey
to "public"
Set the algorithm attribute of publicKey to be algorithm.
Set the extractable attribute of publicKey to true.
Set the usages attribute of publicKey to be the empty list.
Let privateKey be a new Key object representing the private key of the generated key pair.
Set the type attribute of privateKey
to "private"
Set the algorithm attribute of privateKey to be algorithm.
Set the extractable attribute of privateKey to extractable.
Set the usages attribute of
privateKey to be the
usage intersection of
usages and [ "deriveKey", "deriveBits" ]
.
Let result be a new KeyPair object.
Set the publicKey attribute of result to be publicKey.
Set the privateKey attribute of result to be privateKey.
Return result.
If the type attribute of key
is not "private"
,
then return an error named
InvalidAccessError
.
Let normalizedAlgorithm be the result of normalizing algorithm to EcdhKeyDeriveParams.
If any of the members of EcdhKeyDeriveParams are not present in
normalizedAlgorithm,
then return an error named
SyntaxError
.
Let publicKey be the public member of normalizedAlgorithm.
If the name attribute of the
algorithm attribute of publicKey is
not "ECDH"
,
then return an error named
InvalidAccessError
.
If the type attribute of publicKey
is not
"public"
,
then return an error named
InvalidAccessError
.
If the namedCurve attribute of
the algorithm attribute of publicKey
is not equal to the namedCurve
property of
the algorithm attribute of key,
then return an error named
DataError
.
Perform the ECDH primitive specified in X9.63 Section 5.4.1 with key as the EC private key d and the EC public key represented by publicKey as the EC public key Q.
If performing the operation results in an error,
then return an error named
OperationError
.
Let secret be the result of applying the field element to octet string comversion defined in Section ? of X9.63 to the output of the ECDH primitive.
DataError
.
Let keyData be the key data to be imported.
"spki"
:Let spki be the result of running the parse a subjectPublicKeyInfo algorithm over keyData
If an error occurred while parsing,
then return an error named
DataError
.
If the algorithm
object identifier field of the
algorithm
AlgorithmIdentifier field of spki is
not equal to the id-ecPublicKey
or id-ecDH
object identifiers defined in RFC 5480,
then return an error named
DataError
.
If the parameters
field of the algorithm
AlgorithmIdentifier field of spki is absent,
then return an error named
SyntaxError
.
Let params be the parameters
field of the
algorithm
AlgorithmIdentifier field of spki.
If params is not an instance of the
namedCurve
ASN.1 type defined in RFC
5480,
then return an error named
DataError
.
Let key be a new Key object that represents the Elliptic Curve public key identified by performing the conversion steps defined in Section 2.2 of RFC 5480.
Set the type attribute of key
to "public"
Let algorithm be a new EcKeyAlgorithm.
Set the name attribute of
algorithm to "ECDH"
.
secp256r1
object identifier defined in RFC 5480:
Set the namedCurve
attribute of algorithm to "P-256"
.
secp384r1
object identifier defined in RFC 5480:
Set the namedCurve
attribute of algorithm to "P-384"
.
secp521r1
object identifier defined in RFC 5480:
Set the namedCurve
attribute of algorithm to "P-521"
.
Return an error named
DataError
.
Set the algorithm attribute of key to algorithm.
"pkcs8"
:Let privateKeyInfo be the result of running the parse a privateKeyInfo algorithm over keyData.
If an error occurs while parsing,
return an error named
DataError
.
If the algorithm
object identifier field of the
privateKeyAlgorithm
PrivateKeyAlgorithm field of
privateKeyInfo is not equal to the
id-ecPublicKey
or id-ecDH
object identifiers
defined in RFC 5480,
return an error named
DataError
.
If the parameters
field of the
privateKeyAlgorithm
PrivateKeyAlgorithmIdentifier field
of privateKeyInfo is not present,
return an error named
DataError
.
Let params be the parameters
field of the
privateKeyAlgorithm
PrivateKeyAlgorithmIdentifier field
of privateKeyInfo.
If the params is not an instance of the
namedCurve
ASN.1 type defined in RFC
5480,
return an error named
DataError
.
Let ecPrivateKey be the result of performing the
parse an ASN.1 structure
algorithm, with data as the privateKey
field
of privateKeyInfo, structure as the ASN.1
ECPrivateKey
structure specified in Section 3 of
RFC 5915, and exactData set to true.
If an error occurred while parsing,
then return an error named
DataError
.
If the parameters
field of ecPrivateKey is
present, and is not an instance of the namedCurve
ASN.1
type defined in RFC 5480, or does not contain
the same object identifier as the parameters
field of the
privateKeyAlgorithm
PrivateKeyAlgorithmIdentifier field
of privateKeyInfo,
return an error named
DataError
.
Let key be a new Key object that represents the Elliptic Curve private key identified by performing the conversion steps defined in Section 3 of RFC 5915.
Set the type attribute of key
to "private"
.
Let algorithm be a new EcKeyAlgorithm.
Set the name attribute of
algorithm to "ECDH"
.
secp256r1
object identifier defined in RFC 5480:
Set the namedCurve
attribute of algorithm to "P-256"
.
secp384r1
object identifier defined in RFC 5480:
Set the namedCurve
attribute of algorithm to "P-384"
.
secp521r1
object identifier defined in RFC 5480:
Set the namedCurve
attribute of algorithm to "P-521"
.
Return an error named
DataError
.
Set the algorithm attribute of key to algorithm.
"jwk"
:Let jwk be the result of running the parse a JWK algorithm over keyData.
If an error occurred while parsing,
then return an error named
DataError
.
If the "kty"
field of jwk is
to "EC"
,
then return an error named
DataError
.
If the "use"
field of jwk is present,
then return an error named
DataError
.
If the "key_ops"
field of jwk is present, and
is invalid according to the requirements of JSON Web
Key, or it does not contain all of the specified usages
values, then return an error
named DataError
.
If the "ext"
field of jwk is present and
has the value false and extractable is true,
then return an error named
DataError
.
"d"
field is present:
If jwk does not meet the requirements of Section
6.2.2 of JSON Web Algorithms,
then return an error named
DataError
.
Let key be a new Key object that represents the Elliptic Curve private key identified by interpreting jwk according to Section 6.2.2 of JSON Web Algorithms.
Set the type attribute of
Key to "private"
.
If jwk does not meet the requirements of Section
6.2.1 of JSON Web Algorithms,
then return an error named
DataError
.
Let key be a new Key object that represents the Elliptic Curve public key identified by interpreting jwk according to Section 6.2.1 of JSON Web Algorithms.
Set the type attribute of
Key to "public"
.
Let algorithm be a new instance of an EcKeyAlgorithm object.
Set the name attribute of
algorithm to "ECDH"
.
"crv"
field of jwk is a
"P-256"
Set the namedCurve
attribute of algorithm to "P-256"
.
"crv"
field of jwk is
"P-384"
Set the namedCurve
attribute of algorithm to "P-384"
.
"crv"
field of jwk is
"P-521"
Set the namedCurve
attribute of algorithm to "P-521"
.
Return an error named
DataError
.
Set the algorithm attribute of key to algorithm.
"raw"
:
If any of the members of EcKeyImportParams are not present in
normalizedAlgorithm,
then return an error named
SyntaxError
.
If the namedCurve
member of normalizedAlgorithm is not a
named curve,
then return an error named
DataError
.
If usages is not the empty list,
then return an error named
DataError
.
If extractable is false,
then return an error named
InvalidAccessError
.
Let Q be the elliptic curve point on the curve identified by the namedCurve member of normalizedAlgorithm identified by interpreting keyData according to X9.62 Annex A.
Let algorithm be a new EcKeyAlgorithm object.
Set the name attribute of
algorithm to "ECDH"
.
Set the namedCurve attribute of algorithm to equal the namedCurve member of normalizedAlgorithm.
Let key be a new Key object.
Set the type attribute of key to
"public"
Set the algorithm attribute of key to algorithm.
Set the usages attribute of key to usages.
Set the extractable attribute of key to extractable.
Return an error named
NotSupportedError
.
Return key
Let key be the Key to be exported.
"spki"
:
If the type attribute of key is
not "public"
,
then return an error named
InvalidAccessError
.
Let result be the result of encoding a subjectPublicKeyInfo with the following properties:
Set the algorithm field to an
AlgorithmIdentifier
ASN.1 type with the following
properties:
Set the algorithm object identifier to the OID
1.3.132.112
.
Set the parameters field to an instance of the
namedCurve
ASN.1 type as follows:
"P-256"
:
Let the namedCurve be the object identifier
secp256r1
defined in RFC
5480
"P-384"
:
Let the namedCurve be the object identifier
secp384r1
defined in RFC
5480
"P-521"
:
Let the namedCurve be the object identifier
secp521r1
defined in RFC
5480
Set the subjectPublicKey field to the octet string that represents the Elliptic Curve public key identified by key according to the encoding rules specified in Section 2.2 of RFC 5480 and using the uncompressed form.
"pkcs8"
:
If the type attribute of key
is not "private"
,
then return an error named
InvalidAccessError
.
Let result be the result of encoding a privateKeyInfo with the following properties:
Set the version field to 0
.
Set the privateKeyAlgorithm field to an
PrivateKeyAlgorithmIdentifier
ASN.1 type with the
following properties:
Set the algorithm object identifier to the OID
1.3.132.112
.
Set the parameters field to an instance of the
namedCurve
ASN.1 type as follows:
"P-256"
:
Let the namedCurve be the object identifier
secp256r1
defined in RFC
5480
"P-384"
:
Let the namedCurve be the object identifier
secp384r1
defined in RFC
5480
"P-521"
:
Let the namedCurve be the object identifier
secp521r1
defined in RFC
5480
Set the privateKey field to the result of DER-encoding
an instance of the ECPrivateKey
structure defined in
Section 3 of RFC 5915 for the Elliptic
Curve private key represented by key and that conforms
to the following:
The parameters field is present, and is equivalent
to the parameters field of the
privateKeyAlgorithm field of this
PrivateKeyInfo
ASN.1 structure.
The publicKey field is present and represents the Elliptic Curve public key associated with the Elliptic Curve private key represented by key.
"jwk"
:Let jwk be a new internal object.
Set the kty
property of jwk to
"EC"
.
P-256
:
crv
property of jwk to
"P-256"
P-384
:
crv
property of jwk to
"P-384"
P-521
:
crv
property of jwk to
"P-521"
Set the x
property of jwk according to the
definition in Section 6.2.1.2 of JSON Web
Algorithms.
Set the y
property of jwk according to the
definition in Section 6.2.1.3 of JSON Web
Algorithms.
private
Set the d
property of jwk according to the
definition in Section 6.2.2.1 of JSON Web
Algorithms.
Set the key_ops
property of jwk to the
usages attribute of key.
Set the ext
property of jwk to the extractable attribute of
key.
Let stringifiedJwk be the result of encoding jwk into a string according to the grammer specified in Section 15.12 of ECMA262.
Let data be the UTF-8 encoding of stringifiedJwk.
"raw"
:
If the type attribute of key is
not "public"
,
then return an error named
InvalidAccessError
.
Let data be an octet string representing the Elliptic Curve point Q represented by key according to X9.62 Annex A.
Return an error named
NotSupportedError
.
Let data be a new ArrayBuffer
that contains
result.
Return data.
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 SP 800-38A [SP800-38A].
The recognized algorithm name for
this algorithm is "AES-CTR"
.
Operation | Parameters | Result |
---|---|---|
encrypt | AesCtrParams | ArrayBuffer |
decrypt | AesCtrParams | ArrayBuffer |
generateKey | AesKeyGenParams | Key |
importKey | None | Key |
exportKey | None | ArrayBuffer |
get key length | AesDerivedKeyParams | Integer |
dictionary AesCtrParams : Algorithm {
// The initial value of the counter block. counter MUST be 16 bytes
// (the AES block size). The counter bits are the rightmost length
// bits of the counter block. The rest of the counter block is for
// the nonce. The counter bits are incremented using the standard
// incrementing function specified in NIST SP 800-38A Appendix B.1:
// the counter bits are interpreted as a big-endian integer and
// incremented by one.
CryptoOperationData counter;
// The length, in bits, of the rightmost part of the counter block
// that is incremented.
[EnforceRange] octet length;
};
[NoInterfaceObject]
interface AesKeyAlgorithm : KeyAlgorithm {
// The length, in bits, of the key.
readonly attribute unsigned short length;
};
dictionary AesKeyGenParams : Algorithm {
// The length, in bits, of the key.
[EnforceRange] unsigned short length;
};
dictionary AesDerivedKeyParams : Algorithm {
// The length, in bits, of the key.
[EnforceRange] unsigned short length;
};
Let normalizedAlgorithm be the result of normalizing algorithm to AesCtrParams.
If any of the members of AesCtrParams are not
present in normalizedAlgorithm,
then return an error named
SyntaxError
.
If the counter member of
normalizedAlgorithm does not have length 16
bytes,
then return an error named
DataError
.
If the length member of
normalizedAlgorithm is zero or is greater
than 128,
then return an error named
DataError
.
Let ciphertext be the result of performing the CTR Encryption operation described in Section 6.5 of NIST SP 800-38A [SP800-38A] using AES as the block cipher, the contents of the counter member of normalizedAlgorithm as the initial value of the counter block, the length member of normalizedAlgorithm as the input parameter m to the standard counter block incrementing functon defined in Appendix B.1 of NIST SP 800-38A [SP800-38A] and plaintext as the input plaintext.
Return ciphertext.
Let normalizedAlgorithm be the result of normalizing algorithm to AesCtrParams.
If any of the members of AesCtrParams are not
present in normalizedAlgorithm,
then return an error named
SyntaxError
.
If the counter member of
normalizedAlgorithm does not have length 16
bytes,
then return an error named
DataError
.
If the length member of
normalizedAlgorithm is zero or is greater
than 128,
then return an error named
DataError
.
Let plaintext be the result of performing the CTR Decryption operation described in Section 6.5 of NIST SP 800-38A [SP800-38A] using AES as the block cipher, the contents of the counter member of normalizedAlgorithm as the initial value of the counter block, the length member of normalizedAlgorithm as the input parameter m to the standard counter block incrementing functon defined in Appendix B.1 of NIST SP 800-38A [SP800-38A] and ciphertext as the input ciphertext.
Return plaintext.
Let normalizedAlgorithm be the result of normalizing algorithm to AesKeyGenParams.
If any of the members of AesKeyGenParams are
not present in normalizedAlgorithm,
then return an error named
SyntaxError
.
If the length member of
normalizedAlgorithm is not equal to one of
128, 192 or 256,
then return an error named
DataError
.
If usages contains any entry which is not
one of "encrypt"
, "decrypt"
,
"wrapKey"
or "unwrapKey"
,
then return an error named
DataError
.
Generate an AES key of length equal to the length member of normalizedAlgorithm.
If the key generation step fails,
then return an error named
OperationError
.
Let key be a new Key object representing the generated AES key.
Let algorithm be a new AesKeyAlgorithm.
Set the name attribute of
algorithm to "AES-CTR"
.
Set the length attribute of algorithm to equal the length member of normalizedAlgorithm.
Set the algorithm attribute of key to algorithm.
Set the extractable attribute of key to be extractable.
Set the usages attribute of key to be usages.
Return key.
If usages contains an entry which is not
one of "encrypt"
, "decrypt"
,
"wrapKey"
or "unwrapKey"
,
then return an error named
DataError
.
"raw"
:Let data be the octet string contained in keyData.
If the length in bits of data is not 128, 192 or 256
then return an error named
DataError
.
"jwk"
:Let jwk be the result of running the parse a jwk algorithm over keyData.
If the "kty"
field of jwk is not
"oct"
,
then return an error named
DataError
.
If jwk does not meet the requirements of
Section 6.4 of JSON Web Algorithms,
then return an error named
DataError
.
Let data be the octet string obtained by decoding the
"k"
field of jwk.
"alg"
field of jwk is present, and is
not "A128CTR"
,
then return an error named
DataError
."alg"
field of jwk is present, and is
not "A192CTR"
,
then return an error named
DataError
."alg"
field of jwk is present, and is
not "A256CTR"
,
then return an error named
DataError
.DataError
.
If the "use"
field of jwk is present, and is
not "enc"
,
then return an error named
DataError
.
If the "key_ops"
field of jwk is present, and
is invalid according to the requirements of
JSON Web Key or
does not contain all of the specified usages values,
then return an error named
DataError
.
If the "ext"
field of jwk is present and
has the value false and extractable is true,
then return an error named
DataError
.
NotSupportedError
.
Let key be a new Key
object representing an AES key with value data.
Let algorithm be a new AesKeyAlgorithm.
Set the name attribute of
algorithm to "AES-CTR"
.
Set the length attribute of algorithm to the length, in bits, of data.
Set the algorithm attribute of key to algorithm.
Set the extractable attribute of key to extractable.
Set the usages attribute of key to the normalized value of usages.
Return key.
"raw"
:"jwk"
:Let jwk be a new internal object.
Set the kty
property of jwk to the
string "oct"
.
Set the k
property of jwk to be a string
containng the raw octets
of the key represented by key, encoded according to
Section 6.4 of JSON Web Algorithms.
Set the key_ops
property of jwk to equal the
usages attribute of key.
Set the ext
property of jwk to equal the
extractable attribute of
key.
Let stringifiedJwk be the result of encoding jwk into a string according to the grammer specified in Section 15.12 of ECMA262.
Let data be the UTF-8 encoding of stringifiedJwk.
Let keyData be a new ArrayBuffer containing data.
Return data.
Let normalizedAlgorithm be the result of normalizing algorithm to AesDerivedKeyParams.
If any of the members of
AesDerivedKeyParams are not present in
normalizedDerivedKeyAlgorithm,
then return an error named
SyntaxError
.
If the length member of
normalizedDerivedKeyAlgorithm is not 128, 192 or 256,
then return an error named
DataError
.
Return the length member of normalizedDerivedKeyAlgorithm.
This section is non-normative.
The "AES-CBC"
algorithm identifier is used to perform
encryption and decryption using AES in Cipher Block Chaining mode,
as described in NIST SP 800-38A [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 RFC 2315 [RFC2315].
The recognized algorithm name for
this algorithm is "AES-CBC"
.
Operation | Parameters | Result |
---|---|---|
encrypt | AesCbcParams | ArrayBuffer |
decrypt | AesCbcParams | ArrayBuffer |
generateKey | AesKeyGenParams | Key |
importKey | None | Key |
exportKey | None | ArrayBuffer |
get key length | AesDerivedKeyParams | Integer |
dictionary AesCbcParams : Algorithm {
// The initialization vector. MUST be 16 bytes.
CryptoOperationData iv;
};
Let normalizedAlgorithm be the result of normalizing algorithm to AesCbcParams.
If any of the members of AesCbcParams are not
present in normalizedAlgorithm,
then return an error named
SyntaxError
.
If the iv member of
normalizedAlgorithm does not have length 16
bytes,
then return an error named
DataError
.
Let padded-plaintext be the result of adding padding octets to ciphertext according to the procedure defined in Section 10.3 of RFC 2315 [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 SP 800-38A [SP800-38A] using AES as the block cipher, the contents of the iv member of normalizedAlgorithm as the IV input parameter and padded-plaintext as the input plaintext.
Return ciphertext.
Let normalizedAlgorithm be the result of normalizing algorithm to AesCbcParams.
If any of the members of AesCbcParams are not
present in normalizedAlgorithm,
then return an error named
SyntaxError
.
If the iv member of
normalizedAlgorithm does not have length 16
bytes,
then return an error named
DataError
.
Let padded-plaintext be the result of performing the CBC Decryption operation described in Section 6.2 of NIST SP 800-38A [SP800-38A] using AES as the block cipher, the contents of the iv member of normalizedAlgorithm as the IV input parameter and ciphertext as the input ciphertext.
Let p be the value of the last octet of padded-plaintext.
If p is zero or greater than 16, or if any of the last p
octets of padded-plaintext have a value which is not p,
then return an error named
DataError
.
Let plaintext be the result of removing p octents from the end of padded-plaintext.
Return plaintext.
Let normalizedAlgorithm be the result of normalizing algorithm to AesKeyGenParams.
If any of the members of AesKeyGenParams are
not present in normalizedAlgorithm,
then return an error named
SyntaxError
.
If the length member of
normalizedAlgorithm is not equal to one of
128, 192 or 256,
then return an error named
DataError
.
If usages contains any entry which is not
one of "encrypt"
, "decrypt"
,
"wrapKey"
or "unwrapKey"
,
then return an error named
DataError
.
Generate an AES key of length equal to the length member of normalizedAlgorithm.
If the key generation step fails,
then return an error named
OperationError
.
Let key be a new Key object representing the generated AES key.
Let algorithm be a new AesKeyAlgorithm.
Set the name attribute of
algorithm to "AES-CBC"
.
Set the length attribute of algorithm to equal the length member of normalizedAlgorithm.
Set the algorithm attribute of key to algorithm.
Set the extractable attribute of key to be extractable.
Set the usages attribute of key to be usages.
Return key.
If usages contains an entry which is not
one of "encrypt"
, "decrypt"
,
"wrapKey"
or "unwrapKey"
,
then return an error named
DataError
.
"raw"
:Let data be the octet string contained in keyData.
If the length in bits of data is not 128, 192 or 256
then return an error named
DataError
.
"jwk"
:Let jwk be the result of running the parse a jwk algorithm over keyData.
If the "kty"
field of jwk is not
to "oct"
,
then return an error named
DataError
.
If jwk does not meet the requirements of
Section 6.4 of JSON Web Algorithms,
then return an error named
DataError
.
Let data be the octet string obtained by decoding the
"k"
field of jwk.
"alg"
field of jwk is present, and is
not "A128CBC"
,
then return an error named
DataError
."alg"
field of jwk is present, and is
not "A192CBC"
,
then return an error named
DataError
."alg"
field of jwk is present, and is
not "A256CBC"
,
then return an error named
DataError
.DataError
.
If the "use"
field of jwk is present, and is
not "enc"
,
then return an error named
DataError
.
If the "key_ops"
field of jwk is present, and
is invalid according to the requirements of
JSON Web Key or
does not contain all of the specified usages values,
then return an error named
DataError
.
If the "ext"
field of jwk is present and
has the value false and extractable is true,
then return an error named
DataError
.
NotSupportedError
Let key be a new Key
object representing an AES key with value data.
Let algorithm be a new AesKeyAlgorithm.
Set the name attribute of
algorithm to "AES-CBC"
.
Set the length attribute of algorithm to the length, in bits, of data.
Set the algorithm attribute of key to algorithm.
Set the extractable attribute of key to extractable.
Set the usages attribute of key to the normalized value of usages.
Return key.
"raw"
:"jwk"
:Let jwk be a new internal object.
Set the kty
property of jwk to the
string "oct"
.
Set the k
property of jwk to be a string
containng the raw octets
of the key represented by key, encoded according to
Section 6.4 of JSON Web Algorithms.
Set the key_ops
property of jwk to equal the
usages attribute of key.
Set the ext
property of jwk to equal the
extractable attribute of
key.
Let stringifiedJwk be the result of encoding jwk into a string according to the grammer specified in Section 15.12 of ECMA262.
Let data be the UTF-8 encoding of stringifiedJwk.
Let keyData be a new ArrayBuffer containing data.
Return data.
Let normalizedAlgorithm be the result of normalizing algorithm to AesDerivedKeyParams.
If any of the members of
AesDerivedKeyParams are not present in
normalizedDerivedKeyAlgorithm,
then return an error named
SyntaxError
.
If the length member of
normalizedDerivedKeyAlgorithm is not 128, 192 or 256,
then return an error named
DataError
.
Return the length member of normalizedDerivedKeyAlgorithm.
This section is non-normative.
The "AES-CMAC"
algorithm identifier is used to perform
message authentication using AES with a cipher-based MAC, as
described in NIST SP 800-38B [SP800-38B].
The recognized algorithm name for
this algorithm is "AES-CMAC"
.
Operation | Parameters | Result |
---|---|---|
sign | AesCmacParams | ArrayBuffer |
verify | AesCmacParams | boolean |
generateKey | AesKeyGenParams | Key |
importKey | None | Key |
exportKey | None | ArrayBuffer |
get key length | AesDerivedKeyParams | Integer |
dictionary AesCmacParams : Algorithm {
// The length, in bits, of the MAC.
[EnforceRange] unsigned short length;
};
Let length equal the length member of normalizedAlgorithm, if present, and 128 otherwise.
If length is zero or greater than 128,
then return an error named
DataError
.
Let mac be the result of performing the MAC Generation operation described in Section 6.2 of NIST SP 800-38B [SP800-38B] using AES as the block cipher, length as the value of the MAC length parameter, Tlen, and message as the message, M.
Return mac.
Let normalizedAlgorithm be the result of normalizing algorithm to AesCmacParams.
Let length equal the length member of normalizedAlgorithm, if present, and 128 otherwise.
If length is zero or greater than 128,
then return an error named
DataError
.
Let ouput be the result of performing the MAC Verification operation described in Section 6.3 of NIST SP 800-38B [SP800-38B] using AES as the block cipher, length as the value of the MAC length parameter, Tlen, message as the message, M and signature as the received MAC, T'.
Return true if output is VALID and false otherwise.
Let normalizedAlgorithm be the result of normalizing algorithm to AesKeyGenParams.
If any of the members of AesKeyGenParams are
not present in normalizedAlgorithm,
then return an error named
SyntaxError
.
If the length member of
normalizedAlgorithm is not equal to one of
128, 192 or 256,
then return an error named
DataError
.
If usages contains any entry which is not
"sign"
or "verify"
,
then return an error named
DataError
.
Generate an AES key of length equal to the length member of normalizedAlgorithm.
If the key generation step fails,
then return an error named
OperationError
.
Let key be a new Key object representing the generated AES key.
Let algorithm be a new AesKeyAlgorithm.
Set the name attribute of
algorithm to "AES-CMAC"
.
Set the length attribute of algorithm to equal the length member of normalizedAlgorithm.
Set the algorithm attribute of key to algorithm.
Set the extractable attribute of key to be extractable.
Set the usages attribute of key to be usages.
Return key.
If usages contains an entry which is not
"sign"
or "verify"
,
then return an error named
DataError
.
"raw"
:Let data be the octet string contained in keyData.
If the length in bits of data is not 128, 192 or 256
then return an error named
DataError
.
"jwk"
:Let jwk be the result of running the parse a jwk algorithm over keyData.
If the "kty"
field of jwk is not
to "oct"
,
then return an error named
DataError
.
If jwk does not meet the requirements of
Section 6.4 of JSON Web Algorithms,
then return an error named
DataError
.
Let data be the octet string obtained by decoding the
"k"
field of jwk.
"alg"
field of jwk is present, and is
not "A128CMAC"
,
then return an error named
DataError
."alg"
field of jwk is present, and is
not "A192CMAC"
,
then return an error named
DataError
."alg"
field of jwk is present, and is
not "A256CMAC"
,
then return an error named
DataError
.DataError
.
If the "use"
field of jwk is present, and is
not "enc"
,
then return an error named
DataError
.
If the "key_ops"
field of jwk is present, and
is invalid according to the requirements of
JSON Web Key or
does not contain all of the specified usages values,
then return an error named
DataError
.
If the "ext"
field of jwk is present and
has the value false and extractable is true,
then return an error named
DataError
.
NotSupportedError
.
Let key be a new Key
object representing an AES key with value data.
Let algorithm be a new AesKeyAlgorithm.
Set the name attribute of
algorithm to "AES-CMAC"
.
Set the length attribute of algorithm to the length, in bits, of data.
Set the algorithm attribute of key to algorithm.
Set the extractable attribute of key to extractable.
Set the usages attribute of key to the normalized value of usages.
Return key.
"raw"
:"jwk"
:Let jwk be a new internal object.
Set the kty
property of jwk to the
string "oct"
.
Set the k
property of jwk to be a string
containng the raw octets
of the key represented by key, encoded according to
Section 6.4 of JSON Web Algorithms.
Set the key_ops
property of jwk to equal the
usages attribute of key.
Set the ext
property of jwk to equal the
extractable attribute of
key.
Let stringifiedJwk be the result of encoding jwk into a string according to the grammer specified in Section 15.12 of ECMA262.
Let data be the UTF-8 encoding of stringifiedJwk.
Return a new ArrayBuffer containing data.
Let normalizedAlgorithm be the result of normalizing algorithm to AesDerivedKeyParams.
If any of the members of
AesDerivedKeyParams are not present in
normalizedDerivedKeyAlgorithm,
then return an error named
SyntaxError
.
If the length member of
normalizedDerivedKeyAlgorithm is not 128, 192 or 256,
then return an error named
DataError
.
Return the length member of normalizedDerivedKeyAlgorithm.
This section is non-normative.
The "AES-GCM"
algorithm identifier is used to perform
authenticated encryption and decryption using AES in Galois/Counter Mode mode,
as described in NIST SP 800-38D [SP800-38D].
The recognized algorithm name for
this algorithm is "AES-GCM"
.
Operation | Parameters | Result |
---|---|---|
encrypt | AesGcmParams | ArrayBuffer |
decrypt | AesGcmParams | ArrayBuffer |
generateKey | AesKeyGenParams | Key |
importKey | None | Key |
exportKey | None | ArrayBuffer |
get key length | AesDerivedKeyParams | Integer |
dictionary AesGcmParams : Algorithm {
// The initialization vector to use. May be up to 2^64-1 bytes long.
CryptoOperationData iv;
// The additional authentication data to include.
CryptoOperationData? additionalData;
// The desired length of the authentication tag. May be 0 - 128.
[EnforceRange] octet? tagLength;
};
Let normalizedAlgorithm be the result of normalizing algorithm to AesGcmParams.
If the iv member of
AesGcmParams is not
present in normalizedAlgorithm,
then return an error named
SyntaxError
.
If plaintext has a length greater than 2^39 - 256
bytes,
then return an error named
DataError
.
If the iv member of
normalizedAlgorithm has a length greater than 2^64 - 1
bytes,
then return an error named
DataError
.
If the additionalData member
of normalizedAlgorithm is present, is not null and has a length
greater than 2^64 - 1 bytes,
then return an error named
DataError
.
DataError
.
Let additionalData be the contents of the additionalData member of normalizedAlgorithm if present and not null and the empty octet string otherwise.
Let C and T be the outputs that result from performing the Authenticated Encryption Function described in Section 7.1 of NIST SP 800-38D [SP800-38D] using AES as the block cipher, the contents of the iv member 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.
Return a new ArrayBuffer containing C | T where '|' denotes concatenation.
Let normalizedAlgorithm be the result of normalizing algorithm to AesGcmParams.
If the iv member of
AesGcmParams is not
present in normalizedAlgorithm,
then return an error named
SyntaxError
.
DataError
.
If plaintext has a length less than tagLength bits,
then return an error named
DataError
.
If the iv member of
normalizedAlgorithm has a length greater than 2^64 - 1
bytes,
then return an error named
DataError
.
If the additionalData member
of normalizedAlgorithm is present, is not null and has a length
greater than 2^64 - 1
bytes,
then return an error named
DataError
.
Let tag be the last tagLength bits of ciphertext.
Let actualCiphertext be the result of removing the last tagLength bits from ciphertext.
Let additionalData be the contents of the additionalData member of normalizedAlgorithm if present and not null and the empty octet string otherwise.
Perform the Authenticated Decryption Function described in Section 7.2 of NIST SP 800-38D [SP800-38D] using AES as the block cipher, the contents of the iv member 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 authentation tag, T.
OperationError
Return a new ArrayBuffer containing plaintext.
Let normalizedAlgorithm be the result of normalizing algorithm to AesKeyGenParams.
If any of the members of AesKeyGenParams are
not present in normalizedAlgorithm,
then return an error named
SyntaxError
.
If the length member of
normalizedAlgorithm is not equal to one of
128, 192 or 256,
then return an error named
DataError
.
If usages contains any entry which is not
one of "encrypt"
, "decrypt"
,
"wrapKey"
or "unwrapKey"
,
then return an error named
DataError
.
Generate an AES key of length equal to the length member of normalizedAlgorithm.
If the key generation step fails,
then return an error named
OperationError
.
Let key be a new Key object representing the generated AES key.
Let algorithm be a new AesKeyAlgorithm.
Set the name attribute of
algorithm to "AES-GCM"
.
Set the length attribute of algorithm to equal the length member of normalizedAlgorithm.
Set the algorithm attribute of key to algorithm.
Set the extractable attribute of key to be extractable.
Set the usages attribute of key to be usages.
Return key.
If usages contains an entry which is not
one of "encrypt"
, "decrypt"
,
"wrapKey"
or "unwrapKey"
,
then return an error named
DataError
.
"raw"
:Let data be the octet string contained in keyData.
If the length in bits of data is not 128, 192 or 256
then return an error named
DataError
.
"jwk"
:Let jwk be the result of running the parse a jwk algorithm over keyData.
If the "kty"
field of jwk is not
"oct"
,
then return an error named
DataError
.
If jwk does not meet the requirements of
Section 6.4 of JSON Web Algorithms,
then return an error named
DataError
.
Let data be the octet string obtained by decoding the
"k"
field of jwk.
"alg"
field of jwk is present, and is
not "A128GCM"
,
then return an error named
DataError
."alg"
field of jwk is present, and is
not "A192GCM"
,
then return an error named
DataError
."alg"
field of jwk is present, and is
not "A256GCM"
,
then return an error named
DataError
.DataError
.
If the "use"
field of jwk is present, and is
not "enc"
,
then return an error named
DataError
.
If the "key_ops"
field of jwk is present, and
is invalid according to the requirements of
JSON Web Key or
does not contain all of the specified usages values,
then return an error named
DataError
.
If the "ext"
field of jwk is present and
has the value false and extractable is true,
then return an error named
DataError
.
NotSupportedError
.
Let key be a new Key
object representing an AES key with value data.
Let algorithm be a new AesKeyAlgorithm.
Set the name attribute of
algorithm to "AES-GCM"
.
Set the length attribute of algorithm to the length, in bits, of data.
Set the algorithm attribute of key to algorithm.
Set the extractable attribute of key to extractable.
Set the usages attribute of key to the normalized value of usages.
Return key.
"raw"
:"jwk"
:Let jwk be a new internal object.
Set the kty
property of jwk to the
string "oct"
.
Set the k
property of jwk to be a string
containng the raw octets
of the key represented by key, encoded according to
Section 6.4 of JSON Web Algorithms.
Set the key_ops
property of jwk to equal the
usages attribute of key.
Set the ext
property of jwk to equal the
extractable attribute of
key.
Let stringifiedJwk be the result of encoding jwk into a string according to the grammer specified in Section 15.12 of ECMA262.
Let data be the UTF-8 encoding of stringifiedJwk.
DataError
.
Return a new ArrayBuffer containing data.
Let normalizedAlgorithm be the result of normalizing algorithm to AesDerivedKeyParams.
If any of the members of
AesDerivedKeyParams are not present in
normalizedDerivedKeyAlgorithm,
then return an error named
SyntaxError
.
If the length member of
normalizedDerivedKeyAlgorithm is not 128, 192 or 256,
then return an error named
DataError
.
Return the length member of normalizedDerivedKeyAlgorithm.
This section is non-normative.
The "AES-CFB-8"
algorithm identifier is used to perform
encryption and decryption using AES in Cipher Feedback mode, specifically CFB-8,
as described in Section 6.3 of NIST SP 800-38A
[SP800-38A].
The recognized algorithm name for
this algorithm is "AES-CFB-8"
.
Operation | Parameters | Result |
---|---|---|
encrypt | AesCfbParams | ArrayBuffer |
decrypt | AesCfbParams | ArrayBuffer |
generateKey | AesKeyGenParams | Key |
importKey | None | Key |
exportKey | None | ArrayBuffer |
get key length | AesDerivedKeyParams | Integer |
dictionary AesCfbParams : Algorithm {
// The initialization vector. MUST be 16 bytes.
CryptoOperationData iv;
};
Let normalizedAlgorithm be the result of normalizing algorithm to AesCfbParams.
If any of the members of AesCfbParams are not
present in normalizedAlgorithm,
then return an error named
SyntaxError
.
If the iv member of
normalizedAlgorithm does not have length 16
bytes,
then return an error named
DataError
.
Let ciphertext be the result of performing the CFB Encryption operation described in Section 6.3 of NIST SP 800-38A [SP800-38A] using AES as the block cipher, the contents of the iv member of normalizedAlgorithm as the IV input parameter, the value 8 as the input parameter s and plaintext as the input plaintext.
Return ciphertext.
Let normalizedAlgorithm be the result of normalizing algorithm to AesCfbParams.
If any of the members of AesCfbParams are not
present in normalizedAlgorithm,
then return an error named
SyntaxError
.
If the iv member of
normalizedAlgorithm does not have length 16
bytes,
then return an error named
DataError
.
Let plaintext be the result of performing the CFB Decryption operation described in Section 6.3 of NIST SP 800-38A [SP800-38A] using AES as the block cipher, the contents of the iv member of normalizedAlgorithm as the IV input parameter, the the value 8 as the input parameter s and ciphertext as the input ciphertext.
Return plaintext.
Let normalizedAlgorithm be the result of normalizing algorithm to AesKeyGenParams.
If any of the members of AesKeyGenParams are
not present in normalizedAlgorithm,
then return an error named
SyntaxError
.
If the length member of
normalizedAlgorithm is not equal to one of
128, 192 or 256,
then return an error named
DataError
.
If usages contains any entry which is not
one of "encrypt"
, "decrypt"
,
"wrapKey"
or "unwrapKey"
,
then return an error named
DataError
.
Generate an AES key of length equal to the length member of normalizedAlgorithm.
If the key generation step fails,
then return an error named
OperationError
.
Let key be a new Key object representing the generated AES key.
Let algorithm be a new AesKeyAlgorithm.
Set the name attribute of
algorithm to "AES-CFB-8"
.
Set the length attribute of algorithm to equal the length member of normalizedAlgorithm.
Set the algorithm attribute of key to algorithm.
Set the extractable attribute of key to be extractable.
Set the usages attribute of key to be usages.
Return key.
If usages contains an entry which is not
one of "encrypt"
, "decrypt"
,
"wrapKey"
or "unwrapKey"
,
then return an error named
DataError
.
"raw"
:Let data be the octet string contained in keyData.
If the length in bits of data is not 128, 192 or 256
then return an error named
DataError
.
"jwk"
:Let jwk be the result of running the parse a jwk algorithm over keyData.
If the "kty"
field of jwk is not
"oct"
,
then return an error named
DataError
.
If jwk does not meet the requirements of
Section 6.4 of JSON Web Algorithms,
then return an error named
DataError
.
Let data be the octet string obtained by decoding the
"k"
field of jwk.
"alg"
field of jwk is present, and is
not "A128CFB8"
,
then return an error named
DataError
."alg"
field of jwk is present, and is
not "A192CFB8"
,
then return an error named
DataError
."alg"
field of jwk is present, and is
not "A256CFB8"
,
then return an error named
DataError
.DataError
.
If the "use"
field of jwk is present, and is
not "enc"
,
then return an error named
DataError
.
If the "key_ops"
field of jwk is present, and
is invalid according to the requirements of
JSON Web Key or
does not contain all of the specified usages values,
then return an error named
DataError
.
If the "ext"
field of jwk is present and
has the value false and extractable is true,
then return an error named
DataError
.
NotSupportedError
.
Let key be a new Key
object representing an AES key with value data.
Let algorithm be a new AesKeyAlgorithm.
Set the name attribute of
algorithm to "AES-CFB-8"
.
Set the length attribute of algorithm to the length, in bits, of data.
Set the algorithm attribute of key to algorithm.
Set the extractable attribute of key to extractable.
Set the usages attribute of key to the normalized value of usages.
Return key.
"raw"
:"jwk"
:Let jwk be a new internal object.
Set the kty
property of jwk to the
string "oct"
.
Set the k
property of jwk to be a string
containng the raw octets
of the key represented by key, encoded according to
Section 6.4 of JSON Web Algorithms.
Set the key_ops
property of jwk to equal the
usages attribute of key.
Set the ext
property of jwk to equal the
extractable attribute of
key.
Let stringifiedJwk be the result of encoding jwk into a string according to the grammer specified in Section 15.12 of ECMA262.
Let data be the UTF-8 encoding of stringifiedJwk.
Let keyData be a new ArrayBuffer containing data.
Return data.
Let normalizedAlgorithm be the result of normalizing algorithm to AesDerivedKeyParams.
If any of the members of
AesDerivedKeyParams are not present in
normalizedDerivedKeyAlgorithm,
then return an error named
SyntaxError
.
If the length property of
normalizedDerivedKeyAlgorithm is not 128, 192 or 256,
then return an error named
DataError
.
Return the length property of normalizedDerivedKeyAlgorithm.
This section is non-normative.
The "AES-KW"
algorithm identifier is used to perform
key wrapping using AES, as
described in [RFC3394].
The recognized algorithm name for
this algorithm is "AES-KW"
.
Operation | Parameters | Result |
---|---|---|
wrapKey | None | ArrayBuffer |
unwrapKey | None | ArrayBuffer |
generateKey | AesKeyGenParams | Key |
importKey | None | Key |
exportKey | None | ArrayBuffer |
get key length | AesDerivedKeyParams | Integer |
If plaintext is not a multiple of 64 bits in length,
then return an error named
DataError
.
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 return an error named
OperationError
.
Return plaintext.
Let normalizedAlgorithm be the result of normalizing algorithm to AesKeyGenParams.
If any of the members of AesKeyGenParams are
not present in normalizedAlgorithm,
then return an error named
SyntaxError
.
If the length property of
normalizedAlgorithm is not equal to one of
128, 192 or 256,
then return an error named
DataError
.
If usages contains any entry which is not
one of "wrapKey"
or "unwrapKey"
,
then return an error named
DataError
.
If the key generation step fails,
then return an error named
OperationError
.
Let key be a new Key object representing the generated AES key.
Let algorithm be a new AesKeyAlgorithm.
Set the name attribute of
algorithm to "AES-KW"
.
Set the length attribute of algorithm to equal the length property of normalizedAlgorithm.
Set the algorithm attribute of key to algorithm.
Set the extractable attribute of key to be extractable.
Set the usages attribute of key to be usages.
Return key.
If usages contains an entry which is not
one of "wrapKey"
or "unwrapKey"
,
then return an error named
DataError
.
"raw"
:Let data be the octet string contained in keyData.
If the length in bits of data is not 128, 192 or 256
then return an error named
DataError
.
"jwk"
:Let jwk be the result of running the parse a jwk algorithm over keyData.
If the "kty"
field of jwk is not
"oct"
,
then return an error named
DataError
.
If jwk does not meet the requirements of
Section 6.4 of JSON Web Algorithms,
then return an error named
DataError
.
Let data be the octet string obtained by decoding the
"k"
field of jwk.
"alg"
field of jwk is present, and is
not "A128KW"
,
then return an error named
DataError
."alg"
field of jwk is present, and is
not "A192KW"
,
then return an error named
DataError
."alg"
field of jwk is present, and is
not "A256KW"
,
then return an error named
DataError
.DataError
.
If the "use"
field of jwk is present, and is
not "enc"
,
then return an error named
DataError
.
If the "key_ops"
field of jwk is present, and
is invalid according to the requirements of
JSON Web Key or
does not contain all of the specified usages values,
then return an error named
DataError
.
If the "ext"
field of jwk is present and
has the value false and extractable is true,
then return an error named
DataError
.
NotSupportedError
.
Let key be a new Key object representing an AES key with value data.
Let algorithm be a new AesKeyAlgorithm.
Set the name attribute of
algorithm to "AES-KW"
.
Set the length attribute of algorithm to the length, in bits, of data.
Set the algorithm attribute of key to algorithm.
Set the extractable attribute of key to extractable.
Set the usages attribute of key to the normalized value of usages.
Return key.
"raw"
:"jwk"
:Let jwk be a new internal object.
Set the kty
property of jwk to the
string "oct"
.
Set the k
property of jwk to be a string
containng the raw octets
of the key represented by key, encoded according to
Section 6.4 of JSON Web Algorithms.
Set the key_ops
property of jwk to equal the
usages attribute of key.
Set the ext
property of jwk to equal the
extractable attribute of
key.
Let stringifiedJwk be the result of encoding jwk into a string according to the grammer specified in Section 15.12 of ECMA262.
Let data be the UTF-8 encoding of stringifiedJwk.
Return a new ArrayBuffer containing data.
Let normalizedAlgorithm be the result of normalizing algorithm to AesDerivedKeyParams.
If any of the members of
AesDerivedKeyParams are not present in
normalizedDerivedKeyAlgorithm,
then return an error named
SyntaxError
.
If the length member of
normalizedDerivedKeyAlgorithm is not 128, 192 or 256,
then return an error named
DataError
.
Return the length member of normalizedDerivedKeyAlgorithm.
This section is non-normative.
The HMAC
algorithm calculates and verifies hash-based message
authentication codes according to [FIPS PUB 198-1].
The recognized algorithm name for
this algorithm is "HMAC"
.
Operation | Parameters | Result |
---|---|---|
sign | None | ArrayBuffer |
verify | None | boolean |
generateKey | HmacKeyGenParams | Key |
importKey | HmacImportParams | Key |
exportKey | None | ArrayBuffer |
get key length | HmacDerivedKeyParams | Integer |
dictionary HmacImportParams : Algorithm {
// The inner hash function to use.
AlgorithmIdentifier hash;
};
interface HmacKeyAlgorithm : KeyAlgorithm {
// The inner hash function to use.
readonly attribute KeyAlgorithm hash;
};
dictionary HmacKeyGenParams : Algorithm {
// The inner hash function to use.
AlgorithmIdentifier hash;
// The length (in bits) of the key to generate. If unspecified, the
// recommended length will be used, which is the size of the associated hash function's block
// size.
[EnforceRange] unsigned long length;
};
dictionary HmacDerivedKeyParams : HmacImportParams {
// The length (in bits) of the key to generate. If unspecified, the
// recommended length will be used, which is the size of the associated hash function's block
// size.
[EnforceRange] unsigned long length;
};
Let mac be the result of performing the MAC Generation operation described in Section 4 of [FIPS PUB 198-1] using the key represented by key, the hash function identified by the hash attribute of the algorithm attribute 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 PUB 198-1] using the key represented by key, the hash function identified by the hash attribute of the algorithm attribute of key and message as the input data text.
Return true if mac is equal to signature and false otherwise.
Let normalizedAlgorithm be the result of normalizing algorithm to HmacKeyGenParams.
If the hash member is
not present in normalizedAlgorithm, then
return an error named
SyntaxError
.
DataError
.
If usages contains any entry which is not
"sign"
or "verify"
,
then return an error named
DataError
.
Generate a key of length length bits.
If the key generation step fails,
then return an error named
OperationError
.
Let key be a new Key object representing the generated key.
Let algorithm be a new HmacKeyAlgorithm.
Set the name attribute of
algorithm to "HMAC"
.
Let hash be a new KeyAlgorithm.
Set the name attribute of hash to equal the name member of the hash member of normalizedAlgorithm.
Set the hash attribute of algorithm to hash.
Set the algorithm attribute of key to algorithm.
Set the extractable attribute of key to be extractable.
Set the usages attribute of key to be usages.
Return key.
If usages contains an entry which is not
"sign"
or "verify"
,
then return an error named
DataError
.
Let hash be a new KeyAlgorithm.
"raw"
:Let data be the octet string contained in keyData.
If the length in bits of data is zero
then return an error named
DataError
.
SyntaxError
.
"jwk"
:Let jwk be the result of running the parse a jwk algorithm over keyData.
If the "kty"
field of jwk is not
"oct"
,
then return an error named
DataError
.
If jwk does not meet the requirements of
Section 6.4 of JSON Web Algorithms,
then return an error named
DataError
.
Let data be the octet string obtained by decoding the
"k"
field of jwk.
Set the name attribute of hash to equal the name member of the hash member of normalizedAlgorithm.
"SHA-1"
:
"alg"
field of jwk is present
and is not "HS1"
,
then return an error named
DataError
.
"SHA-256"
:
"alg"
field of jwk is present
and is not "HS256"
,
then return an error named
DataError
.
"SHA-384"
:
"alg"
field of jwk is present
and is not "HS384"
,
then return an error named
DataError
.
"SHA-512"
:
"alg"
field of jwk is present
and is not "HS512"
,
then return an error named
DataError
.
DataError
.
If the alg
field of jwk is not present,
then return an error named
DataError
.
"alg"
field of jwk is
"HS1"
:
"SHA-1"
.
"alg"
field of jwk is
to "HS256"
:
"SHA-256"
.
"alg"
field of jwk is
"HS384"
:
"SHA-384"
.
"alg"
field of jwk is
"HS512"
:
"SHA-512"
.
DataError
.
If the "use"
field of jwk is present, and is
not "sign"
,
then return an error named
DataError
.
If the "key_ops"
field of jwk is present, and
is invalid according to the requirements of
JSON Web Key or
does not contain all of the specified usages values,
then return an error named
DataError
.
If the "ext"
field of jwk is present and
has the value false and extractable is true,
then return an error named
DataError
.
NotSupportedError
.
Let key be a new Key
object representing an HMAC key with value data.
Let algorithm be a new HmacKeyAlgorithm.
Set the name attribute of
algorithm to "HMAC"
.
Set the hash attribute of algorithm to hash.
Set the algorithm attribute of key to algorithm.
Set the extractable attribute of key to extractable.
Set the usages attribute of key to the normalized value of usages.
Return key.
"raw"
:"jwk"
:Let jwk be a new internal object.
Set the kty
property of jwk to the
string "oct"
.
Set the k
property of jwk to be a string
containng the raw octets
of the key represented by key, encoded according to
Section 6.4 of JSON Web Algorithms.
Let algorithm be the algorithm attribute of key.
Let hash be the hash attribute of algorithm.
"SHA-1"
:alg
property of jwk to
the string "HS1"
."SHA-256"
:alg
property of jwk to
the string "HS256"
."SHA-384"
:alg
property of jwk to
the string "HS384"
."SHA-512"
:alg
property of jwk to
the string "HS512"
.
Set the key_ops
property of jwk to equal the
usages attribute of key.
Set the ext
property of jwk to equal the
extractable attribute of
key.
Let stringifiedJwk be the result of encoding jwk into a string according to the grammer specified in Section 15.12 of ECMA262.
Let data be the UTF-8 encoding of stringifiedJwk.
Return a new ArrayBuffer containing data.
Let normalizedAlgorithm be the result of normalizing algorithm to HmacImportParams.
If the hash member is
not present in normalizedDerivedKeyAlgorithm, then
return an error named
SyntaxError
.
DataError
.
Return length.
This section is non-normative.
This describes using Diffie-Hellman for key generation and key agreement, as specified by PKCS #3.
The recognized algorithm name for
this algorithm is "DH"
.
Operation | Parameters | Result |
---|---|---|
generateKey | DhKeyGenParams | KeyPair |
deriveBits | DhKeyDeriveParams | Octet string |
importKey | DhImportKeyParams | Key |
exportKey | None | ArrayBuffer |
dictionary DhKeyGenParams : Algorithm {
// The prime p.
BigInteger prime;
// The base g.
BigInteger generator;
};
[NoInterfaceObject]
interface DhKeyAlgorithm : KeyAlgorithm {
// The prime p.
readonly attribute BigInteger prime;
// The base g.
readonly attribute BigInteger generator;
};
dictionary DhImportKeyParams : Algorithm {
// The prime p.
BigInteger prime;
// The base g.
BigInteger generator;
};
Let normalizedAlgorithm be the result of normalizing algorithm to DhKeyGenParams.
If any of the members of DhKeyGenParams are
not present in normalizedAlgorithm,
then return an error named
SyntaxError
.
If usages contains a value which is not
one of "deriveKey"
or "deriveBits"
,
then return an error named
DataError
.
Generate a Diffie-Hellman key pair, as defined in Section 7 of [PKCS #3], with prime, p, and base, g, as specified in the prime and generator properties of normalizedAlgorithm, respectively.
If performing the operation results in an error,
then return an error named
OperationError
.
Let algorithm be a new DhKeyAlgorithm object.
Set the name member of
algorithm to "DH"
.
Set the prime attribute of algorithm to equal the prime member of normalizedAlgorithm.
Set the generator attribute of algorithm to equal the generator member of normalizedAlgorithm.
Let publicKey be a new Key object representing the public key of the generated key pair.
Set the type attribute of publicKey
to "public"
Set the algorithm attribute of publicKey to be algorithm.
Set the extractable attribute of publicKey to true.
Set the usages attribute of publicKey to be the empty list.
Let privateKey be a new Key object representing the private key of the generated key pair.
Set the type attribute of privateKey
to "private"
Set the algorithm attribute of privateKey to be algorithm.
Set the extractable attribute of privateKey to extractable.
Set the usages attribute of privateKey to be usages.
Let result be a new KeyPair object.
Set the publicKey attribute of result to be publicKey.
Set the privateKey attribute of result to be privateKey.
Return result.
If the type attribute of key
is not "private"
, then
return an error named
InvalidAccessError
.
Let normalizedAlgorithm be the result of normalizing algorithm to DhKeyDeriveParams.
If any of the members of DhKeyDeriveParams are not present in
normalizedAlgorithm,
then return an error named
SyntaxError
.
Let publicKey be the public member of normalizedAlgorithm.
If the name attribute of the
algorithm attribute of publicKey is
not "DH"
,
then return an error named
DataError
.
If the type attribute of publicKey
is not
"public"
,
then return an error named
DataError
.
If the prime attribute of the
algorithm attribute of publicKey
is not equal to the prime attribute of the
algorithm attribute of key,
then return an error named
DataError
.
If the generator attribute of the
algorithm attribute of publicKey
is not equal to the generator
attribute of the
algorithm attribute of key,
then return an error named
DataError
.
Perform the Diffie Hellman Phase II algorithm as specified in Section 8 of [PKCS #3] with key as the DH private value x and the Diffie Hellman public value represented by the public member of normalizedAlgorithm as the other's public value PV'.
OperationError
.
DataError
.
"raw"
:
Raw import of private values is presently not supported.
Let normalizedAlgorithm be the result of normalizing algorithm to DhImportKeyParams.
If any of the members of DhImportKeyParams are not present in
normalizedAlgorithm,
then return an error named
SyntaxError
.
If extractable is false,
then return an error named
DataError
.
Let PV be the integer which results from interpreting the octets of keyData as an unsigned big integer with most significant octet first.
Let key be a new Key object representing a Diffie-Hellman public key with public value PV and with prime, p and base, g equal to the prime and generator properties of normalizedAlgorithm respectively.
Set the type attribute of key to
"public"
.
Let algorithm be a new DhKeyAlgorithm.
Set the name attribute of
algorithm to "DH"
.
Set the prime attribute of algorithm to equal the prime member of normalizedAlgorithm.
Set the generator attribute of algorithm to equal the generator member of normalizedAlgorithm.
Set the algorithm attribute of key to algorithm.
Set the extractable attribute of key to extractable.
Set the usages attribute of key to usages.
Return key.
"spki"
:
Let spki be the result of running the parse a subjectPublicKeyInfo algorithm over keyData.
If an error occured while parsing,
then return an error named
DataError
.
If the algorithm
object identifier field of the
algorithm
AlgorithmIdentifier field of spki is not
equivalent to the dhKeyAgreement
OID defined in Section 9
of [PKCS #3],
then return an error named
DataError
.
If the parameters
field of the algorithm
AlgorithmIdentifier field of spki is absent,
then return an error named
DataError
.
Let params be the parameters
field of the
algorithm
AlgorithmIdentifier field of spki.
If params is not an instance of the DHParameter
ASN.1 type defined in Section 9 of PKCS #3,
then return an error named
DataError
.
Let key be a new Key object representing
the Diffie-Hellman public key obtained by parsing the
subjectPublicKey
field of spki as an ASN.1
INTEGER.
Set the type propety of key to
"public"
.
Let algorithm be a new DhKeyAlgorithm.
Set the name member of
algorithm to "DH"
.
Set the prime attribute of
algorithm to a new BigInteger
equal to the
octet string encoding of the prime
field of
params.
Set the generator attribute of
algorithm to a new BigInteger
equal to the
octet string encoding of the base
field of
params.
Set the algorithm attribute of key to algorithm.
Set the extractable attribute of key to extractable.
Set the usages attribute of key to the normalized value of usages.
Return key.
"pkcs8"
:
If usages contains a value which is not
one of "deriveKey"
or "deriveBits"
,
then return an error named
DataError
.
Let privateKeyInfo be the result of running the parse a privateKeyInfo algorithm over keyData.
If an error occurred while parsing,
then return an error named
OperationError
.
If the algorithm
object identifier field of the
algorithm
AlgorithmIdentifier field of
privateKeyInfo is not
equivalent to the dhKeyAgreement
OID defined in Section 9
of [PKCS #3],
then return an error named
DataError
.
If the parameters
field of the
privateKeyAlgorithm
PrivateKeyAlgorithmIdentifier field of
privateKeyInfo is absent,
then return an error named
DataError
.
Let params be the parameters
field of the
privateKeyAlgorithm
PrivateKeyAlgorithmIdentifier field of
privateKeyInfo.
If params is not an instance of the DHParameter
ASN.1 type defined in Section 9 of PKCS #3,
then return an error named
DataError
.
privateKey
field of privateKeyInfo as an ASN.1
INTEGER.
Set the type attribute of key to
"private"
.
Let algorithm be a new DhKeyAlgorithm.
Set the name member of
algorithm to "DH"
.
Set the prime attribute of
algorithm to a new BigInteger
equal to the
octet string encoding of the prime
field of
params.
Set the generator attribute of
algorithm to a new BigInteger
equal to the
octet string encoding of the base
field of
params.
Set the algorithm attribute of key to algorithm.
Set the extractable attribute of key to extractable.
Set the usages attribute of key to the normalized value of usages.
Return key.
NotSupportedError
.
"raw"
:
"public"
:
"private"
:
"spki"
:
If the type attribute of key is
not "public"
, then
return an error named
InvalidAccessError
.
Let result be the result of encoding a subjectPublicKeyInfo with the following properties:
Set the algorithmIdentifier field to an
AlgorithmIdentifier
ASN.1 structure with the
following properties:
Set the subjectPublicKey to an ASN.1 INTEGER that corresponds to the Diffie-Hellman public value represented by key.
"pkcs8"
:
If the type attribute of key is
not "private"
, then
return an error named
InvalidAccessError
.
Let result be the result of encoding a privateKeyInfo with the following properties:
Set the privateKeyAlgorithm field to a
PrivateKeyAlgorithmIdentifier
ASN.1 structure with
the following properties:
Set the privateKey field to an ASN.1 INTEGER that corresponds to the Diffie-Hellman private value represented by key.
NotSupportedError
.
Let data be a new ArrayBuffer
containing
result.
Return data.
This describes the SHA-1 and SHA-2 families, as specified by [FIPS PUB 180-4].
The following algorithms are added as recognized algorithm names:
"SHA-1"
"SHA-256"
"SHA-384"
"SHA-512"
Operation | Parameters | Result |
---|---|---|
digest | None | ArrayBuffer |
Let normalizedAlgorithm be the result of normalizing algorithm to Algorithm.
"SHA-1"
:
"SHA-256"
:
"SHA-384"
:
"SHA-512"
:
Return a new ArrayBuffer containing result.
The "CONCAT"
algorithm identifier is used to perform key derivation
using the key derivation algorithm defined in Section 5.8.1 of NIST SP 800-56A
[SP800-56A].
The recognized algorithm name for
this algorithm is "CONCAT"
.
Operation | Parameters | Result |
---|---|---|
deriveBits | ConcatParams | Octet string |
Import key | None | Key |
Get key length | None | Integer or null |
dictionary ConcatParams : Algorithm {
// The digest method to use to derive the keying material.
AlgorithmIdentifier hash;
// A bit string corresponding to the AlgorithmId field of the OtherInfo parameter.
// The AlgorithmId indicates how the derived keying material will be parsed and for which
// algorithm(s) the derived secret keying material will be used.
CryptoOperationData algorithmId;
// A bit string that corresponds to the PartyUInfo field of the OtherInfo parameter.
CryptoOperationData partyUInfo;
// A bit string that corresponds to the PartyVInfo field of the OtherInfo parameter.
CryptoOperationData partyVInfo;
// An optional bit string that corresponds to the SuppPubInfo field of the OtherInfo parameter.
CryptoOperationData? publicInfo;
// An optional bit string that corresponds to the SuppPrivInfo field of the OtherInfo parameter.
CryptoOperationData? privateInfo;
};
Let normalizedAlgorithm be the result of normalizing algorithm to ConcatParams.
If any of the
hash,
algorithmId,
partyUInfo or
partyVInfo properties are not
present in normalizedAlgorithm, then
return an error named
SyntaxError
.
Let secret be the result of performing the Concatenation Key Derivation Funtion defined in Section 5.8.1 of [SP800-56A] with length as keydatalen, the hash function identified by the hash member of normalizedAlgorithm as H, the algorithmId member of normalizedAlgorithm as AlgorithmID, the partyUInfo member of normalizedAlgorithm as PartyUInfo, the partyVInfo member of normalizedAlgorithm as PartyVInfo, the publicInfo member of normalizedAlgorithm, if present and not null, as publicInfo and the privateInfo member of normalizedAlgorithm, if present and not null, as privateInfo.
If the operation fails,
then return an error named
OperationError
.
Return secret
"raw"
:
If usages contains a value that is not
"deriveKey"
or "deriveBits"
,
then return an error named
DataError
.
Let key be a new Key object representing the key data provided in keyData.
Set the type attribute of key to
"secret"
.
Let algorithm be a new KeyAlgorithm object.
Set the name attribute of
algorithm to "CONCAT"
.
Set the algorithm attribute of key to algorithm.
Set the extractable attribute of key to extractable.
Set the usages attribute of key to the normalized value of usages.
Return key.
NotSupportedError
.
Return null.
This section is non-normative.
The "HKDF-CTR"
algorithm identifier is used to
perform key derivation using the extraction-then-expansion approach described in
NIST SP 800-56C[SP800-56C], using HMAC in counter mode,
as described in Section 5.1 of NIST SP 800-108
[SP800-108].
The recognized algorithm name
for this algorithm is "HKDF-CTR"
.
Operation | Parameters | Result |
---|---|---|
deriveBits | HkdfCtrParams | ArrayBuffer |
Import key | None | Key |
Get key length | None | Integer or null |
dictionary HkdfCtrParams : Algorithm {
// The algorithm to use with HMAC (eg: SHA-256)
AlgorithmIdentifier hash;
// A bit string that corresponds to the label that identifies the purpose for the derived keying material.
CryptoOperationData label;
// A bit string that corresponds to the context of the key derivation, as described in Section 5 of NIST SP 800-108 [SP800-108]
CryptoOperationData context;
};
The definition of HKDF allows the caller to supply an optional pseudorandom salt value, which is used as the key during the extract phase. If this value is not supplied, an all zero string is used instead. However, support for an explicit salt value is not widely implemented in existing APIs, nor is it required by existing usages of HKDF. Should this be an optional parameter, and if so, what should the behaviour be of a user agent that does not support explicit salt values (is it conforming or non-conforming?)
If length is null,
then return an error named
DataError
.
Let normalizedAlgorithm be the result of normalizing algorithm to HkdfCtrParams.
If any of the members of HkdfCtrParams are
not present in normalizedAlgorithm,
then return an error named
SyntaxError
.
If the hash member of
normalizedAlgorithm does not describe a
recognised algorithm that supports the digest operation, then
return an error named
NotSupportedError
Let extractKey be a key equal to n zero bits where n is the size of the output of the hash fuction described by the hash member of normalizedAlgorithm.
Let prf be the MAC Generation function described in Section 4 of [FIPS PUB 198-1] using the hash function described by the hash member of normalizedAlgorithm.
Let keyDerivationKey be the result of performing prf using extractKey as the key and the secret represented by key as the message.
Let result be the result of performing the KDF in counter mode operation described in Section 5.1 of NIST SP 800-108 [SP800-108] using:
prf as the Pseudo-Random Function, PRF,
keyDerivationKey as the Key derivation key, KI,
the contents of the label member of normalizedAlgorithm as Label,
the contents of the context member of normalizedAlgorithm as Context,
length as the value of L,
32 as the value of r, and
the 32-bit little-endian binary encoding of length as the encoded length value [L]2.
If the key derivation operation fails,
then return an error named
OperationError
.
Return result.
"raw"
:
If usages contains a value that is not
"deriveKey"
or "deriveBits"
,
then return an error named
DataError
.
Let key be a new Key object representing the key data provided in keyData.
Set the type attribute of key to
"secret"
.
Let algorithm be a new KeyAlgorithm object.
Set the name attribute of
algorithm to "HKDF-CTR"
.
Set the algorithm attribute of key to algorithm.
Set the extractable attribute of key to extractable.
Set the usages attribute of key to the normalized value of usages.
Return key.
NotSupportedError
.
Return null.
This section is non-normative.
The "PBKDF2"
algorithm identifier is used to
perform key derivation using the PKCS#5 password-based key
derivation function version 2.0, as defined in
[RFC2898] using HMAC as the pseudo-random function.
The recognized algorithm name for
this algorithm is "PBKDF2"
.
Operation | Parameters | Result |
---|---|---|
generateKey | None | Key |
deriveBits | Pbkdf2Params | ArrayBuffer |
importKey | None | Key |
Get key length | None | Length or null |
dictionary Pbkdf2Params : Algorithm {
CryptoOperationData salt;
[EnforceRange] unsigned long iterations;
AlgorithmIdentifier hash;
};
In the above snippet, password
is an optional field. The intent is
that conforming user agents MAY support applications
that wish to use PBKDF2 by providing password entry via an un-spoofable (by the
web application) UI.
Let normalizedAlgorithm be the result of normalizing algorithm to Pbkdf2Params.
If any of the members of Pbkdf2Params are
not present in normalizedAlgorithm,
then return an error named
SyntaxError
.
If length is null or is not a multiple of 8,
then return an error named
DataError
.
If the hash member of
normalizedAlgorithm does not describe a
recognised algorithm that supports the digest operation, then
return an error named
NotSupportedError
Let prf be the MAC Generation function described in Section 4 of [FIPS PUB 198-1] using the hash function described by the hash member of normalizedAlgorithm.
Let result be the result of performing the PBKDF2 operation defined in Section 5.2 of [RFC2898] using prf as the pseudo-random function, PRF, the password represented by key as the password, P, the contents of the salt attribute of normalizedAlgorithm as the salt, S, the value of the iterations attribute of normalizedAlgorithm as the iteration count, c, and length divided by 8 as the intended key length, dkLen.
If the key derivation operation fails,
then return an error named
OperationError
.
Return result
If usages contains any element that is not
"deriveKey"
,
then return an error named
DataError
.
If extractable is true,
then return an error named
DataError
.
Generate a new password by prompting the user.
Let key be a new Key object representing the provided password, encoded using UTF-8.
Set the type attribute of key to
"secret"
.
Let algorithm be a new KeyAlgorithm object.
Set the name attribute of
algorithm to "PBKDF2"
.
Set the algorithm attribute of key to algorithm.
Set the extractable attribute of key to extractable.
Set the usages attribute of key to the normalized value of usages.
Return key.
If format is not
"raw"
,
return an error named
NotSupportedError
If usages contains any element that is not
"deriveKey"
,
then return an error named
DataError
.
Let key be a new Key object representing keyData.
Set the type attribute of key to
"secret"
.
Let algorithm be a new KeyAlgorithm object.
Set the name attribute of
algorithm to "PBKDF2"
.
Set the algorithm attribute of key to algorithm.
Set the extractable attribute of key to extractable.
Set the usages attribute of key to the normalized value of usages.
Return key.
Return null.
The AlgorithmIdentifier typedef permits algorithms to be specified as either an Algorithm dictionary or a DOMString. The DOMString option permits algorithms to be specified using shorthand 'aliases'. Algorithms may define aliases and the values they correspond to. Using an alias is exactly equivalent to using the value corresponding to the alias.
Additionally, many algorithms define a subclass of the Algorithm type. As a result WebIDL type mapping to the correct subclass must be performed at the appropriate time.
When this specification says that a value algorithm be normalized to type the user agent must perform the following steps:
Let mappedAlgorithm be the result of mapping algorithm to the AlgorithmIdentifier type as specified in [WEBIDL].
If mappedAlgorithm contains any non-ASCII characters,
return an error named
SyntaxError
.
Convert every character in mappedAlgorithm to lower case.
If mappedAlgorithm is equal to a recognized algorithm alias then let objectAlgorithm be the value defined to be equivalent to this alias.
Otherwise, return an error named
SyntaxError
.
Let result be the result of mapping objectAlgorithm to type as specified in [WEBIDL].
If a member, memberName, of type has a type that is a union of DOMString and a type, memberType, that is either Algorithm or a subclass of Algorithm and if the memberName member of result is present and has type DOMString, then replace memberName in result with the result of normalizing the memberName member of result to memberType.
Return result.
// Algorithm Object
var algorithmKeyGen = {
name: "RSASSA-PKCS1-v1_5",
// RsaHashedKeyGenParams
modulusLength: 2048,
publicExponent: new Uint8Array([0x01, 0x00, 0x01]), // Equivalent to 65537
hash: {
name: "SHA-256",
}
};
var algorithmSign = {
name: "RSASSA-PKCS1-v1_5"
};
window.crypto.subtle.generateKey(algorithmKeyGen, false, ["sign"]).then(
function(key) {
var dataPart1 = convertPlainTextToArrayBufferView("hello,");
var dataPart2 = convertPlainTextToArrayBufferView(" world!");
// TODO: create example utility function that converts text -> ArrayBufferView
return window.crypto.subtle.sign(algorithmSign, key.privateKey, [dataPart1, dataPar2]);
},
console.error.bind(console, "Unable to generate a key")
).then(
console.log.bind(console, "The signature is: "),
console.error.bind(console, "Unable to sign")
);
var clearDataArrayBufferView = convertPlainTextToArrayBufferView("Plain Text Data");
// TODO: create example utility function that converts text -> ArrayBufferView
var aesAlgorithmKeyGen = {
name: "AES-CBC",
// AesKeyGenParams
length: 128
};
var aesAlgorithmEncrypt = {
name: "AES-CBC",
// AesCbcParams
iv: window.crypto.getRandomValues(new Uint8Array(16))
};
// Create a keygenerator to produce a one-time-use AES key to encrypt some data
window.crypto.subtle.generateKey(aesAlgorithmKeyGen, false, ["encrypt"]).then(
function(aesKey) {
return window.crypto.subtle.encrypt(aesAlgorithmEncrypt, aesKey, [ clearDataArrayBufferView ]);
}
).then(console.log.bind(console, "The ciphertext is: "),
console.error.bind(console, "Unable to encrypt"));
This section registers the following algorithm identifiers in the IANA JSON Web Signature and Encryption Algorithms Registry for use with JSON Web Key. Note that the 'Implementation Requirements' field in the template refers to use with JSON Web Signature and JSON Web Encryption specifically, in which case use of unauthenticated encryption is prohibited.
The editors would like to thank Adam Barth, Alex Russell, Ali Asad, Arun Ranganathan, Brian Smith, Brian Warner, Channy Yun, Eric Roman, Glenn Adams, Jim Schaad, Kai Engert, Mark Watson, Michael Hutchinson, Michael Jones, Nick Van den Bleeken, Richard Barnes, Vijay Bharadwaj, Virginie Galindo, and Wan-Teh Chang for their technical feedback and assistance.
Thanks to the W3C Web Cryptography WG, and to participants on the public-webcrypto@w3.org mailing list.
The W3C would like to thank the Northrop Grumman Cybersecurity Research Consortium for supporting W3C/MIT.
The getRandomValues
method in the Crypto
interface was originally proposed by Adam Barth to the
WHATWG.
The following section is non-normative. Refer to algorithm-specific sections for the normative requirements of importing and exporting JWK.
JSON Web Key | AlgorithmIdentifier |
---|---|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
ECMAScript
|
Should the following be specified.
RSASSA-PKCS1-v1_5 with SHA-1
RSA-PSS with SHA-1
RSA-OAEP needs specifiers for the hash algorithms.
ECDSA with SHA-1
ECDSA where the curve (P-256, P-384, P-521) is not aligned with the hash (SHA-256, SHA-384, SHA-512)
JWK use value |
KeyUsages |
---|---|
enc |
["encrypt", "decrypt", "wrapKey", "unwrapKey"] |
sig |
["sign","verify"] |
The following section is non-normative. Refer to algorithm-specific sections for the normative requirements of importing and exporting SPKI.
Algorithm OID | subjectPublicKey ASN.1 structure | AlgorithmIdentifier | Reference |
---|---|---|---|
rsaEncryption (1.2.840.113549.1.1.1) | RSAPublicKey |
"RSAES-PKCS1-v1_5" ,
"RSASSA-PKCS1-v1_5" ,
"RSA-PSS" , or
"RSA-OAEP"
|
RFC 3279, RFC 4055, RFC 5756 |
id-RSASSA-PSS (1.2.840.113549.1.1.10) | RSAPublicKey | "RSA-PSS" |
RFC 4055, RFC 5756 |
id-RSAES-OAEP (1.2.840.113549.1.1.7) | RSAPublicKey | "RSA-OAEP" |
RFC 4055, RFC 5756 |
id-ecPublicKey (1.2.840.10045.2.1) | ECPoint | "ECDH" or "ECDSA" |
RFC 5480 |
id-ecDH (1.3.132.112) | ECPoint | "ECDH" |
RFC 5480 |
id-dsa (1.2.840.10040.4.1) | DSAPublicKey | "DSA" |
RFC 3279 |
dhKeyAgreement (1.2.840.113549.1.3.1) | INTEGER | "DH" |
PKCS #3 |
The handling of "id-RSASSA-PSS" and "id-RSAES-OAEP" are tricky. RFC 5756 recommends implementations should not include parameters when PSS is used with a subjectPublicKeyInfo, and MUST NOT include parameters when OAEP is used. However, when OAEP is used as part of a key transport (as an AlgorithmIdentifier), implementations MUST include the parameters.
The natural conflict is in deciding when a key is being exported as part of a subjectPublicKeyInfo (which is what "spki" implies) and when it's being used as an algorithmIdentifier for transport.
The following section is non-normative. Refer to algorithm-specific sections for the normative requirements of importing and exporting PKCS#8 PrivateKeyInfo.
privateKeyAlgorithm | privateKey format | AlgorithmIdentifier | Reference |
---|---|---|---|
rsaEncryption (1.2.840.113549.1.1.1) | RSAPrivateKey |
"RSAES-PKCS1-v1_5" ,
"RSASSA-PKCS1-v1_5" ,
"RSA-PSS" , or
"RSA-OAEP"
|
RFC 3447, RFC 5958 |
id-RSASSA-PSS (1.2.840.113549.1.1.10) | RSAPrivateKey | "RSA-PSS" |
RFC 3447, RFC 4055, RFC 5958 |
id-RSAES-OAEP (1.2.840.113549.1.1.7) | RSAPrivateKey | "RSA-OAEP" |
RFC 3447, RFC 4055, RFC 5958 |
id-ecPublicKey (1.2.840.10045.2.1) | ECPrivateKey | "ECDH" or "ECDSA" |
RFC 5480, RFC 5915, RFC 5958 |
id-ecDH (1.3.132.112) | ECPrivateKey | "ECDH" |
RFC 5480, RFC 5915, RFC 5958 |
id-dsa (1.2.840.10040.4.1) | INTEGER | "DSA" |
RFC 5958 |
dhKeyAgreement (1.2.840.113549.1.3.1) | INTEGER | "DH" |
PKCS #3 |
There does not appear to be a normative reference for a DH key being encoded as an INTEGER. Only RFC 5958 seems to mention this.