Secure contextThis feature is available only in secure contexts (HTTPS), in some or all supporting browsers.
The 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 Window.crypto
.
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.
If you're not sure you know what you are doing, you probably shouldn't be using this API.
Properties
This interface doesn't inherit any properties, as it has no parent interface.
Methods
This interface doesn't inherit any methods, as it has no parent interface.
SubtleCrypto.encrypt()
- Returns a
Promise
that fufills with the encrypted data corresponding to the clear text, algorithm, and key given as parameters. SubtleCrypto.decrypt()
- Returns a
Promise
that fulfills with the clear data corresponding to the encrypted text, algorithm, and key given as parameters. SubtleCrypto.sign()
- Returns a
Promise
that fulfills with the signature corresponding to the text, algorithm, and key given as parameters. SubtleCrypto.verify()
- Returns a
Promise
that fulfills with aBoolean
value indicating if the signature given as a parameter matches the text, algorithm, and key that are also given as parameters. SubtleCrypto.digest()
- Returns a
Promise
that fulfills with a digest generated from the algorithm and text given as parameters. SubtleCrypto.generateKey()
- Returns a
Promise
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 a
Promise
that fulfills with a newly generatedCryptoKey
derived from the master key and specific algorithm given as parameters. SubtleCrypto.deriveBits()
- Returns a
Promise
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 a
Promise
that fulfills with aCryptoKey
corresponding to the format, the algorithm, raw key data, usages, and extractability given as parameters. SubtleCrypto.exportKey()
- Returns a
Promise
that fulfills with a buffer containing the key in the requested format. SubtleCrypto.wrapKey()
- Returns a
Promise
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 a
Promise
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. The SubtleCrypto
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 for 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 sign()
or encrypt()
function.
Generating and deriving keys
The generateKey()
and deriveKey()
functions both create a new CryptoKey
object.
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 exportKey()
is 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 wrapKey()
is unwrapKey()
, which decrypts then imports the key.
Storing keys
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 CryptoKey
objects.
Supported algorithms
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 summarises which algorithms are suitable for which cryptographic operations:
digest() | |||||
---|---|---|---|---|---|
RSASSA-PKCS1-v1_5 | ✓ | ||||
RSA-PSS | ✓ | ||||
ECDSA | ✓ | ||||
HMAC | ✓ | ||||
RSA-OAEP | ✓ | ✓ | |||
AES-CTR | ✓ | ✓ | |||
AES-CBC | ✓ | ✓ | |||
AES-GCM | ✓ | ✓ | |||
SHA-1 | ✓ | ||||
SHA-256 | ✓ | ||||
SHA-384 | ✓ | ||||
SHA-512 | ✓ | ||||
ECDH | ✓ | ||||
HKDF | ✓ | ||||
PBKDF2 | ✓ | ||||
AES-KW | ✓ |
Specifications
Specification | Status | Comment |
Web Cryptography APIThe definition of 'SubtleCrypto' in that specification. | Recommendation | Initial definition. |
Browser compatibility
The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request.
Update compatibility data on GitHub
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
SubtleCrypto
|
Chrome
Full support 37 |
Edge
Partial support 12 |
Firefox Full support 34 Full support 34 No support 32 — 34 Disabled' From version 32 until version 34 (exclusive): this feature is behind the |
IE
Partial support 11 |
Opera
Full support 24 |
Safari Full support 10.1 Full support 10.1 Full support 7 Prefixed' Implemented with the vendor prefix: WebKit |
WebView Android
Full support 37 |
Chrome Android
Full support 37 |
Firefox Android Full support 34 Full support 34 No support 32 — 34 Disabled' From version 32 until version 34 (exclusive): this feature is behind the |
Opera Android
Full support 24 |
Safari iOS Full support 10.3 Full support 10.3 Full support 7 Prefixed' Implemented with the vendor prefix: WebKit |
Samsung Internet Android
Full support 6.0 |
decrypt
|
Chrome
Full support 37 |
Edge Partial support 12 Partial support 12 Notes' Not supported: AES-CTR. |
Firefox Full support 34 Full support 34 No support 32 — 34 Disabled' From version 32 until version 34 (exclusive): this feature is behind the |
IE Partial support 11 Partial support 11 Notes' Returns |
Opera
Full support 24 |
Safari
Full support 7 |
WebView Android
Full support 37 |
Chrome Android
Full support 37 |
Firefox Android Full support 34 Full support 34 No support 32 — 34 Disabled' From version 32 until version 34 (exclusive): this feature is behind the |
Opera Android
Full support 24 |
Safari iOS
Full support 7 |
Samsung Internet Android
Full support 6.0 |
deriveBits
|
Chrome
Full support 37 |
Edge Partial support 12 Partial support 12 Notes' Not supported: ECDH. Notes' Not supported: HKDF, PBKDF2. |
Firefox Full support 34 Full support 34 No support 32 — 34 Disabled' From version 32 until version 34 (exclusive): this feature is behind the |
IE
No support No |
Opera
Full support 24 |
Safari
Full support 7 |
WebView Android
Full support 37 |
Chrome Android
Full support 37 |
Firefox Android Full support 34 Full support 34 No support 32 — 34 Disabled' From version 32 until version 34 (exclusive): this feature is behind the |
Opera Android
Full support 24 |
Safari iOS
Full support 7 |
Samsung Internet Android
Full support 6.0 |
deriveKey
|
Chrome
Full support 37 |
Edge Partial support 12 Partial support 12 Notes' Not supported: ECDH. Notes' Not supported: HKDF, PBKDF2. |
Firefox Full support 34 Full support 34 No support 32 — 34 Disabled' From version 32 until version 34 (exclusive): this feature is behind the |
IE
No support No |
Opera
Full support 24 |
Safari
Full support 7 |
WebView Android
Full support 37 |
Chrome Android
Full support 37 |
Firefox Android Full support 34 Full support 34 No support 32 — 34 Disabled' From version 32 until version 34 (exclusive): this feature is behind the |
Opera Android
Full support 24 |
Safari iOS
Full support 7 |
Samsung Internet Android
Full support 6.0 |
digest
|
Chrome
Full support 37 |
Edge Partial support 12 Partial support 12 Notes' Not supported: SHA-1. |
Firefox Full support 34 Full support 34 No support 32 — 34 Disabled' From version 32 until version 34 (exclusive): this feature is behind the |
IE Partial support 11 Partial support 11 Notes' Returns |
Opera
Full support 24 |
Safari
Full support 7 |
WebView Android
Full support 37 |
Chrome Android
Full support 37 |
Firefox Android Full support 34 Full support 34 No support 32 — 34 Disabled' From version 32 until version 34 (exclusive): this feature is behind the |
Opera Android
Full support 24 |
Safari iOS
Full support 7 |
Samsung Internet Android
Full support 6.0 |
encrypt
|
Chrome
Full support 37 |
Edge Partial support 12 Partial support 12 Notes' Not supported: AES-CTR. |
Firefox Full support 34 Full support 34 No support 32 — 34 Disabled' From version 32 until version 34 (exclusive): this feature is behind the |
IE Partial support 11 Partial support 11 Notes' Returns |
Opera
Full support 24 |
Safari
Full support 7 |
WebView Android
Full support 37 |
Chrome Android
Full support 37 |
Firefox Android Full support 34 Full support 34 No support 32 — 34 Disabled' From version 32 until version 34 (exclusive): this feature is behind the |
Opera Android
Full support 24 |
Safari iOS
Full support 7 |
Samsung Internet Android
Full support 6.0 |
exportKey
|
Chrome
Full support 37 |
Edge Partial support 12 Partial support 12 Notes' Not supported: RSA-PSS, ECDSA, ECDH. Notes' Not supported: AES-CTR. |
Firefox Full support 34 Full support 34 No support 32 — 34 Disabled' From version 32 until version 34 (exclusive): this feature is behind the |
IE Partial support 11 Partial support 11 Notes' Returns |
Opera
Full support 24 |
Safari
Full support 7 |
WebView Android
Full support 37 |
Chrome Android
Full support 37 |
Firefox Android Full support 34 Full support 34 No support 32 — 34 Disabled' From version 32 until version 34 (exclusive): this feature is behind the |
Opera Android
Full support 24 |
Safari iOS
Full support 7 |
Samsung Internet Android
Full support 6.0 |
generateKey
|
Chrome
Full support 37 |
Edge Partial support 12 Partial support 12 Notes' Not supported: RSA-PSS, ECDSA, ECDH. Notes' Not supported: AES-CTR. |
Firefox Full support 34 Full support 34 No support 32 — 34 Disabled' From version 32 until version 34 (exclusive): this feature is behind the |
IE Partial support 11 Partial support 11 Notes' Returns |
Opera
Full support 24 |
Safari
Full support 7 |
WebView Android
Full support 37 |
Chrome Android
Full support 37 |
Firefox Android Full support 34 Full support 34 No support 32 — 34 Disabled' From version 32 until version 34 (exclusive): this feature is behind the |
Opera Android
Full support 24 |
Safari iOS
Full support 7 |
Samsung Internet Android
Full support 6.0 |
importKey
|
Chrome
Full support 37 |
Edge Partial support 12 Partial support 12 Notes' Not supported: RSA-PSS, ECDSA, ECDH. Notes' Not supported: AES-CTR, HKDF, PBKDF2. |
Firefox Full support 34 Full support 34 No support 32 — 34 Disabled' From version 32 until version 34 (exclusive): this feature is behind the |
IE Partial support 11 Partial support 11 Notes' Returns |
Opera
Full support 24 |
Safari
Full support 7 |
WebView Android
Full support 37 |
Chrome Android
Full support 37 |
Firefox Android Full support 34 Full support 34 No support 32 — 34 Disabled' From version 32 until version 34 (exclusive): this feature is behind the |
Opera Android
Full support 24 |
Safari iOS
Full support 7 |
Samsung Internet Android
Full support 6.0 |
Secure context required | Chrome
Full support 60 |
Edge
Full support 79 |
Firefox
Full support 75 |
IE
No support No |
Opera
Full support 47 |
Safari
No support No |
WebView Android
Full support 60 |
Chrome Android
Full support 60 |
Firefox Android
No support No |
Opera Android
Full support 47 |
Safari iOS
No support No |
Samsung Internet Android
Full support 8.0 |
sign
|
Chrome
Full support 37 |
Edge Partial support 12 Partial support 12 Notes' Not supported: RSA-PSS, ECDSA. |
Firefox Full support 34 Full support 34 No support 32 — 34 Disabled' From version 32 until version 34 (exclusive): this feature is behind the |
IE Partial support 11 Partial support 11 Notes' Returns |
Opera
Full support 24 |
Safari
Full support 7 |
WebView Android
Full support 37 |
Chrome Android
Full support 37 |
Firefox Android Full support 34 Full support 34 No support 32 — 34 Disabled' From version 32 until version 34 (exclusive): this feature is behind the |
Opera Android
Full support 24 |
Safari iOS
Full support 7 |
Samsung Internet Android
Full support 6.0 |
unwrapKey
|
Chrome
Full support 37 |
Edge Partial support 12 Partial support 12 Notes' Not supported: AES-CTR. |
Firefox Full support 34 Full support 34 No support 32 — 34 Disabled' From version 32 until version 34 (exclusive): this feature is behind the |
IE Partial support 11 Partial support 11 Notes' Returns |
Opera
Full support 24 |
Safari
Full support 7 |
WebView Android
? |
Chrome Android
Full support 37 |
Firefox Android Full support 34 Full support 34 No support 32 — 34 Disabled' From version 32 until version 34 (exclusive): this feature is behind the |
Opera Android
Full support 24 |
Safari iOS
Full support 7 |
Samsung Internet Android
Full support 6.0 |
verify
|
Chrome
Full support 37 |
Edge Partial support 12 Partial support 12 Notes' Not supported: RSA-PSS, ECDSA. |
Firefox Full support 34 Full support 34 No support 32 — 34 Disabled' From version 32 until version 34 (exclusive): this feature is behind the |
IE Partial support 11 Partial support 11 Notes' Returns |
Opera
Full support 24 |
Safari
Full support 7 |
WebView Android
Full support 37 |
Chrome Android
Full support 37 |
Firefox Android Full support 34 Full support 34 No support 32 — 34 Disabled' From version 32 until version 34 (exclusive): this feature is behind the |
Opera Android
Full support 24 |
Safari iOS
Full support 7 |
Samsung Internet Android
Full support 6.0 |
Available in workers | Chrome
? |
Edge
? |
Firefox
Full support 48 |
IE
? |
Opera
? |
Safari
? |
WebView Android
? |
Chrome Android
? |
Firefox Android
? |
Opera Android
? |
Safari iOS
? |
Samsung Internet Android
? |
wrapKey
|
Chrome
Full support 37 |
Edge Partial support 12 Partial support 12 Notes' Not supported: AES-CTR. |
Firefox Full support 34 Full support 34 No support 32 — 34 Disabled' From version 32 until version 34 (exclusive): this feature is behind the |
IE Partial support 11 Partial support 11 Notes' Returns |
Opera
Full support 24 |
Safari
Full support 7 |
WebView Android
Full support 37 |
Chrome Android
Full support 37 |
Firefox Android Full support 34 Full support 34 No support 32 — 34 Disabled' From version 32 until version 34 (exclusive): this feature is behind the |
Opera Android
Full support 24 |
Safari iOS
Full support 7 |
Samsung Internet Android
Full support 6.0 |
Legend
- Full support
- Full support
- Partial support
- Partial support
- No support
- No support
- Compatibility unknown
- Compatibility unknown
- See implementation notes.'
- See implementation notes.
- User must explicitly enable this feature.'
- User must explicitly enable this feature.
- Requires a vendor prefix or different name for use.'
- Requires a vendor prefix or different name for use.
See also
- Web Crypto API
- Web security
- Privacy, permissions, and information security
Crypto
andCrypto.subtle
.- Crypto 101: an introductory course on cryptography.
SubtleCrypto by Mozilla Contributors is licensed under CC-BY-SA 2.5.