iDoc.dev

Español

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

Español

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

Tema

Criptografía ​

[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 envoltorios 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)
// Imprime:
//   c0fa1bc00531bd78ef38c628449c5102aeabd49b5dc3a2a516ea6ea959d6658e
js
const { createHmac } = require('node:crypto')

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

Determinar si la compatibilidad con criptografía no está disponible ​

Es posible que Node.js se compile sin incluir compatibilidad con el módulo node:crypto. En tales casos, intentar importar desde crypto o llamar a require('node:crypto') producirá un error.

Cuando se usa CommonJS, el error que se produce se puede capturar usando try/catch:

js
let crypto
try {
  crypto = require('node:crypto')
} catch (err) {
  console.error('¡La compatibilidad con criptografía está deshabilitada!')
}

Cuando se usa la palabra clave import ESM léxica, el error solo se puede capturar si se registra un controlador para process.on('uncaughtException') antes de que se realice cualquier intento de cargar el módulo (usando, por ejemplo, un módulo de precarga).

Cuando se usa ESM, si existe la posibilidad de que el código se ejecute en una compilación de Node.js donde la compatibilidad con criptografía no está habilitada, considere usar la función import() en lugar de la palabra clave import léxica:

js
let crypto
try {
  crypto = await import('node:crypto')
} catch (err) {
  console.error('¡La compatibilidad con criptografía está deshabilitada!')
}

Clase: Certificate ​

Añadido 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á en desuso desde HTML 5.2 y los nuevos proyectos no deben usar más este elemento.

El módulo node:crypto proporciona la clase Certificate para trabajar con datos SPKAC. El uso más común es manejar la salida generada por el elemento \<keygen\> de HTML5. Node.js usa 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.0Añadido 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)
// Imprime: la clave pública como <Buffer ...>
js
const { Certificate } = require('node:crypto')
const spkac = getSpkacSomehow()
const publicKey = Certificate.exportPublicKey(spkac)
console.log(publicKey)
// Imprime: la clave pública como <Buffer ...>

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

[Historial]

VersiónCambios
v15.0.0El argumento spkac puede ser un ArrayBuffer. Se añadió encoding. 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)))
// Imprime: true o false
js
const { Buffer } = require('node:buffer')
const { Certificate } = require('node:crypto')

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

API heredada ​

[Estable: 0 - Obsoleta]

Estable: 0 Estabilidad: 0 - Obsoleta

Como interfaz heredada, 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 se pueden crear 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'))
// Imprime: el desafío como una cadena UTF8
js
const { Certificate } = require('node:crypto')
const cert = Certificate()
const spkac = getSpkacSomehow()
const challenge = cert.exportChallenge(spkac)
console.log(challenge.toString('utf8'))
// Imprime: el desafío como una cadena UTF8

certificate.exportPublicKey(spkac[, encoding]) ​

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

Añadido 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 legible y escribible, donde se escriben datos sin cifrar para producir datos cifrados en el lado legible, o
  • Usando 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 usando 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 = 'Contraseña usada para generar la clave'

// Primero, generaremos la clave. La longitud de la clave depende del algoritmo.
// En este caso, para aes192, son 24 bytes (192 bits).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err
  // Luego, generaremos un vector de inicialización aleatorio
  randomFill(new Uint8Array(16), (err, iv) => {
    if (err) throw err

    // Una vez que tengamos la clave y el iv, podemos crear y usar el cifrado...
    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('algunos datos de texto claro')
    cipher.end()
  })
})
js
const { scrypt, randomFill, createCipheriv } = require('node:crypto')

const algorithm = 'aes-192-cbc'
const password = 'Contraseña usada para generar la clave'

// Primero, generaremos la clave. La longitud de la clave depende del algoritmo.
// En este caso, para aes192, son 24 bytes (192 bits).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err
  // Luego, generaremos un vector de inicialización aleatorio
  randomFill(new Uint8Array(16), (err, iv) => {
    if (err) throw err

    // Una vez que tengamos la clave y el iv, podemos crear y usar el cifrado...
    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('algunos datos de texto claro')
    cipher.end()
  })
})

Ejemplo: Usando Cipher y streams en canalización:

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 = 'Contraseña usada para generar la clave'

// Primero, generaremos la clave. La longitud de la clave depende del algoritmo.
// En este caso, para aes192, son 24 bytes (192 bits).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err
  // Luego, generaremos un vector de inicialización aleatorio
  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 = 'Contraseña usada para generar la clave'

// Primero, generaremos la clave. La longitud de la clave depende del algoritmo.
// En este caso, para aes192, son 24 bytes (192 bits).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err
  // Luego, generaremos un vector de inicialización aleatorio
  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 = 'Contraseña usada para generar la clave'

// Primero, generaremos la clave. La longitud de la clave depende del algoritmo.
// En este caso, para aes192, son 24 bytes (192 bits).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err
  // Luego, generaremos un vector de inicialización aleatorio
  randomFill(new Uint8Array(16), (err, iv) => {
    if (err) throw err

    const cipher = createCipheriv(algorithm, key, iv)

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

const algorithm = 'aes-192-cbc'
const password = 'Contraseña usada para generar la clave'

// Primero, generaremos la clave. La longitud de la clave depende del algoritmo.
// En este caso, para aes192, son 24 bytes (192 bits).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err
  // Luego, generaremos un vector de inicialización aleatorio
  randomFill(new Uint8Array(16), (err, iv) => {
    if (err) throw err

    const cipher = createCipheriv(algorithm, key, iv)

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

cipher.final([outputEncoding]) ​

Añadido en: v0.1.94

  • outputEncoding <string> La codificación del valor devuelto.
  • 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 utilizar para cifrar datos. Los intentos de llamar a cipher.final() más de una vez darán como resultado que se lance un error.

cipher.getAuthTag() ​

Añadido en: v1.0.0

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

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

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

cipher.setAAD(buffer[, options]) ​

Añadido en: v1.0.0

Cuando se utiliza un modo de cifrado autenticado (GCM, CCM, OCB, y chacha20-poly1305 son actualmente compatibles), el método cipher.setAAD() establece el valor utilizado para el parámetro de entrada de 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 plano en bytes. Ver modo CCM.

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

cipher.setAutoPadding([autoPadding]) ​

Añadido en: v0.7.1

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

Cuando se utilizan algoritmos de cifrado de bloque, la clase Cipher añadirá 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() lanzará un error. Deshabilitar el relleno automático es útil para rellenos no estándar, por ejemplo, usando 0x0 en lugar de relleno PKCS.

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

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

[Historial]

VersiónCambios
v6.0.0La codificación inputEncoding predeterminada cambió de binary a utf8.
v0.1.94Añadido 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 inputEncoding se ignora.

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 nuevos datos hasta que se llame a cipher.final(). Llamar a cipher.update() después de cipher.final() resultará en que se lance un error.

Clase: Decipher ​

Añadido 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 a la vez legible y escribible, donde se escriben datos encriptados para producir datos desencriptados en el lado legible, o
  • Usando los métodos decipher.update() y decipher.final() para producir los datos desencriptados.

El método crypto.createDecipheriv() se usa 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 = 'Contraseña usada para generar la clave'
// La longitud de la clave depende del algoritmo. En este caso para aes192, es
// 24 bytes (192 bits).
// Use `crypto.scrypt()` asíncrono en su lugar.
const key = scryptSync(password, 'salt', 24)
// El IV normalmente se pasa junto con el texto cifrado.
const iv = Buffer.alloc(16, 0) // Vector de inicialización.

const decipher = createDecipheriv(algorithm, key, iv)

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

// Encriptado con el mismo algoritmo, clave e iv.
const encrypted = 'e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa'
decipher.write(encrypted, 'hex')
decipher.end()
js
const { scryptSync, createDecipheriv } = require('node:crypto')
const { Buffer } = require('node:buffer')

const algorithm = 'aes-192-cbc'
const password = 'Contraseña usada para generar la clave'
// La longitud de la clave depende del algoritmo. En este caso para aes192, es
// 24 bytes (192 bits).
// Use `crypto.scrypt()` asíncrono en su lugar.
const key = scryptSync(password, 'salt', 24)
// El IV normalmente se pasa junto con el texto cifrado.
const iv = Buffer.alloc(16, 0) // Vector de inicialización.

const decipher = createDecipheriv(algorithm, key, iv)

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

// Encriptado con el mismo algoritmo, clave e iv.
const encrypted = 'e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa'
decipher.write(encrypted, 'hex')
decipher.end()

Ejemplo: Usando Decipher y streams encadenados:

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 = 'Contraseña usada para generar la clave'
// Use `crypto.scrypt()` asíncrono en su lugar.
const key = scryptSync(password, 'salt', 24)
// El IV normalmente se pasa junto con el texto cifrado.
const iv = Buffer.alloc(16, 0) // Vector de inicialización.

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 = 'Contraseña usada para generar la clave'
// Use `crypto.scrypt()` asíncrono en su lugar.
const key = scryptSync(password, 'salt', 24)
// El IV normalmente se pasa junto con el texto cifrado.
const iv = Buffer.alloc(16, 0) // Vector de inicialización.

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 = 'Contraseña usada para generar la clave'
// Use `crypto.scrypt()` asíncrono en su lugar.
const key = scryptSync(password, 'salt', 24)
// El IV normalmente se pasa junto con el texto cifrado.
const iv = Buffer.alloc(16, 0) // Vector de inicialización.

const decipher = createDecipheriv(algorithm, key, iv)

// Encriptado usando el mismo algoritmo, clave e iv.
const encrypted = 'e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa'
let decrypted = decipher.update(encrypted, 'hex', 'utf8')
decrypted += decipher.final('utf8')
console.log(decrypted)
// Imprime: algunos datos de texto claro
js
const { scryptSync, createDecipheriv } = require('node:crypto')
const { Buffer } = require('node:buffer')

const algorithm = 'aes-192-cbc'
const password = 'Contraseña usada para generar la clave'
// Use `crypto.scrypt()` asíncrono en su lugar.
const key = scryptSync(password, 'salt', 24)
// El IV normalmente se pasa junto con el texto cifrado.
const iv = Buffer.alloc(16, 0) // Vector de inicialización.

const decipher = createDecipheriv(algorithm, key, iv)

// Encriptado usando el mismo algoritmo, clave e iv.
const encrypted = 'e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa'
let decrypted = decipher.update(encrypted, 'hex', 'utf8')
decrypted += decipher.final('utf8')
console.log(decrypted)
// Imprime: algunos datos de texto claro

decipher.final([outputEncoding]) ​

Añadido en: v0.1.94

  • outputEncoding <string> La codificación del valor devuelto.
  • 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 (GCM, CCM, OCB y chacha20-poly1305 son compatibles actualmente), 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().

Al pasar una cadena como buffer, tenga en cuenta las advertencias al usar cadenas como entradas para las API criptográficas.

decipher.setAuthTag(buffer[, encoding]) ​

[Historial]

VersiónCambios
v22.0.0, v20.13.0Se ha deprecado el uso de longitudes de etiquetas GCM distintas de 128 bits sin especificar la opción authTagLength al crear decipher.
v15.0.0El argumento buffer puede ser una cadena o un ArrayBuffer y está limitado a no más de 2 ** 31 - 1 bytes.
v11.0.0Este método ahora lanza una excepción 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 (GCM, CCM, OCB y chacha20-poly1305 son actualmente compatibles), 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á una excepción, indicando que el texto cifrado debe descartarse debido a una autenticación fallida. 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 llamarse antes de decipher.update() para el modo CCM o antes de decipher.final() para los modos GCM y OCB y chacha20-poly1305. decipher.setAuthTag() solo se puede llamar una vez.

Al pasar una cadena como etiqueta de autenticación, tenga en cuenta las advertencias al usar cadenas como entradas para las API criptográficas.

decipher.setAutoPadding([autoPadding]) ​

Añadido en: v0.7.1

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

Cuando los datos han sido encriptados sin relleno de bloque estándar, llamar a decipher.setAutoPadding(false) deshabilitará el relleno automático para prevenir que decipher.final() compruebe y elimine el relleno.

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

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

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

[Historial]

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

Actualiza el descifrador con data. Si se proporciona el argumento inputEncoding, el argumento data es una cadena que usa 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.

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

El método decipher.update() puede ser llamado múltiples veces con nuevos datos hasta que se llame a decipher.final(). Llamar a decipher.update() después de decipher.final() resultará en que se lance un error.

Incluso si el cifrado subyacente implementa autenticación, la autenticidad e integridad del texto plano devuelto por esta función pueden ser inciertas en este momento. Para 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 usando la función crypto.createDiffieHellman().

js
import assert from 'node:assert'

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

// Generar las claves de Alicia...
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 Alicia...
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 usando la inputEncoding especificada, y el secreto se codifica usando la outputEncoding especificada. Si no se proporciona 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 se hayan generado o calculado, y devuelve la clave pública en la codificación especificada. Esta clave debe transferirse a la otra parte. Si se proporciona encoding, se devuelve una cadena; de lo contrario, se devuelve un Buffer.

Esta función es un envoltorio ligero alrededor de DH_generate_key(). En particular, una vez que se ha generado o establecido una clave privada, llamar 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 codificación 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 codificación especificada. Si se proporciona encoding, se devuelve una cadena; de lo contrario, se devuelve un Buffer.

diffieHellman.getPrivateKey([encoding]) ​

Añadido en: v0.5.0

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

diffieHellman.getPublicKey([encoding]) ​

Añadido en: v0.5.0

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

diffieHellman.setPrivateKey(privateKey[, encoding]) ​

Añadido en: v0.5.0

Establece la clave privada Diffie-Hellman. Si se proporciona el argumento encoding, se espera que privateKey sea una cadena. 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 utilizar diffieHellman.setPublicKey() o diffieHellman.generateKeys() para proporcionar manualmente la clave pública o para derivarla automáticamente.

diffieHellman.setPublicKey(publicKey[, encoding]) ​

Añadido en: v0.5.0

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

diffieHellman.verifyError ​

Añadido en: v0.11.12

Un campo de bits que contiene cualquier advertencia o error resultante de una comprobació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 ​

Añadido en: v0.7.5

La clase DiffieHellmanGroup toma un grupo modp conocido como 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')

Se admiten los siguientes grupos:

  • '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 se admiten pero están en desuso (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 en desuso podrían eliminarse en futuras versiones de Node.js.

Clase: ECDH ​

Añadido en: v0.11.14

La clase ECDH es una utilidad para crear intercambios de claves Elliptic Curve Diffie-Hellman (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')

// Generar las claves de Alicia...
const alice = createECDH('secp521r1')
const aliceKey = alice.generateKeys()

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

// Intercambiar y generar 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')

// Generar las claves de Alicia...
const alice = createECDH('secp521r1')
const aliceKey = alice.generateKeys()

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

// Intercambiar y generar 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]]]) ​

Añadido 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 proporcionada se interpreta utilizando la inputEncoding especificada, y la clave devuelta se codifica utilizando la outputEncoding especificada.

Utilice crypto.getCurves() para obtener una lista de los 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.

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 descomprimida deberían 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 descomprimida deberían ser iguales
console.log(uncompressedKey === ecdh.getPublicKey('hex'))

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

[Historial]

VersiónCambios
v10.0.0Formato de error modificado para una mejor compatibilidad con el error de clave pública inválida.
v6.0.0La codificación inputEncoding predeterminada 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 usando la inputEncoding especificada, y el secreto devuelto se codifica usando la outputEncoding especificada. Si no se proporciona inputEncoding, se espera que otherPublicKey sea un Buffer, TypedArray o DataView.

Si outputEncoding se da una cadena, se devolverá una cadena; de lo contrario, se devuelve 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 proporciona de un usuario remoto a través de una red insegura, asegúrese de manejar esta excepción en consecuencia.

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

Añadido en: v0.11.14

Genera valores de clave EC Diffie-Hellman privada y pública, y devuelve la clave pública en el format y la 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]) ​

Añadido en: v0.11.14

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

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

Añadido 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álida para la curva especificada cuando se creó el objeto ECDH, se lanza un error. Al establecer la clave privada, el punto público (clave) asociado también se genera 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. Normalmente se llamará a ecdh.generateKeys() o ecdh.setPrivateKey(). El método ecdh.setPrivateKey() intenta generar el punto/clave público asociado con la clave privada que se está estableciendo.

Ejemplo (obteniendo un secreto compartido):

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

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

// Esta es una forma abreviada de especificar una de las claves privadas anteriores de Alice.
// Sería imprudente usar una clave privada tan predecible en una aplicación real.
alice.setPrivateKey(createHash('sha256').update('alice', 'utf8').digest())

// Bob usa un nuevo par de claves pseudorandom criptográficamente fuerte
// generado
bob.generateKeys()

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

// aliceSecret y bobSecret deberían ser el mismo valor de secreto compartido
console.log(aliceSecret === bobSecret)
js
const { createECDH, createHash } = require('node:crypto')

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

// Esta es una forma abreviada de especificar una de las claves privadas anteriores de Alice.
// Sería imprudente usar una clave privada tan predecible en una aplicación real.
alice.setPrivateKey(createHash('sha256').update('alice', 'utf8').digest())

// Bob usa un nuevo par de claves pseudorandom criptográficamente fuerte
// generado
bob.generateKeys()

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

// aliceSecret y bobSecret deberían ser el mismo valor de secreto compartido
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. Se puede usar de dos maneras:

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

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

Ejemplo: Usando objetos Hash como streams:

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

const hash = createHash('sha256')

hash.on('readable', () => {
  // Solo se va a producir un elemento 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', () => {
  // Solo se va a producir un elemento 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: Usando Hash y streams encadenados:

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

Añadido en: v13.1.0

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

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

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

js
// Calcular 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
// Calcular 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]) ​

Añadido en: v0.1.92

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

El objeto Hash no se puede usar de nuevo después de que se haya llamado al método hash.digest(). Múltiples llamadas harán que se lance un error.

hash.update(data[, inputEncoding]) ​

[Historial]

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

Actualiza el contenido del hash con los datos dados, cuya codificación se proporciona 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: Hmac ​

Añadido en: v0.1.94

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

  • Como un stream que es legible y 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', () => {
  // Sólo se va a producir un elemento por el
  // stream hash.
  const data = hmac.read()
  if (data) {
    console.log(data.toString('hex'))
    // Imprime:
    //   7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f77e
  }
})

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

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

hmac.on('readable', () => {
  // Sólo se va a producir un elemento por el
  // stream hash.
  const data = hmac.read()
  if (data) {
    console.log(data.toString('hex'))
    // Imprime:
    //   7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f77e
  }
})

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

Ejemplo: Usando Hmac y streams encadenados:

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'))
// Imprime:
//   7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f77e
js
const { createHmac } = require('node:crypto')

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

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

hmac.digest([encoding]) ​

Añadido 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 usar después de que se haya llamado a hmac.digest(). Múltiples llamadas a hmac.digest() resultarán en que se lance un error.

hmac.update(data[, inputEncoding]) ​

[Historial]

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

Actualiza el contenido de Hmac con los datos proporcionados, cuya codificación se proporciona 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.

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 subprocesos de trabajo usando postMessage.
v11.13.0Esta clase ahora se exporta.
v11.6.0Añadido en: v11.6.0

Node.js utiliza 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 el uso de la nueva API KeyObject en lugar de pasar claves como cadenas o Buffer debido a las características de seguridad mejoradas.

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

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

Añadido en: v15.0.0

Ejemplo: Conversión de una instancia 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.0Exponer parámetros de secuencia RSASSA-PSS-params para claves RSA-PSS.
v15.7.0Añadido en: v15.7.0
  • <Objeto>
    • modulusLength: <número> Tamaño de la clave en bits (RSA, DSA).
    • publicExponent: <bigint> Exponente público (RSA).
    • hashAlgorithm: <cadena> Nombre del resumen del mensaje (RSA-PSS).
    • mgf1HashAlgorithm: <cadena> Nombre del resumen del mensaje usado por MGF1 (RSA-PSS).
    • saltLength: <número> Longitud mínima de la sal en bytes (RSA-PSS).
    • divisorLength: <número> Tamaño de q en bits (DSA).
    • namedCurve: <cadena> Nombre de la curva (EC).

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

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

Otros detalles de la clave podrían ser expuestos a través de esta API usando 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 desconocido en lugar de abortar.
v12.0.0Se agregó soporte para 'x25519' y 'x448'.
v12.0.0Se agregó soporte para 'ed25519' y 'ed448'.
v11.6.0Añadido en: v11.6.0

Para claves asimétricas, esta propiedad representa el tipo de clave. Los tipos de clave compatibles 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 de KeyObject desconocidos y claves simétricas.

keyObject.equals(otherKeyObject) ​

Añadido 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 tiempo constante.

keyObject.export([options]) ​

[Historial]

VersiónCambios
v15.9.0Se añadió soporte para el formato 'jwk'.
v11.6.0Añadido en: v11.6.0

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

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

Para claves públicas, se pueden usar 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 usar 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 passphrase dados usando el cifrado basado en contraseña PKCS#5 v2.0.
  • passphrase: <string> | <Buffer> La frase de contraseña que se utilizará para el cifrado, ver cipher.

El tipo de resultado depende del formato de codificación seleccionado, cuando es PEM el resultado es una cadena, cuando es DER será un buffer que contiene los datos codificados como DER, cuando es 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 tipo 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 formato 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 PEM no es compatible cuando se cifra 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 a 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 stream escribible, donde se escriben los datos a firmar y se utiliza el método sign.sign() para generar y devolver la firma, o
  • Utilizando 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 la función hash que se utilizará como cadena de texto. 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'))
// Imprime: 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'))
// Imprime: 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))
// Imprime: 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))
// Imprime: true

sign.sign(privateKey[, outputEncoding]) ​

[Historial]

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

Calcula la firma de todos los datos pasados utilizando 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): Codificación de estructura de firma ASN.1 codificada en DER (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, 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 en el tamaño del resumen, crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN (predeterminado) la establece en el valor máximo permitido.

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(). Múltiples llamadas a sign.sign() resultarán en que se lance un error.

sign.update(data[, inputEncoding]) ​

[Historial]

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

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

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

Clase: Verify ​

Añadido en: v0.1.92

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

  • Como un flujo stream escribible donde los datos escritos se utilizan para validar contra la firma proporcionada, o
  • Usando 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 deben crearse directamente usando la palabra clave new.

Ver Sign para ejemplos.

verify.update(data[, inputEncoding]) ​

[Historial]

VersiónCambios
v6.0.0La codificación 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 proporciona 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 nuevos datos 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 admite firmas IEEE-P1363 DSA y ECDSA.
v12.0.0Esta función ahora admite claves RSA-PSS.
v11.7.0La clave ahora puede ser una clave privada.
v8.0.0Se agregó compatibilidad con RSASSA-PSS y opciones adicionales.
v0.1.92Añadido en: v0.1.92

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

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

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

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

  • padding <entero> 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 usada para verificar 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 <entero> 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_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 usar después de que se haya llamado a verify.verify(). Múltiples llamadas a verify.verify() resultarán en que se lance un error.

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

Clase: X509Certificate ​

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

Añadido en: v15.6.0

x509.ca ​

Añadido en: v15.6.0

  • Tipo: <boolean> Será true si se trata de 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.1Las opciones wildcards, partialWildcards, multiLabelWildcards y singleLabelSubdomains se han eliminado ya que no tenían ningún efecto.
v15.6.0Añadido en: v15.6.0

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

Si la opción 'subject' no está definida o está establecida en 'default', el sujeto del certificado solo se considera si la extensión del nombre alternativo del sujeto 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 del nombre alternativo del sujeto no existe o no contiene una dirección de correo electrónico coincidente, se considera el sujeto del certificado.

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

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.0Añadido 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 sujeto que coincide con name, o undefined si ningún nombre de sujeto 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 del sujeto que coincide. 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 mayúsculas de minúsculas, el nombre del sujeto devuelto también puede diferir del name dado en la capitalización.

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

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

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

x509.checkIP(ip) ​

[Historial]

VersiónCambios
v17.5.0, v16.14.1Se ha eliminado el argumento options ya que no tenía ningún efecto.
v15.6.0Añadido en: v15.6.0

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

Solo se consideran los nombres alternativos del sujeto iPAddress de RFC 5280, y deben coincidir exactamente con la dirección ip proporcionada. 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 proporcionado.

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

Una matriz 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á criptográficamente roto y porque 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 ​

Añadido en: v15.6.0

La huella digital SHA-256 de este certificado.

x509.fingerprint512 ​

Añadido en: v17.2.0, v16.14.0

La huella digital SHA-512 de este certificado.

Debido a que el cálculo de la huella digital SHA-256 suele ser más rápido y porque solo tiene 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 mayor nivel de seguridad 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.0Añadido en: v15.6.0

Una representación textual de la extensión de acceso a la información de 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 puede estar entre comillas para indicar que el valor es un literal de cadena JSON. Para compatibilidad con versiones anteriores, Node.js solo utiliza 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 ​

Añadido en: v15.6.0

La identificación del emisor incluida en este certificado.

x509.issuerCertificate ​

Añadido en: v15.9.0

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

x509.publicKey ​

Añadido en: v15.6.0

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

x509.raw ​

Añadido en: v15.6.0

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

x509.serialNumber ​

Añadido 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 identificador único en su lugar.

x509.subject ​

Añadido 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.0Añadido en: v15.6.0

El nombre alternativo del sujeto especificado para este certificado.

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

Versiones anteriores de Node.js asumían incorrectamente que es seguro dividir esta propiedad en la secuencia de dos caracteres ', ' (ver 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. Para compatibilidad con versiones anteriores, Node.js solo utiliza 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.toJSON() ​

Añadido en: v15.6.0

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

x509.toLegacyObject() ​

Añadido en: v15.6.0

Devuelve información sobre este certificado usando la codificación del objeto de certificado legado.

x509.toString() ​

Añadido en: v15.6.0

Devuelve el certificado codificado en PEM.

x509.validFrom ​

Añadido en: v15.6.0

La fecha y hora desde la cual este certificado es válido.

x509.validFromDate ​

Añadido en: v23.0.0

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

x509.validTo ​

Añadido en: v15.6.0

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

x509.validToDate ​

Añadido en: v23.0.0

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

x509.verify(publicKey) ​

Añadido 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 devolución de llamada 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 primo codificado como una secuencia de octetos de orden big endian de longitud arbitraria.

  • options <Object>

    • checks <number> El número de iteraciones de primalidad probabilística de Miller-Rabin que se realizarán. 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

  • 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 primo con una probabilidad de error menor que 0.25 ** options.checks.

Comprueba la primalidad del candidate.

crypto.checkPrimeSync(candidate[, options]) ​

Añ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 de primalidad probabilística de Miller-Rabin que se realizarán. 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 menor que 0.25 ** options.checks.

Comprueba la primalidad del candidate.

crypto.constants ​

Añadido 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 predeterminada a 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.0La opción authTagLength ahora se puede usar para producir etiquetas de autenticación más cortas en modo GCM y predeterminada a 16 bytes.
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 Cipher, con el algorithm, key y 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 o OCB (por ejemplo, 'aes-128-ccm'). En ese caso, se requiere la opción authTagLength y especifica la longitud de la etiqueta de autenticación en bytes, consulte Modo CCM. En 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 predeterminada a 16 bytes. Para chacha20-poly1305, la opción authTagLength predeterminada es 16 bytes.

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 y iv es un vector de inicialización. Ambos argumentos deben ser cadenas codificadas en 'utf8', Buffers, TypedArray o DataView. La key puede ser opcionalmente un KeyObject de tipo secret. Si el cifrado no necesita un vector de inicialización, iv puede ser null.

Al pasar cadenas para key o iv, tenga en cuenta 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 suelen agregarse simplemente a los mensajes de texto cifrado sin cifrar. Puede parecer contradictorio que algo deba 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 cuando se usa el cifrado chacha20-poly1305 y por defecto es 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 los 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 los 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, key y 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 o OCB (por ejemplo, 'aes-128-ccm'). En ese caso, se requiere la opción authTagLength 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 predeterminada es de 16 bytes y debe establecerse en un valor diferente si se usa una longitud diferente.

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 y iv es un vector de inicialización. Ambos argumentos deben ser cadenas codificadas en 'utf8', Buffers, TypedArray o DataView. La key puede ser opcionalmente un KeyObject de tipo secret. Si el cifrado no necesita un vector de inicialización, iv puede ser null.

Al pasar cadenas para key o iv, tenga en cuenta 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 parecer contradictorio que algo tenga que ser impredecible y único, pero no tiene que ser secreto; recuerde que un atacante no debe poder predecir con anticipación cuál será un IV dado.

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 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 Elliptic Curve Diffie-Hellman (ECDH) utilizando una curva predefinida especificada por la cadena curveName. Use crypto.getCurves() para obtener una lista de los 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 usar para generar resúmenes hash usando el algorithm dado. El argumento options opcional controla el comportamiento de la transmisión. Para las funciones hash XOF como 'shake256', la opción outputLength se puede usar para especificar la longitud de salida deseada en bytes.

El algorithm depende de los algoritmos disponibles compatibles con 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.

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', () => {
  // Solo se va a producir un elemento por la
  // transmisión hash.
  const data = input.read()
  if (data) hash.update(data)
  else {
    console.log(`${hash.digest('hex')} ${filename}`)
  }
})
js
const { createReadStream } = require('node:fs')
const { createHash } = require('node:crypto')
const { argv } = require('node:process')

const filename = argv[2]

const hash = createHash('sha256')

const input = createReadStream(filename)
input.on('readable', () => {
  // Solo se va a producir un elemento por la
  // transmisión hash.
  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.94Añadido en: v0.1.94

Crea y devuelve un objeto Hmac que usa el algorithm y la key dados. El argumento options opcional controla el comportamiento de la transmisión.

El algorithm depende de los algoritmos disponibles compatibles con la versión de OpenSSL en la plataforma. Algunos ejemplos son 'sha256', 'sha512', etc. En 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 criptográfico HMAC. 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 del 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', () => {
  // Solo se va a producir un elemento por la
  // transmisión hash.
  const data = input.read()
  if (data) hmac.update(data)
  else {
    console.log(`${hmac.digest('hex')} ${filename}`)
  }
})
js
const { createReadStream } = require('node:fs')
const { createHmac } = require('node:crypto')
const { argv } = require('node:process')

const filename = argv[2]

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

const input = createReadStream(filename)
input.on('readable', () => {
  // Solo se va a producir un elemento por la
  // transmisión hash.
  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 agregó 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 format es 'pem'; de lo contrario, key debe ser un objeto con las propiedades descritas anteriormente.

Si la clave privada está encriptada, se debe especificar 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 agregó 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 clave que contiene una clave pública. Si key es una cadena o Buffer, se asume que 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.

Debido a que las claves públicas se pueden derivar de las 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. De manera similar, si se da 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 agregó 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 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 algoritmo dado. Use 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 usar siempre los nombres de los algoritmos de resumen.

crypto.createVerify(algorithm[, options]) ​

Añadido en: v0.1.92

Crea y devuelve un objeto Verify que utiliza el algoritmo dado. Use crypto.getHashes() para obtener una matriz de nombres de los algoritmos de firma disponibles. El argumento options opcional 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 usar siempre los nombres de los algoritmos de resumen.

crypto.diffieHellman(options) ​

Añadido en: v13.9.0, v12.17.0

Calcula el secreto Diffie-Hellman basado en un privateKey y un 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 ​

Añadido 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 de cifrado compatible con FIPS. Establecerlo en true requiere una compilación FIPS de Node.js.

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

crypto.generateKey(type, options, 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.
v15.0.0Añadido en: v15.0.0

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

  • options: <Object>

    • length: <number> La longitud en bits de la clave que se va a generar. Este 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 múltiplo de 8, la clave generada se truncará a Math.floor(length / 8).
    • Si type es 'aes', la longitud debe ser uno de 128, 192 o 256.

  • callback: <Function>

Genera de forma asíncrona una nueva clave secreta aleatoria de la longitud 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 devolución de llamada inválida al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v16.10.0Agregar la capacidad de definir parámetros de secuencia RSASSA-PSS-params para pares de claves RSA-PSS.
v13.9.0, v12.17.0Agregar soporte para Diffie-Hellman.
v12.0.0Agregar soporte para pares de claves RSA-PSS.
v12.0.0Agregar la capacidad de generar pares de claves X25519 y X448.
v12.0.0Agregar 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.0Añadido en: v10.12.0

Genera un nuevo par de claves asimétricas del tipo 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.

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) => {
    // Manejar errores y usar el par de claves generado.
  }
)
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) => {
    // Manejar errores y usar el par de claves generado.
  }
)

Una vez completada la operación, 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(), devuelve una Promise para un Object con las propiedades publicKey y privateKey.

crypto.generateKeyPairSync(type, options) ​

[Historial]

VersiónCambios
v16.10.0Se agrega la capacidad de definir los parámetros de la secuencia RSASSA-PSS-params para pares de claves RSA-PSS.
v13.9.0, v12.17.0Se agrega soporte para Diffie-Hellman.
v12.0.0Se agrega soporte para pares de claves RSA-PSS.
v12.0.0Se agrega la capacidad de generar pares de claves X25519 y X448.
v12.0.0Se agrega 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.0Añadido en: v10.12.0

Genera un nuevo par de claves asimétricas del tipo dado. Actualmente se admite 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 usar 'spki'. Al codificar claves privadas, se recomienda usar 'pkcs8' con una contraseña segura y mantener la contraseña confidencial.

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

const { publicKey, privateKey } = generateKeyPairSync('rsa', {
  modulusLength: 4096,
  publicKeyEncoding: {
    type: 'spki',
    format: 'pem',
  },
  privateKeyEncoding: {
    type: 'pkcs8',
    format: 'pem',
    cipher: 'aes-256-cbc',
    passphrase: 'secreto',
  },
})
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: 'secreto',
  },
})

El valor devuelto { 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) ​

Añadido 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 que se va 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 128, 192 o 256.

  • Devuelve: <KeyObject>

Genera sincrónicamente una nueva clave secreta aleatoria de la longitud 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 devolución de llamada 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

Genera un primo pseudorandom 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á 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]) ​

Añadido en: v15.8.0

Genera un primo pseudorandom 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 configurados, 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á 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 proporcionan 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.getCipherInfo(nameOrNid[, options]) ​

Añadido 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. De forma predeterminada, el método crypto.getCipherInfo() devolverá los valores predeterminados para estos cifrados. Para probar si una longitud de clave o una longitud de iv dada es aceptable para un cifrado dado, utilice las opciones keyLength e ivLength. Si los valores dados son inaceptables, se devolverá undefined.

crypto.getCiphers() ​

Añadido en: v0.9.3

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

Añadido en: v2.3.0

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

Añadido en: v0.7.5

Crea un objeto de intercambio de claves DiffieHellmanGroup predefinido. Los grupos admitidos se enumeran en la documentación de 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 (obteniendo 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() ​

Añadido en: v10.0.0

  • Devuelve: <number> 1 si y solo si se está utilizando actualmente un proveedor de cifrado compatible con FIPS, 0 de lo contrario. Una futura versión principal de semver puede cambiar el tipo de retorno de esta API a un <boolean>.

crypto.getHashes() ​

Añadido en: v0.9.3

  • Devuelve: <string[]> Una matriz de los nombres de los algoritmos hash compatibles, 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) ​

Añadido en: v17.4.0

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

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

Añadido en: v21.7.0, v20.12.0

[Estable: 1 - Experimental]

Estable: 1 Estabilidad: 1.2 - Candidato a lanzamiento

Una utilidad para crear resúmenes hash de un solo uso de datos. Puede ser más rápido que el objeto basado en crypto.createHash() al hashear una cantidad menor de datos (<= 5 MB) que está fácilmente disponible. Si los datos pueden ser grandes o si se transmiten en secuencia, se recomienda seguir usando crypto.createHash().

El algorithm depende de los algoritmos disponibles compatibles con la versión de OpenSSL en la plataforma. Algunos ejemplos son 'sha256', 'sha512', etc. En 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))

// Codificar una cadena codificada en base64 en un Buffer, hashearlo y devolver
// el resultado como un buffer.
const base64 = 'Tm9kZS5qcw=='
// <Buffer 10 b3 49 32 87 f8 31 e8 1a 43 88 11 a1 ff ba 01 f8 ce c4 b7>
console.log(crypto.hash('sha1', Buffer.from(base64, 'base64'), 'buffer'))
js
import crypto from 'node:crypto'
import { Buffer } from 'node:buffer'

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

// Codificar una cadena codificada en base64 en un Buffer, hashearlo y devolver
// el resultado como un buffer.
const base64 = 'Tm9kZS5qcw=='
// <Buffer 10 b3 49 32 87 f8 31 e8 1a 43 88 11 a1 ff ba 01 f8 ce c4 b7>
console.log(crypto.hash('sha1', Buffer.from(base64, 'base64'), 'buffer'))

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

[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.
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 claves simple definida en RFC 5869. El ikm, salt e info proporcionados 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 se produce un error al derivar la clave, se establecerá err; de lo contrario, err será null. La derivedKey generada correctamente se pasará a la devolución de llamada como un <ArrayBuffer>. Se lanzará un error si alguno de los argumentos de entrada especifica valores o tipos inválidos.

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

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

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

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

[Historial]

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

Proporciona una función de derivación de claves HKDF sincrónica como se define en RFC 5869. Los ikm, salt e info proporcionados 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 una función de devolución de llamada invá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.
v14.0.0El parámetro iterations ahora está restringido a valores positivos. 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 está ahora en desuso 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 clave basada en contraseña 2 (PBKDF2). Se aplica un algoritmo de resumen HMAC seleccionado especificado por digest 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, err se establecerá; de lo contrario, err será null. De forma predeterminada, la derivedKey generada correctamente se pasará a la función de devolución de llamada como un Buffer. Se lanzará un error si alguno de los argumentos de entrada especifica valores o tipos inválidos.

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

La salt debe ser lo más única posible. Se recomienda que una salt sea aleatoria y tenga al menos 16 bytes de longitud. Consulte NIST SP 800-132 para obtener más detalles.

Al pasar cadenas para password o salt, tenga en cuenta las advertencias al usar cadenas como entradas para las API criptográficas.

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

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

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

Se puede recuperar una matriz de funciones de resumen compatibles utilizando crypto.getHashes().

Esta API utiliza el grupo de subprocesos de libuv, 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. Versiones anteriores trataban otros valores como uno.
v6.0.0Llamar a esta función sin pasar el parámetro digest está ahora 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.3Añadido en: v0.9.3

Proporciona una implementación sincrónica de la función de derivación de clave basada en contraseña 2 (PBKDF2). Se aplica un algoritmo de resumen HMAC seleccionado especificado por digest para derivar una clave de la longitud de byte 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.

La salt debe ser lo más única posible. Se recomienda que la sal sea aleatoria y tenga al menos 16 bytes de longitud. Consulte NIST SP 800-132 para obtener más detalles.

Al pasar cadenas para password o salt, tenga en cuenta las advertencias al usar cadenas como entradas para 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 obtener una matriz de funciones de resumen compatibles utilizando 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 cadena, ArrayBuffer y CryptoKey como tipos de clave permitidos. oaepLabel puede ser un ArrayBuffer. El búfer puede ser una cadena o un ArrayBuffer. Todos los tipos que aceptan búferes 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 clave.
v0.11.14Añadido 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, intentar utilizar RSA_PKCS1_PADDING producirá un error.

crypto.privateEncrypt(privateKey, buffer) ​

[Historial]

VersiónCambios
v15.0.0Se añadieron los tipos de clave string, ArrayBuffer y CryptoKey. La frase de contraseña puede ser un ArrayBuffer. El búfer puede ser una cadena o un 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 admite objetos clave.
v1.1.0Añadido en: v1.1.0

Cifra buffer con privateKey. Los datos devueltos se pueden descifrar utilizando la clave pública correspondiente, por ejemplo, utilizando 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 utiliza RSA_PKCS1_PADDING.

crypto.publicDecrypt(key, buffer) ​

[Historial]

VersiónCambios
v15.0.0Se agregaron los tipos de clave string, ArrayBuffer y CryptoKey permitidos. La frase de contraseña puede ser un ArrayBuffer. El búfer puede ser una cadena o un 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 admite objetos clave.
v1.1.0Añadido en: v1.1.0

Descifra buffer con key. 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.

Debido a 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 añadieron los tipos de clave string, ArrayBuffer y CryptoKey. oaepLabel y passphrase pueden ser ArrayBuffers. El buffer puede ser una cadena o un ArrayBuffer. Todos los tipos que aceptan buffers están limitados a un máximo de 2 ** 31 - 1 bytes.
v12.11.0Se añadió la opción oaepLabel.
v12.9.0Se añadió la opción oaepHash.
v11.6.0Esta función ahora admite objetos clave.
v0.11.14Añadido en: v0.11.14

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

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_OAEP_PADDING.

Debido a 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 una devolución de llamada inválida al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v9.0.0Pasar null como argumento callback ahora lanza ERR_INVALID_CALLBACK.
v0.5.8Añadido en: v0.5.8

Genera datos pseudorandom criptográficamente seguros. 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 se invoca la función callback con dos argumentos: err y buf. Si ocurre un error, err será un objeto Error; de lo contrario, es 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 nunca debería tardar más de unos pocos milisegundos. El único momento en que la generación de bytes aleatorios podría bloquearse durante un período de tiempo más largo es inmediatamente después del arranque, cuando todo el sistema todavía tiene poca entropía.

Esta API utiliza el threadpool de libuv, 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 de la longitud de la tarea del threadpool, divida 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 un callback inválido 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 pasarse como buffer.

Si bien esto incluye instancias de Float32Array y Float64Array, esta función no debe utilizarse para generar números de punto flotante aleatorios. El resultado puede contener +Infinity, -Infinity, y NaN, e incluso si el array contiene solo números finitos, no se extraen de una distribución aleatoria uniforme y no tienen límites inferior o superior 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, 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.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 del 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'))

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

// Lo anterior es equivalente a lo siguiente:
randomFillSync(buf, 5, 5)
console.log(buf.toString('hex'))

Cualquier instancia de ArrayBuffer, TypedArray o DataView puede pasarse 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 <entero> Inicio del rango aleatorio (inclusivo). Predeterminado: 0.
  • max <entero> Fin del rango aleatorio (exclusivo).
  • callback <Función> function(err, n) {}.

Devuelve un entero aleatorio n tal que min \<= n \< max. Esta implementación evita el sesgo del 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 argumento `min`
const { randomInt } = await import('node:crypto')

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

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

crypto.randomUUID([options]) ​

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

  • options <Object>

    • disableEntropyCache <boolean> De forma predeterminada, 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é, establezca disableEntropyCache en true. Predeterminado: false.

  • Devuelve: <string>

Genera un UUID versión 4 aleatorio RFC 4122. 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 devolución de llamada inválida al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v15.0.0Los argumentos de contraseña y sal 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 asincrónica de scrypt. Scrypt es una función de derivación de claves basada en contraseña que está diseñada para ser costosa computacional y de memoria con el fin de hacer que los ataques de fuerza bruta no sean rentables.

La salt debe ser lo más única posible. Se recomienda que una sal sea aleatoria y tenga al menos 16 bytes de longitud. Consulte NIST SP 800-132 para más detalles.

Al pasar cadenas para password o salt, tenga en cuenta las advertencias al usar cadenas como entradas para las API criptográficas.

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

Se lanza una excepción cuando cualquiera de los argumentos de entrada especifica valores o tipos invá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 maxmem ahora puede ser cualquier entero seguro.
v10.9.0Se han agregado los nombres de las opciones cost, blockSize y parallelization.
v10.5.0Añadido en: v10.5.0

Proporciona una implementación sincrónica de scrypt. Scrypt es una función de derivación de clave basada en contraseña que está diseñada para ser costosa computacional y en memoria para que los ataques de fuerza bruta no sean rentables.

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

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

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

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

js
const { scryptSync } = await import('node:crypto')
// Usando los valores predeterminados de fábrica.

const key1 = scryptSync('password', 'salt', 64)
console.log(key1.toString('hex')) // '3745e48...08d59ae'
// Usando un parámetro N personalizado. Debe ser una potencia de dos.
const key2 = scryptSync('password', 'salt', 64, { N: 1024 })
console.log(key2.toString('hex')) // '3745e48...aa39b34'
js
const { scryptSync } = require('node:crypto')
// Usando los valores predeterminados de fábrica.

const key1 = scryptSync('password', 'salt', 64)
console.log(key1.toString('hex')) // '3745e48...08d59ae'
// Usando un parámetro N personalizado. Debe ser una potencia de dos.
const key2 = scryptSync('password', 'salt', 64, { N: 1024 })
console.log(key2.toString('hex')) // '3745e48...aa39b34'

crypto.secureHeapUsed() ​

Añadido en: v15.6.0

  • Devuelve: <Object>
    • total <number> El tamaño total del montón seguro asignado, según lo especificado mediante el indicador de línea de comandos --secure-heap=n.
    • min <number> La asignación mínima del montón seguro, según lo especificado mediante el indicador de línea de comandos --secure-heap-min.
    • used <number> El número total de bytes asignados actualmente del montón seguro.
    • utilization <number> La razón calculada de used a total bytes asignados.

crypto.setEngine(engine[, flags]) ​

[Historial]

VersiónCambios
v22.4.0, v20.16.0El soporte de motor personalizado en OpenSSL 3 está en desuso.
v0.11.11Añadido en: v0.11.11

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

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

El argumento flags opcional usa ENGINE_METHOD_ALL por defecto. flags es 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) ​

Añadido 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 devolución de llamada inválida al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v15.12.0Se añadió el argumento de devolución de llamada opcional.
v13.2.0, v12.16.0Esta función ahora admite firmas DSA y ECDSA IEEE-P1363.
v12.0.0Añadido en: v12.0.0

Calcula y devuelve la firma para data usando 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 hubiera sido 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): Codificación de estructura de firma ASN.1 codificada en DER (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 usada para firmar el mensaje como se especifica en la sección 3.1 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) lo establece en el valor máximo permitido.

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

crypto.subtle ​

Añadido 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.0Añadido en: v6.6.0

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

Esta función no filtra la 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 Buffer, TypedArray o DataView, y deben tener la misma longitud de bytes. Se lanza un error si a y b tienen longitudes de bytes diferentes.

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 Float32Array o Float64Array, esta función puede devolver resultados inesperados debido a la codificación IEEE 754 de números de punto flotante. En particular, ni x === y ni Object.is(x, y) implican que las representaciones de bytes de dos números de punto flotante x e y sean iguales.

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

crypto.verify(algorithm, data, key, signature[, 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.
v15.12.0Se agregó el argumento de devolución de llamada opcional.
v15.0.0Los argumentos de datos, clave y firma también pueden ser ArrayBuffer.
v13.2.0, v12.16.0Esta función ahora admite firmas IEEE-P1363 DSA y ECDSA.
v12.0.0Añadido en: v12.0.0

Verifica la firma dada para data usando 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 hubiera sido 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): Codificación de estructura de firma ASN.1 codificada en DER (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.

  • saltLength <integer> Longitud de 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) lo establece en el valor máximo permitido.

El argumento signature es la firma calculada previamente para data.

Debido a que las claves públicas se pueden derivar 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 grupo de subprocesos de libuv.

crypto.webcrypto ​

Añadido en: v15.0.0

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

Consulte la documentación de la API Web Crypto 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. Estos casos incluyen textos sin cifrar, textos cifrados, claves simétricas, vectores de inicialización, frases de contraseña, sales, etiquetas de autenticación y datos autenticados adicionales.

Al pasar cadenas a las API criptográficas, considere 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 de bytes aleatoria o pseudorandom de n bytes. Por ejemplo, ninguna cadena UTF-8 resultará en la secuencia de bytes c0 af. Las claves secretas deben ser casi exclusivamente secuencias de bytes aleatorias o pseudorandom.
  • De manera similar, al convertir secuencias de bytes aleatorias o pseudorandom 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). Por lo tanto, la representación en bytes de la cadena Unicode resultante puede no ser igual a la secuencia de bytes a partir de la cual se creó la cadena. Los resultados de los cifrados, funciones hash, algoritmos de firma y funciones de derivación de claves son secuencias de bytes pseudorandom y no deben usarse como cadenas Unicode.
  • Cuando las cadenas se obtienen de la entrada del usuario, algunos caracteres Unicode pueden representarse de varias maneras equivalentes que dan como resultado diferentes secuencias de bytes. Por ejemplo, al pasar una frase de 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 el uso de String.prototype.normalize() en las entradas del usuario antes de pasarlas a las API criptográficas.

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

El módulo Crypto se agregó a Node.js antes de que existiera el concepto de una API de transmisión unificada, y antes de que hubiera objetos Buffer para manejar datos binarios. Como tal, muchas clases crypto tienen métodos que no se encuentran típicamente en otras clases de Node.js que implementan la API de transmisiones (por ejemplo, update(), final() o digest()). Además, muchos métodos aceptaban y devolvían cadenas codificadas en 'latin1' de forma predeterminada en lugar de Buffer. Este valor predeterminado se cambió después de Node.js v0.8 para usar objetos Buffer de forma predeterminada.

Soporte para algoritmos débiles o comprometidos ​

El módulo node:crypto todavía admite algunos algoritmos que ya están comprometidos y no se recomiendan para 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.

Según las recomendaciones de NIST SP 800-131A:

  • MD5 y SHA-1 ya no son aceptables cuando se requiere resistencia a colisiones, 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 que sea segura durante varios años.
  • Los grupos DH de modp1, modp2 y modp5 tienen un tamaño de clave inferior a 2048 bits y no se recomiendan.

Consulte la referencia para obtener otras recomendaciones y detalles.

Algunos algoritmos que tienen debilidades conocidas y poca relevancia en la práctica solo están disponibles a través del proveedor heredado, que no está habilitado de forma predeterminada.

Modo CCM ​

CCM es uno de los algoritmos AEAD compatibles Algoritmos AEAD. Las aplicaciones que utilizan este modo deben cumplir 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 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 mediante setAuthTag() antes de llamar a update(). De lo contrario, el descifrado fallará y final() arrojará un error de acuerdo con 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 fragmento 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 siempre es 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()

// Ahora transmite { 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()

// Ahora transmite { 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 admite FIPS 140-2 cuando se utiliza con un proveedor OpenSSL 3 adecuado, como el proveedor FIPS de OpenSSL 3, que se puede instalar siguiendo las instrucciones del archivo README de FIPS de OpenSSL.

Para la compatibilidad con 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 ejemplo de archivo de configuración tiene este aspecto:

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}
# archivo 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

Configure 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 biblioteca openssl>/ossl-modules

El modo FIPS se puede habilitar en Node.js mediante:

  • Iniciar Node.js con los indicadores de línea de comandos --enable-fips o --force-fips.
  • Llamar mediante programación 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}
# archivo 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 indicadores SSL OP para obtener más 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 obtener más detalles.
SSL_OP_ALLOW_NO_DHE_KEXIndica a OpenSSL que permita un modo de intercambio de claves que no sea 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 utilizar 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 utilice 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 de saludo del servidor de una versión anterior 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 la compatibilidad con la compresión SSL/TLS.
SSL_OP_NO_ENCRYPT_THEN_MACIndica a OpenSSL que deshabilite el cifrado-entonces-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 una 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 hace. Esta opción no tiene efecto si no está habilitada SSL_OP_CIPHER_SERVER_PREFERENCE.
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 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 criptográficas de Node.js ​

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