Web Crypto API

[Cronologia]

Versione	Modifiche
v23.5.0	Gli algoritmi `Ed25519` e `X25519` sono ora stabili.
v19.0.0	Non più sperimentale, eccetto per gli algoritmi `Ed25519`, `Ed448`, `X25519` e `X448`.
v20.0.0, v18.17.0	Gli argomenti sono ora forzati e convalidati secondo le loro definizioni WebIDL come nelle altre implementazioni Web Crypto API.
v18.4.0, v16.17.0	Rimosso il formato di importazione/esportazione proprietario `'node.keyObject'`.
v18.4.0, v16.17.0	Rimossi gli algoritmi proprietari `'NODE-DSA'`, `'NODE-DH'` e `'NODE-SCRYPT'`.
v18.4.0, v16.17.0	Aggiunti gli algoritmi `'Ed25519'`, `'Ed448'`, `'X25519'` e `'X448'`.
v18.4.0, v16.17.0	Rimossi gli algoritmi proprietari `'NODE-ED25519'` e `'NODE-ED448'`.
v18.4.0, v16.17.0	Rimosse le curve denominate proprietarie `'NODE-X25519'` e `'NODE-X448'` dall'algoritmo `'ECDH'`.

[Stabile: 2 - Stabile]

Stabile: 2 Stabilità: 2 - Stabile

Node.js fornisce un'implementazione della standard Web Crypto API.

Utilizzare globalThis.crypto o require('node:crypto').webcrypto per accedere a questo modulo.

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

Esempi

Generazione di chiavi

La classe <SubtleCrypto> può essere utilizzata per generare chiavi simmetriche (segrete) o coppie di chiavi asimmetriche (chiave pubblica e chiave privata).

Chiavi AES

const { subtle } = globalThis.crypto

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

  return key
}

Coppie di chiavi 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 }
}

Coppie di chiavi 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']
  )
}

Chiavi HMAC

const { subtle } = globalThis.crypto

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

  return key
}

Coppie di chiavi 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 }
}

Crittografia e decrittografia

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

Esportazione e importazione di chiavi

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
}

Avvolgimento e svolgimento delle chiavi

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
}

Firma e verifica

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
}

Derivazione di bit e chiavi

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
}

Sintesi

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 algoritmi

La tabella dettagliata gli algoritmi supportati dall'implementazione Node.js Web Crypto API e le API supportate per ciascuno:

Algoritmo	`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`

Aggiunto in: v15.0.0

globalThis.crypto è un'istanza della classe Crypto. Crypto è un singleton che fornisce l'accesso al resto dell'API crittografica.

`crypto.subtle`

Aggiunto in: v15.0.0

Tipo: <SubtleCrypto>

Fornisce accesso all'API SubtleCrypto.

`crypto.getRandomValues(typedArray)`

Aggiunto in: v15.0.0

typedArray <Buffer> | <TypedArray>
Restituisce: <Buffer> | <TypedArray>

Genera valori casuali crittograficamente sicuri. Il typedArray fornito viene riempito con valori casuali e viene restituito un riferimento a typedArray.

Il typedArray fornito deve essere un'istanza basata su intero di <TypedArray>, ad esempio Float32Array e Float64Array non sono accettati.

Verà sollevato un errore se il typedArray fornito è maggiore di 65.536 byte.

`crypto.randomUUID()`

Aggiunto in: v16.7.0

Restituisce: <string>

Genera un UUID versione 4 RFC 4122 casuale. L'UUID viene generato usando un generatore di numeri pseudo-casuali crittografici.

Classe: `CryptoKey`

Aggiunto in: v15.0.0

`cryptoKey.algorithm`

Aggiunto in: v15.0.0

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

Un oggetto che descrive l'algoritmo per il quale la chiave può essere utilizzata insieme a parametri aggiuntivi specifici dell'algoritmo.

Sola lettura.

`cryptoKey.extractable`

Aggiunto in: v15.0.0

Tipo: <boolean>

Quando true, il <CryptoKey> può essere estratto usando subtleCrypto.exportKey() o subtleCrypto.wrapKey().

Sola lettura.

`cryptoKey.type`

Aggiunto in: v15.0.0

Tipo: <string> Uno tra 'secret', 'private', o 'public'.

Una stringa che identifica se la chiave è una chiave simmetrica ('secret') o asimmetrica ('private' o 'public').

`cryptoKey.usages`

Aggiunto in: v15.0.0

Tipo: <string[]>

Una matrice di stringhe che identificano le operazioni per le quali la chiave può essere utilizzata.

I possibili usi sono:

'encrypt' - La chiave può essere usata per crittografare i dati.
'decrypt' - La chiave può essere usata per decrittografare i dati.
'sign' - La chiave può essere usata per generare firme digitali.
'verify' - La chiave può essere usata per verificare firme digitali.
'deriveKey' - La chiave può essere usata per derivare una nuova chiave.
'deriveBits' - La chiave può essere usata per derivare bit.
'wrapKey' - La chiave può essere usata per impacchettare un'altra chiave.
'unwrapKey' - La chiave può essere usata per disimpacchettare un'altra chiave.

Gli usi validi delle chiavi dipendono dall'algoritmo della chiave (identificato da cryptokey.algorithm.name).

Tipo di chiave	`'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`

Aggiunto in: v15.0.0

CryptoKeyPair è un semplice oggetto dizionario con le proprietà publicKey e privateKey, che rappresentano una coppia di chiavi asimmetriche.

`cryptoKeyPair.privateKey`

Aggiunto in: v15.0.0

Tipo: <CryptoKey> Un <CryptoKey> il cui type sarà 'private'.

`cryptoKeyPair.publicKey`

Aggiunto in: v15.0.0

Tipo: <CryptoKey> Un <CryptoKey> il cui type sarà 'public'.

Classe: `SubtleCrypto`

Aggiunto in: v15.0.0

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

Aggiunto in: v15.0.0

algorithm: <RsaOaepParams> | <AesCtrParams> | <AesCbcParams> | <AesGcmParams>
key: <CryptoKey>
data: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
Restituisce: <Promise> Risolve con un <ArrayBuffer>

Usando il metodo e i parametri specificati in algorithm e il materiale di chiave fornito da key, subtle.decrypt() tenta di decifrare i data forniti. Se ha successo, la promise restituita verrà risolta con un <ArrayBuffer> contenente il risultato in testo in chiaro.

Gli algoritmi attualmente supportati includono:

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

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

[Cronologia]

Versione	Modifiche
v22.5.0, v20.17.0	Il parametro `length` è ora opzionale per `'ECDH'`, `'X25519'` e `'X448'`.
v18.4.0, v16.17.0	Aggiunti gli algoritmi `'X25519'` e `'X448'`.
v15.0.0	Aggiunto in: v15.0.0

algorithm: <AlgorithmIdentifier> | <EcdhKeyDeriveParams> | <HkdfParams> | <Pbkdf2Params>
baseKey: <CryptoKey>
length: <number> | <null> Predefinito: null
Restituisce: <Promise> Risolve con un <ArrayBuffer>

Usando il metodo e i parametri specificati in algorithm e il materiale chiave fornito da baseKey, subtle.deriveBits() tenta di generare length bit.

Quando length non è fornito o è null, viene generato il numero massimo di bit per un dato algoritmo. Questo è consentito per gli algoritmi 'ECDH', 'X25519' e 'X448'; per altri algoritmi, length deve essere un numero.

Se ha successo, la promise restituita verrà risolta con un <ArrayBuffer> contenente i dati generati.

Gli algoritmi attualmente supportati includono:

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

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

[Cronologia]

Versione	Modifiche
v18.4.0, v16.17.0	Aggiunti gli algoritmi `'X25519'` e `'X448'`.
v15.0.0	Aggiunto in: v15.0.0

algorithm: <AlgorithmIdentifier> | <EcdhKeyDeriveParams> | <HkdfParams> | <Pbkdf2Params>
baseKey: <CryptoKey>
derivedKeyAlgorithm: <HmacKeyGenParams> | <AesKeyGenParams>
extractable: <boolean>
keyUsages: <string[]> Vedi Utilizzi delle chiavi.
Restituisce: <Promise> Risolve con un <CryptoKey>

Usando il metodo e i parametri specificati in algorithm e il materiale chiave fornito da baseKey, subtle.deriveKey() tenta di generare un nuovo <CryptoKey> basato sul metodo e sui parametri in derivedKeyAlgorithm.

Chiamare subtle.deriveKey() è equivalente a chiamare subtle.deriveBits() per generare materiale chiave grezzo, quindi passare il risultato al metodo subtle.importKey() usando i parametri deriveKeyAlgorithm, extractable e keyUsages come input.

Gli algoritmi attualmente supportati includono:

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

`subtle.digest(algorithm, data)`

Aggiunto in: v15.0.0

algorithm: <string> | <Object>
data: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
Restituisce: <Promise> Risolta con un <ArrayBuffer>

Usando il metodo identificato da algorithm, subtle.digest() tenta di generare un digest di data. Se ha successo, la promise restituita viene risolta con un <ArrayBuffer> contenente il digest calcolato.

Se algorithm è fornito come <string>, deve essere uno dei seguenti:

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

Se algorithm è fornito come <Object>, deve avere una proprietà name il cui valore è uno di quelli sopra indicati.

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

Aggiunto in: v15.0.0

algorithm: <RsaOaepParams> | <AesCtrParams> | <AesCbcParams> | <AesGcmParams>
key: <CryptoKey>
data: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
Restituisce: <Promise> Risolta con un <ArrayBuffer>

Usando il metodo e i parametri specificati da algorithm e il materiale di crittografia fornito da key, subtle.encrypt() tenta di cifrare data. Se ha successo, la promise restituita viene risolta con un <ArrayBuffer> contenente il risultato crittografato.

Gli algoritmi attualmente supportati includono:

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

`subtle.exportKey(format, key)`

[Cronologia]

Versione	Modifiche
v18.4.0, v16.17.0	Aggiunti algoritmi `'Ed25519'`, `'Ed448'`, `'X25519'` e `'X448'`.
v15.9.0	Rimossa esportazione JWK `'NODE-DSA'`.
v15.0.0	Aggiunto in: v15.0.0

format: <string> Deve essere uno tra 'raw', 'pkcs8', 'spki' o 'jwk'.
key: <CryptoKey>
Restituisce: <Promise> Risolta con un <ArrayBuffer> | <Object>.

Esporta la chiave fornita nel formato specificato, se supportato.

Se il <CryptoKey> non è estraibile, la promise restituita verrà rifiutata.

Quando format è 'pkcs8' o 'spki' e l'esportazione ha successo, la promise restituita verrà risolta con un <ArrayBuffer> contenente i dati della chiave esportata.

Quando format è 'jwk' e l'esportazione ha successo, la promise restituita verrà risolta con un oggetto JavaScript conforme alla specifica JSON Web Key.

Tipo di chiave	`'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)`

Aggiunto in: v15.0.0

algorithm: <AlgorithmIdentifier> | <RsaHashedKeyGenParams> | <EcKeyGenParams> | <HmacKeyGenParams> | <AesKeyGenParams>
extractable: <boolean>
keyUsages: <string[]> Vedi Utilizzi delle chiavi.
Restituisce: <Promise> Risolta con un <CryptoKey> | <CryptoKeyPair>

Usando il metodo e i parametri forniti in algorithm, subtle.generateKey() tenta di generare nuovo materiale di crittografia. A seconda del metodo utilizzato, il metodo può generare un singolo <CryptoKey> o una <CryptoKeyPair>.

Gli algoritmi di generazione di <CryptoKeyPair> (chiave pubblica e privata) supportati includono:

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

Gli algoritmi di generazione di <CryptoKey> (chiave segreta) supportati includono:

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

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

[Cronologia]

Versione	Modifiche
v18.4.0, v16.17.0	Aggiunti algoritmi `'Ed25519'`, `'Ed448'`, `'X25519'` e `'X448'`.
v15.9.0	Rimossa importazione JWK `'NODE-DSA'`.
v15.0.0	Aggiunto in: v15.0.0

format: <string> Deve essere uno tra 'raw', 'pkcs8', 'spki' o 'jwk'.
keyData: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer> | <Object>
algorithm: <AlgorithmIdentifier> | <RsaHashedImportParams> | <EcKeyImportParams> | <HmacImportParams>
extractable: <boolean>
keyUsages: <string[]> Vedi Utilizzi chiave.
Restituisce: <Promise> Risolve con una <CryptoKey>

Il metodo subtle.importKey() tenta di interpretare keyData fornito come format dato per creare un'istanza <CryptoKey> usando gli argomenti algorithm, extractable e keyUsages forniti. Se l'importazione ha successo, la promise restituita sarà risolta con la <CryptoKey> creata.

Se si importa una chiave 'PBKDF2', extractable deve essere false.

Gli algoritmi attualmente supportati includono:

Tipo chiave	`'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)`

[Cronologia]

Versione	Modifiche
v18.4.0, v16.17.0	Aggiunti algoritmi `'Ed25519'` e `'Ed448'`.
v15.0.0	Aggiunto in: v15.0.0

algorithm: <AlgorithmIdentifier> | <RsaPssParams> | <EcdsaParams> | <Ed448Params>
key: <CryptoKey>
data: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
Restituisce: <Promise> Risolve con un <ArrayBuffer>

Usando il metodo e i parametri forniti da algorithm e il materiale chiave fornito da key, subtle.sign() tenta di generare una firma crittografica di data. Se ha successo, la promise restituita viene risolta con un <ArrayBuffer> contenente la firma generata.

Gli algoritmi attualmente supportati includono:

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

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

Aggiunto in: v15.0.0

format: <string> Deve essere uno tra 'raw', 'pkcs8', 'spki' o 'jwk'.
wrappedKey: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
unwrappingKey: <CryptoKey>
unwrapAlgo: <AlgorithmIdentifier> | <RsaOaepParams> | <AesCtrParams> | <AesCbcParams> | <AesGcmParams>
unwrappedKeyAlgo: <AlgorithmIdentifier> | <RsaHashedImportParams> | <EcKeyImportParams> | <HmacImportParams>
extractable: <boolean>
keyUsages: <string[]> Vedi Utilizzi delle chiavi.
Restituisce: <Promise> Risolve con un <CryptoKey>

In crittografia, "incapsulare una chiave" si riferisce all'esportazione e quindi alla crittografia del materiale chiave. Il metodo subtle.unwrapKey() tenta di decrittografare una chiave incapsulata e creare un'istanza <CryptoKey>. È equivalente a chiamare prima subtle.decrypt() sui dati della chiave crittografata (usando gli argomenti wrappedKey, unwrapAlgo e unwrappingKey come input), quindi passando i risultati al metodo subtle.importKey() usando gli argomenti unwrappedKeyAlgo, extractable e keyUsages come input. Se ha successo, la promise restituita viene risolta con un oggetto <CryptoKey>.

Gli algoritmi di incapsulamento attualmente supportati includono:

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

Gli algoritmi di chiave decriptata supportati includono:

'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)`

[Cronologia]

Versione	Modifiche
v18.4.0, v16.17.0	Aggiunti algoritmi `'Ed25519'` e `'Ed448'`.
v15.0.0	Aggiunto in: v15.0.0

algorithm: <AlgorithmIdentifier> | <RsaPssParams> | <EcdsaParams> | <Ed448Params>
key: <CryptoKey>
signature: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
data: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
Restituisce: <Promise> Risolta con un valore <boolean>

Usando il metodo e i parametri indicati in algorithm e il materiale chiave fornito da key, subtle.verify() tenta di verificare che signature sia una firma crittografica valida di data. La promise restituita viene risolta con true o false.

Gli algoritmi attualmente supportati includono:

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

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

Aggiunto in: v15.0.0

format: <string> Deve essere uno tra 'raw', 'pkcs8', 'spki' o 'jwk'.
key: <CryptoKey>
wrappingKey: <CryptoKey>
wrapAlgo: <AlgorithmIdentifier> | <RsaOaepParams> | <AesCtrParams> | <AesCbcParams> | <AesGcmParams>
Restituisce: <Promise> Risolta con un <ArrayBuffer>

In crittografia, "incapsulare una chiave" si riferisce all'esportazione e quindi alla crittografia del materiale chiave. Il metodo subtle.wrapKey() esporta il materiale chiave nel formato identificato da format, quindi lo crittografa usando il metodo e i parametri specificati da wrapAlgo e il materiale chiave fornito da wrappingKey. È equivalente a chiamare subtle.exportKey() usando format e key come argomenti, quindi passando il risultato al metodo subtle.encrypt() usando wrappingKey e wrapAlgo come input. Se ha successo, la promise restituita verrà risolta con un <ArrayBuffer> contenente i dati della chiave crittografati.

Gli algoritmi di incapsulamento attualmente supportati includono:

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

Parametri dell'algoritmo

Gli oggetti dei parametri dell'algoritmo definiscono i metodi e i parametri utilizzati dai vari metodi <SubtleCrypto>. Sebbene qui descritti come "classi", sono semplici oggetti dizionario JavaScript.

Classe: `AlgorithmIdentifier`

Aggiunto in: v18.4.0, v16.17.0

`algorithmIdentifier.name`

Aggiunto in: v18.4.0, v16.17.0

Tipo: <string>

Classe: `AesCbcParams`

Aggiunto in: v15.0.0

`aesCbcParams.iv`

Aggiunto in: v15.0.0

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

Fornisce il vettore di inizializzazione. Deve essere esattamente lungo 16 byte e deve essere imprevedibile e crittograficamente casuale.

`aesCbcParams.name`

Aggiunto in: v15.0.0

Tipo: <string> Deve essere 'AES-CBC'.

Classe: `AesCtrParams`

Aggiunto in: v15.0.0

`aesCtrParams.counter`

Aggiunto in: v15.0.0

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

Il valore iniziale del blocco contatore. Questo deve essere lungo esattamente 16 byte.

Il metodo AES-CTR utilizza i bit più a destra di length del blocco come contatore e i bit rimanenti come nonce.

`aesCtrParams.length`

Aggiunto in: v15.0.0

Tipo: <number> Il numero di bit in aesCtrParams.counter che devono essere utilizzati come contatore.

`aesCtrParams.name`

Aggiunto in: v15.0.0

Tipo: <string> Deve essere 'AES-CTR'.

Classe: `AesGcmParams`

Aggiunto in: v15.0.0

`aesGcmParams.additionalData`

Aggiunto in: v15.0.0

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

Con il metodo AES-GCM, additionalData è un input extra che non viene criptato ma è incluso nell'autenticazione dei dati. L'utilizzo di additionalData è facoltativo.

`aesGcmParams.iv`

Aggiunto in: v15.0.0

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

Il vettore di inizializzazione deve essere univoco per ogni operazione di crittografia che utilizza una determinata chiave.

Idealmente, questo è un valore deterministico di 12 byte calcolato in modo tale da essere garantita l'univocità in tutte le invocazioni che utilizzano la stessa chiave. In alternativa, il vettore di inizializzazione può essere composto da almeno 12 byte crittograficamente casuali. Per ulteriori informazioni sulla costruzione di vettori di inizializzazione per AES-GCM, fare riferimento alla Sezione 8 di NIST SP 800-38D.

`aesGcmParams.name`

Aggiunto in: v15.0.0

Tipo: <string> Deve essere 'AES-GCM'.

`aesGcmParams.tagLength`

Aggiunto in: v15.0.0

Tipo: <number> La dimensione in bit del tag di autenticazione generato. Questo valore deve essere uno tra 32, 64, 96, 104, 112, 120, o 128. Predefinito: 128.

Classe: `AesKeyGenParams`

Aggiunto in: v15.0.0

`aesKeyGenParams.length`

Aggiunto in: v15.0.0

Tipo: <number>

La lunghezza della chiave AES da generare. Questo deve essere 128, 192, o 256.

`aesKeyGenParams.name`

Aggiunto in: v15.0.0

Tipo: <string> Deve essere uno tra 'AES-CBC', 'AES-CTR', 'AES-GCM', o 'AES-KW'

Classe: `EcdhKeyDeriveParams`

Aggiunto in: v15.0.0

`ecdhKeyDeriveParams.name`

Aggiunto in: v15.0.0

Tipo: <string> Deve essere 'ECDH', 'X25519', o 'X448'.

`ecdhKeyDeriveParams.public`

Aggiunto in: v15.0.0

Tipo: <CryptoKey>

La derivazione della chiave ECDH opera prendendo come input la chiave privata di una parte e la chiave pubblica di un'altra parte, usando entrambe per generare un segreto condiviso comune. La proprietà ecdhKeyDeriveParams.public è impostata sulla chiave pubblica dell'altra parte.

Classe: `EcdsaParams`

Aggiunto in: v15.0.0

`ecdsaParams.hash`

Aggiunto in: v15.0.0

Tipo: <string> | <Object>

Se rappresentato come <string>, il valore deve essere uno tra:

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

Se rappresentato come <Object>, l'oggetto deve avere una proprietà name il cui valore è uno dei valori sopra elencati.

`ecdsaParams.name`

Aggiunto in: v15.0.0

Tipo: <string> Deve essere 'ECDSA'.

Classe: `EcKeyGenParams`

Aggiunto in: v15.0.0

`ecKeyGenParams.name`

Aggiunto in: v15.0.0

Tipo: <string> Deve essere uno tra 'ECDSA' o 'ECDH'.

`ecKeyGenParams.namedCurve`

Aggiunto in: v15.0.0

Tipo: <string> Deve essere uno tra 'P-256', 'P-384', 'P-521'.

Classe: `EcKeyImportParams`

Aggiunto in: v15.0.0

`ecKeyImportParams.name`

Aggiunto in: v15.0.0

Tipo: <string> Deve essere uno tra 'ECDSA' o 'ECDH'.

`ecKeyImportParams.namedCurve`

Aggiunto in: v15.0.0

Tipo: <string> Deve essere uno tra 'P-256', 'P-384', 'P-521'.

Classe: `Ed448Params`

Aggiunto in: v15.0.0

`ed448Params.name`

Aggiunto in: v18.4.0, v16.17.0

Tipo: <string> Deve essere 'Ed448'.

`ed448Params.context`

Aggiunto in: v18.4.0, v16.17.0

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

Il membro context rappresenta i dati di contesto opzionali da associare al messaggio. L'implementazione Node.js dell'API Web Crypto supporta solo contesti di lunghezza zero, che è equivalente a non fornire alcun contesto.

Classe: `HkdfParams`

Aggiunto in: v15.0.0

`hkdfParams.hash`

Aggiunto in: v15.0.0

Tipo: <string> | <Object>

Se rappresentato come <string>, il valore deve essere uno dei seguenti:

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

Se rappresentato come <Object>, l'oggetto deve avere una proprietà name il cui valore è uno dei valori sopra elencati.

`hkdfParams.info`

Aggiunto in: v15.0.0

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

Fornisce input contestuale specifico dell'applicazione all'algoritmo HKDF. Può essere di lunghezza zero ma deve essere fornito.

`hkdfParams.name`

Aggiunto in: v15.0.0

Tipo: <string> Deve essere 'HKDF'.

`hkdfParams.salt`

Aggiunto in: v15.0.0

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

Il valore del sale migliora significativamente la robustezza dell'algoritmo HKDF. Dovrebbe essere casuale o pseudocasuale e dovrebbe avere la stessa lunghezza dell'output della funzione di digest (ad esempio, se si usa 'SHA-256' come digest, il sale dovrebbe essere di 256 bit di dati casuali).

Classe: `HmacImportParams`

Aggiunto in: v15.0.0

`hmacImportParams.hash`

Aggiunto in: v15.0.0

Tipo: <string> | <Object>

Se rappresentato come <string>, il valore deve essere uno dei seguenti:

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

Se rappresentato come <Object>, l'oggetto deve avere una proprietà name il cui valore è uno dei valori elencati sopra.

`hmacImportParams.length`

Aggiunto in: v15.0.0

Tipo: <number>

Il numero opzionale di bit nella chiave HMAC. Questo è opzionale e dovrebbe essere omesso nella maggior parte dei casi.

`hmacImportParams.name`

Aggiunto in: v15.0.0

Tipo: <string> Deve essere 'HMAC'.

Classe: `HmacKeyGenParams`

Aggiunto in: v15.0.0

`hmacKeyGenParams.hash`

Aggiunto in: v15.0.0

Tipo: <string> | <Object>

Se rappresentato come <string>, il valore deve essere uno dei seguenti:

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

Se rappresentato come <Object>, l'oggetto deve avere una proprietà name il cui valore è uno dei valori elencati sopra.

`hmacKeyGenParams.length`

Aggiunto in: v15.0.0

Tipo: <number>

Il numero di bit da generare per la chiave HMAC. Se omesso, la lunghezza sarà determinata dall'algoritmo hash utilizzato. Questo è opzionale e dovrebbe essere omesso nella maggior parte dei casi.

`hmacKeyGenParams.name`

Aggiunto in: v15.0.0

Tipo: <string> Deve essere 'HMAC'.

Classe: `Pbkdf2Params`

Aggiunto in: v15.0.0

`pbkdb2Params.hash`

Aggiunto in: v15.0.0

Tipo: <string> | <Object>

Se rappresentato come <string>, il valore deve essere uno dei seguenti:

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

Se rappresentato come <Object>, l'oggetto deve avere una proprietà name il cui valore è uno dei valori sopra elencati.

`pbkdf2Params.iterations`

Aggiunto in: v15.0.0

Tipo: <number>

Il numero di iterazioni che l'algoritmo PBKDF2 dovrebbe effettuare durante la derivazione dei bit.

`pbkdf2Params.name`

Aggiunto in: v15.0.0

Tipo: <string> Deve essere 'PBKDF2'.

`pbkdf2Params.salt`

Aggiunto in: v15.0.0

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

Dovrebbe essere almeno di 16 byte casuali o pseudocasuali.

Classe: `RsaHashedImportParams`

Aggiunto in: v15.0.0

`rsaHashedImportParams.hash`

Aggiunto in: v15.0.0

Tipo: <string> | <Object>

Se rappresentato come <string>, il valore deve essere uno dei seguenti:

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

Se rappresentato come <Object>, l'oggetto deve avere una proprietà name il cui valore è uno dei valori sopra elencati.

`rsaHashedImportParams.name`

Aggiunto in: v15.0.0

Tipo: <string> Deve essere uno tra 'RSASSA-PKCS1-v1_5', 'RSA-PSS', o 'RSA-OAEP'.

Classe: `RsaHashedKeyGenParams`

Aggiunto in: v15.0.0

`rsaHashedKeyGenParams.hash`

Aggiunto in: v15.0.0

Tipo: <string> | <Object>

Se rappresentato come <string>, il valore deve essere uno tra:

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

Se rappresentato come <Object>, l'oggetto deve avere una proprietà name il cui valore è uno dei valori sopra elencati.

`rsaHashedKeyGenParams.modulusLength`

Aggiunto in: v15.0.0

Tipo: <number>

La lunghezza in bit del modulo RSA. Come best practice, questo dovrebbe essere almeno 2048.

`rsaHashedKeyGenParams.name`

Aggiunto in: v15.0.0

Tipo: <string> Deve essere uno tra 'RSASSA-PKCS1-v1_5', 'RSA-PSS', o 'RSA-OAEP'.

`rsaHashedKeyGenParams.publicExponent`

Aggiunto in: v15.0.0

Tipo: <Uint8Array>

L'esponente pubblico RSA. Questo deve essere un <Uint8Array> contenente un intero senza segno big-endian che deve rientrare entro 32 bit. Il <Uint8Array> può contenere un numero arbitrario di bit zero iniziali. Il valore deve essere un numero primo. A meno che non ci sia motivo di utilizzare un valore diverso, utilizzare new Uint8Array([1, 0, 1]) (65537) come esponente pubblico.

Classe: `RsaOaepParams`

Aggiunto in: v15.0.0

`rsaOaepParams.label`

Aggiunto in: v15.0.0

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

Una collezione aggiuntiva di byte che non saranno criptati, ma saranno legati al testo cifrato generato.

Il parametro rsaOaepParams.label è opzionale.

`rsaOaepParams.name`

Aggiunto in: v15.0.0

Tipo: <string> deve essere 'RSA-OAEP'.

Classe: `RsaPssParams`

Aggiunto in: v15.0.0

`rsaPssParams.name`

Aggiunto in: v15.0.0

Tipo: <string> Deve essere 'RSA-PSS'.

`rsaPssParams.saltLength`

Aggiunto in: v15.0.0

Tipo: <number>

La lunghezza (in byte) del sale casuale da utilizzare.

Web Crypto API ​

Esempi ​

Generazione di chiavi ​

Chiavi AES ​

Coppie di chiavi ECDSA ​

Coppie di chiavi Ed25519/X25519 ​

Chiavi HMAC ​

Coppie di chiavi RSA ​

Crittografia e decrittografia ​

Esportazione e importazione di chiavi ​

Avvolgimento e svolgimento delle chiavi ​

Firma e verifica ​

Derivazione di bit e chiavi ​

Sintesi ​

Matrice algoritmi ​

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) ​

Parametri dell'algoritmo ​

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

Esempi

Generazione di chiavi

Chiavi AES

Coppie di chiavi ECDSA

Coppie di chiavi Ed25519/X25519

Chiavi HMAC

Coppie di chiavi RSA

Crittografia e decrittografia

Esportazione e importazione di chiavi

Avvolgimento e svolgimento delle chiavi

Firma e verifica

Derivazione di bit e chiavi

Sintesi

Matrice algoritmi

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)`

Parametri dell'algoritmo

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`