Modern Algorithms in the Web Cryptography API

Abstract

This specification defines a number of post-quantum secure and modern cryptographic algorithms for the Web Cryptography API , namely ML-KEM, ML-DSA, SLH-DSA, AES-OCB, ChaCha20-Poly1305, SHA-3, cSHAKE, KMAC, and Argon2.

This section extends the SubtleCrypto interface of [ webcrypto ].

WebIDL[SecureContext,Exposed=(Window,Worker)]
partial interface SubtleCrypto {
  Promise<EncapsulatedKey> encapsulateKey(
    AlgorithmIdentifier encapsulationAlgorithm,
    CryptoKey encapsulationKey,
    AlgorithmIdentifier sharedKeyAlgorithm,
    boolean extractable,
    sequence<KeyUsage> keyUsages
  );
  Promise<EncapsulatedBits> encapsulateBits(
    AlgorithmIdentifier encapsulationAlgorithm,
    CryptoKey encapsulationKey
  );
  Promise<CryptoKey> decapsulateKey(
    AlgorithmIdentifier decapsulationAlgorithm,
    CryptoKey decapsulationKey,
    BufferSource ciphertext,
    AlgorithmIdentifier sharedKeyAlgorithm,
    boolean extractable,
    sequence<KeyUsage> keyUsages
  );
  Promise<ArrayBuffer> decapsulateBits(
    AlgorithmIdentifier decapsulationAlgorithm,
    CryptoKey decapsulationKey,
    BufferSource ciphertext
  );
  Promise<CryptoKey> getPublicKey(
    CryptoKey key,
    sequence<KeyUsage> keyUsages
  );
  static boolean supports(DOMString operation,
                   AlgorithmIdentifier algorithm,
                   optional unsigned long? length = null);
  static boolean supports(DOMString operation,
                   AlgorithmIdentifier algorithm,
                   AlgorithmIdentifier additionalAlgorithm);
};

This specification replaces the definition of KeyFormat in [ webcrypto ] with the following:



WebIDL




enum


KeyFormat


{

"


raw-public


"
,

"


raw-private


"
,

"


raw-seed


"
,

"


raw-secret


"
,

"


raw


"
,

"


spki


"
,

"


pkcs8


"
,

"


jwk


"

};

This specification specifies a number of new recognized key format values :

raw-public: An unformatted sequence of public key bytes.
raw-private: An unformatted sequence of private key bytes.
raw-seed: An unformatted sequence of private key seed bytes.
raw-secret: An unformatted sequence of secret key bytes.

For all existing symmetric algorithms in [ webcrypto ], " raw-secret " acts as an alias of " raw ".

For all existing asymmetric algorithms in [ webcrypto ], " raw-public " acts as an alias of " raw ".

In the deriveKey () method, in the import key step, " raw-secret " must be used as the format instead of " raw ".

This specification replaces the definition of KeyUsage in [ webcrypto ] with the following:



WebIDL




enum


KeyUsage


{

"


encrypt


"
,

"


decrypt


"
,

"


sign


"
,

"


verify


"
,

"


deriveKey


"
,

"


deriveBits


"
,

"


wrapKey


"
,

"


unwrapKey


"
,

"


encapsulateKey


"
,

"


encapsulateBits


"
,

"


decapsulateKey


"
,

"


decapsulateBits


"

};

This specification specifies a number of new recognized key usage values :

encapsulateKey: Enable using the key with SubtleCrypto . encapsulateKey .
encapsulateBits: Enable using the key with SubtleCrypto . encapsulateBits .
decapsulateKey: Enable using the key with SubtleCrypto . decapsulateKey .
decapsulateBits: Enable using the key with SubtleCrypto . decapsulateBits .

The encapsulateKey( encapsulationAlgorithm , encapsulationKey , sharedKeyAlgorithm , extractable , usages ) method encapsulates a key and returns an EncapsulatedKey object. It behaves as follows:

Let encapsulationAlgorithm, encapsulationKey, sharedKeyAlgorithm, extractable and usages be the encapsulationAlgorithm, encapsulationKey, sharedKeyAlgorithm, extractable and keyUsages parameters passed to the encapsulateKey () method, respectively.
Let normalizedEncapsulationAlgorithm be the result of normalizing an algorithm , with alg set to encapsulationAlgorithm and op set to " encapsulate ".
If an error occurred, return a Promise rejected with normalizedEncapsulationAlgorithm.
Let normalizedSharedKeyAlgorithm be the result of normalizing an algorithm , with alg set to sharedKeyAlgorithm and op set to " importKey ".
If an error occurred, return a Promise rejected with normalizedSharedKeyAlgorithm.
Let realm be the relevant realm of this .
Let promise be a new Promise.
Return promise and perform the remaining steps in parallel .
If the following steps or referenced procedures say to throw an error, queue a global task on the crypto task source , given realm 's global object, to reject promise with the returned error; and then terminate the algorithm .
If the name member of normalizedEncapsulationAlgorithm is not equal to the name attribute of the [[algorithm]] internal slot of encapsulationKey then throw an InvalidAccessError .
If the [[usages]] internal slot of encapsulationKey does not contain an entry that is " encapsulateKey ", then throw an InvalidAccessError .
Let encapsulatedBits be the result of performing the encapsulate operation specified by the [[algorithm]] internal slot of encapsulationKey using encapsulationKey.
Let sharedKey be the result of performing the import key operation specified by normalizedSharedKeyAlgorithm using " raw-secret " as format, the sharedKey field of encapsulatedBits as keyData, sharedKeyAlgorithm as algorithm and using extractable and usages.
Let encapsulatedKey be a new EncapsulatedKey dictionary with sharedKey set to sharedKey and ciphertext set to the ciphertext field of encapsulatedBits.
Queue a global task on the crypto task source , given realm 's global object, to perform the remaining steps.
Let result be the result of converting encapsulatedKey to an ECMAScript Object in realm, as defined by [ WebIDL ].
Resolve promise with result.

The encapsulateBits( encapsulationAlgorithm , encapsulationKey ) method encapsulates a key and returns an EncapsulatedBits object. It behaves as follows:

Let encapsulationAlgorithm and encapsulationKey be the encapsulationAlgorithm and encapsulationKey parameters passed to the encapsulateBits () method, respectively.
Let normalizedEncapsulationAlgorithm be the result of normalizing an algorithm , with alg set to encapsulationAlgorithm and op set to " encapsulate ".
If an error occurred, return a Promise rejected with normalizedEncapsulationAlgorithm.
Let realm be the relevant realm of this .
Let promise be a new Promise.
Return promise and perform the remaining steps in parallel .
If the following steps or referenced procedures say to throw an error, queue a global task on the crypto task source , given realm 's global object, to reject promise with the returned error; and then terminate the algorithm .
If the name member of normalizedEncapsulationAlgorithm is not equal to the name attribute of the [[algorithm]] internal slot of encapsulationKey then throw an InvalidAccessError .
If the [[usages]] internal slot of encapsulationKey does not contain an entry that is " encapsulateBits ", then throw an InvalidAccessError .
Let encapsulatedBits be the result of performing the encapsulate operation specified by the [[algorithm]] internal slot of encapsulationKey using encapsulationKey.
Queue a global task on the crypto task source , given realm 's global object, to perform the remaining steps.
Let result be the result of converting encapsulatedBits to an ECMAScript Object in realm, as defined by [ WebIDL ].
Resolve promise with result.

The decapsulateKey( decapsulationAlgorithm , decapsulationKey , ciphertext , sharedKeyAlgorithm , extractable , usages ) method decapsulates a key and returns an CryptoKey object. It behaves as follows:

Let decapsulationAlgorithm, decapsulationKey, sharedKeyAlgorithm, extractable and usages be the decapsulationAlgorithm, decapsulationKey, sharedKeyAlgorithm, extractable and keyUsages parameters passed to the decapsulateKey () method, respectively.
Let ciphertext be the result of getting a copy of the bytes held by the ciphertext parameter passed to the decapsulateKey () method.
Let normalizedDecapsulationAlgorithm be the result of normalizing an algorithm , with alg set to decapsulationAlgorithm and op set to " decapsulate ".
If an error occurred, return a Promise rejected with normalizedDecapsulationAlgorithm.
Let normalizedSharedKeyAlgorithm be the result of normalizing an algorithm , with alg set to sharedKeyAlgorithm and op set to " importKey ".
If an error occurred, return a Promise rejected with normalizedSharedKeyAlgorithm.
Let realm be the relevant realm of this .
Let promise be a new Promise.
Return promise and perform the remaining steps in parallel .
If the following steps or referenced procedures say to throw an error, queue a global task on the crypto task source , given realm 's global object, to reject promise with the returned error; and then terminate the algorithm .
If the name member of normalizedDecapsulationAlgorithm is not equal to the name attribute of the [[algorithm]] internal slot of decapsulationKey then throw an InvalidAccessError .
If the [[usages]] internal slot of decapsulationKey does not contain an entry that is " decapsulateKey ", then throw an InvalidAccessError .
Let decapsulatedBits be the result of performing the decapsulate operation specified by the [[algorithm]] internal slot of decapsulationKey using decapsulationKey and ciphertext.
Let sharedKey be the result of performing the import key operation specified by normalizedSharedKeyAlgorithm using " raw-secret " as format, the decapsulatedBits as keyData, sharedKeyAlgorithm as algorithm and using extractable and usages.
Queue a global task on the crypto task source , given realm 's global object, to perform the remaining steps.
Let result be the result of converting sharedKey to an ECMAScript Object in realm, as defined by [ WebIDL ].
Resolve promise with result.

The decapsulateBits( decapsulationAlgorithm , decapsulationKey , ciphertext ) method decapsulates a key and returns an ArrayBuffer object. It behaves as follows:

Let decapsulationAlgorithm and decapsulationKey be the decapsulationAlgorithm and decapsulationKey parameters passed to the decapsulateBits () method, respectively.
Let ciphertext be the result of getting a copy of the bytes held by the ciphertext parameter passed to the decapsulateBits () method.
Let normalizedDecapsulationAlgorithm be the result of normalizing an algorithm , with alg set to decapsulationAlgorithm and op set to " decapsulate ".
If an error occurred, return a Promise rejected with normalizedDecapsulationAlgorithm.
Let realm be the relevant realm of this .
Let promise be a new Promise.
Return promise and perform the remaining steps in parallel .
If the following steps or referenced procedures say to throw an error, queue a global task on the crypto task source , given realm 's global object, to reject promise with the returned error; and then terminate the algorithm .
If the name member of normalizedDecapsulationAlgorithm is not equal to the name attribute of the [[algorithm]] internal slot of decapsulationKey then throw an InvalidAccessError .
If the [[usages]] internal slot of decapsulationKey does not contain an entry that is " decapsulateBits ", then throw an InvalidAccessError .
Let decapsulatedBits be the result of performing the decapsulate operation specified by the [[algorithm]] internal slot of decapsulationKey using decapsulationKey and ciphertext.
Queue a global task on the crypto task source , given realm 's global object, to perform the remaining steps.
Let result be the result of creating an ArrayBuffer in realm, containing decapsulatedBits.
Resolve promise with result.

The getPublicKey( key , usages ) method returns the public key corresponding to a given private key. It behaves as follows:

Let key and usages be the key and keyUsages parameters passed to the getPublicKey () method, respectively.
Let algorithm be the [[algorithm]] internal slot of key.
If the cryptographic algorithm identified by algorithm does not support deriving a public key from a private key, then return a Promise rejected with a NotSupportedError .
Let realm be the relevant realm of this .
Let promise be a new Promise.
Return promise and perform the remaining steps in parallel .
If the following steps or referenced procedures say to throw an error, queue a global task on the crypto task source , given realm 's global object, to reject promise with the returned error; and then terminate the algorithm .
If the [[type]] internal slot of key is not " private ", then throw an InvalidAccessError .
If usages contains an entry which is not supported for a public key by the algorithm identified by algorithm, then throw a SyntaxError .
Let publicKey be a new CryptoKey representing the public key corresponding to the private key represented by the [[handle]] internal slot of key.
If an error occurred, then throw a OperationError .
Set the [[type]] internal slot of publicKey to " public ".
Set the [[algorithm]] internal slot of publicKey to algorithm.
Set the [[extractable]] internal slot of publicKey to true.
Set the [[usages]] internal slot of publicKey to usages.
Queue a global task on the crypto task source , given realm 's global object, to perform the remaining steps.
Let result be the result of converting publicKey to an ECMAScript Object in realm, as defined by [ WebIDL ].
Resolve promise with result.

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 ", " unwrapKey ", " encapsulateKey ", " encapsulateBits ", " decapsulateKey ", " decapsulateBits " or " getPublicKey ", 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 ", " unwrapKey ", " encapsulateKey ", " encapsulateBits ", " decapsulateKey ", " decapsulateBits " or " getPublicKey ", return false.
If operation is " deriveKey ", " unwrapKey ", " encapsulateKey " or " decapsulateKey ":

If the result of checking support for an algorithm with op set to " importKey " and alg set to additionalAlgorithm is false, return false.

If operation is " wrapKey ":

If the result of checking support for an algorithm with op set to " exportKey " and alg set to additionalAlgorithm is false, return false.
Let length be null.
If operation is " deriveKey ":
1. If the result of checking support for an algorithm with op set to " get key length " and alg set to additionalAlgorithm is false, return false.
2. Let normalizedAdditionalAlgorithm be the result of normalizing an algorithm , with alg set to additionalAlgorithm and op set to " get key length ".
3. Let length be the result of performing the get key length algorithm specified by additionalAlgorithm using normalizedAdditionalAlgorithm.
4. Set operation to " deriveBits ".
Return the result of checking support for an algorithm , with op set to operation, alg set to algorithm, and length set to length.

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 a length parameter. Its output is a boolean. It behaves as follows:

If op is " encapsulateKey " or " encapsulateBits ", set op to " encapsulate ".
If op is " decapsulateKey " or " decapsulateBits ", set op to " decapsulate ".
If op is " getPublicKey ":
1. Let normalizedAlgorithm be the result of normalizing an algorithm , with alg set to alg and op set to " exportKey ".
2. If an error occurred, return false.
3. If the cryptographic algorithm identified by normalizedAlgorithm does not support deriving a public key from a private key, then return false.
4. Otherwise, return true.
Let normalizedAlgorithm be the result of normalizing an algorithm , with alg set to alg and op set to op.
If an error occurred:
1. If op is " wrapKey ", return the result of checking support for an algorithm with op set to " encrypt " and alg set to alg.
2. If op is " unwrapKey ", return the result of checking support for an algorithm with op set to " decrypt " and alg set to alg.
3. 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:

If the step says to throw an error:

Return false.

If the step says to generate a key:

Return true.

If the step relies on an unavailable parameter, such as key, plaintext or ciphertext:

Return true.

If the step says to return a value:

Return true.

Otherwise:

Execute the step.

Note

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.

This describes using ML-KEM for key encapsulation and decapsulation, as specified by [ FIPS-203 ].

The recognized algorithm names for this algorithm are " ML-KEM-512 ", " ML-KEM-768 " and " ML-KEM-1024 ".

Operation	Parameters	Result
encapsulate	None	`EncapsulatedBits`
decapsulate	None	byte sequence
generateKey	None	`CryptoKeyPair`
importKey	None	`CryptoKey`
exportKey	None	object

If the [[type]] internal slot of key is not " public ", then throw an InvalidAccessError .
Perform the encapsulation key check described in Section 7.2 of [ FIPS-203 ] with the parameter set indicated by the name member of algorithm, using the key represented by the [[handle]] internal slot of key as the ek input parameter.

Note

The result of this check may be cached or precomputed for the CryptoKey object if desirable for performance.
If the encapsulation key check failed, return an OperationError .
Let sharedKey and ciphertext be the outputs that result from performing the ML-KEM.Encaps function described in Section 7.2 of [ FIPS-203 ] with the parameter set indicated by the name member of algorithm, using the key represented by the [[handle]] internal slot of key as the ek input parameter.
If the ML-KEM.Encaps function returned an error, return an OperationError .
Let result be a new EncapsulatedBits dictionary.
Set the sharedKey attribute of result to the result of creating an ArrayBuffer containing sharedKey.
Set the ciphertext attribute of result to the result of creating an ArrayBuffer containing ciphertext.
Return result.

If the [[type]] internal slot of key is not " private ", then throw an InvalidAccessError .
Perform the decapsulation input check described in Section 7.3 of [ FIPS-203 ] with the parameter set indicated by the name member of algorithm, using the key represented by the [[handle]] internal slot of key as the dk input parameter, and ciphertext as the c input parameter.

Note

The result of the decapsulation key type check and the hash check may be cached or precomputed for the CryptoKey object if desirable for performance.
If the decapsulation key check failed, return an OperationError .
Let sharedKey be the output that results from performing the ML-KEM.Decaps function described in Section 7.3 of [ FIPS-203 ] with the parameter set indicated by the name member of algorithm, using the key represented by the [[handle]] internal slot of key as the dk input parameter, and ciphertext as the c input parameter.
Return sharedKey.

If usages contains any entry which is not one of " encapsulateKey ", " encapsulateBits ", " decapsulateKey " or " decapsulateBits ", then throw a SyntaxError .
Generate an ML-KEM key pair, as described in Section 7.1 of [ FIPS-203 ], with the parameter set indicated by the name member of normalizedAlgorithm.

Note

In order to be able to export the seed (d, z), d and z need to be stored as part of the generated key material.
If the key generation step fails, then throw an OperationError .
Let algorithm be a new KeyAlgorithm object.
Set the name attribute of algorithm to the name attribute of normalizedAlgorithm.
Let publicKey be a new CryptoKey representing the encapsulation key of the generated key pair.
Set the [[type]] internal slot of publicKey to " public ".
Set the [[algorithm]] internal slot of publicKey to algorithm.
Set the [[extractable]] internal slot of publicKey to true.
Set the [[usages]] internal slot of publicKey to be the usage intersection of usages and [ "encapsulateKey", "encapsulateBits" ].
Let privateKey be a new CryptoKey representing the decapsulation key of the generated key pair.
Set the [[type]] internal slot of privateKey to " private ".
Set the [[algorithm]] internal slot of privateKey to algorithm.
Set the [[extractable]] internal slot of privateKey to extractable.
Set the [[usages]] internal slot of privateKey to be the usage intersection of usages and [ "decapsulateKey", "decapsulateBits" ].
Let result be a new CryptoKeyPair dictionary.
Set the publicKey attribute of result to be publicKey.
Set the privateKey attribute of result to be privateKey.
Return result.

Let keyData be the key data to be imported.
If format is " spki ":
2. If usages contains an entry which is not " encapsulateKey " or " encapsulateBits " then throw a SyntaxError .
3. Let spki be the result of running the parse a subjectPublicKeyInfo algorithm over keyData.
4. If an error occurred while parsing, then throw a DataError .
5. If the name member of normalizedAlgorithm is " ML-KEM-512 ":
  
  Let expectedOid be id-alg-ml-kem-512 (2.16.840.1.101.3.4.4.1).
  
  If the name member of normalizedAlgorithm is " ML-KEM-768 ":
  
  Let expectedOid be id-alg-ml-kem-768 (2.16.840.1.101.3.4.4.2).
  
  If the name member of normalizedAlgorithm is " ML-KEM-1024 ":
  
  Let expectedOid be id-alg-ml-kem-1024 (2.16.840.1.101.3.4.4.3).
  
  Otherwise:
  
  throw a NotSupportedError .
6. If the algorithm object identifier field of the algorithm AlgorithmIdentifier field of spki is not equal to expectedOid, then throw a DataError .
7. If the parameters field of the algorithm AlgorithmIdentifier field of spki is present, then throw a DataError .
8. Let publicKey be the ML-KEM public key identified by the subjectPublicKey field of spki.
9. Let key be a new CryptoKey that represents publicKey.
10. Set the [[type]] internal slot of key to " public "
11. Let algorithm be a new KeyAlgorithm .
12. Set the name attribute of algorithm to the name attribute of normalizedAlgorithm.
13. Set the [[algorithm]] internal slot of key to algorithm.
14. Set the [[extractable]] internal slot of key to extractable.
15. Set the [[usages]] internal slot of key to usages.
If format is " pkcs8 ":
2. If usages contains an entry which is not " encapsulateKey " or " encapsulateBits " then throw a SyntaxError .
3. Let privateKeyInfo be the result of running the parse a privateKeyInfo algorithm over keyData.
4. If an error occurs while parsing, then throw a DataError .
5. If the name member of normalizedAlgorithm is " ML-KEM-512 ":
  
  Let expectedOid be id-alg-ml-kem-512 (2.16.840.1.101.3.4.4.1).
  
  Let asn1Structure be the ASN.1 ML-KEM-512-PrivateKey structure.
  
  If the name member of normalizedAlgorithm is " ML-KEM-768 ":
  
  Let expectedOid be id-alg-ml-kem-768 (2.16.840.1.101.3.4.4.2).
  
  Let asn1Structure be the ASN.1 ML-KEM-768-PrivateKey structure.
  
  If the name member of normalizedAlgorithm is " ML-KEM-1024 ":
  
  Let expectedOid be id-alg-ml-kem-1024 (2.16.840.1.101.3.4.4.3).
  
  Let asn1Structure be the ASN.1 ML-KEM-1024-PrivateKey structure.
  
  Otherwise:
  
  throw a NotSupportedError .
6. If the algorithm object identifier field of the privateKeyAlgorithm PrivateKeyAlgorithm field of privateKeyInfo is not equal to expectedOid, then throw a DataError .
7. If the parameters field of the privateKeyAlgorithm PrivateKeyAlgorithmIdentifier field of privateKeyInfo is present, then throw a DataError .
8. Let mlKemPrivateKey be the result of performing the parse an ASN.1 structure algorithm, with data as the privateKey field of privateKeyInfo, structure as asn1Structure, and exactData set to true.
9. If an error occurred while parsing, then throw a DataError .
  
  Note
  The import operation shall accept ML-KEM-512-PrivateKey,ML-KEM-768-PrivateKey, or ML-KEM-1024-PrivateKey structures in either one of the three CHOICEs (seed-only, private-only, or both). The absence of a seed or presence of the expanded private key is not a reason to throw a DataError.
10. Let key be a new CryptoKey that represents the ML-KEM private key identified by mlKemPrivateKey.
11. Set the [[type]] internal slot of key to " private "
12. Let algorithm be a new KeyAlgorithm .
13. Set the name attribute of algorithm to the name attribute of normalizedAlgorithm.
14. Set the [[algorithm]] internal slot of key to algorithm.
15. Set the [[extractable]] internal slot of key to extractable.
16. Set the [[usages]] internal slot of key to usages.
If format is " raw-public ":
1. If usages contains an entry which is not " encapsulateKey " or " encapsulateBits " then throw a SyntaxError .
2. Let data be keyData.
3. Let key be a new CryptoKey that represents the ML-KEM public key data in data.
4. Set the [[type]] internal slot of key to " public "
5. Let algorithm be a new KeyAlgorithm .
6. Set the name attribute of algorithm to the name attribute of normalizedAlgorithm.
7. Set the [[algorithm]] internal slot of key to algorithm.
If format is " raw-seed ":
1. If usages contains an entry which is not " decapsulateKey " or " decapsulateBits " then throw a SyntaxError .
2. Let data be keyData.
3. If the length in bits of data is not 512 then throw a DataError .
4. Let privateKey be the result of performing the ML-KEM.KeyGen_internal function described in Section 6.1 of [ FIPS-203 ] with the parameter set indicated by the name member of normalizedAlgorithm, using the first 256 bits of data as d and the last 256 bits of data as z.
5. Let key be a new CryptoKey that represents the ML-KEM private key identified by privateKey.
6. Set the [[type]] internal slot of key to " private "
7. Let algorithm be a new KeyAlgorithm .
8. Set the name attribute of algorithm to the name attribute of normalizedAlgorithm.
9. Set the [[algorithm]] internal slot of key to algorithm.
If format is " jwk ":
1. If keyData is a JsonWebKey dictionary:
  
  Let jwk equal keyData.
  
  Otherwise:
  
  Throw a DataError .
2. If the priv field of jwk is present and if usages contains an entry which is not " decapsulateKey " or " decapsulateBits " then throw a SyntaxError .
3. If the priv field of jwk is not present and if usages contains an entry which is not " encapsulateKey " or " encapsulateBits " then throw a SyntaxError .
4. If the kty field of jwk is not " AKP ", then throw a DataError .
5. If the alg field of jwk is not one of the alg values corresponding to the name member of normalizedAlgorithm indicated in Section 8 of [ draft-ietf-jose-pqc-kem-01 ] (Figure 1 or 2), then throw a DataError .
  
  For example, MLKEM512 and MLKEM512+A128KW are valid "alg" values for ML-KEM-512.
6. If usages is non-empty and the use field of jwk is present and is not equal to " enc ", then throw a DataError .
7. If the key_ops field of jwk is present, and is invalid according to the requirements of JSON Web Key [ JWK ], or it does not contain all of the specified usages values, then throw a DataError .
8. If the ext field of jwk is present and has the value false and extractable is true, then throw a DataError .
9. If the priv field of jwk is present:
  
  If the priv attribute of jwk does not contain a valid base64url encoded seed representing an ML-KEM private key, then throw a DataError .
  
  Let key be a new CryptoKey object that represents the ML-KEM private key identified by interpreting the priv attribute of jwk as a base64url encoded seed.
  
  Set the [[type]] internal slot of Key to " private ".
  
  If the pub attribute of jwk does not contain the base64url encoded public key representing the ML-KEM public key corresponding to key, then throw a DataError .
  
  Otherwise:
  
  If the pub attribute of jwk does not contain a valid base64url encoded public key representing an ML-KEM public key, then throw a DataError .
  
  Let key be a new CryptoKey object that represents the ML-KEM public key identified by interpreting the pub attribute of jwk as a base64url encoded public key.
  
  Set the [[type]] internal slot of Key to " public ".
10. Let algorithm be a new instance of a KeyAlgorithm object.
11. Set the name attribute of algorithm to the name member of normalizedAlgorithm.
12. Set the [[algorithm]] internal slot of key to algorithm.
Otherwise:

throw a NotSupportedError .
Return key.

If the underlying cryptographic key material represented by the [[handle]] internal slot of key cannot be accessed, then throw an OperationError .
If the [[type]] internal slot of key is " private " and an ML-KEM seed cannot be resolved from the [[handle]] internal slot of key, then throw an OperationError.
If format is " spki ":
1. If the [[type]] internal slot of key is not " public ", then throw an InvalidAccessError .
2. Let data be an instance of the SubjectPublicKeyInfo ASN.1 structure defined in [ RFC5280 ] with the following properties:
  - Set the algorithm field to an AlgorithmIdentifier ASN.1 type with the following properties:
    
    If the name member of normalizedAlgorithm is " ML-KEM-512 ":
    
    Set the algorithm object identifier to the id-alg-ml-kem-512 (2.16.840.1.101.3.4.4.1) OID.
    
    If the name member of normalizedAlgorithm is " ML-KEM-768 ":
    
    Set the algorithm object identifier to the id-alg-ml-kem-768 (2.16.840.1.101.3.4.4.2) OID.
    
    If the name member of normalizedAlgorithm is " ML-KEM-1024 ":
    
    Set the algorithm object identifier to the id-alg-ml-kem-1024 (2.16.840.1.101.3.4.4.3) OID.
    
    Otherwise:
    
    throw a NotSupportedError .
  - Set the subjectPublicKey field to keyData.
3. Let result be the result of DER-encoding data.
If format is " pkcs8 ":
1. If the [[type]] internal slot of key is not " private ", then throw an InvalidAccessError .
2. Let data be an instance of the PrivateKeyInfo ASN.1 structure defined in [ RFC5208 ] with the following properties:
  - Set the version field to 0.
  - Set the privateKeyAlgorithm field to a PrivateKeyAlgorithmIdentifier ASN.1 type with the following properties:
    
    If the name member of normalizedAlgorithm is " ML-KEM-512 ":
    
    Set the algorithm object identifier to the id-alg-ml-kem-512 (2.16.840.1.101.3.4.4.1) OID.
    
    If the name member of normalizedAlgorithm is " ML-KEM-768 ":
    
    Set the algorithm object identifier to the id-alg-ml-kem-768 (2.16.840.1.101.3.4.4.2) OID.
    
    If the name member of normalizedAlgorithm is " ML-KEM-1024 ":
    
    Set the algorithm object identifier to the id-alg-ml-kem-1024 (2.16.840.1.101.3.4.4.3) OID.
    
    Otherwise:
    
    throw a NotSupportedError .
  - Set the privateKey field as follows:
    
    If the name member of normalizedAlgorithm is " ML-KEM-512 ":
    
    Set the privateKey field to the result of DER-encoding a ML-KEM-512-PrivateKey ASN.1 type that represents the ML-KEM private key seed represented by the [[handle]] internal slot of key using the seed-only format (using a context-specific [0] primitive tag with an implicit encoding of OCTET STRING).
    
    If the name member of normalizedAlgorithm is " ML-KEM-768 ":
    
    Set the privateKey field to the result of DER-encoding a ML-KEM-768-PrivateKey ASN.1 type that represents the ML-KEM private key seed represented by the [[handle]] internal slot of key using the seed-only format (using a context-specific [0] primitive tag with an implicit encoding of OCTET STRING).
    
    If the name member of normalizedAlgorithm is " ML-KEM-1024 ":
    
    Set the privateKey field to the result of DER-encoding a ML-KEM-1024-PrivateKey ASN.1 type that represents the ML-KEM private key seed represented by the [[handle]] internal slot of key using the seed-only format (using a context-specific [0] primitive tag with an implicit encoding of OCTET STRING).
    
    Otherwise:
    
    throw a NotSupportedError .
3. Let result be the result of DER-encoding data.
If format is " raw-public ":
1. If the [[type]] internal slot of key is not " public ", then throw an InvalidAccessError .
2. Let data be a byte sequence containing the raw octets of the key represented by the [[handle]] internal slot of key.
3. Let result be data.
If format is " raw-seed ":
1. If the [[type]] internal slot of key is not " private ", then throw an InvalidAccessError .
2. Let data be a byte sequence containing the concatenation of the d and z seed variables of the key represented by the [[handle]] internal slot of key.
  
  Note
  
  The d and z seed variables were sampled in the ML-KEM.KeyGen function as described in Section 7.1 of [ FIPS-203 ].
3. Let result be data.
If format is " jwk ":
1. Let jwk be a new JsonWebKey dictionary.
2. Set the kty attribute of jwk to " AKP ".
3. Set the alg attribute of jwk to the alg value corresponding to the name member of normalizedAlgorithm indicated in Section 8 of [ draft-ietf-jose-pqc-kem-01 ] (Figure 1).
  
  For example, MLKEM512 is the "alg" value used for ML-KEM-512.
4. Set the pub attribute of jwk to the base64url encoded public key corresponding to the [[handle]] internal slot of key.
5. If the [[type]] internal slot of key is " private ":
  
  Set the priv attribute of jwk to the base64url encoded seed represented by the [[handle]] internal slot of key.
6. Set the key_ops attribute of jwk to the usages attribute of key.
7. Set the ext attribute of jwk to the [[extractable]] internal slot of key.
8. Let result be jwk.
Otherwise:

throw a NotSupportedError .
Return result.

This section is non-normative.

This describes using ML-DSA for signing and verification, as specified by [ FIPS-204 ].

The recognized algorithm names for this algorithm are " ML-DSA-44 ", " ML-DSA-65 " and " ML-DSA-87 ".

Operation	Parameters	Result
sign	`ContextParams`	byte sequence
verify	`ContextParams`	boolean
generateKey	None	`CryptoKeyPair`
importKey	None	`CryptoKey`
exportKey	None	object

WebIDLdictionary ContextParams : Algorithm {
  BufferSource context;
};

The context member represents the optional context data to associate with the message.

If the [[type]] internal slot of key is not " private ", then throw an InvalidAccessError .
Let context be the context member of normalizedAlgorithm or the empty octet string if the context member of normalizedAlgorithm is not present.
Let result be the result of performing the ML-DSA.Sign signing algorithm, as specified in Section 5.2 of [ FIPS-204 ], with the parameter set indicated by the name member of normalizedAlgorithm, using the ML-DSA private key associated with key as sk, message as M and context as ctx.
If the ML-DSA.Sign algorithm returned an error, return an OperationError .
Return result.

If the [[type]] internal slot of key is not " public ", then throw an InvalidAccessError .
Let context be the context member of normalizedAlgorithm or the empty octet string if the context member of normalizedAlgorithm is not present.
Let result be the result of performing the ML-DSA.Verify verification algorithm, as specified in Section 5.3 of [ FIPS-204 ], with the parameter set indicated by the name member of normalizedAlgorithm, using the ML-DSA public key associated with key as pk, message as M, signature as σ and context as ctx.
If the ML-DSA.Verify algorithm returned an error, return an OperationError .
Return result.

If usages contains a value which is not one of " sign " or " verify ", then throw a SyntaxError .
Generate an ML-DSA key pair, as described in Section 5.1 of [ FIPS-204 ], with the parameter set indicated by the name member of normalizedAlgorithm.

Note

In order to be able to export the seed ξ, it needs to be stored as part of the generated key material.
If the key generation step fails, then throw an OperationError .
Let algorithm be a new KeyAlgorithm object.
Set the name attribute of algorithm to the name attribute of normalizedAlgorithm.
Let publicKey be a new CryptoKey representing the public key of the generated key pair.
Set the [[type]] internal slot of publicKey to " public ".
Set the [[algorithm]] internal slot of publicKey to algorithm.
Set the [[extractable]] internal slot of publicKey to true.
Set the [[usages]] internal slot of publicKey to be the usage intersection of usages and [ "verify" ].
Let privateKey be a new CryptoKey representing the private key of the generated key pair.
Set the [[type]] internal slot of privateKey to " private ".
Set the [[algorithm]] internal slot of privateKey to algorithm.
Set the [[extractable]] internal slot of privateKey to extractable.
Set the [[usages]] internal slot of privateKey to be the usage intersection of usages and [ "sign" ].
Let result be a new CryptoKeyPair dictionary.
Set the publicKey attribute of result to be publicKey.
Set the privateKey attribute of result to be privateKey.
Return result.

Let keyData be the key data to be imported.
If format is " spki ":
1. If usages contains a value which is not " verify " then throw a SyntaxError .
2. Let spki be the result of running the parse a subjectPublicKeyInfo algorithm over keyData.
3. If an error occurred while parsing, then throw a DataError .
4. If the name member of normalizedAlgorithm is " ML-DSA-44 ":
  
  Let expectedOid be id-ml-dsa-44 (2.16.840.1.101.3.4.3.17).
  
  If the name member of normalizedAlgorithm is " ML-DSA-65 ":
  
  Let expectedOid be id-ml-dsa-65 (2.16.840.1.101.3.4.3.18).
  
  If the name member of normalizedAlgorithm is " ML-DSA-87 ":
  
  Let expectedOid be id-ml-dsa-87 (2.16.840.1.101.3.4.3.19).
  
  Otherwise:
  
  throw a NotSupportedError .
5. If the algorithm object identifier field of the algorithm AlgorithmIdentifier field of spki is not equal to expectedOid, then throw a DataError .
6. If the parameters field of the algorithm AlgorithmIdentifier field of spki is present, then throw a DataError .
7. Let publicKey be the ML-DSA public key identified by the subjectPublicKey field of spki.
8. Let key be a new CryptoKey that represents publicKey.
9. Set the [[type]] internal slot of key to " public "
10. Let algorithm be a new KeyAlgorithm .
11. Set the name attribute of algorithm to the name attribute of normalizedAlgorithm.
12. Set the [[algorithm]] internal slot of key to algorithm.
13. Set the [[extractable]] internal slot of key to extractable.
14. Set the [[usages]] internal slot of key to usages.
If format is " pkcs8 ":
1. If usages contains a value which is not " sign " then throw a SyntaxError .
2. Let privateKeyInfo be the result of running the parse a privateKeyInfo algorithm over keyData.
3. If an error occurs while parsing, then throw a DataError .
4. If the name member of normalizedAlgorithm is " ML-DSA-44 ":
  
  Let expectedOid be id-ml-dsa-44 (2.16.840.1.101.3.4.3.17).
  
  Let asn1Structure be the ASN.1 ML-DSA-44-PrivateKey structure.
  
  If the name member of normalizedAlgorithm is " ML-DSA-65 ":
  
  Let expectedOid be id-ml-dsa-65 (2.16.840.1.101.3.4.3.18).
  
  Let asn1Structure be the ASN.1 ML-DSA-65-PrivateKey structure.
  
  If the name member of normalizedAlgorithm is " ML-DSA-87 ":
  
  Let expectedOid be id-ml-dsa-87 (2.16.840.1.101.3.4.3.19).
  
  Let asn1Structure be the ASN.1 ML-DSA-87-PrivateKey structure.
  
  Otherwise:
  
  throw a NotSupportedError .
5. If the algorithm object identifier field of the privateKeyAlgorithm PrivateKeyAlgorithm field of privateKeyInfo is not equal to expectedOid, then throw a DataError .
6. If the parameters field of the privateKeyAlgorithm PrivateKeyAlgorithmIdentifier field of privateKeyInfo is present, then throw a DataError .
7. Let mlDsaPrivateKey be the result of performing the parse an ASN.1 structure algorithm, with data as the privateKey field of privateKeyInfo, structure as asn1Structure, and exactData set to true.
8. If an error occurred while parsing, then throw a DataError .
  
  Note
  The import operation shall accept ML-DSA-44-PrivateKey,ML-DSA-65-PrivateKey, or ML-DSA-87-PrivateKey structures in either one of the three CHOICEs (seed-only, private-only, or both). The absence of a seed or presence of the expanded private key is not a reason to throw a DataError.
9. Let key be a new CryptoKey that represents the ML-DSA private key identified by mlDsaPrivateKey.
10. Set the [[type]] internal slot of key to " private "
11. Let algorithm be a new KeyAlgorithm .
12. Set the name attribute of algorithm to the name attribute of normalizedAlgorithm.
13. Set the [[algorithm]] internal slot of key to algorithm.
14. Set the [[extractable]] internal slot of key to extractable.
15. Set the [[usages]] internal slot of key to usages.
If format is " raw-public ":
1. If usages contains a value which is not " verify " then throw a SyntaxError .
2. Let algorithm be a new KeyAlgorithm object.
3. Set the name attribute of algorithm to the name attribute of normalizedAlgorithm.
4. Let key be a new CryptoKey representing the key data provided in keyData.
5. Set the [[type]] internal slot of key to " public "
6. Set the [[algorithm]] internal slot of key to algorithm.
If format is " raw-seed ":
1. If usages contains an entry which is not " sign " then throw a SyntaxError .
2. Let data be keyData.
3. If the length in bits of data is not 256 then throw a DataError .
4. Let privateKey be the result of performing the ML-DSA.KeyGen_internal function described in Section 6.1 of [ FIPS-204 ] with the parameter set indicated by the name member of normalizedAlgorithm, using data as ξ.
5. Let key be a new CryptoKey that represents the ML-DSA private key identified by privateKey.
6. Set the [[type]] internal slot of key to " private "
7. Let algorithm be a new KeyAlgorithm .
8. Set the name attribute of algorithm to the name attribute of normalizedAlgorithm.
9. Set the [[algorithm]] internal slot of key to algorithm.
If format is " jwk ":
1. If keyData is a JsonWebKey dictionary:
  
  Let jwk equal keyData.
  
  Otherwise:
  
  Throw a DataError .
2. If the priv field is present and usages contains a value which is not " sign ", or, if the priv field is not present and usages contains a value which is not " verify " then throw a SyntaxError .
3. If the kty field of jwk is not " AKP ", then throw a DataError .
4. If the alg field of jwk is not equal to the name member of normalizedAlgorithm, then throw a DataError .
5. If usages is non-empty and the use field of jwk is present and is not equal to " sig ", then throw a DataError .
6. If the key_ops field of jwk is present, and is invalid according to the requirements of JSON Web Key [ JWK ], or it does not contain all of the specified usages values, then throw a DataError .
7. If the ext field of jwk is present and has the value false and extractable is true, then throw a DataError .
8. If the priv field of jwk is present:
  
  If the priv attribute of jwk does not contain a valid base64url encoded seed representing an ML-DSA private key, then throw a DataError .
  
  Let key be a new CryptoKey object that represents the ML-DSA private key identified by interpreting the priv attribute of jwk as a base64url encoded seed.
  
  Set the [[type]] internal slot of Key to " private ".
  
  If the pub attribute of jwk does not contain the base64url encoded public key representing the ML-DSA public key corresponding to key, then throw a DataError .
  
  Otherwise:
  
  If the pub attribute of jwk does not contain a valid base64url encoded public key representing an ML-DSA public key, then throw a DataError .
  
  Let key be a new CryptoKey object that represents the ML-DSA public key identified by interpreting the pub attribute of jwk as a base64url encoded public key.
  
  Set the [[type]] internal slot of Key to " public ".
9. Let algorithm be a new instance of a KeyAlgorithm object.
10. Set the name attribute of algorithm to the name member of normalizedAlgorithm.
11. Set the [[algorithm]] internal slot of key to algorithm.
Otherwise:

throw a NotSupportedError .
Return key

Let key be the CryptoKey to be exported.
If the underlying cryptographic key material represented by the [[handle]] internal slot of key cannot be accessed, then throw an OperationError .
If the [[type]] internal slot of key is " private " and an ML-DSA seed cannot be resolved from the [[handle]] internal slot of key, then throw an OperationError.
If format is " spki ":
1. If the [[type]] internal slot of key is not " public ", then throw an InvalidAccessError .
2. Let data be an instance of the SubjectPublicKeyInfo ASN.1 structure defined in [ RFC5280 ] with the following properties:
  - Set the algorithm field to an AlgorithmIdentifier ASN.1 type with the following properties:
    
    If the name member of normalizedAlgorithm is " ML-DSA-44 ":
    
    Set the algorithm object identifier to the id-ml-dsa-44 (2.16.840.1.101.3.4.3.17) OID.
    
    If the name member of normalizedAlgorithm is " ML-DSA-65 ":
    
    Set the algorithm object identifier to the id-ml-dsa-65 (2.16.840.1.101.3.4.3.18) OID.
    
    If the name member of normalizedAlgorithm is " ML-DSA-87 ":
    
    Set the algorithm object identifier to the id-ml-dsa-87 (2.16.840.1.101.3.4.3.19) OID.
    
    Otherwise:
    
    throw a NotSupportedError .
  - Set the subjectPublicKey field to keyData.
3. Let result be the result of DER-encoding data.
If format is " pkcs8 ":
1. If the [[type]] internal slot of key is not " private ", then throw an InvalidAccessError .
2. Let data be an instance of the PrivateKeyInfo ASN.1 structure defined in [ RFC5208 ] with the following properties:
  - Set the version field to 0.
  - Set the privateKeyAlgorithm field to a PrivateKeyAlgorithmIdentifier ASN.1 type with the following properties:
    
    If the name member of normalizedAlgorithm is " ML-DSA-44 ":
    
    Set the algorithm object identifier to the id-ml-dsa-44 (2.16.840.1.101.3.4.3.17) OID.
    
    If the name member of normalizedAlgorithm is " ML-DSA-65 ":
    
    Set the algorithm object identifier to the id-ml-dsa-65 (2.16.840.1.101.3.4.3.18) OID.
    
    If the name member of normalizedAlgorithm is " ML-DSA-87 ":
    
    Set the algorithm object identifier to the id-ml-dsa-87 (2.16.840.1.101.3.4.3.19) OID.
    
    Otherwise:
    
    throw a NotSupportedError .
  - Set the privateKey field as follows:
    
    If the name member of normalizedAlgorithm is " ML-DSA-44 ":
    
    Set the privateKey field to the result of DER-encoding a ML-DSA-44-PrivateKey ASN.1 type that represents the ML-DSA private key seed represented by the [[handle]] internal slot of key using the seed-only format (using a context-specific [0] primitive tag with an implicit encoding of OCTET STRING).
    
    If the name member of normalizedAlgorithm is " ML-DSA-65 ":
    
    Set the privateKey field to the result of DER-encoding a ML-DSA-65-PrivateKey ASN.1 type that represents the ML-DSA private key seed represented by the [[handle]] internal slot of key using the seed-only format (using a context-specific [0] primitive tag with an implicit encoding of OCTET STRING).
    
    If the name member of normalizedAlgorithm is " ML-DSA-87 ":
    
    Set the privateKey field to the result of DER-encoding a ML-DSA-87-PrivateKey ASN.1 type that represents the ML-DSA private key seed represented by the [[handle]] internal slot of key using the seed-only format (using a context-specific [0] primitive tag with an implicit encoding of OCTET STRING).
    
    Otherwise:
    
    throw a NotSupportedError .
3. Let result be the result of DER-encoding data.
If format is " raw-public ":
1. If the [[type]] internal slot of key is not " public ", then throw an InvalidAccessError .
2. Let data be a byte sequence containing the ML-DSA public key represented by the [[handle]] internal slot of key.
3. Let result be data.
If format is " raw-seed ":
1. If the [[type]] internal slot of key is not " private ", then throw an InvalidAccessError .
2. Let data be a byte sequence containing the ξ seed variable of the key represented by the [[handle]] internal slot of key.
  
  Note
  
  The ξ seed variable was sampled in the ML-DSA.KeyGen function as described in Section 5.1 of [ FIPS-204 ].
3. Let result be data.
If format is " jwk ":
1. Let jwk be a new JsonWebKey dictionary.
2. Set the kty attribute of jwk to " AKP ".
3. Set the alg attribute of jwk to the name member of normalizedAlgorithm.
4. Set the pub attribute of jwk to the base64url encoded public key corresponding to the [[handle]] internal slot of key.
5. If the [[type]] internal slot of key is " private ":
  
  Set the priv attribute of jwk to the base64url encoded seed represented by the [[handle]] internal slot of key.
6. Set the key_ops attribute of jwk to the usages attribute of key.
7. Set the ext attribute of jwk to the [[extractable]] internal slot of key.
8. Let result be jwk.
Otherwise:

throw a NotSupportedError .
Return result.

This section is non-normative.

This describes using SLH-DSA for signing and verification, as specified by [ FIPS-205 ].

The recognized algorithm names for this algorithm are " SLH-DSA-SHA2-128s ", " SLH-DSA-SHAKE-128s ", " SLH-DSA-SHA2-128f ", " SLH-DSA-SHAKE-128f ", " SLH-DSA-SHA2-192s ", " SLH-DSA-SHAKE-192s ", " SLH-DSA-SHA2-192f ", " SLH-DSA-SHAKE-192f ", " SLH-DSA-SHA2-256s ", " SLH-DSA-SHAKE-256s ", " SLH-DSA-SHA2-256f " and " SLH-DSA-SHAKE-256f ".

Operation	Parameters	Result
sign	`ContextParams`	byte sequence
verify	`ContextParams`	boolean
generateKey	None	`CryptoKeyPair`
importKey	None	`CryptoKey`
exportKey	None	object

If the [[type]] internal slot of key is not " private ", then throw an InvalidAccessError .
Let context be the context member of normalizedAlgorithm or the empty octet string if the context member of normalizedAlgorithm is not present.
Let result be the result of performing the slh_sign signing algorithm, as specified in Section 10.2.1 of [ FIPS-205 ], with the parameter set indicated by the name member of normalizedAlgorithm, using the SLH-DSA private key associated with key as SK, message as M and context as ctx.
If the slh_sign algorithm returned an error, return an OperationError .
Return result.

If the [[type]] internal slot of key is not " public ", then throw an InvalidAccessError .
Let context be the context member of normalizedAlgorithm or the empty octet string if the context member of normalizedAlgorithm is not present.
Let result be the result of performing the slh_verify verification algorithm, as specified in Section 10.3 of [ FIPS-205 ], with the parameter set indicated by the name member of normalizedAlgorithm, using the SLH-DSA public key associated with key as PK, message as M, signature as SIG and context as ctx.
If the slh_verify algorithm returned an error, return an OperationError .
Return result.

If usages contains a value which is not one of " sign " or " verify ", then throw a SyntaxError .
Generate an SLH-DSA key pair, as described in Section 10.1 of [ FIPS-205 ], with the parameter set indicated by the name member of normalizedAlgorithm.
If the key generation step fails, then throw an OperationError .
Let algorithm be a new KeyAlgorithm object.
Set the name attribute of algorithm to the name attribute of normalizedAlgorithm.
Let publicKey be a new CryptoKey representing the public key of the generated key pair.
Set the [[type]] internal slot of publicKey to " public ".
Set the [[algorithm]] internal slot of publicKey to algorithm.
Set the [[extractable]] internal slot of publicKey to true.
Set the [[usages]] internal slot of publicKey to be the usage intersection of usages and [ "verify" ].
Let privateKey be a new CryptoKey representing the private key of the generated key pair.
Set the [[type]] internal slot of privateKey to " private ".
Set the [[algorithm]] internal slot of privateKey to algorithm.
Set the [[extractable]] internal slot of privateKey to extractable.
Set the [[usages]] internal slot of privateKey to be the usage intersection of usages and [ "sign" ].
Let result be a new CryptoKeyPair dictionary.
Set the publicKey attribute of result to be publicKey.
Set the privateKey attribute of result to be privateKey.
Return result.

Let keyData be the key data to be imported.
If format is " spki ":
1. If usages contains a value which is not " verify " then throw a SyntaxError .
2. Let spki be the result of running the parse a subjectPublicKeyInfo algorithm over keyData.
3. If an error occurred while parsing, then throw a DataError .
4. If the name member of normalizedAlgorithm is " SLH-DSA-SHA2-128s ":
  
  Let expectedOid be id-slh-dsa-sha2-128s (2.16.840.1.101.3.4.3.20).
  
  If the name member of normalizedAlgorithm is " SLH-DSA-SHA2-128f ":
  
  Let expectedOid be id-slh-dsa-sha2-128f (2.16.840.1.101.3.4.3.21).
  
  If the name member of normalizedAlgorithm is " SLH-DSA-SHA2-192s ":
  
  Let expectedOid be id-slh-dsa-sha2-192s (2.16.840.1.101.3.4.3.22).
  
  If the name member of normalizedAlgorithm is " SLH-DSA-SHA2-192f ":
  
  Let expectedOid be id-slh-dsa-sha2-192f (2.16.840.1.101.3.4.3.23).
  
  If the name member of normalizedAlgorithm is " SLH-DSA-SHA2-256s ":
  
  Let expectedOid be id-slh-dsa-sha2-256s (2.16.840.1.101.3.4.3.24).
  
  If the name member of normalizedAlgorithm is " SLH-DSA-SHA2-256f ":
  
  Let expectedOid be id-slh-dsa-sha2-256f (2.16.840.1.101.3.4.3.25).
  
  If the name member of normalizedAlgorithm is " SLH-DSA-SHAKE-128s ":
  
  Let expectedOid be id-slh-dsa-shake-128s (2.16.840.1.101.3.4.3.26).
  
  If the name member of normalizedAlgorithm is " SLH-DSA-SHAKE-128f ":
  
  Let expectedOid be id-slh-dsa-shake-128f (2.16.840.1.101.3.4.3.27).
  
  If the name member of normalizedAlgorithm is " SLH-DSA-SHAKE-192s ":
  
  Let expectedOid be id-slh-dsa-shake-192s (2.16.840.1.101.3.4.3.28).
  
  If the name member of normalizedAlgorithm is " SLH-DSA-SHAKE-192f ":
  
  Let expectedOid be id-slh-dsa-shake-192f (2.16.840.1.101.3.4.3.29).
  
  If the name member of normalizedAlgorithm is " SLH-DSA-SHAKE-256s ":
  
  Let expectedOid be id-slh-dsa-shake-256s (2.16.840.1.101.3.4.3.30).
  
  If the name member of normalizedAlgorithm is " SLH-DSA-SHAKE-256f ":
  
  Let expectedOid be id-slh-dsa-shake-256f (2.16.840.1.101.3.4.3.31).
  
  Otherwise:
  
  throw a NotSupportedError .
5. If the algorithm object identifier field of the algorithm AlgorithmIdentifier field of spki is not equal to expectedOid, then throw a DataError .
6. If the parameters field of the algorithm AlgorithmIdentifier field of spki is present, then throw a DataError .
7. Let publicKey be the SLH-DSA public key identified by the subjectPublicKey field of spki.
8. Let key be a new CryptoKey that represents publicKey.
9. Set the [[type]] internal slot of key to " public "
10. Let algorithm be a new KeyAlgorithm .
11. Set the name attribute of algorithm to the name attribute of normalizedAlgorithm.
12. Set the [[algorithm]] internal slot of key to algorithm.
13. Set the [[extractable]] internal slot of key to extractable.
14. Set the [[usages]] internal slot of key to usages.
If format is " pkcs8 ":
1. If usages contains a value which is not " sign " then throw a SyntaxError .
2. Let privateKeyInfo be the result of running the parse a privateKeyInfo algorithm over keyData.
3. If an error occurs while parsing, then throw a DataError .
4. If the name member of normalizedAlgorithm is " SLH-DSA-SHA2-128s ":
  
  Let expectedOid be id-slh-dsa-sha2-128s (2.16.840.1.101.3.4.3.20).
  
  If the name member of normalizedAlgorithm is " SLH-DSA-SHA2-128f ":
  
  Let expectedOid be id-slh-dsa-sha2-128f (2.16.840.1.101.3.4.3.21).
  
  If the name member of normalizedAlgorithm is " SLH-DSA-SHA2-192s ":
  
  Let expectedOid be id-slh-dsa-sha2-192s (2.16.840.1.101.3.4.3.22).
  
  If the name member of normalizedAlgorithm is " SLH-DSA-SHA2-192f ":
  
  Let expectedOid be id-slh-dsa-sha2-192f (2.16.840.1.101.3.4.3.23).
  
  If the name member of normalizedAlgorithm is " SLH-DSA-SHA2-256s ":
  
  Let expectedOid be id-slh-dsa-sha2-256s (2.16.840.1.101.3.4.3.24).
  
  If the name member of normalizedAlgorithm is " SLH-DSA-SHA2-256f ":
  
  Let expectedOid be id-slh-dsa-sha2-256f (2.16.840.1.101.3.4.3.25).
  
  If the name member of normalizedAlgorithm is " SLH-DSA-SHAKE-128s ":
  
  Let expectedOid be id-slh-dsa-shake-128s (2.16.840.1.101.3.4.3.26).
  
  If the name member of normalizedAlgorithm is " SLH-DSA-SHAKE-128f ":
  
  Let expectedOid be id-slh-dsa-shake-128f (2.16.840.1.101.3.4.3.27).
  
  If the name member of normalizedAlgorithm is " SLH-DSA-SHAKE-192s ":
  
  Let expectedOid be id-slh-dsa-shake-192s (2.16.840.1.101.3.4.3.28).
  
  If the name member of normalizedAlgorithm is " SLH-DSA-SHAKE-192f ":
  
  Let expectedOid be id-slh-dsa-shake-192f (2.16.840.1.101.3.4.3.29).
  
  If the name member of normalizedAlgorithm is " SLH-DSA-SHAKE-256s ":
  
  Let expectedOid be id-slh-dsa-shake-256s (2.16.840.1.101.3.4.3.30).
  
  If the name member of normalizedAlgorithm is " SLH-DSA-SHAKE-256f ":
  
  Let expectedOid be id-slh-dsa-shake-256f (2.16.840.1.101.3.4.3.31).
  
  Otherwise:
  
  throw a NotSupportedError .
5. If the algorithm object identifier field of the privateKeyAlgorithm PrivateKeyAlgorithm field of privateKeyInfo is not equal to expectedOid, then throw a DataError .
6. If the parameters field of the privateKeyAlgorithm PrivateKeyAlgorithmIdentifier field of privateKeyInfo is present, then throw a DataError .
7. Let slhDsaPrivateKey be the result of performing the parse an ASN.1 structure algorithm, with data as the privateKey field of privateKeyInfo, structure as OCTET STRING, and exactData set to true.
8. If an error occurred while parsing, then throw a DataError .
9. Let key be a new CryptoKey that represents the SLH-DSA private key identified by slhDsaPrivateKey.
10. Set the [[type]] internal slot of key to " private "
11. Let algorithm be a new KeyAlgorithm .
12. Set the name attribute of algorithm to the name attribute of normalizedAlgorithm.
13. Set the [[algorithm]] internal slot of key to algorithm.
14. Set the [[extractable]] internal slot of key to extractable.
15. Set the [[usages]] internal slot of key to usages.
If format is " raw-public ":
1. If usages contains a value which is not " verify " then throw a SyntaxError .
2. Let algorithm be a new KeyAlgorithm object.
3. Set the name attribute of algorithm to the name attribute of normalizedAlgorithm.
4. If the length of keyData is not the pk length specified by Table 2 of [ FIPS-205 ] for the parameter set indicated by the name member of normalizedAlgorithm, then throw a DataError .
5. Let key be a new CryptoKey representing the key data provided in keyData.
6. Set the [[type]] internal slot of key to " public "
7. Set the [[algorithm]] internal slot of key to algorithm.
If format is " raw-private ":
1. If usages contains an entry which is not " sign " then throw a SyntaxError .
2. If the length of keyData is not 2 * the pk length specified by Table 2 of [ FIPS-205 ] for the parameter set indicated by the name member of normalizedAlgorithm, then throw a DataError .
3. Let key be a new CryptoKey representing the key data provided in keyData.
4. Set the [[type]] internal slot of key to " private ".
5. Let algorithm be a new KeyAlgorithm .
6. Set the name attribute of algorithm to the name attribute of normalizedAlgorithm.
7. Set the [[algorithm]] internal slot of key to algorithm.
If format is " jwk ":
1. If keyData is a JsonWebKey dictionary:
  
  Let jwk equal keyData.
  
  Otherwise:
  
  Throw a DataError .
2. If the priv field is present and usages contains a value which is not " sign ", or, if the priv field is not present and usages contains a value which is not " verify " then throw a SyntaxError .
3. If the kty field of jwk is not " AKP ", then throw a DataError .
4. If the alg field of jwk is not equal to the name member of normalizedAlgorithm, then throw a DataError .
5. If usages is non-empty and the use field of jwk is present and is not equal to " sig ", then throw a DataError .
6. If the key_ops field of jwk is present, and is invalid according to the requirements of JSON Web Key [ JWK ], or it does not contain all of the specified usages values, then throw a DataError .
7. If the ext field of jwk is present and has the value false and extractable is true, then throw a DataError .
8. If the priv field of jwk is present:
  
  If the priv attribute of jwk does not contain a valid base64url encoded value representing an SLH-DSA private key, then throw a DataError .
  
  Let key be a new CryptoKey object that represents the SLH-DSA private key identified by interpreting the priv attribute of jwk as a base64url encoded private key.
  
  Set the [[type]] internal slot of Key to " private ".
  
  If the pub attribute of jwk does not contain the base64url encoded public key representing the SLH-DSA public key corresponding to key, then throw a DataError .
  
  Otherwise:
  
  If the pub attribute of jwk does not contain a valid base64url encoded public key representing an SLH-DSA public key, then throw a DataError .
  
  Let key be a new CryptoKey object that represents the SLH-DSA public key identified by interpreting the pub attribute of jwk as a base64url encoded public key.
  
  Set the [[type]] internal slot of Key to " public ".
9. Let algorithm be a new instance of a KeyAlgorithm object.
10. Set the name attribute of algorithm to the name member of normalizedAlgorithm.
11. Set the [[algorithm]] internal slot of key to algorithm.
Otherwise:

throw a NotSupportedError .
Return key

Let key be the CryptoKey to be exported.
If the underlying cryptographic key material represented by the [[handle]] internal slot of key cannot be accessed, then throw an OperationError .
If format is " spki ":
1. If the [[type]] internal slot of key is not " public ", then throw an InvalidAccessError .
2. Let data be an instance of the SubjectPublicKeyInfo ASN.1 structure defined in [ RFC5280 ] with the following properties:
  - Set the algorithm field to an AlgorithmIdentifier ASN.1 type with the following properties:
    
    If the name member of normalizedAlgorithm is " SLH-DSA-SHA2-128s ":
    
    Set the algorithm object identifier to the id-slh-dsa-sha2-128s (2.16.840.1.101.3.4.3.20) OID.
    
    If the name member of normalizedAlgorithm is " SLH-DSA-SHA2-128f ":
    
    Set the algorithm object identifier to the id-slh-dsa-sha2-128f (2.16.840.1.101.3.4.3.21) OID.
    
    If the name member of normalizedAlgorithm is " SLH-DSA-SHA2-192s ":
    
    Set the algorithm object identifier to the id-slh-dsa-sha2-192s (2.16.840.1.101.3.4.3.22) OID.
    
    If the name member of normalizedAlgorithm is " SLH-DSA-SHA2-192f ":
    
    Set the algorithm object identifier to the id-slh-dsa-sha2-192f (2.16.840.1.101.3.4.3.23) OID.
    
    If the name member of normalizedAlgorithm is " SLH-DSA-SHA2-256s ":
    
    Set the algorithm object identifier to the id-slh-dsa-sha2-256s (2.16.840.1.101.3.4.3.24) OID.
    
    If the name member of normalizedAlgorithm is " SLH-DSA-SHA2-256f ":
    
    Set the algorithm object identifier to the id-slh-dsa-sha2-256f (2.16.840.1.101.3.4.3.25) OID.
    
    If the name member of normalizedAlgorithm is " SLH-DSA-SHAKE-128s ":
    
    Set the algorithm object identifier to the id-slh-dsa-shake-128s (2.16.840.1.101.3.4.3.26) OID.
    
    If the name member of normalizedAlgorithm is " SLH-DSA-SHAKE-128f ":
    
    Set the algorithm object identifier to the id-slh-dsa-shake-128f (2.16.840.1.101.3.4.3.27) OID.
    
    If the name member of normalizedAlgorithm is " SLH-DSA-SHAKE-192s ":
    
    Set the algorithm object identifier to the id-slh-dsa-shake-192s (2.16.840.1.101.3.4.3.28) OID.
    
    If the name member of normalizedAlgorithm is " SLH-DSA-SHAKE-192f ":
    
    Set the algorithm object identifier to the id-slh-dsa-shake-192f (2.16.840.1.101.3.4.3.29) OID.
    
    If the name member of normalizedAlgorithm is " SLH-DSA-SHAKE-256s ":
    
    Set the algorithm object identifier to the id-slh-dsa-shake-256s (2.16.840.1.101.3.4.3.30) OID.
    
    If the name member of normalizedAlgorithm is " SLH-DSA-SHAKE-256f ":
    
    Set the algorithm object identifier to the id-slh-dsa-shake-256f (2.16.840.1.101.3.4.3.31) OID.
    
    Otherwise:
    
    throw a NotSupportedError .
  - Set the subjectPublicKey field to keyData.
3. Let result be the result of DER-encoding data.
If format is " pkcs8 ":
1. If the [[type]] internal slot of key is not " private ", then throw an InvalidAccessError .
2. Let data be an instance of the PrivateKeyInfo ASN.1 structure defined in [ RFC5208 ] with the following properties:
  - Set the version field to 0.
  - Set the privateKeyAlgorithm field to a PrivateKeyAlgorithmIdentifier ASN.1 type with the following properties:
    
    If the name member of normalizedAlgorithm is " SLH-DSA-SHA2-128s ":
    
    Set the algorithm object identifier to the id-slh-dsa-sha2-128s (2.16.840.1.101.3.4.3.20) OID.
    
    If the name member of normalizedAlgorithm is " SLH-DSA-SHA2-128f ":
    
    Set the algorithm object identifier to the id-slh-dsa-sha2-128f (2.16.840.1.101.3.4.3.21) OID.
    
    If the name member of normalizedAlgorithm is " SLH-DSA-SHA2-192s ":
    
    Set the algorithm object identifier to the id-slh-dsa-sha2-192s (2.16.840.1.101.3.4.3.22) OID.
    
    If the name member of normalizedAlgorithm is " SLH-DSA-SHA2-192f ":
    
    Set the algorithm object identifier to the id-slh-dsa-sha2-192f (2.16.840.1.101.3.4.3.23) OID.
    
    If the name member of normalizedAlgorithm is " SLH-DSA-SHA2-256s ":
    
    Set the algorithm object identifier to the id-slh-dsa-sha2-256s (2.16.840.1.101.3.4.3.24) OID.
    
    If the name member of normalizedAlgorithm is " SLH-DSA-SHA2-256f ":
    
    Set the algorithm object identifier to the id-slh-dsa-sha2-256f (2.16.840.1.101.3.4.3.25) OID.
    
    If the name member of normalizedAlgorithm is " SLH-DSA-SHAKE-128s ":
    
    Set the algorithm object identifier to the id-slh-dsa-shake-128s (2.16.840.1.101.3.4.3.26) OID.
    
    If the name member of normalizedAlgorithm is " SLH-DSA-SHAKE-128f ":
    
    Set the algorithm object identifier to the id-slh-dsa-shake-128f (2.16.840.1.101.3.4.3.27) OID.
    
    If the name member of normalizedAlgorithm is " SLH-DSA-SHAKE-192s ":
    
    Set the algorithm object identifier to the id-slh-dsa-shake-192s (2.16.840.1.101.3.4.3.28) OID.
    
    If the name member of normalizedAlgorithm is " SLH-DSA-SHAKE-192f ":
    
    Set the algorithm object identifier to the id-slh-dsa-shake-192f (2.16.840.1.101.3.4.3.29) OID.
    
    If the name member of normalizedAlgorithm is " SLH-DSA-SHAKE-256s ":
    
    Set the algorithm object identifier to the id-slh-dsa-shake-256s (2.16.840.1.101.3.4.3.30) OID.
    
    If the name member of normalizedAlgorithm is " SLH-DSA-SHAKE-256f ":
    
    Set the algorithm object identifier to the id-slh-dsa-shake-256f (2.16.840.1.101.3.4.3.31) OID.
    
    Otherwise:
    
    throw a NotSupportedError .
  - Set the privateKey field to the result of DER-encoding a OCTET STRING ASN.1 type that represents the SLH-DSA private key represented by the [[handle]] internal slot of key
3. Let result be the result of DER-encoding data.
If format is " raw-public ":
1. If the [[type]] internal slot of key is not " public ", then throw an InvalidAccessError .
2. Let data be a byte sequence containing the SLH-DSA public key represented by the [[handle]] internal slot of key.
3. Let result be data.
If format is " raw-private ":
1. If the [[type]] internal slot of key is not " private ", then throw an InvalidAccessError .
2. Let data be a byte sequence containing the SLH-DSA private key represented by the [[handle]] internal slot of key.
3. Let result be data.
If format is " jwk ":
1. Let jwk be a new JsonWebKey dictionary.
2. Set the kty attribute of jwk to " AKP ".
3. Set the alg attribute of jwk to the name member of normalizedAlgorithm.
4. Set the pub attribute of jwk to the base64url encoded public key corresponding to the [[handle]] internal slot of key.
5. If the [[type]] internal slot of key is " private ":
  
  Set the priv attribute of jwk to the base64url encoded private key represented by the [[handle]] internal slot of key.
6. Set the key_ops attribute of jwk to the usages attribute of key.
7. Set the ext attribute of jwk to the [[extractable]] internal slot of key.
8. Let result be jwk.
Otherwise:

throw a NotSupportedError .
Return result.

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`	byte sequence
decrypt	`AeadParams`	byte sequence
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.

Note

The AeadParams dictionary is identical to the AesGcmParams dictionary of [ webcrypto ], 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 .
If the tagLength member of normalizedAlgorithm is not present:

Let tagLength be 128.

If the tagLength member of normalizedAlgorithm is one of 64, 96 or 128:

Let tagLength be equal to the tagLength member of normalizedAlgorithm

Otherwise:

throw an OperationError .
Let additionalData be 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 iv member of normalizedAlgorithm as the N input parameter, additionalData as the A input parameter, plaintext as the P input parameter, and tagLength as the TAGLEN global parameter.
Return C.

If the iv member of normalizedAlgorithm has a length greater than 15 bytes, then throw an OperationError .
If the tagLength member of normalizedAlgorithm is not present:

Let tagLength be 128.

If the tagLength member of normalizedAlgorithm is one of 64, 96 or 128:

Let tagLength be equal to the tagLength member of normalizedAlgorithm

Otherwise:

throw an OperationError .
If ciphertext has a length less than tagLength bits, then throw an OperationError .
Let additionalData be 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 iv member of normalizedAlgorithm as the N input parameter, additionalData as the A input parameter, ciphertext as the C input parameter, and tagLength as the TAGLEN global parameter.

If the result of the algorithm is the indication of authentication failure, "INVALID":

throw an OperationError

Otherwise:

Let plaintext be the output P of OCB-DECRYPT.
Return 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.

Let keyData be the key data to be imported.
If usages contains an entry which is not one of " encrypt ", " decrypt ", " wrapKey " or " unwrapKey ", then throw a SyntaxError .
If format is " raw-secret ":
1. Let data be keyData.
2. If the length in bits of data is not 128, 192 or 256 then throw a DataError .
If format is " jwk ":
1. If keyData is a JsonWebKey dictionary:
  
  Let jwk equal keyData.
  
  Otherwise:
  
  Throw a DataError .
2. If the kty field of jwk is not " oct ", then throw a DataError .
3. If jwk does not meet the requirements of Section 6.4 of JSON Web Algorithms [ JWA ], then throw a DataError .
4. Let data be the byte sequence obtained by decoding the k field of jwk.
5. If data has length 128 bits:
  
  If the alg field of jwk is present, and is not " A128OCB ", then throw a DataError .
  
  If data has length 192 bits:
  
  If the alg field of jwk is present, and is not " A192OCB ", then throw a DataError .
  
  If data has length 256 bits:
  
  If the alg field of jwk is present, and is not " A256OCB ", then throw a DataError .
  
  Otherwise:
  
  throw a DataError .
6. If usages is non-empty and the use field of jwk is present and is not " enc ", then throw a DataError .
7. 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 .
8. If the ext field of jwk is present and has the value false and extractable is true, then throw a DataError .
Otherwise:

throw a 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 .
If format is " raw-secret ":
1. Let data be a byte sequence containing the raw octets of the key represented by [[handle]] internal slot of key.
2. Let result be data.
If format is " jwk ":
1. Let jwk be a new JsonWebKey dictionary.
2. Set the kty attribute of jwk to the string " oct ".
3. 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 ].
4. If the length attribute of key is 128:
  
  Set the alg attribute of jwk to the string " A128OCB ".
  
  If the length attribute of key is 192:
  
  Set the alg attribute of jwk to the string " A192OCB ".
  
  If the length attribute of key is 256:
  
  Set the alg attribute of jwk to the string " A256OCB ".
5. Set the key_ops attribute of jwk to equal the usages attribute of key.
6. Set the ext attribute of jwk to equal the [[extractable]] internal slot of key.
7. Let result be the result of converting jwk to an ECMAScript Object, as defined by [ WebIDL ].
Otherwise:

throw a NotSupportedError .
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`	byte sequence
decrypt	`AeadParams`	byte sequence
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 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 iv member of normalizedAlgorithm as the nonce input parameter, plaintext as the plaintext input parameter, and additionalData as the additional authenticated data (AAD) input parameter.
Return ciphertext.

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 .
If ciphertext has a length less than 128 bits, then throw an OperationError .
Let additionalData be 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 iv member of normalizedAlgorithm as the nonce input parameter, ciphertext as the ciphertext input parameter, and additionalData as the additional authenticated data (AAD) input parameter.

If the result of the algorithm is the indication of authentication failure:

throw an OperationError

Otherwise:

Let plaintext be the resulting plaintext.
Return 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.

Let keyData be the key data to be imported.
If usages contains an entry which is not one of " encrypt ", " decrypt ", " wrapKey " or " unwrapKey ", then throw a SyntaxError .
If format is " raw-secret ":
1. Let data be keyData.
2. If the length in bits of data is not 256 then throw a DataError .
If format is " jwk ":
1. If keyData is a JsonWebKey dictionary:
  
  Let jwk equal keyData.
  
  Otherwise:
  
  Throw a DataError .
2. If the kty field of jwk is not " oct ", then throw a DataError .
3. If jwk does not meet the requirements of Section 6.4 of JSON Web Algorithms [ JWA ], then throw a DataError .
4. Let data be the byte sequence obtained by decoding the k field of jwk.
5. If the alg field of jwk is present, and is not " C20P ", then throw a DataError .
6. If usages is non-empty and the use field of jwk is present and is not " enc ", then throw a DataError .
7. 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 .
8. If the ext field of jwk is present and has the value false and extractable is true, then throw a DataError .
Otherwise:

throw a 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 .
If format is " raw-secret ":
1. Let data be a byte sequence containing the raw octets of the key represented by [[handle]] internal slot of key.
2. Let result be data.
If format is " jwk ":
1. Let jwk be a new JsonWebKey dictionary.
2. Set the kty attribute of jwk to the string " oct ".
3. 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 ].
4. Set the alg attribute of jwk to the string " C20P ".
5. Set the key_ops attribute of jwk to equal the usages attribute of key.
6. Set the ext attribute of jwk to equal the [[extractable]] internal slot of key.
7. Let result be the result of converting jwk to an ECMAScript Object, as defined by [ WebIDL ].
Otherwise:

throw a NotSupportedError .
Return result.

Return 256.

Operation	Parameters	Result
digest	None	byte sequence

Operation	Parameters	Result
digest	`CShakeParams`	byte sequence

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`	byte sequence
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 customization member of normalizedAlgorithm if present or the empty octet string otherwise.
If the name member of normalizedAlgorithm is a case-sensitive string match for " KMAC128 ":

Let mac be the result of performing the KMAC128 function defined in Section 4 of [ NIST-SP800-185 ] using the key represented by [[handle]] internal slot of key as the K input parameter, message as the X input parameter, the length member of normalizedAlgorithm as the L input parameter, and customization as the S input parameter.

If the name member of normalizedAlgorithm is a case-sensitive string match for " KMAC256 ":

Let mac be the result of performing the KMAC256 function defined in Section 4 of [ NIST-SP800-185 ] using the key represented by [[handle]] internal slot of key as the K input parameter, message as the X input parameter, the length member of normalizedAlgorithm as the L input parameter, and customization as the S input parameter.
Return mac.

Let customization be the customization member of normalizedAlgorithm if present or the empty octet string otherwise.
If the name member of normalizedAlgorithm is a case-sensitive string match for " KMAC128 ":

Let mac be the result of performing the KMAC128 function defined in Section 4 of [ NIST-SP800-185 ] using the key represented by [[handle]] internal slot of key as the K input parameter, message as the X input parameter, the length member of normalizedAlgorithm as the L input parameter, and customization as the S input parameter.

If the name member of normalizedAlgorithm is a case-sensitive string match for " KMAC256 ":

Let mac be the result of performing the KMAC256 function defined in Section 4 of [ NIST-SP800-185 ] using the key represented by [[handle]] internal slot of key as the K input parameter, message as the X input parameter, the 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 .
If the length member of normalizedAlgorithm is present:

Let length be equal to the length member of normalizedAlgorithm.

Otherwise, if the name member of normalizedAlgorithm is a case-sensitive string match for " KMAC128 ":

Let length be 128.

Otherwise, if the name member of normalizedAlgorithm is a case-sensitive string match for " KMAC256 ":

Let length be 256.
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 .
If format is " raw-secret ":
1. Let data be keyData.
If format is " jwk ":
1. If keyData is a JsonWebKey dictionary:
  
  Let jwk equal keyData.
  
  Otherwise:
  
  Throw a DataError .
2. If the kty field of jwk is not " oct ", then throw a DataError .
3. If jwk does not meet the requirements of Section 6.4 of JSON Web Algorithms [ JWA ], then throw a DataError .
4. Let data be the byte sequence obtained by decoding the k field of jwk.
5. If the name member of normalizedAlgorithm is a case-sensitive string match for " KMAC128 ":
  
  If the alg field of jwk is present and is not " K128 ", then throw a DataError .
  
  If the name member of normalizedAlgorithm is a case-sensitive string match for " KMAC256 ":
  
  If the alg field of jwk is present and is not " K256 ", then throw a DataError .
6. If usages is non-empty and the use field of jwk is present and is not " sign ", then throw a DataError .
7. 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 .
8. If the ext field of jwk is present and has the value false and extractable is true, then throw a DataError .
Otherwise:

throw a NotSupportedError .
Let length be the length in bits of data.
If length is zero then throw a DataError .
If the length member of normalizedAlgorithm is present:

If the length member of normalizedAlgorithm is greater than length:

throw a DataError .

If the length member of normalizedAlgorithm, is less than or equal to length minus eight:

throw a DataError .

Otherwise:

Set length equal to the length member of normalizedAlgorithm.
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 byte sequence containing bits.
If format is " raw-secret ":
1. Let result be data.
If format is " jwk ":
1. Let jwk be a new JsonWebKey dictionary.
2. Set the kty attribute of jwk to the string " oct ".
3. Set the k attribute of jwk to be a string containing data, encoded according to Section 6.4 of JSON Web Algorithms [ JWA ].
4. Let algorithm be the [[algorithm]] internal slot of key.
5. If the name member of normalizedAlgorithm is a case-sensitive string match for " KMAC128 ":
  
  Set the alg attribute of jwk to the string " K128 ".
  
  If the name member of normalizedAlgorithm is a case-sensitive string match for " KMAC256 ":
  
  Set the alg attribute of jwk to the string " K256 ".
6. Set the key_ops attribute of jwk to equal the usages attribute of key.
7. Set the ext attribute of jwk to equal the [[extractable]] internal slot of key.
8. Let result be the result of converting jwk to an ECMAScript Object, as defined by [ WebIDL ].
Otherwise:

throw a NotSupportedError .
Return result.

If the length member of normalizedAlgorithm is present:

Let length be equal to the length member of normalizedAlgorithm.

Otherwise, if the name member of normalizedAlgorithm is a case-sensitive string match for " KMAC128 ":

Let length be 128.

Otherwise, if the name member of normalizedAlgorithm is a case-sensitive string match for " KMAC256 ":

Let length be 256.
Return length.

JSON Web Key	AlgorithmIdentifier
`{ kty: "oct", alg : "A128OCB" }`	`{ name: "AES-OCB", length : 128 }`
`{ kty: "oct", alg : "A192OCB" }`	`{ name: "AES-OCB", length : 192 }`
`{ kty: "oct", alg : "A256OCB" }`	`{ name: "AES-OCB", length : 256 }`
`{ kty: "oct", alg : "C20P" }`	`{ name : "ChaCha20-Poly1305" }`
`{ kty: "oct", alg : "K128" }`	`{ name : "KMAC128" }`
`{ kty: "oct", alg : "K256" }`	`{ name : "KMAC256" }`

Algorithm OID	subjectPublicKey ASN.1 structure	AlgorithmIdentifier	Reference
id-ml-dsa-44 (2.16.840.1.101.3.4.3.17)	BIT STRING	" `ML-DSA-44` "	[ CSOR ], [ draft-ietf-lamps-dilithium-certificates ]
id-ml-dsa-65 (2.16.840.1.101.3.4.3.18)	BIT STRING	" `ML-DSA-65` "	[ CSOR ], [ draft-ietf-lamps-dilithium-certificates ]
id-ml-dsa-87 (2.16.840.1.101.3.4.3.19)	BIT STRING	" `ML-DSA-87` "	[ CSOR ], [ draft-ietf-lamps-dilithium-certificates ]
id-alg-ml-kem-512 (2.16.840.1.101.3.4.4.1)	BIT STRING	" `ML-KEM-512` "	[ CSOR ], [ draft-ietf-lamps-kyber-certificates ]
id-alg-ml-kem-768 (2.16.840.1.101.3.4.4.2)	BIT STRING	" `ML-KEM-768` "	[ CSOR ], [ draft-ietf-lamps-kyber-certificates ]
id-alg-ml-kem-1024 (2.16.840.1.101.3.4.4.3)	BIT STRING	" `ML-KEM-1024` "	[ CSOR ], [ draft-ietf-lamps-kyber-certificates ]
id-slh-dsa-sha2-128s (2.16.840.1.101.3.4.3.20)	BIT STRING	" `SLH-DSA-SHA2-128s` "	[ CSOR ], [ RFC9814 ]
id-slh-dsa-sha2-128f (2.16.840.1.101.3.4.3.21)	BIT STRING	" `SLH-DSA-SHA2-128f` "	[ CSOR ], [ RFC9814 ]
id-slh-dsa-sha2-192s (2.16.840.1.101.3.4.3.22)	BIT STRING	" `SLH-DSA-SHA2-192s` "	[ CSOR ], [ RFC9814 ]
id-slh-dsa-sha2-192f (2.16.840.1.101.3.4.3.23)	BIT STRING	" `SLH-DSA-SHA2-192f` "	[ CSOR ], [ RFC9814 ]
id-slh-dsa-sha2-256s (2.16.840.1.101.3.4.3.24)	BIT STRING	" `SLH-DSA-SHA2-256s` "	[ CSOR ], [ RFC9814 ]
id-slh-dsa-sha2-256f (2.16.840.1.101.3.4.3.25)	BIT STRING	" `SLH-DSA-SHA2-256f` "	[ CSOR ], [ RFC9814 ]
id-slh-dsa-shake-128s (2.16.840.1.101.3.4.3.26)	BIT STRING	" `SLH-DSA-SHAKE-128s` "	[ CSOR ], [ RFC9814 ]
id-slh-dsa-shake-128f (2.16.840.1.101.3.4.3.27)	BIT STRING	" `SLH-DSA-SHAKE-128f` "	[ CSOR ], [ RFC9814 ]
id-slh-dsa-shake-192s (2.16.840.1.101.3.4.3.28)	BIT STRING	" `SLH-DSA-SHAKE-192s` "	[ CSOR ], [ RFC9814 ]
id-slh-dsa-shake-192f (2.16.840.1.101.3.4.3.29)	BIT STRING	" `SLH-DSA-SHAKE-192f` "	[ CSOR ], [ RFC9814 ]
id-slh-dsa-shake-256s (2.16.840.1.101.3.4.3.30)	BIT STRING	" `SLH-DSA-SHAKE-256s` "	[ CSOR ], [ RFC9814 ]
id-slh-dsa-shake-256f (2.16.840.1.101.3.4.3.31)	BIT STRING	" `SLH-DSA-SHAKE-256f` "	[ CSOR ], [ RFC9814 ]

Operation	Parameters	Result
deriveBits	`Argon2Params`	byte sequence
importKey	None	`CryptoKey`
Get key length	None	null

privateKeyAlgorithm	privateKey format	AlgorithmIdentifier	Reference
id-ml-dsa-44 (2.16.840.1.101.3.4.3.17)	ML-DSA-44-PrivateKey	" `ML-DSA-44` "	[ CSOR ], [ draft-ietf-lamps-dilithium-certificates ]
id-ml-dsa-65 (2.16.840.1.101.3.4.3.18)	ML-DSA-65-PrivateKey	" `ML-DSA-65` "	[ CSOR ], [ draft-ietf-lamps-dilithium-certificates ]
id-ml-dsa-87 (2.16.840.1.101.3.4.3.19)	ML-DSA-87-PrivateKey	" `ML-DSA-87` "	[ CSOR ], [ draft-ietf-lamps-dilithium-certificates ]
id-alg-ml-kem-512 (2.16.840.1.101.3.4.4.1)	ML-KEM-512-PrivateKey	" `ML-KEM-512` "	[ CSOR ], [ draft-ietf-lamps-kyber-certificates ]
id-alg-ml-kem-768 (2.16.840.1.101.3.4.4.2)	ML-KEM-768-PrivateKey	" `ML-KEM-768` "	[ CSOR ], [ draft-ietf-lamps-kyber-certificates ]
id-alg-ml-kem-1024 (2.16.840.1.101.3.4.4.3)	ML-KEM-1024-PrivateKey	" `ML-KEM-1024` "	[ CSOR ], [ draft-ietf-lamps-kyber-certificates ]
id-slh-dsa-sha2-128s (2.16.840.1.101.3.4.3.20)	OCTET STRING	" `SLH-DSA-SHA2-128s` "	[ CSOR ], [ RFC9814 ]
id-slh-dsa-sha2-128f (2.16.840.1.101.3.4.3.21)	OCTET STRING	" `SLH-DSA-SHA2-128f` "	[ CSOR ], [ RFC9814 ]
id-slh-dsa-sha2-192s (2.16.840.1.101.3.4.3.22)	OCTET STRING	" `SLH-DSA-SHA2-192s` "	[ CSOR ], [ RFC9814 ]
id-slh-dsa-sha2-192f (2.16.840.1.101.3.4.3.23)	OCTET STRING	" `SLH-DSA-SHA2-192f` "	[ CSOR ], [ RFC9814 ]
id-slh-dsa-sha2-256s (2.16.840.1.101.3.4.3.24)	OCTET STRING	" `SLH-DSA-SHA2-256s` "	[ CSOR ], [ RFC9814 ]
id-slh-dsa-sha2-256f (2.16.840.1.101.3.4.3.25)	OCTET STRING	" `SLH-DSA-SHA2-256f` "	[ CSOR ], [ RFC9814 ]
id-slh-dsa-shake-128s (2.16.840.1.101.3.4.3.26)	OCTET STRING	" `SLH-DSA-SHAKE-128s` "	[ CSOR ], [ RFC9814 ]
id-slh-dsa-shake-128f (2.16.840.1.101.3.4.3.27)	OCTET STRING	" `SLH-DSA-SHAKE-128f` "	[ CSOR ], [ RFC9814 ]
id-slh-dsa-shake-192s (2.16.840.1.101.3.4.3.28)	OCTET STRING	" `SLH-DSA-SHAKE-192s` "	[ CSOR ], [ RFC9814 ]
id-slh-dsa-shake-192f (2.16.840.1.101.3.4.3.29)	OCTET STRING	" `SLH-DSA-SHAKE-192f` "	[ CSOR ], [ RFC9814 ]
id-slh-dsa-shake-256s (2.16.840.1.101.3.4.3.30)	OCTET STRING	" `SLH-DSA-SHAKE-256s` "	[ CSOR ], [ RFC9814 ]
id-slh-dsa-shake-256f (2.16.840.1.101.3.4.3.31)	OCTET STRING	" `SLH-DSA-SHAKE-256f` "	[ CSOR ], [ RFC9814 ]

Modern Algorithms in the Web Cryptography API

Abstract

Status of This Document

1. Introduction

2. Specification Conventions

3. Partial SubtleCrypto interface

3.1 Data Types

3.1.1 Key Formats

3.1.2 Key Usages

3.2 Methods and Parameters

3.2.1 The encapsulateKey method

3.2.2 The encapsulateBits method

3.2.3 The decapsulateKey method

3.2.4 The decapsulateBits method

3.2.5 The getPublicKey method

3.2.6 The supports method

3.3 Checking support for an algorithm

4. Encapsulation dictionaries

5. JsonWebKey dictionary

6. ML-KEM

6.1 Description

6.2 Registration

6.3 Operations

6.3.1 Encapsulate

6.3.2 Decapsulate

6.3.3 Generate Key

6.3.4 Import Key

6.3.5 Export Key

7. ML-DSA

7.1 Description

7.2 Registration

7.3 ContextParams dictionary

7.4 Operations

7.4.1 Sign

7.4.2 Verify

7.4.3 Generate Key

7.4.4 Import Key

7.4.5 Export Key

8. SLH-DSA

8.1 Description

8.2 Registration

8.3 Operations

8.3.1 Sign

8.3.2 Verify

8.3.3 Generate Key

8.3.4 Import Key

8.3.5 Export Key

9. AES-OCB

9.1 Description

9.2 Registration

9.3 AeadParams dictionary

9.4 Operations

9.4.1 Encrypt

9.4.2 Decrypt

9.4.3 Generate Key

9.4.4 Import Key

9.4.5 Export Key

9.4.6 Get key length

10. ChaCha20-Poly1305

10.1 Description

10.2 Registration

10.3 Operations

10.3.1 Encrypt

10.3.2 Decrypt

10.3.3 Generate Key

10.3.4 Import Key

10.3.5 Export Key

10.3.6 Get key length

11. SHA-3

11.1 Description

11.2 Registration

11.3 Operations

11.3.1 Digest

12. cSHAKE

12.1 Description

12.2 Registration

12.3 CShakeParams dictionary

12.4 Operations

12.4.1 Digest

13. KMAC

7.3 `ContextParams` dictionary

9.3 `AeadParams` dictionary

12.3 `CShakeParams` dictionary

13.3 `KmacKeyGenParams` dictionary

13.4 `KmacImportParams` dictionary

13.5 `KmacKeyAlgorithm` dictionary

13.6 `KmacParams` dictionary

14.3 `Argon2Params` dictionary