iDoc

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, decifrar, assinar e verificar 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);
// Prints:
//   c0fa1bc00531bd78ef38c628449c5102aeabd49b5dc3a2a516ea6ea959d6658e
js
const { createHmac } = require('node:crypto');

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

Determinando se o suporte ao crypto está indisponível ​

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

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

js
let crypto;
try {
  crypto = require('node:crypto');
} catch (err) {
  console.error('crypto support is disabled!');
}

Ao usar a palavra-chave léxica 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 que o código possa ser executado em uma compilação do Node.js onde o suporte ao crypto não está habilitado, considere usar a função import() em vez da palavra-chave léxica import:

js
let crypto;
try {
  crypto = await import('node:crypto');
} catch (err) {
  console.error('crypto support is disabled!');
}

Classe: Certificate ​

Adicionado em: v0.11.8

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

\<keygen\> está obsoleto desde o 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 é lidar com a 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ã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 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ãoAlterações
v15.0.0O argumento spkac pode ser um ArrayBuffer. Limitou o tamanho do argumento spkac para 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ãoAlterações
v15.0.0O argumento spkac pode ser um ArrayBuffer. Adicionada a codificação. Limitou o tamanho do argumento spkac para 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, conforme 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'));
// Prints: the challenge as a UTF8 string
js
const { Certificate } = require('node:crypto');
const cert = Certificate();
const spkac = getSpkacSomehow();
const challenge = cert.exportChallenge(spkac);
console.log(challenge.toString('utf8'));
// Prints: the challenge as a UTF8 string

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 duas maneiras:

  • Como um stream que é legível e gravável, onde dados não criptografados simples são gravados 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 de 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 = 'Password used to generate key';

// First, we'll generate the key. The key length is dependent on the algorithm.
// In this case for aes192, it is 24 bytes (192 bits).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err;
  // Then, we'll generate a random initialization vector
  randomFill(new Uint8Array(16), (err, iv) => {
    if (err) throw err;

    // Once we have the key and iv, we can create and use the cipher...
    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('some clear text data');
    cipher.end();
  });
});
js
const {
  scrypt,
  randomFill,
  createCipheriv,
} = require('node:crypto');

const algorithm = 'aes-192-cbc';
const password = 'Password used to generate key';

// First, we'll generate the key. The key length is dependent on the algorithm.
// In this case for aes192, it is 24 bytes (192 bits).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err;
  // Then, we'll generate a random initialization vector
  randomFill(new Uint8Array(16), (err, iv) => {
    if (err) throw err;

    // Once we have the key and iv, we can create and use the cipher...
    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('some clear text data');
    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 = 'Password used to generate key';

// First, we'll generate the key. The key length is dependent on the algorithm.
// In this case for aes192, it is 24 bytes (192 bits).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err;
  // Then, we'll generate a random initialization vector
  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 = 'Password used to generate key';

// First, we'll generate the key. The key length is dependent on the algorithm.
// In this case for aes192, it is 24 bytes (192 bits).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err;
  // Then, we'll generate a random initialization vector
  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 = 'Password used to generate key';

// First, we'll generate the key. The key length is dependent on the algorithm.
// In this case for aes192, it is 24 bytes (192 bits).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err;
  // Then, we'll generate a random initialization vector
  randomFill(new Uint8Array(16), (err, iv) => {
    if (err) throw err;

    const cipher = createCipheriv(algorithm, key, iv);

    let encrypted = cipher.update('some clear text data', 'utf8', 'hex');
    encrypted += cipher.final('hex');
    console.log(encrypted);
  });
});
js
const {
  scrypt,
  randomFill,
  createCipheriv,
} = require('node:crypto');

const algorithm = 'aes-192-cbc';
const password = 'Password used to generate key';

// First, we'll generate the key. The key length is dependent on the algorithm.
// In this case for aes192, it is 24 bytes (192 bits).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err;
  // Then, we'll generate a random initialization vector
  randomFill(new Uint8Array(16), (err, iv) => {
    if (err) throw err;

    const cipher = createCipheriv(algorithm, key, iv);

    let encrypted = cipher.update('some clear text data', '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 será retornada. Se um outputEncoding não for fornecido, um Buffer será 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 em um erro sendo lançado.

cipher.getAuthTag() ​

Adicionado em: v1.0.0

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

O método cipher.getAuthTag() deve ser chamado apenas depois que a criptografia for concluída usando o método cipher.final().

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

cipher.setAAD(buffer[, options]) ​

Adicionado em: v1.0.0

Ao usar um modo de criptografia autenticada (atualmente, GCM, CCM, OCB e chacha20-poly1305 são suportados), o método cipher.setAAD() define o valor usado para o parâmetro de entrada dados autenticados adicionais (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 simples 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 preenchimento aos dados de entrada para o tamanho de bloco apropriado. Para desativar o preenchimento padrão, chame cipher.setAutoPadding(false).

Quando autoPadding é false, o comprimento de todos os dados de entrada deve ser um múltiplo do tamanho do bloco da cifra ou cipher.final() lançará um erro. Desativar o preenchimento automático é útil para preenchimento não padrão, por exemplo, usando 0x0 em vez de preenchimento 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 foi alterado 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 é ignorado.

O outputEncoding especifica o formato de saída dos dados criptografados. 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() após cipher.final() resultará no lançamento de um erro.

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 é legível e 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 = 'Password used to generate key';
// Key length is dependent on the algorithm. In this case for aes192, it is
// 24 bytes (192 bits).
// Use the async `crypto.scrypt()` instead.
const key = scryptSync(password, 'salt', 24);
// The IV is usually passed along with the ciphertext.
const iv = Buffer.alloc(16, 0); // Initialization vector.

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);
  // Prints: some clear text data
});

// Encrypted with same algorithm, key and 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 = 'Password used to generate key';
// Key length is dependent on the algorithm. In this case for aes192, it is
// 24 bytes (192 bits).
// Use the async `crypto.scrypt()` instead.
const key = scryptSync(password, 'salt', 24);
// The IV is usually passed along with the ciphertext.
const iv = Buffer.alloc(16, 0); // Initialization vector.

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);
  // Prints: some clear text data
});

// Encrypted with same algorithm, key and 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 = 'Password used to generate key';
// Use the async `crypto.scrypt()` instead.
const key = scryptSync(password, 'salt', 24);
// The IV is usually passed along with the ciphertext.
const iv = Buffer.alloc(16, 0); // Initialization vector.

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 = 'Password used to generate key';
// Use the async `crypto.scrypt()` instead.
const key = scryptSync(password, 'salt', 24);
// The IV is usually passed along with the ciphertext.
const iv = Buffer.alloc(16, 0); // Initialization vector.

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 = 'Password used to generate key';
// Use the async `crypto.scrypt()` instead.
const key = scryptSync(password, 'salt', 24);
// The IV is usually passed along with the ciphertext.
const iv = Buffer.alloc(16, 0); // Initialization vector.

const decipher = createDecipheriv(algorithm, key, iv);

// Encrypted using same algorithm, key and iv.
const encrypted =
  'e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa';
let decrypted = decipher.update(encrypted, 'hex', 'utf8');
decrypted += decipher.final('utf8');
console.log(decrypted);
// Prints: some clear text data
js
const {
  scryptSync,
  createDecipheriv,
} = require('node:crypto');
const { Buffer } = require('node:buffer');

const algorithm = 'aes-192-cbc';
const password = 'Password used to generate key';
// Use the async `crypto.scrypt()` instead.
const key = scryptSync(password, 'salt', 24);
// The IV is usually passed along with the ciphertext.
const iv = Buffer.alloc(16, 0); // Initialization vector.

const decipher = createDecipheriv(algorithm, key, iv);

// Encrypted using same algorithm, key and iv.
const encrypted =
  'e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa';
let decrypted = decipher.update(encrypted, 'hex', 'utf8');
decrypted += decipher.final('utf8');
console.log(decrypted);
// Prints: some clear text data

decipher.final([outputEncoding]) ​

Adicionado em: v0.1.94

  • outputEncoding <string> A codificação do valor de retorno.
  • Retorna: <Buffer> | <string> Qualquer conteúdo decifrado restante. 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ãoAlterações
v15.0.0O argumento buffer pode ser uma string ou ArrayBuffer e é limitado a não mais que 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 (GCM, CCM, OCB e chacha20-poly1305 são atualmente suportados), o método decipher.setAAD() define o valor usado para o parâmetro de entrada dados autenticados adicionais (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 autenticada (atualmente, GCM, CCM, OCB e chacha20-poly1305 são 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 a tag de autenticação, considere ressalvas 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 o preenchimento de bloco padrão, chamar decipher.setAutoPadding(false) desativará o preenchimento automático para evitar que decipher.final() verifique e remova o preenchimento.

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

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

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

[Histórico]

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

Atualiza a decifração 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 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 decipher.update() pode ser chamado várias vezes com novos dados até que decipher.final() seja chamado. Chamar decipher.update() após decipher.final() resultará em um erro sendo lançado.

Mesmo que a cifra subjacente implemente autenticação, a autenticidade e integridade do texto simples retornado desta função podem ser incertas neste momento. Para algoritmos de criptografia autenticada, a autenticidade geralmente só é estabelecida 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');

// Generate Alice's keys...
const alice = createDiffieHellman(2048);
const aliceKey = alice.generateKeys();

// Generate Bob's keys...
const bob = createDiffieHellman(alice.getPrime(), alice.getGenerator());
const bobKey = bob.generateKeys();

// Exchange and generate the secret...
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');

// Generate Alice's keys...
const alice = createDiffieHellman(2048);
const aliceKey = alice.generateKeys();

// Generate Bob's keys...
const bob = createDiffieHellman(alice.getPrime(), alice.getGenerator());
const bobKey = bob.generateKeys();

// Exchange and generate the secret...
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 for fornecida, uma string é retornada; caso contrário, um Buffer é 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 computados, 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 será retornada; caso contrário, um Buffer será retornado.

Esta função é um wrapper fino em torno de DH_generate_key(). Em particular, uma vez que uma chave privada tenha sido 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 será retornada; caso contrário, um Buffer será retornado.

diffieHellman.getPrime([encoding]) ​

Adicionado em: v0.5.0

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

diffieHellman.getPrivateKey([encoding]) ​

Adicionado em: v0.5.0

Retorna a chave privada Diffie-Hellman na encoding especificada. Se encoding for fornecida, uma string será retornada; caso contrário, um Buffer será retornado.

diffieHellman.getPublicKey([encoding]) ​

Adicionado em: v0.5.0

Retorna a chave pública Diffie-Hellman na encoding especificada. Se encoding for fornecida, uma string será retornada; caso contrário, um Buffer será 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 nenhuma encoding for fornecida, 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 nenhuma encoding for fornecida, 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 bem conhecido como seu argumento. Ela funciona da mesma forma que DiffieHellman, exceto que não permite alterar suas chaves após a criação. Em outras palavras, ela 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 (ver 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 versões futuras 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 de 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 de nomes de curvas disponíveis. Nas 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 não compactada devem ser as mesmas
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 não compactada devem ser as mesmas
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 mudou 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 o 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 for fornecido, uma string será retornada; caso contrário, um Buffer será 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 por meio de 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 formato e codificação especificados. Esta chave deve ser transferida para a outra parte.

O argumento format especifica a codificação do 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 será retornada; caso contrário, um Buffer será 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 do 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 (chave) público 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, pois 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úblico associado à 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');

// This is a shortcut way of specifying one of Alice's previous private
// keys. It would be unwise to use such a predictable private key in a real
// application.
alice.setPrivateKey(
  createHash('sha256').update('alice', 'utf8').digest(),
);

// Bob uses a newly generated cryptographically strong
// pseudorandom key pair
bob.generateKeys();

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

// aliceSecret and bobSecret should be the same shared secret value
console.log(aliceSecret === bobSecret);
js
const {
  createECDH,
  createHash,
} = require('node:crypto');

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

// This is a shortcut way of specifying one of Alice's previous private
// keys. It would be unwise to use such a predictable private key in a real
// application.
alice.setPrivateKey(
  createHash('sha256').update('alice', 'utf8').digest(),
);

// Bob uses a newly generated cryptographically strong
// pseudorandom key pair
bob.generateKeys();

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

// aliceSecret and bobSecret should be the same shared secret value
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 é legível e gravável, onde os dados são escritos 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 stream. Para funções hash XOF como 'shake256', a opção outputLength pode ser usada para especificar o comprimento de saída desejado em bytes.

Um erro é lançado quando uma tentativa é feita para copiar o objeto Hash após o método hash.digest() ter sido 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 hashed (usando o método hash.update()). Se encoding for fornecido, uma string será retornada; caso contrário, um Buffer será retornado.

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

hash.update(data[, inputEncoding]) ​

[Histórico]

VersãoAlterações
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 os data fornecidos, cuja codificação é fornecida em inputEncoding. Se encoding não for fornecido e os data forem uma string, uma codificação de 'utf8' será aplicada. Se data for um Buffer, TypedArray ou DataView, então inputEncoding é ignorado.

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

Classe: Hmac ​

Adicionado em: v0.1.94

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

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

O método crypto.createHmac() é usado para criar instâncias Hmac. Os 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', () => {
  // Only one element is going to be produced by the
  // hash stream.
  const data = hmac.read();
  if (data) {
    console.log(data.toString('hex'));
    // Prints:
    //   7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f77e
  }
});

hmac.write('some data to hash');
hmac.end();
js
const {
  createHmac,
} = require('node:crypto');

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

hmac.on('readable', () => {
  // Only one element is going to be produced by the
  // hash stream.
  const data = hmac.read();
  if (data) {
    console.log(data.toString('hex'));
    // Prints:
    //   7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f77e
  }
});

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

Exemplo: Usando Hmac e streams canalizados:

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('some data to hash');
console.log(hmac.digest('hex'));
// Prints:
//   7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f77e
js
const {
  createHmac,
} = require('node:crypto');

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

hmac.update('some data to hash');
console.log(hmac.digest('hex'));
// Prints:
//   7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f77e

hmac.digest([encoding]) ​

Adicionado em: v0.1.94

Calcula o resumo HMAC de todos os dados passados usando hmac.update(). Se encoding for fornecido, uma string será retornada; caso contrário, um Buffer será 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.0O inputEncoding padrão mudou de binary para utf8.
v0.1.94Adicionado em: v0.1.94

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

Isto 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 worker 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 de KeyObject. Objetos KeyObject não devem ser criados diretamente usando a palavra-chave new.

A maioria das aplicações devem considerar usar a 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 outras threads através 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);
// Prints: 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);
  // Prints: 32 (tamanho da chave simétrica em bytes)
})();

keyObject.asymmetricKeyDetails ​

[Histórico]

VersãoMudanças
v16.9.0Expõe os 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 por meio desta propriedade pode ser usada para identificar exclusivamente uma chave 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 por meio 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 de 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 é tempo constante.

keyObject.export([options]) ​

[Histórico]

VersãoMudanças
v15.9.0Adicionado suporte para o 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' (somente 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' (somente RSA), 'pkcs8' ou 'sec1' (somente EC).
  • format: <string> Deve ser 'pem', 'der' ou 'jwk'.
  • cipher: <string> Se especificado, a chave privada será criptografada com o cipher e passphrase fornecidos 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 em 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 de KeyObject para uma 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 em string da função de hash a ser usada. 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('some data to sign');
sign.end();
const signature = sign.sign(privateKey, 'hex');

const verify = createVerify('SHA256');
verify.write('some data to sign');
verify.end();
console.log(verify.verify(publicKey, signature, 'hex'));
// Prints: true
js
const {
  generateKeyPairSync,
  createSign,
  createVerify,
} = require('node:crypto');

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

const sign = createSign('SHA256');
sign.write('some data to sign');
sign.end();
const signature = sign.sign(privateKey, 'hex');

const verify = createVerify('SHA256');
verify.write('some data to sign');
verify.end();
console.log(verify.verify(publicKey, signature, 'hex'));
// Prints: 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('some data to sign');
sign.end();
const signature = sign.sign(privateKey);

const verify = createVerify('SHA256');
verify.update('some data to sign');
verify.end();
console.log(verify.verify(publicKey, signature));
// Prints: true
js
const {
  generateKeyPairSync,
  createSign,
  createVerify,
} = require('node:crypto');

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

const sign = createSign('SHA256');
sign.update('some data to sign');
sign.end();
const signature = sign.sign(privateKey);

const verify = createVerify('SHA256');
verify.update('some data to sign');
verify.end();
console.log(verify.verify(publicKey, signature));
// Prints: true

sign.sign(privateKey[, outputEncoding]) ​

[Histórico]

VersãoAlterações
v15.0.0O 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 de hash usada para assinar a mensagem, conforme especificado na seção 3.1 do RFC 4055, a menos que uma função de hash MGF1 tenha sido especificada como parte da chave em conformidade com a seção 3.3 do RFC 4055.

  • saltLength <integer> Comprimento do sal para quando o preenchimento for RSA_PKCS1_PSS_PADDING. O valor especial crypto.constants.RSA_PSS_SALTLEN_DIGEST define o comprimento do sal para o tamanho do digest, crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN (padrão) define-o 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 após a chamada do método sign.sign(). Várias chamadas para sign.sign() resultarão em um erro sendo lançado.

sign.update(data[, inputEncoding]) ​

[Histórico]

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

Atualiza o conteúdo do Sign com os dados fornecidos em data, cuja codificação é fornecida em inputEncoding. Se encoding não for fornecido e os data forem uma string, uma codificação de 'utf8' será aplicada. Se data for um Buffer, TypedArray ou DataView, então inputEncoding é 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 a 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 de Verify. Os objetos Verify não devem ser criados diretamente usando a palavra-chave new.

Veja Sign para exemplos.

verify.update(data[, inputEncoding]) ​

[Histórico]

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

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

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

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

[Histórico]

VersãoAlterações
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 com codificação 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 de hash usada para verificar a mensagem, conforme especificado na seção 3.1 do RFC 4055, a menos que uma função de hash MGF1 tenha sido especificada como parte da chave em conformidade com a seção 3.3 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_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 a signature seja um Buffer, TypedArray ou DataView.

O objeto verify não pode ser usado novamente depois que verify.verify() foi 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('{... pem encoded cert ...}');

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

const x509 = new X509Certificate('{... pem encoded cert ...}');

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 tem 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 e-mail 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 e-mail.

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 e-mail 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ãoMudanças
v18.0.0A opção subject agora usa o valor 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 diferir do name fornecido na 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 nomes alternativos de assunto iPAddress RFC 5280 são considerados, e eles 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 da chave para este certificado.

x509.fingerprint ​

Adicionado em: v15.6.0

A impressão digital SHA-1 deste certificado.

Como o SHA-1 é 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 o cálculo da 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. Embora o SHA-512 presumivelmente forneça um nível mais alto de segurança em geral, a segurança do SHA-256 corresponde à da maioria dos algoritmos 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 à CVE-2021-44532.
v15.6.0Adicionado em: v15.6.0

Uma representação textual da extensão de acesso às informações 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 do 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 ser colocado 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 os dois 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 exclusivamente os certificados. Considere usar x509.fingerprint256 como um identificador exclusivo.

x509.subject ​

Adicionado em: v15.6.0

O assunto 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 ao CVE-2021-44532.
v15.6.0Adicionado em: v15.6.0

O nome alternativo do assunto especificado para este certificado.

Esta é uma lista separada por vírgulas de nomes alternativos de assunto. Cada entrada começa com uma string que identifica o tipo do nome alternativo do assunto, seguido por dois pontos e o valor associado à entrada.

As versões anteriores do Node.js assumiram incorretamente que é 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 assunto que incluem esta sequência quando representados como uma string.

Após o prefixo que denota o tipo de entrada, o restante de cada entrada pode ser colocado entre aspas para indicar que o valor é um literal de string JSON. Para compatibilidade retroativa, o Node.js usa apenas literais de string JSON nesta propriedade 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.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 do objeto de certificado legado.

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 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 falsos positivos 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 a função BN_is_prime_ex opções nchecks para obter mais detalhes. Padrão: 0

  • callback <Function>

    • err <Error> Definido como um objeto <Error> se ocorrer um erro durante a verificação.
    • result <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 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ísticas de Miller-Rabin a serem realizadas. Quando o valor é 0 (zero), um número de verificações é usado que produz uma taxa de falsos positivos 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 a função BN_is_prime_ex opções nchecks para obter 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 candidate.

crypto.constants ​

Adicionado em: v6.3.0

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

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 são limitados a um máximo de 2 ** 31 - 1 bytes cada.
v11.6.0O argumento key agora pode ser um KeyObject.
v11.2.0, v10.17.0A cifra chacha20-poly1305 (a variante IETF do 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 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. Nas 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 ressalvas ao usar strings como entradas para APIs criptográficas.

Os vetores de inicialização devem ser imprevisíveis e exclusivos; 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 exclusivo, 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 do 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 é padrão para 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 ressalvas ao usar strings como entradas para APIs criptográficas.

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 normalmente são apenas 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 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.createDiffieHellman(prime[, primeEncoding][, generator][, generatorEncoding]) ​

[Histórico]

VersãoMudanças
v8.0.0O argumento prime agora pode ser qualquer TypedArray ou DataView.
v8.0.0O argumento prime agora pode ser um Uint8Array.
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 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.

crypto.createHash(algorithm[, options]) ​

[Histórico]

VersãoMudanças
v12.8.0A opção outputLength foi adicionada para funções de 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 de 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', () => {
  // Only one element is going to be produced by the
  // hash stream.
  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', () => {
  // Only one element is going to be produced by the
  // hash stream.
  const data = input.read();
  if (data)
    hash.update(data);
  else {
    console.log(`${hash.digest('hex')} ${filename}`);
  }
});

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

[Histórico]

VersãoAlterações
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 options opcional controla o comportamento do fluxo.

O algorithm depende dos algoritmos disponíveis suportados pela versão do OpenSSL na plataforma. Os 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 de 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', () => {
  // Only one element is going to be produced by the
  // hash stream.
  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', () => {
  // Only one element is going to be produced by the
  // hash stream.
  const data = input.read();
  if (data)
    hmac.update(data);
  else {
    console.log(`${hmac.digest('hex')} ${filename}`);
  }
});

crypto.createPrivateKey(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.6.0Adicionado em: v11.6.0

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

Se a chave privada estiver criptografada, uma passphrase 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 o 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 'pem'; se key for um KeyObject com o 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 o tipo 'private' for fornecido, um novo KeyObject com o 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 de codificação 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 de chave 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 de stream.Writable.

Em alguns casos, uma instância de 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 um array de nomes dos algoritmos de assinatura disponíveis. O argumento opcional options controla o comportamento de 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 sempre usar nomes de 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 criptográfico compatível com FIPS está atualmente em uso. Definir como verdadeiro requer uma build 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ã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.0Adicionado em: v15.0.0

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

  • options: <Object>

    • length: <number> O tamanho 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 tipo 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 respectiva parte da chave é retornada como um KeyObject.

É recomendado codificar chaves públicas como 'spki' e 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) => {
  // Handle errors and use the generated key pair.
});
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) => {
  // Lidar com erros e usar o par de chaves gerado.
});

Na 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 retorna uma Promise para um Object com propriedades publicKey e privateKey.

crypto.generateKeyPairSync(type, options) ​

[Histórico]

VersãoMudanças
v16.10.0Adiciona a capacidade de definir parâmetros de sequência RSASSA-PSS-params para pares de chaves RSA-PSS.
v13.9.0, v12.17.0Adiciona suporte para Diffie-Hellman.
v12.0.0Adiciona suporte para pares de chaves RSA-PSS.
v12.0.0Adiciona a capacidade de gerar pares de chaves X25519 e X448.
v12.0.0Adiciona 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 tipo 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.

Ao codificar chaves públicas, é recomendado usar 'spki'. Ao codificar chaves privadas, é recomendado 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 respectiva chave 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 comprimento 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 sincronamente 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 primo pseudoaleatório de size bits.

Se options.safe for true, o primo será um primo seguro -- isto é, (prime - 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 satisfará a condição de que prime % add = rem.
  • Se apenas options.add estiver definido e options.safe não for true, o primo satisfará a condição de que prime % add = 1.
  • Se apenas options.add estiver definido e options.safe estiver definido como true, o primo satisfará 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 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.generatePrimeSync(size[, options]) ​

Adicionado em: v15.8.0

Gera um número primo pseudoaleatório 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á 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 forem 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, 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 tamanho de chave de teste.
    • ivLength: <number> Um tamanho 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 tamanho do vetor de inicialização esperado ou padrão em bytes. Esta propriedade é omitida se a cifra não usar um vetor de inicialização.
    • keyLength <number> O tamanho da chave esperado ou padrão em bytes.
    • mode <string> O modo da 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 and bobSecret should be the same */
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 and bobSecret should be the same */
console.log(aliceSecret === bobSecret);

crypto.getFips() ​

Adicionado em: v10.0.0

  • Retorna: <number> 1 se e somente se um provedor de criptografia compatível com FIPS estiver em uso, 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 de "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 é compatível 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 ao lançamento

Uma utilidade para criar digests de hash únicos de dados. Pode ser mais rápido que o crypto.createHash() baseado em objeto ao fazer o hash de uma quantidade menor de dados (<= 5 MB) que esteja prontamente disponível. Se os dados puderem ser grandes ou se forem transmitidos, ainda é recomendável 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. Nas versões recentes do OpenSSL, openssl list -digest-algorithms exibirá os algoritmos de digest 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 de derivação de chave simples definida na 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 de derivação de chave HKDF síncrona conforme definido em RFC 5869. O ikm, salt e info fornecidos são usados com o digest para derivar uma chave de keylen bytes.

O derivedKey gerado com sucesso será retornado 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 é 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 digest 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, a derivedKey gerada com sucesso será passada 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 as 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 digest 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; veja 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 digest 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. Veja NIST SP 800-132 para 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'

Uma array de funções de digest suportadas pode ser recuperada usando crypto.getHashes().

crypto.privateDecrypt(privateKey, buffer) ​

[Histórico]

VersãoAlterações
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 previamente criptografado 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.

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

crypto.privateEncrypt(privateKey, buffer) ​

[Histórico]

VersãoAlterações
v15.0.0Adicionado 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 o buffer com a key. O buffer foi previamente criptografado 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 passado 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.0Adicionado string, ArrayBuffer e CryptoKey como tipos de chave permitidos. O oaepLabel e a 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 passado 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ã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.
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 são gerados de forma assíncrona e a função callback é 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 de forma síncrona 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 demorar mais do que alguns milissegundos. A única vez em que a geração de 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 threadpool do libuv, o 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.randomBytes() é realizada em uma única solicitação de threadpool. Para minimizar a variação da duração das tarefas do threadpool, particione grandes solicitações de randomBytes ao fazer isso como parte do atendimento de 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, o 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 requisição de threadpool. Para minimizar a variação do comprimento da tarefa do threadpool, particione grandes requisições de randomFill ao fazer isso como parte do atendimento a uma requisiçã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 viés de módulo.

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

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

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 <booleano> 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 versão 4 RFC 4122 aleatório. 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 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 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 projetada para ser computacionalmente e em termos de memória cara, a fim de tornar os 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, 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 da chave falha, caso contrário, err é null. derivedKey é passado 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 de 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 cara computacionalmente e em termos de memória, a fim de tornar os ataques de força bruta não compensadores.

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 as 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 algum dos argumentos de entrada especifica valores ou tipos inválidos.

js
const {
  scryptSync,
} = await import('node:crypto');
// Usando os padrões 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 padrões 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: <Objeto>
    • 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 proporção calculada de used para o total de bytes alocados.

crypto.setEngine(engine[, flags]) ​

[Histórico]

VersãoAlterações
v22.4.0, v20.16.0O suporte para 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 do 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. O flags é um campo de bits que usa um ou uma combinação 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 crypto 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 callback opcional adicionado.
v13.2.0, v12.16.0Esta função agora suporta assinaturas DSA e ECDSA IEEE-P1363.
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 é dependente 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 que codifica (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 da 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 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 resumos 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 em bytes. 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 bytes 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ã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.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 DSA e ECDSA IEEE-P1363.
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 codificada em DER que codifica (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 de 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 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_MAX_SIGN (padrão) define-o para o valor máximo permitido.

O argumento signature é a assinatura calculada anteriormente 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 usará o threadpool do libuv.

crypto.webcrypto ​

Adicionado em: v15.0.0

Tipo: <Crypto> Uma implementação do padrão 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. Essas instâncias incluem textos simples, textos cifrados, chaves simétricas, vetores de inicialização, senhas, salts, tags de autenticação e dados autenticados adicionais.

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 que a entropia de uma sequência de bytes n aleatória ou pseudoaleatória. Por exemplo, nenhuma string UTF-8 resultará na sequência de bytes c0 af. As chaves secretas devem ser quase exclusivamente 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 byte 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 chaves 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 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 de existir o conceito de uma API de Stream unificada e antes de existirem objetos Buffer para lidar com dados binários. Como tal, 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. Este 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 por selecionar o algoritmo de criptografia e o 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 à colisão é necessária, como assinaturas digitais.
  • A chave usada com os algoritmos RSA, DSA e DH é recomendada para ter pelo menos 2048 bits e a da curva de ECDSA e ECDH pelo menos 224 bits, para ser segura 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.

Veja 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 através do provedor legado, que não está habilitado por padrão.

Modo CCM ​

CCM é um dos algoritmos AEAD suportados. As aplicações que usam este modo devem obedecer a 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 simples é 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 da 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 pedaço de dados por instância.
  • Ao passar dados autenticados adicionais (AAD), o comprimento da mensagem real em bytes deve ser passado para setAAD() através 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, então o comprimento do texto cifrado é sempre plaintextLength. Isso não é necessário se nenhum AAD for usado.
  • Como o CCM processa a mensagem inteira de uma vez, update() deve ser chamado exatamente uma vez.
  • Mesmo que chamar update() seja suficiente para criptografar/descriptografar a mensagem, as aplicações devem chamar final() para computar 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();

// Now transmit { 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('Authentication failed!', { 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();

// Now transmit { 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('Authentication failed!', { cause: err });
}

console.log(receivedPlaintext);

Modo FIPS ​

Ao usar o OpenSSL 3, o Node.js suporta o 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 FIPS no Node.js, você precisará de:

  • Um provedor OpenSSL 3 FIPS corretamente instalado.
  • Um arquivo de configuração do módulo FIPS do OpenSSL 3.
  • Um arquivo de configuração 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 OpenSSL que aponte para o provedor FIPS. Um exemplo de arquivo de configuração é:

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 do 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 através do arquivo de configuração 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 Criptográficas ​

As seguintes constantes exportadas por crypto.constants aplicam-se 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 alternativas para bugs dentro do OpenSSL. Consulte 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 chaves 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. Consulte 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. Consulte 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 do DTLS_BAD_VER.
SSL_OP_COOKIE_EXCHANGEInstrui o OpenSSL a ativar a troca de cookies.
SSL_OP_CRYPTOPRO_TLSEXT_BUGInstrui o OpenSSL a adicionar uma extensão server-hello de uma versão antiga do rascunho cryptopro.
SSL_OP_DONT_INSERT_EMPTY_FRAGMENTSInstrui o OpenSSL a desativar uma solução alternativa de vulnerabilidade SSL 3.0/TLS 1.0 adicionada no OpenSSL 0.9.6d.
SSL_OP_LEGACY_SERVER_CONNECTPermite a conexão inicial a servidores que não suportam RI.
SSL_OP_NO_COMPRESSIONInstrui o OpenSSL a desativar o suporte para compactação SSL/TLS.
SSL_OP_NO_ENCRYPT_THEN_MACInstrui o OpenSSL a desativar encrypt-then-MAC.
SSL_OP_NO_QUERY_MTU
SSL_OP_NO_RENEGOTIATIONInstrui o OpenSSL a desativar 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 desativar o SSL v2
SSL_OP_NO_SSLv3Instrui o OpenSSL a desativar o SSL v3
SSL_OP_NO_TICKETInstrui o OpenSSL a desativar o uso de tickets RFC4507bis.
SSL_OP_NO_TLSv1Instrui o OpenSSL a desativar o TLS v1
SSL_OP_NO_TLSv1_1Instrui o OpenSSL a desativar o TLS v1.1
SSL_OP_NO_TLSv1_2Instrui o OpenSSL a desativar o TLS v1.2
SSL_OP_NO_TLSv1_3Instrui o OpenSSL a desativar o TLS v1.3
SSL_OP_PRIORITIZE_CHACHAInstrui o servidor OpenSSL a priorizar ChaCha20-Poly1305 quando o cliente o faz. Esta opção não tem efeito se SSL_OP_CIPHER_SERVER_PREFERENCE não estiver ativado.
SSL_OP_TLS_ROLLBACK_BUGInstrui o OpenSSL a desativar a detecção de ataque de rollback de versão.

Constantes do engine OpenSSL ​

ConstanteDescrição
ENGINE_METHOD_RSALimita o uso do engine a RSA
ENGINE_METHOD_DSALimita o uso do engine a DSA
ENGINE_METHOD_DHLimita o uso do engine a DH
ENGINE_METHOD_RANDLimita o uso do engine a RAND
ENGINE_METHOD_ECLimita o uso do engine a EC
ENGINE_METHOD_CIPHERSLimita o uso do engine a CIPHERS
ENGINE_METHOD_DIGESTSLimita o uso do engine a DIGESTS
ENGINE_METHOD_PKEY_METHSLimita o uso do engine a PKEY_METHS
ENGINE_METHOD_PKEY_ASN1_METHSLimita o uso do engine a PKEY_ASN1_METHS
ENGINE_METHOD_ALL
ENGINE_METHOD_NONE

Outras constantes 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 permitido 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 crypto do Node.js ​

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