SubtleCrypto
The SubtleCrypto interface of the Web Crypto API provides a number of low-level cryptographic functions.
The interface name includes the term "subtle" to indicate that many of its algorithms have subtle usage requirements, and hence that it must be used carefully in order to provide suitable security guarantees.
Properties
decrypt()
decrypt: (
algorithm,key,data) =>Promise<ArrayBuffer>
The decrypt() method of the SubtleCrypto interface decrypts some encrypted
data. It takes as arguments a key to decrypt with, some optional extra
parameters, and the data to decrypt (also known as "ciphertext"). It
returns a Promise which will be fulfilled with the decrypted data (also
known as "plaintext").
Parameters
algorithm
An object specifying the algorithm to be used, and any extra parameters as required. The values given for the extra parameters must match those passed into the corresponding encrypt call.
- To use AES-CTR, pass an AesCtrParams object.
- To use AES-CBC, pass an AesCbcParams object.
- To use AES-GCM, pass an AesGcmParams object.
key
A CryptoKey containing the key to be used for decryption.
data
An ArrayBuffer, a TypedArray, or a DataView
containing the data to be decrypted (also known as ciphertext).
Returns
Promise<ArrayBuffer>
A Promise that fulfills with an ArrayBuffer containing the plaintext.
Throws
InvalidArgumentError If the algorithm parameters are invalid or missing required fields
Throws
NotSupportedError If the algorithm is not supported or parameters have unsupported values
deriveBits()
deriveBits: (
algorithm,baseKey,length) =>Promise<ArrayBuffer>
The deriveBits() method of the SubtleCrypto interface can be used to derive
an array of bits from a base key.
It takes as its arguments the base key, the derivation algorithm to use, and
the length of the bits to derive. It returns a Promise which will be fulfilled
with an ArrayBuffer containing the derived bits.
Parameters
algorithm
An object defining the derivation algorithm to use.
- To use ECDH, pass an EcdhKeyDeriveParams object, specifying the string "ECDH" as the name property.
baseKey
A CryptoKey representing the input to the derivation algorithm. If algorithm is ECDH, this will be the ECDH private key. Otherwise it will be the initial key material for the derivation function: for example, for PBKDF2 it might be a password, imported as a CryptoKey using SubtleCrypto.importKey.
length
number
A number representing the number of bits to derive. To be compatible with all browsers, the number should be a multiple of 8.
Returns
Promise<ArrayBuffer>
A Promise that fulfills with an ArrayBuffer containing the derived bits.
Throws
NotSupportedError If the specified derivation algorithm is not supported.
Throws
InvalidArgumentError If the algorithm parameters are invalid.
digest()
digest: (
algorithm,data) =>Promise<ArrayBuffer>
The digest() method of the SubtleCrypto interface generates a digest of the
given data, using the specified hash function. A digest is a short fixed-length
value derived from some variable-length input. Cryptographic digests should
exhibit collision-resistance, meaning that it's hard to come up with two
different inputs that have the same digest value.
It takes as its arguments an identifier for the digest algorithm to use and
the data to digest. It returns a Promise which will be fulfilled with the digest.
Note that this API does not support streaming input: you must read the entire input into memory before passing it into the digest function.
Parameters
algorithm
This may be a string or an object with a single property name that is a string. The string names the hash function to use. Supported values are:
SHA-256SHA-384SHA-512
data
An ArrayBuffer, a TypedArray,
or a DataView object containing the data to be digested.
Returns
Promise<ArrayBuffer>
A Promise that fulfills with an ArrayBuffer
containing the digest.
Throws
NotSupportedError If the specified hash function is not supported.
Throws
InvalidArgumentError If the input parameters are invalid.
encrypt()
encrypt: (
algorithm,key,data) =>Promise<ArrayBuffer>
The encrypt() method of the SubtleCrypto interface encrypts data.
It takes as its arguments a key to encrypt with, some algorithm-specific
parameters, and the data to encrypt (also known as "plaintext"). It returns
a Promise which will be fulfilled with the encrypted data (also known as
"ciphertext").
Parameters
algorithm
An object specifying the algorithm to be used and any extra parameters if required:
- To use AES-CTR, pass an AesCtrParams object.
- To use AES-CBC, pass an AesCbcParams object.
- To use AES-GCM, pass an AesGcmParams object.
key
A CryptoKey containing the key to be used for encryption.
data
An ArrayBuffer, a TypedArray, or a DataView containing the
data to be encrypted (also known as the plaintext).
Returns
Promise<ArrayBuffer>
A Promise that fulfills with an ArrayBuffer containing the "ciphertext".
Throws
InvalidArgumentError If the algorithm parameters are invalid or missing required fields
Throws
NotSupportedError If the algorithm is not supported or parameters have unsupported values
exportKey()
exportKey: (
format,key) =>Promise<ArrayBuffer|JsonWebKey>
The exportKey() method of the SubtleCrypto interface exports a key: that is,
it takes as input a CryptoKey object and gives you the key in an
external, portable format.
To export a key, the key must have CryptoKey.extractable set to true. Keys can be exported in several formats.
Parameters
format
A string value describing the data format in which the key should be exported. It can be one of the following:
raw: Raw format (for symmetric keys or Elliptic Curve public keys).pkcs8: PKCS #8 format (for private keys).spki: SubjectPublicKeyInfo format (for public keys).jwk: JSON Web Key format.
key
The CryptoKey to export.
Returns
Promise<ArrayBuffer | JsonWebKey>
A Promise.
- If format was jwk, then the promise fulfills with a JSON object containing the key.
- Otherwise the promise fulfills with an
ArrayBuffercontaining the key.
Throws
InvalidArgumentError If the key is not extractable
Throws
NotSupportedError If the requested format is not supported for the given key type
generateKey()
generateKey: (
algorithm,extractable,keyUsages) =>Promise<CryptoKey|CryptoKeyPair>
The generateKey() method of the SubtleCrypto interface is used to generate
a new key (for symmetric algorithms) or key pair (for public-key algorithms).
Parameters
algorithm
An object defining the type of key to generate and providing extra algorithm-specific parameters.
- For ECDH: pass an EcKeyGenParams object.
- For HMAC: pass an HmacKeyGenParams object.
- For AES-CTR, AES-CBC, AES-GCM, or AES-KW: pass an AesKeyGenParams object.
extractable
boolean
A boolean value indicating whether it will be possible to export the key using SubtleCrypto.exportKey.
keyUsages
KeyUsage[]
An Array of strings indicating what can be done with the newly generated key. Possible values for array elements are:
encrypt: The key may be used to encrypt messages.decrypt: The key may be used to decrypt messages.sign: The key may be used to sign messages.verify: The key may be used to verify signatures.deriveKey: The key may be used in deriving a new key.deriveBits: The key may be used in deriving bits.wrapKey: The key may be used to wrap a key.unwrapKey: The key may be used to unwrap a key.
Returns
Promise<CryptoKey | CryptoKeyPair>
A Promise that fulfills with a
CryptoKey (for symmetric algorithms) or a CryptoKeyPair (for public-key algorithms).
Throws
InvalidArgumentError If the algorithm parameters are invalid
Throws
NotSupportedError If the algorithm or parameter values are not supported
importKey()
importKey: (
format,keyData,algorithm,extractable,keyUsages) =>Promise<CryptoKey>
The importKey() method of the SubtleCrypto interface imports a key: that is,
it takes as input a key in an external, portable format and gives you a
CryptoKey object that you can use in the Web Crypto API.
Parameters
format
A string describing the data format of the key to import. It can be one of the following:
raw: Raw format (for symmetric keys or Elliptic Curve public keys).pkcs8: PKCS #8 format (for private keys).spki: SubjectPublicKeyInfo format (for public keys).jwk: JSON Web Key format.
keyData
An ArrayBuffer,
a TypedArray, a DataView, or a JSONWebKey object containing
the key in the given format.
JsonWebKey |
BufferSource |
algorithm
An object defining the type of key to import and providing extra algorithm-specific parameters.
- For ECDH: pass an EcKeyImportParams object.
- For HMAC: pass an HmacImportParams object.
- For AES-CTR, AES-CBC, AES-GCM, and AES-KW: pass the string identifying the algorithm or an object of the form { name: ALGORITHM }, where ALGORITHM is the name of the algorithm.
extractable
boolean
A boolean value indicating whether it will be possible to export the key using SubtleCrypto.exportKey.
keyUsages
KeyUsage[]
An Array indicating what can be done with the key. Possible array values are:
encrypt: The key may be used to encrypt messages.decrypt: The key may be used to decrypt messages.sign: The key may be used to sign messages.verify: The key may be used to verify signatures.deriveKey: The key may be used in deriving a new key.deriveBits: The key may be used in deriving bits.wrapKey: The key may be used to wrap a key.unwrapKey: The key may be used to unwrap a key.
Returns
Promise<CryptoKey>
A Promise that fulfills with the imported key
as a CryptoKey object.
Throws
InvalidArgumentError
If the format is invalid or keyData doesn't match the required format
Throws
NotSupportedError If the algorithm or key format combination is not supported
sign()
sign: (
algorithm,key,data) =>Promise<ArrayBuffer>
The sign() method of the SubtleCrypto interface generates a digital signature.
It takes as its arguments a key to sign with, some algorithm-specific parameters,
and the data to sign. It returns a Promise which will be fulfilled with the signature.
You can use the corresponding SubtleCrypto.verify method to verify the signature.
Parameters
algorithm
A string or object that specifies the signature algorithm to use and its parameters:
- To use HMAC, pass the string HMAC or an object of the form { name: "HMAC" }.
key
A CryptoKey object containing the key to be used for signing. If algorithm identifies a public-key cryptosystem, this is the private key.
data
An ArrayBuffer, a TypedArray, or a DataView
object containing the data to be signed.
Returns
Promise<ArrayBuffer>
A Promise that fulfills with an ArrayBuffer containing the signature.
Throws
InvalidArgumentError If the algorithm parameters are invalid
Throws
NotSupportedError If the algorithm is not supported
verify()
verify: (
algorithm,key,signature,data) =>Promise<boolean>
The verify() method of the SubtleCrypto interface verifies a digital signature.
It takes as its arguments a key to verify the signature with, some
algorithm-specific parameters, the signature, and the original signed data.
It returns a Promise which will be fulfilled with a boolean value indicating
whether the signature is valid.
Parameters
algorithm
A string or object defining the algorithm to use, and for some algorithm choices, some extra parameters. The values given for the extra parameters must match those passed into the corresponding sign call.
- To use HMAC, pass the string "HMAC" or an object of the form { "name": "HMAC" }.
key
A CryptoKey containing the key that will be used to verify the signature. It is the secret key for a symmetric algorithm and the public key for a public-key system.
signature
ArrayBuffer
A ArrayBuffer containing the signature to verify.
data
ArrayBuffer
A ArrayBuffer containing the data whose signature is
to be verified.
Returns
Promise<boolean>
A Promise that fulfills with a boolean value: true if
the signature is valid, false otherwise.
Throws
InvalidArgumentError If the algorithm parameters are invalid
Throws
NotSupportedError If the algorithm is not supported
Last updated: Sep 30, 2025
