Secure context: This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.
SubtleCrypto interface of the Web Crypto API provides a number of low-level cryptographic functions. Access to the features of
SubtleCrypto is obtained through the
subtle property of the
Crypto object you get from the
Warning: This API provides a number of low-level cryptographic primitives. It's very easy to misuse them, and the pitfalls involved can be very subtle.
Even assuming you use the basic cryptographic functions correctly, secure key management and overall security system design are extremely hard to get right, and are generally the domain of specialist security experts.
Errors in security system design and implementation can make the security of the system completely ineffective.
Please learn and experiment, but don't guarantee or imply the security of your work before an individual knowledgeable in this subject matter thoroughly reviews it. The Crypto 101 Course can be a great place to start learning about the design and implementation of secure systems.
This interface doesn't inherit any properties, as it has no parent interface.
This interface doesn't inherit any methods, as it has no parent interface.
Promisethat fulfills with the encrypted data corresponding to the clear text, algorithm, and key given as parameters.
Promisethat fulfills with the clear data corresponding to the encrypted text, algorithm, and key given as parameters.
Promisethat fulfills with the signature corresponding to the text, algorithm, and key given as parameters.
Promisethat fulfills with a boolean value indicating if the signature given as a parameter matches the text, algorithm, and key that are also given as parameters.
Promisethat fulfills with a digest generated from the algorithm and text given as parameters.
Promisethat fulfills with a newly-generated
CryptoKey, for symmetrical algorithms, or a
CryptoKeyPair, containing two newly generated keys, for asymmetrical algorithms. These will match the algorithm, usages, and extractability given as parameters.
Promisethat fulfills with a newly generated
CryptoKeyderived from the master key and specific algorithm given as parameters.
Promisethat fulfills with a newly generated buffer of pseudo-random bits derived from the master key and specific algorithm given as parameters.
Promisethat fulfills with a
CryptoKeycorresponding to the format, the algorithm, raw key data, usages, and extractability given as parameters.
Promisethat fulfills with the raw key data containing the key in the requested format.
Promisethat fulfills with a wrapped symmetric key for usage (transfer and storage) in insecure environments. The wrapped key matches the format specified in the given parameters, and wrapping is done by the given wrapping key, using the specified algorithm.
Promisethat fulfills with a
CryptoKeycorresponding to the wrapped key given in the parameter.
We can split the functions implemented by this API into two groups: cryptography functions and key management functions.
These are the functions you can use to implement security features such as privacy and authentication in a system. The
SubtleCrypto API provides the following cryptography functions:
Key management functions
digest(), all the cryptography functions in the API use cryptographic keys. In the
SubtleCrypto API a cryptographic key is represented using a
CryptoKey object. To perform operations like signing and encrypting, you pass a
CryptoKey object into the
Generating and deriving keys
deriveKey() functions both create a new
The difference is that
generateKey() will generate a new distinct key value each time you call it, while
deriveKey() derives a key from some initial keying material. If you provide the same keying material to two separate calls to
deriveKey(), you will get two
CryptoKey objects that have the same underlying value. This is useful if, for example, you want to derive an encryption key from a password and later derive the same key from the same password to decrypt the data.
Importing and exporting keys
To make keys available outside your app, you need to export the key, and that's what
exportKey() is for. You can choose one of a number of export formats.
The inverse of
importKey(). You can import keys from other systems, and support for standard formats like PKCS #8 and JSON Web Key helps you do this. The
exportKey() function exports the key in an unencrypted format.
If the key is sensitive you should use
wrapKey(), which exports the key and then encrypts it using another key; the API calls a "key-wrapping key".
The inverse of
unwrapKey(), which decrypts then imports the key.
CryptoKey objects can be stored using the structured clone algorithm, meaning that you can store and retrieve them using standard web storage APIs. The specification expects that most developers will use the IndexedDB API to store
The cryptographic functions provided by the Web Crypto API can be performed by one or more different cryptographic algorithms: the
algorithm argument to the function indicates which algorithm to use. Some algorithms need extra parameters: in these cases the
algorithm argument is a dictionary object that includes the extra parameters.
The table below summarizes which algorithms are suitable for which cryptographic operations:
|Web Cryptography API |
BCD tables only load in the browser
- Web Crypto API
- Non-cryptographic uses of SubtleCrypto
- Web security
- Privacy, permissions, and information security
- Crypto 101: an introductory course on cryptography.