Security
Vue d’ensemble
Cette page couvre les mots de passe, le chiffrement et les signatures numériques. Document.OpenFile() / Document.Open() acceptent un mot de passe pour ouvrir un document protégé, Document.Save() accepte une option encrypt pour en protéger un, et Document.Sign() / Document.Certify() / Document.VerifySignatures() ajoutent et vérifient les signatures numériques.
Ouverture et déchiffrement de documents protégés par mot de passe
Passez { password: '...' } à Document.OpenFile() ou Document.Open() pour ouvrir un document protégé par un mot de passe utilisateur. Si le mot de passe est manquant ou incorrect, l’appel lève 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;
}Chiffrement lors de l’enregistrement
Document.Save() (et Document.WriteTo()) acceptent une option encrypt. Le chiffrement basé sur un mot de passe est le cas le plus courant; la bibliothèque prend également en charge le chiffrement à clé publique vers un ou plusieurs certificats de destinataire, qui sont de nouveau ouverts avec la clé privée du destinataire.
// 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)
Signature et certification
Document.Certify() ajoute une signature de certification (auteur) portant une transformation DocMDP qui indique quels changements ultérieurs sont autorisés; Document.Sign() ajoute une signature d’approbation ordinaire supplémentaire qui peut être ajoutée de façon incrémentielle par-dessus. Les deux acceptent un signataire { certificate, privateKey } et un objet d’options (reason, location, name, fieldName, et — pour 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');Vérification des signatures
Document.VerifySignatures() vérifie chaque signature du document: il recompute chaque empreinte /ByteRange, vérifie le CMS détaché, et rapporte ce qui a changé après chaque signature. Il renvoie un SignatureReport[], une entrée par signature.
const reports = await Document.OpenFile('signed.pdf').VerifySignatures();
for (const r of reports) {
console.log(r.name, 'integrity:', r.integrity, 'signature:', r.signature);
}Conseils et bonnes pratiques
- Capturez
InvalidPasswordErrorspécifiquement avant un bloc catch-all plus large lors de l’ouverture d’une entrée non fiable, afin de pouvoir réagir différemment à un mot de passe incorrect qu’à un fichier corrompu. - Appelez
Certify()avant tout appel àSign()— une signature de certification établit les permissions DocMDP sur lesquelles les signatures d’approbation ultérieures sont superposées. Document.Open()renvoie lesPermissionsrécupérés après le déchiffrement à clé publique, mais la bibliothèque ne les impose pas elle-même — considérez-les comme purement informatifs.VerifySignatures()estasync—await-le (ou gérez lePromiseretourné) avant de lire le tableau de rapports.
Problèmes courants
| Problème | Cause | Correction |
|---|---|---|
Document.OpenFile() / Document.Open() lance InvalidPasswordError | Le document est protégé par mot de passe et aucun mot de passe, ou le mauvais, n’a été fourni. | Passez { password: '...' } à Document.OpenFile() / Document.Open() |
| Le déchiffrement à clé publique échoue | La mauvaise clé privée ou le mauvais certificat a été fourni, ou aucun des deux ne correspond à une entrée recipients utilisée lors du chiffrement. | Confirmez que l’option recipient privateKey / certificate (ou le bundle PKCS#12) correspond à l’un des destinataires d’origine |
| Une signature d’approbation invalide la certification | Sign() a été appelé avec des autorisations que la transformation de certification DocMDP n’autorise pas | Définissez une valeur permissions sur Certify() (p. ex. 'form-fill') suffisamment large pour les changements que les signataires ultérieurs apporteront |
VerifySignatures() signale une vérification d’intégrité échouée | Les octets signés ont été modifiés après la signature, en dehors d’une mise à jour incrémentielle couverte par la signature | Resignez le document après toute modification supplémentaire |
FAQ
Quelle est la différence entre Sign et Certify?
Certify() ajoute la première signature de certification et déclare (via une transformation DocMDP) quels changements ultérieurs sont autorisés. Sign() ajoute une signature d’approbation ordinaire, ajoutée de façon incrémentielle au-dessus de tout ce qui précède.
Comment ouvrir un PDF protégé par mot de passe?
Passez { password: '...' } à Document.OpenFile() ou Document.Open(), et attrapez InvalidPasswordError si le mot de passe pourrait être incorrect.
Cette bibliothèque impose-t-elle les drapeaux d’autorisation PDF?
Non. Document.Open() récupère les drapeaux Permissions d’un document chiffré pour que vous les inspectiez, mais ne restreint pas lui-même ce que votre code peut faire avec le document ouvert.
Comment vérifier si les signatures d’un PDF signé sont toujours valides?
Appelez Document.VerifySignatures() (une méthode async) et inspectez les champs integrity et signature de chaque SignatureReport retourné.
API Reference Résumé
| Classe/Méthode | Description |
|---|---|
Document.OpenFile() / Document.Open() | Ouvrir un document, éventuellement protégé par mot de passe ou par clé publique |
InvalidPasswordError | Lancée lorsque le mot de passe est absent ou incorrect |
Document.Save() / Document.WriteTo() | Enregistrer un document, éventuellement avec une option encrypt |
Permissions | Drapeaux d’autorisation récupérés d’un document chiffré |
Document.Certify() | Ajouter une signature de certification (auteur) avec une transformation DocMDP |
Document.Sign() | Ajouter une signature d’approbation |
Document.VerifySignatures() | Vérifier chaque signature du document |
SignatureReport | Résultat de la vérification d’une signature: name, integrity, signature |