iDoc.dev

Português

English
简体中文
Español
Français
Deutsch
Italiano
日本語
한국어
Русский
العربية

Português

English
简体中文
Español
Français
Deutsch
Italiano
日本語
한국어
Русский
العربية

Tema

Crypto ​

[Stable: 2 - Stable]

Stable: 2 Estabilidade: 2 - Estável

Código-fonte: lib/crypto.js

O módulo node:crypto fornece funcionalidade criptográfica que inclui um conjunto de wrappers para as funções de hash, HMAC, cifra, decifração, assinatura e verificação do OpenSSL.

js
const { createHmac } = await import('node:crypto')

const secret = 'abcdefg'
const hash = createHmac('sha256', secret).update('I love cupcakes').digest('hex')
console.log(hash)
// Imprime:
//   c0fa1bc00531bd78ef38c628449c5102aeabd49b5dc3a2a516ea6ea959d6658e
js
const { createHmac } = require('node:crypto')

const secret = 'abcdefg'
const hash = createHmac('sha256', secret).update('I love cupcakes').digest('hex')
console.log(hash)
// Imprime:
//   c0fa1bc00531bd78ef38c628449c5102aeabd49b5dc3a2a516ea6ea959d6658e

Determinar se o suporte a criptografia está indisponível ​

É possível que o Node.js seja construído sem incluir suporte para o módulo node:crypto. Nesses casos, tentar importar de crypto ou chamar require('node:crypto') resultará em um erro sendo lançado.

Ao usar o CommonJS, o erro lançado pode ser capturado usando try/catch:

js
let crypto
try {
  crypto = require('node:crypto')
} catch (err) {
  console.error('suporte a criptografia está desabilitado!')
}

Ao usar a palavra-chave lexical ESM import, o erro só pode ser capturado se um manipulador para process.on('uncaughtException') for registrado antes de qualquer tentativa de carregar o módulo ser feita (usando, por exemplo, um módulo de pré-carregamento).

Ao usar ESM, se houver uma chance de o código ser executado em uma build do Node.js onde o suporte a criptografia não esteja habilitado, considere usar a função import() em vez da palavra-chave lexical import:

js
let crypto
try {
  crypto = await import('node:crypto')
} catch (err) {
  console.error('suporte a criptografia está desabilitado!')
}

Classe: Certificate ​

Adicionado em: v0.11.8

SPKAC é um mecanismo de Solicitação de Assinatura de Certificado originalmente implementado pela Netscape e foi especificado formalmente como parte do elemento keygen do HTML5.

\<keygen\> está depreciado desde HTML 5.2 e novos projetos não devem mais usar este elemento.

O módulo node:crypto fornece a classe Certificate para trabalhar com dados SPKAC. O uso mais comum é o tratamento da saída gerada pelo elemento HTML5 \<keygen\>. O Node.js usa a implementação SPKAC do OpenSSL internamente.

Método estático: Certificate.exportChallenge(spkac[, encoding]) ​

[Histórico]

VersãoAlterações
v15.0.0O argumento spkac pode ser um ArrayBuffer. Limitou o tamanho do argumento spkac a um máximo de 2**31 - 1 bytes.
v9.0.0Adicionado em: v9.0.0
js
const { Certificate } = await import('node:crypto')
const spkac = getSpkacSomehow()
const challenge = Certificate.exportChallenge(spkac)
console.log(challenge.toString('utf8'))
// Imprime: o desafio como uma string UTF8
js
const { Certificate } = require('node:crypto')
const spkac = getSpkacSomehow()
const challenge = Certificate.exportChallenge(spkac)
console.log(challenge.toString('utf8'))
// Imprime: o desafio como uma string UTF8

Método estático: Certificate.exportPublicKey(spkac[, encoding]) ​

[Histórico]

VersãoMudanças
v15.0.0O argumento spkac pode ser um ArrayBuffer. Limitou o tamanho do argumento spkac a um máximo de 2**31 - 1 bytes.
v9.0.0Adicionado em: v9.0.0
js
const { Certificate } = await import('node:crypto')
const spkac = getSpkacSomehow()
const publicKey = Certificate.exportPublicKey(spkac)
console.log(publicKey)
// Imprime: a chave pública como <Buffer ...>
js
const { Certificate } = require('node:crypto')
const spkac = getSpkacSomehow()
const publicKey = Certificate.exportPublicKey(spkac)
console.log(publicKey)
// Imprime: a chave pública como <Buffer ...>

Método estático: Certificate.verifySpkac(spkac[, encoding]) ​

[Histórico]

VersãoMudanças
v15.0.0O argumento spkac pode ser um ArrayBuffer. Adicionada codificação. Limitou o tamanho do argumento spkac a um máximo de 2**31 - 1 bytes.
v9.0.0Adicionado em: v9.0.0
js
import { Buffer } from 'node:buffer'
const { Certificate } = await import('node:crypto')

const spkac = getSpkacSomehow()
console.log(Certificate.verifySpkac(Buffer.from(spkac)))
// Imprime: true ou false
js
const { Buffer } = require('node:buffer')
const { Certificate } = require('node:crypto')

const spkac = getSpkacSomehow()
console.log(Certificate.verifySpkac(Buffer.from(spkac)))
// Imprime: true ou false

API Legada ​

[Estável: 0 - Obsoleto]

Estável: 0 Estabilidade: 0 - Obsoleto

Como uma interface legada, é possível criar novas instâncias da classe crypto.Certificate como ilustrado nos exemplos abaixo.

new crypto.Certificate() ​

Instâncias da classe Certificate podem ser criadas usando a palavra-chave new ou chamando crypto.Certificate() como uma função:

js
const { Certificate } = await import('node:crypto')

const cert1 = new Certificate()
const cert2 = Certificate()
js
const { Certificate } = require('node:crypto')

const cert1 = new Certificate()
const cert2 = Certificate()

certificate.exportChallenge(spkac[, encoding]) ​

Adicionado em: v0.11.8

js
const { Certificate } = await import('node:crypto')
const cert = Certificate()
const spkac = getSpkacSomehow()
const challenge = cert.exportChallenge(spkac)
console.log(challenge.toString('utf8'))
// Imprime: o desafio como uma string UTF8
js
const { Certificate } = require('node:crypto')
const cert = Certificate()
const spkac = getSpkacSomehow()
const challenge = cert.exportChallenge(spkac)
console.log(challenge.toString('utf8'))
// Imprime: o desafio como uma string UTF8

certificate.exportPublicKey(spkac[, encoding]) ​

Adicionado em: v0.11.8

js
const { Certificate } = await import('node:crypto')
const cert = Certificate()
const spkac = getSpkacSomehow()
const publicKey = cert.exportPublicKey(spkac)
console.log(publicKey)
// Imprime: a chave pública como <Buffer ...>
js
const { Certificate } = require('node:crypto')
const cert = Certificate()
const spkac = getSpkacSomehow()
const publicKey = cert.exportPublicKey(spkac)
console.log(publicKey)
// Imprime: a chave pública como <Buffer ...>

certificate.verifySpkac(spkac[, encoding]) ​

Adicionado em: v0.11.8

js
import { Buffer } from 'node:buffer'
const { Certificate } = await import('node:crypto')

const cert = Certificate()
const spkac = getSpkacSomehow()
console.log(cert.verifySpkac(Buffer.from(spkac)))
// Imprime: true ou false
js
const { Buffer } = require('node:buffer')
const { Certificate } = require('node:crypto')

const cert = Certificate()
const spkac = getSpkacSomehow()
console.log(cert.verifySpkac(Buffer.from(spkac)))
// Imprime: true ou false

Classe: Cipher ​

Adicionado em: v0.1.94

Instâncias da classe Cipher são usadas para criptografar dados. A classe pode ser usada de uma das duas maneiras:

  • Como um stream que é legível e gravável, onde dados simples não criptografados são escritos para produzir dados criptografados no lado legível, ou
  • Usando os métodos cipher.update() e cipher.final() para produzir os dados criptografados.

O método crypto.createCipheriv() é usado para criar instâncias Cipher. Objetos Cipher não devem ser criados diretamente usando a palavra-chave new.

Exemplo: Usando objetos Cipher como streams:

js
const { scrypt, randomFill, createCipheriv } = await import('node:crypto')

const algorithm = 'aes-192-cbc'
const password = 'Senha usada para gerar a chave'

// Primeiro, vamos gerar a chave. O comprimento da chave depende do algoritmo.
// Neste caso para aes192, é 24 bytes (192 bits).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err
  // Então, vamos gerar um vetor de inicialização aleatório
  randomFill(new Uint8Array(16), (err, iv) => {
    if (err) throw err

    // Assim que tivermos a chave e o iv, podemos criar e usar a cifra...
    const cipher = createCipheriv(algorithm, key, iv)

    let encrypted = ''
    cipher.setEncoding('hex')

    cipher.on('data', chunk => (encrypted += chunk))
    cipher.on('end', () => console.log(encrypted))

    cipher.write('alguns dados de texto claro')
    cipher.end()
  })
})
js
const { scrypt, randomFill, createCipheriv } = require('node:crypto')

const algorithm = 'aes-192-cbc'
const password = 'Senha usada para gerar a chave'

// Primeiro, vamos gerar a chave. O comprimento da chave depende do algoritmo.
// Neste caso para aes192, é 24 bytes (192 bits).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err
  // Então, vamos gerar um vetor de inicialização aleatório
  randomFill(new Uint8Array(16), (err, iv) => {
    if (err) throw err

    // Assim que tivermos a chave e o iv, podemos criar e usar a cifra...
    const cipher = createCipheriv(algorithm, key, iv)

    let encrypted = ''
    cipher.setEncoding('hex')

    cipher.on('data', chunk => (encrypted += chunk))
    cipher.on('end', () => console.log(encrypted))

    cipher.write('alguns dados de texto claro')
    cipher.end()
  })
})

Exemplo: Usando Cipher e streams encadeados:

js
import { createReadStream, createWriteStream } from 'node:fs'

import { pipeline } from 'node:stream'

const { scrypt, randomFill, createCipheriv } = await import('node:crypto')

const algorithm = 'aes-192-cbc'
const password = 'Senha usada para gerar a chave'

// Primeiro, vamos gerar a chave. O comprimento da chave depende do algoritmo.
// Neste caso para aes192, é 24 bytes (192 bits).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err
  // Então, vamos gerar um vetor de inicialização aleatório
  randomFill(new Uint8Array(16), (err, iv) => {
    if (err) throw err

    const cipher = createCipheriv(algorithm, key, iv)

    const input = createReadStream('test.js')
    const output = createWriteStream('test.enc')

    pipeline(input, cipher, output, err => {
      if (err) throw err
    })
  })
})
js
const { createReadStream, createWriteStream } = require('node:fs')

const { pipeline } = require('node:stream')

const { scrypt, randomFill, createCipheriv } = require('node:crypto')

const algorithm = 'aes-192-cbc'
const password = 'Senha usada para gerar a chave'

// Primeiro, vamos gerar a chave. O comprimento da chave depende do algoritmo.
// Neste caso para aes192, é 24 bytes (192 bits).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err
  // Então, vamos gerar um vetor de inicialização aleatório
  randomFill(new Uint8Array(16), (err, iv) => {
    if (err) throw err

    const cipher = createCipheriv(algorithm, key, iv)

    const input = createReadStream('test.js')
    const output = createWriteStream('test.enc')

    pipeline(input, cipher, output, err => {
      if (err) throw err
    })
  })
})

Exemplo: Usando os métodos cipher.update() e cipher.final():

js
const { scrypt, randomFill, createCipheriv } = await import('node:crypto')

const algorithm = 'aes-192-cbc'
const password = 'Senha usada para gerar a chave'

// Primeiro, vamos gerar a chave. O comprimento da chave depende do algoritmo.
// Neste caso para aes192, é 24 bytes (192 bits).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err
  // Então, vamos gerar um vetor de inicialização aleatório
  randomFill(new Uint8Array(16), (err, iv) => {
    if (err) throw err

    const cipher = createCipheriv(algorithm, key, iv)

    let encrypted = cipher.update('alguns dados de texto claro', 'utf8', 'hex')
    encrypted += cipher.final('hex')
    console.log(encrypted)
  })
})
js
const { scrypt, randomFill, createCipheriv } = require('node:crypto')

const algorithm = 'aes-192-cbc'
const password = 'Senha usada para gerar a chave'

// Primeiro, vamos gerar a chave. O comprimento da chave depende do algoritmo.
// Neste caso para aes192, é 24 bytes (192 bits).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err
  // Então, vamos gerar um vetor de inicialização aleatório
  randomFill(new Uint8Array(16), (err, iv) => {
    if (err) throw err

    const cipher = createCipheriv(algorithm, key, iv)

    let encrypted = cipher.update('alguns dados de texto claro', 'utf8', 'hex')
    encrypted += cipher.final('hex')
    console.log(encrypted)
  })
})

cipher.final([outputEncoding]) ​

Adicionado em: v0.1.94

  • outputEncoding <string> A codificação do valor de retorno.
  • Retorna: <Buffer> | <string> Quaisquer conteúdos cifrados restantes. Se outputEncoding for especificado, uma string é retornada. Se um outputEncoding não for fornecido, um Buffer é retornado.

Depois que o método cipher.final() for chamado, o objeto Cipher não poderá mais ser usado para criptografar dados. Tentativas de chamar cipher.final() mais de uma vez resultarão no lançamento de um erro.

cipher.getAuthTag() ​

Adicionado em: v1.0.0

  • Retorna: <Buffer> Ao usar um modo de criptografia autenticado (GCM, CCM, OCB e chacha20-poly1305 são suportados atualmente), o método cipher.getAuthTag() retorna um Buffer contendo a tag de autenticação que foi calculada a partir dos dados fornecidos.

O método cipher.getAuthTag() deve ser chamado somente após a conclusão da criptografia usando o método cipher.final().

Se a opção authTagLength foi definida durante a criação da instância cipher, essa função retornará exatamente authTagLength bytes.

cipher.setAAD(buffer[, options]) ​

Adicionado em: v1.0.0

Ao usar um modo de criptografia autenticado (GCM, CCM, OCB e chacha20-poly1305 são suportados atualmente), o método cipher.setAAD() define o valor usado para o parâmetro de entrada dados adicionais autenticados (AAD).

A opção plaintextLength é opcional para GCM e OCB. Ao usar CCM, a opção plaintextLength deve ser especificada e seu valor deve corresponder ao comprimento do texto não criptografado em bytes. Consulte modo CCM.

O método cipher.setAAD() deve ser chamado antes de cipher.update().

cipher.setAutoPadding([autoPadding]) ​

Adicionado em: v0.7.1

  • autoPadding <boolean> Padrão: true
  • Retorna: <Cipher> A mesma instância Cipher para encadeamento de métodos.

Ao usar algoritmos de criptografia de bloco, a classe Cipher adicionará automaticamente padding aos dados de entrada para o tamanho de bloco apropriado. Para desativar o padding padrão, chame cipher.setAutoPadding(false).

Quando autoPadding é false, o comprimento de todos os dados de entrada deve ser um múltiplo do tamanho de bloco da cifra ou cipher.final() lançará um erro. Desativar o padding automático é útil para padding não padrão, por exemplo, usar 0x0 em vez de padding PKCS.

O método cipher.setAutoPadding() deve ser chamado antes de cipher.final().

cipher.update(data[, inputEncoding][, outputEncoding]) ​

[Histórico]

VersãoMudanças
v6.0.0O inputEncoding padrão mudou de binary para utf8.
v0.1.94Adicionado em: v0.1.94

Atualiza a cifra com data. Se o argumento inputEncoding for fornecido, o argumento data é uma string usando a codificação especificada. Se o argumento inputEncoding não for fornecido, data deve ser um Buffer, TypedArray ou DataView. Se data for um Buffer, TypedArray ou DataView, então inputEncoding será ignorado.

O outputEncoding especifica o formato de saída dos dados cifrados. Se o outputEncoding for especificado, uma string usando a codificação especificada é retornada. Se nenhum outputEncoding for fornecido, um Buffer é retornado.

O método cipher.update() pode ser chamado várias vezes com novos dados até que cipher.final() seja chamado. Chamar cipher.update() depois de cipher.final() resultará em um erro sendo lançado.

Classe: Decipher ​

Adicionado em: v0.1.94

Instâncias da classe Decipher são usadas para descriptografar dados. A classe pode ser usada de duas maneiras:

  • Como um stream que é tanto legível quanto gravável, onde dados criptografados simples são gravados para produzir dados não criptografados no lado legível, ou
  • Usando os métodos decipher.update() e decipher.final() para produzir os dados não criptografados.

O método crypto.createDecipheriv() é usado para criar instâncias de Decipher. Objetos Decipher não devem ser criados diretamente usando a palavra-chave new.

Exemplo: Usando objetos Decipher como streams:

js
import { Buffer } from 'node:buffer'
const { scryptSync, createDecipheriv } = await import('node:crypto')

const algorithm = 'aes-192-cbc'
const password = 'Senha usada para gerar a chave'
// O tamanho da chave depende do algoritmo. Neste caso, para aes192, é
// 24 bytes (192 bits).
// Use o `crypto.scrypt()` assíncrono em vez disso.
const key = scryptSync(password, 'salt', 24)
// O IV é geralmente passado junto com o texto cifrado.
const iv = Buffer.alloc(16, 0) // Vetor de inicialização.

const decipher = createDecipheriv(algorithm, key, iv)

let decrypted = ''
decipher.on('readable', () => {
  let chunk
  while (null !== (chunk = decipher.read())) {
    decrypted += chunk.toString('utf8')
  }
})
decipher.on('end', () => {
  console.log(decrypted)
  // Imprime: alguns dados de texto claro
})

// Criptografado com o mesmo algoritmo, chave e iv.
const encrypted = 'e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa'
decipher.write(encrypted, 'hex')
decipher.end()
js
const { scryptSync, createDecipheriv } = require('node:crypto')
const { Buffer } = require('node:buffer')

const algorithm = 'aes-192-cbc'
const password = 'Senha usada para gerar a chave'
// O tamanho da chave depende do algoritmo. Neste caso, para aes192, é
// 24 bytes (192 bits).
// Use o `crypto.scrypt()` assíncrono em vez disso.
const key = scryptSync(password, 'salt', 24)
// O IV é geralmente passado junto com o texto cifrado.
const iv = Buffer.alloc(16, 0) // Vetor de inicialização.

const decipher = createDecipheriv(algorithm, key, iv)

let decrypted = ''
decipher.on('readable', () => {
  let chunk
  while (null !== (chunk = decipher.read())) {
    decrypted += chunk.toString('utf8')
  }
})
decipher.on('end', () => {
  console.log(decrypted)
  // Imprime: alguns dados de texto claro
})

// Criptografado com o mesmo algoritmo, chave e iv.
const encrypted = 'e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa'
decipher.write(encrypted, 'hex')
decipher.end()

Exemplo: Usando Decipher e streams encadeados:

js
import { createReadStream, createWriteStream } from 'node:fs'
import { Buffer } from 'node:buffer'
const { scryptSync, createDecipheriv } = await import('node:crypto')

const algorithm = 'aes-192-cbc'
const password = 'Senha usada para gerar a chave'
// Use o `crypto.scrypt()` assíncrono em vez disso.
const key = scryptSync(password, 'salt', 24)
// O IV é geralmente passado junto com o texto cifrado.
const iv = Buffer.alloc(16, 0) // Vetor de inicialização.

const decipher = createDecipheriv(algorithm, key, iv)

const input = createReadStream('test.enc')
const output = createWriteStream('test.js')

input.pipe(decipher).pipe(output)
js
const { createReadStream, createWriteStream } = require('node:fs')
const { scryptSync, createDecipheriv } = require('node:crypto')
const { Buffer } = require('node:buffer')

const algorithm = 'aes-192-cbc'
const password = 'Senha usada para gerar a chave'
// Use o `crypto.scrypt()` assíncrono em vez disso.
const key = scryptSync(password, 'salt', 24)
// O IV é geralmente passado junto com o texto cifrado.
const iv = Buffer.alloc(16, 0) // Vetor de inicialização.

const decipher = createDecipheriv(algorithm, key, iv)

const input = createReadStream('test.enc')
const output = createWriteStream('test.js')

input.pipe(decipher).pipe(output)

Exemplo: Usando os métodos decipher.update() e decipher.final():

js
import { Buffer } from 'node:buffer'
const { scryptSync, createDecipheriv } = await import('node:crypto')

const algorithm = 'aes-192-cbc'
const password = 'Senha usada para gerar a chave'
// Use o `crypto.scrypt()` assíncrono em vez disso.
const key = scryptSync(password, 'salt', 24)
// O IV é geralmente passado junto com o texto cifrado.
const iv = Buffer.alloc(16, 0) // Vetor de inicialização.

const decipher = createDecipheriv(algorithm, key, iv)

// Criptografado usando o mesmo algoritmo, chave e iv.
const encrypted = 'e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa'
let decrypted = decipher.update(encrypted, 'hex', 'utf8')
decrypted += decipher.final('utf8')
console.log(decrypted)
// Imprime: alguns dados de texto claro
js
const { scryptSync, createDecipheriv } = require('node:crypto')
const { Buffer } = require('node:buffer')

const algorithm = 'aes-192-cbc'
const password = 'Senha usada para gerar a chave'
// Use o `crypto.scrypt()` assíncrono em vez disso.
const key = scryptSync(password, 'salt', 24)
// O IV é geralmente passado junto com o texto cifrado.
const iv = Buffer.alloc(16, 0) // Vetor de inicialização.

const decipher = createDecipheriv(algorithm, key, iv)

// Criptografado usando o mesmo algoritmo, chave e iv.
const encrypted = 'e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa'
let decrypted = decipher.update(encrypted, 'hex', 'utf8')
decrypted += decipher.final('utf8')
console.log(decrypted)
// Imprime: alguns dados de texto claro

decipher.final([outputEncoding]) ​

Adicionado em: v0.1.94

  • outputEncoding <string> A codificação do valor de retorno.
  • Retorna: <Buffer> | <string> Quaisquer conteúdos decifrados restantes. Se outputEncoding for especificado, uma string é retornada. Se um outputEncoding não for fornecido, um Buffer é retornado.

Depois que o método decipher.final() for chamado, o objeto Decipher não poderá mais ser usado para descriptografar dados. Tentativas de chamar decipher.final() mais de uma vez resultarão em um erro sendo lançado.

decipher.setAAD(buffer[, options]) ​

[Histórico]

VersãoMudanças
v15.0.0O argumento do buffer pode ser uma string ou ArrayBuffer e é limitado a no máximo 2 ** 31 - 1 bytes.
v7.2.0Este método agora retorna uma referência para decipher.
v1.0.0Adicionado em: v1.0.0

Ao usar um modo de criptografia autenticado (atualmente, GCM, CCM, OCB e chacha20-poly1305 são suportados), o método decipher.setAAD() define o valor usado para o parâmetro de entrada dados adicionais autenticados (AAD).

O argumento options é opcional para GCM. Ao usar CCM, a opção plaintextLength deve ser especificada e seu valor deve corresponder ao comprimento do texto cifrado em bytes. Consulte modo CCM.

O método decipher.setAAD() deve ser chamado antes de decipher.update().

Ao passar uma string como buffer, considere ressalvas ao usar strings como entradas para APIs criptográficas.

decipher.setAuthTag(buffer[, encoding]) ​

[Histórico]

VersãoMudanças
v22.0.0, v20.13.0Usar comprimentos de tag GCM diferentes de 128 bits sem especificar a opção authTagLength ao criar decipher está obsoleto.
v15.0.0O argumento buffer pode ser uma string ou ArrayBuffer e é limitado a no máximo 2 ** 31 - 1 bytes.
v11.0.0Este método agora lança um erro se o comprimento da tag GCM for inválido.
v7.2.0Este método agora retorna uma referência a decipher.
v1.0.0Adicionado em: v1.0.0

Ao usar um modo de criptografia autenticado (GCM, CCM, OCB e chacha20-poly1305 são atualmente suportados), o método decipher.setAuthTag() é usado para passar a tag de autenticação recebida. Se nenhuma tag for fornecida, ou se o texto cifrado tiver sido adulterado, decipher.final() lançará um erro, indicando que o texto cifrado deve ser descartado devido à falha na autenticação. Se o comprimento da tag for inválido de acordo com NIST SP 800-38D ou não corresponder ao valor da opção authTagLength, decipher.setAuthTag() lançará um erro.

O método decipher.setAuthTag() deve ser chamado antes de decipher.update() para o modo CCM ou antes de decipher.final() para os modos GCM e OCB e chacha20-poly1305. decipher.setAuthTag() só pode ser chamado uma vez.

Ao passar uma string como tag de autenticação, considere as advertências ao usar strings como entradas para APIs criptográficas.

decipher.setAutoPadding([autoPadding]) ​

Adicionado em: v0.7.1

  • autoPadding <boolean> Padrão: true
  • Retorna: <Decipher> O mesmo Decipher para encadeamento de métodos.

Quando os dados são criptografados sem preenchimento de bloco padrão, chamar decipher.setAutoPadding(false) desativará o preenchimento automático para impedir que decipher.final() verifique e remova o preenchimento.

Desligar o preenchimento automático só funcionará se o comprimento dos dados de entrada for um múltiplo do tamanho do bloco de cifras.

O método decipher.setAutoPadding() deve ser chamado antes de decipher.final().

decipher.update(data[, inputEncoding][, outputEncoding]) ​

[Histórico]

VersãoAlterações
v6.0.0O inputEncoding padrão mudou de binary para utf8.
v0.1.94Adicionado em: v0.1.94

Atualiza o decifrador com data. Se o argumento inputEncoding for fornecido, o argumento data é uma string usando a codificação especificada. Se o argumento inputEncoding não for fornecido, data deve ser um Buffer. Se data for um Buffer, então inputEncoding é ignorado.

O outputEncoding especifica o formato de saída dos dados decifrados. Se o outputEncoding for especificado, uma string usando a codificação especificada é retornada. Se nenhum outputEncoding for fornecido, um Buffer é retornado.

O método decipher.update() pode ser chamado várias vezes com novos dados até que decipher.final() seja chamado. Chamar decipher.update() depois de decipher.final() resultará em um erro sendo lançado.

Mesmo que a cifra subjacente implemente autenticação, a autenticidade e a integridade do texto simples retornado desta função podem ser incertas neste momento. Para algoritmos de criptografia autenticada, a autenticidade geralmente é estabelecida apenas quando o aplicativo chama decipher.final().

Classe: DiffieHellman ​

Adicionado em: v0.5.0

A classe DiffieHellman é uma utilidade para criar trocas de chaves Diffie-Hellman.

Instâncias da classe DiffieHellman podem ser criadas usando a função crypto.createDiffieHellman().

js
import assert from 'node:assert'

const { createDiffieHellman } = await import('node:crypto')

// Gera as chaves da Alice...
const alice = createDiffieHellman(2048)
const aliceKey = alice.generateKeys()

// Gera as chaves do Bob...
const bob = createDiffieHellman(alice.getPrime(), alice.getGenerator())
const bobKey = bob.generateKeys()

// Troca e gera o segredo...
const aliceSecret = alice.computeSecret(bobKey)
const bobSecret = bob.computeSecret(aliceKey)

// OK
assert.strictEqual(aliceSecret.toString('hex'), bobSecret.toString('hex'))
js
const assert = require('node:assert')

const { createDiffieHellman } = require('node:crypto')

// Gera as chaves da Alice...
const alice = createDiffieHellman(2048)
const aliceKey = alice.generateKeys()

// Gera as chaves do Bob...
const bob = createDiffieHellman(alice.getPrime(), alice.getGenerator())
const bobKey = bob.generateKeys()

// Troca e gera o segredo...
const aliceSecret = alice.computeSecret(bobKey)
const bobSecret = bob.computeSecret(aliceKey)

// OK
assert.strictEqual(aliceSecret.toString('hex'), bobSecret.toString('hex'))

diffieHellman.computeSecret(otherPublicKey[, inputEncoding][, outputEncoding]) ​

Adicionado em: v0.5.0

Calcula o segredo compartilhado usando otherPublicKey como a chave pública da outra parte e retorna o segredo compartilhado calculado. A chave fornecida é interpretada usando a inputEncoding especificada, e o segredo é codificado usando a outputEncoding especificada. Se a inputEncoding não for fornecida, espera-se que otherPublicKey seja um Buffer, TypedArray ou DataView.

Se outputEncoding receber uma string, uma string será retornada; caso contrário, um Buffer será retornado.

diffieHellman.generateKeys([encoding]) ​

Adicionado em: v0.5.0

Gera valores de chave Diffie-Hellman privada e pública, a menos que já tenham sido gerados ou calculados, e retorna a chave pública na codificação especificada. Esta chave deve ser transferida para a outra parte. Se encoding for fornecido, uma string é retornada; caso contrário, um Buffer é retornado.

Esta função é um wrapper fino em torno de DH_generate_key(). Em particular, depois que uma chave privada é gerada ou definida, chamar esta função apenas atualiza a chave pública, mas não gera uma nova chave privada.

diffieHellman.getGenerator([encoding]) ​

Adicionado em: v0.5.0

Retorna o gerador Diffie-Hellman na codificação especificada. Se encoding for fornecido, uma string é retornada; caso contrário, um Buffer é retornado.

diffieHellman.getPrime([encoding]) ​

Adicionado em: v0.5.0

Retorna o primo Diffie-Hellman na codificação especificada. Se encoding for fornecido, uma string é retornada; caso contrário, um Buffer é retornado.

diffieHellman.getPrivateKey([encoding]) ​

Adicionado em: v0.5.0

Retorna a chave privada Diffie-Hellman na codificação especificada. Se encoding for fornecido, uma string será retornada; caso contrário, um Buffer é retornado.

diffieHellman.getPublicKey([encoding]) ​

Adicionado em: v0.5.0

Retorna a chave pública Diffie-Hellman na codificação especificada. Se encoding for fornecido, uma string será retornada; caso contrário, um Buffer é retornado.

diffieHellman.setPrivateKey(privateKey[, encoding]) ​

Adicionado em: v0.5.0

Define a chave privada Diffie-Hellman. Se o argumento encoding for fornecido, espera-se que privateKey seja uma string. Se nenhum encoding for fornecido, espera-se que privateKey seja um Buffer, TypedArray ou DataView.

Esta função não calcula automaticamente a chave pública associada. diffieHellman.setPublicKey() ou diffieHellman.generateKeys() podem ser usados para fornecer manualmente a chave pública ou para derivá-la automaticamente.

diffieHellman.setPublicKey(publicKey[, encoding]) ​

Adicionado em: v0.5.0

Define a chave pública Diffie-Hellman. Se o argumento encoding for fornecido, espera-se que publicKey seja uma string. Se nenhum encoding for fornecido, espera-se que publicKey seja um Buffer, TypedArray ou DataView.

diffieHellman.verifyError ​

Adicionado em: v0.11.12

Um campo de bits contendo quaisquer avisos e/ou erros resultantes de uma verificação realizada durante a inicialização do objeto DiffieHellman.

Os seguintes valores são válidos para esta propriedade (conforme definido no módulo node:constants):

  • DH_CHECK_P_NOT_SAFE_PRIME
  • DH_CHECK_P_NOT_PRIME
  • DH_UNABLE_TO_CHECK_GENERATOR
  • DH_NOT_SUITABLE_GENERATOR

Classe: DiffieHellmanGroup ​

Adicionado em: v0.7.5

A classe DiffieHellmanGroup recebe um grupo modp conhecido como seu argumento. Ele funciona da mesma forma que DiffieHellman, exceto que não permite alterar suas chaves após a criação. Em outras palavras, ele não implementa os métodos setPublicKey() ou setPrivateKey().

js
const { createDiffieHellmanGroup } = await import('node:crypto')
const dh = createDiffieHellmanGroup('modp16')
js
const { createDiffieHellmanGroup } = require('node:crypto')
const dh = createDiffieHellmanGroup('modp16')

Os seguintes grupos são suportados:

  • 'modp14' (2048 bits, RFC 3526 Seção 3)
  • 'modp15' (3072 bits, RFC 3526 Seção 4)
  • 'modp16' (4096 bits, RFC 3526 Seção 5)
  • 'modp17' (6144 bits, RFC 3526 Seção 6)
  • 'modp18' (8192 bits, RFC 3526 Seção 7)

Os seguintes grupos ainda são suportados, mas estão obsoletos (consulte Advertências):

  • 'modp1' (768 bits, RFC 2409 Seção 6.1)
  • 'modp2' (1024 bits, RFC 2409 Seção 6.2)
  • 'modp5' (1536 bits, RFC 3526 Seção 2)

Esses grupos obsoletos podem ser removidos em futuras versões do Node.js.

Classe: ECDH ​

Adicionado em: v0.11.14

A classe ECDH é uma utilidade para criar trocas de chaves Elliptic Curve Diffie-Hellman (ECDH).

Instâncias da classe ECDH podem ser criadas usando a função crypto.createECDH().

js
import assert from 'node:assert'

const { createECDH } = await import('node:crypto')

// Gerar as chaves de Alice...
const alice = createECDH('secp521r1')
const aliceKey = alice.generateKeys()

// Gerar as chaves de Bob...
const bob = createECDH('secp521r1')
const bobKey = bob.generateKeys()

// Trocar e gerar o segredo...
const aliceSecret = alice.computeSecret(bobKey)
const bobSecret = bob.computeSecret(aliceKey)

assert.strictEqual(aliceSecret.toString('hex'), bobSecret.toString('hex'))
// OK
js
const assert = require('node:assert')

const { createECDH } = require('node:crypto')

// Gerar as chaves de Alice...
const alice = createECDH('secp521r1')
const aliceKey = alice.generateKeys()

// Gerar as chaves de Bob...
const bob = createECDH('secp521r1')
const bobKey = bob.generateKeys()

// Trocar e gerar o segredo...
const aliceSecret = alice.computeSecret(bobKey)
const bobSecret = bob.computeSecret(aliceKey)

assert.strictEqual(aliceSecret.toString('hex'), bobSecret.toString('hex'))
// OK

Método estático: ECDH.convertKey(key, curve[, inputEncoding[, outputEncoding[, format]]]) ​

Adicionado em: v10.0.0

Converte a chave pública EC Diffie-Hellman especificada por key e curve para o formato especificado por format. O argumento format especifica a codificação do ponto e pode ser 'compressed', 'uncompressed' ou 'hybrid'. A chave fornecida é interpretada usando o inputEncoding especificado, e a chave retornada é codificada usando o outputEncoding especificado.

Use crypto.getCurves() para obter uma lista dos nomes de curvas disponíveis. Em versões recentes do OpenSSL, openssl ecparam -list_curves também exibirá o nome e a descrição de cada curva elíptica disponível.

Se format não for especificado, o ponto será retornado no formato 'uncompressed'.

Se o inputEncoding não for fornecido, espera-se que key seja um Buffer, TypedArray ou DataView.

Exemplo (descompactando uma chave):

js
const { createECDH, ECDH } = await import('node:crypto')

const ecdh = createECDH('secp256k1')
ecdh.generateKeys()

const compressedKey = ecdh.getPublicKey('hex', 'compressed')

const uncompressedKey = ECDH.convertKey(compressedKey, 'secp256k1', 'hex', 'hex', 'uncompressed')

// A chave convertida e a chave pública descompactada devem ser iguais
console.log(uncompressedKey === ecdh.getPublicKey('hex'))
js
const { createECDH, ECDH } = require('node:crypto')

const ecdh = createECDH('secp256k1')
ecdh.generateKeys()

const compressedKey = ecdh.getPublicKey('hex', 'compressed')

const uncompressedKey = ECDH.convertKey(compressedKey, 'secp256k1', 'hex', 'hex', 'uncompressed')

// A chave convertida e a chave pública descompactada devem ser iguais
console.log(uncompressedKey === ecdh.getPublicKey('hex'))

ecdh.computeSecret(otherPublicKey[, inputEncoding][, outputEncoding]) ​

[Histórico]

VersãoMudanças
v10.0.0Formato de erro alterado para melhor suportar erro de chave pública inválida.
v6.0.0O inputEncoding padrão foi alterado de binary para utf8.
v0.11.14Adicionado em: v0.11.14

Calcula o segredo compartilhado usando otherPublicKey como a chave pública da outra parte e retorna o segredo compartilhado calculado. A chave fornecida é interpretada usando inputEncoding especificado, e o segredo retornado é codificado usando o outputEncoding especificado. Se o inputEncoding não for fornecido, espera-se que otherPublicKey seja um Buffer, TypedArray ou DataView.

Se outputEncoding receber uma string, uma string será retornada; caso contrário, um Buffer é retornado.

ecdh.computeSecret lançará um erro ERR_CRYPTO_ECDH_INVALID_PUBLIC_KEY quando otherPublicKey estiver fora da curva elíptica. Como otherPublicKey é geralmente fornecido por um usuário remoto em uma rede não segura, certifique-se de lidar com essa exceção adequadamente.

ecdh.generateKeys([encoding[, format]]) ​

Adicionado em: v0.11.14

Gera valores de chave privada e pública EC Diffie-Hellman e retorna a chave pública no format e encoding especificados. Esta chave deve ser transferida para a outra parte.

O argumento format especifica a codificação de ponto e pode ser 'compressed' ou 'uncompressed'. Se format não for especificado, o ponto será retornado no formato 'uncompressed'.

Se encoding for fornecido, uma string é retornada; caso contrário, um Buffer é retornado.

ecdh.getPrivateKey([encoding]) ​

Adicionado em: v0.11.14

Se encoding for especificado, uma string será retornada; caso contrário, um Buffer será retornado.

ecdh.getPublicKey([encoding][, format]) ​

Adicionado em: v0.11.14

O argumento format especifica a codificação de ponto e pode ser 'compressed' ou 'uncompressed'. Se format não for especificado, o ponto será retornado no formato 'uncompressed'.

Se encoding for especificado, uma string será retornada; caso contrário, um Buffer será retornado.

ecdh.setPrivateKey(privateKey[, encoding]) ​

Adicionado em: v0.11.14

Define a chave privada EC Diffie-Hellman. Se encoding for fornecido, espera-se que privateKey seja uma string; caso contrário, espera-se que privateKey seja um Buffer, TypedArray ou DataView.

Se privateKey não for válida para a curva especificada quando o objeto ECDH foi criado, um erro será lançado. Ao definir a chave privada, o ponto público (chave) associado também é gerado e definido no objeto ECDH.

ecdh.setPublicKey(publicKey[, encoding]) ​

Adicionado em: v0.11.14

Obsoleto desde: v5.2.0

[Estável: 0 - Obsoleto]

Estável: 0 Estabilidade: 0 - Obsoleto

Define a chave pública EC Diffie-Hellman. Se encoding for fornecido, espera-se que publicKey seja uma string; caso contrário, espera-se um Buffer, TypedArray ou DataView.

Normalmente, não há razão para chamar este método, porque ECDH requer apenas uma chave privada e a chave pública da outra parte para calcular o segredo compartilhado. Normalmente, ecdh.generateKeys() ou ecdh.setPrivateKey() serão chamados. O método ecdh.setPrivateKey() tenta gerar o ponto/chave pública associada à chave privada que está sendo definida.

Exemplo (obtendo um segredo compartilhado):

js
const { createECDH, createHash } = await import('node:crypto')

const alice = createECDH('secp256k1')
const bob = createECDH('secp256k1')

// Esta é uma forma abreviada de especificar uma das chaves privadas
// anteriores de Alice. Não seria sensato usar uma chave privada tão
// previsível em uma aplicação real.
alice.setPrivateKey(createHash('sha256').update('alice', 'utf8').digest())

// Bob usa um novo par de chaves pseudorrandômicas criptograficamente
// forte
bob.generateKeys()

const aliceSecret = alice.computeSecret(bob.getPublicKey(), null, 'hex')
const bobSecret = bob.computeSecret(alice.getPublicKey(), null, 'hex')

// aliceSecret e bobSecret devem ser o mesmo valor secreto compartilhado
console.log(aliceSecret === bobSecret)
js
const { createECDH, createHash } = require('node:crypto')

const alice = createECDH('secp256k1')
const bob = createECDH('secp256k1')

// Esta é uma forma abreviada de especificar uma das chaves privadas
// anteriores de Alice. Não seria sensato usar uma chave privada tão
// previsível em uma aplicação real.
alice.setPrivateKey(createHash('sha256').update('alice', 'utf8').digest())

// Bob usa um novo par de chaves pseudorrandômicas criptograficamente
// forte
bob.generateKeys()

const aliceSecret = alice.computeSecret(bob.getPublicKey(), null, 'hex')
const bobSecret = bob.computeSecret(alice.getPublicKey(), null, 'hex')

// aliceSecret e bobSecret devem ser o mesmo valor secreto compartilhado
console.log(aliceSecret === bobSecret)

Classe: Hash ​

Adicionado em: v0.1.92

A classe Hash é uma utilidade para criar resumos de hash de dados. Ela pode ser usada de duas maneiras:

  • Como um stream que é tanto legível quanto gravável, onde os dados são gravados para produzir um resumo de hash computado no lado legível, ou
  • Usando os métodos hash.update() e hash.digest() para produzir o hash computado.

O método crypto.createHash() é usado para criar instâncias de Hash. Objetos Hash não devem ser criados diretamente usando a palavra-chave new.

Exemplo: Usando objetos Hash como streams:

js
const { createHash } = await import('node:crypto')

const hash = createHash('sha256')

hash.on('readable', () => {
  // Apenas um elemento será produzido pelo
  // stream de hash.
  const data = hash.read()
  if (data) {
    console.log(data.toString('hex'))
    // Imprime:
    //   6a2da20943931e9834fc12cfe5bb47bbd9ae43489a30726962b576f4e3993e50
  }
})

hash.write('some data to hash')
hash.end()
js
const { createHash } = require('node:crypto')

const hash = createHash('sha256')

hash.on('readable', () => {
  // Apenas um elemento será produzido pelo
  // stream de hash.
  const data = hash.read()
  if (data) {
    console.log(data.toString('hex'))
    // Imprime:
    //   6a2da20943931e9834fc12cfe5bb47bbd9ae43489a30726962b576f4e3993e50
  }
})

hash.write('some data to hash')
hash.end()

Exemplo: Usando Hash e streams encadeados:

js
import { createReadStream } from 'node:fs'
import { stdout } from 'node:process'
const { createHash } = await import('node:crypto')

const hash = createHash('sha256')

const input = createReadStream('test.js')
input.pipe(hash).setEncoding('hex').pipe(stdout)
js
const { createReadStream } = require('node:fs')
const { createHash } = require('node:crypto')
const { stdout } = require('node:process')

const hash = createHash('sha256')

const input = createReadStream('test.js')
input.pipe(hash).setEncoding('hex').pipe(stdout)

Exemplo: Usando os métodos hash.update() e hash.digest():

js
const { createHash } = await import('node:crypto')

const hash = createHash('sha256')

hash.update('some data to hash')
console.log(hash.digest('hex'))
// Imprime:
//   6a2da20943931e9834fc12cfe5bb47bbd9ae43489a30726962b576f4e3993e50
js
const { createHash } = require('node:crypto')

const hash = createHash('sha256')

hash.update('some data to hash')
console.log(hash.digest('hex'))
// Imprime:
//   6a2da20943931e9834fc12cfe5bb47bbd9ae43489a30726962b576f4e3993e50

hash.copy([options]) ​

Adicionado em: v13.1.0

Cria um novo objeto Hash que contém uma cópia profunda do estado interno do objeto Hash atual.

O argumento opcional options controla o comportamento do fluxo. Para funções de hash XOF como 'shake256', a opção outputLength pode ser usada para especificar o tamanho de saída desejado em bytes.

Um erro é lançado quando uma tentativa é feita para copiar o objeto Hash depois que seu método hash.digest() foi chamado.

js
// Calcular um hash rotativo.
const { createHash } = await import('node:crypto')

const hash = createHash('sha256')

hash.update('one')
console.log(hash.copy().digest('hex'))

hash.update('two')
console.log(hash.copy().digest('hex'))

hash.update('three')
console.log(hash.copy().digest('hex'))

// Etc.
js
// Calcular um hash rotativo.
const { createHash } = require('node:crypto')

const hash = createHash('sha256')

hash.update('one')
console.log(hash.copy().digest('hex'))

hash.update('two')
console.log(hash.copy().digest('hex'))

hash.update('three')
console.log(hash.copy().digest('hex'))

// Etc.

hash.digest([encoding]) ​

Adicionado em: v0.1.92

Calcula o resumo de todos os dados passados para serem hash (usando o método hash.update()). Se encoding for fornecido, uma string será retornada; caso contrário, um Buffer é retornado.

O objeto Hash não pode ser usado novamente depois que o método hash.digest() foi chamado. Várias chamadas farão com que um erro seja lançado.

hash.update(data[, inputEncoding]) ​

[Histórico]

VersãoMudanças
v6.0.0O inputEncoding padrão mudou de binary para utf8.
v0.1.92Adicionado em: v0.1.92

Atualiza o conteúdo do hash com o data fornecido, cuja codificação é fornecida em inputEncoding. Se encoding não for fornecido, e o data for uma string, uma codificação de 'utf8' é aplicada. Se data for um Buffer, TypedArray ou DataView, então inputEncoding é ignorado.

Isso pode ser chamado várias vezes com novos dados, pois ele é transmitido.

Classe: Hmac ​

Adicionado em: v0.1.94

A classe Hmac é uma utilidade para criar resumos HMAC criptográficos. Ele pode ser usado de duas maneiras:

  • Como um stream que é legível e gravável, onde os dados são escritos para produzir um resumo HMAC calculado no lado legível, ou
  • Usando os métodos hmac.update() e hmac.digest() para produzir o resumo HMAC calculado.

O método crypto.createHmac() é usado para criar instâncias de Hmac. Objetos Hmac não devem ser criados diretamente usando a palavra-chave new.

Exemplo: Usando objetos Hmac como streams:

js
const { createHmac } = await import('node:crypto')

const hmac = createHmac('sha256', 'a secret')

hmac.on('readable', () => {
  // Apenas um elemento será produzido pelo
  // fluxo de hash.
  const data = hmac.read()
  if (data) {
    console.log(data.toString('hex'))
    // Imprime:
    //   7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f77e
  }
})

hmac.write('alguns dados para hash')
hmac.end()
js
const { createHmac } = require('node:crypto')

const hmac = createHmac('sha256', 'a secret')

hmac.on('readable', () => {
  // Apenas um elemento será produzido pelo
  // fluxo de hash.
  const data = hmac.read()
  if (data) {
    console.log(data.toString('hex'))
    // Imprime:
    //   7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f77e
  }
})

hmac.write('alguns dados para hash')
hmac.end()

Exemplo: Usando Hmac e streams encadeados:

js
import { createReadStream } from 'node:fs'
import { stdout } from 'node:process'
const { createHmac } = await import('node:crypto')

const hmac = createHmac('sha256', 'a secret')

const input = createReadStream('test.js')
input.pipe(hmac).pipe(stdout)
js
const { createReadStream } = require('node:fs')
const { createHmac } = require('node:crypto')
const { stdout } = require('node:process')

const hmac = createHmac('sha256', 'a secret')

const input = createReadStream('test.js')
input.pipe(hmac).pipe(stdout)

Exemplo: Usando os métodos hmac.update() e hmac.digest():

js
const { createHmac } = await import('node:crypto')

const hmac = createHmac('sha256', 'a secret')

hmac.update('alguns dados para hash')
console.log(hmac.digest('hex'))
// Imprime:
//   7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f77e
js
const { createHmac } = require('node:crypto')

const hmac = createHmac('sha256', 'a secret')

hmac.update('alguns dados para hash')
console.log(hmac.digest('hex'))
// Imprime:
//   7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f77e

hmac.digest([encoding]) ​

Adicionado em: v0.1.94

Calcula o resumo HMAC de todos os dados passados usando hmac.update(). Se encoding for fornecida, uma string será retornada; caso contrário, um Buffer é retornado;

O objeto Hmac não pode ser usado novamente após hmac.digest() ter sido chamado. Várias chamadas para hmac.digest() resultarão em um erro sendo lançado.

hmac.update(data[, inputEncoding]) ​

[Histórico]

VersãoMudanças
v6.0.0A inputEncoding padrão mudou de binary para utf8.
v0.1.94Adicionado em: v0.1.94

Atualiza o conteúdo Hmac com os dados fornecidos em data, cuja codificação é fornecida em inputEncoding. Se encoding não for fornecida e os data forem uma string, uma codificação de 'utf8' será imposta. Se data for um Buffer, TypedArray ou DataView, inputEncoding será ignorado.

Isso pode ser chamado várias vezes com novos dados à medida que são transmitidos.

Classe: KeyObject ​

[Histórico]

VersãoMudanças
v14.5.0, v12.19.0Instâncias desta classe agora podem ser passadas para threads de trabalho usando postMessage.
v11.13.0Esta classe agora é exportada.
v11.6.0Adicionado em: v11.6.0

O Node.js usa uma classe KeyObject para representar uma chave simétrica ou assimétrica, e cada tipo de chave expõe funções diferentes. Os métodos crypto.createSecretKey(), crypto.createPublicKey() e crypto.createPrivateKey() são usados para criar instâncias KeyObject. Os objetos KeyObject não devem ser criados diretamente usando a palavra-chave new.

A maioria dos aplicativos deve considerar o uso da nova API KeyObject em vez de passar chaves como strings ou Buffers devido aos recursos de segurança aprimorados.

Instâncias de KeyObject podem ser passadas para outros threads por meio de postMessage(). O receptor obtém um KeyObject clonado e o KeyObject não precisa ser listado no argumento transferList.

Método estático: KeyObject.from(key) ​

Adicionado em: v15.0.0

Exemplo: Convertendo uma instância CryptoKey para um KeyObject:

js
const { KeyObject } = await import('node:crypto')
const { subtle } = globalThis.crypto

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

const keyObject = KeyObject.from(key)
console.log(keyObject.symmetricKeySize)
// Imprime: 32 (tamanho da chave simétrica em bytes)
js
const { KeyObject } = require('node:crypto')
const { subtle } = globalThis.crypto

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

  const keyObject = KeyObject.from(key)
  console.log(keyObject.symmetricKeySize)
  // Imprime: 32 (tamanho da chave simétrica em bytes)
})()

keyObject.asymmetricKeyDetails ​

[Histórico]

VersãoAlterações
v16.9.0Expõe parâmetros de sequência RSASSA-PSS-params para chaves RSA-PSS.
v15.7.0Adicionado em: v15.7.0
  • <Object>
    • modulusLength: <number> Tamanho da chave em bits (RSA, DSA).
    • publicExponent: <bigint> Expoente público (RSA).
    • hashAlgorithm: <string> Nome do resumo da mensagem (RSA-PSS).
    • mgf1HashAlgorithm: <string> Nome do resumo da mensagem usado pelo MGF1 (RSA-PSS).
    • saltLength: <number> Tamanho mínimo do salt em bytes (RSA-PSS).
    • divisorLength: <number> Tamanho de q em bits (DSA).
    • namedCurve: <string> Nome da curva (EC).

Esta propriedade existe apenas em chaves assimétricas. Dependendo do tipo da chave, este objeto contém informações sobre a chave. Nenhuma das informações obtidas através desta propriedade pode ser usada para identificar uma chave de forma única ou para comprometer a segurança da chave.

Para chaves RSA-PSS, se o material da chave contiver uma sequência RSASSA-PSS-params, as propriedades hashAlgorithm, mgf1HashAlgorithm e saltLength serão definidas.

Outros detalhes da chave podem ser expostos através desta API usando atributos adicionais.

keyObject.asymmetricKeyType ​

[Histórico]

VersãoMudanças
v13.9.0, v12.17.0Adicionado suporte para 'dh'.
v12.0.0Adicionado suporte para 'rsa-pss'.
v12.0.0Esta propriedade agora retorna undefined para instâncias KeyObject de tipo não reconhecido em vez de abortar.
v12.0.0Adicionado suporte para 'x25519' e 'x448'.
v12.0.0Adicionado suporte para 'ed25519' e 'ed448'.
v11.6.0Adicionado em: v11.6.0

Para chaves assimétricas, esta propriedade representa o tipo da chave. Os tipos de chave suportados são:

  • 'rsa' (OID 1.2.840.113549.1.1.1)
  • 'rsa-pss' (OID 1.2.840.113549.1.1.10)
  • 'dsa' (OID 1.2.840.10040.4.1)
  • 'ec' (OID 1.2.840.10045.2.1)
  • 'x25519' (OID 1.3.101.110)
  • 'x448' (OID 1.3.101.111)
  • 'ed25519' (OID 1.3.101.112)
  • 'ed448' (OID 1.3.101.113)
  • 'dh' (OID 1.2.840.113549.1.3.1)

Esta propriedade é undefined para tipos KeyObject não reconhecidos e chaves simétricas.

keyObject.equals(otherKeyObject) ​

Adicionado em: v17.7.0, v16.15.0

Retorna true ou false dependendo se as chaves têm exatamente o mesmo tipo, valor e parâmetros. Este método não é de tempo constante.

keyObject.export([options]) ​

[Histórico]

VersãoMudanças
v15.9.0Adicionado suporte para formato 'jwk'.
v11.6.0Adicionado em: v11.6.0

Para chaves simétricas, as seguintes opções de codificação podem ser usadas:

  • format: <string> Deve ser 'buffer' (padrão) ou 'jwk'.

Para chaves públicas, as seguintes opções de codificação podem ser usadas:

  • type: <string> Deve ser um de 'pkcs1' (apenas RSA) ou 'spki'.
  • format: <string> Deve ser 'pem', 'der', ou 'jwk'.

Para chaves privadas, as seguintes opções de codificação podem ser usadas:

  • type: <string> Deve ser um de 'pkcs1' (apenas RSA), 'pkcs8' ou 'sec1' (apenas EC).
  • format: <string> Deve ser 'pem', 'der', ou 'jwk'.
  • cipher: <string> Se especificado, a chave privada será criptografada com a cipher e a passphrase fornecidas usando a criptografia baseada em senha PKCS#5 v2.0.
  • passphrase: <string> | <Buffer> A senha a ser usada para criptografia, consulte cipher.

O tipo de resultado depende do formato de codificação selecionado, quando PEM o resultado é uma string, quando DER será um buffer contendo os dados codificados como DER, quando JWK será um objeto.

Quando o formato de codificação JWK foi selecionado, todas as outras opções de codificação são ignoradas.

Chaves do tipo PKCS#1, SEC1 e PKCS#8 podem ser criptografadas usando uma combinação das opções cipher e format. O type PKCS#8 pode ser usado com qualquer format para criptografar qualquer algoritmo de chave (RSA, EC ou DH) especificando um cipher. PKCS#1 e SEC1 só podem ser criptografados especificando um cipher quando o format PEM é usado. Para máxima compatibilidade, use PKCS#8 para chaves privadas criptografadas. Como o PKCS#8 define seu próprio mecanismo de criptografia, a criptografia no nível PEM não é suportada ao criptografar uma chave PKCS#8. Consulte RFC 5208 para criptografia PKCS#8 e RFC 1421 para criptografia PKCS#1 e SEC1.

keyObject.symmetricKeySize ​

Adicionado em: v11.6.0

Para chaves secretas, esta propriedade representa o tamanho da chave em bytes. Esta propriedade é undefined para chaves assimétricas.

keyObject.toCryptoKey(algorithm, extractable, keyUsages) ​

Adicionado em: v23.0.0

Converte uma instância KeyObject para um CryptoKey.

keyObject.type ​

Adicionado em: v11.6.0

Dependendo do tipo deste KeyObject, esta propriedade é 'secret' para chaves secretas (simétricas), 'public' para chaves públicas (assimétricas) ou 'private' para chaves privadas (assimétricas).

Classe: Sign ​

Adicionado em: v0.1.92

A classe Sign é uma utilidade para gerar assinaturas. Ela pode ser usada de duas maneiras:

  • Como um stream gravável, onde os dados a serem assinados são escritos e o método sign.sign() é usado para gerar e retornar a assinatura, ou
  • Usando os métodos sign.update() e sign.sign() para produzir a assinatura.

O método crypto.createSign() é usado para criar instâncias de Sign. O argumento é o nome da string da função hash a ser usada. Os objetos Sign não devem ser criados diretamente usando a palavra-chave new.

Exemplo: Usando objetos Sign e Verify como streams:

js
const { generateKeyPairSync, createSign, createVerify } = await import('node:crypto')

const { privateKey, publicKey } = generateKeyPairSync('ec', {
  namedCurve: 'sect239k1',
})

const sign = createSign('SHA256')
sign.write('alguns dados para assinar')
sign.end()
const signature = sign.sign(privateKey, 'hex')

const verify = createVerify('SHA256')
verify.write('alguns dados para assinar')
verify.end()
console.log(verify.verify(publicKey, signature, 'hex'))
// Imprime: true
js
const { generateKeyPairSync, createSign, createVerify } = require('node:crypto')

const { privateKey, publicKey } = generateKeyPairSync('ec', {
  namedCurve: 'sect239k1',
})

const sign = createSign('SHA256')
sign.write('alguns dados para assinar')
sign.end()
const signature = sign.sign(privateKey, 'hex')

const verify = createVerify('SHA256')
verify.write('alguns dados para assinar')
verify.end()
console.log(verify.verify(publicKey, signature, 'hex'))
// Imprime: true

Exemplo: Usando os métodos sign.update() e verify.update():

js
const { generateKeyPairSync, createSign, createVerify } = await import('node:crypto')

const { privateKey, publicKey } = generateKeyPairSync('rsa', {
  modulusLength: 2048,
})

const sign = createSign('SHA256')
sign.update('alguns dados para assinar')
sign.end()
const signature = sign.sign(privateKey)

const verify = createVerify('SHA256')
verify.update('alguns dados para assinar')
verify.end()
console.log(verify.verify(publicKey, signature))
// Imprime: true
js
const { generateKeyPairSync, createSign, createVerify } = require('node:crypto')

const { privateKey, publicKey } = generateKeyPairSync('rsa', {
  modulusLength: 2048,
})

const sign = createSign('SHA256')
sign.update('alguns dados para assinar')
sign.end()
const signature = sign.sign(privateKey)

const verify = createVerify('SHA256')
verify.update('alguns dados para assinar')
verify.end()
console.log(verify.verify(publicKey, signature))
// Imprime: true

sign.sign(privateKey[, outputEncoding]) ​

[Histórico]

VersãoMudanças
v15.0.0A privateKey também pode ser um ArrayBuffer e CryptoKey.
v13.2.0, v12.16.0Esta função agora suporta assinaturas IEEE-P1363 DSA e ECDSA.
v12.0.0Esta função agora suporta chaves RSA-PSS.
v11.6.0Esta função agora suporta objetos de chave.
v8.0.0Foi adicionado suporte para RSASSA-PSS e opções adicionais.
v0.1.92Adicionado em: v0.1.92

Calcula a assinatura em todos os dados passados usando sign.update() ou sign.write().

Se privateKey não for um KeyObject, esta função se comporta como se privateKey tivesse sido passado para crypto.createPrivateKey(). Se for um objeto, as seguintes propriedades adicionais podem ser passadas:

  • dsaEncoding <string> Para DSA e ECDSA, esta opção especifica o formato da assinatura gerada. Pode ser um dos seguintes:

    • 'der' (padrão): Estrutura de assinatura ASN.1 codificada em DER codificando (r, s).
    • 'ieee-p1363': Formato de assinatura r || s conforme proposto em IEEE-P1363.

  • padding <integer> Valor de preenchimento opcional para RSA, um dos seguintes:

    • crypto.constants.RSA_PKCS1_PADDING (padrão)
    • crypto.constants.RSA_PKCS1_PSS_PADDING

RSA_PKCS1_PSS_PADDING usará MGF1 com a mesma função hash usada para assinar a mensagem, conforme especificado na seção 3.1 de RFC 4055, a menos que uma função hash MGF1 tenha sido especificada como parte da chave em conformidade com a seção 3.3 de RFC 4055.

  • saltLength <integer> Comprimento do salt para quando o preenchimento é RSA_PKCS1_PSS_PADDING. O valor especial crypto.constants.RSA_PSS_SALTLEN_DIGEST define o comprimento do salt para o tamanho do resumo, crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN (padrão) define para o valor máximo permitido.

Se outputEncoding for fornecido, uma string será retornada; caso contrário, um Buffer será retornado.

O objeto Sign não pode ser usado novamente depois que o método sign.sign() for chamado. Múltiplas chamadas para sign.sign() resultarão em um erro sendo lançado.

sign.update(data[, inputEncoding]) ​

[Histórico]

VersãoMudanças
v6.0.0O inputEncoding padrão mudou de binary para utf8.
v0.1.92Adicionado em: v0.1.92

Atualiza o conteúdo Sign com os data fornecidos, cuja codificação é fornecida em inputEncoding. Se encoding não for fornecido e o data for uma string, uma codificação de 'utf8' é aplicada. Se data for um Buffer, TypedArray ou DataView, então inputEncoding será ignorado.

Isso pode ser chamado várias vezes com novos dados à medida que são transmitidos.

Classe: Verify ​

Adicionado em: v0.1.92

A classe Verify é um utilitário para verificar assinaturas. Ele pode ser usado de duas maneiras:

  • Como um stream gravável onde os dados gravados são usados para validar em relação à assinatura fornecida, ou
  • Usando os métodos verify.update() e verify.verify() para verificar a assinatura.

O método crypto.createVerify() é usado para criar instâncias Verify. Objetos Verify não devem ser criados diretamente usando a palavra-chave new.

Veja Sign para exemplos.

verify.update(data[, inputEncoding]) ​

[Histórico]

VersãoMudanças
v6.0.0O inputEncoding padrão mudou de binary para utf8.
v0.1.92Adicionado em: v0.1.92

Atualiza o conteúdo Verify com os data fornecidos, cuja codificação é fornecida em inputEncoding. Se inputEncoding não for fornecido e o data for uma string, uma codificação de 'utf8' é aplicada. Se data for um Buffer, TypedArray ou DataView, então inputEncoding será ignorado.

Isso pode ser chamado várias vezes com novos dados à medida que são transmitidos.

verify.verify(object, signature[, signatureEncoding]) ​

[Histórico]

VersãoMudanças
v15.0.0O objeto também pode ser um ArrayBuffer e CryptoKey.
v13.2.0, v12.16.0Esta função agora suporta assinaturas IEEE-P1363 DSA e ECDSA.
v12.0.0Esta função agora suporta chaves RSA-PSS.
v11.7.0A chave agora pode ser uma chave privada.
v8.0.0Foi adicionado suporte para RSASSA-PSS e opções adicionais.
v0.1.92Adicionado em: v0.1.92

Verifica os dados fornecidos usando o object e a signature fornecidos.

Se object não for um KeyObject, esta função se comporta como se object tivesse sido passado para crypto.createPublicKey(). Se for um objeto, as seguintes propriedades adicionais podem ser passadas:

  • dsaEncoding <string> Para DSA e ECDSA, esta opção especifica o formato da assinatura. Pode ser um dos seguintes:

    • 'der' (padrão): estrutura de assinatura ASN.1 codificada em DER codificando (r, s).
    • 'ieee-p1363': Formato de assinatura r || s conforme proposto em IEEE-P1363.

  • padding <inteiro> Valor de preenchimento opcional para RSA, um dos seguintes:

    • crypto.constants.RSA_PKCS1_PADDING (padrão)
    • crypto.constants.RSA_PKCS1_PSS_PADDING

RSA_PKCS1_PSS_PADDING usará MGF1 com a mesma função hash usada para verificar a mensagem, conforme especificado na seção 3.1 do RFC 4055, a menos que uma função hash MGF1 tenha sido especificada como parte da chave em conformidade com a seção 3.3 do RFC 4055.

  • saltLength <inteiro> Comprimento do salt para quando o padding for RSA_PKCS1_PSS_PADDING. O valor especial crypto.constants.RSA_PSS_SALTLEN_DIGEST define o comprimento do salt para o tamanho do digest, crypto.constants.RSA_PSS_SALTLEN_AUTO (padrão) faz com que ele seja determinado automaticamente.

O argumento signature é a assinatura previamente calculada para os dados, na signatureEncoding. Se uma signatureEncoding for especificada, espera-se que a signature seja uma string; caso contrário, espera-se que signature seja um Buffer, TypedArray ou DataView.

O objeto verify não pode ser usado novamente depois que verify.verify() for chamado. Várias chamadas para verify.verify() resultarão em um erro sendo lançado.

Como as chaves públicas podem ser derivadas de chaves privadas, uma chave privada pode ser passada em vez de uma chave pública.

Classe: X509Certificate ​

Adicionado em: v15.6.0

Encapsula um certificado X509 e fornece acesso somente leitura às suas informações.

js
const { X509Certificate } = await import('node:crypto')

const x509 = new X509Certificate('{... certificado codificado em pem ...}')

console.log(x509.subject)
js
const { X509Certificate } = require('node:crypto')

const x509 = new X509Certificate('{... certificado codificado em pem ...}')

console.log(x509.subject)

new X509Certificate(buffer) ​

Adicionado em: v15.6.0

x509.ca ​

Adicionado em: v15.6.0

  • Tipo: <boolean> Será true se este for um certificado de Autoridade de Certificação (CA).

x509.checkEmail(email[, options]) ​

[Histórico]

VersãoMudanças
v18.0.0A opção subject agora usa como padrão 'default'.
v17.5.0, v16.15.0A opção subject agora pode ser definida como 'default'.
v17.5.0, v16.14.1As opções wildcards, partialWildcards, multiLabelWildcards e singleLabelSubdomains foram removidas, pois não tinham efeito.
v15.6.0Adicionado em: v15.6.0

Verifica se o certificado corresponde ao endereço de email fornecido.

Se a opção 'subject' não estiver definida ou estiver definida como 'default', o assunto do certificado só será considerado se a extensão de nome alternativo do assunto não existir ou não contiver nenhum endereço de email.

Se a opção 'subject' estiver definida como 'always' e se a extensão de nome alternativo do assunto não existir ou não contiver um endereço de email correspondente, o assunto do certificado será considerado.

Se a opção 'subject' estiver definida como 'never', o assunto do certificado nunca será considerado, mesmo que o certificado não contenha nomes alternativos de assunto.

x509.checkHost(name[, options]) ​

[Histórico]

VersãoAlterações
v18.0.0A opção subject agora tem como padrão 'default'.
v17.5.0, v16.15.0A opção subject agora pode ser definida como 'default'.
v15.6.0Adicionado em: v15.6.0

  • name <string>

  • options <Object>

    • subject <string> 'default', 'always' ou 'never'. Padrão: 'default'.
    • wildcards <boolean> Padrão: true.
    • partialWildcards <boolean> Padrão: true.
    • multiLabelWildcards <boolean> Padrão: false.
    • singleLabelSubdomains <boolean> Padrão: false.

  • Retorna: <string> | <undefined> Retorna um nome de assunto que corresponde a name, ou undefined se nenhum nome de assunto corresponder a name.

Verifica se o certificado corresponde ao nome de host fornecido.

Se o certificado corresponder ao nome de host fornecido, o nome do assunto correspondente será retornado. O nome retornado pode ser uma correspondência exata (por exemplo, foo.example.com) ou pode conter curingas (por exemplo, *.example.com). Como as comparações de nome de host não diferenciam maiúsculas de minúsculas, o nome do assunto retornado também pode ser diferente do name fornecido em capitalização.

Se a opção 'subject' for indefinida ou definida como 'default', o assunto do certificado só será considerado se a extensão de nome alternativo do assunto não existir ou não contiver nenhum nome DNS. Esse comportamento é consistente com RFC 2818 ("HTTP Over TLS").

Se a opção 'subject' estiver definida como 'always' e se a extensão de nome alternativo do assunto não existir ou não contiver um nome DNS correspondente, o assunto do certificado será considerado.

Se a opção 'subject' estiver definida como 'never', o assunto do certificado nunca será considerado, mesmo que o certificado não contenha nomes alternativos de assunto.

x509.checkIP(ip) ​

[Histórico]

VersãoMudanças
v17.5.0, v16.14.1O argumento options foi removido, pois não tinha efeito.
v15.6.0Adicionado em: v15.6.0

Verifica se o certificado corresponde ao endereço IP fornecido (IPv4 ou IPv6).

Apenas os nomes alternativos de assunto iPAddress da RFC 5280 são considerados e devem corresponder exatamente ao endereço ip fornecido. Outros nomes alternativos de assunto, bem como o campo de assunto do certificado, são ignorados.

x509.checkIssued(otherCert) ​

Adicionado em: v15.6.0

Verifica se este certificado foi emitido pelo otherCert fornecido.

x509.checkPrivateKey(privateKey) ​

Adicionado em: v15.6.0

Verifica se a chave pública para este certificado é consistente com a chave privada fornecida.

x509.extKeyUsage ​

Adicionado em: v15.6.0

Um array detalhando os usos estendidos de chave para este certificado.

x509.fingerprint ​

Adicionado em: v15.6.0

A impressão digital SHA-1 deste certificado.

Como o SHA-1 está criptograficamente quebrado e porque a segurança do SHA-1 é significativamente pior do que a dos algoritmos que são comumente usados para assinar certificados, considere usar x509.fingerprint256 em vez disso.

x509.fingerprint256 ​

Adicionado em: v15.6.0

A impressão digital SHA-256 deste certificado.

x509.fingerprint512 ​

Adicionado em: v17.2.0, v16.14.0

A impressão digital SHA-512 deste certificado.

Como computar a impressão digital SHA-256 geralmente é mais rápido e porque tem apenas metade do tamanho da impressão digital SHA-512, x509.fingerprint256 pode ser uma escolha melhor. Enquanto SHA-512 presumivelmente fornece um nível mais alto de segurança em geral, a segurança de SHA-256 corresponde à da maioria dos algoritmos que são comumente usados para assinar certificados.

x509.infoAccess ​

[Histórico]

VersãoMudanças
v17.3.1, v16.13.2Partes desta string podem ser codificadas como literais de string JSON em resposta ao CVE-2021-44532.
v15.6.0Adicionado em: v15.6.0

Uma representação textual da extensão de acesso à informação da autoridade do certificado.

Esta é uma lista separada por quebras de linha de descrições de acesso. Cada linha começa com o método de acesso e o tipo de local de acesso, seguido por dois pontos e o valor associado ao local de acesso.

Após o prefixo que denota o método de acesso e o tipo do local de acesso, o restante de cada linha pode estar entre aspas para indicar que o valor é um literal de string JSON. Para compatibilidade com versões anteriores, o Node.js usa literais de string JSON nesta propriedade apenas quando necessário para evitar ambiguidade. O código de terceiros deve estar preparado para lidar com ambos os formatos de entrada possíveis.

x509.issuer ​

Adicionado em: v15.6.0

A identificação do emissor incluída neste certificado.

x509.issuerCertificate ​

Adicionado em: v15.9.0

O certificado do emissor ou undefined se o certificado do emissor não estiver disponível.

x509.publicKey ​

Adicionado em: v15.6.0

A chave pública <KeyObject> para este certificado.

x509.raw ​

Adicionado em: v15.6.0

Um Buffer contendo a codificação DER deste certificado.

x509.serialNumber ​

Adicionado em: v15.6.0

O número de série deste certificado.

Os números de série são atribuídos por autoridades de certificação e não identificam certificados de forma única. Considere usar x509.fingerprint256 como um identificador único.

x509.subject ​

Adicionado em: v15.6.0

O sujeito completo deste certificado.

x509.subjectAltName ​

[Histórico]

VersãoMudanças
v17.3.1, v16.13.2Partes desta string podem ser codificadas como literais de string JSON em resposta a CVE-2021-44532.
v15.6.0Adicionado em: v15.6.0

O nome alternativo do sujeito especificado para este certificado.

Esta é uma lista de nomes alternativos de sujeito separados por vírgulas. Cada entrada começa com uma string identificando o tipo do nome alternativo do sujeito seguido por dois pontos e o valor associado à entrada.

Versões anteriores do Node.js assumiam incorretamente que era seguro dividir esta propriedade na sequência de dois caracteres ', ' (ver CVE-2021-44532). No entanto, certificados maliciosos e legítimos podem conter nomes alternativos de sujeito que incluem esta sequência quando representados como uma string.

Após o prefixo que denota o tipo da entrada, o restante de cada entrada pode ser incluído em aspas para indicar que o valor é um literal de string JSON. Para compatibilidade com versões anteriores, o Node.js só usa literais de string JSON dentro desta propriedade quando necessário para evitar ambiguidade. O código de terceiros deve estar preparado para lidar com os dois formatos de entrada possíveis.

x509.toJSON() ​

Adicionado em: v15.6.0

Não existe uma codificação JSON padrão para certificados X509. O método toJSON() retorna uma string contendo o certificado codificado em PEM.

x509.toLegacyObject() ​

Adicionado em: v15.6.0

Retorna informações sobre este certificado usando a codificação legado de objeto de certificado.

x509.toString() ​

Adicionado em: v15.6.0

Retorna o certificado codificado em PEM.

x509.validFrom ​

Adicionado em: v15.6.0

A data/hora a partir da qual este certificado é válido.

x509.validFromDate ​

Adicionado em: v23.0.0

A data/hora a partir da qual este certificado é válido, encapsulada em um objeto Date.

x509.validTo ​

Adicionado em: v15.6.0

A data/hora até a qual este certificado é válido.

x509.validToDate ​

Adicionado em: v23.0.0

A data/hora até a qual este certificado é válido, encapsulada em um objeto Date.

x509.verify(publicKey) ​

Adicionado em: v15.6.0

Verifica se este certificado foi assinado pela chave pública fornecida. Não realiza nenhuma outra verificação de validação no certificado.

Métodos e propriedades do módulo node:crypto ​

crypto.checkPrime(candidate[, options], callback) ​

[Histórico]

VersãoMudanças
v18.0.0Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v15.8.0Adicionado em: v15.8.0

  • candidate <ArrayBuffer> | <SharedArrayBuffer> | <TypedArray> | <Buffer> | <DataView> | <bigint> Um possível número primo codificado como uma sequência de octetos big endian de comprimento arbitrário.

  • options <Object>

    • checks <number> O número de iterações probabilísticas de primalidade de Miller-Rabin a serem realizadas. Quando o valor é 0 (zero), um número de verificações é usado que produz uma taxa de falso positivo de no máximo 2 para entrada aleatória. Deve-se ter cuidado ao selecionar um número de verificações. Consulte a documentação OpenSSL para as opções nchecks da função BN_is_prime_ex para mais detalhes. Padrão: 0

  • callback <Function>

    • err <Error> Definido como um objeto <Error> se ocorreu um erro durante a verificação.
    • result <boolean> true se o candidato for um número primo com uma probabilidade de erro inferior a 0,25 ** options.checks.

Verifica a primalidade do candidate.

crypto.checkPrimeSync(candidate[, options]) ​

Adicionado em: v15.8.0

  • candidate <ArrayBuffer> | <SharedArrayBuffer> | <TypedArray> | <Buffer> | <DataView> | <bigint> Um possível número primo codificado como uma sequência de octetos big endian de comprimento arbitrário.

  • options <Object>

    • checks <number> O número de iterações de primalidade probabilística de Miller-Rabin a serem executadas. Quando o valor é 0 (zero), um número de verificações é usado que produz uma taxa de falso positivo de no máximo 2 para entrada aleatória. Deve-se ter cuidado ao selecionar um número de verificações. Consulte a documentação do OpenSSL para as opções nchecks da função BN_is_prime_ex para mais detalhes. Padrão: 0

  • Retorna: <boolean> true se o candidato for um número primo com uma probabilidade de erro menor que 0,25 ** options.checks.

Verifica a primalidade do candidato.

crypto.constants ​

Adicionado em: v6.3.0

Um objeto contendo constantes comumente usadas para operações relacionadas a criptografia e segurança. As constantes específicas atualmente definidas são descritas em Constantes de Criptografia.

crypto.createCipheriv(algorithm, key, iv[, options]) ​

[Histórico]

VersãoMudanças
v17.9.0, v16.17.0A opção authTagLength agora é opcional ao usar a cifra chacha20-poly1305 e o padrão é 16 bytes.
v15.0.0Os argumentos password e iv podem ser um ArrayBuffer e cada um está limitado a um máximo de 2 ** 31 - 1 bytes.
v11.6.0O argumento key agora pode ser um KeyObject.
v11.2.0, v10.17.0A cifra chacha20-poly1305 (a variante IETF de ChaCha20-Poly1305) agora é suportada.
v10.10.0Cifras no modo OCB agora são suportadas.
v10.2.0A opção authTagLength agora pode ser usada para produzir tags de autenticação mais curtas no modo GCM e o padrão é 16 bytes.
v9.9.0O parâmetro iv agora pode ser null para cifras que não precisam de um vetor de inicialização.
v0.1.94Adicionado em: v0.1.94

Cria e retorna um objeto Cipher, com o algorithm, key e o vetor de inicialização (iv) fornecidos.

O argumento options controla o comportamento do fluxo e é opcional, exceto quando uma cifra no modo CCM ou OCB (por exemplo, 'aes-128-ccm') é usada. Nesse caso, a opção authTagLength é obrigatória e especifica o comprimento da tag de autenticação em bytes, consulte modo CCM. No modo GCM, a opção authTagLength não é obrigatória, mas pode ser usada para definir o comprimento da tag de autenticação que será retornada por getAuthTag() e o padrão é 16 bytes. Para chacha20-poly1305, a opção authTagLength tem como padrão 16 bytes.

O algorithm depende do OpenSSL, exemplos são 'aes192', etc. Em versões recentes do OpenSSL, openssl list -cipher-algorithms exibirá os algoritmos de cifra disponíveis.

A key é a chave bruta usada pelo algorithm e iv é um vetor de inicialização. Ambos os argumentos devem ser strings codificadas em 'utf8', Buffers, TypedArray ou DataViews. A key pode ser opcionalmente um KeyObject do tipo secret. Se a cifra não precisar de um vetor de inicialização, iv pode ser null.

Ao passar strings para key ou iv, considere ressalvas ao usar strings como entradas para APIs criptográficas.

Os vetores de inicialização devem ser imprevisíveis e únicos; idealmente, eles serão criptograficamente aleatórios. Eles não precisam ser secretos: os IVs são normalmente apenas adicionados a mensagens de texto cifrado não criptografadas. Pode parecer contraditório que algo tenha que ser imprevisível e único, mas não precisa ser secreto; lembre-se de que um invasor não deve ser capaz de prever com antecedência qual será um determinado IV.

crypto.createDecipheriv(algorithm, key, iv[, options]) ​

[Histórico]

VersãoMudanças
v17.9.0, v16.17.0A opção authTagLength agora é opcional ao usar a cifra chacha20-poly1305 e o padrão é 16 bytes.
v11.6.0O argumento key agora pode ser um KeyObject.
v11.2.0, v10.17.0A cifra chacha20-poly1305 (a variante IETF de ChaCha20-Poly1305) agora é suportada.
v10.10.0Cifras no modo OCB agora são suportadas.
v10.2.0A opção authTagLength agora pode ser usada para restringir os comprimentos de tag de autenticação GCM aceitos.
v9.9.0O parâmetro iv agora pode ser null para cifras que não precisam de um vetor de inicialização.
v0.1.94Adicionado em: v0.1.94

Cria e retorna um objeto Decipher que usa o algorithm, a key e o vetor de inicialização (iv) fornecidos.

O argumento options controla o comportamento do fluxo e é opcional, exceto quando uma cifra no modo CCM ou OCB (por exemplo, 'aes-128-ccm') é usada. Nesse caso, a opção authTagLength é obrigatória e especifica o comprimento da tag de autenticação em bytes, consulte modo CCM. Para AES-GCM e chacha20-poly1305, a opção authTagLength assume o padrão de 16 bytes e deve ser definida para um valor diferente se um comprimento diferente for usado.

O algorithm depende do OpenSSL, exemplos são 'aes192', etc. Em versões recentes do OpenSSL, openssl list -cipher-algorithms exibirá os algoritmos de cifra disponíveis.

A key é a chave bruta usada pelo algorithm e iv é um vetor de inicialização. Ambos os argumentos devem ser strings codificadas em 'utf8', Buffers, TypedArray ou DataViews. O key pode, opcionalmente, ser um KeyObject do tipo secret. Se a cifra não precisar de um vetor de inicialização, iv pode ser null.

Ao passar strings para key ou iv, considere as ressalvas ao usar strings como entradas para APIs criptográficas.

Os vetores de inicialização devem ser imprevisíveis e únicos; idealmente, eles serão criptograficamente aleatórios. Eles não precisam ser secretos: os IVs são normalmente adicionados às mensagens de texto cifrado não criptografadas. Pode parecer contraditório que algo tenha que ser imprevisível e único, mas não precise ser secreto; lembre-se de que um invasor não deve ser capaz de prever com antecedência qual será um determinado IV.

crypto.createDiffieHellman(prime[, primeEncoding][, generator][, generatorEncoding]) ​

[Histórico]

VersãoMudanças
v8.0.0O argumento prime pode ser qualquer TypedArray ou DataView agora.
v8.0.0O argumento prime pode ser um Uint8Array agora.
v6.0.0O padrão para os parâmetros de codificação mudou de binary para utf8.
v0.11.12Adicionado em: v0.11.12

Cria um objeto de troca de chaves DiffieHellman usando o prime fornecido e um generator específico opcional.

O argumento generator pode ser um número, string ou Buffer. Se generator não for especificado, o valor 2 é usado.

Se primeEncoding for especificado, espera-se que prime seja uma string; caso contrário, espera-se um Buffer, TypedArray ou DataView.

Se generatorEncoding for especificado, espera-se que generator seja uma string; caso contrário, espera-se um número, Buffer, TypedArray ou DataView.

crypto.createDiffieHellman(primeLength[, generator]) ​

Adicionado em: v0.5.0

Cria um objeto de troca de chaves DiffieHellman e gera um primo de primeLength bits usando um generator numérico específico opcional. Se generator não for especificado, o valor 2 será usado.

crypto.createDiffieHellmanGroup(name) ​

Adicionado em: v0.9.3

Um alias para crypto.getDiffieHellman()

crypto.createECDH(curveName) ​

Adicionado em: v0.11.14

Cria um objeto de troca de chaves Elliptic Curve Diffie-Hellman (ECDH) usando uma curva predefinida especificada pela string curveName. Use crypto.getCurves() para obter uma lista de nomes de curva disponíveis. Em versões recentes do OpenSSL, openssl ecparam -list_curves também exibirá o nome e a descrição de cada curva elíptica disponível.

crypto.createHash(algorithm[, options]) ​

[Histórico]

VersãoMudanças
v12.8.0A opção outputLength foi adicionada para funções hash XOF.
v0.1.92Adicionado em: v0.1.92

Cria e retorna um objeto Hash que pode ser usado para gerar resumos de hash usando o algorithm fornecido. O argumento opcional options controla o comportamento do fluxo. Para funções hash XOF, como 'shake256', a opção outputLength pode ser usada para especificar o comprimento de saída desejado em bytes.

O algorithm depende dos algoritmos disponíveis suportados pela versão do OpenSSL na plataforma. Exemplos são 'sha256', 'sha512', etc. Em versões recentes do OpenSSL, openssl list -digest-algorithms exibirá os algoritmos de resumo disponíveis.

Exemplo: gerando a soma sha256 de um arquivo

js
import { createReadStream } from 'node:fs'
import { argv } from 'node:process'
const { createHash } = await import('node:crypto')

const filename = argv[2]

const hash = createHash('sha256')

const input = createReadStream(filename)
input.on('readable', () => {
  // Apenas um elemento será produzido pelo
  // fluxo de hash.
  const data = input.read()
  if (data) hash.update(data)
  else {
    console.log(`${hash.digest('hex')} ${filename}`)
  }
})
js
const { createReadStream } = require('node:fs')
const { createHash } = require('node:crypto')
const { argv } = require('node:process')

const filename = argv[2]

const hash = createHash('sha256')

const input = createReadStream(filename)
input.on('readable', () => {
  // Apenas um elemento será produzido pelo
  // fluxo de hash.
  const data = input.read()
  if (data) hash.update(data)
  else {
    console.log(`${hash.digest('hex')} ${filename}`)
  }
})

crypto.createHmac(algorithm, key[, options]) ​

[Histórico]

VersãoMudanças
v15.0.0A chave também pode ser um ArrayBuffer ou CryptoKey. A opção de codificação foi adicionada. A chave não pode conter mais de 2 ** 32 - 1 bytes.
v11.6.0O argumento key agora pode ser um KeyObject.
v0.1.94Adicionado em: v0.1.94

Cria e retorna um objeto Hmac que usa o algorithm e a key fornecidos. O argumento opcional options controla o comportamento do fluxo.

O algorithm depende dos algoritmos disponíveis suportados pela versão do OpenSSL na plataforma. Exemplos são 'sha256', 'sha512', etc. Em versões recentes do OpenSSL, openssl list -digest-algorithms exibirá os algoritmos de digest disponíveis.

A key é a chave HMAC usada para gerar o hash HMAC criptográfico. Se for um KeyObject, seu tipo deve ser secret. Se for uma string, considere ressalvas ao usar strings como entradas para APIs criptográficas. Se foi obtido de uma fonte de entropia criptograficamente segura, como crypto.randomBytes() ou crypto.generateKey(), seu comprimento não deve exceder o tamanho do bloco do algorithm (por exemplo, 512 bits para SHA-256).

Exemplo: gerando o HMAC sha256 de um arquivo

js
import { createReadStream } from 'node:fs'
import { argv } from 'node:process'
const { createHmac } = await import('node:crypto')

const filename = argv[2]

const hmac = createHmac('sha256', 'a secret')

const input = createReadStream(filename)
input.on('readable', () => {
  // Apenas um elemento será produzido pelo
  // fluxo de hash.
  const data = input.read()
  if (data) hmac.update(data)
  else {
    console.log(`${hmac.digest('hex')} ${filename}`)
  }
})
js
const { createReadStream } = require('node:fs')
const { createHmac } = require('node:crypto')
const { argv } = require('node:process')

const filename = argv[2]

const hmac = createHmac('sha256', 'a secret')

const input = createReadStream(filename)
input.on('readable', () => {
  // Apenas um elemento será produzido pelo
  // fluxo de hash.
  const data = input.read()
  if (data) hmac.update(data)
  else {
    console.log(`${hmac.digest('hex')} ${filename}`)
  }
})

crypto.createPrivateKey(chave) ​

[Histórico]

VersãoMudanças
v15.12.0A chave também pode ser um objeto JWK.
v15.0.0A chave também pode ser um ArrayBuffer. A opção de codificação foi adicionada. A chave não pode conter mais de 2 ** 32 - 1 bytes.
v11.6.0Adicionado em: v11.6.0

Cria e retorna um novo objeto de chave contendo uma chave privada. Se chave for uma string ou Buffer, o formato será considerado como 'pem'; caso contrário, chave deve ser um objeto com as propriedades descritas acima.

Se a chave privada estiver criptografada, uma senha deve ser especificada. O comprimento da senha é limitado a 1024 bytes.

crypto.createPublicKey(key) ​

[Histórico]

VersãoMudanças
v15.12.0A chave também pode ser um objeto JWK.
v15.0.0A chave também pode ser um ArrayBuffer. A opção de codificação foi adicionada. A chave não pode conter mais de 2 ** 32 - 1 bytes.
v11.13.0O argumento key agora pode ser um KeyObject com tipo private.
v11.7.0O argumento key agora pode ser uma chave privada.
v11.6.0Adicionado em: v11.6.0

Cria e retorna um novo objeto de chave contendo uma chave pública. Se key for uma string ou Buffer, format é considerado como sendo 'pem'; se key for um KeyObject com tipo 'private', a chave pública é derivada da chave privada fornecida; caso contrário, key deve ser um objeto com as propriedades descritas acima.

Se o formato for 'pem', a 'key' também pode ser um certificado X.509.

Como as chaves públicas podem ser derivadas de chaves privadas, uma chave privada pode ser passada em vez de uma chave pública. Nesse caso, esta função se comporta como se crypto.createPrivateKey() tivesse sido chamada, exceto que o tipo do KeyObject retornado será 'public' e que a chave privada não pode ser extraída do KeyObject retornado. Da mesma forma, se um KeyObject com tipo 'private' for fornecido, um novo KeyObject com tipo 'public' será retornado e será impossível extrair a chave privada do objeto retornado.

crypto.createSecretKey(key[, encoding]) ​

[Histórico]

VersãoMudanças
v18.8.0, v16.18.0A chave agora pode ter comprimento zero.
v15.0.0A chave também pode ser um ArrayBuffer ou string. O argumento encoding foi adicionado. A chave não pode conter mais de 2 ** 32 - 1 bytes.
v11.6.0Adicionado em: v11.6.0

Cria e retorna um novo objeto key contendo uma chave secreta para criptografia simétrica ou Hmac.

crypto.createSign(algorithm[, options]) ​

Adicionado em: v0.1.92

Cria e retorna um objeto Sign que usa o algorithm fornecido. Use crypto.getHashes() para obter os nomes dos algoritmos de digest disponíveis. O argumento opcional options controla o comportamento stream.Writable.

Em alguns casos, uma instância Sign pode ser criada usando o nome de um algoritmo de assinatura, como 'RSA-SHA256', em vez de um algoritmo de digest. Isso usará o algoritmo de digest correspondente. Isso não funciona para todos os algoritmos de assinatura, como 'ecdsa-with-SHA256', portanto, é melhor sempre usar nomes de algoritmos de digest.

crypto.createVerify(algorithm[, options]) ​

Adicionado em: v0.1.92

Cria e retorna um objeto Verify que usa o algoritmo fornecido. Use crypto.getHashes() para obter uma matriz de nomes dos algoritmos de assinatura disponíveis. O argumento options opcional controla o comportamento do stream.Writable.

Em alguns casos, uma instância Verify pode ser criada usando o nome de um algoritmo de assinatura, como 'RSA-SHA256', em vez de um algoritmo de digestão. Isso usará o algoritmo de digestão correspondente. Isso não funciona para todos os algoritmos de assinatura, como 'ecdsa-with-SHA256', portanto, é melhor usar sempre os nomes dos algoritmos de digestão.

crypto.diffieHellman(options) ​

Adicionado em: v13.9.0, v12.17.0

Calcula o segredo Diffie-Hellman com base em uma privateKey e uma publicKey. Ambas as chaves devem ter o mesmo asymmetricKeyType, que deve ser um de 'dh' (para Diffie-Hellman), 'ec', 'x448', ou 'x25519' (para ECDH).

crypto.fips ​

Adicionado em: v6.0.0

Obsoleto desde: v10.0.0

[Estável: 0 - Obsoleto]

Estável: 0 Estabilidade: 0 - Obsoleto

Propriedade para verificar e controlar se um provedor de criptografia compatível com FIPS está atualmente em uso. Definir como verdadeiro requer uma compilação FIPS do Node.js.

Esta propriedade está obsoleta. Use crypto.setFips() e crypto.getFips() em vez disso.

crypto.generateKey(type, options, callback) ​

[Histórico]

VersãoAlterações
v18.0.0Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v15.0.0Adicionado em: v15.0.0

  • type: <string> O uso pretendido da chave secreta gerada. Os valores atualmente aceitos são 'hmac' e 'aes'.

  • options: <Object>

    • length: <number> O comprimento em bits da chave a ser gerada. Este deve ser um valor maior que 0.
    • Se type for 'hmac', o mínimo é 8 e o comprimento máximo é 2-1. Se o valor não for um múltiplo de 8, a chave gerada será truncada para Math.floor(length / 8).
    • Se type for 'aes', o comprimento deve ser um de 128, 192 ou 256.

  • callback: <Function>

Gera assincronamente uma nova chave secreta aleatória do length fornecido. O type determinará quais validações serão executadas no length.

js
const { generateKey } = await import('node:crypto')

generateKey('hmac', { length: 512 }, (err, key) => {
  if (err) throw err
  console.log(key.export().toString('hex')) // 46e..........620
})
js
const { generateKey } = require('node:crypto')

generateKey('hmac', { length: 512 }, (err, key) => {
  if (err) throw err
  console.log(key.export().toString('hex')) // 46e..........620
})

O tamanho de uma chave HMAC gerada não deve exceder o tamanho do bloco da função hash subjacente. Consulte crypto.createHmac() para obter mais informações.

crypto.generateKeyPair(type, options, callback) ​

[Histórico]

VersãoMudanças
v18.0.0Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v16.10.0Adicionada a capacidade de definir parâmetros de sequência RSASSA-PSS-params para pares de chaves RSA-PSS.
v13.9.0, v12.17.0Adicionado suporte para Diffie-Hellman.
v12.0.0Adicionado suporte para pares de chaves RSA-PSS.
v12.0.0Adicionada a capacidade de gerar pares de chaves X25519 e X448.
v12.0.0Adicionada a capacidade de gerar pares de chaves Ed25519 e Ed448.
v11.6.0As funções generateKeyPair e generateKeyPairSync agora produzem objetos de chave se nenhuma codificação foi especificada.
v10.12.0Adicionado em: v10.12.0

Gera um novo par de chaves assimétricas do type fornecido. RSA, RSA-PSS, DSA, EC, Ed25519, Ed448, X25519, X448 e DH são suportados atualmente.

Se um publicKeyEncoding ou privateKeyEncoding foi especificado, esta função se comporta como se keyObject.export() tivesse sido chamado em seu resultado. Caso contrário, a parte respectiva da chave é retornada como um KeyObject.

É recomendável codificar as chaves públicas como 'spki' e as chaves privadas como 'pkcs8' com criptografia para armazenamento de longo prazo:

js
const { generateKeyPair } = await import('node:crypto')

generateKeyPair(
  'rsa',
  {
    modulusLength: 4096,
    publicKeyEncoding: {
      type: 'spki',
      format: 'pem',
    },
    privateKeyEncoding: {
      type: 'pkcs8',
      format: 'pem',
      cipher: 'aes-256-cbc',
      passphrase: 'top secret',
    },
  },
  (err, publicKey, privateKey) => {
    // Manipule os erros e use o par de chaves gerado.
  }
)
js
const { generateKeyPair } = require('node:crypto')

generateKeyPair(
  'rsa',
  {
    modulusLength: 4096,
    publicKeyEncoding: {
      type: 'spki',
      format: 'pem',
    },
    privateKeyEncoding: {
      type: 'pkcs8',
      format: 'pem',
      cipher: 'aes-256-cbc',
      passphrase: 'top secret',
    },
  },
  (err, publicKey, privateKey) => {
    // Manipule os erros e use o par de chaves gerado.
  }
)

Após a conclusão, callback será chamado com err definido como undefined e publicKey / privateKey representando o par de chaves gerado.

Se este método for invocado como sua versão util.promisify()ed, ele retornará uma Promise para um Objeto com propriedades publicKey e privateKey.

crypto.generateKeyPairSync(type, options) ​

[Histórico]

VersãoMudanças
v16.10.0Adicionada a capacidade de definir parâmetros de sequência RSASSA-PSS-params para pares de chaves RSA-PSS.
v13.9.0, v12.17.0Adicionado suporte para Diffie-Hellman.
v12.0.0Adicionado suporte para pares de chaves RSA-PSS.
v12.0.0Adicionada a capacidade de gerar pares de chaves X25519 e X448.
v12.0.0Adicionada a capacidade de gerar pares de chaves Ed25519 e Ed448.
v11.6.0As funções generateKeyPair e generateKeyPairSync agora produzem objetos de chave se nenhuma codificação foi especificada.
v10.12.0Adicionado em: v10.12.0

Gera um novo par de chaves assimétricas do type fornecido. RSA, RSA-PSS, DSA, EC, Ed25519, Ed448, X25519, X448 e DH são suportados atualmente.

Se um publicKeyEncoding ou privateKeyEncoding foi especificado, esta função se comporta como se keyObject.export() tivesse sido chamada em seu resultado. Caso contrário, a parte respectiva da chave é retornada como um KeyObject.

Ao codificar chaves públicas, é recomendável usar 'spki'. Ao codificar chaves privadas, é recomendável usar 'pkcs8' com uma senha forte e manter a senha confidencial.

js
const { generateKeyPairSync } = await import('node:crypto')

const { publicKey, privateKey } = generateKeyPairSync('rsa', {
  modulusLength: 4096,
  publicKeyEncoding: {
    type: 'spki',
    format: 'pem',
  },
  privateKeyEncoding: {
    type: 'pkcs8',
    format: 'pem',
    cipher: 'aes-256-cbc',
    passphrase: 'top secret',
  },
})
js
const { generateKeyPairSync } = require('node:crypto')

const { publicKey, privateKey } = generateKeyPairSync('rsa', {
  modulusLength: 4096,
  publicKeyEncoding: {
    type: 'spki',
    format: 'pem',
  },
  privateKeyEncoding: {
    type: 'pkcs8',
    format: 'pem',
    cipher: 'aes-256-cbc',
    passphrase: 'top secret',
  },
})

O valor de retorno { publicKey, privateKey } representa o par de chaves gerado. Quando a codificação PEM foi selecionada, a chave respectiva será uma string, caso contrário, será um buffer contendo os dados codificados como DER.

crypto.generateKeySync(type, options) ​

Adicionado em: v15.0.0

  • type: <string> O uso pretendido da chave secreta gerada. Os valores atualmente aceitos são 'hmac' e 'aes'.

  • options: <Object>

    • length: <number> O tamanho em bits da chave a ser gerada.
    • Se type for 'hmac', o mínimo é 8 e o comprimento máximo é 2-1. Se o valor não for um múltiplo de 8, a chave gerada será truncada para Math.floor(length / 8).
    • Se type for 'aes', o comprimento deve ser um de 128, 192 ou 256.

  • Retorna: <KeyObject>

Gera sincronicamente uma nova chave secreta aleatória do length fornecido. O type determinará quais validações serão realizadas no length.

js
const { generateKeySync } = await import('node:crypto')

const key = generateKeySync('hmac', { length: 512 })
console.log(key.export().toString('hex')) // e89..........41e
js
const { generateKeySync } = require('node:crypto')

const key = generateKeySync('hmac', { length: 512 })
console.log(key.export().toString('hex')) // e89..........41e

O tamanho de uma chave HMAC gerada não deve exceder o tamanho do bloco da função hash subjacente. Consulte crypto.createHmac() para obter mais informações.

crypto.generatePrime(size[, options[, callback]]) ​

[Histórico]

VersãoMudanças
v18.0.0Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v15.8.0Adicionado em: v15.8.0

Gera um número primo pseudorrandômico de size bits.

Se options.safe for true, o número primo será um número primo seguro - ou seja, (prime - 1) / 2 também será um número primo.

Os parâmetros options.add e options.rem podem ser usados para impor requisitos adicionais, por exemplo, para Diffie-Hellman:

  • Se options.add e options.rem estiverem ambos definidos, o número primo satisfará a condição de que prime % add = rem.
  • Se apenas options.add estiver definido e options.safe não for true, o número primo satisfará a condição de que prime % add = 1.
  • Se apenas options.add estiver definido e options.safe estiver definido como true, o número primo satisfará, em vez disso, a condição de que prime % add = 3. Isso é necessário porque prime % add = 1 para options.add \> 2 contradiria a condição imposta por options.safe.
  • options.rem é ignorado se options.add não for fornecido.

Tanto options.add quanto options.rem devem ser codificados como sequências big-endian se fornecidos como um ArrayBuffer, SharedArrayBuffer, TypedArray, Buffer ou DataView.

Por padrão, o número primo é codificado como uma sequência big-endian de octetos em um <ArrayBuffer>. Se a opção bigint for true, um <bigint> é fornecido.

crypto.generatePrimeSync(size[, options]) ​

Adicionado em: v15.8.0

Gera um primo pseudoaleatório de size bits.

Se options.safe for true, o primo será um primo seguro - ou seja, (primo - 1) / 2 também será um primo.

Os parâmetros options.add e options.rem podem ser usados para impor requisitos adicionais, por exemplo, para Diffie-Hellman:

  • Se options.add e options.rem estiverem ambos definidos, o primo irá satisfazer a condição de que primo % add = rem.
  • Se apenas options.add estiver definido e options.safe não for true, o primo irá satisfazer a condição de que primo % add = 1.
  • Se apenas options.add estiver definido e options.safe estiver definido como true, o primo irá, em vez disso, satisfazer a condição de que primo % add = 3. Isto é necessário porque primo % add = 1 para options.add \> 2 iria contradizer a condição imposta por options.safe.
  • options.rem é ignorado se options.add não for dado.

Tanto options.add quanto options.rem devem ser codificados como sequências big-endian se forem fornecidos como um ArrayBuffer, SharedArrayBuffer, TypedArray, Buffer ou DataView.

Por padrão, o primo é codificado como uma sequência big-endian de octetos em um <ArrayBuffer>. Se a opção bigint for true, então um <bigint> é fornecido.

crypto.getCipherInfo(nameOrNid[, options]) ​

Adicionado em: v15.0.0

  • nameOrNid: <string> | <number> O nome ou nid da cifra para consultar.

  • options: <Object>

    • keyLength: <number> Um comprimento de chave de teste.
    • ivLength: <number> Um comprimento de IV de teste.

  • Retorna: <Object>

    • name <string> O nome da cifra
    • nid <number> O nid da cifra
    • blockSize <number> O tamanho do bloco da cifra em bytes. Esta propriedade é omitida quando mode é 'stream'.
    • ivLength <number> O comprimento esperado ou padrão do vetor de inicialização em bytes. Esta propriedade é omitida se a cifra não usar um vetor de inicialização.
    • keyLength <number> O comprimento de chave esperado ou padrão em bytes.
    • mode <string> O modo de cifra. Um de 'cbc', 'ccm', 'cfb', 'ctr', 'ecb', 'gcm', 'ocb', 'ofb', 'stream', 'wrap', 'xts'.

Retorna informações sobre uma determinada cifra.

Algumas cifras aceitam chaves e vetores de inicialização de comprimento variável. Por padrão, o método crypto.getCipherInfo() retornará os valores padrão para essas cifras. Para testar se um determinado comprimento de chave ou comprimento de iv é aceitável para uma determinada cifra, use as opções keyLength e ivLength. Se os valores fornecidos forem inaceitáveis, undefined será retornado.

crypto.getCiphers() ​

Adicionado em: v0.9.3

  • Retorna: <string[]> Um array com os nomes dos algoritmos de cifra suportados.
js
const { getCiphers } = await import('node:crypto')

console.log(getCiphers()) // ['aes-128-cbc', 'aes-128-ccm', ...]
js
const { getCiphers } = require('node:crypto')

console.log(getCiphers()) // ['aes-128-cbc', 'aes-128-ccm', ...]

crypto.getCurves() ​

Adicionado em: v2.3.0

  • Retorna: <string[]> Um array com os nomes das curvas elípticas suportadas.
js
const { getCurves } = await import('node:crypto')

console.log(getCurves()) // ['Oakley-EC2N-3', 'Oakley-EC2N-4', ...]
js
const { getCurves } = require('node:crypto')

console.log(getCurves()) // ['Oakley-EC2N-3', 'Oakley-EC2N-4', ...]

crypto.getDiffieHellman(groupName) ​

Adicionado em: v0.7.5

Cria um objeto de troca de chaves DiffieHellmanGroup predefinido. Os grupos suportados estão listados na documentação para DiffieHellmanGroup.

O objeto retornado imita a interface de objetos criados por crypto.createDiffieHellman(), mas não permitirá alterar as chaves (com diffieHellman.setPublicKey(), por exemplo). A vantagem de usar este método é que as partes não precisam gerar nem trocar um módulo de grupo antecipadamente, economizando tempo de processador e comunicação.

Exemplo (obtendo um segredo compartilhado):

js
const { getDiffieHellman } = await import('node:crypto')
const alice = getDiffieHellman('modp14')
const bob = getDiffieHellman('modp14')

alice.generateKeys()
bob.generateKeys()

const aliceSecret = alice.computeSecret(bob.getPublicKey(), null, 'hex')
const bobSecret = bob.computeSecret(alice.getPublicKey(), null, 'hex')

/* aliceSecret e bobSecret devem ser iguais */
console.log(aliceSecret === bobSecret)
js
const { getDiffieHellman } = require('node:crypto')

const alice = getDiffieHellman('modp14')
const bob = getDiffieHellman('modp14')

alice.generateKeys()
bob.generateKeys()

const aliceSecret = alice.computeSecret(bob.getPublicKey(), null, 'hex')
const bobSecret = bob.computeSecret(alice.getPublicKey(), null, 'hex')

/* aliceSecret e bobSecret devem ser iguais */
console.log(aliceSecret === bobSecret)

crypto.getFips() ​

Adicionado em: v10.0.0

  • Retorna: <number> 1 se e somente se um provedor criptográfico compatível com FIPS estiver em uso no momento, 0 caso contrário. Uma futura versão semver-major pode alterar o tipo de retorno desta API para um <boolean>.

crypto.getHashes() ​

Adicionado em: v0.9.3

  • Retorna: <string[]> Um array com os nomes dos algoritmos de hash suportados, como 'RSA-SHA256'. Algoritmos de hash também são chamados de algoritmos "digest".
js
const { getHashes } = await import('node:crypto')

console.log(getHashes()) // ['DSA', 'DSA-SHA', 'DSA-SHA1', ...]
js
const { getHashes } = require('node:crypto')

console.log(getHashes()) // ['DSA', 'DSA-SHA', 'DSA-SHA1', ...]

crypto.getRandomValues(typedArray) ​

Adicionado em: v17.4.0

Um alias conveniente para crypto.webcrypto.getRandomValues(). Esta implementação não está em conformidade com a especificação da Web Crypto, para escrever código compatível com a web, use crypto.webcrypto.getRandomValues() em vez disso.

crypto.hash(algorithm, data[, outputEncoding]) ​

Adicionado em: v21.7.0, v20.12.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1.2 - Candidato a lançamento

Um utilitário para criar resumos hash únicos de dados. Pode ser mais rápido do que crypto.createHash() baseado em objeto ao fazer hash de uma quantidade menor de dados (<= 5MB) que esteja prontamente disponível. Se os dados puderem ser grandes ou se forem transmitidos, ainda é recomendado usar crypto.createHash() em vez disso.

O algorithm depende dos algoritmos disponíveis suportados pela versão do OpenSSL na plataforma. Exemplos são 'sha256', 'sha512', etc. Em versões recentes do OpenSSL, openssl list -digest-algorithms exibirá os algoritmos de resumo disponíveis.

Exemplo:

js
const crypto = require('node:crypto')
const { Buffer } = require('node:buffer')

// Fazendo o hash de uma string e retornando o resultado como uma string codificada em hexadecimal.
const string = 'Node.js'
// 10b3493287f831e81a438811a1ffba01f8cec4b7
console.log(crypto.hash('sha1', string))

// Codifica uma string codificada em base64 em um Buffer, faz o hash e retorna
// o resultado como um buffer.
const base64 = 'Tm9kZS5qcw=='
// <Buffer 10 b3 49 32 87 f8 31 e8 1a 43 88 11 a1 ff ba 01 f8 ce c4 b7>
console.log(crypto.hash('sha1', Buffer.from(base64, 'base64'), 'buffer'))
js
import crypto from 'node:crypto'
import { Buffer } from 'node:buffer'

// Fazendo o hash de uma string e retornando o resultado como uma string codificada em hexadecimal.
const string = 'Node.js'
// 10b3493287f831e81a438811a1ffba01f8cec4b7
console.log(crypto.hash('sha1', string))

// Codifica uma string codificada em base64 em um Buffer, faz o hash e retorna
// o resultado como um buffer.
const base64 = 'Tm9kZS5qcw=='
// <Buffer 10 b3 49 32 87 f8 31 e8 1a 43 88 11 a1 ff ba 01 f8 ce c4 b7>
console.log(crypto.hash('sha1', Buffer.from(base64, 'base64'), 'buffer'))

crypto.hkdf(digest, ikm, salt, info, keylen, callback) ​

[Histórico]

VersãoMudanças
v18.0.0Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v18.8.0, v16.18.0O material de chave de entrada agora pode ter comprimento zero.
v15.0.0Adicionado em: v15.0.0

HKDF é uma função simples de derivação de chaves definida no RFC 5869. O ikm, salt e info fornecidos são usados com o digest para derivar uma chave de keylen bytes.

A função callback fornecida é chamada com dois argumentos: err e derivedKey. Se ocorrer um erro ao derivar a chave, err será definido; caso contrário, err será null. A derivedKey gerada com sucesso será passada para o callback como um <ArrayBuffer>. Um erro será lançado se algum dos argumentos de entrada especificar valores ou tipos inválidos.

js
import { Buffer } from 'node:buffer'
const { hkdf } = await import('node:crypto')

hkdf('sha512', 'key', 'salt', 'info', 64, (err, derivedKey) => {
  if (err) throw err
  console.log(Buffer.from(derivedKey).toString('hex')) // '24156e2...5391653'
})
js
const { hkdf } = require('node:crypto')
const { Buffer } = require('node:buffer')

hkdf('sha512', 'key', 'salt', 'info', 64, (err, derivedKey) => {
  if (err) throw err
  console.log(Buffer.from(derivedKey).toString('hex')) // '24156e2...5391653'
})

crypto.hkdfSync(digest, ikm, salt, info, keylen) ​

[Histórico]

VersãoMudanças
v18.8.0, v16.18.0O material de chave de entrada agora pode ter comprimento zero.
v15.0.0Adicionado em: v15.0.0

Fornece uma função síncrona de derivação de chave HKDF conforme definido em RFC 5869. O ikm, salt e info fornecidos são usados com o digest para derivar uma chave de keylen bytes.

A derivedKey gerada com sucesso será retornada como um <ArrayBuffer>.

Um erro será lançado se algum dos argumentos de entrada especificar valores ou tipos inválidos, ou se a chave derivada não puder ser gerada.

js
import { Buffer } from 'node:buffer'
const { hkdfSync } = await import('node:crypto')

const derivedKey = hkdfSync('sha512', 'key', 'salt', 'info', 64)
console.log(Buffer.from(derivedKey).toString('hex')) // '24156e2...5391653'
js
const { hkdfSync } = require('node:crypto')
const { Buffer } = require('node:buffer')

const derivedKey = hkdfSync('sha512', 'key', 'salt', 'info', 64)
console.log(Buffer.from(derivedKey).toString('hex')) // '24156e2...5391653'

crypto.pbkdf2(password, salt, iterations, keylen, digest, callback) ​

[Histórico]

VersãoMudanças
v18.0.0Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v15.0.0Os argumentos password e salt também podem ser instâncias de ArrayBuffer.
v14.0.0O parâmetro iterations agora está restrito a valores positivos. Versões anteriores tratavam outros valores como um.
v8.0.0O parâmetro digest agora é sempre obrigatório.
v6.0.0Chamar esta função sem passar o parâmetro digest agora está obsoleto e emitirá um aviso.
v6.0.0A codificação padrão para password se for uma string mudou de binary para utf8.
v0.5.5Adicionado em: v0.5.5

Fornece uma implementação assíncrona da Função de Derivação de Chave Baseada em Senha 2 (PBKDF2). Um algoritmo de resumo HMAC selecionado especificado por digest é aplicado para derivar uma chave do comprimento de byte solicitado (keylen) da password, salt e iterations.

A função callback fornecida é chamada com dois argumentos: err e derivedKey. Se ocorrer um erro ao derivar a chave, err será definido; caso contrário, err será null. Por padrão, o derivedKey gerado com sucesso será passado para o callback como um Buffer. Um erro será lançado se algum dos argumentos de entrada especificar valores ou tipos inválidos.

O argumento iterations deve ser um número definido o mais alto possível. Quanto maior o número de iterações, mais segura será a chave derivada, mas levará mais tempo para ser concluída.

O salt deve ser o mais exclusivo possível. Recomenda-se que um salt seja aleatório e tenha pelo menos 16 bytes de comprimento. Consulte NIST SP 800-132 para obter detalhes.

Ao passar strings para password ou salt, considere ressalvas ao usar strings como entradas para APIs criptográficas.

js
const { pbkdf2 } = await import('node:crypto')

pbkdf2('secret', 'salt', 100000, 64, 'sha512', (err, derivedKey) => {
  if (err) throw err
  console.log(derivedKey.toString('hex')) // '3745e48...08d59ae'
})
js
const { pbkdf2 } = require('node:crypto')

pbkdf2('secret', 'salt', 100000, 64, 'sha512', (err, derivedKey) => {
  if (err) throw err
  console.log(derivedKey.toString('hex')) // '3745e48...08d59ae'
})

Um array de funções de resumo suportadas pode ser recuperado usando crypto.getHashes().

Esta API usa o threadpool do libuv, que pode ter implicações de desempenho surpreendentes e negativas para algumas aplicações; consulte a documentação de UV_THREADPOOL_SIZE para mais informações.

crypto.pbkdf2Sync(password, salt, iterations, keylen, digest) ​

[Histórico]

VersãoMudanças
v14.0.0O parâmetro iterations agora é restrito a valores positivos. Versões anteriores tratavam outros valores como um.
v6.0.0Chamar esta função sem passar o parâmetro digest agora está obsoleto e emitirá um aviso.
v6.0.0A codificação padrão para password se for uma string foi alterada de binary para utf8.
v0.9.3Adicionado em: v0.9.3

Fornece uma implementação síncrona da Função de Derivação de Chave Baseada em Senha 2 (PBKDF2). Um algoritmo de resumo HMAC selecionado especificado por digest é aplicado para derivar uma chave do comprimento de byte solicitado (keylen) da password, salt e iterations.

Se ocorrer um erro, um Error será lançado, caso contrário, a chave derivada será retornada como um Buffer.

O argumento iterations deve ser um número definido o mais alto possível. Quanto maior o número de iterações, mais segura será a chave derivada, mas levará mais tempo para ser concluída.

O salt deve ser o mais exclusivo possível. Recomenda-se que um salt seja aleatório e tenha pelo menos 16 bytes de comprimento. Consulte NIST SP 800-132 para obter detalhes.

Ao passar strings para password ou salt, considere ressalvas ao usar strings como entradas para APIs criptográficas.

js
const { pbkdf2Sync } = await import('node:crypto')

const key = pbkdf2Sync('secret', 'salt', 100000, 64, 'sha512')
console.log(key.toString('hex')) // '3745e48...08d59ae'
js
const { pbkdf2Sync } = require('node:crypto')

const key = pbkdf2Sync('secret', 'salt', 100000, 64, 'sha512')
console.log(key.toString('hex')) // '3745e48...08d59ae'

Um array de funções de resumo suportadas pode ser recuperado usando crypto.getHashes().

crypto.privateDecrypt(privateKey, buffer) ​

[Histórico]

VersãoMudanças
v21.6.2, v20.11.1, v18.19.1O preenchimento RSA_PKCS1_PADDING foi desativado a menos que a compilação do OpenSSL suporte rejeição implícita.
v15.0.0Adicionado string, ArrayBuffer e CryptoKey como tipos de chave permitidos. O oaepLabel pode ser um ArrayBuffer. O buffer pode ser uma string ou ArrayBuffer. Todos os tipos que aceitam buffers são limitados a um máximo de 2 ** 31 - 1 bytes.
v12.11.0A opção oaepLabel foi adicionada.
v12.9.0A opção oaepHash foi adicionada.
v11.6.0Esta função agora suporta objetos de chave.
v0.11.14Adicionado em: v0.11.14

Descriptografa buffer com privateKey. buffer foi criptografado anteriormente usando a chave pública correspondente, por exemplo, usando crypto.publicEncrypt().

Se privateKey não for um KeyObject, esta função se comporta como se privateKey tivesse sido passado para crypto.createPrivateKey(). Se for um objeto, a propriedade padding pode ser passada. Caso contrário, esta função usa RSA_PKCS1_OAEP_PADDING.

O uso de crypto.constants.RSA_PKCS1_PADDING em crypto.privateDecrypt() requer que o OpenSSL suporte a rejeição implícita (rsa_pkcs1_implicit_rejection). Se a versão do OpenSSL usada pelo Node.js não suportar esse recurso, tentar usar RSA_PKCS1_PADDING falhará.

crypto.privateEncrypt(privateKey, buffer) ​

[Histórico]

VersãoMudanças
v15.0.0Adicionados string, ArrayBuffer e CryptoKey como tipos de chave permitidos. A senha pode ser um ArrayBuffer. O buffer pode ser uma string ou ArrayBuffer. Todos os tipos que aceitam buffers são limitados a um máximo de 2 ** 31 - 1 bytes.
v11.6.0Esta função agora suporta objetos de chave.
v1.1.0Adicionado em: v1.1.0

Criptografa buffer com privateKey. Os dados retornados podem ser descriptografados usando a chave pública correspondente, por exemplo, usando crypto.publicDecrypt().

Se privateKey não for um KeyObject, esta função se comporta como se privateKey tivesse sido passado para crypto.createPrivateKey(). Se for um objeto, a propriedade padding pode ser passada. Caso contrário, esta função usa RSA_PKCS1_PADDING.

crypto.publicDecrypt(key, buffer) ​

[Histórico]

VersãoMudanças
v15.0.0Adicionado string, ArrayBuffer e CryptoKey como tipos de chave aceitáveis. A senha pode ser um ArrayBuffer. O buffer pode ser uma string ou ArrayBuffer. Todos os tipos que aceitam buffers são limitados a um máximo de 2 ** 31 - 1 bytes.
v11.6.0Esta função agora suporta objetos de chave.
v1.1.0Adicionado em: v1.1.0

Descriptografa buffer com key. buffer foi criptografado anteriormente usando a chave privada correspondente, por exemplo, usando crypto.privateEncrypt().

Se key não for um KeyObject, esta função se comporta como se key tivesse sido passada para crypto.createPublicKey(). Se for um objeto, a propriedade padding pode ser passada. Caso contrário, esta função usa RSA_PKCS1_PADDING.

Como as chaves públicas RSA podem ser derivadas de chaves privadas, uma chave privada pode ser passada em vez de uma chave pública.

crypto.publicEncrypt(key, buffer) ​

[Histórico]

VersãoMudanças
v15.0.0Adicionadas string, ArrayBuffer e CryptoKey como tipos de chave permitidos. oaepLabel e passphrase podem ser ArrayBuffers. O buffer pode ser uma string ou ArrayBuffer. Todos os tipos que aceitam buffers são limitados a um máximo de 2 ** 31 - 1 bytes.
v12.11.0A opção oaepLabel foi adicionada.
v12.9.0A opção oaepHash foi adicionada.
v11.6.0Esta função agora suporta objetos de chave.
v0.11.14Adicionado em: v0.11.14

Criptografa o conteúdo de buffer com key e retorna um novo Buffer com o conteúdo criptografado. Os dados retornados podem ser descriptografados usando a chave privada correspondente, por exemplo, usando crypto.privateDecrypt().

Se key não for um KeyObject, esta função se comporta como se key tivesse sido passada para crypto.createPublicKey(). Se for um objeto, a propriedade padding pode ser passada. Caso contrário, esta função usa RSA_PKCS1_OAEP_PADDING.

Como as chaves públicas RSA podem ser derivadas de chaves privadas, uma chave privada pode ser passada em vez de uma chave pública.

crypto.randomBytes(size[, callback]) ​

[Histórico]

VersãoMudanças
v18.0.0Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v9.0.0Passar null como o argumento callback agora lança ERR_INVALID_CALLBACK.
v0.5.8Adicionado em: v0.5.8

Gera dados pseudoaleatórios criptograficamente fortes. O argumento size é um número que indica o número de bytes a serem gerados.

Se uma função callback for fornecida, os bytes serão gerados assincronamente e a função callback será invocada com dois argumentos: err e buf. Se ocorrer um erro, err será um objeto Error; caso contrário, será null. O argumento buf é um Buffer contendo os bytes gerados.

js
// Assíncrono
const { randomBytes } = await import('node:crypto')

randomBytes(256, (err, buf) => {
  if (err) throw err
  console.log(`${buf.length} bytes de dados aleatórios: ${buf.toString('hex')}`)
})
js
// Assíncrono
const { randomBytes } = require('node:crypto')

randomBytes(256, (err, buf) => {
  if (err) throw err
  console.log(`${buf.length} bytes de dados aleatórios: ${buf.toString('hex')}`)
})

Se a função callback não for fornecida, os bytes aleatórios serão gerados sincronicamente e retornados como um Buffer. Um erro será lançado se houver um problema ao gerar os bytes.

js
// Síncrono
const { randomBytes } = await import('node:crypto')

const buf = randomBytes(256)
console.log(`${buf.length} bytes de dados aleatórios: ${buf.toString('hex')}`)
js
// Síncrono
const { randomBytes } = require('node:crypto')

const buf = randomBytes(256)
console.log(`${buf.length} bytes de dados aleatórios: ${buf.toString('hex')}`)

O método crypto.randomBytes() não será concluído até que haja entropia suficiente disponível. Isso normalmente nunca deve levar mais do que alguns milissegundos. A única vez em que a geração dos bytes aleatórios pode concebivelmente bloquear por um período de tempo mais longo é logo após a inicialização, quando todo o sistema ainda está com pouca entropia.

Esta API usa o pool de threads do libuv, o que pode ter implicações de desempenho surpreendentes e negativas para algumas aplicações; veja a documentação UV_THREADPOOL_SIZE para mais informações.

A versão assíncrona de crypto.randomBytes() é realizada em uma única solicitação de pool de threads. Para minimizar a variação do comprimento da tarefa do pool de threads, particione grandes solicitações randomBytes ao fazer isso como parte do atendimento a uma solicitação do cliente.

crypto.randomFill(buffer[, offset][, size], callback) ​

[Histórico]

VersãoMudanças
v18.0.0Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v9.0.0O argumento buffer pode ser qualquer TypedArray ou DataView.
v7.10.0, v6.13.0Adicionado em: v7.10.0, v6.13.0

Esta função é semelhante a crypto.randomBytes(), mas requer que o primeiro argumento seja um Buffer que será preenchido. Também requer que um callback seja passado.

Se a função callback não for fornecida, um erro será lançado.

js
import { Buffer } from 'node:buffer'
const { randomFill } = await import('node:crypto')

const buf = Buffer.alloc(10)
randomFill(buf, (err, buf) => {
  if (err) throw err
  console.log(buf.toString('hex'))
})

randomFill(buf, 5, (err, buf) => {
  if (err) throw err
  console.log(buf.toString('hex'))
})

// O acima é equivalente ao seguinte:
randomFill(buf, 5, 5, (err, buf) => {
  if (err) throw err
  console.log(buf.toString('hex'))
})
js
const { randomFill } = require('node:crypto')
const { Buffer } = require('node:buffer')

const buf = Buffer.alloc(10)
randomFill(buf, (err, buf) => {
  if (err) throw err
  console.log(buf.toString('hex'))
})

randomFill(buf, 5, (err, buf) => {
  if (err) throw err
  console.log(buf.toString('hex'))
})

// O acima é equivalente ao seguinte:
randomFill(buf, 5, 5, (err, buf) => {
  if (err) throw err
  console.log(buf.toString('hex'))
})

Qualquer instância de ArrayBuffer, TypedArray ou DataView pode ser passada como buffer.

Embora isso inclua instâncias de Float32Array e Float64Array, esta função não deve ser usada para gerar números de ponto flutuante aleatórios. O resultado pode conter +Infinity, -Infinity e NaN, e mesmo que o array contenha apenas números finitos, eles não são extraídos de uma distribuição aleatória uniforme e não têm limites inferiores ou superiores significativos.

js
import { Buffer } from 'node:buffer'
const { randomFill } = await import('node:crypto')

const a = new Uint32Array(10)
randomFill(a, (err, buf) => {
  if (err) throw err
  console.log(Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength).toString('hex'))
})

const b = new DataView(new ArrayBuffer(10))
randomFill(b, (err, buf) => {
  if (err) throw err
  console.log(Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength).toString('hex'))
})

const c = new ArrayBuffer(10)
randomFill(c, (err, buf) => {
  if (err) throw err
  console.log(Buffer.from(buf).toString('hex'))
})
js
const { randomFill } = require('node:crypto')
const { Buffer } = require('node:buffer')

const a = new Uint32Array(10)
randomFill(a, (err, buf) => {
  if (err) throw err
  console.log(Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength).toString('hex'))
})

const b = new DataView(new ArrayBuffer(10))
randomFill(b, (err, buf) => {
  if (err) throw err
  console.log(Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength).toString('hex'))
})

const c = new ArrayBuffer(10)
randomFill(c, (err, buf) => {
  if (err) throw err
  console.log(Buffer.from(buf).toString('hex'))
})

Esta API usa o threadpool do libuv, que pode ter implicações de desempenho surpreendentes e negativas para algumas aplicações; consulte a documentação UV_THREADPOOL_SIZE para obter mais informações.

A versão assíncrona de crypto.randomFill() é realizada em uma única solicitação de threadpool. Para minimizar a variação do comprimento da tarefa do threadpool, particione grandes solicitações de randomFill ao fazer isso como parte do atendimento a uma solicitação do cliente.

crypto.randomFillSync(buffer[, offset][, size]) ​

[Histórico]

VersãoMudanças
v9.0.0O argumento buffer pode ser qualquer TypedArray ou DataView.
v7.10.0, v6.13.0Adicionado em: v7.10.0, v6.13.0

Versão síncrona de crypto.randomFill().

js
import { Buffer } from 'node:buffer'
const { randomFillSync } = await import('node:crypto')

const buf = Buffer.alloc(10)
console.log(randomFillSync(buf).toString('hex'))

randomFillSync(buf, 5)
console.log(buf.toString('hex'))

// O acima é equivalente ao seguinte:
randomFillSync(buf, 5, 5)
console.log(buf.toString('hex'))
js
const { randomFillSync } = require('node:crypto')
const { Buffer } = require('node:buffer')

const buf = Buffer.alloc(10)
console.log(randomFillSync(buf).toString('hex'))

randomFillSync(buf, 5)
console.log(buf.toString('hex'))

// O acima é equivalente ao seguinte:
randomFillSync(buf, 5, 5)
console.log(buf.toString('hex'))

Qualquer instância de ArrayBuffer, TypedArray ou DataView pode ser passada como buffer.

js
import { Buffer } from 'node:buffer'
const { randomFillSync } = await import('node:crypto')

const a = new Uint32Array(10)
console.log(Buffer.from(randomFillSync(a).buffer, a.byteOffset, a.byteLength).toString('hex'))

const b = new DataView(new ArrayBuffer(10))
console.log(Buffer.from(randomFillSync(b).buffer, b.byteOffset, b.byteLength).toString('hex'))

const c = new ArrayBuffer(10)
console.log(Buffer.from(randomFillSync(c)).toString('hex'))
js
const { randomFillSync } = require('node:crypto')
const { Buffer } = require('node:buffer')

const a = new Uint32Array(10)
console.log(Buffer.from(randomFillSync(a).buffer, a.byteOffset, a.byteLength).toString('hex'))

const b = new DataView(new ArrayBuffer(10))
console.log(Buffer.from(randomFillSync(b).buffer, b.byteOffset, b.byteLength).toString('hex'))

const c = new ArrayBuffer(10)
console.log(Buffer.from(randomFillSync(c)).toString('hex'))

crypto.randomInt([min, ]max[, callback]) ​

[Histórico]

VersãoMudanças
v18.0.0Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v14.10.0, v12.19.0Adicionado em: v14.10.0, v12.19.0
  • min <integer> Início do intervalo aleatório (inclusivo). Padrão: 0.
  • max <integer> Fim do intervalo aleatório (exclusivo).
  • callback <Function> function(err, n) {}.

Retorna um inteiro aleatório n tal que min \<= n \< max. Esta implementação evita o viés de módulo.

O intervalo (max - min) deve ser menor que 2. min e max devem ser inteiros seguros.

Se a função callback não for fornecida, o inteiro aleatório é gerado de forma síncrona.

js
// Assíncrono
const { randomInt } = await import('node:crypto')

randomInt(3, (err, n) => {
  if (err) throw err
  console.log(`Número aleatório escolhido de (0, 1, 2): ${n}`)
})
js
// Assíncrono
const { randomInt } = require('node:crypto')

randomInt(3, (err, n) => {
  if (err) throw err
  console.log(`Número aleatório escolhido de (0, 1, 2): ${n}`)
})
js
// Síncrono
const { randomInt } = await import('node:crypto')

const n = randomInt(3)
console.log(`Número aleatório escolhido de (0, 1, 2): ${n}`)
js
// Síncrono
const { randomInt } = require('node:crypto')

const n = randomInt(3)
console.log(`Número aleatório escolhido de (0, 1, 2): ${n}`)
js
// Com argumento `min`
const { randomInt } = await import('node:crypto')

const n = randomInt(1, 7)
console.log(`O dado rolou: ${n}`)
js
// Com argumento `min`
const { randomInt } = require('node:crypto')

const n = randomInt(1, 7)
console.log(`O dado rolou: ${n}`)

crypto.randomUUID([options]) ​

Adicionado em: v15.6.0, v14.17.0

  • options <Objeto>

    • disableEntropyCache <boolean> Por padrão, para melhorar o desempenho, o Node.js gera e armazena em cache dados aleatórios suficientes para gerar até 128 UUIDs aleatórios. Para gerar um UUID sem usar o cache, defina disableEntropyCache como true. Padrão: false.

  • Retorna: <string>

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

crypto.scrypt(password, salt, keylen[, options], callback) ​

[Histórico]

VersãoMudanças
v18.0.0Passar um callback inválido para o argumento callback agora gera ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v15.0.0Os argumentos password e salt também podem ser instâncias ArrayBuffer.
v12.8.0, v10.17.0O valor maxmem agora pode ser qualquer inteiro seguro.
v10.9.0Os nomes das opções cost, blockSize e parallelization foram adicionados.
v10.5.0Adicionado em: v10.5.0

Fornece uma implementação scrypt assíncrona. Scrypt é uma função de derivação de chave baseada em senha que é projetada para ser computacionalmente e em termos de memória dispendiosa, a fim de tornar ataques de força bruta não recompensadores.

O salt deve ser o mais exclusivo possível. Recomenda-se que um salt seja aleatório e tenha pelo menos 16 bytes de comprimento. Veja NIST SP 800-132 para detalhes.

Ao passar strings para password ou salt, por favor, considere ressalvas ao usar strings como entradas para APIs criptográficas.

A função callback é chamada com dois argumentos: err e derivedKey. err é um objeto de exceção quando a derivação de chave falha, caso contrário, err é null. derivedKey é passada para o callback como um Buffer.

Uma exceção é lançada quando qualquer um dos argumentos de entrada especifica valores ou tipos inválidos.

js
const { scrypt } = await import('node:crypto')

// Usando os padrões de fábrica.
scrypt('password', 'salt', 64, (err, derivedKey) => {
  if (err) throw err
  console.log(derivedKey.toString('hex')) // '3745e48...08d59ae'
})
// Usando um parâmetro N personalizado. Deve ser uma potência de dois.
scrypt('password', 'salt', 64, { N: 1024 }, (err, derivedKey) => {
  if (err) throw err
  console.log(derivedKey.toString('hex')) // '3745e48...aa39b34'
})
js
const { scrypt } = require('node:crypto')

// Usando os padrões de fábrica.
scrypt('password', 'salt', 64, (err, derivedKey) => {
  if (err) throw err
  console.log(derivedKey.toString('hex')) // '3745e48...08d59ae'
})
// Usando um parâmetro N personalizado. Deve ser uma potência de dois.
scrypt('password', 'salt', 64, { N: 1024 }, (err, derivedKey) => {
  if (err) throw err
  console.log(derivedKey.toString('hex')) // '3745e48...aa39b34'
})

crypto.scryptSync(password, salt, keylen[, options]) ​

[Histórico]

VersãoMudanças
v12.8.0, v10.17.0O valor maxmem agora pode ser qualquer inteiro seguro.
v10.9.0Os nomes das opções cost, blockSize e parallelization foram adicionados.
v10.5.0Adicionado em: v10.5.0

Fornece uma implementação síncrona de scrypt. Scrypt é uma função de derivação de chave baseada em senha que é projetada para ser dispendiosa computacionalmente e em termos de memória, a fim de tornar os ataques de força bruta pouco recompensadores.

O salt deve ser o mais exclusivo possível. Recomenda-se que um salt seja aleatório e tenha pelo menos 16 bytes de comprimento. Consulte NIST SP 800-132 para obter detalhes.

Ao passar strings para password ou salt, considere ressalvas ao usar strings como entradas para APIs criptográficas.

Uma exceção é lançada quando a derivação da chave falha, caso contrário, a chave derivada é retornada como um Buffer.

Uma exceção é lançada quando qualquer um dos argumentos de entrada especifica valores ou tipos inválidos.

js
const { scryptSync } = await import('node:crypto')
// Usando os valores padrão de fábrica.

const key1 = scryptSync('password', 'salt', 64)
console.log(key1.toString('hex')) // '3745e48...08d59ae'
// Usando um parâmetro N personalizado. Deve ser uma potência de dois.
const key2 = scryptSync('password', 'salt', 64, { N: 1024 })
console.log(key2.toString('hex')) // '3745e48...aa39b34'
js
const { scryptSync } = require('node:crypto')
// Usando os valores padrão de fábrica.

const key1 = scryptSync('password', 'salt', 64)
console.log(key1.toString('hex')) // '3745e48...08d59ae'
// Usando um parâmetro N personalizado. Deve ser uma potência de dois.
const key2 = scryptSync('password', 'salt', 64, { N: 1024 })
console.log(key2.toString('hex')) // '3745e48...aa39b34'

crypto.secureHeapUsed() ​

Adicionado em: v15.6.0

  • Retorna: <Object>
    • total <number> O tamanho total do heap seguro alocado, conforme especificado usando o sinalizador de linha de comando --secure-heap=n.
    • min <number> A alocação mínima do heap seguro, conforme especificado usando o sinalizador de linha de comando --secure-heap-min.
    • used <number> O número total de bytes atualmente alocados do heap seguro.
    • utilization <number> A razão calculada de used para total de bytes alocados.

crypto.setEngine(engine[, flags]) ​

[Histórico]

VersãoMudanças
v22.4.0, v20.16.0O suporte a mecanismos personalizados no OpenSSL 3 está obsoleto.
v0.11.11Adicionado em: v0.11.11

Carrega e define o engine para algumas ou todas as funções OpenSSL (selecionadas por flags). O suporte para mecanismos personalizados no OpenSSL está obsoleto a partir do OpenSSL 3.

engine pode ser um id ou um caminho para a biblioteca compartilhada do mecanismo.

O argumento opcional flags usa ENGINE_METHOD_ALL por padrão. flags é um campo de bits que usa um ou uma mistura dos seguintes flags (definidos em crypto.constants):

  • crypto.constants.ENGINE_METHOD_RSA
  • crypto.constants.ENGINE_METHOD_DSA
  • crypto.constants.ENGINE_METHOD_DH
  • crypto.constants.ENGINE_METHOD_RAND
  • crypto.constants.ENGINE_METHOD_EC
  • crypto.constants.ENGINE_METHOD_CIPHERS
  • crypto.constants.ENGINE_METHOD_DIGESTS
  • crypto.constants.ENGINE_METHOD_PKEY_METHS
  • crypto.constants.ENGINE_METHOD_PKEY_ASN1_METHS
  • crypto.constants.ENGINE_METHOD_ALL
  • crypto.constants.ENGINE_METHOD_NONE

crypto.setFips(bool) ​

Adicionado em: v10.0.0

  • bool <boolean> true para habilitar o modo FIPS.

Habilita o provedor criptográfico compatível com FIPS em uma build do Node.js habilitada para FIPS. Lança um erro se o modo FIPS não estiver disponível.

crypto.sign(algorithm, data, key[, callback]) ​

[Histórico]

VersãoMudanças
v18.0.0Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v15.12.0Argumento de callback opcional adicionado.
v13.2.0, v12.16.0Esta função agora suporta assinaturas IEEE-P1363 DSA e ECDSA.
v12.0.0Adicionado em: v12.0.0

Calcula e retorna a assinatura para data usando a chave privada e o algoritmo fornecidos. Se algorithm for null ou undefined, então o algoritmo depende do tipo de chave (especialmente Ed25519 e Ed448).

Se key não for um KeyObject, esta função se comporta como se key tivesse sido passado para crypto.createPrivateKey(). Se for um objeto, as seguintes propriedades adicionais podem ser passadas:

  • dsaEncoding <string> Para DSA e ECDSA, esta opção especifica o formato da assinatura gerada. Pode ser um dos seguintes:

    • 'der' (padrão): estrutura de assinatura ASN.1 codificada em DER codificando (r, s).
    • 'ieee-p1363': Formato de assinatura r || s conforme proposto no IEEE-P1363.

  • padding <integer> Valor de preenchimento opcional para RSA, um dos seguintes:

    • crypto.constants.RSA_PKCS1_PADDING (padrão)
    • crypto.constants.RSA_PKCS1_PSS_PADDING

RSA_PKCS1_PSS_PADDING usará MGF1 com a mesma função hash usada para assinar a mensagem, conforme especificado na seção 3.1 do RFC 4055.

  • saltLength <integer> Comprimento do salt para quando o preenchimento é RSA_PKCS1_PSS_PADDING. O valor especial crypto.constants.RSA_PSS_SALTLEN_DIGEST define o comprimento do salt para o tamanho do digest, crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN (padrão) define-o para o valor máximo permitido.

Se a função callback for fornecida, esta função usa o threadpool do libuv.

crypto.subtle ​

Adicionado em: v17.4.0

Um alias conveniente para crypto.webcrypto.subtle.

crypto.timingSafeEqual(a, b) ​

[Histórico]

VersãoMudanças
v15.0.0Os argumentos a e b também podem ser ArrayBuffer.
v6.6.0Adicionado em: v6.6.0

Esta função compara os bytes subjacentes que representam as instâncias ArrayBuffer, TypedArray ou DataView fornecidas usando um algoritmo de tempo constante.

Esta função não vaza informações de tempo que permitiriam a um invasor adivinhar um dos valores. Isso é adequado para comparar digests HMAC ou valores secretos, como cookies de autenticação ou URLs de capacidade.

a e b devem ser ambos Buffers, TypedArrays ou DataViews, e devem ter o mesmo comprimento de byte. Um erro é lançado se a e b tiverem comprimentos de byte diferentes.

Se pelo menos um de a e b for um TypedArray com mais de um byte por entrada, como Uint16Array, o resultado será calculado usando a ordem de byte da plataforma.

Quando ambas as entradas são Float32Arrays ou Float64Arrays, esta função pode retornar resultados inesperados devido à codificação IEEE 754 de números de ponto flutuante. Em particular, nem x === y nem Object.is(x, y) implica que as representações de byte de dois números de ponto flutuante x e y são iguais.

O uso de crypto.timingSafeEqual não garante que o código circundante seja seguro em termos de tempo. Deve-se ter cuidado para garantir que o código circundante não introduza vulnerabilidades de tempo.

crypto.verify(algorithm, data, key, signature[, callback]) ​

[Histórico]

VersãoMudanças
v18.0.0Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v15.12.0Argumento de callback opcional adicionado.
v15.0.0Os argumentos data, key e signature também podem ser ArrayBuffer.
v13.2.0, v12.16.0Esta função agora suporta assinaturas IEEE-P1363 DSA e ECDSA.
v12.0.0Adicionado em: v12.0.0

Verifica a assinatura fornecida para data usando a chave e o algoritmo fornecidos. Se algorithm for null ou undefined, o algoritmo depende do tipo de chave (especialmente Ed25519 e Ed448).

Se key não for um KeyObject, esta função se comporta como se key tivesse sido passado para crypto.createPublicKey(). Se for um objeto, as seguintes propriedades adicionais podem ser passadas:

  • dsaEncoding <string> Para DSA e ECDSA, esta opção especifica o formato da assinatura. Pode ser um dos seguintes:

    • 'der' (padrão): Estrutura de assinatura ASN.1 com codificação DER codificando (r, s).
    • 'ieee-p1363': Formato de assinatura r || s conforme proposto no IEEE-P1363.

  • padding <integer> Valor de preenchimento opcional para RSA, um dos seguintes:

    • crypto.constants.RSA_PKCS1_PADDING (padrão)
    • crypto.constants.RSA_PKCS1_PSS_PADDING

RSA_PKCS1_PSS_PADDING usará MGF1 com a mesma função de hash usada para assinar a mensagem, conforme especificado na seção 3.1 de RFC 4055.

  • saltLength <integer> Comprimento do salt para quando o preenchimento for RSA_PKCS1_PSS_PADDING. O valor especial crypto.constants.RSA_PSS_SALTLEN_DIGEST define o comprimento do salt para o tamanho do resumo, crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN (padrão) o define para o valor máximo permitido.

O argumento signature é a assinatura previamente calculada para os data.

Como as chaves públicas podem ser derivadas de chaves privadas, uma chave privada ou uma chave pública pode ser passada para key.

Se a função callback for fornecida, esta função usa o threadpool do libuv.

crypto.webcrypto ​

Adicionado em: v15.0.0

Tipo: <Crypto> Uma implementação do padrão da Web Crypto API.

Consulte a documentação da Web Crypto API para obter detalhes.

Notas ​

Usando strings como entradas para APIs criptográficas ​

Por razões históricas, muitas APIs criptográficas fornecidas pelo Node.js aceitam strings como entradas onde o algoritmo criptográfico subjacente funciona em sequências de bytes. Esses exemplos incluem textos simples, textos cifrados, chaves simétricas, vetores de inicialização, senhas, salts, tags de autenticação e dados adicionais autenticados.

Ao passar strings para APIs criptográficas, considere os seguintes fatores.

  • Nem todas as sequências de bytes são strings UTF-8 válidas. Portanto, quando uma sequência de bytes de comprimento n é derivada de uma string, sua entropia é geralmente menor do que a entropia de uma sequência de n bytes aleatória ou pseudoaleatória. Por exemplo, nenhuma string UTF-8 resultará na sequência de bytes c0 af. Chaves secretas devem quase exclusivamente ser sequências de bytes aleatórias ou pseudoaleatórias.
  • Da mesma forma, ao converter sequências de bytes aleatórias ou pseudoaleatórias em strings UTF-8, subsequências que não representam pontos de código válidos podem ser substituídas pelo caractere de substituição Unicode (U+FFFD). A representação de bytes da string Unicode resultante pode, portanto, não ser igual à sequência de bytes da qual a string foi criada. As saídas de cifras, funções de hash, algoritmos de assinatura e funções de derivação de chave são sequências de bytes pseudoaleatórias e não devem ser usadas como strings Unicode.
  • Quando as strings são obtidas da entrada do usuário, alguns caracteres Unicode podem ser representados de várias maneiras equivalentes que resultam em sequências de bytes diferentes. Por exemplo, ao passar uma senha de usuário para uma função de derivação de chave, como PBKDF2 ou scrypt, o resultado da função de derivação de chave depende de se a string usa caracteres compostos ou decompostos. O Node.js não normaliza as representações de caracteres. Os desenvolvedores devem considerar o uso de String.prototype.normalize() nas entradas do usuário antes de passá-las para APIs criptográficas.

API de streams legada (anterior ao Node.js 0.10) ​

O módulo Crypto foi adicionado ao Node.js antes que houvesse o conceito de uma API Stream unificada e antes que houvesse objetos Buffer para lidar com dados binários. Assim, muitas classes crypto têm métodos que não são normalmente encontrados em outras classes Node.js que implementam a API de streams (por exemplo, update(), final() ou digest()). Além disso, muitos métodos aceitavam e retornavam strings codificadas em 'latin1' por padrão, em vez de Buffers. Esse padrão foi alterado após o Node.js v0.8 para usar objetos Buffer por padrão.

Suporte para algoritmos fracos ou comprometidos ​

O módulo node:crypto ainda suporta alguns algoritmos que já estão comprometidos e não são recomendados para uso. A API também permite o uso de cifras e hashes com um tamanho de chave pequeno, que são muito fracos para uso seguro.

Os usuários devem assumir total responsabilidade pela seleção do algoritmo criptográfico e do tamanho da chave de acordo com seus requisitos de segurança.

Com base nas recomendações do NIST SP 800-131A:

  • MD5 e SHA-1 não são mais aceitáveis onde a resistência a colisões é necessária, como assinaturas digitais.
  • Recomenda-se que a chave usada com algoritmos RSA, DSA e DH tenha pelo menos 2048 bits e a da curva de ECDSA e ECDH pelo menos 224 bits, para serem seguras para uso por vários anos.
  • Os grupos DH de modp1, modp2 e modp5 têm um tamanho de chave menor que 2048 bits e não são recomendados.

Consulte a referência para outras recomendações e detalhes.

Alguns algoritmos que têm fraquezas conhecidas e são de pouca relevância na prática estão disponíveis apenas por meio do provedor legado, que não está habilitado por padrão.

Modo CCM ​

CCM é um dos algoritmos AEAD suportados. Aplicativos que usam este modo devem seguir certas restrições ao usar a API de cifra:

  • O comprimento da tag de autenticação deve ser especificado durante a criação da cifra definindo a opção authTagLength e deve ser um de 4, 6, 8, 10, 12, 14 ou 16 bytes.
  • O comprimento do vetor de inicialização (nonce) N deve estar entre 7 e 13 bytes (7 ≤ N ≤ 13).
  • O comprimento do texto sem formatação é limitado a 2 ** (8 * (15 - N)) bytes.
  • Ao descriptografar, a tag de autenticação deve ser definida via setAuthTag() antes de chamar update(). Caso contrário, a descriptografia falhará e final() lançará um erro em conformidade com a seção 2.6 de RFC 3610.
  • O uso de métodos de stream como write(data), end(data) ou pipe() no modo CCM pode falhar, pois o CCM não pode lidar com mais de um bloco de dados por instância.
  • Ao passar dados autenticados adicionais (AAD), o comprimento da mensagem real em bytes deve ser passado para setAAD() por meio da opção plaintextLength. Muitas bibliotecas de criptografia incluem a tag de autenticação no texto cifrado, o que significa que elas produzem textos cifrados do comprimento plaintextLength + authTagLength. O Node.js não inclui a tag de autenticação, portanto, o comprimento do texto cifrado é sempre plaintextLength. Isso não é necessário se nenhum AAD for usado.
  • Como o CCM processa toda a mensagem de uma vez, update() deve ser chamado exatamente uma vez.
  • Mesmo que chamar update() seja suficiente para criptografar/descriptografar a mensagem, os aplicativos devem chamar final() para calcular ou verificar a tag de autenticação.
js
import { Buffer } from 'node:buffer'
const { createCipheriv, createDecipheriv, randomBytes } = await import('node:crypto')

const key = 'keykeykeykeykeykeykeykey'
const nonce = randomBytes(12)

const aad = Buffer.from('0123456789', 'hex')

const cipher = createCipheriv('aes-192-ccm', key, nonce, {
  authTagLength: 16,
})
const plaintext = 'Hello world'
cipher.setAAD(aad, {
  plaintextLength: Buffer.byteLength(plaintext),
})
const ciphertext = cipher.update(plaintext, 'utf8')
cipher.final()
const tag = cipher.getAuthTag()

// Agora transmita { ciphertext, nonce, tag }.

const decipher = createDecipheriv('aes-192-ccm', key, nonce, {
  authTagLength: 16,
})
decipher.setAuthTag(tag)
decipher.setAAD(aad, {
  plaintextLength: ciphertext.length,
})
const receivedPlaintext = decipher.update(ciphertext, null, 'utf8')

try {
  decipher.final()
} catch (err) {
  throw new Error('Falha na autenticação!', { cause: err })
}

console.log(receivedPlaintext)
js
const { Buffer } = require('node:buffer')
const { createCipheriv, createDecipheriv, randomBytes } = require('node:crypto')

const key = 'keykeykeykeykeykeykeykey'
const nonce = randomBytes(12)

const aad = Buffer.from('0123456789', 'hex')

const cipher = createCipheriv('aes-192-ccm', key, nonce, {
  authTagLength: 16,
})
const plaintext = 'Hello world'
cipher.setAAD(aad, {
  plaintextLength: Buffer.byteLength(plaintext),
})
const ciphertext = cipher.update(plaintext, 'utf8')
cipher.final()
const tag = cipher.getAuthTag()

// Agora transmita { ciphertext, nonce, tag }.

const decipher = createDecipheriv('aes-192-ccm', key, nonce, {
  authTagLength: 16,
})
decipher.setAuthTag(tag)
decipher.setAAD(aad, {
  plaintextLength: ciphertext.length,
})
const receivedPlaintext = decipher.update(ciphertext, null, 'utf8')

try {
  decipher.final()
} catch (err) {
  throw new Error('Falha na autenticação!', { cause: err })
}

console.log(receivedPlaintext)

Modo FIPS ​

Ao usar o OpenSSL 3, o Node.js suporta FIPS 140-2 quando usado com um provedor OpenSSL 3 apropriado, como o provedor FIPS do OpenSSL 3 que pode ser instalado seguindo as instruções no arquivo README do FIPS do OpenSSL.

Para suporte a FIPS no Node.js, você precisará de:

  • Um provedor OpenSSL 3 FIPS instalado corretamente.
  • Um arquivo de configuração do módulo FIPS do OpenSSL 3.
  • Um arquivo de configuração do OpenSSL 3 que referencia o arquivo de configuração do módulo FIPS.

O Node.js precisará ser configurado com um arquivo de configuração do OpenSSL que aponte para o provedor FIPS. Um exemplo de arquivo de configuração é este:

text
nodejs_conf = nodejs_init

.include /<caminho absoluto>/fipsmodule.cnf

[nodejs_init]
providers = provider_sect

[provider_sect]
default = default_sect
# O nome da seção fips deve corresponder ao nome da seção dentro do {#the-fips-section-name-should-match-the-section-name-inside-the}
# fipsmodule.cnf incluído.
fips = fips_sect

[default_sect]
activate = 1

onde fipsmodule.cnf é o arquivo de configuração do módulo FIPS gerado a partir da etapa de instalação do provedor FIPS:

bash
openssl fipsinstall

Defina a variável de ambiente OPENSSL_CONF para apontar para o seu arquivo de configuração e OPENSSL_MODULES para o local da biblioteca dinâmica do provedor FIPS. Ex:

bash
export OPENSSL_CONF=/<caminho para o arquivo de configuração>/nodejs.cnf
export OPENSSL_MODULES=/<caminho para a lib openssl>/ossl-modules

O modo FIPS pode então ser habilitado no Node.js por:

  • Iniciar o Node.js com as flags de linha de comando --enable-fips ou --force-fips.
  • Chamar programaticamente crypto.setFips(true).

Opcionalmente, o modo FIPS pode ser habilitado no Node.js por meio do arquivo de configuração do OpenSSL. Ex:

text
nodejs_conf = nodejs_init

.include /<caminho absoluto>/fipsmodule.cnf

[nodejs_init]
providers = provider_sect
alg_section = algorithm_sect

[provider_sect]
default = default_sect
# O nome da seção fips deve corresponder ao nome da seção dentro do {#included-fipsmodulecnf}
# fipsmodule.cnf incluído.
fips = fips_sect

[default_sect]
activate = 1

[algorithm_sect]
default_properties = fips=yes

Constantes de criptografia ​

As seguintes constantes exportadas por crypto.constants se aplicam a vários usos dos módulos node:crypto, node:tls e node:https e são geralmente específicas do OpenSSL.

Opções do OpenSSL ​

Consulte a lista de Flags SSL OP para obter detalhes.

ConstanteDescrição
SSL_OP_ALLAplica várias soluções para bugs dentro do OpenSSL. Veja https://www.openssl.org/docs/man3.0/man3/SSL_CTX_set_options.html para detalhes.
SSL_OP_ALLOW_NO_DHE_KEXInstrui o OpenSSL a permitir um modo de troca de chave não baseado em [EC]DHE para TLS v1.3
SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATIONPermite a renegociação legada insegura entre o OpenSSL e clientes ou servidores não corrigidos. Veja https://www.openssl.org/docs/man3.0/man3/SSL_CTX_set_options.html .
SSL_OP_CIPHER_SERVER_PREFERENCETenta usar as preferências do servidor em vez das do cliente ao selecionar uma cifra. O comportamento depende da versão do protocolo. Veja https://www.openssl.org/docs/man3.0/man3/SSL_CTX_set_options.html .
SSL_OP_CISCO_ANYCONNECTInstrui o OpenSSL a usar o identificador de versão da Cisco de DTLS_BAD_VER.
SSL_OP_COOKIE_EXCHANGEInstrui o OpenSSL a ativar a troca de cookies.
SSL_OP_CRYPTOPRO_TLSEXT_BUGInstrui o OpenSSL a adicionar a extensão server-hello de uma versão inicial do rascunho do cryptopro.
SSL_OP_DONT_INSERT_EMPTY_FRAGMENTSInstrui o OpenSSL a desabilitar uma solução para vulnerabilidade do SSL 3.0/TLS 1.0 adicionada no OpenSSL 0.9.6d.
SSL_OP_LEGACY_SERVER_CONNECTPermite a conexão inicial com servidores que não oferecem suporte a RI.
SSL_OP_NO_COMPRESSIONInstrui o OpenSSL a desabilitar o suporte para compressão SSL/TLS.
SSL_OP_NO_ENCRYPT_THEN_MACInstrui o OpenSSL a desabilitar o encrypt-then-MAC.
SSL_OP_NO_QUERY_MTU
SSL_OP_NO_RENEGOTIATIONInstrui o OpenSSL a desabilitar a renegociação.
SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATIONInstrui o OpenSSL a sempre iniciar uma nova sessão ao realizar a renegociação.
SSL_OP_NO_SSLv2Instrui o OpenSSL a desligar o SSL v2
SSL_OP_NO_SSLv3Instrui o OpenSSL a desligar o SSL v3
SSL_OP_NO_TICKETInstrui o OpenSSL a desabilitar o uso de tickets RFC4507bis.
SSL_OP_NO_TLSv1Instrui o OpenSSL a desligar o TLS v1
SSL_OP_NO_TLSv1_1Instrui o OpenSSL a desligar o TLS v1.1
SSL_OP_NO_TLSv1_2Instrui o OpenSSL a desligar o TLS v1.2
SSL_OP_NO_TLSv1_3Instrui o OpenSSL a desligar o TLS v1.3
SSL_OP_PRIORITIZE_CHACHAInstrui o servidor OpenSSL a priorizar ChaCha20-Poly1305 quando o cliente o fizer. Esta opção não tem efeito se SSL_OP_CIPHER_SERVER_PREFERENCE não estiver habilitado.
SSL_OP_TLS_ROLLBACK_BUGInstrui o OpenSSL a desabilitar a detecção de ataque de reversão de versão.

Constantes do motor OpenSSL ​

ConstanteDescrição
ENGINE_METHOD_RSALimitar o uso do motor para RSA
ENGINE_METHOD_DSALimitar o uso do motor para DSA
ENGINE_METHOD_DHLimitar o uso do motor para DH
ENGINE_METHOD_RANDLimitar o uso do motor para RAND
ENGINE_METHOD_ECLimitar o uso do motor para EC
ENGINE_METHOD_CIPHERSLimitar o uso do motor para CIPHERS
ENGINE_METHOD_DIGESTSLimitar o uso do motor para DIGESTS
ENGINE_METHOD_PKEY_METHSLimitar o uso do motor para PKEY_METHS
ENGINE_METHOD_PKEY_ASN1_METHSLimitar o uso do motor para PKEY_ASN1_METHS
ENGINE_METHOD_ALL
ENGINE_METHOD_NONE

Outras constantes do OpenSSL ​

ConstanteDescrição
DH_CHECK_P_NOT_SAFE_PRIME
DH_CHECK_P_NOT_PRIME
DH_UNABLE_TO_CHECK_GENERATOR
DH_NOT_SUITABLE_GENERATOR
RSA_PKCS1_PADDING
RSA_SSLV23_PADDING
RSA_NO_PADDING
RSA_PKCS1_OAEP_PADDING
RSA_X931_PADDING
RSA_PKCS1_PSS_PADDING
RSA_PSS_SALTLEN_DIGESTDefine o comprimento do salt para RSA_PKCS1_PSS_PADDING para o tamanho do digest ao assinar ou verificar.
RSA_PSS_SALTLEN_MAX_SIGNDefine o comprimento do salt para RSA_PKCS1_PSS_PADDING para o valor máximo permissível ao assinar dados.
RSA_PSS_SALTLEN_AUTOFaz com que o comprimento do salt para RSA_PKCS1_PSS_PADDING seja determinado automaticamente ao verificar uma assinatura.
POINT_CONVERSION_COMPRESSED
POINT_CONVERSION_UNCOMPRESSED
POINT_CONVERSION_HYBRID

Constantes de criptografia do Node.js ​

ConstanteDescrição
defaultCoreCipherListEspecifica a lista de cifras padrão incorporada usada pelo Node.js.
defaultCipherListEspecifica a lista de cifras padrão ativa usada pelo processo atual do Node.js.