Security

Visión general

Esta página cubre contraseñas, cifrado y firmas digitales. Document.OpenFile() / Document.Open() aceptan una contraseña para abrir un documento protegido, Document.Save() acepta una opción encrypt para proteger uno, y Document.Sign() / Document.Certify() / Document.VerifySignatures() añaden y verifican firmas digitales.


Abrir y descifrar documentos protegidos con contraseña

Pase { password: '...' } a Document.OpenFile() o Document.Open() para abrir un documento protegido con una contraseña de usuario. Si la contraseña falta o es incorrecta, la llamada lanza InvalidPasswordError.

import { Document, InvalidPasswordError } from '@asposefoss/pdf';

try {
  const doc = Document.OpenFile('secret.pdf', { password: 'hunter2' });
  doc.WriteTo('decrypted.pdf');    // output is plaintext
} catch (e) {
  if (e instanceof InvalidPasswordError) console.error('wrong password');
  else throw e;
}

Cifrado al guardar

Document.Save() (y Document.WriteTo()) aceptan una opción encrypt. El cifrado basado en contraseña es el caso más común; la biblioteca también admite cifrado de clave pública a uno o más certificados de destinatario, que se abre nuevamente con la clave privada del destinatario.

// Encrypt to one or more recipient certificates (PEM string or DER bytes):
const bytes = doc.Save({
  encrypt: {
    recipients: [{ certificate: recipientCertPem }],
    algorithm: 'aes256',                 // 'aes256' (default) | 'aes128' | 'rc4'
    permissions: { copying: false },     // shared across all recipients
  },
});

// Open with the recipient's private key + certificate, or a PKCS#12 bundle:
const opened = Document.Open(bytes, {
  recipient: { privateKey, certificate: recipientCertPem },
});
console.log(opened.Permissions);         // recovered permission flags (not enforced)

Firmado y certificación

Document.Certify() agrega una firma de certificación (autor) que lleva una DocMDP transformación que declara qué cambios posteriores están permitidos; Document.Sign() agrega una firma de aprobación ordinaria adicional que puede añadirse incrementalmente encima. Ambas toman un firmante { certificate, privateKey } y un objeto de opciones (reason, location, name, fieldName, y — para Certify() — permissions).

const certifying = Document.OpenFile('report.pdf');
await certifying.Certify(
  { certificate: author.certificate, privateKey: author.privateKey },
  { permissions: 'form-fill', reason: 'Certifying the report', fieldName: 'Certification' },
);
const certifiedBytes = certifying.Save();

const approving = Document.Open(certifiedBytes);
await approving.Sign(
  { certificate: approver.certificate, privateKey: approver.privateKey },
  { reason: 'Approved for publication', fieldName: 'Approval' },
);
approving.WriteTo('signed.pdf');

Verificando firmas

Document.VerifySignatures() verifica cada firma en el documento: recalcula cada resumen /ByteRange, verifica el CMS separado y reporta qué cambió después de cada firma. Devuelve un SignatureReport[], una entrada por firma.

const reports = await Document.OpenFile('signed.pdf').VerifySignatures();
for (const r of reports) {
  console.log(r.name, 'integrity:', r.integrity, 'signature:', r.signature);
}

Consejos y mejores prácticas

  • Captura InvalidPasswordError específicamente antes de un manejo más amplio al abrir entradas no confiables, de modo que puedas reaccionar de forma distinta a una contraseña incorrecta que a un archivo corrupto.
  • Llama a Certify() antes de cualquier llamada a Sign() — una firma de certificación establece los permisos DocMDP sobre los que se superponen las firmas de aprobación posteriores.
  • Document.Open() devuelve Permissions recuperados después de la descifrado con clave pública, pero la biblioteca no los impone por sí misma — trátalos como informativos.
  • VerifySignatures() es async — awaitlo (o maneja el Promise devuelto) antes de leer la matriz de informes.

Problemas comunes

ProblemaCausaSolución
Document.OpenFile() / Document.Open() lanza InvalidPasswordErrorEl documento está protegido con contraseña y no se proporcionó ninguna contraseña, o se proporcionó una incorrectaPase { password: '...' } a Document.OpenFile() / Document.Open()
Falla el descifrado con clave públicaSe pasó la clave privada o certificado incorrecto, o ninguno coincide con cualquier entrada recipients utilizada en el momento del cifradoConfirme que la opción recipient tenga su privateKey / certificate (o paquete PKCS#12) coincida con uno de los destinatarios originales
Una firma de aprobación invalida la certificaciónSe llamó a Sign() con permisos que la transformación certificadora DocMDP no permiteEstablezca un valor permissions en Certify() (e.g. 'form-fill') lo suficientemente amplio para los cambios que harán los firmantes posteriores
VerifySignatures() informa una verificación de integridad fallidaLos bytes firmados fueron modificados después de la firma, fuera de una actualización incremental que cubre la firmaVuelva a firmar el documento después de cualquier edición adicional

FAQ

¿Cuál es la diferencia entre Sign y Certify?

Certify() agrega la primera firma de certificación y declara (mediante una transformación DocMDP) qué cambios posteriores están permitidos. Sign() agrega una firma de aprobación ordinaria, añadida de forma incremental sobre lo que ya estaba.

¿Cómo abro un PDF protegido con contraseña?

Pase { password: '...' } a Document.OpenFile() o Document.Open(), y capture InvalidPasswordError si la contraseña podría estar equivocada.

¿Esta biblioteca hace cumplir las banderas de permisos PDF?

No. Document.Open() recupera las banderas Permissions de un documento cifrado para que las inspecciones, pero no restringe lo que tu código puede hacer con el documento abierto.

¿Cómo puedo comprobar si las firmas de un PDF firmado siguen siendo válidas?

Llame a Document.VerifySignatures() (un método async) e inspeccione los campos integrity y signature de cada SignatureReport devuelto.


API Reference Resumen

Clase/MétodoDescripción
Document.OpenFile() / Document.Open()Abrir un documento, opcionalmente protegido con contraseña o clave pública
InvalidPasswordErrorLanzado cuando falta una contraseña o es incorrecta
Document.Save() / Document.WriteTo()Guardar un documento, opcionalmente con una opción encrypt
PermissionsBanderas de permiso recuperadas de un documento cifrado
Document.Certify()Agregar una firma de certificación (autor) con una transformación DocMDP
Document.Sign()Agregar una firma de aprobación
Document.VerifySignatures()Verificar cada firma en el documento
SignatureReportResultado de la verificación de una firma: name, integrity, signature

Ver también

 Español