PrivateKey y PublicKey
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
.keybinario 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 encabezadosProc-TypeyDEK-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');
import { PrivateKey } from '@nodecfdi/credentials';
const privateKey = new PrivateKey(keyContents, '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:
import { Buffer } from 'node:buffer';
const signatureBinary = privateKey.sign('Cadena original a firmar', 'sha256');
const signatureBase64 = Buffer.from(signatureBinary, 'binary').toString('base64');
""), 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):
// 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:
// 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 / Propiedad | Retorno | Descripción |
|---|---|---|
pem() | string | Contenido PEM de la llave privada. |
passPhrase() | string | Contraseña utilizada al abrir la llave privada. |
publicKey() | PublicKey | Obtiene la instancia PublicKey derivada de la llave privada. |
publicKeyContents() | string | Contenido PEM de la llave pública asociada. |
numberOfBits() | number | Longitud en bits del módulo RSA (ej. 2048). |
type | KeyTypeEnum | Tipo de llave (privateKey.type.isRSA()). |
isType(type) | boolean | Comprueba el tipo de llave (ej. privateKey.isType('RSA')). |
callOnPrivateKey(fn) | T | Ejecuta un callback recibiendo el objeto forge.pki.rsa.PrivateKey desencriptado (cacheado tras la primera apertura). |
PrivateKey.convertDerToPem(contents, isEncrypted) | string | Convierte 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');
import { PublicKey } from '@nodecfdi/credentials';
// Desde texto PEM (PUBLIC KEY o CERTIFICATE)
const publicKey = new PublicKey(publicKeyOrCertPem);
// O desde un Certificate / PrivateKey ya cargado:
const pubFromCert = certificate.publicKey();
const pubFromPriv = privateKey.publicKey();
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):
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 / Propiedad | Retorno | Descripción |
|---|---|---|
publicKeyContents() | string | Contenido PEM de la llave pública (-----BEGIN PUBLIC KEY-----). |
numberOfBits() | number | Número de bits de la llave RSA (ej. 2048). |
type | KeyTypeEnum | Tipo de llave (publicKey.type.isRSA()). |
isType(type) | boolean | Comprueba si la llave es del tipo indicado ('RSA'). |
callOnPublicKey(fn) | T | Ejecuta un callback recibiendo la instancia forge.pki.rsa.PublicKey. |
