On this page

C

SubtleCrypto

History
S

SubtleCrypto.supports

History
SubtleCrypto.supports(operation, algorithm, lengthOrAdditionalAlgorithm?): boolean
Stability: 1.1Active development
Attributes
operation:string
"encrypt", "decrypt", "sign", "verify", "digest", "generateKey", "deriveKey", "deriveBits", "importKey", "exportKey", "getPublicKey", "wrapKey", "unwrapKey", "encapsulateBits", "encapsulateKey", "decapsulateBits", or "decapsulateKey"
algorithm:string | Algorithm
lengthOrAdditionalAlgorithm?:null | number | string | Algorithm | undefined
Depending on the operation this is either ignored, the value of the length argument when operation is "deriveBits", the algorithm of key to be derived when operation is "deriveKey", the algorithm of key to be exported before wrapping when operation is "wrapKey", the algorithm of key to be imported after unwrapping when operation is "unwrapKey", or the algorithm of key to be imported after en/decapsulating a key when operation is "encapsulateKey" or "decapsulateKey". Default: null when operation is "deriveBits", undefined otherwise.
Returns:boolean
Indicating whether the implementation supports the given operation

Allows feature detection in Web Crypto API, which can be used to detect whether a given algorithm identifier (including its parameters) is supported for the given operation.

See Checking for runtime algorithm support for an example use of this method.

M

subtle.decapsulateBits

History
subtle.decapsulateBits(decapsulationAlgorithm, decapsulationKey, ciphertext): Promise
Stability: 1.1Active development
Attributes
decapsulationAlgorithm:string | Algorithm
decapsulationKey:CryptoKey
ciphertext:ArrayBuffer | TypedArray | DataView | Buffer
Returns:Promise
Fulfills with ArrayBuffer upon success.

A message recipient uses their asymmetric private key to decrypt an "encapsulated key" (ciphertext), thereby recovering a temporary symmetric key (represented as ArrayBuffer) which is then used to decrypt a message.

The algorithms currently supported include:

  • 'ML-KEM-512'1
  • 'ML-KEM-768'1
  • 'ML-KEM-1024'1
M

subtle.decapsulateKey

History
subtle.decapsulateKey(decapsulationAlgorithm, decapsulationKey, ciphertext, sharedKeyAlgorithm, extractable, keyUsages): Promise
Stability: 1.1Active development
Attributes
decapsulationAlgorithm:string | Algorithm
decapsulationKey:CryptoKey
ciphertext:ArrayBuffer | TypedArray | DataView | Buffer
sharedKeyAlgorithm:string | Algorithm | HmacImportParams | AesDerivedKeyParams | KmacImportParams
extractable:boolean
keyUsages:string[]
See Key usages.
Returns:Promise
Fulfills with CryptoKey upon success.

A message recipient uses their asymmetric private key to decrypt an "encapsulated key" (ciphertext), thereby recovering a temporary symmetric key (represented as CryptoKey) which is then used to decrypt a message.

The algorithms currently supported include:

  • 'ML-KEM-512'1
  • 'ML-KEM-768'1
  • 'ML-KEM-1024'1
subtle.decrypt(algorithm, key, data): Promise
Attributes
algorithm:RsaOaepParams | AesCtrParams | AesCbcParams | AeadParams
key:CryptoKey
data:ArrayBuffer | TypedArray | DataView | Buffer
Returns:Promise
Fulfills with an ArrayBuffer upon success.

Using the method and parameters specified in algorithm and the keying material provided by key, this method attempts to decipher the provided data. If successful, the returned promise will be resolved with an ArrayBuffer containing the plaintext result.

The algorithms currently supported include:

  • 'AES-CBC'
  • 'AES-CTR'
  • 'AES-GCM'
  • 'AES-OCB'1
  • 'ChaCha20-Poly1305'1
  • 'RSA-OAEP'
subtle.deriveBits(algorithm, baseKey, length?): Promise
Attributes
algorithm:EcdhKeyDeriveParams | HkdfParams | Pbkdf2Params | Argon2Params
baseKey:CryptoKey
length?:number | null
Default: null
Returns:Promise
Fulfills with an ArrayBuffer upon success.

Using the method and parameters specified in algorithm and the keying material provided by baseKey, this method attempts to generate length bits.

When length is not provided or null the maximum number of bits for a given algorithm is generated. This is allowed for the 'ECDH', 'X25519', and 'X448'2 algorithms, for other algorithms length is required to be a number.

If successful, the returned promise will be resolved with an ArrayBuffer containing the generated data.

The algorithms currently supported include:

  • 'Argon2d'1
  • 'Argon2i'1
  • 'Argon2id'1
  • 'ECDH'
  • 'HKDF'
  • 'PBKDF2'
  • 'X25519'
  • 'X448'2
subtle.deriveKey(algorithm, baseKey, derivedKeyType, extractable, keyUsages): Promise
Attributes
algorithm:EcdhKeyDeriveParams | HkdfParams | Pbkdf2Params | Argon2Params
baseKey:CryptoKey
derivedKeyType:string | Algorithm | HmacImportParams | AesDerivedKeyParams | KmacImportParams
extractable:boolean
keyUsages:string[]
See Key usages.
Returns:Promise
Fulfills with a CryptoKey upon success.

Using the method and parameters specified in algorithm, and the keying material provided by baseKey, this method attempts to generate a new CryptoKey based on the method and parameters in derivedKeyType.

Calling this method is equivalent to calling subtle.deriveBits() to generate raw keying material, then passing the result into the subtle.importKey() method using the derivedKeyType, extractable, and keyUsages parameters as input.

The algorithms currently supported include:

  • 'Argon2d'1
  • 'Argon2i'1
  • 'Argon2id'1
  • 'ECDH'
  • 'HKDF'
  • 'PBKDF2'
  • 'X25519'
  • 'X448'2
subtle.digest(algorithm, data): Promise
Attributes
algorithm:string | Algorithm | CShakeParams | TurboShakeParams | KangarooTwelveParams
data:ArrayBuffer | TypedArray | DataView | Buffer
Returns:Promise
Fulfills with an ArrayBuffer upon success.

Using the method identified by algorithm, this method attempts to generate a digest of data. If successful, the returned promise is resolved with an ArrayBuffer containing the computed digest.

If algorithm is provided as a string, it must be one of:

  • 'cSHAKE128'1
  • 'cSHAKE256'1
  • 'KT128'1
  • 'KT256'1
  • 'SHA-1'
  • 'SHA-256'
  • 'SHA-384'
  • 'SHA-512'
  • 'SHA3-256'1
  • 'SHA3-384'1
  • 'SHA3-512'1
  • 'TurboSHAKE128'1
  • 'TurboSHAKE256'1

If algorithm is provided as an Object, it must have a name property whose value is one of the above.

M

subtle.encapsulateBits

History
subtle.encapsulateBits(encapsulationAlgorithm, encapsulationKey): Promise
Stability: 1.1Active development
Attributes
encapsulationAlgorithm:string | Algorithm
encapsulationKey:CryptoKey
Returns:Promise
Fulfills with EncapsulatedBits upon success.

Uses a message recipient's asymmetric public key to encrypt a temporary symmetric key. This encrypted key is the "encapsulated key" represented as EncapsulatedBits.

The algorithms currently supported include:

  • 'ML-KEM-512'1
  • 'ML-KEM-768'1
  • 'ML-KEM-1024'1
M

subtle.encapsulateKey

History
subtle.encapsulateKey(encapsulationAlgorithm, encapsulationKey, sharedKeyAlgorithm, extractable, keyUsages): Promise
Stability: 1.1Active development
Attributes
encapsulationAlgorithm:string | Algorithm
encapsulationKey:CryptoKey
sharedKeyAlgorithm:string | Algorithm | HmacImportParams | AesDerivedKeyParams | KmacImportParams
extractable:boolean
keyUsages:string[]
See Key usages.
Returns:Promise
Fulfills with EncapsulatedKey upon success.

Uses a message recipient's asymmetric public key to encrypt a temporary symmetric key. This encrypted key is the "encapsulated key" represented as EncapsulatedKey.

The algorithms currently supported include:

  • 'ML-KEM-512'1
  • 'ML-KEM-768'1
  • 'ML-KEM-1024'1
subtle.encrypt(algorithm, key, data): Promise
Attributes
algorithm:RsaOaepParams | AesCtrParams | AesCbcParams | AeadParams
key:CryptoKey
data:ArrayBuffer | TypedArray | DataView | Buffer
Returns:Promise
Fulfills with an ArrayBuffer upon success.

Using the method and parameters specified by algorithm and the keying material provided by key, this method attempts to encipher data. If successful, the returned promise is resolved with an ArrayBuffer containing the encrypted result.

The algorithms currently supported include:

  • 'AES-CBC'
  • 'AES-CTR'
  • 'AES-GCM'
  • 'AES-OCB'1
  • 'ChaCha20-Poly1305'1
  • 'RSA-OAEP'
subtle.exportKey(format, key): Promise
Attributes
format:string
Must be one of 'raw', 'pkcs8', 'spki', 'jwk', 'raw-secret'1, 'raw-public'1, or 'raw-seed'1.
key:CryptoKey
Returns:Promise
Fulfills with an ArrayBuffer | Object upon success.

Exports the given key into the specified format, if supported.

If the CryptoKey is not extractable, the returned promise will reject.

When format is either 'pkcs8' or 'spki' and the export is successful, the returned promise will be resolved with an ArrayBuffer containing the exported key data.

When format is 'jwk' and the export is successful, the returned promise will be resolved with a JavaScript object conforming to the JSON Web Key specification.

See Key formats for the formats supported by each algorithm.

M

subtle.getPublicKey

History
subtle.getPublicKey(key, keyUsages): Promise
Stability: 1.1Active development
Attributes
key:CryptoKey
A private key from which to derive the corresponding public key.
keyUsages:string[]
See Key usages.
Returns:Promise
Fulfills with a CryptoKey upon success.

Derives the public key from a given private key.

subtle.generateKey(algorithm, extractable, keyUsages): void
Attributes
algorithm:string | Algorithm | RsaHashedKeyGenParams | EcKeyGenParams | HmacKeyGenParams | AesKeyGenParams | KmacKeyGenParams
Attributes
extractable:boolean
keyUsages:string[]
See Key usages.
Returns:Promise
Fulfills with a CryptoKey | CryptoKeyPair upon success.

Using the parameters provided in algorithm, this method attempts to generate new keying material. Depending on the algorithm used either a single CryptoKey or a CryptoKeyPair is generated.

The CryptoKeyPair (public and private key) generating algorithms supported include:

  • 'ECDH'
  • 'ECDSA'
  • 'Ed25519'
  • 'Ed448'2
  • 'ML-DSA-44'1
  • 'ML-DSA-65'1
  • 'ML-DSA-87'1
  • 'ML-KEM-512'1
  • 'ML-KEM-768'1
  • 'ML-KEM-1024'1
  • 'RSA-OAEP'
  • 'RSA-PSS'
  • 'RSASSA-PKCS1-v1_5'
  • 'X25519'
  • 'X448'2

The CryptoKey (secret key) generating algorithms supported include:

  • 'AES-CBC'
  • 'AES-CTR'
  • 'AES-GCM'
  • 'AES-KW'
  • 'AES-OCB'1
  • 'ChaCha20-Poly1305'1
  • 'HMAC'
  • 'KMAC128'1
  • 'KMAC256'1
subtle.importKey(format, keyData, algorithm, extractable, keyUsages): void
Attributes
format:string
Must be one of 'raw', 'pkcs8', 'spki', 'jwk', 'raw-secret'1, 'raw-public'1, or 'raw-seed'1.
keyData:ArrayBuffer | TypedArray | DataView | Buffer | Object
Attributes
algorithm:string | Algorithm | RsaHashedImportParams | EcKeyImportParams | HmacImportParams | KmacImportParams
Attributes
extractable:boolean
keyUsages:string[]
See Key usages.
Returns:Promise
Fulfills with a CryptoKey upon success.

This method attempts to interpret the provided keyData as the given format to create a CryptoKey instance using the provided algorithm, extractable, and keyUsages arguments. If the import is successful, the returned promise will be resolved with a CryptoKey representation of the key material.

If importing KDF algorithm keys, extractable must be false.

See Key formats for the algorithms and formats currently supported.

subtle.sign(algorithm, key, data): Promise
Attributes
algorithm:string | Algorithm | RsaPssParams | EcdsaParams | ContextParams | KmacParams
key:CryptoKey
data:ArrayBuffer | TypedArray | DataView | Buffer
Returns:Promise
Fulfills with an ArrayBuffer upon success.

Using the method and parameters given by algorithm and the keying material provided by key, this method attempts to generate a cryptographic signature of data. If successful, the returned promise is resolved with an ArrayBuffer containing the generated signature.

The algorithms currently supported include:

  • 'ECDSA'
  • 'Ed25519'
  • 'Ed448'2
  • 'HMAC'
  • 'KMAC128'1
  • 'KMAC256'1
  • 'ML-DSA-44'1
  • 'ML-DSA-65'1
  • 'ML-DSA-87'1
  • 'RSA-PSS'
  • 'RSASSA-PKCS1-v1_5'
subtle.unwrapKey(format, wrappedKey, unwrappingKey, unwrapAlgorithm, unwrappedKeyAlgorithm, extractable, keyUsages): void
Attributes
format:string
Must be one of 'raw', 'pkcs8', 'spki', 'jwk', 'raw-secret'1, 'raw-public'1, or 'raw-seed'1.
wrappedKey:ArrayBuffer | TypedArray | DataView | Buffer
unwrappingKey:CryptoKey
Attributes
unwrapAlgorithm:string | Algorithm | RsaOaepParams | AesCtrParams | AesCbcParams | AeadParams
unwrappedKeyAlgorithm:string | Algorithm | RsaHashedImportParams | EcKeyImportParams | HmacImportParams | KmacImportParams
Attributes
extractable:boolean
keyUsages:string[]
See Key usages.
Returns:Promise
Fulfills with a CryptoKey upon success.

In cryptography, "wrapping a key" refers to exporting and then encrypting the keying material. This method attempts to decrypt a wrapped key and create a CryptoKey instance. It is equivalent to calling subtle.decrypt() first on the encrypted key data (using the wrappedKey, unwrapAlgorithm, and unwrappingKey arguments as input) then passing the results to the subtle.importKey() method using the unwrappedKeyAlgorithm, extractable, and keyUsages arguments as inputs. If successful, the returned promise is resolved with a CryptoKey object.

The wrapping algorithms currently supported include:

  • 'AES-CBC'
  • 'AES-CTR'
  • 'AES-GCM'
  • 'AES-KW'
  • 'AES-OCB'1
  • 'ChaCha20-Poly1305'1
  • 'RSA-OAEP'

The unwrapped key algorithms supported include:

  • 'AES-CBC'
  • 'AES-CTR'
  • 'AES-GCM'
  • 'AES-KW'
  • 'AES-OCB'1
  • 'ChaCha20-Poly1305'1
  • 'ECDH'
  • 'ECDSA'
  • 'Ed25519'
  • 'Ed448'2
  • 'HMAC'
  • 'KMAC128'1
  • 'KMAC256'1
  • 'ML-DSA-44'1
  • 'ML-DSA-65'1
  • 'ML-DSA-87'1
  • 'ML-KEM-512'1
  • 'ML-KEM-768'1
  • 'ML-KEM-1024'1
  • 'RSA-OAEP'
  • 'RSA-PSS'
  • 'RSASSA-PKCS1-v1_5'
  • 'X25519'
  • 'X448'2
subtle.verify(algorithm, key, signature, data): Promise
Attributes
algorithm:string | Algorithm | RsaPssParams | EcdsaParams | ContextParams | KmacParams
key:CryptoKey
signature:ArrayBuffer | TypedArray | DataView | Buffer
data:ArrayBuffer | TypedArray | DataView | Buffer
Returns:Promise
Fulfills with a boolean upon success.

Using the method and parameters given in algorithm and the keying material provided by key, this method attempts to verify that signature is a valid cryptographic signature of data. The returned promise is resolved with either true or false.

The algorithms currently supported include:

  • 'ECDSA'
  • 'Ed25519'
  • 'Ed448'2
  • 'HMAC'
  • 'KMAC128'1
  • 'KMAC256'1
  • 'ML-DSA-44'1
  • 'ML-DSA-65'1
  • 'ML-DSA-87'1
  • 'RSA-PSS'
  • 'RSASSA-PKCS1-v1_5'
subtle.wrapKey(format, key, wrappingKey, wrapAlgorithm): Promise
Attributes
format:string
Must be one of 'raw', 'pkcs8', 'spki', 'jwk', 'raw-secret'1, 'raw-public'1, or 'raw-seed'1.
key:CryptoKey
wrappingKey:CryptoKey
wrapAlgorithm:string | Algorithm | RsaOaepParams | AesCtrParams | AesCbcParams | AeadParams
Returns:Promise
Fulfills with an ArrayBuffer upon success.

In cryptography, "wrapping a key" refers to exporting and then encrypting the keying material. This method exports the keying material into the format identified by format, then encrypts it using the method and parameters specified by wrapAlgorithm and the keying material provided by wrappingKey. It is the equivalent to calling subtle.exportKey() using format and key as the arguments, then passing the result to the subtle.encrypt() method using wrappingKey and wrapAlgorithm as inputs. If successful, the returned promise will be resolved with an ArrayBuffer containing the encrypted key data.

The wrapping algorithms currently supported include:

  • 'AES-CBC'
  • 'AES-CTR'
  • 'AES-GCM'
  • 'AES-KW'
  • 'AES-OCB'1
  • 'ChaCha20-Poly1305'1
  • 'RSA-OAEP'
PreviousCryptoKeyPairNextAlgorithm parameters