API Web Crypto

[Histórico]

Versão	Mudanças
v23.5.0	Os algoritmos `Ed25519` e `X25519` agora são estáveis.
v19.0.0	Não é mais experimental, exceto para os algoritmos `Ed25519`, `Ed448`, `X25519` e `X448`.
v20.0.0, v18.17.0	Os argumentos agora são forçados e validados de acordo com suas definições WebIDL como em outras implementações da API Web Crypto.
v18.4.0, v16.17.0	Formato de importação/exportação proprietário `'node.keyObject'` removido.
v18.4.0, v16.17.0	Algoritmos proprietários `'NODE-DSA'`, `'NODE-DH'` e `'NODE-SCRYPT'` removidos.
v18.4.0, v16.17.0	Algoritmos `'Ed25519'`, `'Ed448'`, `'X25519'` e `'X448'` adicionados.
v18.4.0, v16.17.0	Algoritmos proprietários `'NODE-ED25519'` e `'NODE-ED448'` removidos.
v18.4.0, v16.17.0	Curvas nomeadas proprietárias `'NODE-X25519'` e `'NODE-X448'` removidas do algoritmo `'ECDH'`.

[Estável: 2 - Estável]

Estável: 2 Estabilidade: 2 - Estável

O Node.js fornece uma implementação da API Web Crypto padrão.

Use globalThis.crypto ou require('node:crypto').webcrypto para acessar este módulo.

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('Eu amo cupcakes');

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

})();

Exemplos

Gerando chaves

A classe <SubtleCrypto> pode ser usada para gerar chaves simétricas (secretas) ou pares de chaves assimétricas (chave pública e chave privada).

Chaves AES

const { subtle } = globalThis.crypto;

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

  return key;
}

Pares de chaves 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 };
}

Pares de chaves 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']);
}

Chaves HMAC

const { subtle } = globalThis.crypto;

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

  return key;
}

Pares de chaves 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 };
}

Criptografia e descriptografia

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

Exportando e importando chaves

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

Wrapping e unwrapping de chaves

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

Assinar e verificar

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

Derivando bits e chaves

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

Matriz de Algoritmos

A tabela detalha os algoritmos suportados pela implementação da API Web Crypto do Node.js e as APIs suportadas para cada um:

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`

Adicionado em: v15.0.0

globalThis.crypto é uma instância da classe Crypto. Crypto é um singleton que fornece acesso ao restante da API de criptografia.

`crypto.subtle`

Adicionado em: v15.0.0

Tipo: <SubtleCrypto>

Fornece acesso à API SubtleCrypto.

`crypto.getRandomValues(typedArray)`

Adicionado em: v15.0.0

typedArray <Buffer> | <TypedArray>
Retorna: <Buffer> | <TypedArray>

Gera valores aleatórios criptograficamente fortes. O typedArray fornecido é preenchido com valores aleatórios e uma referência a typedArray é retornada.

O typedArray fornecido deve ser uma instância baseada em inteiros de <TypedArray>, ou seja, Float32Array e Float64Array não são aceitos.

Um erro será lançado se o typedArray fornecido for maior que 65.536 bytes.

`crypto.randomUUID()`

Adicionado em: v16.7.0

Retorna: <string>

Gera um UUID versão 4 RFC 4122 aleatório. O UUID é gerado usando um gerador de números pseudoaleatórios criptográfico.

Classe: `CryptoKey`

Adicionado em: v15.0.0

`cryptoKey.algorithm`

Adicionado em: v15.0.0

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

Um objeto detalhando o algoritmo para o qual a chave pode ser usada, juntamente com parâmetros adicionais específicos do algoritmo.

Somente leitura.

`cryptoKey.extractable`

Adicionado em: v15.0.0

Tipo: <boolean>

Quando true, a <CryptoKey> pode ser extraída usando subtleCrypto.exportKey() ou subtleCrypto.wrapKey().

Somente leitura.

`cryptoKey.type`

Adicionado em: v15.0.0

Tipo: <string> Um de 'secret', 'private' ou 'public'.

Uma string identificando se a chave é simétrica ('secret') ou assimétrica ('private' ou 'public').

`cryptoKey.usages`

Adicionado em: v15.0.0

Tipo: <string[]>

Um array de strings identificando as operações para as quais a chave pode ser usada.

Os usos possíveis são:

'encrypt' - A chave pode ser usada para criptografar dados.
'decrypt' - A chave pode ser usada para descriptografar dados.
'sign' - A chave pode ser usada para gerar assinaturas digitais.
'verify' - A chave pode ser usada para verificar assinaturas digitais.
'deriveKey' - A chave pode ser usada para derivar uma nova chave.
'deriveBits' - A chave pode ser usada para derivar bits.
'wrapKey' - A chave pode ser usada para envolver outra chave.
'unwrapKey' - A chave pode ser usada para desembrulhar outra chave.

Os usos válidos da chave dependem do algoritmo da chave (identificado por cryptokey.algorithm.name).

Tipo de Chave	`'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`

Adicionado em: v15.0.0

O CryptoKeyPair é um objeto de dicionário simples com propriedades publicKey e privateKey, representando um par de chaves assimétricas.

`cryptoKeyPair.privateKey`

Adicionado em: v15.0.0

Tipo: <CryptoKey> Um <CryptoKey> cujo type será 'private'.

`cryptoKeyPair.publicKey`

Adicionado em: v15.0.0

Tipo: <CryptoKey> Um <CryptoKey> cujo type será 'public'.

Classe: `SubtleCrypto`

Adicionado em: v15.0.0

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

Adicionado em: v15.0.0

algorithm: <RsaOaepParams> | <AesCtrParams> | <AesCbcParams> | <AesGcmParams>
key: <CryptoKey>
data: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
Retorna: <Promise> Cumpre com um <ArrayBuffer>

Usando o método e os parâmetros especificados em algorithm e o material de chaveamento fornecido por key, subtle.decrypt() tenta decifrar os data fornecidos. Se bem-sucedido, a promise retornada será resolvida com um <ArrayBuffer> contendo o resultado do texto simples.

Os algoritmos atualmente suportados incluem:

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

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

[Histórico]

Versão	Mudanças
v22.5.0, v20.17.0	O parâmetro length agora é opcional para `'ECDH'`, `'X25519'` e `'X448'`.
v18.4.0, v16.17.0	Adicionados os algoritmos `'X25519'` e `'X448'`.
v15.0.0	Adicionado em: v15.0.0

algorithm: <AlgorithmIdentifier> | <EcdhKeyDeriveParams> | <HkdfParams> | <Pbkdf2Params>
baseKey: <CryptoKey>
length: <number> | <null> Padrão: null
Retorna: <Promise> Cumpre com um <ArrayBuffer>

Usando o método e os parâmetros especificados em algorithm e o material de chave fornecido por baseKey, subtle.deriveBits() tenta gerar length bits.

Quando length não é fornecido ou é null, o número máximo de bits para um determinado algoritmo é gerado. Isso é permitido para os algoritmos 'ECDH', 'X25519' e 'X448', para outros algoritmos, length deve ser um número.

Se bem-sucedida, a promessa retornada será resolvida com um <ArrayBuffer> contendo os dados gerados.

Os algoritmos atualmente suportados incluem:

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

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

[Histórico]

Versão	Mudanças
v18.4.0, v16.17.0	Adicionados os algoritmos `'X25519'` e `'X448'`.
v15.0.0	Adicionado em: v15.0.0

algorithm: <AlgorithmIdentifier> | <EcdhKeyDeriveParams> | <HkdfParams> | <Pbkdf2Params>
baseKey: <CryptoKey>
derivedKeyAlgorithm: <HmacKeyGenParams> | <AesKeyGenParams>
extractable: <boolean>
keyUsages: <string[]> Veja Usos de chave.
Retorna: <Promise> Cumpre com um <CryptoKey>

Usando o método e os parâmetros especificados em algorithm, e o material de chave fornecido por baseKey, subtle.deriveKey() tenta gerar um novo <CryptoKey> com base no método e parâmetros em derivedKeyAlgorithm.

Chamar subtle.deriveKey() é equivalente a chamar subtle.deriveBits() para gerar material de chave bruto, e então passar o resultado para o método subtle.importKey() usando os parâmetros deriveKeyAlgorithm, extractable e keyUsages como entrada.

Os algoritmos atualmente suportados incluem:

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

`subtle.digest(algorithm, data)`

Adicionado em: v15.0.0

algorithm: <string> | <Object>
data: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
Retorna: <Promise> Cumpre com um <ArrayBuffer>

Usando o método identificado por algorithm, subtle.digest() tenta gerar um resumo de data. Se bem-sucedido, a promise retornada é resolvida com um <ArrayBuffer> contendo o resumo computado.

Se algorithm for fornecido como uma <string>, deve ser um dos seguintes:

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

Se algorithm for fornecido como um <Object>, ele deve ter uma propriedade name cujo valor seja um dos acima.

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

Adicionado em: v15.0.0

algorithm: <RsaOaepParams> | <AesCtrParams> | <AesCbcParams> | <AesGcmParams>
key: <CryptoKey>
data: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
Retorna: <Promise> Cumpre com um <ArrayBuffer>

Usando o método e os parâmetros especificados por algorithm e o material de chaveamento fornecido por key, subtle.encrypt() tenta criptografar data. Se bem-sucedido, a promise retornada é resolvida com um <ArrayBuffer> contendo o resultado criptografado.

Os algoritmos atualmente suportados incluem:

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

`subtle.exportKey(format, key)`

[Histórico]

Versão	Mudanças
v18.4.0, v16.17.0	Adicionados algoritmos `'Ed25519'`, `'Ed448'`, `'X25519'` e `'X448'`.
v15.9.0	Removida a exportação JWK `'NODE-DSA'`.
v15.0.0	Adicionado em: v15.0.0

format: <string> Deve ser um de 'raw', 'pkcs8', 'spki' ou 'jwk'.
key: <CryptoKey>
Retorna: <Promise> Cumpre com um <ArrayBuffer> | <Object>.

Exporta a chave fornecida para o formato especificado, se suportado.

Se o <CryptoKey> não for extraível, a promise retornada será rejeitada.

Quando format é 'pkcs8' ou 'spki' e a exportação for bem-sucedida, a promise retornada será resolvida com um <ArrayBuffer> contendo os dados da chave exportada.

Quando format é 'jwk' e a exportação for bem-sucedida, a promise retornada será resolvida com um objeto JavaScript em conformidade com a especificação JSON Web Key.

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

Adicionado em: v15.0.0

algorithm: <AlgorithmIdentifier> | <RsaHashedKeyGenParams> | <EcKeyGenParams> | <HmacKeyGenParams> | <AesKeyGenParams>
extractable: <boolean>
keyUsages: <string[]> Veja Usos de Chave.
Retorna: <Promise> Cumpre com um <CryptoKey> | <CryptoKeyPair>

Usando o método e os parâmetros fornecidos em algorithm, subtle.generateKey() tenta gerar um novo material de chave. Dependendo do método usado, o método pode gerar um único <CryptoKey> ou um <CryptoKeyPair>.

Os algoritmos de geração de <CryptoKeyPair> (chave pública e privada) suportados incluem:

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

Os algoritmos de geração de <CryptoKey> (chave secreta) suportados incluem:

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

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

[Histórico]

Versão	Mudanças
v18.4.0, v16.17.0	Adicionados os algoritmos `'Ed25519'`, `'Ed448'`, `'X25519'` e `'X448'`.
v15.9.0	Removida a importação JWK `'NODE-DSA'`.
v15.0.0	Adicionado em: v15.0.0

format: <string> Deve ser um de 'raw', 'pkcs8', 'spki' ou 'jwk'.
keyData: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer> | <Object>
algorithm: <AlgorithmIdentifier> | <RsaHashedImportParams> | <EcKeyImportParams> | <HmacImportParams>
extractable: <boolean>
keyUsages: <string[]> Veja Usos de chaves.
Retorna: <Promise> Cumpre com um <CryptoKey>

O método subtle.importKey() tenta interpretar o keyData fornecido como o format fornecido para criar uma instância <CryptoKey> usando os argumentos algorithm, extractable e keyUsages fornecidos. Se a importação for bem-sucedida, a promise retornada será resolvida com o <CryptoKey> criado.

Se importar uma chave 'PBKDF2', extractable deve ser false.

Os algoritmos atualmente suportados incluem:

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

[Histórico]

Versão	Alterações
v18.4.0, v16.17.0	Adicionados os algoritmos `'Ed25519'` e `'Ed448'`.
v15.0.0	Adicionado em: v15.0.0

algorithm: <AlgorithmIdentifier> | <RsaPssParams> | <EcdsaParams> | <Ed448Params>
key: <CryptoKey>
data: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
Retorna: <Promise> Cumpre com um <ArrayBuffer>

Usando o método e os parâmetros fornecidos por algorithm e o material de chaveamento fornecido por key, subtle.sign() tenta gerar uma assinatura criptográfica de data. Se bem-sucedido, a promessa retornada é resolvida com um <ArrayBuffer> contendo a assinatura gerada.

Os algoritmos atualmente suportados incluem:

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

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

Adicionado em: v15.0.0

format: <string> Deve ser um de '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[]> Veja Usos de Chave.
Retorna: <Promise> Cumpre com um <CryptoKey>

Em criptografia, "empacotar uma chave" refere-se a exportar e, em seguida, criptografar o material de chaveamento. O método subtle.unwrapKey() tenta descriptografar uma chave empacotada e criar uma instância de <CryptoKey>. É equivalente a chamar subtle.decrypt() primeiro nos dados da chave criptografada (usando os argumentos wrappedKey, unwrapAlgo e unwrappingKey como entrada) e, em seguida, passar os resultados para o método subtle.importKey() usando os argumentos unwrappedKeyAlgo, extractable e keyUsages como entradas. Se bem-sucedido, a promessa retornada é resolvida com um objeto <CryptoKey>.

Os algoritmos de empacotamento atualmente suportados incluem:

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

Os algoritmos de chave desembrulhada suportados incluem:

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

[Histórico]

Versão	Mudanças
v18.4.0, v16.17.0	Adicionados algoritmos `'Ed25519'` e `'Ed448'`.
v15.0.0	Adicionado em: v15.0.0

algorithm: <AlgorithmIdentifier> | <RsaPssParams> | <EcdsaParams> | <Ed448Params>
key: <CryptoKey>
signature: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
data: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
Retorna: <Promise> Cumpre com um <boolean>

Usando o método e os parâmetros fornecidos em algorithm e o material de chave fornecido por key, subtle.verify() tenta verificar se signature é uma assinatura criptográfica válida de data. A promessa retornada é resolvida com true ou false.

Os algoritmos atualmente suportados incluem:

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

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

Adicionado em: v15.0.0

format: <string> Deve ser um de 'raw', 'pkcs8', 'spki' ou 'jwk'.
key: <CryptoKey>
wrappingKey: <CryptoKey>
wrapAlgo: <AlgorithmIdentifier> | <RsaOaepParams> | <AesCtrParams> | <AesCbcParams> | <AesGcmParams>
Retorna: <Promise> Cumpre com um <ArrayBuffer>

Em criptografia, "envolver uma chave" refere-se a exportar e, em seguida, criptografar o material da chave. O método subtle.wrapKey() exporta o material da chave para o formato identificado por format e, em seguida, criptografa-o usando o método e os parâmetros especificados por wrapAlgo e o material da chave fornecido por wrappingKey. É o equivalente a chamar subtle.exportKey() usando format e key como argumentos e, em seguida, passar o resultado para o método subtle.encrypt() usando wrappingKey e wrapAlgo como entradas. Se bem-sucedida, a promessa retornada será resolvida com um <ArrayBuffer> contendo os dados da chave criptografada.

Os algoritmos de encapsulamento atualmente suportados incluem:

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

Parâmetros do Algoritmo

Os objetos de parâmetros do algoritmo definem os métodos e parâmetros usados pelos vários métodos <SubtleCrypto>. Embora sejam descritos aqui como "classes", eles são objetos de dicionário JavaScript simples.

Classe: `AlgorithmIdentifier`

Adicionado em: v18.4.0, v16.17.0

`algorithmIdentifier.name`

Adicionado em: v18.4.0, v16.17.0

Tipo: <string>

Classe: `AesCbcParams`

Adicionado em: v15.0.0

`aesCbcParams.iv`

Adicionado em: v15.0.0

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

Fornece o vetor de inicialização. Deve ter exatamente 16 bytes de comprimento e deve ser imprevisível e criptograficamente aleatório.

`aesCbcParams.name`

Adicionado em: v15.0.0

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

Classe: `AesCtrParams`

Adicionado em: v15.0.0

`aesCtrParams.counter`

Adicionado em: v15.0.0

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

O valor inicial do bloco do contador. Isso deve ter exatamente 16 bytes de comprimento.

O método AES-CTR usa os length bits mais à direita do bloco como contador e os bits restantes como nonce.

`aesCtrParams.length`

Adicionado em: v15.0.0

Tipo: <number> O número de bits em aesCtrParams.counter que devem ser usados como contador.

`aesCtrParams.name`

Adicionado em: v15.0.0

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

Classe: `AesGcmParams`

Adicionado em: v15.0.0

`aesGcmParams.additionalData`

Adicionado em: v15.0.0

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

Com o método AES-GCM, o additionalData é uma entrada extra que não é criptografada, mas é incluída na autenticação dos dados. O uso de additionalData é opcional.

`aesGcmParams.iv`

Adicionado em: v15.0.0

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

O vetor de inicialização deve ser único para cada operação de criptografia usando uma determinada chave.

Idealmente, este é um valor determinístico de 12 bytes que é computado de forma que seja garantido que seja único em todas as invocações que usam a mesma chave. Alternativamente, o vetor de inicialização pode consistir em pelo menos 12 bytes criptograficamente aleatórios. Para obter mais informações sobre como construir vetores de inicialização para AES-GCM, consulte a Seção 8 do NIST SP 800-38D.

`aesGcmParams.name`

Adicionado em: v15.0.0

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

`aesGcmParams.tagLength`

Adicionado em: v15.0.0

Tipo: <number> O tamanho em bits da tag de autenticação gerada. Este valor deve ser um de 32, 64, 96, 104, 112, 120 ou 128. Padrão: 128.

Classe: `AesKeyGenParams`

Adicionado em: v15.0.0

`aesKeyGenParams.length`

Adicionado em: v15.0.0

Tipo: <number>

O comprimento da chave AES a ser gerada. Deve ser 128, 192 ou 256.

`aesKeyGenParams.name`

Adicionado em: v15.0.0

Tipo: <string> Deve ser um de 'AES-CBC', 'AES-CTR', 'AES-GCM' ou 'AES-KW'

Classe: `EcdhKeyDeriveParams`

Adicionado em: v15.0.0

`ecdhKeyDeriveParams.name`

Adicionado em: v15.0.0

Tipo: <string> Deve ser 'ECDH', 'X25519' ou 'X448'.

`ecdhKeyDeriveParams.public`

Adicionado em: v15.0.0

Tipo: <CryptoKey>

A derivação de chaves ECDH opera tomando como entrada a chave privada de uma parte e a chave pública de outra parte -- usando ambas para gerar um segredo compartilhado comum. A propriedade ecdhKeyDeriveParams.public é definida para a chave pública da outra parte.

Classe: `EcdsaParams`

Adicionado em: v15.0.0

`ecdsaParams.hash`

Adicionado em: v15.0.0

Tipo: <string> | <Object>

Se representado como uma <string>, o valor deve ser um de:

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

Se representado como um <Object>, o objeto deve ter uma propriedade name cujo valor seja um dos valores listados acima.

`ecdsaParams.name`

Adicionado em: v15.0.0

Tipo: <string> Deve ser 'ECDSA'.

Classe: `EcKeyGenParams`

Adicionado em: v15.0.0

`ecKeyGenParams.name`

Adicionado em: v15.0.0

Tipo: <string> Deve ser um de 'ECDSA' ou 'ECDH'.

`ecKeyGenParams.namedCurve`

Adicionado em: v15.0.0

Tipo: <string> Deve ser um de 'P-256', 'P-384', 'P-521'.

Classe: `EcKeyImportParams`

Adicionado em: v15.0.0

`ecKeyImportParams.name`

Adicionado em: v15.0.0

Tipo: <string> Deve ser um de 'ECDSA' ou 'ECDH'.

`ecKeyImportParams.namedCurve`

Adicionado em: v15.0.0

Tipo: <string> Deve ser um de 'P-256', 'P-384', 'P-521'.

Classe: `Ed448Params`

Adicionado em: v15.0.0

`ed448Params.name`

Adicionado em: v18.4.0, v16.17.0

Tipo: <string> Deve ser 'Ed448'.

`ed448Params.context`

Adicionado em: v18.4.0, v16.17.0

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

O membro context representa os dados de contexto opcionais a serem associados à mensagem. A implementação da API Web Crypto do Node.js suporta apenas contexto de comprimento zero, que é equivalente a não fornecer contexto algum.

Classe: `HkdfParams`

Adicionado em: v15.0.0

`hkdfParams.hash`

Adicionado em: v15.0.0

Tipo: <string> | <Object>

Se representado como uma <string>, o valor deve ser um dos seguintes:

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

Se representado como um <Object>, o objeto deve ter uma propriedade name cujo valor seja um dos valores listados acima.

`hkdfParams.info`

Adicionado em: v15.0.0

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

Fornece entrada contextual específica da aplicação para o algoritmo HKDF. Pode ter comprimento zero, mas deve ser fornecido.

`hkdfParams.name`

Adicionado em: v15.0.0

Tipo: <string> Deve ser 'HKDF'.

`hkdfParams.salt`

Adicionado em: v15.0.0

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

O valor do salt melhora significativamente a força do algoritmo HKDF. Deve ser aleatório ou pseudoaleatório e deve ter o mesmo comprimento da saída da função de digest (por exemplo, se usar 'SHA-256' como o digest, o salt deve ter 256 bits de dados aleatórios).

Classe: `HmacImportParams`

Adicionado em: v15.0.0

`hmacImportParams.hash`

Adicionado em: v15.0.0

Tipo: <string> | <Object>

Se representado como um <string>, o valor deve ser um dos seguintes:

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

Se representado como um <Object>, o objeto deve ter uma propriedade name cujo valor seja um dos valores listados acima.

`hmacImportParams.length`

Adicionado em: v15.0.0

Tipo: <number>

O número opcional de bits na chave HMAC. Isso é opcional e deve ser omitido na maioria dos casos.

`hmacImportParams.name`

Adicionado em: v15.0.0

Tipo: <string> Deve ser 'HMAC'.

Classe: `HmacKeyGenParams`

Adicionado em: v15.0.0

`hmacKeyGenParams.hash`

Adicionado em: v15.0.0

Tipo: <string> | <Object>

Se representado como um <string>, o valor deve ser um dos seguintes:

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

Se representado como um <Object>, o objeto deve ter uma propriedade name cujo valor seja um dos valores listados acima.

`hmacKeyGenParams.length`

Adicionado em: v15.0.0

Tipo: <number>

O número de bits a serem gerados para a chave HMAC. Se omitido, o comprimento será determinado pelo algoritmo de hash usado. Isso é opcional e deve ser omitido na maioria dos casos.

`hmacKeyGenParams.name`

Adicionado em: v15.0.0

Tipo: <string> Deve ser 'HMAC'.

Classe: `Pbkdf2Params`

Adicionado em: v15.0.0

`pbkdb2Params.hash`

Adicionado em: v15.0.0

Tipo: <string> | <Object>

Se representado como uma <string>, o valor deve ser um dos seguintes:

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

Se representado como um <Object>, o objeto deve ter uma propriedade name cujo valor seja um dos valores listados acima.

`pbkdf2Params.iterations`

Adicionado em: v15.0.0

Tipo: <number>

O número de iterações que o algoritmo PBKDF2 deve fazer ao derivar bits.

`pbkdf2Params.name`

Adicionado em: v15.0.0

Tipo: <string> Deve ser 'PBKDF2'.

`pbkdf2Params.salt`

Adicionado em: v15.0.0

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

Deve ter pelo menos 16 bytes aleatórios ou pseudoaleatórios.

Classe: `RsaHashedImportParams`

Adicionado em: v15.0.0

`rsaHashedImportParams.hash`

Adicionado em: v15.0.0

Tipo: <string> | <Object>

Se representado como uma <string>, o valor deve ser um dos seguintes:

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

Se representado como um <Object>, o objeto deve ter uma propriedade name cujo valor seja um dos valores listados acima.

`rsaHashedImportParams.name`

Adicionado em: v15.0.0

Tipo: <string> Deve ser um de 'RSASSA-PKCS1-v1_5', 'RSA-PSS' ou 'RSA-OAEP'.

Classe: `RsaHashedKeyGenParams`

Adicionado em: v15.0.0

`rsaHashedKeyGenParams.hash`

Adicionado em: v15.0.0

Tipo: <string> | <Object>

Se representado como um <string>, o valor deve ser um de:

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

Se representado como um <Object>, o objeto deve ter uma propriedade name cujo valor seja um dos valores listados acima.

`rsaHashedKeyGenParams.modulusLength`

Adicionado em: v15.0.0

Tipo: <number>

O comprimento em bits do módulo RSA. Como prática recomendada, isso deve ser pelo menos 2048.

`rsaHashedKeyGenParams.name`

Adicionado em: v15.0.0

Tipo: <string> Deve ser um de 'RSASSA-PKCS1-v1_5', 'RSA-PSS' ou 'RSA-OAEP'.

`rsaHashedKeyGenParams.publicExponent`

Adicionado em: v15.0.0

Tipo: <Uint8Array>

O expoente público RSA. Isso deve ser um <Uint8Array> contendo um inteiro não assinado big-endian que deve caber em 32 bits. O <Uint8Array> pode conter um número arbitrário de bits zero à esquerda. O valor deve ser um número primo. A menos que haja um motivo para usar um valor diferente, use new Uint8Array([1, 0, 1]) (65537) como o expoente público.

Classe: `RsaOaepParams`

Adicionado em: v15.0.0

`rsaOaepParams.label`

Adicionado em: v15.0.0

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

Uma coleção adicional de bytes que não serão criptografados, mas serão vinculados ao texto cifrado gerado.

O parâmetro rsaOaepParams.label é opcional.

`rsaOaepParams.name`

Adicionado em: v15.0.0

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

Classe: `RsaPssParams`

Adicionado em: v15.0.0

`rsaPssParams.name`

Adicionado em: v15.0.0

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

`rsaPssParams.saltLength`

Adicionado em: v15.0.0

Tipo: <number>

O comprimento (em bytes) do salt aleatório a ser usado.

API Web Crypto ​

Exemplos ​

Gerando chaves ​

Chaves AES ​

Pares de chaves ECDSA ​

Pares de chaves Ed25519/X25519 ​

Chaves HMAC ​

Pares de chaves RSA ​

Criptografia e descriptografia ​

Exportando e importando chaves ​

Wrapping e unwrapping de chaves ​

Assinar e verificar ​

Derivando bits e chaves ​

Digest ​

Matriz de Algoritmos ​

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

Parâmetros do 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 ​

API Web Crypto

Exemplos

Gerando chaves

Chaves AES

Pares de chaves ECDSA

Pares de chaves Ed25519/X25519

Chaves HMAC

Pares de chaves RSA

Criptografia e descriptografia

Exportando e importando chaves

Wrapping e unwrapping de chaves

Assinar e verificar

Derivando bits e chaves

Digest

Matriz de Algoritmos

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

Parâmetros do 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`