Copyright © 2024 the Contributors to the Modern Algorithms in the Web Cryptography API Specification, published by the Web Platform Incubator Community Group under the W3C Community Contributor License Agreement (CLA). A human-readable summary is available.
This specification defines a number of modern cryptographic algorithms for the Web Cryptography API, namely AES-OCB, ChaCha20-Poly1305, SHA-3, cSHAKE, KMAC, and Argon2.
This specification was published by the Web Platform Incubator Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.
This is an unofficial proposal.
GitHub Issues are preferred for discussion of this specification.
This section is non-normative.
This proposal aims to modernize the set of cryptographic algorithms available in the Web Cryptography API, such that web applications can make use of the most secure and performant options available. To this end, the following cryptographic algorithms are added:
Additionally, this proposal aims to make feature detection easier,
by adding a SubtleCrypto.supports function,
which can be used to detect whether a given algorithm identifier
(including any parameters) is supported for the given operation.
This specification follows the conventions laid out in Section 18.3 of [WebCryptoAPI]. None of the algorithms defined here are required to be implemented, but if a conforming User Agent implements an algorithm, it MUST implement all of the supported operations specified in this document, and must perform the steps to define an algorithm specified in section 18.4.3 of [WebCryptoAPI] for each of the supported operations.
An octet string is an ordered sequence of zero or more integers, each in the range 0 to 255 inclusive.
When this specification states to supply the contents of an ArrayBuffer named data to an underlying cryptographic implementation, the User Agent shall supply a contiguous sequence of bytes that is equal to the result of getting a copy of the bytes held data.
This section extends the SubtleCrypto interface of [WebCryptoAPI].
WebIDL[SecureContext,Exposed=(Window,Worker)]
partial interface SubtleCrypto {
static boolean supports(DOMString operation,
AlgorithmIdentifier algorithm,
optional unsigned long? length = null);
static boolean supports(DOMString operation,
AlgorithmIdentifier algorithm,
AlgorithmIdentifier additionalAlgorithm);
};
The supports(operation, algorithm, length)
method returns a boolean indicating whether the implementation
supports the given operation using the specified AlgorithmIdentifier,
with an optional length parameter to indicate the number of bits to be derived when operation is "deriveBits".
It behaves as follows:
If operation is not one of
"encrypt", "decrypt", "sign", "verify",
"digest", "generateKey", "deriveKey", "deriveBits",
"importKey", "exportKey", "wrapKey" or "unwrapKey",
return false.
Return the result of checking support for an algorithm,
with op set to operation, alg set to algorithm,
and length set to length.
The supports(operation, algorithm, additionalAlgorithm)
method returns a boolean indicating whether the implementation
supports the given operation using the specified AlgorithmIdentifier.
The additional algorithm indicates the type of key to be derived when operation is "deriveKey",
the type of key to be exported before wrapping when operation is "wrapKey",
and the type of key to be imported after unwrapping when operation is "unwrapKey".
It behaves as follows:
If operation is not one of
"encrypt", "decrypt", "sign", "verify",
"digest", "generateKey", "deriveKey", "deriveBits",
"importKey", "exportKey", "wrapKey" or "unwrapKey",
return false.
deriveKey":
If the result of checking support for an algorithm
with op set to "importKey"
and alg set to additionalAlgorithm
is false, or
the result of checking support for an algorithm
with op set to "get key length"
and alg set to additionalAlgorithm
is false,
return false.
wrapKey":
If the result of checking support for an algorithm
with op set to "exportKey"
and alg set to additionalAlgorithm
is false,
return false.
unwrapKey":
If the result of checking support for an algorithm
with op set to "importKey"
and alg set to additionalAlgorithm
is false,
return false.
Return the result of checking support for an algorithm,
with op set to operation and alg set to algorithm.
The check support for an algorithm algorithm
defines a process for checking whether the given algorithm is supported for the given operation.
Its input is an operation name op, an AlgorithmIdentifier alg,
and an optional length parameter. Its output is a boolean.
It behaves as follows:
If op is "deriveKey", set op is "deriveBits".
Let normalizedAlgorithm be the result of
normalizing an algorithm, with
alg set to alg and op set to op.
If op is "wrapKey",
return the result of checking support for an algorithm
with op set to "encrypt"
and alg set to alg.
If op is "unwrapKey",
return the result of checking support for an algorithm
with op set to "decrypt"
and alg set to alg.
Otherwise, return false.
If the specified operation or algorithm (or one of its parameter values) is expected to fail (for any key and/or data) for an implementation-specific reason (e.g. known nonconformance to the specification), return false.
If op is "generateKey" or "importKey", let usages be the empty list.
For each of the steps of the operation specified by op of the algorithm specified by normalizedAlgorithm:
key, plaintext or ciphertext:
The steps in the referenced algorithm may access the normalizedAlgorithm, length, and usages variables from this context.
Assert: this step is never reached, because one of the steps of the operation will have said to return a value or throw an error, causing us to return true or false, respectively.
This section is non-normative.
The "AES-OCB" algorithm identifier is used to perform
authenticated encryption and decryption using AES in OCB mode,
as described in [RFC7253].
The recognized algorithm name for
this algorithm is "AES-OCB".
| Operation | Parameters | Result |
|---|---|---|
| encrypt | AeadParams |
ArrayBuffer |
| decrypt | AeadParams |
ArrayBuffer |
| generateKey | AesKeyGenParams |
CryptoKey |
| importKey | None | CryptoKey |
| exportKey | None | object |
| get key length | AesDerivedKeyParams |
Integer |
WebIDLdictionary AeadParams : Algorithm {
required BufferSource iv;
BufferSource additionalData;
[EnforceRange] octet tagLength;
};
The iv member represents the initialization vector to use.
The additionalData member represents the additional authentication data to include.
The tagLength member represents the desired length of the authentication tag.
The AeadParams dictionary is identical to the AesGcmParams dictionary of [WebCryptoAPI],
and the latter may be replaced by the former when merging this proposal.
If the iv member of
normalizedAlgorithm has a length greater than 15
bytes,
then throw an
OperationError.
tagLength member of
normalizedAlgorithm is not present:tagLength member of
normalizedAlgorithm is one of 64, 96 or 128:tagLength member of
normalizedAlgorithmOperationError.
Let additionalData be the contents of the additionalData member of
normalizedAlgorithm if present or the empty octet
string otherwise.
Let C be the output that results from performing
the OCB-ENCRYPT function described in Section 4.2 of
[RFC7253] using AES as the block cipher, using
the key represented by [[handle]]
internal slot of key as the K input parameter,
the contents of the iv member of normalizedAlgorithm as
the N input parameter, the contents of
additionalData as the A input parameter,
the contents of
plaintext as the P input parameter, and
tagLength as the TAGLEN global parameter.
Return the result of creating
an ArrayBuffer containing C.
tagLength member of
normalizedAlgorithm is not present:tagLength member of
normalizedAlgorithm is one of 64, 96 or 128:tagLength member of
normalizedAlgorithmOperationError.
If ciphertext has a length less than tagLength bits,
then throw an
OperationError.
If the iv member of
normalizedAlgorithm has a length greater than 15
bytes,
then throw an
OperationError.
Let additionalData be the contents of the additionalData member of
normalizedAlgorithm if present or the empty octet
string otherwise.
Perform the OCB-DECRYPT function described in Section 4.3 of
[RFC7253] using AES as the block cipher, using
the key represented by [[handle]]
internal slot of key as the K input parameter,
the contents of the iv member of normalizedAlgorithm as
the N input parameter, the contents of
additionalData as the A input parameter,
the contents of
ciphertext as the C input parameter, and
tagLength as the TAGLEN global parameter.
OperationError
Return the result of creating
an ArrayBuffer containing plaintext.
If usages contains any entry which is not
one of "encrypt", "decrypt",
"wrapKey" or "unwrapKey",
then throw a
SyntaxError.
If the length member of
normalizedAlgorithm is not equal to one of
128, 192 or 256,
then throw an
OperationError.
Generate an AES key of length
equal to the length member of
normalizedAlgorithm.
If the key generation step fails,
then throw an
OperationError.
Let key be a new
CryptoKey object representing the
generated AES key.
Let algorithm be a new
AesKeyAlgorithm.
Set the name attribute of
algorithm to "AES-OCB".
Set the length attribute of
algorithm to equal the
length member of
normalizedAlgorithm.
Set the [[algorithm]] internal slot of key to algorithm.
Set the [[extractable]] internal slot of key to be extractable.
Set the [[usages]] internal slot of key to be usages.
Return key.
If usages contains an entry which is not
one of "encrypt", "decrypt",
"wrapKey" or "unwrapKey",
then throw a
SyntaxError.
raw":Let data be the octet string contained in keyData.
If the length in bits of data is not 128, 192 or 256
then throw a
DataError.
jwk":JsonWebKey dictionary:Let jwk equal keyData.
If the kty field of jwk is not
"oct",
then throw a
DataError.
If jwk does not meet the requirements of
Section 6.4 of JSON Web Algorithms [JWA],
then throw a
DataError.
Let data be the octet string obtained by decoding the
k field of jwk.
alg field of jwk is present, and is
not "A128OCB",
then throw a
DataError.alg field of jwk is present, and is
not "A192OCB",
then throw a
DataError.alg field of jwk is present, and is
not "A256OCB",
then throw a
DataError.DataError.
If usages is non-empty and the use field of jwk is present and is
not "enc",
then throw a
DataError.
If the key_ops field of jwk is present, and
is invalid according to the requirements of
JSON Web Key [JWK] or
does not contain all of the specified usages values,
then throw a
DataError.
If the ext field of jwk is present and
has the value false and extractable is true,
then throw a
DataError.
NotSupportedError.
Let key be a new {{CryptoKey}}
object representing an AES key with value data.
Let algorithm be a new
AesKeyAlgorithm.
Set the name attribute of
algorithm to "AES-OCB".
Set the length attribute of
algorithm to the length, in bits, of data.
Set the [[algorithm]] internal slot of key to algorithm.
Return key.
If the underlying cryptographic key material represented by the [[handle]] internal slot of key
cannot be accessed, then throw an OperationError.
raw":Let data be the raw octets of the key represented by [[handle]] internal slot of key.
Let result be the result of creating
an ArrayBuffer containing data.
jwk":
Let jwk be a new JsonWebKey
dictionary.
Set the kty attribute of jwk to the
string "oct".
Set the k attribute of jwk to be a string
containing the raw octets of the key represented by [[handle]] internal slot of
key, encoded according to Section 6.4 of JSON Web Algorithms [JWA].
Set the key_ops attribute of jwk to equal the
usages attribute of
key.
Set the ext attribute of jwk to equal the [[extractable]] internal slot
of key.
Let result be the result of converting jwk to an ECMAScript Object, as defined by [WebIDL].
Return result.
If the length member of
normalizedDerivedKeyAlgorithm is not 128, 192 or 256, then throw an OperationError.
Return the length member of
normalizedDerivedKeyAlgorithm.
This section is non-normative.
The "ChaCha20-Poly1305" algorithm identifier is used to perform
authenticated encryption and decryption using AEAD_CHACHA20_POLY1305,
as described in [RFC8439].
The recognized algorithm name for
this algorithm is "ChaCha20-Poly1305".
| Operation | Parameters | Result |
|---|---|---|
| encrypt | AeadParams |
ArrayBuffer |
| decrypt | AeadParams |
ArrayBuffer |
| generateKey | None | CryptoKey |
| importKey | None | CryptoKey |
| exportKey | None | object |
| get key length | None | Integer |
If the iv member of
normalizedAlgorithm does not have a length of 12 bytes,
then throw an
OperationError.
If the tagLength member
of normalizedAlgorithm is present and is not 128,
then throw an
OperationError.
Let additionalData be the contents of the additionalData member of
normalizedAlgorithm if present or the empty octet
string otherwise.
Let ciphertext be the output that results from
performing the AEAD_CHACHA20_POLY1305 encryption algorithm
described in Section 2.8 of [RFC8439], using
the key represented by [[handle]]
internal slot of key as the key input parameter,
the contents of the iv member of normalizedAlgorithm as
the nonce input parameter,
the contents of
plaintext as the plaintext input parameter, and
the contents of
additionalData as the additional authenticated data (AAD) input parameter.
Return the result of creating
an ArrayBuffer containing ciphertext.
tagLength member of
normalizedAlgorithm is not present:tagLength member of
normalizedAlgorithm is one of 64, 96 or 128:tagLength member of
normalizedAlgorithmOperationError.
If ciphertext has a length less than tagLength bits,
then throw an
OperationError.
If the iv member of
normalizedAlgorithm has a length greater than 15
bytes,
then throw an
OperationError.
Let additionalData be the contents of the additionalData member of
normalizedAlgorithm if present or the empty octet
string otherwise.
Perform the AEAD_CHACHA20_POLY1305 decryption algorithm
described in Section 2.8 of [RFC8439], using
the key represented by [[handle]]
internal slot of key as the key input parameter,
the contents of the iv member of normalizedAlgorithm as
the nonce input parameter,
the contents of
ciphertext as the ciphertext input parameter, and
the contents of
additionalData as the additional authenticated data (AAD) input parameter.
OperationError
Return the result of creating
an ArrayBuffer containing plaintext.
If usages contains any entry which is not
one of "encrypt", "decrypt",
"wrapKey" or "unwrapKey",
then throw a
SyntaxError.
Generate a 256-bit key.
If the key generation step fails,
then throw an
OperationError.
Let key be a new
CryptoKey object representing the
generated key.
Let algorithm be a new
KeyAlgorithm.
Set the name attribute of
algorithm to "ChaCha20-Poly1305".
Set the [[algorithm]] internal slot of key to algorithm.
Set the [[extractable]] internal slot of key to be extractable.
Set the [[usages]] internal slot of key to be usages.
Return key.
If usages contains an entry which is not
one of "encrypt", "decrypt",
"wrapKey" or "unwrapKey",
then throw a
SyntaxError.
raw":Let data be the octet string contained in keyData.
If the length in bits of data is not 256
then throw a
DataError.
jwk":JsonWebKey dictionary:Let jwk equal keyData.
If the kty field of jwk is not
"oct",
then throw a
DataError.
If jwk does not meet the requirements of
Section 6.4 of JSON Web Algorithms [JWA],
then throw a
DataError.
Let data be the octet string obtained by decoding the
k field of jwk.
If the alg field of jwk is present, and is
not "CC20P1305",
then throw a
DataError.
If usages is non-empty and the use field of jwk is present and is
not "enc",
then throw a
DataError.
If the key_ops field of jwk is present, and
is invalid according to the requirements of
JSON Web Key [JWK] or
does not contain all of the specified usages values,
then throw a
DataError.
If the ext field of jwk is present and
has the value false and extractable is true,
then throw a
DataError.
NotSupportedError.
Let key be a new {{CryptoKey}}
object representing a key with value data.
Let algorithm be a new
KeyAlgorithm.
Set the name attribute of
algorithm to "ChaCha20-Poly1305".
Set the [[algorithm]] internal slot of key to algorithm.
Return key.
If the underlying cryptographic key material represented by the [[handle]] internal slot of key
cannot be accessed, then throw an OperationError.
raw":Let data be the raw octets of the key represented by [[handle]] internal slot of key.
Let result be the result of creating
an ArrayBuffer containing data.
jwk":
Let jwk be a new JsonWebKey
dictionary.
Set the kty attribute of jwk to the
string "oct".
Set the k attribute of jwk to be a string
containing the raw octets of the key represented by [[handle]] internal slot of
key, encoded according to Section 6.4 of JSON Web Algorithms [JWA].
Set the alg attribute of jwk to
the string "CC20P1305".
Set the key_ops attribute of jwk to equal the
usages attribute of
key.
Set the ext attribute of jwk to equal the [[extractable]] internal slot
of key.
Let result be the result of converting jwk to an ECMAScript Object, as defined by [WebIDL].
Return result.
Return 256.
This section is non-normative.
This describes the SHA-3 family of hash functions, as specified by [FIPS-202].
The recognized algorithm names are
"SHA3-256",
"SHA3-384", and
"SHA3-512" for the respective SHA-3 algorithms.
| Operation | Parameters | Result |
|---|---|---|
| digest | None | ArrayBuffer |
name member of
normalizedAlgorithm is a case-sensitive string match for
"SHA3-256":
name member of
normalizedAlgorithm is a case-sensitive string match for
"SHA3-384":
name member of
normalizedAlgorithm is a case-sensitive string match for
"SHA3-512":
If performing the operation results in an error, then throw an OperationError.
Return a new ArrayBuffer containing result.
This section is non-normative.
This describes cSHAKE128 and cSHAKE256, as specified by [NIST-SP800-185].
The recognized algorithm names are
"cSHAKE128" and
"cSHAKE256".
| Operation | Parameters | Result |
|---|---|---|
| digest | CShakeParams |
ArrayBuffer |
WebIDLdictionary CShakeParams : Algorithm {
required [EnforceRange] unsigned long length;
BufferSource functionName;
BufferSource customization;
};
The length member represents the requested output length in bits.
The functionName member represents the function name, used by NIST to define functions based on cSHAKE. When used, it should only be set to values defined by NIST.
The customization member represents the customization string. The application selects this string to define a variant of the function.
name member of
normalizedAlgorithm is a case-sensitive string match for
"cSHAKE128":
length member of normalizedAlgorithm as
the L input parameter,
the contents of the functionName member of normalizedAlgorithm as
the N input parameter, and
the contents of the customization member of normalizedAlgorithm as
the S input parameter.
name member of
normalizedAlgorithm is a case-sensitive string match for
"cSHAKE256":
length member of normalizedAlgorithm as
the L input parameter,
the contents of the functionName member of normalizedAlgorithm as
the N input parameter, and
the contents of the customization member of normalizedAlgorithm as
the S input parameter.
If performing the operation results in an error, then throw an OperationError.
Return a new ArrayBuffer containing result.
This section is non-normative.
This describes KMAC128 and KMAC256, as specified by [NIST-SP800-185].
The recognized algorithm names are
"KMAC128" and
"KMAC256".
| Operation | Parameters | Result |
|---|---|---|
| sign | KmacParams |
ArrayBuffer |
| verify | KmacParams |
boolean |
| generateKey | KmacKeyGenParams |
CryptoKey |
| importKey | KmacImportParams |
CryptoKey |
| exportKey | None | object |
| get key length | KmacImportParams |
Integer |
WebIDLdictionary KmacKeyGenParams : Algorithm {
[EnforceRange] unsigned long length;
};
The length member represents the length (in bits) of the key to generate. If unspecified, the recommended length will be used, which is 128 for KMAC128 and 256 for KMAC256.
WebIDLdictionary KmacImportParams : Algorithm {
[EnforceRange] unsigned long length;
};
The length member represents the length (in bits) of the key.
WebIDLdictionary KmacKeyAlgorithm : KeyAlgorithm {
required unsigned long length;
};
The length member represents the length (in bits) of the key.
WebIDLdictionary KmacParams : Algorithm {
required [EnforceRange] unsigned long length;
BufferSource customization;
};
The length member represents the requested output length in bits.
The customization member represents the customization string. The application selects this string to define a variant of the function.
Let customization be the contents of the customization member of
normalizedAlgorithm if present or the empty octet
string otherwise.
name member of
normalizedAlgorithm is a case-sensitive string match for
"KMAC128":
length member of normalizedAlgorithm as
the L input parameter, and
customization as
the S input parameter.
name member of
normalizedAlgorithm is a case-sensitive string match for
"KMAC256":
length member of normalizedAlgorithm as
the L input parameter, and
customization as
the S input parameter.
Return the result of creating
an ArrayBuffer containing mac.
Let customization be the contents of the customization member of
normalizedAlgorithm if present or the empty octet
string otherwise.
name member of
normalizedAlgorithm is a case-sensitive string match for
"KMAC128":
length member of normalizedAlgorithm as
the L input parameter, and
customization as
the S input parameter.
name member of
normalizedAlgorithm is a case-sensitive string match for
"KMAC256":
length member of normalizedAlgorithm as
the L input parameter, and
customization as
the S input parameter.
Return true if mac is equal to signature and false otherwise.
If usages contains any entry which is not "sign" or
"verify", then throw a SyntaxError.
length member of
normalizedAlgorithm is present:
length
member of normalizedAlgorithm.
name member of
normalizedAlgorithm is a case-sensitive string match for
"KMAC128":
name member of
normalizedAlgorithm is a case-sensitive string match for
"KMAC256":
Generate a key of length length bits.
If the key generation step fails,
then throw an
OperationError.
Let key be a new
CryptoKey object representing the
generated key.
Let algorithm be a new
KmacKeyAlgorithm.
Set the name attribute of
algorithm to "KMAC".
Set the [[algorithm]] internal slot of key to algorithm.
Set the [[extractable]] internal slot of key to be extractable.
Set the [[usages]] internal slot of key to be usages.
Return key.
Let keyData be the key data to be imported.
If usages contains an entry which is not
"sign" or "verify",
then throw a
SyntaxError.
raw":Let data be the octet string contained in keyData.
jwk":JsonWebKey dictionary:Let jwk equal keyData.
If the kty field of jwk is not
"oct",
then throw a
DataError.
If jwk does not meet the requirements of
Section 6.4 of JSON Web Algorithms [JWA],
then throw a
DataError.
Let data be the octet string obtained by decoding the
k field of jwk.
name member of
normalizedAlgorithm is a case-sensitive string match for
"KMAC128":
alg field of jwk is present
and is not "K128",
then throw a
DataError.
name member of
normalizedAlgorithm is a case-sensitive string match for
"KMAC256":
alg field of jwk is present
and is not "K256",
then throw a
DataError.
If usages is non-empty and the use field of jwk is present and is
not "sign",
then throw a
DataError.
If the key_ops field of jwk is present, and
is invalid according to the requirements of
JSON Web Key [JWK] or
does not contain all of the specified usages values,
then throw a
DataError.
If the ext field of jwk is present and
has the value false and extractable is true,
then throw a
DataError.
NotSupportedError.
Let length be equivalent to the length, in octets, of data, multiplied by 8.
length member of
normalizedAlgorithm is present:
Let key be a new {{CryptoKey}}
object representing an KMAC key with the first length
bits of data.
Let algorithm be a new
KmacKeyAlgorithm.
Set the name attribute of
algorithm to "KMAC".
Set the length attribute of
algorithm to length.
Set the [[algorithm]] internal slot of key to algorithm.
Return key.
If the underlying cryptographic key material represented by the [[handle]] internal slot of key
cannot be accessed, then throw an OperationError.
Let bits be the raw bits of the key represented by [[handle]] internal slot of key.
Let data be an octet string containing bits.
raw":
Let result be the result of creating
an ArrayBuffer containing data.
jwk":
Let jwk be a new JsonWebKey
dictionary.
Set the kty attribute of jwk to the
string "oct".
Set the k attribute of jwk to be a string
containing data, encoded according to Section 6.4 of JSON Web Algorithms [JWA].
Let algorithm be the [[algorithm]] internal slot of key.
Set the key_ops attribute of jwk to equal the
usages attribute of key.
Set the ext attribute of jwk to equal the [[extractable]] internal slot
of key.
Let result be the result of converting jwk to an ECMAScript Object, as defined by [WebIDL].
Return result.
length member of
normalizedAlgorithm is present:
length
member of normalizedAlgorithm.
name member of
normalizedAlgorithm is a case-sensitive string match for
"KMAC128":
name member of
normalizedAlgorithm is a case-sensitive string match for
"KMAC256":
Return length.
This section is non-normative.
This describes the Argon2 function for password hashing and key derivation, as defined in [RFC9106].
The recognized algorithm names are
"Argon2d",
"Argon2i", and
"Argon2id" for the respective Argon2 types.
| Operation | Parameters | Result |
|---|---|---|
| deriveBits | Argon2Params |
ArrayBuffer |
| importKey | None | CryptoKey |
| Get key length | None | null |
WebIDLdictionary Argon2Params : Algorithm {
required BufferSource nonce;
required [EnforceRange] unsigned long parallelism;
required [EnforceRange] unsigned long memory;
required [EnforceRange] unsigned long passes;
[EnforceRange] octet version;
BufferSource secretValue;
BufferSource associatedData;
};
The nonce member represents the nonce, which is a salt for password hashing applications.
The parallelism member represents the degree of parallelism.
The memory member represents the memory size in kibibytes. It must be at least 8 times the degree of parallelism.
The passes member represents the number of passes.
The version member represents the version number. The default and currently only defined version is 19 (0x13).
The secretValue member represents the optional secret value.
The associatedData member represents the optional associated data.
For the recommended values of the parameters, see section 4 of [RFC9106].
If length is null, or is less than 32 (4*8), then throw an OperationError.
If the version member
of normalizedAlgorithm is present and is not 19 (0x13),
then throw an
OperationError.
If the parallelism member of normalizedAlgorithm is zero,
or greater than 16777215 (2^24-1),
then throw an OperationError.
If the memory member of normalizedAlgorithm is less than
8 times the parallelism member of normalizedAlgorithm,
then throw an OperationError.
If the passes member of normalizedAlgorithm is zero,
then throw an OperationError.
name member of
normalizedAlgorithm is a case-sensitive string match for
"Argon2d":
name member of
normalizedAlgorithm is a case-sensitive string match for
"Argon2i":
name member of
normalizedAlgorithm is a case-sensitive string match for
"Argon2id":
Let secretValue be the contents of the secretValue member of
normalizedAlgorithm, if present.
Let associatedData be the contents of the associatedData member of
normalizedAlgorithm, if present.
Let result be the result of performing the Argon2 function defined
in Section 3 of [RFC9106] using
the password represented by [[handle]] internal slot of key
as the message, P, the
contents of the nonce attribute of
normalizedAlgorithm as the nonce, S,
the value of the parallelism attribute
of normalizedAlgorithm as the degree of parallelism, p,
the value of the memory attribute
of normalizedAlgorithm as the memory size, m,
the value of the passes attribute
of normalizedAlgorithm as the number of passes, t,
0x13 as the version number, v,
secretValue (if present) as the secret value, K,
associatedData (if present) as the associated data, X,
type as the type, y, and
length divided by 8 as the tag length, T.
If the key derivation operation fails,
then throw an
OperationError.
Return result
If format is not "raw", throw a NotSupportedError
If usages contains a value that is not
"deriveKey" or "deriveBits", then
throw a SyntaxError.
If extractable is not false,
then throw a
SyntaxError.
Let key be a new CryptoKey
representing keyData.
Set the [[extractable]] internal slot of
key to false.
Let algorithm be a new KeyAlgorithm
object.
Set the name attribute of
algorithm to the name member of
normalizedAlgorithm.
Set the [[algorithm]] internal slot of key to algorithm.
Return key.
Return null.
This example derives a key from a password using Argon2, if available, or PBKDF2, otherwise; and then encrypts and decrypts some text with it using AES-OCB, if available, and AES-GCM, otherwise.
const password = 'correct horse battery staple';
const derivationAlg =
SubtleCrypto.supports?.('importKey', 'Argon2id') ?
'Argon2id' :
'PBKDF2';
const encryptionAlg =
SubtleCrypto.supports?.('importKey', 'AES-OCB') ?
'AES-OCB' :
'AES-GCM';
const passwordKey = await crypto.subtle.importKey(
'raw',
new TextEncoder().encode(password),
derivationAlg,
/* extractable: */ false,
['deriveKey']
);
const nonce = crypto.getRandomValues(new Uint8Array(16));
const derivationParams =
derivationAlg === 'Argon2id' ?
{
nonce,
parallelism: 4,
memory: 2 ** 21,
passes: 1
} :
{
salt: nonce,
iterations: 100_000,
hash: 'SHA-256'
};
const key = await crypto.subtle.deriveKey(
{
name: derivationAlg,
...derivationParams
},
passwordKey,
{
name: encryptionAlg,
length: 256
},
/* extractable: */ false,
['encrypt', 'decrypt']
);
const plaintext = 'Hello, world!';
const iv = crypto.getRandomValues(new Uint8Array(16));
const encrypted = await crypto.subtle.encrypt(
{ name: encryptionAlg, iv },
key,
new TextEncoder().encode(plaintext)
);
// Store the derivation and encryption algorithm and parameters
// as well as the ciphertext (e.g. in IndexedDB or a database),
// and retrieve them later. Then, derive the key using the
// original parameters and the password. Here we immediately
// use the same key object to decrypt again.
const decrypted = new TextDecoder().decode(await crypto.subtle.decrypt(
{ name: encryptionAlg, iv },
key,
encrypted
));This section is non-normative.
Refer to algorithm-specific sections for the normative requirements of importing and exporting JWK.
| JSON Web Key | AlgorithmIdentifier |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key word MUST in this document is to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in: