aboutsummaryrefslogtreecommitdiff
path: root/files/fr/web/api/subtlecrypto
diff options
context:
space:
mode:
authorjulieng <julien.gattelier@gmail.com>2021-10-02 17:20:24 +0200
committerSphinxKnight <SphinxKnight@users.noreply.github.com>2021-10-02 17:30:20 +0200
commit1407c8fdef01ecd0ffb8a8bd46e7113f119b9fde (patch)
tree30a56efd3eff3a01bd1611e1840fdbbfacf544a4 /files/fr/web/api/subtlecrypto
parentc05efa8d7ae464235cf83d7c0956e42dc6974103 (diff)
downloadtranslated-content-1407c8fdef01ecd0ffb8a8bd46e7113f119b9fde.tar.gz
translated-content-1407c8fdef01ecd0ffb8a8bd46e7113f119b9fde.tar.bz2
translated-content-1407c8fdef01ecd0ffb8a8bd46e7113f119b9fde.zip
convert content to md
Diffstat (limited to 'files/fr/web/api/subtlecrypto')
-rw-r--r--files/fr/web/api/subtlecrypto/digest/index.md136
-rw-r--r--files/fr/web/api/subtlecrypto/index.md476
2 files changed, 286 insertions, 326 deletions
diff --git a/files/fr/web/api/subtlecrypto/digest/index.md b/files/fr/web/api/subtlecrypto/digest/index.md
index eee3e4668d..2a3b3b4098 100644
--- a/files/fr/web/api/subtlecrypto/digest/index.md
+++ b/files/fr/web/api/subtlecrypto/digest/index.md
@@ -3,73 +3,63 @@ title: SubtleCrypto.digest()
slug: Web/API/SubtleCrypto/digest
translation_of: Web/API/SubtleCrypto/digest
---
-<div>{{APIRef("Web Crypto API")}}{{SecureContext_header}}</div>
+{{APIRef("Web Crypto API")}}{{SecureContext_header}}
-<p>La méthode <code><strong>digest()</strong></code> de l'interface {{domxref("SubtleCrypto")}} génère un {{Glossary("digest")}} de la donnée fournie. Un condensé est une petite valeur de taille fixe issue d'une donnée de taille variable. Les condensés cryptographiques doivent résister à la collision, ce qui signifie qu'il doit être très difficile d'obtenir le même condensé à partir de deux entrés différentes.</p>
+La méthode **`digest()`** de l'interface {{domxref("SubtleCrypto")}} génère un {{Glossary("digest")}} de la donnée fournie. Un condensé est une petite valeur de taille fixe issue d'une donnée de taille variable. Les condensés cryptographiques doivent résister à la collision, ce qui signifie qu'il doit être très difficile d'obtenir le même condensé à partir de deux entrés différentes.
-<p>Il prend en argument un identifiant pour l'algorithme de condensé et les données à traiter. Il retourne une {{jsxref("Promise")}} qui contiendra le condensé.</p>
+Il prend en argument un identifiant pour l'algorithme de condensé et les données à traiter. Il retourne une {{jsxref("Promise")}} qui contiendra le condensé.
-<h2 id="Syntaxe">Syntaxe</h2>
+## Syntaxe
-<pre class="syntaxbox">const digest = <em>crypto</em><code>.subtle.digest(<em>algorithm</em>, <em>data</em>)</code>;
-</pre>
+ const digest = crypto.subtle.digest(algorithm, data);
-<h3 id="Paramètres">Paramètres</h3>
+### Paramètres
-<ul>
- <li><em><code>algorithm</code></em> est une {{domxref("DOMString")}} indiquant la fonction de condensé à utiliser. Les valeurs possibles sont:
+- _`algorithm`_ est une {{domxref("DOMString")}} indiquant la fonction de condensé à utiliser. Les valeurs possibles sont:
- <ul>
- <li><code>SHA-1</code> (ne pas utiliser pour des applications cryptographiques)</li>
- <li><code>SHA-256</code></li>
- <li><code>SHA-384</code></li>
- <li><code>SHA-512</code>.</li>
- </ul>
- </li>
- <li><em><code>data</code></em> est un {{jsxref("ArrayBuffer")}} ou un {{domxref("ArrayBufferView")}} contenant les données à traiter.</li>
-</ul>
+ - `SHA-1` (ne pas utiliser pour des applications cryptographiques)
+ - `SHA-256`
+ - `SHA-384`
+ - `SHA-512`.
-<h3 id="Valeur_retournée">Valeur retournée</h3>
+- _`data`_ est un {{jsxref("ArrayBuffer")}} ou un {{domxref("ArrayBufferView")}} contenant les données à traiter.
-<ul>
- <li><code><em>digest</em></code> est une {{jsxref("Promise")}} pour accéder {{jsxref("ArrayBuffer")}} au condensé.</li>
-</ul>
+### Valeur retournée
-<h2 id="Algorithmes_supportés">Algorithmes supportés</h2>
+- `digest` est une {{jsxref("Promise")}} pour accéder {{jsxref("ArrayBuffer")}} au condensé.
-<p>Les algorithmes de condensé, aussi connue sous le nom de <a href="/fr/docs/Glossaire/Fonction_de_hachage_cryptographique">fonctions de hachage cryptographique</a>, transforme un bloque de données de longueur arbitraire dans un résultat de taille fixe, souvent plus petit que l'entré. Ils ont de nombreuses utilisations en cryptographie.</p>
+## Algorithmes supportés
-<h3 id="SHA-1">SHA-1</h3>
+Les algorithmes de condensé, aussi connue sous le nom de [fonctions de hachage cryptographique](/fr/docs/Glossaire/Fonction_de_hachage_cryptographique), transforme un bloque de données de longueur arbitraire dans un résultat de taille fixe, souvent plus petit que l'entré. Ils ont de nombreuses utilisations en cryptographie.
-<p>Cet algorithme est spécifié dans <a href="https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf">FIPS 180-4</a>, section 6.1, et produit un résultat de 160 bits de long.</p>
+### SHA-1
-<div class="warning">
-<p><strong>Attention :</strong> Cet algorithme est maintenant considérer comme vulnérable et ne doit pas être utilisé pour des applications cryptographiques.</p>
-</div>
+Cet algorithme est spécifié dans [FIPS 180-4](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf), section 6.1, et produit un résultat de 160 bits de long.
-<h3 id="SHA-256">SHA-256</h3>
+> **Attention :** Cet algorithme est maintenant considérer comme vulnérable et ne doit pas être utilisé pour des applications cryptographiques.
-<p>Cet algorithme est spécifié dans <a href="https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf">FIPS 180-4</a>, section 6.2, et produit un résultat de 256 bits de long.</p>
+### SHA-256
-<h3 id="SHA-384">SHA-384</h3>
+Cet algorithme est spécifié dans [FIPS 180-4](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf), section 6.2, et produit un résultat de 256 bits de long.
-<p>Cet algorithme est spécifié dans <a href="https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf">FIPS 180-4</a>, section 6.5, et produit un résultat de 384 bits de long.</p>
+### SHA-384
-<h3 id="SHA-512">SHA-512</h3>
+Cet algorithme est spécifié dans [FIPS 180-4](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf), section 6.5, et produit un résultat de 384 bits de long.
-<p>Cet algorithme est spécifié dans <a href="https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf">FIPS 180-4</a>, section 6.4, et produit un résultat de 512 bits de long.</p>
+### SHA-512
-<div class="note">
-<p><strong>Note :</strong> Si vous cherchez à créer un condensé pour authentifié un message (<a href="/fr/docs/Glossary/HMAC">HMAC</a>), vous aurez plutôt besoin de <a href="/en-US/docs/Web/API/SubtleCrypto/sign#HMAC">SubtleCrypto.sign()</a>.</p>
-</div>
+Cet algorithme est spécifié dans [FIPS 180-4](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf), section 6.4, et produit un résultat de 512 bits de long.
-<h2 id="Exemples">Exemples</h2>
+> **Note :** Si vous cherchez à créer un condensé pour authentifié un message ([HMAC](/fr/docs/Glossary/HMAC)), vous aurez plutôt besoin de [SubtleCrypto.sign()](/en-US/docs/Web/API/SubtleCrypto/sign#HMAC).
-<h3 id="Exemple_basique">Exemple basique</h3>
+## Exemples
-<p>Cet exemple encode un message, puis calcule le condensé avec SHA-256, enfin affiche la longueur du résultat.</p>
+### Exemple basique
-<pre class="brush: js">const text = 'Un obscur message venant du le système S-K, votre majesté. Ses habitants le nomment la planète Terre.';
+Cet exemple encode un message, puis calcule le condensé avec SHA-256, enfin affiche la longueur du résultat.
+
+```js
+const text = 'Un obscur message venant du le système S-K, votre majesté. Ses habitants le nomment la planète Terre.';
async function digestMessage(message) {
const encoder = new TextEncoder();
@@ -80,54 +70,40 @@ async function digestMessage(message) {
const digestBuffer = await digestMessage(text);
console.log(digestBuffer.byteLength);
-</pre>
+```
-<h3 id="Convertir_un_condensé_vers_une_chaîne_hexadécimale">Convertir un condensé vers une chaîne hexadécimale</h3>
+### Convertir un condensé vers une chaîne hexadécimale
-<p>Le condensé est retourné sous forme d'un <code>ArrayBuffer</code>, mais la comparaison et l'affichage se fait souvent avec des chaînes hexadécimales. Cet exemple calcule un condensé puis converti l'<code>ArrayBuffer</code> vers une chaîne hexadécimale.</p>
+Le condensé est retourné sous forme d'un `ArrayBuffer`, mais la comparaison et l'affichage se fait souvent avec des chaînes hexadécimales. Cet exemple calcule un condensé puis converti l'`ArrayBuffer` vers une chaîne hexadécimale.
-<pre class="brush: js">const text = 'Un obscur message venant du le système S-K, votre majesté. Ses habitants le nomment la planète Terre.';
+```js
+const text = 'Un obscur message venant du le système S-K, votre majesté. Ses habitants le nomment la planète Terre.';
async function digestMessage(message) {
const msgUint8 = new TextEncoder().encode(message); // encode comme (utf-8) Uint8Array
const hashBuffer = await crypto.subtle.digest('SHA-256', msgUint8); // fait le condensé
const hashArray = Array.from(new Uint8Array(hashBuffer)); // convertit le buffer en tableau d'octet
- const hashHex = hashArray.map(b =&gt; b.toString(16).padStart(2, '0')).join(''); // convertit le tableau en chaîne hexadélimale
+ const hashHex = hashArray.map(b => b.toString(16).padStart(2, '0')).join(''); // convertit le tableau en chaîne hexadélimale
return hashHex;
}
const digestHex = await digestMessage(text);
console.log(digestHex);
-</pre>
-
-<h2 id="Spécifications">Spécifications</h2>
-
-<table class="standard-table">
- <tbody>
- <tr>
- <th scope="col">Spécifications</th>
- <th scope="col">Statue</th>
- <th scope="col">Commentaire</th>
- </tr>
- <tr>
- <td>{{SpecName('Web Crypto API', '#dfn-SubtleCrypto-method-digest', 'SubtleCrypto.digest()')}}</td>
- <td>{{Spec2('Web Crypto API')}}</td>
- <td>Définition intiale</td>
- </tr>
- </tbody>
-</table>
-
-<h2 id="Compatibilité_des_navigateurs">Compatibilité des navigateurs</h2>
-
-<p>{{Compat("api.SubtleCrypto.digest")}}</p>
-
-<div class="note">
-<p><strong>Note :</strong> Dans Chrome 60, une fonctionnalité a été ajoutée qui désactive <strong>crypto.subtle</strong> pour les connexions non TLS.</p>
-</div>
-
-<h2 id="Voir_aussi">Voir aussi</h2>
-
-<ul>
- <li><a href="https://www.chromium.org/Home/chromium-security/prefer-secure-origins-for-powerful-new-features">(en) Chromium secure origins specification</a></li>
- <li><a href="https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf" rel="noopener">(en) FIPS 180-4</a> spécifie les algorithmes de condensé de la famille SHA.</li>
-</ul>
+```
+
+## Spécifications
+
+| Spécifications | Statue | Commentaire |
+| ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------ | ------------------ |
+| {{SpecName('Web Crypto API', '#dfn-SubtleCrypto-method-digest', 'SubtleCrypto.digest()')}} | {{Spec2('Web Crypto API')}} | Définition intiale |
+
+## Compatibilité des navigateurs
+
+{{Compat("api.SubtleCrypto.digest")}}
+
+> **Note :** Dans Chrome 60, une fonctionnalité a été ajoutée qui désactive **crypto.subtle** pour les connexions non TLS.
+
+## Voir aussi
+
+- [(en) Chromium secure origins specification](https://www.chromium.org/Home/chromium-security/prefer-secure-origins-for-powerful-new-features)
+- [(en) FIPS 180-4](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf) spécifie les algorithmes de condensé de la famille SHA.
diff --git a/files/fr/web/api/subtlecrypto/index.md b/files/fr/web/api/subtlecrypto/index.md
index b9cca851e9..dc6bb3bfe3 100644
--- a/files/fr/web/api/subtlecrypto/index.md
+++ b/files/fr/web/api/subtlecrypto/index.md
@@ -14,285 +14,269 @@ tags:
- Web Crypto API
translation_of: Web/API/SubtleCrypto
---
-<div>{{APIRef("Web Crypto API")}}{{SecureContext_header}}</div>
+{{APIRef("Web Crypto API")}}{{SecureContext_header}}
-<p>The <code><strong>SubtleCrypto</strong></code> interface of the <a href="/en-US/docs/Web/API/Web_Crypto_API">Web Crypto API</a> provides a number of low-level cryptographic functions. Access to the features of <code>SubtleCrypto</code> is obtained through the {{domxref("Crypto.subtle", "subtle")}} property of the {{domxref("Crypto")}} object you get from {{domxref("Window.crypto")}}.</p>
+The **`SubtleCrypto`** interface of the [Web Crypto API](/en-US/docs/Web/API/Web_Crypto_API) provides a number of low-level cryptographic functions. Access to the features of `SubtleCrypto` is obtained through the {{domxref("Crypto.subtle", "subtle")}} property of the {{domxref("Crypto")}} object you get from {{domxref("Window.crypto")}}.
-<div class="warning">
-<p><strong>Warning:</strong> 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.</p>
+> **Attention :** 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.**
-<p>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.</p>
+## Properties
-<p>Errors in security system design and implementation can make the security of the system completely ineffective.</p>
+_This interface doesn't inherit any properties, as it has no parent interface._
-<p><strong>If you're not sure you know what you are doing, you probably shouldn't be using this API.</strong></p>
-</div>
+## Methods
-<h2 id="Properties">Properties</h2>
+_This interface doesn't inherit any methods, as it has no parent interface._
-<p><em>This interface doesn't inherit any properties, as it has no parent interface.</em></p>
+- {{domxref("SubtleCrypto.encrypt()")}}
+ - : Returns a {{jsxref("Promise")}} that fufills with the encrypted data corresponding to the clear text, algorithm, and key given as parameters.
+- {{domxref("SubtleCrypto.decrypt()")}}
+ - : Returns a {{jsxref("Promise")}} that fulfills with the clear data corresponding to the encrypted text, algorithm, and key given as parameters.
+- {{domxref("SubtleCrypto.sign()")}}
+ - : Returns a {{jsxref("Promise")}} that fulfills with the signature corresponding to the text, algorithm, and key given as parameters.
+- {{domxref("SubtleCrypto.verify()")}}
+ - : Returns a {{jsxref("Promise")}} that fulfills with a {{jsxref("Boolean")}} value indicating if the signature given as a parameter matches the text, algorithm, and key that are also given as parameters.
+- {{domxref("SubtleCrypto.digest()")}}
+ - : Returns a {{jsxref("Promise")}} that fulfills with a digest generated from the algorithm and text given as parameters.
+- {{domxref("SubtleCrypto.generateKey()")}}
+ - : Returns a {{jsxref("Promise")}} that fulfills with a newly-generated {{domxref("CryptoKey")}}, for symmetrical algorithms, or a {{domxref("CryptoKeyPair")}}, containing two newly generated keys, for asymmetrical algorithms. These will match the algorithm, usages, and extractability given as parameters.
+- {{domxref("SubtleCrypto.deriveKey()")}}
+ - : Returns a {{jsxref("Promise")}} that fulfills with a newly generated {{domxref("CryptoKey")}} derived from the master key and specific algorithm given as parameters.
+- {{domxref("SubtleCrypto.deriveBits()")}}
+ - : Returns a {{jsxref("Promise")}} that fulfills with a newly generated buffer of pseudo-random bits derived from the master key and specific algorithm given as parameters.
+- {{domxref("SubtleCrypto.importKey()")}}
+ - : Returns a {{jsxref("Promise")}} that fulfills with a {{domxref("CryptoKey")}} corresponding to the format, the algorithm, raw key data, usages, and extractability given as parameters.
+- {{domxref("SubtleCrypto.exportKey()")}}
+ - : Returns a {{jsxref("Promise")}} that fulfills with a buffer containing the key in the requested format.
+- {{domxref("SubtleCrypto.wrapKey()")}}
+ - : Returns a {{jsxref("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.
+- {{domxref("SubtleCrypto.unwrapKey()")}}
+ - : Returns a {{jsxref("Promise")}} that fulfills with a {{domxref("CryptoKey")}} corresponding to the wrapped key given in the parameter.
-<h2 id="Methods">Methods</h2>
+## Using SubtleCrypto
-<p><em>This interface doesn't inherit any methods, as it has no parent interface.</em></p>
+We can split the functions implemented by this API into two groups: cryptography functions and key management functions.
-<dl>
- <dt>{{domxref("SubtleCrypto.encrypt()")}}</dt>
- <dd>Returns a {{jsxref("Promise")}} that fufills with the encrypted data corresponding to the clear text, algorithm, and key given as parameters.</dd>
- <dt>{{domxref("SubtleCrypto.decrypt()")}}</dt>
- <dd>Returns a {{jsxref("Promise")}} that fulfills with the clear data corresponding to the encrypted text, algorithm, and key given as parameters.</dd>
- <dt>{{domxref("SubtleCrypto.sign()")}}</dt>
- <dd>Returns a {{jsxref("Promise")}} that fulfills with the signature corresponding to the text, algorithm, and key given as parameters.</dd>
- <dt>{{domxref("SubtleCrypto.verify()")}}</dt>
- <dd>Returns a {{jsxref("Promise")}} that fulfills with a {{jsxref("Boolean")}} value indicating if the signature given as a parameter matches the text, algorithm, and key that are also given as parameters.</dd>
- <dt>{{domxref("SubtleCrypto.digest()")}}</dt>
- <dd>Returns a {{jsxref("Promise")}} that fulfills with a digest generated from the algorithm and text given as parameters.</dd>
- <dt>{{domxref("SubtleCrypto.generateKey()")}}</dt>
- <dd>Returns a {{jsxref("Promise")}} that fulfills with a newly-generated {{domxref("CryptoKey")}}, for symmetrical algorithms, or a {{domxref("CryptoKeyPair")}}, containing two newly generated keys, for asymmetrical algorithms. These will match the algorithm, usages, and extractability given as parameters.</dd>
- <dt>{{domxref("SubtleCrypto.deriveKey()")}}</dt>
- <dd>Returns a {{jsxref("Promise")}} that fulfills with a newly generated {{domxref("CryptoKey")}} derived from the master key and specific algorithm given as parameters.</dd>
- <dt>{{domxref("SubtleCrypto.deriveBits()")}}</dt>
- <dd>Returns a {{jsxref("Promise")}} that fulfills with a newly generated buffer of pseudo-random bits derived from the master key and specific algorithm given as parameters.</dd>
- <dt>{{domxref("SubtleCrypto.importKey()")}}</dt>
- <dd>Returns a {{jsxref("Promise")}} that fulfills with a {{domxref("CryptoKey")}} corresponding to the format, the algorithm, raw key data, usages, and extractability given as parameters.</dd>
- <dt>{{domxref("SubtleCrypto.exportKey()")}}</dt>
- <dd>Returns a {{jsxref("Promise")}} that fulfills with a buffer containing the key in the requested format.</dd>
- <dt>{{domxref("SubtleCrypto.wrapKey()")}}</dt>
- <dd>Returns a {{jsxref("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.</dd>
- <dt>{{domxref("SubtleCrypto.unwrapKey()")}}</dt>
- <dd>Returns a {{jsxref("Promise")}} that fulfills with a {{domxref("CryptoKey")}} corresponding to the wrapped key given in the parameter.</dd>
-</dl>
+### Cryptography functions
-<h2 id="Using_SubtleCrypto">Using SubtleCrypto</h2>
+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:
-<p>We can split the functions implemented by this API into two groups: cryptography functions and key management functions.</p>
+\* {{DOMxRef("SubtleCrypto.sign","sign()")}} and {{DOMxRef("SubtleCrypto.verify","verify()")}}: create and verify digital signatures.
+\* {{DOMxRef("SubtleCrypto.encrypt","encrypt()")}} and {{DOMxRef("SubtleCrypto.decrypt","decrypt()")}}: encrypt and decrypt data. \* {{DOMxRef("SubtleCrypto.digest","digest()")}}: create a fixed-length, collision-resistant digest of some data.
-<h3 id="Cryptography_functions">Cryptography functions</h3>
+### Key management functions
-<p>These are the functions you can use to implement security features such as privacy and authentication in a system. The <code>SubtleCrypto</code> API provides the following cryptography functions:</p>
+Except for {{DOMxRef("SubtleCrypto.digest","digest()")}}, all the cryptography functions in the API use cryptographic keys. In the `SubtleCrypto` API a cryptographic key is represented using a {{DOMxRef("CryptoKey","CryptoKey")}} object. To perform operations like signing and encrypting, you pass a {{DOMxRef("CryptoKey","CryptoKey")}} object into the {{DOMxRef("SubtleCrypto.sign","sign()")}} or {{DOMxRef("SubtleCrypto.encrypt","encrypt()")}} function.
-<p>* {{DOMxRef("SubtleCrypto.sign","sign()")}} and {{DOMxRef("SubtleCrypto.verify","verify()")}}: create and verify digital signatures.<br>
- * {{DOMxRef("SubtleCrypto.encrypt","encrypt()")}} and {{DOMxRef("SubtleCrypto.decrypt","decrypt()")}}: encrypt and decrypt data.<br>
- * {{DOMxRef("SubtleCrypto.digest","digest()")}}: create a fixed-length, collision-resistant digest of some data.</p>
+#### Generating and deriving keys
-<h3 id="Key_management_functions">Key management functions</h3>
+The {{DOMxRef("SubtleCrypto.generateKey","generateKey()")}} and {{DOMxRef("SubtleCrypto.deriveKey","deriveKey()")}} functions both create a new {{DOMxRef("CryptoKey")}} object.
-<p>Except for {{DOMxRef("SubtleCrypto.digest","digest()")}}, all the cryptography functions in the API use cryptographic keys. In the <code>SubtleCrypto</code> API a cryptographic key is represented using a {{DOMxRef("CryptoKey","CryptoKey")}} object. To perform operations like signing and encrypting, you pass a {{DOMxRef("CryptoKey","CryptoKey")}} object into the {{DOMxRef("SubtleCrypto.sign","sign()")}} or {{DOMxRef("SubtleCrypto.encrypt","encrypt()")}} function.</p>
+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.
-<h4 id="Generating_and_deriving_keys">Generating and deriving keys</h4>
+#### Importing and exporting keys
-<p>The {{DOMxRef("SubtleCrypto.generateKey","generateKey()")}} and {{DOMxRef("SubtleCrypto.deriveKey","deriveKey()")}} functions both create a new {{DOMxRef("CryptoKey")}} object.</p>
+To make keys available outside your app, you need to export the key, and that's what {{DOMxRef("SubtleCrypto.exportKey","exportKey()")}} is for. You can choose one of a number of export formats.
-<p>The difference is that <code>generateKey()</code> will generate a new distinct key value each time you call it, while <code>deriveKey()</code> derives a key from some initial keying material. If you provide the same keying material to two separate calls to <code>deriveKey()</code>, you will get two <code>CryptoKey</code> 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.</p>
+The inverse of `exportKey()` is {{DOMxRef("SubtleCrypto.importKey","importKey()")}}. You can import keys from other systems, and support for standard formats like [PKCS #8](https://tools.ietf.org/html/rfc5208) and [JSON Web Key](https://tools.ietf.org/html/rfc7517) helps you do this. The `exportKey()` function exports the key in an unencrypted format.
-<h4 id="Importing_and_exporting_keys">Importing and exporting keys</h4>
+If the key is sensitive you should use {{DOMxRef("SubtleCrypto.wrapKey","wrapKey()")}}, which exports the key and then encrypts it using another key; the API calls a "key-wrapping key".
-<p>To make keys available outside your app, you need to export the key, and that's what {{DOMxRef("SubtleCrypto.exportKey","exportKey()")}} is for. You can choose one of a number of export formats.</p>
+The inverse of `wrapKey()` is {{DOMxRef("SubtleCrypto.unwrapKey","unwrapKey()")}}, which decrypts then imports the key.
-<p>The inverse of <code>exportKey()</code> is {{DOMxRef("SubtleCrypto.importKey","importKey()")}}. You can import keys from other systems, and support for standard formats like <a href="https://tools.ietf.org/html/rfc5208">PKCS #8</a> and <a href="https://tools.ietf.org/html/rfc7517">JSON Web Key</a> helps you do this. The <code>exportKey()</code> function exports the key in an unencrypted format.</p>
+#### Storing keys
-<p>If the key is sensitive you should use {{DOMxRef("SubtleCrypto.wrapKey","wrapKey()")}}, which exports the key and then encrypts it using another key; the API calls a "key-wrapping key".</p>
+`CryptoKey` objects can be stored using the [structured clone algorithm](/en-US/docs/Web/API/Web_Workers_API/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](/en-US/docs/Web/API/IndexedDB_API) to store `CryptoKey` objects.
-<p>The inverse of <code>wrapKey()</code> is {{DOMxRef("SubtleCrypto.unwrapKey","unwrapKey()")}}, which decrypts then imports the key.</p>
+### Supported algorithms
-<h4 id="Storing_keys">Storing keys</h4>
+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.
-<p><code>CryptoKey</code> objects can be stored using the <a href="/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm">structured clone algorithm</a>, meaning that you can store and retrieve them using standard web storage APIs. The specification expects that most developers will use the <a href="/en-US/docs/Web/API/IndexedDB_API">IndexedDB API</a> to store <code>CryptoKey</code> objects.</p>
-
-<h3 id="Supported_algorithms">Supported algorithms</h3>
-
-<p>The cryptographic functions provided by the Web Crypto API can be performed by one or more different <em>cryptographic algorithms</em>: the <code>algorithm</code> argument to the function indicates which algorithm to use. Some algorithms need extra parameters: in these cases the <code>algorithm</code> argument is a dictionary object that includes the extra parameters.</p>
-
-<p>The table below summarises which algorithms are suitable for which cryptographic operations:</p>
-
-<table class="standard-table">
- <thead>
- <tr>
- <th scope="row"></th>
- <th scope="col">
- <p><a href="/en-US/docs/Web/API/SubtleCrypto/sign">sign()</a></p>
-
- <p><a href="/en-US/docs/Web/API/SubtleCrypto/verify">verify()</a></p>
- </th>
- <th scope="col">
- <p><a href="/en-US/docs/Web/API/SubtleCrypto/encrypt">encrypt()</a></p>
-
- <p><a href="/en-US/docs/Web/API/SubtleCrypto/decrypt">decrypt()</a></p>
- </th>
- <th scope="col"><a href="/en-US/docs/Web/API/SubtleCrypto/digest">digest()</a></th>
- <th scope="col">
- <p><a href="/en-US/docs/Web/API/SubtleCrypto/deriveBits">deriveBits()</a></p>
-
- <p><a href="/en-US/docs/Web/API/SubtleCrypto/deriveKey">deriveKey()</a></p>
- </th>
- <th scope="col">
- <p><a href="/en-US/docs/Web/API/SubtleCrypto/wrapKey">wrapKey()</a></p>
-
- <p><a href="/en-US/docs/Web/API/SubtleCrypto/unwrapKey">unwrapKey()</a></p>
- </th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <th scope="row">RSASSA-PKCS1-v1_5</th>
- <td>✓</td>
- <td></td>
- <td></td>
- <td></td>
- <td></td>
- </tr>
- <tr>
- <th scope="row">RSA-PSS</th>
- <td>✓</td>
- <td></td>
- <td></td>
- <td></td>
- <td></td>
- </tr>
- <tr>
- <th scope="row">ECDSA</th>
- <td>✓</td>
- <td></td>
- <td></td>
- <td></td>
- <td></td>
- </tr>
- <tr>
- <th scope="row">HMAC</th>
- <td>✓</td>
- <td></td>
- <td></td>
- <td></td>
- <td></td>
- </tr>
- <tr>
- <th scope="row">RSA-OAEP</th>
- <td></td>
- <td>✓</td>
- <td></td>
- <td></td>
- <td>✓</td>
- </tr>
- <tr>
- <th scope="row">AES-CTR</th>
- <td></td>
- <td>✓</td>
- <td></td>
- <td></td>
- <td>✓</td>
- </tr>
- <tr>
- <th scope="row">AES-CBC</th>
- <td></td>
- <td>✓</td>
- <td></td>
- <td></td>
- <td>✓</td>
- </tr>
- <tr>
- <th scope="row">AES-GCM</th>
- <td></td>
- <td>✓</td>
- <td></td>
- <td></td>
- <td>✓</td>
- </tr>
- <tr>
- <th scope="row">SHA-1</th>
- <td></td>
- <td></td>
- <td>✓</td>
- <td></td>
- <td></td>
- </tr>
- <tr>
- <th scope="row">SHA-256</th>
- <td></td>
- <td></td>
- <td>✓</td>
- <td></td>
- <td></td>
- </tr>
- <tr>
- <th scope="row">SHA-384</th>
- <td></td>
- <td></td>
- <td>✓</td>
- <td></td>
- <td></td>
- </tr>
- <tr>
- <th scope="row">SHA-512</th>
- <td></td>
- <td></td>
- <td>✓</td>
- <td></td>
- <td></td>
- </tr>
- <tr>
- <th scope="row">ECDH</th>
- <td></td>
- <td></td>
- <td></td>
- <td>✓</td>
- <td></td>
- </tr>
- <tr>
- <th scope="row">HKDF</th>
- <td></td>
- <td></td>
- <td></td>
- <td>✓</td>
- <td></td>
- </tr>
- <tr>
- <th scope="row">PBKDF2</th>
- <td></td>
- <td></td>
- <td></td>
- <td>✓</td>
- <td></td>
- </tr>
- <tr>
- <th scope="row">AES-KW</th>
- <td></td>
- <td></td>
- <td></td>
- <td></td>
- <td>✓</td>
- </tr>
- </tbody>
-</table>
-
-<h2 id="Specifications">Specifications</h2>
+The table below summarises which algorithms are suitable for which cryptographic operations:
<table class="standard-table">
- <tbody>
- <tr>
- <th scope="col">Specification</th>
- <th scope="col">Status</th>
- <th scope="col">Comment</th>
- </tr>
- <tr>
- <td>{{ SpecName('Web Crypto API', '#subtlecrypto-interface', 'SubtleCrypto') }}</td>
- <td>{{ Spec2('Web Crypto API') }}</td>
- <td>Initial definition.</td>
- </tr>
- </tbody>
+ <thead>
+ <tr>
+ <th scope="row"></th>
+ <th scope="col">
+ <p><a href="/en-US/docs/Web/API/SubtleCrypto/sign">sign()</a></p>
+ <p><a href="/en-US/docs/Web/API/SubtleCrypto/verify">verify()</a></p>
+ </th>
+ <th scope="col">
+ <p><a href="/en-US/docs/Web/API/SubtleCrypto/encrypt">encrypt()</a></p>
+ <p><a href="/en-US/docs/Web/API/SubtleCrypto/decrypt">decrypt()</a></p>
+ </th>
+ <th scope="col">
+ <a href="/en-US/docs/Web/API/SubtleCrypto/digest">digest()</a>
+ </th>
+ <th scope="col">
+ <p>
+ <a href="/en-US/docs/Web/API/SubtleCrypto/deriveBits">deriveBits()</a>
+ </p>
+ <p>
+ <a href="/en-US/docs/Web/API/SubtleCrypto/deriveKey">deriveKey()</a>
+ </p>
+ </th>
+ <th scope="col">
+ <p><a href="/en-US/docs/Web/API/SubtleCrypto/wrapKey">wrapKey()</a></p>
+ <p>
+ <a href="/en-US/docs/Web/API/SubtleCrypto/unwrapKey">unwrapKey()</a>
+ </p>
+ </th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <th scope="row">RSASSA-PKCS1-v1_5</th>
+ <td>✓</td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ </tr>
+ <tr>
+ <th scope="row">RSA-PSS</th>
+ <td>✓</td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ </tr>
+ <tr>
+ <th scope="row">ECDSA</th>
+ <td>✓</td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ </tr>
+ <tr>
+ <th scope="row">HMAC</th>
+ <td>✓</td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ </tr>
+ <tr>
+ <th scope="row">RSA-OAEP</th>
+ <td></td>
+ <td>✓</td>
+ <td></td>
+ <td></td>
+ <td>✓</td>
+ </tr>
+ <tr>
+ <th scope="row">AES-CTR</th>
+ <td></td>
+ <td>✓</td>
+ <td></td>
+ <td></td>
+ <td>✓</td>
+ </tr>
+ <tr>
+ <th scope="row">AES-CBC</th>
+ <td></td>
+ <td>✓</td>
+ <td></td>
+ <td></td>
+ <td>✓</td>
+ </tr>
+ <tr>
+ <th scope="row">AES-GCM</th>
+ <td></td>
+ <td>✓</td>
+ <td></td>
+ <td></td>
+ <td>✓</td>
+ </tr>
+ <tr>
+ <th scope="row">SHA-1</th>
+ <td></td>
+ <td></td>
+ <td>✓</td>
+ <td></td>
+ <td></td>
+ </tr>
+ <tr>
+ <th scope="row">SHA-256</th>
+ <td></td>
+ <td></td>
+ <td>✓</td>
+ <td></td>
+ <td></td>
+ </tr>
+ <tr>
+ <th scope="row">SHA-384</th>
+ <td></td>
+ <td></td>
+ <td>✓</td>
+ <td></td>
+ <td></td>
+ </tr>
+ <tr>
+ <th scope="row">SHA-512</th>
+ <td></td>
+ <td></td>
+ <td>✓</td>
+ <td></td>
+ <td></td>
+ </tr>
+ <tr>
+ <th scope="row">ECDH</th>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td>✓</td>
+ <td></td>
+ </tr>
+ <tr>
+ <th scope="row">HKDF</th>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td>✓</td>
+ <td></td>
+ </tr>
+ <tr>
+ <th scope="row">PBKDF2</th>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td>✓</td>
+ <td></td>
+ </tr>
+ <tr>
+ <th scope="row">AES-KW</th>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td>✓</td>
+ </tr>
+ </tbody>
</table>
-<h2 id="Browser_compatibility">Browser compatibility</h2>
+## Specifications
+| Specification | Status | Comment |
+| ---------------------------------------------------------------------------------------------------- | ---------------------------------------- | ------------------- |
+| {{ SpecName('Web Crypto API', '#subtlecrypto-interface', 'SubtleCrypto') }} | {{ Spec2('Web Crypto API') }} | Initial definition. |
+## Browser compatibility
-<p>{{Compat("api.SubtleCrypto")}}</p>
+{{Compat("api.SubtleCrypto")}}
-<h2 id="See_also">See also</h2>
+## See also
-<ul>
- <li><a href="/en-US/docs/Web/API/Web_Crypto_API">Web Crypto API</a></li>
- <li><a href="/en-US/docs/Web/Security">Web security</a></li>
- <li><a href="/en-US/docs/Web/Privacy">Privacy, permissions, and information security</a></li>
- <li>{{domxref("Crypto")}} and {{domxref("Crypto.subtle")}}.</li>
- <li><a href="https://www.crypto101.io/">Crypto 101</a>: an introductory course on cryptography.</li>
-</ul>
+- [Web Crypto API](/en-US/docs/Web/API/Web_Crypto_API)
+- [Web security](/en-US/docs/Web/Security)
+- [Privacy, permissions, and information security](/en-US/docs/Web/Privacy)
+- {{domxref("Crypto")}} and {{domxref("Crypto.subtle")}}.
+- [Crypto 101](https://www.crypto101.io/): an introductory course on cryptography.