Web Crypto API

[Histórico]

Versão	Alterações
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 Web Crypto API.
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

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

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('I love 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 decriptografia

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
}

Envolvimento e desenvolvimento 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 criptográfica.

`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 ao 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 aleatório RFC 4122. O UUID é gerado usando um gerador de números aleatórios pseudorandom 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, o <CryptoKey> pode ser extraído 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 é uma 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 possíveis usos 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 encapsular outra chave.
'unwrapKey' - A chave pode ser usada para desembrulhar outra chave.

Usos de chave válidos 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

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 promessa retornada será resolvida com um <ArrayBuffer> contendo o resultado em texto simples.

Os algoritmos atualmente suportados incluem:

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

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

[Histórico]

Versão	Alterações
v22.5.0, v20.17.0	O parâmetro length agora é opcional para `'ECDH'`, `'X25519'` e `'X448'`.
v18.4.0, v16.17.0	Adicionados 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 chaveamento 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-sucedido, 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	Alterações
v18.4.0, v16.17.0	Adicionados 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 chaveamento fornecido por baseKey, subtle.deriveKey() tenta gerar um novo <CryptoKey> baseado no método e parâmetros em derivedKeyAlgorithm.

Chamar subtle.deriveKey() é equivalente a chamar subtle.deriveBits() para gerar material de chaveamento 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 digest de data. Se bem-sucedido, a promessa retornada é resolvida com um <ArrayBuffer> contendo o digest calculado.

Se algorithm for fornecido como um <string>, ele 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 chave fornecido por key, subtle.encrypt() tenta cifrar data. Se bem-sucedido, a promessa 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	Alterações
v18.4.0, v16.17.0	Adicionados algoritmos `'Ed25519'`, `'Ed448'`, `'X25519'` e `'X448'`.
v15.9.0	Removida exportação JWK `'NODE-DSA'`.
v15.0.0	Adicionada em: v15.0.0

format: <string> Deve ser um dos seguintes: '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 a <CryptoKey> não for extraível, a promise retornada será rejeitada.

Quando format for '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 for 'jwk' e a exportação for bem-sucedida, a promise retornada será resolvida com um objeto JavaScript conforme 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 novo material de chaveamento. 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	Alterações
v18.4.0, v16.17.0	Adicionados algoritmos `'Ed25519'`, `'Ed448'`, `'X25519'` e `'X448'`.
v15.9.0	Removida importação JWK `'NODE-DSA'`.
v15.0.0	Adicionado em: v15.0.0

format: <string> Deve ser um dos seguintes: '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 uma <CryptoKey>

O método subtle.importKey() tenta interpretar o keyData fornecido como o format dado 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.

Ao 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 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 chave 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 dos seguintes: '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, "embrulhar uma chave" refere-se a exportar e, em seguida, criptografar o material da chave. O método subtle.unwrapKey() tenta descriptografar uma chave embrulhada e criar uma instância <CryptoKey>. É equivalente a chamar primeiro subtle.decrypt() 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 embrulho 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	Alterações
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 promise 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 dos seguintes: 'raw', 'pkcs8', 'spki' ou 'jwk'.
key: <CryptoKey>
wrappingKey: <CryptoKey>
wrapAlgo: <AlgorithmIdentifier> | <RsaOaepParams> | <AesCtrParams> | <AesCbcParams> | <AesGcmParams>
Retorna: <Promise> Cumpre com um <ArrayBuffer>

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

Os algoritmos de embrulho 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 descritos aqui como "classes", são simples objetos de dicionário JavaScript.

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 de contador. Deve ter exatamente 16 bytes de comprimento.

O método AES-CTR usa os bits mais à direita de length do bloco como o contador e os bits restantes como o 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 está 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 chave fornecida.

Idealmente, este é um valor determinístico de 12 bytes que é calculado 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 mais informações sobre a construção de vetores de inicialização para AES-GCM, consulte a Seção 8 de 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 dos seguintes: 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 dos seguintes: '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 chave ECDH opera recebendo 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 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.

`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 dos seguintes: 'ECDSA' ou 'ECDH'.

`ecKeyGenParams.namedCurve`

Adicionado em: v15.0.0

Tipo: <string> Deve ser um dos seguintes: '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 dos seguintes: 'ECDSA' ou 'ECDH'.

`ecKeyImportParams.namedCurve`

Adicionado em: v15.0.0

Tipo: <string> Deve ser um dos seguintes: '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, o 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 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.

`hkdfParams.info`

Adicionado em: v15.0.0

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

Fornece entrada contextual específica do aplicativo para o algoritmo HKDF. Isso 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 salt melhora significativamente a força do algoritmo HKDF. Deve ser aleatório ou pseudorandom e deve ter o mesmo comprimento que a saída da função de digestão (por exemplo, se usar 'SHA-256' como digestão, o salt deve ser 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 gerar para a chave HMAC. Se omitido, o comprimento será determinado pelo algoritmo 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 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.

`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 pseudorandom.

Classe: `RsaHashedImportParams`

Adicionado em: v15.0.0

`rsaHashedImportParams.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.

`rsaHashedImportParams.name`

Adicionado em: v15.0.0

Tipo: <string> Deve ser um dos seguintes: '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 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.

`rsaHashedKeyGenParams.modulusLength`

Adicionado em: v15.0.0

Tipo: <number>

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

`rsaHashedKeyGenParams.name`

Adicionado em: v15.0.0

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

`rsaHashedKeyGenParams.publicExponent`

Adicionado em: v15.0.0

Tipo: <Uint8Array>

O expoente público RSA. Este deve ser um <Uint8Array> contendo um inteiro sem sinal, 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 razão 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á criptografada, mas será vinculada 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 sal aleatório a ser usado.

Web Crypto API ​

Exemplos ​

Gerando chaves ​

Chaves AES ​

Pares de chaves ECDSA ​

Pares de chaves Ed25519/X25519 ​

Chaves HMAC ​

Pares de chaves RSA ​

Criptografia e decriptografia ​

Exportando e importando chaves ​

Envolvimento e desenvolvimento 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 ​

Web Crypto API

Exemplos

Gerando chaves

Chaves AES

Pares de chaves ECDSA

Pares de chaves Ed25519/X25519

Chaves HMAC

Pares de chaves RSA

Criptografia e decriptografia

Exportando e importando chaves

Envolvimento e desenvolvimento 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`