Uso

PrivateKey y PublicKey

Maneja llaves privadas (.key) y públicas (.pem) para firmar datos, verificar firmas y cambiar contraseñas.

Además de trabajar a través de Credential, puedes utilizar las clases PrivateKey y PublicKey de manera individual.

PrivateKey (Llave privada)

La clase PrivateKey soporta los siguientes formatos de entrada:

  • PKCS#8 DER (el archivo .key binario cifrado tal como lo entrega el SAT, o sin cifrar).
  • PKCS#8 PEM (-----BEGIN ENCRYPTED PRIVATE KEY----- o -----BEGIN PRIVATE KEY-----).
  • PKCS#5 PEM (-----BEGIN RSA PRIVATE KEY-----, tanto plano como protegido con encabezados Proc-Type y DEK-Info).

Abrir una llave privada

Si la llave privada no tiene contraseña (está desencriptada), pasa una cadena vacía '' como passPhrase.

import { openPrivateKeyFile } from '@nodecfdi/credentials/node';

const privateKey = openPrivateKeyFile('/ruta/a/la/llave.key', '12345678a');

Firmar datos con PrivateKey

El método sign(data, algorithm?) firma una cadena no vacía usando 'sha256' por defecto (o cualquier algoritmo válido en Algorithm) y devuelve la firma como cadena binaria:

private-key-sign.ts
import { Buffer } from 'node:buffer';

const signatureBinary = privateKey.sign('Cadena original a firmar', 'sha256');
const signatureBase64 = Buffer.from(signatureBinary, 'binary').toString('base64');
Si intentas firmar una cadena vacía (""), sign() lanzará el error Error: Cannot sign data: empty signature.

Verificar pertenencia a un certificado

Puedes comprobar si una llave privada corresponde a un objeto Certificate o a un certificado en texto PEM comparando sus módulos y exponentes RSA (n y e):

belongs-to.ts
// Contra una instancia de Certificate
const matchesCert = privateKey.belongsTo(certificate);

// Contra una cadena PEM de certificado
const matchesPem = privateKey.belongsToPEMCertificate(certificate.pem());

Cambiar o eliminar la contraseña (changePassPhrase)

El método changePassPhrase(newPassPhrase) genera una nueva instancia de PrivateKey en formato PKCS#8 PEM protegida con la nueva contraseña. Si pasas una cadena vacía '', genera una llave privada PKCS#8 PEM sin cifrar:

change-passphrase.ts
// Recifrar con una nueva contraseña
const reEncryptedKey = privateKey.changePassPhrase('NuevaContraseñaSegura123');
console.log(reEncryptedKey.pem()); // -----BEGIN ENCRYPTED PRIVATE KEY----- ...

// Quitar la contraseña (llave en texto plano)
const plainKey = privateKey.changePassPhrase('');
console.log(plainKey.pem()); // -----BEGIN PRIVATE KEY----- ...

Otros métodos de PrivateKey

Método / PropiedadRetornoDescripción
pem()stringContenido PEM de la llave privada.
passPhrase()stringContraseña utilizada al abrir la llave privada.
publicKey()PublicKeyObtiene la instancia PublicKey derivada de la llave privada.
publicKeyContents()stringContenido PEM de la llave pública asociada.
numberOfBits()numberLongitud en bits del módulo RSA (ej. 2048).
typeKeyTypeEnumTipo de llave (privateKey.type.isRSA()).
isType(type)booleanComprueba el tipo de llave (ej. privateKey.isType('RSA')).
callOnPrivateKey(fn)TEjecuta un callback recibiendo el objeto forge.pki.rsa.PrivateKey desencriptado (cacheado tras la primera apertura).
PrivateKey.convertDerToPem(contents, isEncrypted)stringConvierte contenido PKCS#8 DER binario a PKCS#8 PEM.

PublicKey (Llave pública)

La clase PublicKey representa una llave pública RSA. Puede construirse a partir de un archivo/texto PEM de llave pública (-----BEGIN PUBLIC KEY-----) o directamente desde el PEM de un certificado X.509 (-----BEGIN CERTIFICATE-----), o bien obtenerse desde certificate.publicKey() o privateKey.publicKey().

Abrir una llave pública

import { openPublicKeyFile } from '@nodecfdi/credentials/node';

const publicKey = openPublicKeyFile('/ruta/a/public_key.pem');

Verificar una firma con PublicKey

El método verify(data, signature, algorithm?) recibe el texto original, la firma como cadena binaria y el algoritmo ('sha256' por defecto):

public-key-verify.ts
import { Buffer } from 'node:buffer';

const signatureBinary = Buffer.from(signatureBase64, 'base64').toString('binary');
const isValid = publicKey.verify('Cadena original a firmar', signatureBinary, 'sha256');

console.log('¿Es válida?:', isValid);

Otros métodos de PublicKey

Método / PropiedadRetornoDescripción
publicKeyContents()stringContenido PEM de la llave pública (-----BEGIN PUBLIC KEY-----).
numberOfBits()numberNúmero de bits de la llave RSA (ej. 2048).
typeKeyTypeEnumTipo de llave (publicKey.type.isRSA()).
isType(type)booleanComprueba si la llave es del tipo indicado ('RSA').
callOnPublicKey(fn)TEjecuta un callback recibiendo la instancia forge.pki.rsa.PublicKey.