Web Crypto API

[Historique]

Version	Modifications
v23.5.0	Les algorithmes `Ed25519` et `X25519` sont maintenant stables.
v19.0.0	Plus expérimental, sauf pour les algorithmes `Ed25519`, `Ed448`, `X25519`, et `X448`.
v20.0.0, v18.17.0	Les arguments sont maintenant forcés et validés selon leurs définitions WebIDL, comme dans d'autres implémentations de l'API Web Crypto.
v18.4.0, v16.17.0	Format d'importation/exportation propriétaire `'node.keyObject'` supprimé.
v18.4.0, v16.17.0	Algorithmes propriétaires `'NODE-DSA'`, `'NODE-DH'`, et `'NODE-SCRYPT'` supprimés.
v18.4.0, v16.17.0	Algorithmes `'Ed25519'`, `'Ed448'`, `'X25519'`, et `'X448'` ajoutés.
v18.4.0, v16.17.0	Algorithmes propriétaires `'NODE-ED25519'` et `'NODE-ED448'` supprimés.
v18.4.0, v16.17.0	Courbes nommées propriétaires `'NODE-X25519'` et `'NODE-X448'` supprimées de l'algorithme `'ECDH'`.

[Stable : 2 - Stable]

Stable : 2 Stabilité : 2 - Stable

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

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 (secretes) 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
}

Enveloppement et déballage des 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étail les algorithmes supportés par l'implémentation de l'API Web Crypto de Node.js et les API supportées 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 l'accès au reste de l'API crypto.

`crypto.subtle`

Ajouté dans : v15.0.0

Type : <SubtleCrypto>

Fournit l'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 robustes. 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

Retourne : <string>

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

Classe : `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 subtleCrypto.wrapKey().

Lecture seule.

`cryptoKey.type`

Ajouté dans : v15.0.0

Type : <string> L'un de '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 les données.
'decrypt' - La clé peut être utilisée pour déchiffrer les 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écapsuler une autre clé.

Les utilisations de clés valides 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'`			✔	✔

Classe : `CryptoKeyPair`

Ajouté dans : v15.0.0

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

`cryptoKeyPair.privateKey`

Ajouté dans : v15.0.0

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

`cryptoKeyPair.publicKey`

Ajouté dans : v15.0.0

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

Classe : `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> Restitue un <ArrayBuffer>

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

Les algorithmes actuellement supportés 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 maintenant optionnel pour `'ECDH'`, `'X25519'`, et `'X448'`.
v18.4.0, v16.17.0	Ajout des algorithmes `'X25519'` et `'X448'`.
v15.0.0	Ajouté dans la version : v15.0.0

algorithm: <AlgorithmIdentifier> | <EcdhKeyDeriveParams> | <HkdfParams> | <Pbkdf2Params>
baseKey: <CryptoKey>
length: <number> | <null> Défaut : null
Retourne : <Promise> Restitue un <ArrayBuffer>

En utilisant la méthode et les paramètres spécifiés dans algorithm et le matériel de chiffrement 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 retournée sera résolue avec un <ArrayBuffer> contenant les données générées.

Les algorithmes actuellement pris en charge incluent :

'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 la version : v15.0.0

algorithm: <AlgorithmIdentifier> | <EcdhKeyDeriveParams> | <HkdfParams> | <Pbkdf2Params>
baseKey: <CryptoKey>
derivedKeyAlgorithm: <HmacKeyGenParams> | <AesKeyGenParams>
extractable: <boolean>
keyUsages: <string[]> Voir Utilisations des clés.
Retourne : <Promise> Restitue un <CryptoKey>

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

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

Les algorithmes actuellement pris en charge incluent :

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

`subtle.digest(algorithm, data)`

Ajouté dans : v15.0.0

algorithm: <string> | <Object>
data: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
Retourne : <Promise> Résolue avec un <ArrayBuffer>

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

Si algorithm est fourni sous forme de <string>, il doit être l'un des suivants :

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

Si algorithm est fourni sous forme d'un <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> Résolue avec un <ArrayBuffer>

En utilisant la méthode et les paramètres spécifiés par algorithm et le matériel de chiffrement fourni par key, subtle.encrypt() tente de chiffrer data. Si cela réussit, la promesse retourné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 éléments suivants : 'raw', 'pkcs8', 'spki' ou 'jwk'.
key: <CryptoKey>
Retourne : <Promise> Restitue un <ArrayBuffer> | <Object>.

Exporte la clé donnée au format spécifié, si celui-ci est pris en charge.

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

Lorsque format est 'pkcs8' ou 'spki' et que l'exportation réussit, la promesse retourné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 retourné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 des clés.
Retourne : <Promise> Restitue un <CryptoKey> | <CryptoKeyPair>

À l'aide de la méthode et des paramètres fournis dans algorithm, subtle.generateKey() tente de générer un nouveau matériel de chiffrement. Selon la méthode utilisée, la méthode peut générer une seule clé <CryptoKey> ou une paire de clés <CryptoKeyPair>.

Les algorithmes de génération de <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 de <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 la version : v15.0.0

format: <string> Doit être l'une des valeurs suivantes : 'raw', 'pkcs8', 'spki' ou 'jwk'.
keyData: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer> | <Object>
algorithm: <AlgorithmIdentifier> | <RsaHashedImportParams> | <EcKeyImportParams> | <HmacImportParams>
extractable: <boolean>
keyUsages: <string[]> Voir Utilisations des clés.
Retourne : <Promise> Restitue une <CryptoKey>

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

Lors de l'importation d'une clé 'PBKDF2', extractable doit être false.

Les algorithmes actuellement pris en charge incluent :

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 la version : v15.0.0

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

En utilisant la méthode et les paramètres donnés par algorithm et le matériel de chiffrement 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 la version : 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 des clés.
Retourne : <Promise> Resolue avec un <CryptoKey>

En cryptographie, « encapsuler une clé » consiste à exporter puis à chiffrer le matériel de chiffrement. La méthode subtle.unwrapKey() tente de déchiffrer une clé encapsulée et de créer une instance <CryptoKey>. Elle équivaut à appeler d'abord subtle.decrypt() sur les données de clé chiffrées (en utilisant les arguments wrappedKey, unwrapAlgo et unwrappingKey comme entrée), puis à transmettre les résultats à la méthode subtle.importKey() en utilisant les arguments unwrappedKeyAlgo, extractable et keyUsages comme entrées. 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écapsulé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 la version : v15.0.0

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

En utilisant la méthode et les paramètres donnés dans algorithm et le matériel de chiffrement 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 supportés incluent :

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

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

Ajouté dans la version : v15.0.0

format: <string> Doit être l'un de 'raw', 'pkcs8', 'spki', ou 'jwk'.
key: <CryptoKey>
wrappingKey: <CryptoKey>
wrapAlgo: <AlgorithmIdentifier> | <RsaOaepParams> | <AesCtrParams> | <AesCbcParams> | <AesGcmParams>
Retourne : <Promise> Restitue un <ArrayBuffer>

En cryptographie, « emballer une clé » signifie exporter puis chiffrer le matériel de chiffrement. La méthode subtle.wrapKey() exporte le matériel de chiffrement 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 chiffrement fourni par wrappingKey. C'est l'équivalent d'appeler subtle.exportKey() en utilisant format et key comme arguments, puis en passant 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'emballage actuellement supportés incluent :

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

Paramètres de l'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 <SubtleCrypto>. Bien que décrits ici comme des "classes", ce sont de simples objets dictionnaires 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 faire 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 de compteur. Elle doit faire exactement 16 octets de long.

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

`aesCtrParams.length`

Ajouté dans : v15.0.0

Type : <number> Le nombre de bits dans 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, les additionalData sont des données supplémentaires qui ne sont pas chiffrées mais qui sont incluses 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 calculée de manière à être garantie unique pour toutes les invocations utilisant la même clé. Alternativement, le vecteur d’initialisation peut consister en au moins 12 octets cryptographiquement aléatoires. Pour plus d’informations sur la construction de vecteurs d’initialisation pour AES-GCM, consultez 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. Cette valeur doit être l’une des valeurs suivantes : 32, 64, 96, 104, 112, 120 ou 128. Valeur 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. Cette valeur 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>

Le 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 représenté comme une <string>, la valeur doit être l’une des suivantes :

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

Si représenté comme un <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'.

Classe : `EcKeyGenParams`

Ajouté dans : v15.0.0

`ecKeyGenParams.name`

Ajouté dans : v15.0.0

Type : <string> Doit être l'un des éléments suivants : 'ECDSA' ou 'ECDH'.

`ecKeyGenParams.namedCurve`

Ajouté dans : v15.0.0

Type : <string> Doit être l'un des éléments suivants : 'P-256', 'P-384', 'P-521'.

Classe : `EcKeyImportParams`

Ajouté dans : v15.0.0

`ecKeyImportParams.name`

Ajouté dans : v15.0.0

Type : <string> Doit être l'un des éléments suivants : 'ECDSA' ou 'ECDH'.

`ecKeyImportParams.namedCurve`

Ajouté dans : v15.0.0

Type : <string> Doit être l'un des éléments suivants : 'P-256', 'P-384', 'P-521'.

Classe : `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 facultatives à 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 fournir aucun contexte.

Classe : `HkdfParams`

Ajouté dans : v15.0.0

`hkdfParams.hash`

Ajouté dans : v15.0.0

Type : <string> | <Object>

Si représenté comme une <string>, la valeur doit être l'une des suivantes :

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

Si représenté comme un <Object>, l'objet doit avoir une propriété name dont la valeur est l'une des valeurs listées ci-dessus.

`hkdfParams.info`

Ajouté dans : v15.0.0

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

Fournit une entrée contextuelle spécifique à l'application à l'algorithme HKDF. Cela peut être de longueur nulle, mais doit être fourni.

`hkdfParams.name`

Ajouté dans : v15.0.0

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

`hkdfParams.salt`

Ajouté dans : v15.0.0

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

La valeur de sel améliore considérablement la robustesse 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 256 bits de données aléatoires).

Classe : `HmacImportParams`

Ajouté dans : v15.0.0

`hmacImportParams.hash`

Ajouté dans : v15.0.0

Type : <string> | <Object>

Si représenté comme une <string>, la valeur doit être l'une des suivantes :

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

Si représenté comme un <Object>, l'objet doit avoir une propriété name dont la valeur est l'une des valeurs listées ci-dessus.

`hmacImportParams.length`

Ajouté dans : v15.0.0

Type : <number>

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

`hmacImportParams.name`

Ajouté dans : v15.0.0

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

Classe : `HmacKeyGenParams`

Ajouté dans : v15.0.0

`hmacKeyGenParams.hash`

Ajouté dans : v15.0.0

Type : <string> | <Object>

Si représenté comme une <string>, la valeur doit être l'une des suivantes :

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

Si représenté comme un <Object>, l'objet doit avoir une propriété name dont la valeur est l'une des valeurs listées ci-dessus.

`hmacKeyGenParams.length`

Ajouté dans : v15.0.0

Type : <number>

Le nombre de bits à générer pour la clé HMAC. S'il est omis, 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>

Si représenté comme une <string>, la valeur doit être l'une des suivantes :

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

Si représenté comme un <Object>, l'objet doit avoir une propriété name dont la valeur est l'une des valeurs listé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 contenir 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>

Si représenté comme une <string>, la valeur doit être l'une des suivantes :

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

Si représenté comme un <Object>, l'objet doit avoir une propriété name dont la valeur est l'une des valeurs listé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 représenté comme une <string>, la valeur doit être l’une des suivantes :

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

Si représenté comme un <Object>, l’objet doit posséder une propriété name dont la valeur est l’une de celles listées ci-dessus.

`rsaHashedKeyGenParams.modulusLength`

Ajouté dans : v15.0.0

Type : <number>

La longueur en bits du module RSA. Il est recommandé qu’elle soit 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. Ceci doit être un <Uint8Array> contenant un entier non signé en big-endian qui doit tenir dans 32 bits. Le <Uint8Array> peut contenir un nombre arbitraire de bits de premier plan à zéro. La valeur doit être un nombre premier. Sauf raison de choisir une valeur différente, utiliser 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 seront pas chiffrés, mais qui seront liés 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.

Web Crypto API ​

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 ​

Enveloppement et déballage des 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() ​

Classe : CryptoKey ​

cryptoKey.algorithm ​

cryptoKey.extractable ​

cryptoKey.type ​

cryptoKey.usages ​

Classe : CryptoKeyPair ​

cryptoKeyPair.privateKey ​

cryptoKeyPair.publicKey ​

Classe : 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 de l'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 ​

Classe : EcKeyGenParams ​

ecKeyGenParams.name ​

ecKeyGenParams.namedCurve ​

Classe : EcKeyImportParams ​

ecKeyImportParams.name ​

ecKeyImportParams.namedCurve ​

Classe : Ed448Params ​

ed448Params.name ​

ed448Params.context ​

Classe : HkdfParams ​

hkdfParams.hash ​

hkdfParams.info ​

hkdfParams.name ​

hkdfParams.salt ​

Classe : HmacImportParams ​

hmacImportParams.hash ​

Web Crypto API

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

Enveloppement et déballage des 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()`

Classe : `CryptoKey`

`cryptoKey.algorithm`

`cryptoKey.extractable`

`cryptoKey.type`

`cryptoKey.usages`

Classe : `CryptoKeyPair`

`cryptoKeyPair.privateKey`

`cryptoKeyPair.publicKey`

Classe : `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 de l'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`

Classe : `EcKeyGenParams`

`ecKeyGenParams.name`

`ecKeyGenParams.namedCurve`

Classe : `EcKeyImportParams`

`ecKeyImportParams.name`

`ecKeyImportParams.namedCurve`

Classe : `Ed448Params`

`ed448Params.name`

`ed448Params.context`

Classe : `HkdfParams`

`hkdfParams.hash`

`hkdfParams.info`

`hkdfParams.name`

`hkdfParams.salt`

Classe : `HmacImportParams`

`hmacImportParams.hash`