API Web Crypto

[Historique]

Version	Modifications
v23.5.0	Les algorithmes `Ed25519` et `X25519` sont maintenant stables.
v19.0.0	N'est plus expérimental, sauf pour les algorithmes `Ed25519`, `Ed448`, `X25519` et `X448`.
v20.0.0, v18.17.0	Les arguments sont désormais forcés et validés conformément à leurs définitions WebIDL comme dans les autres implémentations de l'API Web Crypto.
v18.4.0, v16.17.0	Suppression du format d'import/export propriétaire `'node.keyObject'`.
v18.4.0, v16.17.0	Suppression des algorithmes propriétaires `'NODE-DSA'`, `'NODE-DH'` et `'NODE-SCRYPT'`.
v18.4.0, v16.17.0	Ajout des algorithmes `'Ed25519'`, `'Ed448'`, `'X25519'` et `'X448'`.
v18.4.0, v16.17.0	Suppression des algorithmes propriétaires `'NODE-ED25519'` et `'NODE-ED448'`.
v18.4.0, v16.17.0	Suppression des courbes nommées propriétaires `'NODE-X25519'` et `'NODE-X448'` de l'algorithme `'ECDH'`.

[Stable: 2 - Stable]

Stable: 2 Stabilité : 2 - Stable

Node.js fournit une implémentation de l'API standard Web Crypto.

Utilisez globalThis.crypto ou require('node:crypto').webcrypto pour accéder à ce module.

const { subtle } = globalThis.crypto;

(async function() {

  const key = await subtle.generateKey({
    name: 'HMAC',
    hash: 'SHA-256',
    length: 256,
  }, true, ['sign', 'verify']);

  const enc = new TextEncoder();
  const message = enc.encode('I love cupcakes');

  const digest = await subtle.sign({
    name: 'HMAC',
  }, key, message);

})();

Exemples

Génération de clés

La classe <SubtleCrypto> peut être utilisée pour générer des clés symétriques (secrètes) ou des paires de clés asymétriques (clé publique et clé privée).

Clés AES

const { subtle } = globalThis.crypto;

async function generateAesKey(length = 256) {
  const key = await subtle.generateKey({
    name: 'AES-CBC',
    length,
  }, true, ['encrypt', 'decrypt']);

  return key;
}

Paires de clés ECDSA

const { subtle } = globalThis.crypto;

async function generateEcKey(namedCurve = 'P-521') {
  const {
    publicKey,
    privateKey,
  } = await subtle.generateKey({
    name: 'ECDSA',
    namedCurve,
  }, true, ['sign', 'verify']);

  return { publicKey, privateKey };
}

Paires de clés Ed25519/X25519

const { subtle } = globalThis.crypto;

async function generateEd25519Key() {
  return subtle.generateKey({
    name: 'Ed25519',
  }, true, ['sign', 'verify']);
}

async function generateX25519Key() {
  return subtle.generateKey({
    name: 'X25519',
  }, true, ['deriveKey']);
}

Clés HMAC

const { subtle } = globalThis.crypto;

async function generateHmacKey(hash = 'SHA-256') {
  const key = await subtle.generateKey({
    name: 'HMAC',
    hash,
  }, true, ['sign', 'verify']);

  return key;
}

Paires de clés RSA

const { subtle } = globalThis.crypto;
const publicExponent = new Uint8Array([1, 0, 1]);

async function generateRsaKey(modulusLength = 2048, hash = 'SHA-256') {
  const {
    publicKey,
    privateKey,
  } = await subtle.generateKey({
    name: 'RSASSA-PKCS1-v1_5',
    modulusLength,
    publicExponent,
    hash,
  }, true, ['sign', 'verify']);

  return { publicKey, privateKey };
}

Chiffrement et déchiffrement

const crypto = globalThis.crypto;

async function aesEncrypt(plaintext) {
  const ec = new TextEncoder();
  const key = await generateAesKey();
  const iv = crypto.getRandomValues(new Uint8Array(16));

  const ciphertext = await crypto.subtle.encrypt({
    name: 'AES-CBC',
    iv,
  }, key, ec.encode(plaintext));

  return {
    key,
    iv,
    ciphertext,
  };
}

async function aesDecrypt(ciphertext, key, iv) {
  const dec = new TextDecoder();
  const plaintext = await crypto.subtle.decrypt({
    name: 'AES-CBC',
    iv,
  }, key, ciphertext);

  return dec.decode(plaintext);
}

Exportation et importation de clés

const { subtle } = globalThis.crypto;

async function generateAndExportHmacKey(format = 'jwk', hash = 'SHA-512') {
  const key = await subtle.generateKey({
    name: 'HMAC',
    hash,
  }, true, ['sign', 'verify']);

  return subtle.exportKey(format, key);
}

async function importHmacKey(keyData, format = 'jwk', hash = 'SHA-512') {
  const key = await subtle.importKey(format, keyData, {
    name: 'HMAC',
    hash,
  }, true, ['sign', 'verify']);

  return key;
}

Encapsulation et désencapsulation de clés

const { subtle } = globalThis.crypto;

async function generateAndWrapHmacKey(format = 'jwk', hash = 'SHA-512') {
  const [
    key,
    wrappingKey,
  ] = await Promise.all([
    subtle.generateKey({
      name: 'HMAC', hash,
    }, true, ['sign', 'verify']),
    subtle.generateKey({
      name: 'AES-KW',
      length: 256,
    }, true, ['wrapKey', 'unwrapKey']),
  ]);

  const wrappedKey = await subtle.wrapKey(format, key, wrappingKey, 'AES-KW');

  return { wrappedKey, wrappingKey };
}

async function unwrapHmacKey(
  wrappedKey,
  wrappingKey,
  format = 'jwk',
  hash = 'SHA-512') {

  const key = await subtle.unwrapKey(
    format,
    wrappedKey,
    wrappingKey,
    'AES-KW',
    { name: 'HMAC', hash },
    true,
    ['sign', 'verify']);

  return key;
}

Signature et vérification

const { subtle } = globalThis.crypto;

async function sign(key, data) {
  const ec = new TextEncoder();
  const signature =
    await subtle.sign('RSASSA-PKCS1-v1_5', key, ec.encode(data));
  return signature;
}

async function verify(key, signature, data) {
  const ec = new TextEncoder();
  const verified =
    await subtle.verify(
      'RSASSA-PKCS1-v1_5',
      key,
      signature,
      ec.encode(data));
  return verified;
}

Dérivation de bits et de clés

const { subtle } = globalThis.crypto;

async function pbkdf2(pass, salt, iterations = 1000, length = 256) {
  const ec = new TextEncoder();
  const key = await subtle.importKey(
    'raw',
    ec.encode(pass),
    'PBKDF2',
    false,
    ['deriveBits']);
  const bits = await subtle.deriveBits({
    name: 'PBKDF2',
    hash: 'SHA-512',
    salt: ec.encode(salt),
    iterations,
  }, key, length);
  return bits;
}

async function pbkdf2Key(pass, salt, iterations = 1000, length = 256) {
  const ec = new TextEncoder();
  const keyMaterial = await subtle.importKey(
    'raw',
    ec.encode(pass),
    'PBKDF2',
    false,
    ['deriveKey']);
  const key = await subtle.deriveKey({
    name: 'PBKDF2',
    hash: 'SHA-512',
    salt: ec.encode(salt),
    iterations,
  }, keyMaterial, {
    name: 'AES-GCM',
    length,
  }, true, ['encrypt', 'decrypt']);
  return key;
}

Digest

const { subtle } = globalThis.crypto;

async function digest(data, algorithm = 'SHA-512') {
  const ec = new TextEncoder();
  const digest = await subtle.digest(algorithm, ec.encode(data));
  return digest;
}

Matrice des algorithmes

Le tableau détaille les algorithmes pris en charge par l'implémentation de l'API Web Crypto de Node.js et les API prises en charge pour chacun :

Algorithme	`generateKey`	`exportKey`	`importKey`	`encrypt`	`decrypt`	`wrapKey`	`unwrapKey`	`deriveBits`	`deriveKey`	`sign`	`verify`	`digest`
`'RSASSA-PKCS1-v1_5'`	✔	✔	✔							✔	✔
`'RSA-PSS'`	✔	✔	✔							✔	✔
`'RSA-OAEP'`	✔	✔	✔	✔	✔	✔	✔
`'ECDSA'`	✔	✔	✔							✔	✔
`'Ed25519'`	✔	✔	✔							✔	✔
`'Ed448'`	✔	✔	✔							✔	✔
`'ECDH'`	✔	✔	✔					✔	✔
`'X25519'`	✔	✔	✔					✔	✔
`'X448'`	✔	✔	✔					✔	✔
`'AES-CTR'`	✔	✔	✔	✔	✔	✔	✔
`'AES-CBC'`	✔	✔	✔	✔	✔	✔	✔
`'AES-GCM'`	✔	✔	✔	✔	✔	✔	✔
`'AES-KW'`	✔	✔	✔			✔	✔
`'HMAC'`	✔	✔	✔							✔	✔
`'HKDF'`		✔	✔					✔	✔
`'PBKDF2'`		✔	✔					✔	✔
`'SHA-1'`												✔
`'SHA-256'`												✔
`'SHA-384'`												✔
`'SHA-512'`												✔

Classe : `Crypto`

Ajouté dans : v15.0.0

globalThis.crypto est une instance de la classe Crypto. Crypto est un singleton qui fournit un accès au reste de l’API crypto.

`crypto.subtle`

Ajouté dans : v15.0.0

Type : <SubtleCrypto>

Fournit un accès à l’API SubtleCrypto.

`crypto.getRandomValues(typedArray)`

Ajouté dans : v15.0.0

typedArray <Buffer> | <TypedArray>
Retourne : <Buffer> | <TypedArray>

Génère des valeurs aléatoires cryptographiquement fortes. Le typedArray donné est rempli de valeurs aléatoires, et une référence à typedArray est retournée.

Le typedArray donné doit être une instance basée sur des entiers de <TypedArray>, c’est-à-dire que Float32Array et Float64Array ne sont pas acceptés.

Une erreur sera levée si le typedArray donné est supérieur à 65 536 octets.

`crypto.randomUUID()`

Ajouté dans : v16.7.0

Renvoie : <string>

Génère un UUID aléatoire RFC 4122 version 4. L’UUID est généré à l’aide d’un générateur de nombres pseudo-aléatoires cryptographiques.

Class : `CryptoKey`

Ajouté dans : v15.0.0

`cryptoKey.algorithm`

Ajouté dans : v15.0.0

Type : <AesKeyGenParams> | <RsaHashedKeyGenParams> | <EcKeyGenParams> | <HmacKeyGenParams>

Un objet détaillant l’algorithme pour lequel la clé peut être utilisée ainsi que des paramètres supplémentaires spécifiques à l’algorithme.

Lecture seule.

`cryptoKey.extractable`

Ajouté dans : v15.0.0

Type : <boolean>

Lorsque true, la <CryptoKey> peut être extraite à l’aide de subtleCrypto.exportKey() ou de subtleCrypto.wrapKey().

Lecture seule.

`cryptoKey.type`

Ajouté dans : v15.0.0

Type : <string> Un parmi 'secret', 'private' ou 'public'.

Une chaîne identifiant si la clé est une clé symétrique ('secret') ou asymétrique ('private' ou 'public').

`cryptoKey.usages`

Ajouté dans : v15.0.0

Type : <string[]>

Un tableau de chaînes identifiant les opérations pour lesquelles la clé peut être utilisée.

Les utilisations possibles sont :

'encrypt' - La clé peut être utilisée pour chiffrer des données.
'decrypt' - La clé peut être utilisée pour déchiffrer des données.
'sign' - La clé peut être utilisée pour générer des signatures numériques.
'verify' - La clé peut être utilisée pour vérifier les signatures numériques.
'deriveKey' - La clé peut être utilisée pour dériver une nouvelle clé.
'deriveBits' - La clé peut être utilisée pour dériver des bits.
'wrapKey' - La clé peut être utilisée pour encapsuler une autre clé.
'unwrapKey' - La clé peut être utilisée pour désencapsuler une autre clé.

Les utilisations valides de la clé dépendent de l’algorithme de clé (identifié par cryptokey.algorithm.name).

Type de clé	`'encrypt'`	`'decrypt'`	`'sign'`	`'verify'`	`'deriveKey'`	`'deriveBits'`	`'wrapKey'`	`'unwrapKey'`
`'AES-CBC'`	✔	✔					✔	✔
`'AES-CTR'`	✔	✔					✔	✔
`'AES-GCM'`	✔	✔					✔	✔
`'AES-KW'`							✔	✔
`'ECDH'`					✔	✔
`'X25519'`					✔	✔
`'X448'`					✔	✔
`'ECDSA'`			✔	✔
`'Ed25519'`			✔	✔
`'Ed448'`			✔	✔
`'HDKF'`					✔	✔
`'HMAC'`			✔	✔
`'PBKDF2'`					✔	✔
`'RSA-OAEP'`	✔	✔					✔	✔
`'RSA-PSS'`			✔	✔
`'RSASSA-PKCS1-v1_5'`			✔	✔

Class: `CryptoKeyPair`

Ajouté dans : v15.0.0

CryptoKeyPair est un simple objet de dictionnaire avec des propriétés publicKey et privateKey, représentant une paire de clés asymétriques.

`cryptoKeyPair.privateKey`

Ajouté dans : v15.0.0

Type : <CryptoKey> Un <CryptoKey> dont le type sera 'private'.

`cryptoKeyPair.publicKey`

Ajouté dans : v15.0.0

Type : <CryptoKey> Un <CryptoKey> dont le type sera 'public'.

Class: `SubtleCrypto`

Ajouté dans : v15.0.0

`subtle.decrypt(algorithm, key, data)`

Ajouté dans : v15.0.0

algorithm : <RsaOaepParams> | <AesCtrParams> | <AesCbcParams> | <AesGcmParams>
key : <CryptoKey>
data : <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
Retourne : <Promise> Satisfait avec un <ArrayBuffer>

En utilisant la méthode et les paramètres spécifiés dans algorithm et le matériel de clé fourni par key, subtle.decrypt() tente de déchiffrer les data fournis. Si elle réussit, la promesse retournée sera résolue avec un <ArrayBuffer> contenant le résultat en texte clair.

Les algorithmes actuellement pris en charge incluent :

'RSA-OAEP'
'AES-CTR'
'AES-CBC'
'AES-GCM'

`subtle.deriveBits(algorithm, baseKey[, length])`

[Historique]

Version	Modifications
v22.5.0, v20.17.0	Le paramètre length est désormais optionnel pour `'ECDH'`, `'X25519'` et `'X448'`.
v18.4.0, v16.17.0	Ajout des algorithmes `'X25519'` et `'X448'`.
v15.0.0	Ajouté dans : v15.0.0

algorithm: <AlgorithmIdentifier> | <EcdhKeyDeriveParams> | <HkdfParams> | <Pbkdf2Params>
baseKey: <CryptoKey>
length: <number> | <null> Par défaut : null
Renvoie : <Promise> Résout avec un <ArrayBuffer>

En utilisant la méthode et les paramètres spécifiés dans algorithm et le matériel de clé fourni par baseKey, subtle.deriveBits() tente de générer length bits.

Lorsque length n'est pas fourni ou est null, le nombre maximal de bits pour un algorithme donné est généré. Ceci est autorisé pour les algorithmes 'ECDH', 'X25519' et 'X448', pour les autres algorithmes, length doit être un nombre.

En cas de succès, la promesse renvoyée sera résolue avec un <ArrayBuffer> contenant les données générées.

Les algorithmes actuellement pris en charge sont les suivants :

'ECDH'
'X25519'
'X448'
'HKDF'
'PBKDF2'

`subtle.deriveKey(algorithm, baseKey, derivedKeyAlgorithm, extractable, keyUsages)`

[Historique]

Version	Modifications
v18.4.0, v16.17.0	Ajout des algorithmes `'X25519'` et `'X448'`.
v15.0.0	Ajouté dans : v15.0.0

algorithm: <AlgorithmIdentifier> | <EcdhKeyDeriveParams> | <HkdfParams> | <Pbkdf2Params>
baseKey: <CryptoKey>
derivedKeyAlgorithm: <HmacKeyGenParams> | <AesKeyGenParams>
extractable: <boolean>
keyUsages: <string[]> Voir Utilisations de clés.
Renvoie : <Promise> Résout avec une <CryptoKey>

En utilisant la méthode et les paramètres spécifiés dans algorithm, et le matériel de clé fourni par baseKey, subtle.deriveKey() tente de générer une nouvelle <CryptoKey> basée sur la méthode et les paramètres dans derivedKeyAlgorithm.

Appeler subtle.deriveKey() équivaut à appeler subtle.deriveBits() pour générer du matériel de clé brut, puis à passer le résultat dans la méthode subtle.importKey() en utilisant les paramètres deriveKeyAlgorithm, extractable et keyUsages comme entrée.

Les algorithmes actuellement pris en charge sont les suivants :

'ECDH'
'X25519'
'X448'
'HKDF'
'PBKDF2'

`subtle.digest(algorithm, data)`

Ajouté dans : v15.0.0

algorithm : <string> | <Object>
data : <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
Retourne : <Promise> Se réalise avec un <ArrayBuffer>

En utilisant la méthode identifiée par algorithm, subtle.digest() tente de générer un condensé de data. Si elle réussit, la promesse renvoyée est résolue avec un <ArrayBuffer> contenant le condensé calculé.

Si algorithm est fourni en tant que <string>, il doit s'agir de l'un des éléments suivants :

'SHA-1'
'SHA-256'
'SHA-384'
'SHA-512'

Si algorithm est fourni en tant que <Object>, il doit avoir une propriété name dont la valeur est l'une de celles ci-dessus.

`subtle.encrypt(algorithm, key, data)`

Ajouté dans : v15.0.0

algorithm : <RsaOaepParams> | <AesCtrParams> | <AesCbcParams> | <AesGcmParams>
key : <CryptoKey>
data : <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
Retourne : <Promise> Se réalise avec un <ArrayBuffer>

En utilisant la méthode et les paramètres spécifiés par algorithm et le matériel de clé fourni par key, subtle.encrypt() tente de chiffrer data. Si elle réussit, la promesse renvoyée est résolue avec un <ArrayBuffer> contenant le résultat chiffré.

Les algorithmes actuellement pris en charge incluent :

'RSA-OAEP'
'AES-CTR'
'AES-CBC'
'AES-GCM'

`subtle.exportKey(format, key)`

[Historique]

Version	Modifications
v18.4.0, v16.17.0	Ajout des algorithmes `'Ed25519'`, `'Ed448'`, `'X25519'` et `'X448'`.
v15.9.0	Suppression de l'exportation JWK `'NODE-DSA'`.
v15.0.0	Ajouté dans : v15.0.0

format: <string> Doit être l'un des suivants : 'raw', 'pkcs8', 'spki' ou 'jwk'.
key: <CryptoKey>
Renvoie : <Promise> Réussit avec un <ArrayBuffer> | <Object>.

Exporte la clé donnée dans le format spécifié, si pris en charge.

Si la <CryptoKey> n'est pas extractible, la promesse renvoyée sera rejetée.

Lorsque format est soit 'pkcs8' soit 'spki' et que l'exportation réussit, la promesse renvoyée sera résolue avec un <ArrayBuffer> contenant les données de la clé exportée.

Lorsque format est 'jwk' et que l'exportation réussit, la promesse renvoyée sera résolue avec un objet JavaScript conforme à la spécification JSON Web Key.

Type de clé	`'spki'`	`'pkcs8'`	`'jwk'`	`'raw'`
`'AES-CBC'`			✔	✔
`'AES-CTR'`			✔	✔
`'AES-GCM'`			✔	✔
`'AES-KW'`			✔	✔
`'ECDH'`	✔	✔	✔	✔
`'ECDSA'`	✔	✔	✔	✔
`'Ed25519'`	✔	✔	✔	✔
`'Ed448'`	✔	✔	✔	✔
`'HDKF'`
`'HMAC'`			✔	✔
`'PBKDF2'`
`'RSA-OAEP'`	✔	✔	✔
`'RSA-PSS'`	✔	✔	✔
`'RSASSA-PKCS1-v1_5'`	✔	✔	✔

`subtle.generateKey(algorithm, extractable, keyUsages)`

Ajouté dans : v15.0.0

algorithm: <AlgorithmIdentifier> | <RsaHashedKeyGenParams> | <EcKeyGenParams> | <HmacKeyGenParams> | <AesKeyGenParams>
extractable: <boolean>
keyUsages: <string[]> Voir Utilisations de la clé.
Renvoie : <Promise> Réussit avec une <CryptoKey> | <CryptoKeyPair>

En utilisant la méthode et les paramètres fournis dans algorithm, subtle.generateKey() tente de générer un nouveau matériel de clés. Selon la méthode utilisée, la méthode peut générer soit une seule <CryptoKey> soit une <CryptoKeyPair>.

Les algorithmes de génération <CryptoKeyPair> (clé publique et privée) pris en charge incluent :

'RSASSA-PKCS1-v1_5'
'RSA-PSS'
'RSA-OAEP'
'ECDSA'
'Ed25519'
'Ed448'
'ECDH'
'X25519'
'X448'

Les algorithmes de génération <CryptoKey> (clé secrète) pris en charge incluent :

'HMAC'
'AES-CTR'
'AES-CBC'
'AES-GCM'
'AES-KW'

`subtle.importKey(format, keyData, algorithm, extractable, keyUsages)`

[Historique]

Version	Modifications
v18.4.0, v16.17.0	Ajout des algorithmes `'Ed25519'`, `'Ed448'`, `'X25519'` et `'X448'`.
v15.9.0	Suppression de l'importation JWK `'NODE-DSA'`.
v15.0.0	Ajouté dans : v15.0.0

format : <string> Doit être l'un des éléments suivants : 'raw', 'pkcs8', 'spki' ou 'jwk'.
keyData : <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer> | <Object>
algorithm : <AlgorithmIdentifier> | <RsaHashedImportParams> | <EcKeyImportParams> | <HmacImportParams>
extractable : <boolean>
keyUsages : <string[]> Voir Utilisations de la clé.
Retourne : <Promise> Se réalise avec un <CryptoKey>

La méthode subtle.importKey() tente d'interpréter les keyData fournis au format donné pour créer une instance <CryptoKey> en utilisant les arguments algorithm, extractable et keyUsages fournis. Si l'importation réussit, la promesse retournée sera résolue avec le <CryptoKey> créé.

Si vous importez une clé 'PBKDF2', extractable doit être false.

Les algorithmes actuellement pris en charge sont les suivants :

Type de clé	`'spki'`	`'pkcs8'`	`'jwk'`	`'raw'`
`'AES-CBC'`			✔	✔
`'AES-CTR'`			✔	✔
`'AES-GCM'`			✔	✔
`'AES-KW'`			✔	✔
`'ECDH'`	✔	✔	✔	✔
`'X25519'`	✔	✔	✔	✔
`'X448'`	✔	✔	✔	✔
`'ECDSA'`	✔	✔	✔	✔
`'Ed25519'`	✔	✔	✔	✔
`'Ed448'`	✔	✔	✔	✔
`'HDKF'`				✔
`'HMAC'`			✔	✔
`'PBKDF2'`				✔
`'RSA-OAEP'`	✔	✔	✔
`'RSA-PSS'`	✔	✔	✔
`'RSASSA-PKCS1-v1_5'`	✔	✔	✔

`subtle.sign(algorithm, key, data)`

[Historique]

Version	Modifications
v18.4.0, v16.17.0	Ajout des algorithmes `'Ed25519'` et `'Ed448'`.
v15.0.0	Ajouté dans : v15.0.0

algorithm : <AlgorithmIdentifier> | <RsaPssParams> | <EcdsaParams> | <Ed448Params>
key : <CryptoKey>
data : <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
Retourne : <Promise> Réussit avec un <ArrayBuffer>

En utilisant la méthode et les paramètres donnés par algorithm et le matériel de clé fourni par key, subtle.sign() tente de générer une signature cryptographique de data. En cas de succès, la promesse retournée est résolue avec un <ArrayBuffer> contenant la signature générée.

Les algorithmes actuellement pris en charge incluent :

'RSASSA-PKCS1-v1_5'
'RSA-PSS'
'ECDSA'
'Ed25519'
'Ed448'
'HMAC'

`subtle.unwrapKey(format, wrappedKey, unwrappingKey, unwrapAlgo, unwrappedKeyAlgo, extractable, keyUsages)`

Ajouté dans : v15.0.0

format : <string> Doit être l’un des éléments suivants : 'raw', 'pkcs8', 'spki' ou 'jwk'.
wrappedKey : <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
unwrappingKey : <CryptoKey>
unwrapAlgo : <AlgorithmIdentifier> | <RsaOaepParams> | <AesCtrParams> | <AesCbcParams> | <AesGcmParams>
unwrappedKeyAlgo : <AlgorithmIdentifier> | <RsaHashedImportParams> | <EcKeyImportParams> | <HmacImportParams>
extractable : <boolean>
keyUsages : <string[]> Voir Utilisations de la clé.
Retourne : <Promise> Réussit avec une <CryptoKey>

En cryptographie, « encapsuler une clé » fait référence à l’exportation puis au cryptage du matériel de clé. La méthode subtle.unwrapKey() tente de décrypter une clé encapsulée et de créer une instance de <CryptoKey>. Cela équivaut à appeler d’abord subtle.decrypt() sur les données de clé cryptées (en utilisant les arguments wrappedKey, unwrapAlgo et unwrappingKey en entrée), puis à transmettre les résultats à la méthode subtle.importKey() en utilisant les arguments unwrappedKeyAlgo, extractable et keyUsages en entrée. En cas de succès, la promesse retournée est résolue avec un objet <CryptoKey>.

Les algorithmes d’encapsulation actuellement pris en charge incluent :

'RSA-OAEP'
'AES-CTR'
'AES-CBC'
'AES-GCM'
'AES-KW'

Les algorithmes de clé déballée pris en charge incluent :

'RSASSA-PKCS1-v1_5'
'RSA-PSS'
'RSA-OAEP'
'ECDSA'
'Ed25519'
'Ed448'
'ECDH'
'X25519'
'X448'
'HMAC'
'AES-CTR'
'AES-CBC'
'AES-GCM'
'AES-KW'

`subtle.verify(algorithm, key, signature, data)`

[Historique]

Version	Modifications
v18.4.0, v16.17.0	Ajout des algorithmes `'Ed25519'` et `'Ed448'`.
v15.0.0	Ajouté dans : v15.0.0

algorithm : <AlgorithmIdentifier> | <RsaPssParams> | <EcdsaParams> | <Ed448Params>
key : <CryptoKey>
signature : <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
data : <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
Retourne : <Promise> Réussit avec un <boolean>

En utilisant la méthode et les paramètres donnés dans algorithm et le matériel de clé fourni par key, subtle.verify() tente de vérifier que signature est une signature cryptographique valide de data. La promesse retournée est résolue avec true ou false.

Les algorithmes actuellement pris en charge incluent :

'RSASSA-PKCS1-v1_5'
'RSA-PSS'
'ECDSA'
'Ed25519'
'Ed448'
'HMAC'

`subtle.wrapKey(format, key, wrappingKey, wrapAlgo)`

Ajouté dans : v15.0.0

format : <string> Doit être l'un des éléments suivants : 'raw', 'pkcs8', 'spki' ou 'jwk'.
key : <CryptoKey>
wrappingKey : <CryptoKey>
wrapAlgo : <AlgorithmIdentifier> | <RsaOaepParams> | <AesCtrParams> | <AesCbcParams> | <AesGcmParams>
Retourne : <Promise> Réussit avec un <ArrayBuffer>

En cryptographie, « encapsuler une clé » signifie exporter, puis chiffrer le matériel de clé. La méthode subtle.wrapKey() exporte le matériel de clé dans le format identifié par format, puis le chiffre en utilisant la méthode et les paramètres spécifiés par wrapAlgo et le matériel de clé fourni par wrappingKey. Cela équivaut à appeler subtle.exportKey() en utilisant format et key comme arguments, puis à passer le résultat à la méthode subtle.encrypt() en utilisant wrappingKey et wrapAlgo comme entrées. En cas de succès, la promesse retournée sera résolue avec un <ArrayBuffer> contenant les données de clé chiffrées.

Les algorithmes d'encapsulation actuellement pris en charge incluent :

'RSA-OAEP'
'AES-CTR'
'AES-CBC'
'AES-GCM'
'AES-KW'

Paramètres d'algorithme

Les objets de paramètres d'algorithme définissent les méthodes et les paramètres utilisés par les différentes méthodes de <SubtleCrypto>. Bien que décrits ici comme des "classes", ce sont de simples objets de dictionnaire JavaScript.

Classe : `AlgorithmIdentifier`

Ajouté dans : v18.4.0, v16.17.0

`algorithmIdentifier.name`

Ajouté dans : v18.4.0, v16.17.0

Type : <string>

Classe : `AesCbcParams`

Ajouté dans : v15.0.0

`aesCbcParams.iv`

Ajouté dans : v15.0.0

Type : <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

Fournit le vecteur d'initialisation. Il doit avoir exactement 16 octets de long et doit être imprévisible et cryptographiquement aléatoire.

`aesCbcParams.name`

Ajouté dans : v15.0.0

Type : <string> Doit être 'AES-CBC'.

Classe : `AesCtrParams`

Ajouté dans : v15.0.0

`aesCtrParams.counter`

Ajouté dans : v15.0.0

Type : <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

La valeur initiale du bloc compteur. Il doit avoir exactement 16 octets de long.

La méthode AES-CTR utilise les bits les plus à droite length du bloc comme compteur et les bits restants comme nonce.

`aesCtrParams.length`

Ajouté dans : v15.0.0

Type : <number> Le nombre de bits dans le aesCtrParams.counter qui doivent être utilisés comme compteur.

`aesCtrParams.name`

Ajouté dans : v15.0.0

Type : <string> Doit être 'AES-CTR'.

Classe : `AesGcmParams`

Ajouté dans : v15.0.0

`aesGcmParams.additionalData`

Ajouté dans : v15.0.0

Type : <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer> | <undefined>

Avec la méthode AES-GCM, additionalData est une entrée supplémentaire qui n'est pas chiffrée mais qui est incluse dans l'authentification des données. L'utilisation de additionalData est facultative.

`aesGcmParams.iv`

Ajouté dans : v15.0.0

Type : <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

Le vecteur d'initialisation doit être unique pour chaque opération de chiffrement utilisant une clé donnée.

Idéalement, il s'agit d'une valeur déterministe de 12 octets qui est calculée de manière à garantir son caractère unique dans toutes les invocations qui utilisent la même clé. Alternativement, le vecteur d'initialisation peut être constitué d'au moins 12 octets cryptographiquement aléatoires. Pour plus d'informations sur la construction de vecteurs d'initialisation pour AES-GCM, reportez-vous à la section 8 de NIST SP 800-38D.

`aesGcmParams.name`

Ajouté dans : v15.0.0

Type : <string> Doit être 'AES-GCM'.

`aesGcmParams.tagLength`

Ajouté dans: v15.0.0

Type: <number> La taille en bits de la balise d'authentification générée. Ces valeurs doivent être l'une des suivantes : 32, 64, 96, 104, 112, 120 ou 128. Par défaut: 128.

Classe: `AesKeyGenParams`

Ajouté dans: v15.0.0

`aesKeyGenParams.length`

Ajouté dans: v15.0.0

Type: <number>

La longueur de la clé AES à générer. Celle-ci doit être 128, 192 ou 256.

`aesKeyGenParams.name`

Ajouté dans: v15.0.0

Type: <string> Doit être l'une des valeurs suivantes : 'AES-CBC', 'AES-CTR', 'AES-GCM' ou 'AES-KW'

Classe: `EcdhKeyDeriveParams`

Ajouté dans: v15.0.0

`ecdhKeyDeriveParams.name`

Ajouté dans: v15.0.0

Type: <string> Doit être 'ECDH', 'X25519' ou 'X448'.

`ecdhKeyDeriveParams.public`

Ajouté dans: v15.0.0

Type: <CryptoKey>

La dérivation de clé ECDH fonctionne en prenant comme entrée la clé privée d'une partie et la clé publique d'une autre partie -- en utilisant les deux pour générer un secret partagé commun. La propriété ecdhKeyDeriveParams.public est définie sur la clé publique de l'autre partie.

Classe: `EcdsaParams`

Ajouté dans: v15.0.0

`ecdsaParams.hash`

Ajouté dans: v15.0.0

Type: <string> | <Object>

Si elle est représentée sous forme de <string>, la valeur doit être l'une des suivantes :

'SHA-1'
'SHA-256'
'SHA-384'
'SHA-512'

Si elle est représentée sous forme de <Object>, l'objet doit avoir une propriété name dont la valeur est l'une des valeurs énumérées ci-dessus.

`ecdsaParams.name`

Ajouté dans : v15.0.0

Type : <string> Doit être 'ECDSA'.

Class: `EcKeyGenParams`

Ajouté dans : v15.0.0

`ecKeyGenParams.name`

Ajouté dans : v15.0.0

Type : <string> Doit être 'ECDSA' ou 'ECDH'.

`ecKeyGenParams.namedCurve`

Ajouté dans : v15.0.0

Type : <string> Doit être 'P-256', 'P-384', 'P-521'.

Class: `EcKeyImportParams`

Ajouté dans : v15.0.0

`ecKeyImportParams.name`

Ajouté dans : v15.0.0

Type : <string> Doit être 'ECDSA' ou 'ECDH'.

`ecKeyImportParams.namedCurve`

Ajouté dans : v15.0.0

Type : <string> Doit être 'P-256', 'P-384', 'P-521'.

Class: `Ed448Params`

Ajouté dans : v15.0.0

`ed448Params.name`

Ajouté dans : v18.4.0, v16.17.0

Type : <string> Doit être 'Ed448'.

`ed448Params.context`

Ajouté dans : v18.4.0, v16.17.0

Type : <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer> | <undefined>

Le membre context représente les données de contexte optionnelles à associer au message. L'implémentation de l'API Web Crypto de Node.js ne prend en charge que le contexte de longueur nulle, ce qui équivaut à ne pas fournir de contexte du tout.

Classe : `HkdfParams`

Ajoutée dans : v15.0.0

`hkdfParams.hash`

Ajoutée dans : v15.0.0

Type : <string> | <Object>

Si elle est représentée sous forme de <string>, la valeur doit être l’une des suivantes :

'SHA-1'
'SHA-256'
'SHA-384'
'SHA-512'

Si elle est représentée sous forme de <Object>, l’objet doit avoir une propriété name dont la valeur est l’une des valeurs répertoriées ci-dessus.

`hkdfParams.info`

Ajoutée dans : v15.0.0

Type : <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

Fournit une entrée contextuelle spécifique à l’application à l’algorithme HKDF. Elle peut être de longueur nulle, mais doit être fournie.

`hkdfParams.name`

Ajoutée dans : v15.0.0

Type : <string> Doit être 'HKDF'.

`hkdfParams.salt`

Ajoutée dans : v15.0.0

Type : <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

La valeur de sel améliore considérablement la force de l’algorithme HKDF. Elle doit être aléatoire ou pseudo-aléatoire et doit avoir la même longueur que la sortie de la fonction de hachage (par exemple, si vous utilisez 'SHA-256' comme hachage, le sel doit être constitué de 256 bits de données aléatoires).

Classe : `HmacImportParams`

Ajoutée dans : v15.0.0

`hmacImportParams.hash`

Ajoutée dans : v15.0.0

Type : <string> | <Object>

Si elle est représentée sous forme de <string>, la valeur doit être l’une des suivantes :

'SHA-1'
'SHA-256'
'SHA-384'
'SHA-512'

Si elle est représentée sous forme de <Object>, l’objet doit avoir une propriété name dont la valeur est l’une des valeurs listées ci-dessus.

`hmacImportParams.length`

Ajoutée dans : v15.0.0

Type : <number>

Le nombre optionnel de bits dans la clé HMAC. Ceci est optionnel et doit être omis dans la plupart des cas.

`hmacImportParams.name`

Ajoutée dans : v15.0.0

Type : <string> Doit être 'HMAC'.

Classe : `HmacKeyGenParams`

Ajoutée dans : v15.0.0

`hmacKeyGenParams.hash`

Ajoutée dans : v15.0.0

Type : <string> | <Object>

Si elle est représentée sous forme de <string>, la valeur doit être l’une des suivantes :

'SHA-1'
'SHA-256'
'SHA-384'
'SHA-512'

Si elle est représentée sous forme de <Object>, l’objet doit avoir une propriété name dont la valeur est l’une des valeurs listées ci-dessus.

`hmacKeyGenParams.length`

Ajoutée dans : v15.0.0

Type : <number>

Le nombre de bits à générer pour la clé HMAC. Si elle est omise, la longueur sera déterminée par l’algorithme de hachage utilisé. Ceci est optionnel et doit être omis dans la plupart des cas.

`hmacKeyGenParams.name`

Ajouté dans : v15.0.0

Type : <string> Doit être 'HMAC'.

Classe : `Pbkdf2Params`

Ajouté dans : v15.0.0

`pbkdb2Params.hash`

Ajouté dans : v15.0.0

Type : <string> | <Object>

S'il est représenté sous forme de <string>, la valeur doit être l'une des suivantes :

'SHA-1'
'SHA-256'
'SHA-384'
'SHA-512'

S'il est représenté sous forme de <Object>, l'objet doit avoir une propriété name dont la valeur est l'une des valeurs énumérées ci-dessus.

`pbkdf2Params.iterations`

Ajouté dans : v15.0.0

Type : <number>

Le nombre d'itérations que l'algorithme PBKDF2 doit effectuer lors de la dérivation des bits.

`pbkdf2Params.name`

Ajouté dans : v15.0.0

Type : <string> Doit être 'PBKDF2'.

`pbkdf2Params.salt`

Ajouté dans : v15.0.0

Type : <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

Doit comporter au moins 16 octets aléatoires ou pseudo-aléatoires.

Classe : `RsaHashedImportParams`

Ajouté dans : v15.0.0

`rsaHashedImportParams.hash`

Ajouté dans : v15.0.0

Type : <string> | <Object>

S'il est représenté sous forme de <string>, la valeur doit être l'une des suivantes :

'SHA-1'
'SHA-256'
'SHA-384'
'SHA-512'

S'il est représenté sous forme de <Object>, l'objet doit avoir une propriété name dont la valeur est l'une des valeurs énumérées ci-dessus.

`rsaHashedImportParams.name`

Ajouté dans : v15.0.0

Type : <string> Doit être l’une des valeurs suivantes : 'RSASSA-PKCS1-v1_5', 'RSA-PSS' ou 'RSA-OAEP'.

Classe : `RsaHashedKeyGenParams`

Ajouté dans : v15.0.0

`rsaHashedKeyGenParams.hash`

Ajouté dans : v15.0.0

Type : <string> | <Object>

Si elle est représentée par une <string>, la valeur doit être l’une des suivantes :

'SHA-1'
'SHA-256'
'SHA-384'
'SHA-512'

Si elle est représentée par un <Object>, l’objet doit avoir une propriété name dont la valeur est l’une des valeurs répertoriées ci-dessus.

`rsaHashedKeyGenParams.modulusLength`

Ajouté dans : v15.0.0

Type : <number>

La longueur en bits du module RSA. En bonne pratique, elle doit être d’au moins 2048.

`rsaHashedKeyGenParams.name`

Ajouté dans : v15.0.0

Type : <string> Doit être l’une des valeurs suivantes : 'RSASSA-PKCS1-v1_5', 'RSA-PSS' ou 'RSA-OAEP'.

`rsaHashedKeyGenParams.publicExponent`

Ajouté dans : v15.0.0

Type : <Uint8Array>

L’exposant public RSA. Il doit s’agir d’un <Uint8Array> contenant un entier non signé big-endian qui doit tenir dans 32 bits. Le <Uint8Array> peut contenir un nombre arbitraire de bits zéro de début. La valeur doit être un nombre premier. Sauf s’il y a une raison d’utiliser une valeur différente, utilisez new Uint8Array([1, 0, 1]) (65537) comme exposant public.

Classe : `RsaOaepParams`

Ajouté dans : v15.0.0

`rsaOaepParams.label`

Ajouté dans : v15.0.0

Type : <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

Une collection supplémentaire d’octets qui ne sera pas chiffrée, mais qui sera liée au texte chiffré généré.

Le paramètre rsaOaepParams.label est facultatif.

`rsaOaepParams.name`

Ajouté dans : v15.0.0

Type : <string> doit être 'RSA-OAEP'.

Classe : `RsaPssParams`

Ajouté dans : v15.0.0

`rsaPssParams.name`

Ajouté dans : v15.0.0

Type : <string> Doit être 'RSA-PSS'.

`rsaPssParams.saltLength`

Ajouté dans : v15.0.0

Type : <number>

La longueur (en octets) du sel aléatoire à utiliser.

API Web Crypto ​

Exemples ​

Génération de clés ​

Clés AES ​

Paires de clés ECDSA ​

Paires de clés Ed25519/X25519 ​

Clés HMAC ​

Paires de clés RSA ​

Chiffrement et déchiffrement ​

Exportation et importation de clés ​

Encapsulation et désencapsulation de clés ​

Signature et vérification ​

Dérivation de bits et de clés ​

Digest ​

Matrice des algorithmes ​

Classe : Crypto ​

crypto.subtle ​

crypto.getRandomValues(typedArray) ​

crypto.randomUUID() ​

Class : CryptoKey ​

cryptoKey.algorithm ​

cryptoKey.extractable ​

cryptoKey.type ​

cryptoKey.usages ​

Class: CryptoKeyPair ​

cryptoKeyPair.privateKey ​

cryptoKeyPair.publicKey ​

Class: SubtleCrypto ​

subtle.decrypt(algorithm, key, data) ​

subtle.deriveBits(algorithm, baseKey[, length]) ​

subtle.deriveKey(algorithm, baseKey, derivedKeyAlgorithm, extractable, keyUsages) ​

subtle.digest(algorithm, data) ​

subtle.encrypt(algorithm, key, data) ​

subtle.exportKey(format, key) ​

subtle.generateKey(algorithm, extractable, keyUsages) ​

subtle.importKey(format, keyData, algorithm, extractable, keyUsages) ​

subtle.sign(algorithm, key, data) ​

subtle.unwrapKey(format, wrappedKey, unwrappingKey, unwrapAlgo, unwrappedKeyAlgo, extractable, keyUsages) ​

subtle.verify(algorithm, key, signature, data) ​

subtle.wrapKey(format, key, wrappingKey, wrapAlgo) ​

Paramètres d'algorithme ​

Classe : AlgorithmIdentifier ​

algorithmIdentifier.name ​

Classe : AesCbcParams ​

aesCbcParams.iv ​

aesCbcParams.name ​

Classe : AesCtrParams ​

aesCtrParams.counter ​

aesCtrParams.length ​

aesCtrParams.name ​

Classe : AesGcmParams ​

aesGcmParams.additionalData ​

aesGcmParams.iv ​

aesGcmParams.name ​

aesGcmParams.tagLength ​

Classe: AesKeyGenParams ​

aesKeyGenParams.length ​

aesKeyGenParams.name ​

Classe: EcdhKeyDeriveParams ​

ecdhKeyDeriveParams.name ​

ecdhKeyDeriveParams.public ​

Classe: EcdsaParams ​

ecdsaParams.hash ​

ecdsaParams.name ​

Class: EcKeyGenParams ​

ecKeyGenParams.name ​

ecKeyGenParams.namedCurve ​

Class: EcKeyImportParams ​

ecKeyImportParams.name ​

ecKeyImportParams.namedCurve ​

Class: Ed448Params ​

ed448Params.name ​

ed448Params.context ​

Classe : HkdfParams ​

hkdfParams.hash ​

hkdfParams.info ​

hkdfParams.name ​

hkdfParams.salt ​

Classe : HmacImportParams ​

hmacImportParams.hash ​

API Web Crypto

Exemples

Génération de clés

Clés AES

Paires de clés ECDSA

Paires de clés Ed25519/X25519

Clés HMAC

Paires de clés RSA

Chiffrement et déchiffrement

Exportation et importation de clés

Encapsulation et désencapsulation de clés

Signature et vérification

Dérivation de bits et de clés

Digest

Matrice des algorithmes

Classe : `Crypto`

`crypto.subtle`

`crypto.getRandomValues(typedArray)`

`crypto.randomUUID()`

Class : `CryptoKey`

`cryptoKey.algorithm`

`cryptoKey.extractable`

`cryptoKey.type`

`cryptoKey.usages`

Class: `CryptoKeyPair`

`cryptoKeyPair.privateKey`

`cryptoKeyPair.publicKey`

Class: `SubtleCrypto`

`subtle.decrypt(algorithm, key, data)`

`subtle.deriveBits(algorithm, baseKey[, length])`

`subtle.deriveKey(algorithm, baseKey, derivedKeyAlgorithm, extractable, keyUsages)`

`subtle.digest(algorithm, data)`

`subtle.encrypt(algorithm, key, data)`

`subtle.exportKey(format, key)`

`subtle.generateKey(algorithm, extractable, keyUsages)`

`subtle.importKey(format, keyData, algorithm, extractable, keyUsages)`

`subtle.sign(algorithm, key, data)`

`subtle.unwrapKey(format, wrappedKey, unwrappingKey, unwrapAlgo, unwrappedKeyAlgo, extractable, keyUsages)`

`subtle.verify(algorithm, key, signature, data)`

`subtle.wrapKey(format, key, wrappingKey, wrapAlgo)`

Paramètres d'algorithme

Classe : `AlgorithmIdentifier`

`algorithmIdentifier.name`

Classe : `AesCbcParams`

`aesCbcParams.iv`

`aesCbcParams.name`

Classe : `AesCtrParams`

`aesCtrParams.counter`

`aesCtrParams.length`

`aesCtrParams.name`

Classe : `AesGcmParams`

`aesGcmParams.additionalData`

`aesGcmParams.iv`

`aesGcmParams.name`

`aesGcmParams.tagLength`

Classe: `AesKeyGenParams`

`aesKeyGenParams.length`

`aesKeyGenParams.name`

Classe: `EcdhKeyDeriveParams`

`ecdhKeyDeriveParams.name`

`ecdhKeyDeriveParams.public`

Classe: `EcdsaParams`

`ecdsaParams.hash`

`ecdsaParams.name`

Class: `EcKeyGenParams`

`ecKeyGenParams.name`

`ecKeyGenParams.namedCurve`

Class: `EcKeyImportParams`

`ecKeyImportParams.name`

`ecKeyImportParams.namedCurve`

Class: `Ed448Params`

`ed448Params.name`

`ed448Params.context`

Classe : `HkdfParams`

`hkdfParams.hash`

`hkdfParams.info`

`hkdfParams.name`

`hkdfParams.salt`

Classe : `HmacImportParams`

`hmacImportParams.hash`