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 apeluri Sign() — o semnătură de certificare stabilește permisiunile DocMDP pe care semnăturile de aprobare ulterioare le stratifică.
  • Document.Open() returnează Permissions recuperate după decriptarea cu cheie publică, dar biblioteca nu le impune în mod propriu — tratează-le ca informaționale.
  • VerifySignatures() este async — await (sau gestionează Promise returnat) înainte de a citi matricea de rapoarte.

Probleme comune

ProblemăCauzăRemediere
Document.OpenFile() / Document.Open() aruncă InvalidPasswordErrorDocumentul 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ăriiConfirmați că opțiunea recipient are privateKey / certificate (sau pachetul PKCS#12) corespunde unuia dintre destinatarii originali
O semnătură de aprobare invalidează certificareaSign() a fost apelat cu permisiuni pe care transformarea de certificare DocMDP nu le permiteSetaț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ă
InvalidPasswordErrorAruncat când o parolă lipsește sau este greșită
Document.Save() / Document.WriteTo()Salvează un document, opțional cu o opțiune encrypt
PermissionsSteaguri 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
SignatureReportRezultatul verificării unei semnături: name, integrity, signature

Vezi și:

 Română