TheSubtleCrypto interface of theWeb 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.

An instance ofSubtleCrypto is available as thesubtle property of theCrypto interface, which in turn is available in windows through theWindow.crypto property and in workers through theWorkerGlobalScope.crypto property.

Instance properties

This interface doesn't inherit any properties, as it has no parent interface.

Instance methods

This interface doesn't inherit any methods, as it has no parent interface.

SubtleCrypto.encrypt()

Returns aPromise that fulfills with the encrypted data corresponding to the clear text, algorithm, and key given as parameters.

SubtleCrypto.decrypt()

Returns aPromise that fulfills with the clear data corresponding to the encrypted text, algorithm, and key given as parameters.

SubtleCrypto.sign()

Returns aPromise that fulfills with the signature corresponding to the text, algorithm, and key given as parameters.

SubtleCrypto.verify()

Returns aPromise that 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.

SubtleCrypto.digest()

Returns aPromise that fulfills with a digest generated from the algorithm and text given as parameters.

SubtleCrypto.generateKey()

Returns aPromise that fulfills with a newly-generatedCryptoKey, for symmetrical algorithms, or aCryptoKeyPair, containing two newly generated keys, for asymmetrical algorithms. These will match the algorithm, usages, and extractability given as parameters.

SubtleCrypto.deriveKey()

Returns aPromise that fulfills with a newly generatedCryptoKey derived from the master key and specific algorithm given as parameters.

SubtleCrypto.deriveBits()

Returns aPromise that fulfills with a newly generated buffer of pseudo-random bits derived from the master key and specific algorithm given as parameters.

SubtleCrypto.importKey()

Returns aPromise that fulfills with aCryptoKey corresponding to the format, the algorithm, raw key data, usages, and extractability given as parameters.

SubtleCrypto.exportKey()

Returns aPromise that fulfills with the raw key data containing the key in the requested format.

SubtleCrypto.wrapKey()

Returns aPromise that 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.

SubtleCrypto.unwrapKey()

Returns aPromise that fulfills with aCryptoKey corresponding to the wrapped key given in the parameter.

Using SubtleCrypto

We can split the functions implemented by this API into two groups: cryptography functions and key management functions.

Cryptography functions

These are the functions you can use to implement security features such as privacy and authentication in a system. TheSubtleCrypto API provides the following cryptography functions:

• sign() andverify(): create and verify digital signatures.
• encrypt() anddecrypt(): encrypt and decrypt data.
• digest(): create a fixed-length, collision-resistant digest of some data.

Key management functions

Except fordigest(), all the cryptography functions in the API use cryptographic keys. In theSubtleCrypto API a cryptographic key is represented using aCryptoKey object. To perform operations like signing and encrypting, you pass aCryptoKey object into thesign() orencrypt() function.

Generating and deriving keys

ThegenerateKey() andderiveKey() functions both create a newCryptoKey object.

The difference is thatgenerateKey() will generate a new distinct key value each time you call it, whilederiveKey() derives a key from some initial keying material. If you provide the same keying material to two separate calls toderiveKey(), you will get twoCryptoKey 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 whatexportKey() is for. You can choose one of a number of export formats.

The inverse ofexportKey() isimportKey(). You can import keys from other systems, and support for standard formats likePKCS #8 andJSON Web Key helps you do this. TheexportKey() function exports the key in an unencrypted format.

If the key is sensitive you should usewrapKey(), which exports the key and then encrypts it using another key; the API calls a "key-wrapping key".

The inverse ofwrapKey() isunwrapKey(), which decrypts then imports the key.

Storing keys

CryptoKey is aserializable object, which allows keys to be stored and retrieved using standard web storage APIs.

The specification expects that most developers will use theIndexedDB API, storingCryptoKey objects against some key string identifier that is meaningful to the application, along with any other metadata it finds useful.This allows the storage and retrieval of theCryptoKey without having to expose its underlying key material to the application or the JavaScript environment.

Supported algorithms

The cryptographic functions provided by the Web Crypto API can be performed by one or more differentcryptographic algorithms: thealgorithm argument to the function indicates which algorithm to use. Some algorithms need extra parameters: in these cases thealgorithm argument is a dictionary object that includes the extra parameters.

The table below summarizes which algorithms are suitable for which cryptographic operations:

Specifications

Browser compatibility

See also

• Web Crypto API
• Non-cryptographic uses of SubtleCrypto
• Web security
• Privacy, permissions, and information security
• Crypto andCrypto.subtle.
• Crypto 101: an introductory course on cryptography.