Security
Prezentare generală
Această pagină acoperă parolele, criptarea și semnăturile digitale. Document.OpenFile() / Document.Open() acceptă o parolă pentru a deschide un document protejat, Document.Save() acceptă o opțiune encrypt pentru a proteja unul, și Document.Sign() / Document.Certify() / Document.VerifySignatures() adaugă și verifică semnăturile digitale.
Deschiderea și decriptarea documentelor protejate prin parolă
Transmite { password: '...' } către Document.OpenFile() sau Document.Open() pentru a deschide un document protejat cu o parolă de utilizator. Dacă parola lipsește sau este incorectă, apelul aruncă 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;
}Criptare la salvare
Document.Save() (și Document.WriteTo()) acceptă o opțiune encrypt. Criptarea bazată pe parolă este cazul comun; biblioteca suportă, de asemenea, criptarea cu cheie publică către unul sau mai multe certificate de destinatar, deschise din nou cu cheia privată a destinatarului.
// 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)
Semnare și certificare
Document.Certify() adaugă o semnătură de certificare (autor) care conține o transformare DocMDP ce declară ce modificări ulterioare sunt permise; Document.Sign() adaugă o semnătură de aprobare obișnuită suplimentară care poate fi atașată incremental deasupra. Ambele primesc un semnatar { certificate, privateKey } și un obiect de opțiuni (reason, location, name, fieldName, și — pentru 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');Verificarea semnăturilor
Document.VerifySignatures() verifică fiecare semnătură din document: recalculează fiecare rezumat /ByteRange, verifică CMS-ul detașat și raportează ce s-a schimbat după fiecare semnătură. Returnează un SignatureReport[], câte o intrare pentru fiecare semnătură.
const reports = await Document.OpenFile('signed.pdf').VerifySignatures();
for (const r of reports) {
console.log(r.name, 'integrity:', r.integrity, 'signature:', r.signature);
}Sfaturi și bune practici
- Prinde
InvalidPasswordErrorîn mod specific înainte de un bloc catch-all mai larg când deschizi intrări neîncredere, astfel încât să poți reacționa diferit la o parolă greșită decât la un fișier corupt. - Apelează
Certify()înainte de orice apeluriSign()— o semnătură de certificare stabilește permisiunile DocMDP pe care semnăturile de aprobare ulterioare le stratifică. Document.Open()returneazăPermissionsrecuperate după decriptarea cu cheie publică, dar biblioteca nu le impune în mod propriu — tratează-le ca informaționale.VerifySignatures()esteasync—await(sau gestioneazăPromisereturnat) înainte de a citi matricea de rapoarte.
Probleme comune
| Problemă | Cauză | Remediere |
|---|---|---|
Document.OpenFile() / Document.Open() aruncă InvalidPasswordError | Documentul este protejat prin parolă și nu a fost furnizată nicio parolă, sau a fost furnizată una greșită | Transmite { password: '...' } către Document.OpenFile() / Document.Open() |
| Decriptarea cu cheie publică eșuează | A fost transmisă cheia privată sau certificatul greșit, sau niciunul nu corespunde vreunei intrări recipients utilizate în timpul criptării | Confirmați că opțiunea recipient are privateKey / certificate (sau pachetul PKCS#12) corespunde unuia dintre destinatarii originali |
| O semnătură de aprobare invalidează certificarea | Sign() a fost apelat cu permisiuni pe care transformarea de certificare DocMDP nu le permite | Setați o valoare permissions pe Certify() (de exemplu 'form-fill') suficient de largă pentru modificările pe care le vor face semnatarii ulteriori |
VerifySignatures() raportează o verificare a integrității defectuoasă | Octeții semnați au fost modificați după semnare, în afara unei actualizări incrementale pe care semnătura o acoperă | Semnați din nou documentul după orice alte editări |
FAQ
Care este diferența dintre Sign și Certify?
Certify() adaugă prima semnătură de certificare și declară (printr-o transformare DocMDP) ce modificări ulterioare sunt permise. Sign() adaugă o semnătură obișnuită de aprobare, atașată incremental peste tot ce a venit înainte.
Cum pot deschide un PDF protejat prin parolă?
Transmite { password: '...' } către Document.OpenFile() sau Document.Open() și prinde InvalidPasswordError dacă parola ar putea fi greșită.
Această bibliotecă impune steagurile de permisiune PDF?
Nu. Document.Open() recuperează steagurile Permissions dintr-un document criptat pentru a le inspecta, dar nu restricționează în sine ce poate face codul tău cu documentul deschis.
Cum pot verifica dacă semnăturile unui PDF semnat sunt încă valide?
Apelă Document.VerifySignatures() (o metodă async) și inspectează câmpurile integrity și signature ale fiecărui SignatureReport returnat.
API Reference Rezumat
| Clasă/Metodă | Descriere: |
|---|---|
Document.OpenFile() / Document.Open() | Deschide un document, opțional protejat prin parolă sau cheie publică |
InvalidPasswordError | Aruncat când o parolă lipsește sau este greșită |
Document.Save() / Document.WriteTo() | Salvează un document, opțional cu o opțiune encrypt |
Permissions | Steaguri de permisiune recuperate dintr-un document criptat |
Document.Certify() | Adaugă o semnătură de certificare (autor) cu o transformare DocMDP |
Document.Sign() | Adaugă o semnătură de aprobare |
Document.VerifySignatures() | Verifică fiecare semnătură din document |
SignatureReport | Rezultatul verificării unei semnături: name, integrity, signature |