SubtleCrypto

Cette traduction est incomplète. Aidez-nous à traduire cet article depuis l’anglais

Contexte sécurisé
Cette fonctionnalité est uniquement disponible dans des contextes sécurisés (HTTPS), pour certains navigateurs qui la prennent en charge.

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 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 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-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.
SubtleCrypto.deriveKey()
Returns a Promise that fulfills with a newly generated CryptoKey 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 a CryptoKey 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 a CryptoKey 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() and verify(): create and verify digital signatures.
encrypt() and decrypt(): 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:

sign()

verify()

encrypt()

decrypt()

digest()

deriveBits()

deriveKey()

wrapKey()

unwrapKey()

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 API
La définition de 'SubtleCrypto' dans cette spécification.
Recommendation Initial definition.

Browser compatibility

Update compatibility data on GitHub
OrdinateurMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariWebview AndroidChrome pour AndroidFirefox pour AndroidOpera pour AndroidSafari sur iOSSamsung Internet
SubtleCryptoChrome Support complet 37Edge Support partiel 12Firefox Support complet 34
Support complet 34
Aucun support 32 — 34
Désactivée
Désactivée From version 32 until version 34 (exclusive): this feature is behind the dom.webcrypto.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE Support partiel 11Opera Support complet 24Safari Support complet 10.1
Support complet 10.1
Support complet 7
Préfixée
Préfixée Nécessite l'utilisation d'un préfixe : WebKit
WebView Android Support complet 37Chrome Android Support complet 37Firefox Android Support complet 34
Support complet 34
Aucun support 32 — 34
Désactivée
Désactivée From version 32 until version 34 (exclusive): this feature is behind the dom.webcrypto.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android Support complet 24Safari iOS Support complet 10.3
Support complet 10.3
Support complet 7
Préfixée
Préfixée Nécessite l'utilisation d'un préfixe : WebKit
Samsung Internet Android Support complet 6.0
decryptChrome Support complet 37Edge Support partiel 12
Notes
Support partiel 12
Notes
Notes Not supported: AES-CTR.
Firefox Support complet 34
Support complet 34
Aucun support 32 — 34
Désactivée
Désactivée From version 32 until version 34 (exclusive): this feature is behind the dom.webcrypto.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE Support partiel 11
Notes
Support partiel 11
Notes
Notes Returns CryptoOperation instead of Promise
Opera Support complet 24Safari Support complet 7WebView Android Support complet 37Chrome Android Support complet 37Firefox Android Support complet 34
Support complet 34
Aucun support 32 — 34
Désactivée
Désactivée From version 32 until version 34 (exclusive): this feature is behind the dom.webcrypto.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android Support complet 24Safari iOS Support complet 7Samsung Internet Android Support complet 6.0
deriveBitsChrome Support complet 37Edge Support partiel 12
Notes
Support partiel 12
Notes
Notes Not supported: ECDH.
Notes Not supported: HKDF, PBKDF2.
Firefox Support complet 34
Support complet 34
Aucun support 32 — 34
Désactivée
Désactivée From version 32 until version 34 (exclusive): this feature is behind the dom.webcrypto.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE Aucun support NonOpera Support complet 24Safari Support complet 7WebView Android Support complet 37Chrome Android Support complet 37Firefox Android Support complet 34
Support complet 34
Aucun support 32 — 34
Désactivée
Désactivée From version 32 until version 34 (exclusive): this feature is behind the dom.webcrypto.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android Support complet 24Safari iOS Support complet 7Samsung Internet Android Support complet 6.0
deriveKeyChrome Support complet 37Edge Support partiel 12
Notes
Support partiel 12
Notes
Notes Not supported: ECDH.
Notes Not supported: HKDF, PBKDF2.
Firefox Support complet 34
Support complet 34
Aucun support 32 — 34
Désactivée
Désactivée From version 32 until version 34 (exclusive): this feature is behind the dom.webcrypto.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE Aucun support NonOpera Support complet 24Safari Support complet 7WebView Android Support complet 37Chrome Android Support complet 37Firefox Android Support complet 34
Support complet 34
Aucun support 32 — 34
Désactivée
Désactivée From version 32 until version 34 (exclusive): this feature is behind the dom.webcrypto.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android Support complet 24Safari iOS Support complet 7Samsung Internet Android Support complet 6.0
digestChrome Support complet 37Edge Support partiel 12
Notes
Support partiel 12
Notes
Notes Not supported: SHA-1.
Firefox Support complet 34
Support complet 34
Aucun support 32 — 34
Désactivée
Désactivée From version 32 until version 34 (exclusive): this feature is behind the dom.webcrypto.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE Support partiel 11
Notes
Support partiel 11
Notes
Notes Returns CryptoOperation instead of Promise
Opera Support complet 24Safari Support complet 7WebView Android Support complet 37Chrome Android Support complet 37Firefox Android Support complet 34
Support complet 34
Aucun support 32 — 34
Désactivée
Désactivée From version 32 until version 34 (exclusive): this feature is behind the dom.webcrypto.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android Support complet 24Safari iOS Support complet 7Samsung Internet Android Support complet 6.0
encryptChrome Support complet 37Edge Support partiel 12
Notes
Support partiel 12
Notes
Notes Not supported: AES-CTR.
Firefox Support complet 34
Support complet 34
Aucun support 32 — 34
Désactivée
Désactivée From version 32 until version 34 (exclusive): this feature is behind the dom.webcrypto.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE Support partiel 11
Notes
Support partiel 11
Notes
Notes Returns CryptoOperation instead of Promise
Opera Support complet 24Safari Support complet 7WebView Android Support complet 37Chrome Android Support complet 37Firefox Android Support complet 34
Support complet 34
Aucun support 32 — 34
Désactivée
Désactivée From version 32 until version 34 (exclusive): this feature is behind the dom.webcrypto.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android Support complet 24Safari iOS Support complet 7Samsung Internet Android Support complet 6.0
exportKeyChrome Support complet 37Edge Support partiel 12
Notes
Support partiel 12
Notes
Notes Not supported: RSA-PSS, ECDSA, ECDH.
Notes Not supported: AES-CTR.
Firefox Support complet 34
Support complet 34
Aucun support 32 — 34
Désactivée
Désactivée From version 32 until version 34 (exclusive): this feature is behind the dom.webcrypto.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE Support partiel 11
Notes
Support partiel 11
Notes
Notes Returns KeyOperation instead of Promise
Opera Support complet 24Safari Support complet 7WebView Android Support complet 37Chrome Android Support complet 37Firefox Android Support complet 34
Support complet 34
Aucun support 32 — 34
Désactivée
Désactivée From version 32 until version 34 (exclusive): this feature is behind the dom.webcrypto.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android Support complet 24Safari iOS Support complet 7Samsung Internet Android Support complet 6.0
generateKeyChrome Support complet 37Edge Support partiel 12
Notes
Support partiel 12
Notes
Notes Not supported: RSA-PSS, ECDSA, ECDH.
Notes Not supported: AES-CTR.
Firefox Support complet 34
Support complet 34
Aucun support 32 — 34
Désactivée
Désactivée From version 32 until version 34 (exclusive): this feature is behind the dom.webcrypto.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE Support partiel 11
Notes
Support partiel 11
Notes
Notes Returns KeyOperation instead of Promise
Opera Support complet 24Safari Support complet 7WebView Android Support complet 37Chrome Android Support complet 37Firefox Android Support complet 34
Support complet 34
Aucun support 32 — 34
Désactivée
Désactivée From version 32 until version 34 (exclusive): this feature is behind the dom.webcrypto.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android Support complet 24Safari iOS Support complet 7Samsung Internet Android Support complet 6.0
importKeyChrome Support complet 37Edge Support partiel 12
Notes
Support partiel 12
Notes
Notes Not supported: RSA-PSS, ECDSA, ECDH.
Notes Not supported: AES-CTR, HKDF, PBKDF2.
Firefox Support complet 34
Support complet 34
Aucun support 32 — 34
Désactivée
Désactivée From version 32 until version 34 (exclusive): this feature is behind the dom.webcrypto.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE Support partiel 11
Notes
Support partiel 11
Notes
Notes Returns KeyOperation instead of Promise
Opera Support complet 24Safari Support complet 7WebView Android Support complet 37Chrome Android Support complet 37Firefox Android Support complet 34
Support complet 34
Aucun support 32 — 34
Désactivée
Désactivée From version 32 until version 34 (exclusive): this feature is behind the dom.webcrypto.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android Support complet 24Safari iOS Support complet 7Samsung Internet Android Support complet 6.0
Secure context requiredChrome Support complet 60Edge Support complet 79Firefox Support complet 75IE Aucun support NonOpera Support complet 47Safari Aucun support NonWebView Android Support complet 60Chrome Android Support complet 60Firefox Android Aucun support NonOpera Android Support complet 47Safari iOS Aucun support NonSamsung Internet Android Support complet 8.0
signChrome Support complet 37Edge Support partiel 12
Notes
Support partiel 12
Notes
Notes Not supported: RSA-PSS, ECDSA.
Firefox Support complet 34
Support complet 34
Aucun support 32 — 34
Désactivée
Désactivée From version 32 until version 34 (exclusive): this feature is behind the dom.webcrypto.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE Support partiel 11
Notes
Support partiel 11
Notes
Notes Returns CryptoOperation instead of Promise
Opera Support complet 24Safari Support complet 7WebView Android Support complet 37Chrome Android Support complet 37Firefox Android Support complet 34
Support complet 34
Aucun support 32 — 34
Désactivée
Désactivée From version 32 until version 34 (exclusive): this feature is behind the dom.webcrypto.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android Support complet 24Safari iOS Support complet 7Samsung Internet Android Support complet 6.0
unwrapKeyChrome Support complet 37Edge Support partiel 12
Notes
Support partiel 12
Notes
Notes Not supported: AES-CTR.
Firefox Support complet 34
Support complet 34
Aucun support 32 — 34
Désactivée
Désactivée From version 32 until version 34 (exclusive): this feature is behind the dom.webcrypto.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE Support partiel 11
Notes
Support partiel 11
Notes
Notes Returns KeyOperation instead of Promise
Opera Support complet 24Safari Support complet 7WebView Android ? Chrome Android Support complet 37Firefox Android Support complet 34
Support complet 34
Aucun support 32 — 34
Désactivée
Désactivée From version 32 until version 34 (exclusive): this feature is behind the dom.webcrypto.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android Support complet 24Safari iOS Support complet 7Samsung Internet Android Support complet 6.0
verifyChrome Support complet 37Edge Support partiel 12
Notes
Support partiel 12
Notes
Notes Not supported: RSA-PSS, ECDSA.
Firefox Support complet 34
Support complet 34
Aucun support 32 — 34
Désactivée
Désactivée From version 32 until version 34 (exclusive): this feature is behind the dom.webcrypto.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE Support partiel 11
Notes
Support partiel 11
Notes
Notes Returns CryptoOperation instead of Promise
Opera Support complet 24Safari Support complet 7WebView Android Support complet 37Chrome Android Support complet 37Firefox Android Support complet 34
Support complet 34
Aucun support 32 — 34
Désactivée
Désactivée From version 32 until version 34 (exclusive): this feature is behind the dom.webcrypto.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android Support complet 24Safari iOS Support complet 7Samsung Internet Android Support complet 6.0
Available in workersChrome ? Edge ? Firefox Support complet 48IE ? Opera ? Safari ? WebView Android ? Chrome Android ? Firefox Android ? Opera Android ? Safari iOS ? Samsung Internet Android ?
wrapKeyChrome Support complet 37Edge Support partiel 12
Notes
Support partiel 12
Notes
Notes Not supported: AES-CTR.
Firefox Support complet 34
Support complet 34
Aucun support 32 — 34
Désactivée
Désactivée From version 32 until version 34 (exclusive): this feature is behind the dom.webcrypto.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE Support partiel 11
Notes
Support partiel 11
Notes
Notes Returns KeyOperation instead of Promise
Opera Support complet 24Safari Support complet 7WebView Android Support complet 37Chrome Android Support complet 37Firefox Android Support complet 34
Support complet 34
Aucun support 32 — 34
Désactivée
Désactivée From version 32 until version 34 (exclusive): this feature is behind the dom.webcrypto.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android Support complet 24Safari iOS Support complet 7Samsung Internet Android Support complet 6.0

Légende

Support complet  
Support complet
Support partiel  
Support partiel
Aucun support  
Aucun support
Compatibilité inconnue  
Compatibilité inconnue
Voir les notes d'implémentation.
Voir les notes d'implémentation.
Une action explicite de l'utilisateur est nécessaire pour activer cette fonctionnalité.
Une action explicite de l'utilisateur est nécessaire pour activer cette fonctionnalité.
Cette fonctionnalité nécessite un préfixe particulier ou utilise un autre nom.
Cette fonctionnalité nécessite un préfixe particulier ou utilise un autre nom.

See also