iDoc.dev

Español

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

Español

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

Tema

Crypto ​

[Estable: 2 - Estable]

Estable: 2 Estabilidad: 2 - Estable

Código fuente: lib/crypto.js

El módulo node:crypto proporciona funcionalidad criptográfica que incluye un conjunto de wrappers para las funciones hash, HMAC, cifrado, descifrado, firma y verificación de 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

Determinar si el soporte de crypto no está disponible ​

Es posible que Node.js se construya sin incluir soporte para el módulo node:crypto. En tales casos, intentar import desde crypto o llamar a require('node:crypto') resultará en un error.

Cuando se utiliza CommonJS, el error lanzado puede ser capturado utilizando try/catch:

js
let crypto;
try {
  crypto = require('node:crypto');
} catch (err) {
  console.error('¡el soporte de crypto está deshabilitado!');
}

Cuando se utiliza la palabra clave léxica ESM import, el error solo puede ser capturado si un controlador para process.on('uncaughtException') está registrado antes de cualquier intento de cargar el módulo (utilizando, por ejemplo, un módulo de precarga).

Cuando se utiliza ESM, si existe la posibilidad de que el código se ejecute en una compilación de Node.js donde el soporte de crypto no está habilitado, considere la posibilidad de utilizar la función import() en lugar de la palabra clave léxica import:

js
let crypto;
try {
  crypto = await import('node:crypto');
} catch (err) {
  console.error('¡el soporte de crypto está deshabilitado!');
}

Clase: Certificate ​

Agregado en: v0.11.8

SPKAC es un mecanismo de Solicitud de Firma de Certificado implementado originalmente por Netscape y especificado formalmente como parte del elemento keygen de HTML5.

\<keygen\> está obsoleto desde HTML 5.2 y los nuevos proyectos ya no deberían usar este elemento.

El módulo node:crypto proporciona la clase Certificate para trabajar con datos SPKAC. El uso más común es el manejo de la salida generada por el elemento \<keygen\> de HTML5. Node.js utiliza internamente la implementación SPKAC de OpenSSL.

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

[Historial]

VersiónCambios
v15.0.0El argumento spkac puede ser un ArrayBuffer. Se limitó el tamaño del argumento spkac a un máximo de 2**31 - 1 bytes.
v9.0.0Agregado en: v9.0.0
js
const { Certificate } = await import('node:crypto');
const spkac = getSpkacSomehow();
const challenge = Certificate.exportChallenge(spkac);
console.log(challenge.toString('utf8'));
// Imprime: el desafío como una cadena UTF8
js
const { Certificate } = require('node:crypto');
const spkac = getSpkacSomehow();
const challenge = Certificate.exportChallenge(spkac);
console.log(challenge.toString('utf8'));
// Imprime: el desafío como una cadena UTF8

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

[Historial]

VersiónCambios
v15.0.0El argumento spkac puede ser un ArrayBuffer. Se limitó el tamaño del argumento spkac a un máximo de 2**31 - 1 bytes.
v9.0.0Añadido en: v9.0.0
js
const { Certificate } = await import('node:crypto');
const spkac = getSpkacSomehow();
const publicKey = Certificate.exportPublicKey(spkac);
console.log(publicKey);
// Prints: the public key as <Buffer ...>
js
const { Certificate } = require('node:crypto');
const spkac = getSpkacSomehow();
const publicKey = Certificate.exportPublicKey(spkac);
console.log(publicKey);
// Prints: the public key as <Buffer ...>

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

[Historial]

VersiónCambios
v15.0.0El argumento spkac puede ser un ArrayBuffer. Se agregó la codificación. Se limitó el tamaño del argumento spkac a un máximo de 2**31 - 1 bytes.
v9.0.0Añadido en: 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)));
// Prints: true or false
js
const { Buffer } = require('node:buffer');
const { Certificate } = require('node:crypto');

const spkac = getSpkacSomehow();
console.log(Certificate.verifySpkac(Buffer.from(spkac)));
// Prints: true or false

API Legado ​

[Estable: 0 - Obsoleto]

Estable: 0 Estabilidad: 0 - Obsoleto

Como una interfaz legada, es posible crear nuevas instancias de la clase crypto.Certificate como se ilustra en los ejemplos a continuación.

new crypto.Certificate() ​

Las instancias de la clase Certificate pueden ser creadas usando la palabra clave new o llamando a crypto.Certificate() como una función:

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

Añadido en: 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]) ​

Agregado en: 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: la clave 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: la clave pública como <Buffer ...>

certificate.verifySpkac(spkac[, encoding]) ​

Agregado en: 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 o 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 o false

Clase: Cipher ​

Añadido en: v0.1.94

Las instancias de la clase Cipher se utilizan para cifrar datos. La clase se puede utilizar de dos maneras:

  • Como un stream que es tanto legible como escribible, donde los datos planos no cifrados se escriben para producir datos cifrados en el lado legible, o
  • Utilizando los métodos cipher.update() y cipher.final() para producir los datos cifrados.

El método crypto.createCipheriv() se utiliza para crear instancias de Cipher. Los objetos Cipher no deben crearse directamente utilizando la palabra clave new.

Ejemplo: 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();
  });
});

Ejemplo: Usando Cipher y streams canalizados:

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

Ejemplo: Usando los métodos cipher.update() y 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]) ​

Agregado en: v0.1.94

  • outputEncoding <string> La codificación del valor de retorno.
  • Devuelve: <Buffer> | <string> Cualquier contenido cifrado restante. Si se especifica outputEncoding, se devuelve una cadena. Si no se proporciona outputEncoding, se devuelve un Buffer.

Una vez que se ha llamado al método cipher.final(), el objeto Cipher ya no se puede usar para cifrar datos. Los intentos de llamar a cipher.final() más de una vez provocarán que se arroje un error.

cipher.getAuthTag() ​

Agregado en: v1.0.0

  • Devuelve: <Buffer> Cuando se utiliza un modo de cifrado autenticado (actualmente se admiten GCM, CCM, OCB y chacha20-poly1305), el método cipher.getAuthTag() devuelve un Buffer que contiene la etiqueta de autenticación que se ha calculado a partir de los datos proporcionados.

El método cipher.getAuthTag() solo debe llamarse una vez que el cifrado se haya completado utilizando el método cipher.final().

Si la opción authTagLength se estableció durante la creación de la instancia cipher, esta función devolverá exactamente authTagLength bytes.

cipher.setAAD(buffer[, options]) ​

Agregado en: v1.0.0

Cuando se utiliza un modo de cifrado autenticado (actualmente se admiten GCM, CCM, OCB y chacha20-poly1305), el método cipher.setAAD() establece el valor utilizado para el parámetro de entrada datos autenticados adicionales (AAD).

La opción plaintextLength es opcional para GCM y OCB. Cuando se utiliza CCM, la opción plaintextLength debe especificarse y su valor debe coincidir con la longitud del texto sin cifrar en bytes. Consulte modo CCM.

El método cipher.setAAD() debe llamarse antes de cipher.update().

cipher.setAutoPadding([autoPadding]) ​

Agregado en: v0.7.1

  • autoPadding <boolean> Predeterminado: true
  • Devuelve: <Cipher> La misma instancia de Cipher para el encadenamiento de métodos.

Cuando se utilizan algoritmos de cifrado por bloques, la clase Cipher agregará automáticamente relleno a los datos de entrada al tamaño de bloque apropiado. Para deshabilitar el relleno predeterminado, llame a cipher.setAutoPadding(false).

Cuando autoPadding es false, la longitud de todos los datos de entrada debe ser un múltiplo del tamaño de bloque del cifrado o cipher.final() generará un error. Deshabilitar el relleno automático es útil para el relleno no estándar, por ejemplo, usar 0x0 en lugar del relleno PKCS.

El método cipher.setAutoPadding() debe llamarse antes de cipher.final().

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

[Historial]

VersiónCambios
v6.0.0El inputEncoding predeterminado cambió de binary a utf8.
v0.1.94Agregado en: v0.1.94

Actualiza el cifrado con data. Si se proporciona el argumento inputEncoding, el argumento data es una cadena que utiliza la codificación especificada. Si no se proporciona el argumento inputEncoding, data debe ser un Buffer, TypedArray o DataView. Si data es un Buffer, TypedArray o DataView, entonces se ignora inputEncoding.

El outputEncoding especifica el formato de salida de los datos cifrados. Si se especifica outputEncoding, se devuelve una cadena que utiliza la codificación especificada. Si no se proporciona outputEncoding, se devuelve un Buffer.

El método cipher.update() se puede llamar varias veces con datos nuevos hasta que se llame a cipher.final(). Llamar a cipher.update() después de cipher.final() provocará que se produzca un error.

Clase: Decipher ​

Agregado en: v0.1.94

Las instancias de la clase Decipher se utilizan para descifrar datos. La clase se puede usar de dos maneras:

  • Como un stream que es tanto legible como escribible, donde se escriben datos cifrados sin formato para producir datos descifrados en el lado legible, o
  • Usando los métodos decipher.update() y decipher.final() para producir los datos descifrados.

El método crypto.createDecipheriv() se utiliza para crear instancias de Decipher. Los objetos Decipher no deben crearse directamente usando la palabra clave new.

Ejemplo: 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();

Ejemplo: Usando Decipher y streams canalizados:

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

Ejemplo: Usando los métodos decipher.update() y 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]) ​

Añadido en: v0.1.94

  • outputEncoding <string> La codificación del valor de retorno.
  • Devuelve: <Buffer> | <string> Cualquier contenido descifrado restante. Si se especifica outputEncoding, se devuelve una cadena. Si no se proporciona outputEncoding, se devuelve un Buffer.

Una vez que se ha llamado al método decipher.final(), el objeto Decipher ya no se puede utilizar para descifrar datos. Los intentos de llamar a decipher.final() más de una vez provocarán que se lance un error.

decipher.setAAD(buffer[, options]) ​

[Historial]

VersiónCambios
v15.0.0El argumento buffer puede ser una cadena o ArrayBuffer y está limitado a no más de 2 ** 31 - 1 bytes.
v7.2.0Este método ahora devuelve una referencia a decipher.
v1.0.0Añadido en: v1.0.0

Cuando se utiliza un modo de cifrado autenticado (actualmente se admiten GCM, CCM, OCB y chacha20-poly1305), el método decipher.setAAD() establece el valor utilizado para el parámetro de entrada de datos autenticados adicionales (AAD).

El argumento options es opcional para GCM. Cuando se utiliza CCM, se debe especificar la opción plaintextLength y su valor debe coincidir con la longitud del texto cifrado en bytes. Consulte modo CCM.

El método decipher.setAAD() debe llamarse antes de decipher.update().

Cuando se pasa una cadena como buffer, considere advertencias al usar cadenas como entradas para las API criptográficas.

decipher.setAuthTag(buffer[, encoding]) ​

[Historial]

VersiónCambios
v22.0.0, v20.13.0El uso de longitudes de etiqueta GCM distintas de 128 bits sin especificar la opción authTagLength al crear decipher está obsoleto.
v15.0.0El argumento buffer puede ser una cadena o ArrayBuffer y está limitado a no más de 2 ** 31 - 1 bytes.
v11.0.0Este método ahora lanza un error si la longitud de la etiqueta GCM no es válida.
v7.2.0Este método ahora devuelve una referencia a decipher.
v1.0.0Añadido en: v1.0.0

Cuando se utiliza un modo de cifrado autenticado (actualmente se admiten GCM, CCM, OCB y chacha20-poly1305), el método decipher.setAuthTag() se utiliza para pasar la etiqueta de autenticación recibida. Si no se proporciona ninguna etiqueta, o si el texto cifrado ha sido manipulado, decipher.final() lanzará un error, indicando que el texto cifrado debe ser descartado debido a un fallo de autenticación. Si la longitud de la etiqueta no es válida según NIST SP 800-38D o no coincide con el valor de la opción authTagLength, decipher.setAuthTag() lanzará un error.

El método decipher.setAuthTag() debe ser llamado antes de decipher.update() para el modo CCM o antes de decipher.final() para los modos GCM y OCB y chacha20-poly1305. decipher.setAuthTag() sólo puede ser llamado una vez.

Cuando se pasa una cadena como etiqueta de autenticación, por favor, considere advertencias al usar cadenas como entradas para las APIs criptográficas.

decipher.setAutoPadding([autoPadding]) ​

Agregado en: v0.7.1

  • autoPadding <boolean> Predeterminado: true
  • Devuelve: <Decipher> El mismo Decipher para el encadenamiento de métodos.

Cuando los datos se han cifrado sin relleno de bloque estándar, llamar a decipher.setAutoPadding(false) desactivará el relleno automático para evitar que decipher.final() compruebe y elimine el relleno.

Desactivar el relleno automático solo funcionará si la longitud de los datos de entrada es un múltiplo del tamaño del bloque de los cifrados.

El método decipher.setAutoPadding() debe ser llamado antes de decipher.final().

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

[Historial]

VersiónCambios
v6.0.0El inputEncoding predeterminado cambió de binary a utf8.
v0.1.94Agregado en: v0.1.94

Actualiza el descifrado con data. Si se proporciona el argumento inputEncoding, el argumento data es una cadena que utiliza la codificación especificada. Si no se proporciona el argumento inputEncoding, data debe ser un Buffer. Si data es un Buffer entonces inputEncoding se ignora.

El outputEncoding especifica el formato de salida de los datos cifrados. Si se especifica el outputEncoding, se devuelve una cadena utilizando la codificación especificada. Si no se proporciona ningún outputEncoding, se devuelve un Buffer.

El método decipher.update() se puede llamar varias veces con nuevos datos hasta que se llame a decipher.final(). Llamar a decipher.update() después de decipher.final() provocará que se lance un error.

Incluso si el cifrado subyacente implementa la autenticación, la autenticidad y la integridad del texto plano devuelto por esta función pueden ser inciertas en este momento. Para los algoritmos de cifrado autenticados, la autenticidad generalmente solo se establece cuando la aplicación llama a decipher.final().

Clase: DiffieHellman ​

Añadido en: v0.5.0

La clase DiffieHellman es una utilidad para crear intercambios de claves Diffie-Hellman.

Las instancias de la clase DiffieHellman se pueden crear utilizando la función crypto.createDiffieHellman().

js
import assert from 'node:assert';

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

// Generar las claves de Alice...
const alice = createDiffieHellman(2048);
const aliceKey = alice.generateKeys();

// Generar las claves de Bob...
const bob = createDiffieHellman(alice.getPrime(), alice.getGenerator());
const bobKey = bob.generateKeys();

// Intercambiar y generar el secreto...
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');

// Generar las claves de Alice...
const alice = createDiffieHellman(2048);
const aliceKey = alice.generateKeys();

// Generar las claves de Bob...
const bob = createDiffieHellman(alice.getPrime(), alice.getGenerator());
const bobKey = bob.generateKeys();

// Intercambiar y generar el secreto...
const aliceSecret = alice.computeSecret(bobKey);
const bobSecret = bob.computeSecret(aliceKey);

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

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

Añadido en: v0.5.0

Calcula el secreto compartido usando otherPublicKey como la clave pública de la otra parte y devuelve el secreto compartido calculado. La clave proporcionada se interpreta utilizando el inputEncoding especificado, y el secreto se codifica utilizando el outputEncoding especificado. Si no se proporciona el inputEncoding, se espera que otherPublicKey sea un Buffer, TypedArray o DataView.

Si se proporciona outputEncoding, se devuelve una cadena; de lo contrario, se devuelve un Buffer.

diffieHellman.generateKeys([encoding]) ​

Añadido en: v0.5.0

Genera valores de clave Diffie-Hellman privada y pública a menos que ya hayan sido generados o calculados, y devuelve la clave pública en la encoding especificada. Esta clave debe ser transferida a la otra parte. Si se proporciona encoding, se devuelve una cadena; de lo contrario, se devuelve un Buffer.

Esta función es un simple contenedor alrededor de DH_generate_key(). En particular, una vez que se ha generado o establecido una clave privada, la llamada a esta función solo actualiza la clave pública, pero no genera una nueva clave privada.

diffieHellman.getGenerator([encoding]) ​

Añadido en: v0.5.0

Devuelve el generador Diffie-Hellman en la encoding especificada. Si se proporciona encoding, se devuelve una cadena; de lo contrario, se devuelve un Buffer.

diffieHellman.getPrime([encoding]) ​

Añadido en: v0.5.0

Devuelve el primo Diffie-Hellman en la encoding especificada. Si se proporciona encoding, se devuelve una cadena; de lo contrario, se devuelve un Buffer.

diffieHellman.getPrivateKey([encoding]) ​

Agregado en: v0.5.0

Devuelve la clave privada de Diffie-Hellman en la encoding especificada. Si se proporciona encoding, se devuelve una string; de lo contrario, se devuelve un Buffer.

diffieHellman.getPublicKey([encoding]) ​

Agregado en: v0.5.0

Devuelve la clave pública de Diffie-Hellman en la encoding especificada. Si se proporciona encoding, se devuelve una string; de lo contrario, se devuelve un Buffer.

diffieHellman.setPrivateKey(privateKey[, encoding]) ​

Agregado en: v0.5.0

Establece la clave privada Diffie-Hellman. Si se proporciona el argumento encoding, se espera que privateKey sea una string. Si no se proporciona encoding, se espera que privateKey sea un Buffer, TypedArray o DataView.

Esta función no calcula automáticamente la clave pública asociada. Se puede usar diffieHellman.setPublicKey() o diffieHellman.generateKeys() para proporcionar manualmente la clave pública o para derivarla automáticamente.

diffieHellman.setPublicKey(publicKey[, encoding]) ​

Agregado en: v0.5.0

Establece la clave pública de Diffie-Hellman. Si se proporciona el argumento encoding, se espera que publicKey sea una cadena. Si no se proporciona encoding, se espera que publicKey sea un Buffer, TypedArray o DataView.

diffieHellman.verifyError ​

Agregado en: v0.11.12

Un campo de bits que contiene cualquier advertencia y/o error resultante de una verificación realizada durante la inicialización del objeto DiffieHellman.

Los siguientes valores son válidos para esta propiedad (como se define en el módulo node:constants):

  • DH_CHECK_P_NOT_SAFE_PRIME
  • DH_CHECK_P_NOT_PRIME
  • DH_UNABLE_TO_CHECK_GENERATOR
  • DH_NOT_SUITABLE_GENERATOR

Clase: DiffieHellmanGroup ​

Agregado en: v0.7.5

La clase DiffieHellmanGroup toma un grupo modp bien conocido como su argumento. Funciona igual que DiffieHellman, excepto que no permite cambiar sus claves después de la creación. En otras palabras, no implementa los métodos setPublicKey() o setPrivateKey().

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

Los siguientes grupos son compatibles:

  • 'modp14' (2048 bits, RFC 3526 Sección 3)
  • 'modp15' (3072 bits, RFC 3526 Sección 4)
  • 'modp16' (4096 bits, RFC 3526 Sección 5)
  • 'modp17' (6144 bits, RFC 3526 Sección 6)
  • 'modp18' (8192 bits, RFC 3526 Sección 7)

Los siguientes grupos todavía son compatibles pero están obsoletos (ver Advertencias):

  • 'modp1' (768 bits, RFC 2409 Sección 6.1)
  • 'modp2' (1024 bits, RFC 2409 Sección 6.2)
  • 'modp5' (1536 bits, RFC 3526 Sección 2)

Estos grupos obsoletos podrían eliminarse en futuras versiones de Node.js.

Clase: ECDH ​

Agregado en: v0.11.14

La clase ECDH es una utilidad para crear intercambios de claves Diffie-Hellman de curva elíptica (ECDH).

Las instancias de la clase ECDH se pueden crear usando la función crypto.createECDH().

js
import assert from 'node:assert';

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

// Genera las claves de Alice...
const alice = createECDH('secp521r1');
const aliceKey = alice.generateKeys();

// Genera las claves de Bob...
const bob = createECDH('secp521r1');
const bobKey = bob.generateKeys();

// Intercambia y genera el secreto...
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');

// Genera las claves de Alice...
const alice = createECDH('secp521r1');
const aliceKey = alice.generateKeys();

// Genera las claves de Bob...
const bob = createECDH('secp521r1');
const bobKey = bob.generateKeys();

// Intercambia y genera el secreto...
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]]]) ​

Agregado en: v10.0.0

Convierte la clave pública EC Diffie-Hellman especificada por key y curve al formato especificado por format. El argumento format especifica la codificación de puntos y puede ser 'compressed', 'uncompressed' o 'hybrid'. La clave suministrada se interpreta utilizando la inputEncoding especificada, y la clave devuelta se codifica utilizando la outputEncoding especificada.

Utilice crypto.getCurves() para obtener una lista de nombres de curvas disponibles. En las versiones recientes de OpenSSL, openssl ecparam -list_curves también mostrará el nombre y la descripción de cada curva elíptica disponible.

Si no se especifica format, el punto se devolverá en formato 'uncompressed'.

Si no se proporciona inputEncoding, se espera que key sea un Buffer, TypedArray o DataView.

Ejemplo (descomprimiendo una clave):

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

// La clave convertida y la clave pública sin comprimir deben ser iguales
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');

// La clave convertida y la clave pública sin comprimir deben ser iguales
console.log(uncompressedKey === ecdh.getPublicKey('hex'));

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

[Historial]

VersiónCambios
v10.0.0Se cambió el formato de error para admitir mejor el error de clave pública no válida.
v6.0.0El inputEncoding predeterminado cambió de binary a utf8.
v0.11.14Añadido en: v0.11.14

Calcula el secreto compartido usando otherPublicKey como la clave pública de la otra parte y devuelve el secreto compartido calculado. La clave suministrada se interpreta utilizando el inputEncoding especificado, y el secreto devuelto se codifica utilizando el outputEncoding especificado. Si no se proporciona el inputEncoding, se espera que otherPublicKey sea un Buffer, TypedArray o DataView.

Si se proporciona outputEncoding, se devolverá una cadena; de lo contrario, se devolverá un Buffer.

ecdh.computeSecret lanzará un error ERR_CRYPTO_ECDH_INVALID_PUBLIC_KEY cuando otherPublicKey se encuentre fuera de la curva elíptica. Dado que otherPublicKey generalmente se suministra desde un usuario remoto a través de una red insegura, asegúrese de manejar esta excepción en consecuencia.

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

Agregado en: v0.11.14

Genera valores de clave privada y pública EC Diffie-Hellman, y devuelve la clave pública en el format y encoding especificados. Esta clave debe transferirse a la otra parte.

El argumento format especifica la codificación de puntos y puede ser 'compressed' o 'uncompressed'. Si no se especifica format, el punto se devolverá en formato 'uncompressed'.

Si se proporciona encoding, se devuelve una cadena; de lo contrario, se devuelve un Buffer.

ecdh.getPrivateKey([encoding]) ​

Agregado en: v0.11.14

Si se especifica encoding, se devuelve una cadena; de lo contrario, se devuelve un Buffer.

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

Agregado en: v0.11.14

El argumento format especifica la codificación de puntos y puede ser 'compressed' o 'uncompressed'. Si no se especifica format, el punto se devolverá en formato 'uncompressed'.

Si se especifica encoding, se devuelve una cadena; de lo contrario, se devuelve un Buffer.

ecdh.setPrivateKey(privateKey[, encoding]) ​

Añadido en: v0.11.14

Establece la clave privada EC Diffie-Hellman. Si se proporciona encoding, se espera que privateKey sea una cadena; de lo contrario, se espera que privateKey sea un Buffer, TypedArray o DataView.

Si privateKey no es válido para la curva especificada cuando se creó el objeto ECDH, se genera un error. Al establecer la clave privada, también se genera el punto (clave) público asociado y se establece en el objeto ECDH.

ecdh.setPublicKey(publicKey[, encoding]) ​

Añadido en: v0.11.14

Obsoleto desde: v5.2.0

[Estable: 0 - Obsoleto]

Estable: 0 Estabilidad: 0 - Obsoleto

Establece la clave pública EC Diffie-Hellman. Si se proporciona encoding, se espera que publicKey sea una cadena; de lo contrario, se espera un Buffer, TypedArray o DataView.

Normalmente, no hay razón para llamar a este método porque ECDH solo requiere una clave privada y la clave pública de la otra parte para calcular el secreto compartido. Por lo general, se llamará a ecdh.generateKeys() o ecdh.setPrivateKey(). El método ecdh.setPrivateKey() intenta generar el punto/clave pública asociado con la clave privada que se está estableciendo.

Ejemplo (obtención de un secreto compartido):

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

Clase: Hash ​

Añadido en: v0.1.92

La clase Hash es una utilidad para crear resúmenes hash de datos. Puede utilizarse de dos maneras:

  • Como un stream que es tanto legible como escribible, donde los datos se escriben para producir un resumen hash calculado en el lado legible, o
  • Utilizando los métodos hash.update() y hash.digest() para producir el hash calculado.

El método crypto.createHash() se utiliza para crear instancias de Hash. Los objetos Hash no deben crearse directamente utilizando la palabra clave new.

Ejemplo: Utilización de objetos Hash como streams:

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

const hash = createHash('sha256');

hash.on('readable', () => {
  // Sólo un elemento va a ser producido por el
  // stream 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', () => {
  // Sólo un elemento va a ser producido por el
  // stream hash.
  const data = hash.read();
  if (data) {
    console.log(data.toString('hex'));
    // Imprime:
    //   6a2da20943931e9834fc12cfe5bb47bbd9ae43489a30726962b576f4e3993e50
  }
});

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

Ejemplo: Utilización de Hash y streams canalizados:

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

Ejemplo: Utilización de los métodos hash.update() y 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]) ​

Agregado en: v13.1.0

Crea un nuevo objeto Hash que contiene una copia profunda del estado interno del objeto Hash actual.

El argumento opcional options controla el comportamiento del flujo. Para las funciones hash XOF como 'shake256', la opción outputLength se puede utilizar para especificar la longitud de salida deseada en bytes.

Se produce un error cuando se intenta copiar el objeto Hash después de que se haya llamado a su método hash.digest().

js
// Calcula un hash rodante.
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
// Calcula un hash rodante.
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]) ​

Agregado en: v0.1.92

Calcula el resumen de todos los datos pasados para ser hasheados (usando el método hash.update()). Si se proporciona encoding se devolverá una cadena; de lo contrario, se devuelve un Buffer.

El objeto Hash no se puede volver a utilizar después de que se haya llamado al método hash.digest(). Las llamadas múltiples provocarán que se lance un error.

hash.update(data[, inputEncoding]) ​

[Historial]

VersiónCambios
v6.0.0El inputEncoding predeterminado cambió de binary a utf8.
v0.1.92Añadido en: v0.1.92

Actualiza el contenido del hash con los data dados, cuya codificación se indica en inputEncoding. Si no se proporciona encoding y los data son una cadena, se aplica una codificación de 'utf8'. Si data es un Buffer, TypedArray o DataView, entonces se ignora inputEncoding.

Se puede llamar a esto muchas veces con nuevos datos a medida que se transmiten.

Clase: Hmac ​

Añadido en: v0.1.94

La clase Hmac es una utilidad para crear resúmenes criptográficos HMAC. Se puede usar de una de estas dos maneras:

  • Como un stream que es tanto legible como escribible, donde los datos se escriben para producir un resumen HMAC calculado en el lado legible, o
  • Usando los métodos hmac.update() y hmac.digest() para producir el resumen HMAC calculado.

El método crypto.createHmac() se usa para crear instancias de Hmac. Los objetos Hmac no deben crearse directamente usando la palabra clave new.

Ejemplo: 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:
    //   7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f33ad9c87c518115a45971f7f77e
  }
});

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

Ejemplo: Usando Hmac y 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);

Ejemplo: Usando los métodos hmac.update() y 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]) ​

Agregado en: v0.1.94

Calcula el resumen HMAC de todos los datos pasados usando hmac.update(). Si se proporciona encoding, se devuelve una cadena; de lo contrario, se devuelve un Buffer.

El objeto Hmac no se puede volver a utilizar después de que se haya llamado a hmac.digest(). Las llamadas múltiples a hmac.digest() provocarán que se lance un error.

hmac.update(data[, inputEncoding]) ​

[Historial]

VersiónCambios
v6.0.0El inputEncoding predeterminado cambió de binary a utf8.
v0.1.94Agregado en: v0.1.94

Actualiza el contenido de Hmac con los data dados, cuya codificación se da en inputEncoding. Si no se proporciona encoding y los data son una cadena, se aplica una codificación de 'utf8'. Si data es un Buffer, TypedArray o DataView, entonces inputEncoding se ignora.

Esto se puede llamar muchas veces con nuevos datos a medida que se transmiten.

Clase: KeyObject ​

[Historial]

VersiónCambios
v14.5.0, v12.19.0Las instancias de esta clase ahora se pueden pasar a hilos de trabajo usando postMessage.
v11.13.0Esta clase ahora se exporta.
v11.6.0Agregado en: v11.6.0

Node.js usa una clase KeyObject para representar una clave simétrica o asimétrica, y cada tipo de clave expone diferentes funciones. Los métodos crypto.createSecretKey(), crypto.createPublicKey() y crypto.createPrivateKey() se utilizan para crear instancias de KeyObject. Los objetos KeyObject no deben crearse directamente usando la palabra clave new.

La mayoría de las aplicaciones deberían considerar usar la nueva API KeyObject en lugar de pasar claves como cadenas o Buffers debido a las características de seguridad mejoradas.

Las instancias de KeyObject se pueden pasar a otros hilos a través de postMessage(). El receptor obtiene un KeyObject clonado y el KeyObject no necesita estar listado en el argumento transferList.

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

Añadido en: v15.0.0

Ejemplo: Convertir una instancia de CryptoKey a un KeyObject:

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

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

const keyObject = KeyObject.from(key);
console.log(keyObject.symmetricKeySize);
// Imprime: 32 (tamaño de la clave simétrica en bytes)
js
const { KeyObject } = require('node:crypto');
const { subtle } = globalThis.crypto;

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

  const keyObject = KeyObject.from(key);
  console.log(keyObject.symmetricKeySize);
  // Imprime: 32 (tamaño de la clave simétrica en bytes)
})();

keyObject.asymmetricKeyDetails ​

[Historial]

VersiónCambios
v16.9.0Expone los parámetros de la secuencia RSASSA-PSS-params para las claves RSA-PSS.
v15.7.0Añadido en: v15.7.0
  • <Object>
    • modulusLength: <number> Tamaño de la clave en bits (RSA, DSA).
    • publicExponent: <bigint> Exponente público (RSA).
    • hashAlgorithm: <string> Nombre del resumen del mensaje (RSA-PSS).
    • mgf1HashAlgorithm: <string> Nombre del resumen del mensaje utilizado por MGF1 (RSA-PSS).
    • saltLength: <number> Longitud mínima de la sal en bytes (RSA-PSS).
    • divisorLength: <number> Tamaño de q en bits (DSA).
    • namedCurve: <string> Nombre de la curva (EC).

Esta propiedad existe sólo en las claves asimétricas. Dependiendo del tipo de la clave, este objeto contiene información sobre la clave. Ninguna de la información obtenida a través de esta propiedad puede ser utilizada para identificar de forma única una clave o para comprometer la seguridad de la clave.

Para las claves RSA-PSS, si el material de la clave contiene una secuencia RSASSA-PSS-params, las propiedades hashAlgorithm, mgf1HashAlgorithm y saltLength se establecerán.

Otros detalles de la clave pueden ser expuestos a través de esta API utilizando atributos adicionales.

keyObject.asymmetricKeyType ​

[Historial]

VersiónCambios
v13.9.0, v12.17.0Se agregó soporte para 'dh'.
v12.0.0Se agregó soporte para 'rsa-pss'.
v12.0.0Esta propiedad ahora devuelve undefined para instancias de KeyObject de tipo no reconocido en lugar de abortar.
v12.0.0Se agregó soporte para 'x25519' y 'x448'.
v12.0.0Se agregó soporte para 'ed25519' y 'ed448'.
v11.6.0Agregado en: v11.6.0

Para claves asimétricas, esta propiedad representa el tipo de clave. Los tipos de clave admitidos son:

  • '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 propiedad es undefined para tipos KeyObject no reconocidos y claves simétricas.

keyObject.equals(otherKeyObject) ​

Agregado en: v17.7.0, v16.15.0

Devuelve true o false dependiendo de si las claves tienen exactamente el mismo tipo, valor y parámetros. Este método no es de tiempo constante.

keyObject.export([options]) ​

[Historial]

VersiónCambios
v15.9.0Se agregó soporte para el formato 'jwk'.
v11.6.0Agregado en: v11.6.0

Para claves simétricas, se pueden utilizar las siguientes opciones de codificación:

  • format: <string> Debe ser 'buffer' (predeterminado) o 'jwk'.

Para claves públicas, se pueden utilizar las siguientes opciones de codificación:

  • type: <string> Debe ser uno de 'pkcs1' (solo RSA) o 'spki'.
  • format: <string> Debe ser 'pem', 'der' o 'jwk'.

Para claves privadas, se pueden utilizar las siguientes opciones de codificación:

  • type: <string> Debe ser uno de 'pkcs1' (solo RSA), 'pkcs8' o 'sec1' (solo EC).
  • format: <string> Debe ser 'pem', 'der' o 'jwk'.
  • cipher: <string> Si se especifica, la clave privada se cifrará con el cipher y la passphrase dados utilizando el cifrado basado en contraseña PKCS#5 v2.0.
  • passphrase: <string> | <Buffer> La contraseña para usar para el cifrado, vea cipher.

El tipo de resultado depende del formato de codificación seleccionado, cuando PEM el resultado es una cadena, cuando DER será un búfer que contiene los datos codificados como DER, cuando JWK será un objeto.

Cuando se seleccionó el formato de codificación JWK, se ignoran todas las demás opciones de codificación.

Las claves de tipo PKCS#1, SEC1 y PKCS#8 se pueden cifrar utilizando una combinación de las opciones cipher y format. El type PKCS#8 se puede utilizar con cualquier format para cifrar cualquier algoritmo de clave (RSA, EC o DH) especificando un cipher. PKCS#1 y SEC1 solo se pueden cifrar especificando un cipher cuando se utiliza el format PEM. Para una máxima compatibilidad, utilice PKCS#8 para claves privadas cifradas. Dado que PKCS#8 define su propio mecanismo de cifrado, el cifrado a nivel de PEM no es compatible al cifrar una clave PKCS#8. Consulte RFC 5208 para el cifrado PKCS#8 y RFC 1421 para el cifrado PKCS#1 y SEC1.

keyObject.symmetricKeySize ​

Añadido en: v11.6.0

Para claves secretas, esta propiedad representa el tamaño de la clave en bytes. Esta propiedad es undefined para claves asimétricas.

keyObject.toCryptoKey(algorithm, extractable, keyUsages) ​

Añadido en: v23.0.0

Convierte una instancia de KeyObject en una CryptoKey.

keyObject.type ​

Añadido en: v11.6.0

Dependiendo del tipo de este KeyObject, esta propiedad es 'secret' para claves secretas (simétricas), 'public' para claves públicas (asimétricas) o 'private' para claves privadas (asimétricas).

Clase: Sign ​

Añadido en: v0.1.92

La clase Sign es una utilidad para generar firmas. Se puede usar de dos maneras:

  • Como un flujo de escritura, donde se escriben los datos que se van a firmar y el método sign.sign() se utiliza para generar y devolver la firma, o
  • Usando los métodos sign.update() y sign.sign() para producir la firma.

El método crypto.createSign() se utiliza para crear instancias de Sign. El argumento es el nombre de cadena de la función hash que se va a utilizar. Los objetos Sign no deben crearse directamente utilizando la palabra clave new.

Ejemplo: Usando objetos Sign y Verify como flujos:

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

Ejemplo: Usando los métodos sign.update() y 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]) ​

[Historia]

VersiónCambios
v15.0.0La privateKey también puede ser un ArrayBuffer y CryptoKey.
v13.2.0, v12.16.0Esta función ahora es compatible con firmas IEEE-P1363 DSA y ECDSA.
v12.0.0Esta función ahora es compatible con claves RSA-PSS.
v11.6.0Esta función ahora es compatible con objetos de clave.
v8.0.0Se agregó soporte para RSASSA-PSS y opciones adicionales.
v0.1.92Agregado en: v0.1.92

Calcula la firma de todos los datos pasados a través de sign.update() o sign.write().

Si privateKey no es un KeyObject, esta función se comporta como si privateKey se hubiera pasado a crypto.createPrivateKey(). Si es un objeto, se pueden pasar las siguientes propiedades adicionales:

  • dsaEncoding <string> Para DSA y ECDSA, esta opción especifica el formato de la firma generada. Puede ser uno de los siguientes:

    • 'der' (predeterminado): estructura de firma ASN.1 codificada en DER que codifica (r, s).
    • 'ieee-p1363': Formato de firma r || s como se propone en IEEE-P1363.

  • padding <integer> Valor de relleno opcional para RSA, uno de los siguientes:

    • crypto.constants.RSA_PKCS1_PADDING (predeterminado)
    • crypto.constants.RSA_PKCS1_PSS_PADDING

RSA_PKCS1_PSS_PADDING usará MGF1 con la misma función hash utilizada para firmar el mensaje como se especifica en la sección 3.1 de RFC 4055, a menos que se haya especificado una función hash MGF1 como parte de la clave de acuerdo con la sección 3.3 de RFC 4055.

  • saltLength <integer> Longitud de la sal cuando el relleno es RSA_PKCS1_PSS_PADDING. El valor especial crypto.constants.RSA_PSS_SALTLEN_DIGEST establece la longitud de la sal al tamaño del resumen, crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN (predeterminado) la establece al valor máximo permisible.

Si se proporciona outputEncoding, se devuelve una cadena; de lo contrario, se devuelve un Buffer.

El objeto Sign no se puede volver a utilizar después de que se haya llamado al método sign.sign(). Varias llamadas a sign.sign() provocarán que se produzca un error.

sign.update(data[, inputEncoding]) ​

[Historial]

VersiónCambios
v6.0.0La inputEncoding predeterminada cambió de binary a utf8.
v0.1.92Añadido en: v0.1.92

Actualiza el contenido de Sign con los data dados, cuya codificación se indica en inputEncoding. Si no se proporciona encoding y data es una cadena, se aplica una codificación de 'utf8'. Si data es un Buffer, TypedArray o DataView, entonces se ignora inputEncoding.

Esto se puede llamar muchas veces con datos nuevos a medida que se transmiten.

Clase: Verify ​

Añadido en: v0.1.92

La clase Verify es una utilidad para verificar firmas. Se puede utilizar de una de estas dos maneras:

  • Como un stream de escritura donde los datos escritos se utilizan para validar la firma suministrada, o
  • Utilizando los métodos verify.update() y verify.verify() para verificar la firma.

El método crypto.createVerify() se utiliza para crear instancias de Verify. Los objetos Verify no se deben crear directamente utilizando la palabra clave new.

Ver Sign para ejemplos.

verify.update(data[, inputEncoding]) ​

[Historial]

VersiónCambios
v6.0.0La inputEncoding predeterminada cambió de binary a utf8.
v0.1.92Añadido en: v0.1.92

Actualiza el contenido de Verify con los data dados, cuya codificación se indica en inputEncoding. Si no se proporciona inputEncoding y data es una cadena, se aplica una codificación de 'utf8'. Si data es un Buffer, TypedArray o DataView, entonces se ignora inputEncoding.

Esto se puede llamar muchas veces con datos nuevos a medida que se transmiten.

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

[Historial]

VersiónCambios
v15.0.0El objeto también puede ser un ArrayBuffer y CryptoKey.
v13.2.0, v12.16.0Esta función ahora es compatible con las firmas DSA y ECDSA de IEEE-P1363.
v12.0.0Esta función ahora es compatible con las claves RSA-PSS.
v11.7.0La clave ahora puede ser una clave privada.
v8.0.0Se añadió compatibilidad para RSASSA-PSS y opciones adicionales.
v0.1.92Añadido en: v0.1.92

Verifica los datos proporcionados utilizando el object y la signature dados.

Si object no es un KeyObject, esta función se comporta como si object se hubiera pasado a crypto.createPublicKey(). Si es un objeto, se pueden pasar las siguientes propiedades adicionales:

  • dsaEncoding <string> Para DSA y ECDSA, esta opción especifica el formato de la firma. Puede ser uno de los siguientes:

    • 'der' (predeterminado): Estructura de firma ASN.1 codificada en DER que codifica (r, s).
    • 'ieee-p1363': Formato de firma r || s como se propone en IEEE-P1363.

  • padding <integer> Valor de relleno opcional para RSA, uno de los siguientes:

    • crypto.constants.RSA_PKCS1_PADDING (predeterminado)
    • crypto.constants.RSA_PKCS1_PSS_PADDING

RSA_PKCS1_PSS_PADDING utilizará MGF1 con la misma función hash utilizada para verificar el mensaje, tal como se especifica en la sección 3.1 de RFC 4055, a menos que se haya especificado una función hash MGF1 como parte de la clave de conformidad con la sección 3.3 de RFC 4055.

  • saltLength <integer> Longitud de la sal para cuando el relleno es RSA_PKCS1_PSS_PADDING. El valor especial crypto.constants.RSA_PSS_SALTLEN_DIGEST establece la longitud de la sal al tamaño del resumen, crypto.constants.RSA_PSS_SALTLEN_AUTO (predeterminado) hace que se determine automáticamente.

El argumento signature es la firma calculada previamente para los datos, en signatureEncoding. Si se especifica un signatureEncoding, se espera que signature sea una cadena; de lo contrario, se espera que signature sea un Buffer, TypedArray o DataView.

El objeto verify no se puede volver a utilizar después de que se haya llamado a verify.verify(). Varias llamadas a verify.verify() darán como resultado que se lance un error.

Dado que las claves públicas pueden derivarse de las claves privadas, se puede pasar una clave privada en lugar de una clave pública.

Clase: X509Certificate ​

Agregado en: v15.6.0

Encapsula un certificado X509 y proporciona acceso de solo lectura a su información.

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

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

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

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

console.log(x509.subject);

new X509Certificate(buffer) ​

Agregado en: v15.6.0

x509.ca ​

Agregado en: v15.6.0

  • Tipo: <boolean> Será true si este es un certificado de Autoridad de Certificación (CA).

x509.checkEmail(email[, options]) ​

[Historial]

VersiónCambios
v18.0.0La opción subject ahora tiene como valor predeterminado 'default'.
v17.5.0, v16.15.0La opción subject ahora se puede establecer en 'default'.
v17.5.0, v16.14.1Se eliminaron las opciones wildcards, partialWildcards, multiLabelWildcards y singleLabelSubdomains ya que no tenían ningún efecto.
v15.6.0Agregado en: v15.6.0

Comprueba si el certificado coincide con la dirección de correo electrónico dada.

Si la opción 'subject' no está definida o está establecida en 'default', el asunto del certificado solo se considera si la extensión de nombre alternativo del asunto no existe o no contiene ninguna dirección de correo electrónico.

Si la opción 'subject' está establecida en 'always' y si la extensión de nombre alternativo del asunto no existe o no contiene una dirección de correo electrónico coincidente, se considera el asunto del certificado.

Si la opción 'subject' está establecida en 'never', el asunto del certificado nunca se considera, incluso si el certificado no contiene nombres alternativos de asunto.

x509.checkHost(name[, options]) ​

[Historial]

VersiónCambios
v18.0.0La opción subject ahora tiene como valor predeterminado 'default'.
v17.5.0, v16.15.0La opción subject ahora se puede establecer en 'default'.
v15.6.0Agregado en: v15.6.0

  • name <string>

  • options <Object>

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

  • Devuelve: <string> | <undefined> Devuelve un nombre de asunto que coincide con name, o undefined si ningún nombre de asunto coincide con name.

Comprueba si el certificado coincide con el nombre de host dado.

Si el certificado coincide con el nombre de host dado, se devuelve el nombre de asunto coincidente. El nombre devuelto puede ser una coincidencia exacta (por ejemplo, foo.example.com) o puede contener comodines (por ejemplo, *.example.com). Debido a que las comparaciones de nombres de host no distinguen entre mayúsculas y minúsculas, el nombre de asunto devuelto también puede diferir del name dado en el uso de mayúsculas.

Si la opción 'subject' no está definida o se establece en 'default', el asunto del certificado solo se considera si la extensión del nombre alternativo del asunto no existe o no contiene ningún nombre DNS. Este comportamiento es coherente con RFC 2818 ("HTTP Over TLS").

Si la opción 'subject' se establece en 'always' y si la extensión del nombre alternativo del asunto no existe o no contiene un nombre DNS coincidente, se considera el asunto del certificado.

Si la opción 'subject' se establece en 'never', el asunto del certificado nunca se considera, incluso si el certificado no contiene nombres alternativos del asunto.

x509.checkIP(ip) ​

[Historial]

VersiónCambios
v17.5.0, v16.14.1El argumento options ha sido eliminado ya que no tenía efecto.
v15.6.0Añadido en: v15.6.0

Comprueba si el certificado coincide con la dirección IP dada (IPv4 o IPv6).

Solo se consideran los nombres alternativos del sujeto iPAddress RFC 5280, y deben coincidir exactamente con la dirección ip dada. Se ignoran otros nombres alternativos del sujeto, así como el campo del sujeto del certificado.

x509.checkIssued(otherCert) ​

Añadido en: v15.6.0

Comprueba si este certificado fue emitido por el otherCert dado.

x509.checkPrivateKey(privateKey) ​

Añadido en: v15.6.0

Comprueba si la clave pública de este certificado es consistente con la clave privada dada.

x509.extKeyUsage ​

Añadido en: v15.6.0

Un array que detalla los usos extendidos de la clave para este certificado.

x509.fingerprint ​

Añadido en: v15.6.0

La huella digital SHA-1 de este certificado.

Debido a que SHA-1 está roto criptográficamente y a que la seguridad de SHA-1 es significativamente peor que la de los algoritmos que se utilizan comúnmente para firmar certificados, considere usar x509.fingerprint256 en su lugar.

x509.fingerprint256 ​

Agregado en: v15.6.0

La huella digital SHA-256 de este certificado.

x509.fingerprint512 ​

Agregado en: v17.2.0, v16.14.0

La huella digital SHA-512 de este certificado.

Dado que calcular la huella digital SHA-256 suele ser más rápido y porque es solo la mitad del tamaño de la huella digital SHA-512, x509.fingerprint256 puede ser una mejor opción. Si bien SHA-512 presumiblemente proporciona un nivel de seguridad más alto en general, la seguridad de SHA-256 coincide con la de la mayoría de los algoritmos que se utilizan comúnmente para firmar certificados.

x509.infoAccess ​

[Historial]

VersiónCambios
v17.3.1, v16.13.2Partes de esta cadena pueden estar codificadas como literales de cadena JSON en respuesta a CVE-2021-44532.
v15.6.0Agregado en: v15.6.0

Una representación textual de la extensión de acceso a la información de la autoridad del certificado.

Esta es una lista separada por saltos de línea de descripciones de acceso. Cada línea comienza con el método de acceso y el tipo de ubicación de acceso, seguido de dos puntos y el valor asociado con la ubicación de acceso.

Después del prefijo que denota el método de acceso y el tipo de ubicación de acceso, el resto de cada línea podría estar entre comillas para indicar que el valor es un literal de cadena JSON. Por compatibilidad con versiones anteriores, Node.js solo usa literales de cadena JSON dentro de esta propiedad cuando es necesario para evitar ambigüedades. El código de terceros debe estar preparado para manejar ambos formatos de entrada posibles.

x509.issuer ​

Agregado en: v15.6.0

La identificación del emisor incluida en este certificado.

x509.issuerCertificate ​

Agregado en: v15.9.0

El certificado del emisor o undefined si el certificado del emisor no está disponible.

x509.publicKey ​

Agregado en: v15.6.0

La clave pública <KeyObject> para este certificado.

x509.raw ​

Agregado en: v15.6.0

Un Buffer que contiene la codificación DER de este certificado.

x509.serialNumber ​

Agregado en: v15.6.0

El número de serie de este certificado.

Los números de serie son asignados por las autoridades de certificación y no identifican de forma única los certificados. Considere usar x509.fingerprint256 como un identificador único en su lugar.

x509.subject ​

Agregado en: v15.6.0

El sujeto completo de este certificado.

x509.subjectAltName ​

[Historial]

VersiónCambios
v17.3.1, v16.13.2Partes de esta cadena pueden estar codificadas como literales de cadena JSON en respuesta a CVE-2021-44532.
v15.6.0Agregado en: v15.6.0

El nombre alternativo del sujeto especificado para este certificado.

Esta es una lista de nombres alternativos del sujeto separados por comas. Cada entrada comienza con una cadena que identifica el tipo de nombre alternativo del sujeto, seguida de dos puntos y el valor asociado con la entrada.

Las versiones anteriores de Node.js asumieron incorrectamente que es seguro dividir esta propiedad en la secuencia de dos caracteres ', ' (consulte CVE-2021-44532). Sin embargo, tanto los certificados maliciosos como los legítimos pueden contener nombres alternativos del sujeto que incluyen esta secuencia cuando se representan como una cadena.

Después del prefijo que denota el tipo de entrada, el resto de cada entrada puede estar entre comillas para indicar que el valor es un literal de cadena JSON. Por compatibilidad con versiones anteriores, Node.js solo usa literales de cadena JSON dentro de esta propiedad cuando es necesario para evitar la ambigüedad. El código de terceros debe estar preparado para manejar ambos formatos de entrada posibles.

x509.toJSON() ​

Agregado en: v15.6.0

No existe una codificación JSON estándar para los certificados X509. El método toJSON() devuelve una cadena que contiene el certificado codificado en PEM.

x509.toLegacyObject() ​

Agregado en: v15.6.0

Devuelve información sobre este certificado utilizando la codificación de objeto de certificado heredada.

x509.toString() ​

Agregado en: v15.6.0

Devuelve el certificado codificado en PEM.

x509.validFrom ​

Agregado en: v15.6.0

La fecha/hora a partir de la cual este certificado es válido.

x509.validFromDate ​

Agregado en: v23.0.0

La fecha/hora a partir de la cual este certificado es válido, encapsulada en un objeto Date.

x509.validTo ​

Agregado en: v15.6.0

La fecha/hora hasta la cual este certificado es válido.

x509.validToDate ​

Agregado en: v23.0.0

La fecha/hora hasta la cual este certificado es válido, encapsulada en un objeto Date.

x509.verify(publicKey) ​

Agregado en: v15.6.0

Verifica que este certificado fue firmado por la clave pública dada. No realiza ninguna otra comprobación de validación en el certificado.

Métodos y propiedades del módulo node:crypto ​

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

[Historial]

VersiónCambios
v18.0.0Pasar una callback inválida al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v15.8.0Añadido en: v15.8.0

  • candidate <ArrayBuffer> | <SharedArrayBuffer> | <TypedArray> | <Buffer> | <DataView> | <bigint> Un posible número primo codificado como una secuencia de octetos big endian de longitud arbitraria.

  • options <Object>

    • checks <number> El número de iteraciones probabilísticas de primalidad de Miller-Rabin a realizar. Cuando el valor es 0 (cero), se utiliza un número de comprobaciones que produce una tasa de falsos positivos de como máximo 2 para entradas aleatorias. Se debe tener cuidado al seleccionar un número de comprobaciones. Consulte la documentación de OpenSSL para la función BN_is_prime_ex para obtener más detalles sobre las opciones de nchecks. Predeterminado: 0

  • callback <Function>

    • err <Error> Se establece en un objeto <Error> si se produjo un error durante la comprobación.
    • result <boolean> true si el candidato es un número primo con una probabilidad de error menor que 0.25 ** options.checks.

Comprueba la primalidad del candidate.

crypto.checkPrimeSync(candidate[, options]) ​

Agregada en: v15.8.0

  • candidate <ArrayBuffer> | <SharedArrayBuffer> | <TypedArray> | <Buffer> | <DataView> | <bigint> Un posible número primo codificado como una secuencia de octetos big endian de longitud arbitraria.

  • options <Object>

    • checks <number> El número de iteraciones probabilísticas de primalidad de Miller-Rabin a realizar. Cuando el valor es 0 (cero), se utiliza un número de comprobaciones que produce una tasa de falsos positivos de como máximo 2 para la entrada aleatoria. Se debe tener cuidado al seleccionar un número de comprobaciones. Consulte la documentación de OpenSSL para la función BN_is_prime_ex opciones nchecks para obtener más detalles. Predeterminado: 0

  • Devuelve: <boolean> true si el candidato es un número primo con una probabilidad de error inferior a 0.25 ** options.checks.

Comprueba la primalidad del candidate.

crypto.constants ​

Agregada en: v6.3.0

Un objeto que contiene constantes de uso común para operaciones relacionadas con la criptografía y la seguridad. Las constantes específicas actualmente definidas se describen en Constantes criptográficas.

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

[Historial]

VersiónCambios
v17.9.0, v16.17.0La opción authTagLength ahora es opcional cuando se usa el cifrado chacha20-poly1305 y el valor predeterminado es de 16 bytes.
v15.0.0Los argumentos password e iv pueden ser un ArrayBuffer y cada uno está limitado a un máximo de 2 ** 31 - 1 bytes.
v11.6.0El argumento key ahora puede ser un KeyObject.
v11.2.0, v10.17.0Ahora se admite el cifrado chacha20-poly1305 (la variante IETF de ChaCha20-Poly1305).
v10.10.0Ahora se admiten los cifrados en modo OCB.
v10.2.0Ahora se puede usar la opción authTagLength para producir etiquetas de autenticación más cortas en modo GCM y el valor predeterminado es de 16 bytes.
v9.9.0El parámetro iv ahora puede ser null para los cifrados que no necesitan un vector de inicialización.
v0.1.94Añadido en: v0.1.94

Crea y devuelve un objeto Cipher, con el algorithm, la key y el vector de inicialización (iv) dados.

El argumento options controla el comportamiento de la transmisión y es opcional, excepto cuando se usa un cifrado en modo CCM u OCB (por ejemplo, 'aes-128-ccm'). En ese caso, la opción authTagLength es obligatoria y especifica la longitud de la etiqueta de autenticación en bytes, consulte modo CCM. En el modo GCM, la opción authTagLength no es obligatoria, pero se puede usar para establecer la longitud de la etiqueta de autenticación que devolverá getAuthTag() y el valor predeterminado es de 16 bytes. Para chacha20-poly1305, la opción authTagLength tiene un valor predeterminado de 16 bytes.

El algorithm depende de OpenSSL, ejemplos son 'aes192', etc. En las versiones recientes de OpenSSL, openssl list -cipher-algorithms mostrará los algoritmos de cifrado disponibles.

La key es la clave sin procesar utilizada por el algorithm e iv es un vector de inicialización. Ambos argumentos deben ser cadenas codificadas 'utf8', Buffers, TypedArray o DataViews. La key puede ser opcionalmente un KeyObject de tipo secret. Si el cifrado no necesita un vector de inicialización, iv puede ser null.

Cuando pase cadenas para key o iv, considere las advertencias al usar cadenas como entradas para las API criptográficas.

Los vectores de inicialización deben ser impredecibles y únicos; idealmente, serán criptográficamente aleatorios. No tienen que ser secretos: los IV generalmente se agregan a los mensajes de texto cifrado sin cifrar. Puede sonar contradictorio que algo tenga que ser impredecible y único, pero no tiene que ser secreto; recuerde que un atacante no debe poder predecir de antemano cuál será un IV dado.

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

[Historial]

VersiónCambios
v17.9.0, v16.17.0La opción authTagLength ahora es opcional al usar el cifrado chacha20-poly1305 y tiene un valor predeterminado de 16 bytes.
v11.6.0El argumento key ahora puede ser un KeyObject.
v11.2.0, v10.17.0Ahora se admite el cifrado chacha20-poly1305 (la variante IETF de ChaCha20-Poly1305).
v10.10.0Ahora se admiten cifrados en modo OCB.
v10.2.0La opción authTagLength ahora se puede usar para restringir las longitudes de etiquetas de autenticación GCM aceptadas.
v9.9.0El parámetro iv ahora puede ser null para cifrados que no necesitan un vector de inicialización.
v0.1.94Añadido en: v0.1.94

Crea y devuelve un objeto Decipher que usa el algorithm, la key y el vector de inicialización (iv) dados.

El argumento options controla el comportamiento del flujo y es opcional, excepto cuando se usa un cifrado en modo CCM u OCB (por ejemplo, 'aes-128-ccm'). En ese caso, la opción authTagLength es obligatoria y especifica la longitud de la etiqueta de autenticación en bytes, consulte modo CCM. Para AES-GCM y chacha20-poly1305, la opción authTagLength tiene un valor predeterminado de 16 bytes y debe establecerse en un valor diferente si se usa una longitud diferente.

El algorithm depende de OpenSSL, los ejemplos son 'aes192', etc. En las versiones recientes de OpenSSL, openssl list -cipher-algorithms mostrará los algoritmos de cifrado disponibles.

La key es la clave sin procesar utilizada por el algorithm e iv es un vector de inicialización. Ambos argumentos deben ser cadenas codificadas en 'utf8', Buffers, TypedArray o DataViews. La key puede ser opcionalmente un KeyObject de tipo secret. Si el cifrado no necesita un vector de inicialización, iv puede ser null.

Cuando pase cadenas para key o iv, considere las advertencias al usar cadenas como entradas para las API criptográficas.

Los vectores de inicialización deben ser impredecibles y únicos; idealmente, serán criptográficamente aleatorios. No tienen que ser secretos: los IV normalmente se agregan a los mensajes de texto cifrado sin cifrar. Puede sonar contradictorio que algo tenga que ser impredecible y único, pero no tiene que ser secreto; recuerde que un atacante no debe poder predecir de antemano cuál será un IV determinado.

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

[Historial]

VersiónCambios
v8.0.0El argumento prime ahora puede ser cualquier TypedArray o DataView.
v8.0.0El argumento prime ahora puede ser un Uint8Array.
v6.0.0El valor predeterminado para los parámetros de codificación cambió de binary a utf8.
v0.11.12Añadido en: v0.11.12

Crea un objeto de intercambio de claves DiffieHellman utilizando el prime proporcionado y un generator específico opcional.

El argumento generator puede ser un número, una cadena o un Buffer. Si no se especifica generator, se utiliza el valor 2.

Si se especifica primeEncoding, se espera que prime sea una cadena; de lo contrario, se espera un Buffer, TypedArray o DataView.

Si se especifica generatorEncoding, se espera que generator sea una cadena; de lo contrario, se espera un número, Buffer, TypedArray o DataView.

crypto.createDiffieHellman(primeLength[, generator]) ​

Añadido en: v0.5.0

Crea un objeto de intercambio de claves DiffieHellman y genera un número primo de primeLength bits utilizando un generator numérico específico opcional. Si no se especifica generator, se utiliza el valor 2.

crypto.createDiffieHellmanGroup(name) ​

Añadido en: v0.9.3

Un alias para crypto.getDiffieHellman()

crypto.createECDH(curveName) ​

Añadido en: v0.11.14

Crea un objeto de intercambio de claves Diffie-Hellman de curva elíptica (ECDH) utilizando una curva predefinida especificada por la cadena curveName. Utilice crypto.getCurves() para obtener una lista de nombres de curva disponibles. En las versiones recientes de OpenSSL, openssl ecparam -list_curves también mostrará el nombre y la descripción de cada curva elíptica disponible.

crypto.createHash(algorithm[, options]) ​

[Historial]

VersiónCambios
v12.8.0Se agregó la opción outputLength para las funciones hash XOF.
v0.1.92Añadido en: v0.1.92

Crea y devuelve un objeto Hash que se puede utilizar para generar resúmenes hash utilizando el algorithm dado. El argumento options opcional controla el comportamiento del flujo. Para funciones hash XOF como 'shake256', se puede utilizar la opción outputLength para especificar la longitud de salida deseada en bytes.

El algorithm depende de los algoritmos disponibles admitidos por la versión de OpenSSL en la plataforma. Los ejemplos son 'sha256', 'sha512', etc. En las versiones recientes de OpenSSL, openssl list -digest-algorithms mostrará los algoritmos de resumen disponibles.

Ejemplo: generar la suma sha256 de un archivo

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

[Historial]

VersiónCambios
v15.0.0La clave también puede ser un ArrayBuffer o CryptoKey. Se agregó la opción de codificación. La clave no puede contener más de 2 ** 32 - 1 bytes.
v11.6.0El argumento key ahora puede ser un KeyObject.
v0.1.94Agregado en: v0.1.94

Crea y devuelve un objeto Hmac que utiliza el algorithm y la key dados. El argumento options opcional controla el comportamiento del flujo.

El algorithm depende de los algoritmos disponibles soportados por la versión de OpenSSL en la plataforma. Algunos ejemplos son 'sha256', 'sha512', etc. En las versiones recientes de OpenSSL, openssl list -digest-algorithms mostrará los algoritmos de resumen disponibles.

La key es la clave HMAC utilizada para generar el hash HMAC criptográfico. Si es un KeyObject, su tipo debe ser secret. Si es una cadena, considere las advertencias al usar cadenas como entradas para las API criptográficas. Si se obtuvo de una fuente de entropía criptográficamente segura, como crypto.randomBytes() o crypto.generateKey(), su longitud no debe exceder el tamaño de bloque de algorithm (por ejemplo, 512 bits para SHA-256).

Ejemplo: generar el HMAC sha256 de un archivo

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

[Historial]

VersiónCambios
v15.12.0La clave también puede ser un objeto JWK.
v15.0.0La clave también puede ser un ArrayBuffer. Se añadió la opción de codificación. La clave no puede contener más de 2 ** 32 - 1 bytes.
v11.6.0Añadido en: v11.6.0

Crea y devuelve un nuevo objeto clave que contiene una clave privada. Si key es una cadena o Buffer, se asume que el format es 'pem'; de lo contrario, key debe ser un objeto con las propiedades descritas anteriormente.

Si la clave privada está cifrada, debe especificarse una passphrase. La longitud de la frase de contraseña está limitada a 1024 bytes.

crypto.createPublicKey(key) ​

[Historial]

VersiónCambios
v15.12.0La clave también puede ser un objeto JWK.
v15.0.0La clave también puede ser un ArrayBuffer. Se añadió la opción de codificación. La clave no puede contener más de 2 ** 32 - 1 bytes.
v11.13.0El argumento key ahora puede ser un KeyObject con tipo private.
v11.7.0El argumento key ahora puede ser una clave privada.
v11.6.0Añadido en: v11.6.0

Crea y devuelve un nuevo objeto de clave que contiene una clave pública. Si key es una cadena o Buffer, se asume que el format es 'pem'; si key es un KeyObject con tipo 'private', la clave pública se deriva de la clave privada dada; de lo contrario, key debe ser un objeto con las propiedades descritas anteriormente.

Si el formato es 'pem', la 'key' también puede ser un certificado X.509.

Dado que las claves públicas se pueden derivar de claves privadas, se puede pasar una clave privada en lugar de una clave pública. En ese caso, esta función se comporta como si se hubiera llamado a crypto.createPrivateKey(), excepto que el tipo del KeyObject devuelto será 'public' y que la clave privada no se puede extraer del KeyObject devuelto. Del mismo modo, si se proporciona un KeyObject con tipo 'private', se devolverá un nuevo KeyObject con tipo 'public' y será imposible extraer la clave privada del objeto devuelto.

crypto.createSecretKey(key[, encoding]) ​

[Historial]

VersiónCambios
v18.8.0, v16.18.0La clave ahora puede tener longitud cero.
v15.0.0La clave también puede ser un ArrayBuffer o una cadena. Se añadió el argumento de codificación. La clave no puede contener más de 2 ** 32 - 1 bytes.
v11.6.0Añadido en: v11.6.0

Crea y devuelve un nuevo objeto de clave que contiene una clave secreta para el cifrado simétrico o Hmac.

crypto.createSign(algorithm[, options]) ​

Añadido en: v0.1.92

Crea y devuelve un objeto Sign que utiliza el algorithm dado. Utilice crypto.getHashes() para obtener los nombres de los algoritmos de resumen disponibles. El argumento options opcional controla el comportamiento de stream.Writable.

En algunos casos, se puede crear una instancia de Sign utilizando el nombre de un algoritmo de firma, como 'RSA-SHA256', en lugar de un algoritmo de resumen. Esto utilizará el algoritmo de resumen correspondiente. Esto no funciona para todos los algoritmos de firma, como 'ecdsa-with-SHA256', por lo que es mejor utilizar siempre nombres de algoritmos de resumen.

crypto.createVerify(algorithm[, options]) ​

Agregado en: v0.1.92

Crea y devuelve un objeto Verify que utiliza el algoritmo dado. Utilice crypto.getHashes() para obtener una matriz de nombres de los algoritmos de firma disponibles. El argumento opcional options controla el comportamiento de stream.Writable.

En algunos casos, se puede crear una instancia de Verify utilizando el nombre de un algoritmo de firma, como 'RSA-SHA256', en lugar de un algoritmo de resumen. Esto utilizará el algoritmo de resumen correspondiente. Esto no funciona para todos los algoritmos de firma, como 'ecdsa-with-SHA256', por lo que es mejor utilizar siempre los nombres de los algoritmos de resumen.

crypto.diffieHellman(options) ​

Agregado en: v13.9.0, v12.17.0

Calcula el secreto de Diffie-Hellman basado en una privateKey y una publicKey. Ambas claves deben tener el mismo asymmetricKeyType, que debe ser uno de 'dh' (para Diffie-Hellman), 'ec', 'x448' o 'x25519' (para ECDH).

crypto.fips ​

Agregado en: v6.0.0

Obsoleto desde: v10.0.0

[Estable: 0 - Obsoleto]

Estable: 0 Estabilidad: 0 - Obsoleto

Propiedad para comprobar y controlar si se está utilizando actualmente un proveedor criptográfico compatible con FIPS. Establecer en true requiere una compilación FIPS de Node.js.

Esta propiedad está obsoleta. Por favor, use crypto.setFips() y crypto.getFips() en su lugar.

crypto.generateKey(type, options, callback) ​

[Historial]

VersiónCambios
v18.0.0Pasar una devolución de llamada no válida al argumento callback ahora arroja ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v15.0.0Agregado en: v15.0.0

  • type: <string> El uso previsto de la clave secreta generada. Los valores aceptados actualmente son 'hmac' y 'aes'.

  • options: <Object>

    • length: <number> La longitud en bits de la clave a generar. Esto debe ser un valor mayor que 0.
    • Si type es 'hmac', el mínimo es 8 y la longitud máxima es 2-1. Si el valor no es un múltiplo de 8, la clave generada se truncará a Math.floor(length / 8).
    • Si type es 'aes', la longitud debe ser una de 128, 192 o 256.

  • callback: <Function>

Genera asincrónicamente una nueva clave secreta aleatoria de la length dada. El type determinará qué validaciones se realizarán en la 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
});

El tamaño de una clave HMAC generada no debe exceder el tamaño de bloque de la función hash subyacente. Consulte crypto.createHmac() para obtener más información.

crypto.generateKeyPair(type, options, callback) ​

[Historial]

VersiónCambios
v18.0.0Pasar una callback inválida al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v16.10.0Agrega la capacidad de definir parámetros de secuencia RSASSA-PSS-params para pares de claves RSA-PSS.
v13.9.0, v12.17.0Agrega soporte para Diffie-Hellman.
v12.0.0Agrega soporte para pares de claves RSA-PSS.
v12.0.0Agrega la capacidad de generar pares de claves X25519 y X448.
v12.0.0Agrega la capacidad de generar pares de claves Ed25519 y Ed448.
v11.6.0Las funciones generateKeyPair y generateKeyPairSync ahora producen objetos de clave si no se especificó ninguna codificación.
v10.12.0Agregado en: v10.12.0

Genera un nuevo par de claves asimétricas del type dado. Actualmente se admiten RSA, RSA-PSS, DSA, EC, Ed25519, Ed448, X25519, X448 y DH.

Si se especificó un publicKeyEncoding o privateKeyEncoding, esta función se comporta como si se hubiera llamado a keyObject.export() en su resultado. De lo contrario, la parte respectiva de la clave se devuelve como un KeyObject.

Se recomienda codificar las claves públicas como 'spki' y las claves privadas como 'pkcs8' con cifrado para el almacenamiento a largo plazo:

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) => {
  // Handle errors and use the generated key pair.
});

Al finalizar, se llamará a callback con err establecido en undefined y publicKey / privateKey representando el par de claves generado.

Si este método se invoca como su versión util.promisify()ed, devuelve una Promise para un Object con propiedades publicKey y privateKey.

crypto.generateKeyPairSync(type, options) ​

[Historial]

VersiónCambios
v16.10.0Se agregó la capacidad de definir parámetros de secuencia RSASSA-PSS-params para pares de claves RSA-PSS.
v13.9.0, v12.17.0Se agregó soporte para Diffie-Hellman.
v12.0.0Se agregó soporte para pares de claves RSA-PSS.
v12.0.0Se agregó la capacidad de generar pares de claves X25519 y X448.
v12.0.0Se agregó la capacidad de generar pares de claves Ed25519 y Ed448.
v11.6.0Las funciones generateKeyPair y generateKeyPairSync ahora producen objetos clave si no se especificó ninguna codificación.
v10.12.0Se agregó en: v10.12.0

Genera un nuevo par de claves asimétricas del type dado. Actualmente se admiten RSA, RSA-PSS, DSA, EC, Ed25519, Ed448, X25519, X448 y DH.

Si se especificó una publicKeyEncoding o privateKeyEncoding, esta función se comporta como si se hubiera llamado a keyObject.export() en su resultado. De lo contrario, la parte respectiva de la clave se devuelve como un KeyObject.

Al codificar claves públicas, se recomienda utilizar 'spki'. Al codificar claves privadas, se recomienda utilizar 'pkcs8' con una contraseña segura y mantener la confidencialidad de la contraseña.

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

El valor de retorno { publicKey, privateKey } representa el par de claves generado. Cuando se seleccionó la codificación PEM, la clave respectiva será una cadena, de lo contrario, será un búfer que contiene los datos codificados como DER.

crypto.generateKeySync(type, options) ​

Agregado en: v15.0.0

  • type: <string> El uso previsto de la clave secreta generada. Los valores aceptados actualmente son 'hmac' y 'aes'.

  • options: <Object>

    • length: <number> La longitud en bits de la clave a generar.
    • Si type es 'hmac', el mínimo es 8 y la longitud máxima es 2-1. Si el valor no es múltiplo de 8, la clave generada se truncará a Math.floor(length / 8).
    • Si type es 'aes', la longitud debe ser una de 128, 192 o 256.

  • Devuelve: <KeyObject>

Genera sincrónicamente una nueva clave secreta aleatoria de la length dada. El type determinará qué validaciones se realizarán en la 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

El tamaño de una clave HMAC generada no debe exceder el tamaño de bloque de la función hash subyacente. Consulte crypto.createHmac() para obtener más información.

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

[Historial]

VersiónCambios
v18.0.0Pasar una callback inválida al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v15.8.0Agregado en: v15.8.0

Genera un primo pseudoaleatorio de size bits.

Si options.safe es true, el primo será un primo seguro, es decir, (prime - 1) / 2 también será un primo.

Los parámetros options.add y options.rem se pueden usar para imponer requisitos adicionales, por ejemplo, para Diffie-Hellman:

  • Si options.add y options.rem están ambos establecidos, el primo satisfará la condición de que prime % add = rem.
  • Si solo se establece options.add y options.safe no es true, el primo satisfará la condición de que prime % add = 1.
  • Si solo se establece options.add y options.safe se establece en true, el primo satisfará en cambio la condición de que prime % add = 3. Esto es necesario porque prime % add = 1 para options.add \> 2 contradiría la condición impuesta por options.safe.
  • options.rem se ignora si no se proporciona options.add.

Tanto options.add como options.rem deben codificarse como secuencias big-endian si se dan como ArrayBuffer, SharedArrayBuffer, TypedArray, Buffer o DataView.

De forma predeterminada, el primo se codifica como una secuencia big-endian de octetos en un <ArrayBuffer>. Si la opción bigint es true, entonces se proporciona un <bigint>.

crypto.generatePrimeSync(size[, options]) ​

Agregado en: v15.8.0

Genera un número primo pseudoaleatorio de size bits.

Si options.safe es true, el número primo será un número primo seguro; es decir, (prime - 1) / 2 también será un número primo.

Los parámetros options.add y options.rem se pueden utilizar para aplicar requisitos adicionales, por ejemplo, para Diffie-Hellman:

  • Si options.add y options.rem están ambos establecidos, el número primo satisfará la condición de que prime % add = rem.
  • Si solo se establece options.add y options.safe no es true, el número primo satisfará la condición de que prime % add = 1.
  • Si solo se establece options.add y options.safe se establece en true, el número primo satisfará en su lugar la condición de que prime % add = 3. Esto es necesario porque prime % add = 1 para options.add \> 2 contradeciría la condición impuesta por options.safe.
  • options.rem se ignora si no se proporciona options.add.

Tanto options.add como options.rem deben codificarse como secuencias big-endian si se proporcionan como ArrayBuffer, SharedArrayBuffer, TypedArray, Buffer o DataView.

De forma predeterminada, el número primo se codifica como una secuencia big-endian de octetos en un <ArrayBuffer>. Si la opción bigint es true, entonces se proporciona un <bigint>.

crypto.getCipherInfo(nameOrNid[, options]) ​

Agregado en: v15.0.0

  • nameOrNid: <string> | <number> El nombre o nid del cifrado a consultar.

  • options: <Object>

    • keyLength: <number> Una longitud de clave de prueba.
    • ivLength: <number> Una longitud de IV de prueba.

  • Devuelve: <Object>

    • name <string> El nombre del cifrado
    • nid <number> El nid del cifrado
    • blockSize <number> El tamaño del bloque del cifrado en bytes. Esta propiedad se omite cuando mode es 'stream'.
    • ivLength <number> La longitud del vector de inicialización esperada o predeterminada en bytes. Esta propiedad se omite si el cifrado no utiliza un vector de inicialización.
    • keyLength <number> La longitud de clave esperada o predeterminada en bytes.
    • mode <string> El modo de cifrado. Uno de 'cbc', 'ccm', 'cfb', 'ctr', 'ecb', 'gcm', 'ocb', 'ofb', 'stream', 'wrap', 'xts'.

Devuelve información sobre un cifrado dado.

Algunos cifrados aceptan claves y vectores de inicialización de longitud variable. Por defecto, el método crypto.getCipherInfo() devolverá los valores predeterminados para estos cifrados. Para probar si una longitud de clave o una longitud de IV dadas son aceptables para un cifrado dado, utilice las opciones keyLength e ivLength. Si los valores dados no son aceptables, se devolverá undefined.

crypto.getCiphers() ​

Agregado en: v0.9.3

  • Devuelve: <string[]> Un array con los nombres de los algoritmos de cifrado soportados.
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() ​

Agregado en: v2.3.0

  • Devuelve: <string[]> Un array con los nombres de las curvas elípticas soportadas.
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) ​

Agregado en: v0.7.5

Crea un objeto de intercambio de claves DiffieHellmanGroup predefinido. Los grupos soportados se listan en la documentación para DiffieHellmanGroup.

El objeto devuelto imita la interfaz de los objetos creados por crypto.createDiffieHellman(), pero no permitirá cambiar las claves (con diffieHellman.setPublicKey(), por ejemplo). La ventaja de usar este método es que las partes no tienen que generar ni intercambiar un módulo de grupo de antemano, ahorrando tiempo de procesador y comunicación.

Ejemplo (obtener un secreto compartido):

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 y bobSecret deberían ser iguales */
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 y bobSecret deberían ser iguales */
console.log(aliceSecret === bobSecret);

crypto.getFips() ​

Agregado en: v10.0.0

  • Devuelve: <number> 1 si y solo si un proveedor de criptografía compatible con FIPS está actualmente en uso, 0 en caso contrario. Una futura versión semver-major puede cambiar el tipo de retorno de esta API a un <boolean>.

crypto.getHashes() ​

Agregado en: v0.9.3

  • Devuelve: <string[]> Un array de los nombres de los algoritmos hash soportados, como 'RSA-SHA256'. Los algoritmos hash también se denominan algoritmos "digest".
js
const {
  getHashes,
} = await import('node:crypto');

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

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

crypto.getRandomValues(typedArray) ​

Agregado en: v17.4.0

Un alias conveniente para crypto.webcrypto.getRandomValues(). Esta implementación no es compatible con la especificación Web Crypto, para escribir código compatible con la web utilice crypto.webcrypto.getRandomValues() en su lugar.

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

Agregado en: v21.7.0, v20.12.0

[Estable: 1 - Experimental]

Estable: 1 Estabilidad: 1.2 - Candidato a lanzamiento

  • algorithm <string> | <undefined>
  • data <string> | <Buffer> | <TypedArray> | <DataView> Cuando data es una cadena, se codificará como UTF-8 antes de ser hasheada. Si se desea una codificación de entrada diferente para una entrada de cadena, el usuario podría codificar la cadena en un TypedArray usando TextEncoder o Buffer.from() y pasar el TypedArray codificado a esta API en su lugar.
  • outputEncoding <string> | <undefined> Codificación usada para codificar el resumen devuelto. Predeterminado: 'hex'.
  • Devuelve: <string> | <Buffer>

Una utilidad para crear resúmenes hash únicos de datos. Puede ser más rápido que el crypto.createHash() basado en objetos al hashear una cantidad menor de datos (<= 5 MB) que están disponibles de inmediato. Si los datos pueden ser grandes o si se transmiten, todavía se recomienda usar crypto.createHash() en su lugar.

El algorithm depende de los algoritmos disponibles compatibles con la versión de OpenSSL en la plataforma. Los ejemplos son 'sha256', 'sha512', etc. En las versiones recientes de OpenSSL, openssl list -digest-algorithms mostrará los algoritmos de resumen disponibles.

Ejemplo:

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

// Hasheando una cadena y devolviendo el resultado como una cadena codificada en hexadecimal.
const string = 'Node.js';
// 10b3493287f831e81a438811a1ffba01f8cec4b7
console.log(crypto.hash('sha1', string));

// Codifica una cadena codificada en base64 en un Buffer, la hashea y devuelve
// el resultado como un búfer.
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';

// Hasheando una cadena y devolviendo el resultado como una cadena codificada en hexadecimal.
const string = 'Node.js';
// 10b3493287f831e81a438811a1ffba01f8cec4b7
console.log(crypto.hash('sha1', string));

// Codifica una cadena codificada en base64 en un Buffer, la hashea y devuelve
// el resultado como un búfer.
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) ​

[Historial]

VersiónCambios
v18.0.0Pasar una callback inválida al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v18.8.0, v16.18.0El material de clave de entrada ahora puede tener longitud cero.
v15.0.0Añadido en: v15.0.0

HKDF es una función de derivación de clave simple definida en RFC 5869. Los ikm, salt e info dados se utilizan con el digest para derivar una clave de keylen bytes.

La función callback suministrada se llama con dos argumentos: err y derivedKey. Si ocurre un error al derivar la clave, se establecerá err; de lo contrario, err será null. La derivedKey generada con éxito se pasará al callback como un <ArrayBuffer>. Se lanzará un error si alguno de los argumentos de entrada especifica valores o tipos no vá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) ​

[Historial]

VersiónCambios
v18.8.0, v16.18.0El material de clave de entrada ahora puede tener longitud cero.
v15.0.0Añadido en: v15.0.0

Proporciona una función de derivación de claves HKDF síncrona como se define en RFC 5869. El ikm, salt e info dados se utilizan con el digest para derivar una clave de keylen bytes.

La derivedKey generada correctamente se devolverá como un <ArrayBuffer>.

Se lanzará un error si alguno de los argumentos de entrada especifica valores o tipos no válidos, o si no se puede generar la clave derivada.

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

[Historial]

VersiónCambios
v18.0.0Pasar un callback inválido al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v15.0.0Los argumentos password y salt también pueden ser instancias de ArrayBuffer.
v14.0.0El parámetro iterations ahora está restringido a valores positivos. Las versiones anteriores trataban otros valores como uno.
v8.0.0El parámetro digest ahora siempre es requerido.
v6.0.0Llamar a esta función sin pasar el parámetro digest ahora está obsoleto y emitirá una advertencia.
v6.0.0La codificación predeterminada para password si es una cadena cambió de binary a utf8.
v0.5.5Añadido en: v0.5.5

Proporciona una implementación asíncrona de la Función de Derivación de Claves Basada en Contraseña 2 (PBKDF2). Un algoritmo de resumen HMAC seleccionado especificado por digest se aplica para derivar una clave de la longitud de bytes solicitada (keylen) de la password, salt e iterations.

La función callback suministrada se llama con dos argumentos: err y derivedKey. Si ocurre un error al derivar la clave, se establecerá err; de lo contrario, err será null. Por defecto, la derivedKey generada correctamente se pasará al callback como un Buffer. Se lanzará un error si alguno de los argumentos de entrada especifica valores o tipos no válidos.

El argumento iterations debe ser un número establecido lo más alto posible. Cuanto mayor sea el número de iteraciones, más segura será la clave derivada, pero tardará más tiempo en completarse.

El salt debe ser lo más único posible. Se recomienda que un salt sea aleatorio y de al menos 16 bytes de longitud. Consulte NIST SP 800-132 para obtener más detalles.

Cuando se pasan cadenas para password o salt, por favor considere las advertencias al usar cadenas 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'
});

Se puede recuperar una matriz de funciones hash admitidas utilizando crypto.getHashes().

Esta API utiliza el threadpool de libuv, lo que puede tener implicaciones de rendimiento sorprendentes y negativas para algunas aplicaciones; consulte la documentación de UV_THREADPOOL_SIZE para obtener más información.

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

[Historial]

VersiónCambios
v14.0.0El parámetro iterations ahora está restringido a valores positivos. Las versiones anteriores trataban otros valores como uno.
v6.0.0Llamar a esta función sin pasar el parámetro digest ahora está en desuso y emitirá una advertencia.
v6.0.0La codificación predeterminada para password si es una cadena cambió de binary a utf8.
v0.9.3Agregado en: v0.9.3

Proporciona una implementación sincrónica de la función de derivación de claves basada en contraseñas 2 (PBKDF2). Un algoritmo de resumen HMAC seleccionado especificado por digest se aplica para derivar una clave de la longitud de bytes solicitada (keylen) de la password, salt e iterations.

Si ocurre un error, se lanzará un Error, de lo contrario, la clave derivada se devolverá como un Buffer.

El argumento iterations debe ser un número establecido lo más alto posible. Cuanto mayor sea el número de iteraciones, más segura será la clave derivada, pero tardará más tiempo en completarse.

El salt debe ser lo más único posible. Se recomienda que un salt sea aleatorio y tenga al menos 16 bytes de longitud. Consulte NIST SP 800-132 para obtener más detalles.

Cuando pase cadenas para password o salt, considere las advertencias al usar cadenas como entradas a las API 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'

Se puede recuperar una matriz de funciones de resumen admitidas mediante crypto.getHashes().

crypto.privateDecrypt(privateKey, buffer) ​

[Historial]

VersiónCambios
v21.6.2, v20.11.1, v18.19.1El relleno RSA_PKCS1_PADDING se deshabilitó a menos que la compilación de OpenSSL admita el rechazo implícito.
v15.0.0Se agregaron string, ArrayBuffer y CryptoKey como tipos de clave permitidos. El oaepLabel puede ser un ArrayBuffer. El buffer puede ser un string o ArrayBuffer. Todos los tipos que aceptan buffers están limitados a un máximo de 2 ** 31 - 1 bytes.
v12.11.0Se agregó la opción oaepLabel.
v12.9.0Se agregó la opción oaepHash.
v11.6.0Esta función ahora admite objetos de clave.
v0.11.14Agregado en: v0.11.14

Descifra buffer con privateKey. buffer se cifró previamente utilizando la clave pública correspondiente, por ejemplo, utilizando crypto.publicEncrypt().

Si privateKey no es un KeyObject, esta función se comporta como si privateKey se hubiera pasado a crypto.createPrivateKey(). Si es un objeto, se puede pasar la propiedad padding. De lo contrario, esta función utiliza RSA_PKCS1_OAEP_PADDING.

El uso de crypto.constants.RSA_PKCS1_PADDING en crypto.privateDecrypt() requiere que OpenSSL admita el rechazo implícito (rsa_pkcs1_implicit_rejection). Si la versión de OpenSSL utilizada por Node.js no admite esta función, el intento de utilizar RSA_PKCS1_PADDING fallará.

crypto.privateEncrypt(privateKey, buffer) ​

[Historial]

VersiónCambios
v15.0.0Se agregaron string, ArrayBuffer y CryptoKey como tipos de clave permitidos. La frase de contraseña puede ser un ArrayBuffer. El búfer puede ser un string o ArrayBuffer. Todos los tipos que aceptan búferes están limitados a un máximo de 2 ** 31 - 1 bytes.
v11.6.0Esta función ahora soporta objetos clave.
v1.1.0Agregado en: v1.1.0

Encripta buffer con privateKey. Los datos devueltos pueden ser desencriptados usando la clave pública correspondiente, por ejemplo usando crypto.publicDecrypt().

Si privateKey no es un KeyObject, esta función se comporta como si privateKey se hubiera pasado a crypto.createPrivateKey(). Si es un objeto, se puede pasar la propiedad padding. De lo contrario, esta función usa RSA_PKCS1_PADDING.

crypto.publicDecrypt(key, buffer) ​

[Historial]

VersiónCambios
v15.0.0Se agregaron string, ArrayBuffer y CryptoKey como tipos de clave permitidos. La contraseña puede ser un ArrayBuffer. El buffer puede ser un string o ArrayBuffer. Todos los tipos que aceptan buffers están limitados a un máximo de 2 ** 31 - 1 bytes.
v11.6.0Esta función ahora admite objetos de clave.
v1.1.0Agregado en: v1.1.0

Descifra el buffer con key. El buffer se cifró previamente utilizando la clave privada correspondiente, por ejemplo, utilizando crypto.privateEncrypt().

Si key no es un KeyObject, esta función se comporta como si key se hubiera pasado a crypto.createPublicKey(). Si es un objeto, se puede pasar la propiedad padding. De lo contrario, esta función utiliza RSA_PKCS1_PADDING.

Dado que las claves públicas RSA se pueden derivar de las claves privadas, se puede pasar una clave privada en lugar de una clave pública.

crypto.publicEncrypt(key, buffer) ​

[Historial]

VersiónCambios
v15.0.0Se agregaron string, ArrayBuffer y CryptoKey como tipos de clave permitidos. oaepLabel y passphrase pueden ser ArrayBuffers. El buffer puede ser un string o ArrayBuffer. Todos los tipos que aceptan buffers están limitados a un máximo de 2 ** 31 - 1 bytes.
v12.11.0Se agregó la opción oaepLabel.
v12.9.0Se agregó la opción oaepHash.
v11.6.0Esta función ahora soporta objetos key.
v0.11.14Agregado en: v0.11.14

Encripta el contenido de buffer con key y devuelve un nuevo Buffer con el contenido encriptado. Los datos devueltos se pueden desencriptar utilizando la clave privada correspondiente, por ejemplo utilizando crypto.privateDecrypt().

Si key no es un KeyObject, esta función se comporta como si key hubiera sido pasado a crypto.createPublicKey(). Si es un objeto, se puede pasar la propiedad padding. De lo contrario, esta función utiliza RSA_PKCS1_OAEP_PADDING.

Dado que las claves públicas RSA se pueden derivar de las claves privadas, se puede pasar una clave privada en lugar de una clave pública.

crypto.randomBytes(size[, callback]) ​

[Historial]

VersiónCambios
v18.0.0Pasar un callback inválido al argumento callback ahora arroja ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v9.0.0Pasar null como el argumento callback ahora arroja ERR_INVALID_CALLBACK.
v0.5.8Agregado en: v0.5.8

Genera datos pseudorandom seguros criptográficamente. El argumento size es un número que indica la cantidad de bytes a generar.

Si se proporciona una función callback, los bytes se generan de forma asíncrona y la función callback se invoca con dos argumentos: err y buf. Si ocurre un error, err será un objeto Error; de lo contrario, será null. El argumento buf es un Buffer que contiene los bytes generados.

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

randomBytes(256, (err, buf) => {
  if (err) throw err;
  console.log(`${buf.length} bytes de datos aleatorios: ${buf.toString('hex')}`);
});
js
// Asíncrono
const {
  randomBytes,
} = require('node:crypto');

randomBytes(256, (err, buf) => {
  if (err) throw err;
  console.log(`${buf.length} bytes de datos aleatorios: ${buf.toString('hex')}`);
});

Si no se proporciona la función callback, los bytes aleatorios se generan de forma síncrona y se devuelven como un Buffer. Se lanzará un error si hay un problema al generar los bytes.

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

const buf = randomBytes(256);
console.log(
  `${buf.length} bytes de datos aleatorios: ${buf.toString('hex')}`);
js
// Síncrono
const {
  randomBytes,
} = require('node:crypto');

const buf = randomBytes(256);
console.log(
  `${buf.length} bytes de datos aleatorios: ${buf.toString('hex')}`);

El método crypto.randomBytes() no se completará hasta que haya suficiente entropía disponible. Normalmente, esto no debería tardar más de unos pocos milisegundos. La única vez que la generación de bytes aleatorios puede bloquearse durante un período de tiempo más prolongado es inmediatamente después del arranque, cuando todo el sistema todavía tiene poca entropía.

Esta API utiliza el threadpool de libuv, lo que puede tener implicaciones de rendimiento sorprendentes y negativas para algunas aplicaciones; consulte la documentación de UV_THREADPOOL_SIZE para obtener más información.

La versión asíncrona de crypto.randomBytes() se lleva a cabo en una única solicitud de threadpool. Para minimizar la variación en la duración de las tareas del threadpool, particione las solicitudes grandes de randomBytes cuando lo haga como parte del cumplimiento de una solicitud del cliente.

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

[Historial]

VersiónCambios
v18.0.0Pasar una callback no válida al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v9.0.0El argumento buffer puede ser cualquier TypedArray o DataView.
v7.10.0, v6.13.0Añadido en: v7.10.0, v6.13.0

Esta función es similar a crypto.randomBytes() pero requiere que el primer argumento sea un Buffer que será rellenado. También requiere que se pase un callback.

Si no se proporciona la función callback, se lanzará un error.

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

// Lo anterior es equivalente a lo siguiente:
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'));
});

// Lo anterior es equivalente a lo siguiente:
randomFill(buf, 5, 5, (err, buf) => {
  if (err) throw err;
  console.log(buf.toString('hex'));
});

Cualquier instancia de ArrayBuffer, TypedArray o DataView puede ser pasada como buffer.

Aunque esto incluye instancias de Float32Array y Float64Array, esta función no debe ser utilizada para generar números de punto flotante aleatorios. El resultado puede contener +Infinity, -Infinity y NaN, e incluso si el array contiene sólo números finitos, no se extraen de una distribución aleatoria uniforme y no tienen límites inferiores o 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 utiliza el threadpool de libuv, lo cual puede tener implicaciones de rendimiento sorprendentes y negativas para algunas aplicaciones; consulte la documentación de UV_THREADPOOL_SIZE para más información.

La versión asíncrona de crypto.randomFill() se lleva a cabo en una única solicitud de threadpool. Para minimizar la variación de la longitud de la tarea del threadpool, particione las solicitudes grandes de randomFill cuando lo haga como parte del cumplimiento de una solicitud de cliente.

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

[Historial]

VersiónCambios
v9.0.0El argumento buffer puede ser cualquier TypedArray o DataView.
v7.10.0, v6.13.0Añadido en: v7.10.0, v6.13.0

Versión 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'));

// The above is equivalent to the following:
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'));

// The above is equivalent to the following:
randomFillSync(buf, 5, 5);
console.log(buf.toString('hex'));

Cualquier instancia de ArrayBuffer, TypedArray o DataView puede ser pasada 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]) ​

[Historial]

VersiónCambios
v18.0.0Pasar una devolución de llamada inválida al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v14.10.0, v12.19.0Añadido en: v14.10.0, v12.19.0
  • min <integer> Inicio del rango aleatorio (inclusivo). Predeterminado: 0.
  • max <integer> Fin del rango aleatorio (exclusivo).
  • callback <Function> function(err, n) {}.

Devuelve un entero aleatorio n tal que min \<= n \< max. Esta implementación evita el sesgo de módulo.

El rango (max - min) debe ser menor que 2. min y max deben ser enteros seguros.

Si no se proporciona la función callback, el entero aleatorio se genera de forma síncrona.

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

randomInt(3, (err, n) => {
  if (err) throw err;
  console.log(`Número aleatorio elegido de (0, 1, 2): ${n}`);
});
js
// Asíncrono
const {
  randomInt,
} = require('node:crypto');

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

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

const n = randomInt(3);
console.log(`Número aleatorio elegido de (0, 1, 2): ${n}`);
js
// Con el argumento `min`
const {
  randomInt,
} = await import('node:crypto');

const n = randomInt(1, 7);
console.log(`El dado rodó: ${n}`);
js
// Con el argumento `min`
const {
  randomInt,
} = require('node:crypto');

const n = randomInt(1, 7);
console.log(`El dado rodó: ${n}`);

crypto.randomUUID([options]) ​

Añadido en: v15.6.0, v14.17.0

  • options <Objeto>

    • disableEntropyCache <booleano> Por defecto, para mejorar el rendimiento, Node.js genera y almacena en caché suficientes datos aleatorios para generar hasta 128 UUID aleatorios. Para generar un UUID sin usar la caché, establece disableEntropyCache en true. Predeterminado: false.

  • Devuelve: <string>

Genera un UUID aleatorio RFC 4122 versión 4. El UUID se genera utilizando un generador de números pseudoaleatorios criptográfico.

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

[Historial]

VersiónCambios
v18.0.0Pasar una callback no válida al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v15.0.0Los argumentos password y salt también pueden ser instancias de ArrayBuffer.
v12.8.0, v10.17.0El valor maxmem ahora puede ser cualquier entero seguro.
v10.9.0Se han añadido los nombres de las opciones cost, blockSize y parallelization.
v10.5.0Añadido en: v10.5.0

Proporciona una implementación scrypt asíncrona. Scrypt es una función de derivación de claves basada en contraseñas que está diseñada para ser costosa desde el punto de vista computacional y de la memoria con el fin de que los ataques de fuerza bruta no sean gratificantes.

El salt debe ser lo más único posible. Se recomienda que un salt sea aleatorio y tenga al menos 16 bytes de longitud. Consulta NIST SP 800-132 para obtener más detalles.

Al pasar cadenas para password o salt, considera las advertencias al usar cadenas como entradas a las API criptográficas.

La función callback se llama con dos argumentos: err y derivedKey. err es un objeto de excepción cuando falla la derivación de la clave, de lo contrario err es null. derivedKey se pasa a la callback como un Buffer.

Se lanza una excepción cuando cualquiera de los argumentos de entrada especifica valores o tipos no válidos.

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

// Usando los valores predeterminados de fábrica.
scrypt('password', 'salt', 64, (err, derivedKey) => {
  if (err) throw err;
  console.log(derivedKey.toString('hex'));  // '3745e48...08d59ae'
});
// Usando un parámetro N personalizado. Debe ser una potencia de dos.
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 los valores predeterminados de fábrica.
scrypt('password', 'salt', 64, (err, derivedKey) => {
  if (err) throw err;
  console.log(derivedKey.toString('hex'));  // '3745e48...08d59ae'
});
// Usando un parámetro N personalizado. Debe ser una potencia de dos.
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]) ​

[Historial]

VersiónCambios
v12.8.0, v10.17.0El valor de maxmem ahora puede ser cualquier entero seguro.
v10.9.0Se han añadido los nombres de las opciones cost, blockSize y parallelization.
v10.5.0Añadido en: v10.5.0

  • password <string> | <Buffer> | <TypedArray> | <DataView>

  • salt <string> | <Buffer> | <TypedArray> | <DataView>

  • keylen <number>

  • options <Object>

    • cost <number> Parámetro de coste de CPU/memoria. Debe ser una potencia de dos mayor que uno. Predeterminado: 16384.
    • blockSize <number> Parámetro de tamaño de bloque. Predeterminado: 8.
    • parallelization <number> Parámetro de paralelización. Predeterminado: 1.
    • N <number> Alias para cost. Sólo se puede especificar uno de los dos.
    • r <number> Alias para blockSize. Sólo se puede especificar uno de los dos.
    • p <number> Alias para parallelization. Sólo se puede especificar uno de los dos.
    • maxmem <number> Límite superior de memoria. Es un error cuando (aproximadamente) 128 * N * r \> maxmem. Predeterminado: 32 * 1024 * 1024.

  • Devuelve: <Buffer>

Proporciona una implementación síncrona de scrypt. Scrypt es una función de derivación de claves basada en contraseñas que está diseñada para ser costosa computacionalmente y en cuanto a memoria con el fin de hacer que los ataques de fuerza bruta no sean gratificantes.

El salt debe ser lo más único posible. Se recomienda que un salt sea aleatorio y tenga al menos 16 bytes de longitud. Consulte NIST SP 800-132 para obtener más detalles.

Cuando se pasan cadenas para password o salt, por favor considere precauciones al usar cadenas como entradas para APIs criptográficas.

Se lanza una excepción cuando la derivación de claves falla, de lo contrario la clave derivada se devuelve como un Buffer.

Se lanza una excepción cuando cualquiera de los argumentos de entrada especifica valores o tipos no válidos.

js
const {
  scryptSync,
} = await import('node:crypto');
// Using the factory defaults.

const key1 = scryptSync('password', 'salt', 64);
console.log(key1.toString('hex'));  // '3745e48...08d59ae'
// Using a custom N parameter. Must be a power of two.
const key2 = scryptSync('password', 'salt', 64, { N: 1024 });
console.log(key2.toString('hex'));  // '3745e48...aa39b34'
js
const {
  scryptSync,
} = require('node:crypto');
// Using the factory defaults.

const key1 = scryptSync('password', 'salt', 64);
console.log(key1.toString('hex'));  // '3745e48...08d59ae'
// Using a custom N parameter. Must be a power of two.
const key2 = scryptSync('password', 'salt', 64, { N: 1024 });
console.log(key2.toString('hex'));  // '3745e48...aa39b34'

crypto.secureHeapUsed() ​

Agregada en: v15.6.0

  • Devuelve: <Objeto>
    • total <number> El tamaño total del heap seguro asignado, tal como se especifica mediante el indicador de línea de comandos --secure-heap=n.
    • min <number> La asignación mínima del heap seguro, tal como se especifica mediante el indicador de línea de comandos --secure-heap-min.
    • used <number> El número total de bytes actualmente asignados desde el heap seguro.
    • utilization <number> La relación calculada de used a total bytes asignados.

crypto.setEngine(engine[, flags]) ​

[Historial]

VersiónCambios
v22.4.0, v20.16.0El soporte del motor personalizado en OpenSSL 3 está obsoleto.
v0.11.11Agregada en: v0.11.11

Cargue y establezca el engine para algunas o todas las funciones de OpenSSL (seleccionadas por flags). El soporte para motores personalizados en OpenSSL está obsoleto desde OpenSSL 3.

engine podría ser un id o una ruta a la biblioteca compartida del motor.

El argumento opcional flags usa ENGINE_METHOD_ALL de forma predeterminada. Los flags son un campo de bits que toma uno o una mezcla de los siguientes flags (definidos en 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) ​

Agregado en: v10.0.0

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

Habilita el proveedor de cifrado compatible con FIPS en una compilación de Node.js habilitada para FIPS. Lanza un error si el modo FIPS no está disponible.

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

[Historial]

VersiónCambios
v18.0.0Pasar una función de retrollamada no válida al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v15.12.0Se agregó el argumento opcional de retrollamada.
v13.2.0, v12.16.0Esta función ahora soporta firmas DSA y ECDSA IEEE-P1363.
v12.0.0Agregado en: v12.0.0

Calcula y devuelve la firma para data utilizando la clave privada y el algoritmo dados. Si algorithm es null o undefined, entonces el algoritmo depende del tipo de clave (especialmente Ed25519 y Ed448).

Si key no es un KeyObject, esta función se comporta como si key se hubiera pasado a crypto.createPrivateKey(). Si es un objeto, se pueden pasar las siguientes propiedades adicionales:

  • dsaEncoding <string> Para DSA y ECDSA, esta opción especifica el formato de la firma generada. Puede ser uno de los siguientes:

    • 'der' (predeterminado): Estructura de firma ASN.1 con codificación DER que codifica (r, s).
    • 'ieee-p1363': Formato de firma r || s como se propone en IEEE-P1363.

  • padding <integer> Valor de relleno opcional para RSA, uno de los siguientes:

    • crypto.constants.RSA_PKCS1_PADDING (predeterminado)
    • crypto.constants.RSA_PKCS1_PSS_PADDING

RSA_PKCS1_PSS_PADDING utilizará MGF1 con la misma función hash utilizada para firmar el mensaje como se especifica en la sección 3.1 de RFC 4055.

  • saltLength <integer> Longitud de la sal para cuando el relleno es RSA_PKCS1_PSS_PADDING. El valor especial crypto.constants.RSA_PSS_SALTLEN_DIGEST establece la longitud de la sal al tamaño del resumen, crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN (predeterminado) la establece al valor máximo permitido.

Si se proporciona la función callback, esta función utiliza el grupo de hilos de libuv.

crypto.subtle ​

Agregado en: v17.4.0

Un alias conveniente para crypto.webcrypto.subtle.

crypto.timingSafeEqual(a, b) ​

[Historial]

VersiónCambios
v15.0.0Los argumentos a y b también pueden ser ArrayBuffer.
v6.6.0Agregado en: v6.6.0

Esta función compara los bytes subyacentes que representan las instancias de ArrayBuffer, TypedArray o DataView dadas utilizando un algoritmo de tiempo constante.

Esta función no filtra información de tiempo que permitiría a un atacante adivinar uno de los valores. Esto es adecuado para comparar resúmenes HMAC o valores secretos como cookies de autenticación o URL de capacidad.

a y b deben ser ambos Buffers, TypedArrays o DataViews, y deben tener la misma longitud de bytes. Se genera un error si a y b tienen diferentes longitudes de bytes.

Si al menos uno de a y b es un TypedArray con más de un byte por entrada, como Uint16Array, el resultado se calculará utilizando el orden de bytes de la plataforma.

Cuando ambas entradas son Float32Arrays o Float64Arrays, esta función podría devolver resultados inesperados debido a la codificación IEEE 754 de números de coma flotante. En particular, ni x === y ni Object.is(x, y) implica que las representaciones de bytes de dos números de coma flotante x e y sean iguales.

El uso de crypto.timingSafeEqual no garantiza que el código circundante sea seguro en el tiempo. Se debe tener cuidado para garantizar que el código circundante no introduzca vulnerabilidades de tiempo.

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

[Historial]

VersiónCambios
v18.0.0Pasar un callback inválido al argumento callback ahora arroja ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v15.12.0Se agregó el argumento callback opcional.
v15.0.0Los argumentos data, key y signature también pueden ser ArrayBuffer.
v13.2.0, v12.16.0Esta función ahora soporta firmas DSA y ECDSA IEEE-P1363.
v12.0.0Agregado en: v12.0.0

Verifica la firma dada para data utilizando la clave y el algoritmo dados. Si algorithm es null o undefined, entonces el algoritmo depende del tipo de clave (especialmente Ed25519 y Ed448).

Si key no es un KeyObject, esta función se comporta como si key se hubiera pasado a crypto.createPublicKey(). Si es un objeto, se pueden pasar las siguientes propiedades adicionales:

  • dsaEncoding <string> Para DSA y ECDSA, esta opción especifica el formato de la firma. Puede ser uno de los siguientes:

    • 'der' (por defecto): Estructura de firma ASN.1 codificada en DER que codifica (r, s).
    • 'ieee-p1363': Formato de firma r || s como se propone en IEEE-P1363.

  • padding <integer> Valor de relleno opcional para RSA, uno de los siguientes:

    • crypto.constants.RSA_PKCS1_PADDING (por defecto)
    • crypto.constants.RSA_PKCS1_PSS_PADDING

RSA_PKCS1_PSS_PADDING utilizará MGF1 con la misma función hash utilizada para firmar el mensaje como se especifica en la sección 3.1 de RFC 4055.

  • saltLength <integer> Longitud de la sal para cuando el relleno es RSA_PKCS1_PSS_PADDING. El valor especial crypto.constants.RSA_PSS_SALTLEN_DIGEST establece la longitud de la sal al tamaño del resumen, crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN (por defecto) lo establece al valor máximo permisible.

El argumento signature es la firma previamente calculada para los data.

Dado que las claves públicas pueden derivarse de las claves privadas, se puede pasar una clave privada o una clave pública para key.

Si se proporciona la función callback, esta función utiliza el threadpool de libuv.

crypto.webcrypto ​

Agregado en: v15.0.0

Tipo: <Crypto> Una implementación del estándar Web Crypto API.

Consulte la documentación de Web Crypto API para obtener más detalles.

Notas ​

Uso de cadenas como entradas para las API criptográficas ​

Por razones históricas, muchas API criptográficas proporcionadas por Node.js aceptan cadenas como entradas donde el algoritmo criptográfico subyacente funciona con secuencias de bytes. Estas instancias incluyen textos planos, textos cifrados, claves simétricas, vectores de inicialización, contraseñas, sales, etiquetas de autenticación y datos autenticados adicionales.

Al pasar cadenas a las API criptográficas, tenga en cuenta los siguientes factores.

  • No todas las secuencias de bytes son cadenas UTF-8 válidas. Por lo tanto, cuando una secuencia de bytes de longitud n se deriva de una cadena, su entropía es generalmente menor que la entropía de una secuencia n de bytes aleatoria o pseudoaleatoria. Por ejemplo, ninguna cadena UTF-8 dará como resultado la secuencia de bytes c0 af. Las claves secretas deben ser casi exclusivamente secuencias de bytes aleatorias o pseudoaleatorias.
  • De manera similar, al convertir secuencias de bytes aleatorias o pseudoaleatorias en cadenas UTF-8, las subsecuencias que no representan puntos de código válidos pueden ser reemplazadas por el carácter de reemplazo Unicode (U+FFFD). La representación de bytes de la cadena Unicode resultante puede, por lo tanto, no ser igual a la secuencia de bytes de la que se creó la cadena. Las salidas de los cifrados, las funciones hash, los algoritmos de firma y las funciones de derivación de claves son secuencias de bytes pseudoaleatorias y no deben usarse como cadenas Unicode.
  • Cuando las cadenas se obtienen de la entrada del usuario, algunos caracteres Unicode se pueden representar de múltiples formas equivalentes que dan como resultado diferentes secuencias de bytes. Por ejemplo, al pasar una contraseña de usuario a una función de derivación de claves, como PBKDF2 o scrypt, el resultado de la función de derivación de claves depende de si la cadena usa caracteres compuestos o descompuestos. Node.js no normaliza las representaciones de caracteres. Los desarrolladores deben considerar usar String.prototype.normalize() en las entradas del usuario antes de pasarlas a las API criptográficas.

API de streams heredada (anterior a Node.js 0.10) ​

El módulo Crypto se añadió a Node.js antes de que existiera el concepto de una API de Stream unificada, y antes de que existieran los objetos Buffer para manejar datos binarios. Como tal, muchas clases crypto tienen métodos que no se encuentran normalmente en otras clases de Node.js que implementan la API de streams (p.ej. update(), final() o digest()). Además, muchos métodos aceptaban y devolvían cadenas codificadas en 'latin1' por defecto en lugar de Buffers. Este valor predeterminado se cambió después de Node.js v0.8 para utilizar objetos Buffer de forma predeterminada.

Soporte para algoritmos débiles o comprometidos ​

El módulo node:crypto todavía soporta algunos algoritmos que ya están comprometidos y no se recomienda su uso. La API también permite el uso de cifrados y hashes con un tamaño de clave pequeño que son demasiado débiles para un uso seguro.

Los usuarios deben asumir toda la responsabilidad de seleccionar el algoritmo criptográfico y el tamaño de la clave de acuerdo con sus requisitos de seguridad.

Basado en las recomendaciones de NIST SP 800-131A:

  • MD5 y SHA-1 ya no son aceptables cuando se requiere resistencia a la colisión, como en las firmas digitales.
  • Se recomienda que la clave utilizada con los algoritmos RSA, DSA y DH tenga al menos 2048 bits y la de la curva de ECDSA y ECDH al menos 224 bits, para ser segura para su uso durante varios años.
  • Los grupos DH de modp1, modp2 y modp5 tienen un tamaño de clave menor a 2048 bits y no se recomiendan.

Consulta la referencia para otras recomendaciones y detalles.

Algunos algoritmos que tienen debilidades conocidas y son de poca relevancia en la práctica sólo están disponibles a través del proveedor heredado, que no está habilitado por defecto.

Modo CCM ​

CCM es uno de los algoritmos AEAD soportados. Las aplicaciones que utilizan este modo deben adherirse a ciertas restricciones al usar la API de cifrado:

  • La longitud de la etiqueta de autenticación debe especificarse durante la creación del cifrado estableciendo la opción authTagLength y debe ser una de 4, 6, 8, 10, 12, 14 o 16 bytes.
  • La longitud del vector de inicialización (nonce) N debe estar entre 7 y 13 bytes (7 ≤ N ≤ 13).
  • La longitud del texto plano está limitada a 2 ** (8 * (15 - N)) bytes.
  • Al descifrar, la etiqueta de autenticación debe establecerse a través de setAuthTag() antes de llamar a update(). De lo contrario, el descifrado fallará y final() lanzará un error en cumplimiento de la sección 2.6 de RFC 3610.
  • El uso de métodos de flujo como write(data), end(data) o pipe() en modo CCM podría fallar ya que CCM no puede manejar más de un trozo de datos por instancia.
  • Al pasar datos autenticados adicionales (AAD), la longitud del mensaje real en bytes debe pasarse a setAAD() a través de la opción plaintextLength. Muchas bibliotecas criptográficas incluyen la etiqueta de autenticación en el texto cifrado, lo que significa que producen textos cifrados de la longitud plaintextLength + authTagLength. Node.js no incluye la etiqueta de autenticación, por lo que la longitud del texto cifrado es siempre plaintextLength. Esto no es necesario si no se utiliza AAD.
  • Como CCM procesa todo el mensaje a la vez, update() debe llamarse exactamente una vez.
  • Aunque llamar a update() es suficiente para cifrar/descifrar el mensaje, las aplicaciones deben llamar a final() para calcular o verificar la etiqueta de autenticación.
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 ​

Cuando se utiliza OpenSSL 3, Node.js soporta FIPS 140-2 cuando se usa con un proveedor OpenSSL 3 apropiado, como el proveedor FIPS de OpenSSL 3, que se puede instalar siguiendo las instrucciones del archivo README de FIPS de OpenSSL.

Para el soporte de FIPS en Node.js necesitará:

  • Un proveedor FIPS de OpenSSL 3 correctamente instalado.
  • Un archivo de configuración del módulo FIPS de OpenSSL 3.
  • Un archivo de configuración de OpenSSL 3 que haga referencia al archivo de configuración del módulo FIPS.

Node.js deberá configurarse con un archivo de configuración de OpenSSL que apunte al proveedor FIPS. Un archivo de configuración de ejemplo se ve así:

text
nodejs_conf = nodejs_init

.include /<ruta absoluta>/fipsmodule.cnf

[nodejs_init]
providers = provider_sect

[provider_sect]
default = default_sect
# El nombre de la sección fips debe coincidir con el nombre de la sección dentro del {#the-fips-section-name-should-match-the-section-name-inside-the}
# fipsmodule.cnf incluido.
fips = fips_sect

[default_sect]
activate = 1

donde fipsmodule.cnf es el archivo de configuración del módulo FIPS generado a partir del paso de instalación del proveedor FIPS:

bash
openssl fipsinstall

Establezca la variable de entorno OPENSSL_CONF para que apunte a su archivo de configuración y OPENSSL_MODULES a la ubicación de la biblioteca dinámica del proveedor FIPS. Por ejemplo:

bash
export OPENSSL_CONF=/<ruta al archivo de configuración>/nodejs.cnf
export OPENSSL_MODULES=/<ruta a la libreria openssl>/ossl-modules

El modo FIPS se puede habilitar en Node.js ya sea:

  • Iniciando Node.js con los flags de línea de comandos --enable-fips o --force-fips.
  • Llamando programáticamente a crypto.setFips(true).

Opcionalmente, el modo FIPS se puede habilitar en Node.js a través del archivo de configuración de OpenSSL. Por ejemplo:

text
nodejs_conf = nodejs_init

.include /<ruta absoluta>/fipsmodule.cnf

[nodejs_init]
providers = provider_sect
alg_section = algorithm_sect

[provider_sect]
default = default_sect
# El nombre de la sección fips debe coincidir con el nombre de la sección dentro del {#included-fipsmodulecnf}
# fipsmodule.cnf incluido.
fips = fips_sect

[default_sect]
activate = 1

[algorithm_sect]
default_properties = fips=yes

Constantes criptográficas ​

Las siguientes constantes exportadas por crypto.constants se aplican a varios usos de los módulos node:crypto, node:tls y node:https y generalmente son específicas de OpenSSL.

Opciones de OpenSSL ​

Consulte la lista de banderas SSL OP para obtener detalles.

ConstanteDescripción
SSL_OP_ALLAplica múltiples soluciones para errores dentro de OpenSSL. Consulte https://www.openssl.org/docs/man3.0/man3/SSL_CTX_set_options.html para más detalles.
SSL_OP_ALLOW_NO_DHE_KEXIndica a OpenSSL que permita un modo de intercambio de claves no basado en [EC]DHE para TLS v1.3
SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATIONPermite la renegociación insegura heredada entre OpenSSL y clientes o servidores sin parches. Consulte https://www.openssl.org/docs/man3.0/man3/SSL_CTX_set_options.html .
SSL_OP_CIPHER_SERVER_PREFERENCEIntenta usar las preferencias del servidor en lugar de las del cliente al seleccionar un cifrado. El comportamiento depende de la versión del protocolo. Consulte https://www.openssl.org/docs/man3.0/man3/SSL_CTX_set_options.html .
SSL_OP_CISCO_ANYCONNECTIndica a OpenSSL que use el identificador de versión de Cisco de DTLS_BAD_VER.
SSL_OP_COOKIE_EXCHANGEIndica a OpenSSL que active el intercambio de cookies.
SSL_OP_CRYPTOPRO_TLSEXT_BUGIndica a OpenSSL que agregue la extensión server-hello de una versión temprana del borrador de cryptopro.
SSL_OP_DONT_INSERT_EMPTY_FRAGMENTSIndica a OpenSSL que deshabilite una solución para una vulnerabilidad de SSL 3.0/TLS 1.0 agregada en OpenSSL 0.9.6d.
SSL_OP_LEGACY_SERVER_CONNECTPermite la conexión inicial a servidores que no admiten RI.
SSL_OP_NO_COMPRESSIONIndica a OpenSSL que deshabilite el soporte para la compresión SSL/TLS.
SSL_OP_NO_ENCRYPT_THEN_MACIndica a OpenSSL que deshabilite encrypt-then-MAC.
SSL_OP_NO_QUERY_MTU
SSL_OP_NO_RENEGOTIATIONIndica a OpenSSL que deshabilite la renegociación.
SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATIONIndica a OpenSSL que siempre inicie una nueva sesión al realizar la renegociación.
SSL_OP_NO_SSLv2Indica a OpenSSL que desactive SSL v2
SSL_OP_NO_SSLv3Indica a OpenSSL que desactive SSL v3
SSL_OP_NO_TICKETIndica a OpenSSL que deshabilite el uso de tickets RFC4507bis.
SSL_OP_NO_TLSv1Indica a OpenSSL que desactive TLS v1
SSL_OP_NO_TLSv1_1Indica a OpenSSL que desactive TLS v1.1
SSL_OP_NO_TLSv1_2Indica a OpenSSL que desactive TLS v1.2
SSL_OP_NO_TLSv1_3Indica a OpenSSL que desactive TLS v1.3
SSL_OP_PRIORITIZE_CHACHAIndica al servidor OpenSSL que priorice ChaCha20-Poly1305 cuando el cliente lo haga. Esta opción no tiene efecto si SSL_OP_CIPHER_SERVER_PREFERENCE no está habilitada.
SSL_OP_TLS_ROLLBACK_BUGIndica a OpenSSL que deshabilite la detección de ataques de reversión de versión.

Constantes del motor OpenSSL ​

ConstanteDescripción
ENGINE_METHOD_RSALimitar el uso del motor a RSA
ENGINE_METHOD_DSALimitar el uso del motor a DSA
ENGINE_METHOD_DHLimitar el uso del motor a DH
ENGINE_METHOD_RANDLimitar el uso del motor a RAND
ENGINE_METHOD_ECLimitar el uso del motor a EC
ENGINE_METHOD_CIPHERSLimitar el uso del motor a CIPHERS
ENGINE_METHOD_DIGESTSLimitar el uso del motor a DIGESTS
ENGINE_METHOD_PKEY_METHSLimitar el uso del motor a PKEY_METHS
ENGINE_METHOD_PKEY_ASN1_METHSLimitar el uso del motor a PKEY_ASN1_METHS
ENGINE_METHOD_ALL
ENGINE_METHOD_NONE

Otras constantes de OpenSSL ​

ConstanteDescripción
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_DIGESTEstablece la longitud de la sal para RSA_PKCS1_PSS_PADDING al tamaño del resumen al firmar o verificar.
RSA_PSS_SALTLEN_MAX_SIGNEstablece la longitud de la sal para RSA_PKCS1_PSS_PADDING al valor máximo permitido al firmar datos.
RSA_PSS_SALTLEN_AUTOHace que la longitud de la sal para RSA_PKCS1_PSS_PADDING se determine automáticamente al verificar una firma.
POINT_CONVERSION_COMPRESSED
POINT_CONVERSION_UNCOMPRESSED
POINT_CONVERSION_HYBRID

Constantes de crypto de Node.js ​

ConstanteDescripción
defaultCoreCipherListEspecifica la lista de cifrado predeterminada incorporada utilizada por Node.js.
defaultCipherListEspecifica la lista de cifrado predeterminada activa utilizada por el proceso actual de Node.js.