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
InvalidPasswordErrorespecí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 aSign()— una firma de certificación establece los permisos DocMDP sobre los que se superponen las firmas de aprobación posteriores. Document.Open()devuelvePermissionsrecuperados después de la descifrado con clave pública, pero la biblioteca no los impone por sí misma — trátalos como informativos.VerifySignatures()esasync—awaitlo (o maneja elPromisedevuelto) antes de leer la matriz de informes.
Problemas comunes
| Problema | Causa | Solución |
|---|---|---|
Document.OpenFile() / Document.Open() lanza InvalidPasswordError | El documento está protegido con contraseña y no se proporcionó ninguna contraseña, o se proporcionó una incorrecta | Pase { password: '...' } a Document.OpenFile() / Document.Open() |
| Falla el descifrado con clave pública | Se pasó la clave privada o certificado incorrecto, o ninguno coincide con cualquier entrada recipients utilizada en el momento del cifrado | Confirme 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ón | Se llamó a Sign() con permisos que la transformación certificadora DocMDP no permite | Establezca 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 fallida | Los bytes firmados fueron modificados después de la firma, fuera de una actualización incremental que cubre la firma | Vuelva 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étodo | Descripción |
|---|---|
Document.OpenFile() / Document.Open() | Abrir un documento, opcionalmente protegido con contraseña o clave pública |
InvalidPasswordError | Lanzado cuando falta una contraseña o es incorrecta |
Document.Save() / Document.WriteTo() | Guardar un documento, opcionalmente con una opción encrypt |
Permissions | Banderas 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 |
SignatureReport | Resultado de la verificación de una firma: name, integrity, signature |