Cum să securizați și să semnați documente PDF în TypeScript

Acest ghid arată cum să criptați, să certificați, să semnați și să verificați documente PDF cu Aspose.PDF FOSS pentru TypeScript. Document.Save() și Document.Open() gestionează criptarea cu cheie publică către certificatele destinatarului, în timp ce Document.Certify(), Document.Sign() și Document.VerifySignatures() gestionează semnăturile digitale în stil PAdES. Necesită Node.js 22 sau o versiune ulterioară.

Ghid pas cu pas

Pasul 1: Instalați pachetul

git clone https://github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-TypeScript.git
cd Aspose.PDF-FOSS-for-TypeScript
npm install
npm run build

Verificați instalarea importând clasa Document într-un nou fișier TypeScript — această linie ar trebui să se rezolve fără eroare odată ce pachetul este instalat:

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

Pasul 2: Importați clasele necesare

Importă Document pentru a deschide, salva, semna și verifica fișierul; pașii de semnare și criptare de mai jos transmit obiecte de opțiuni simple, astfel încât nu mai sunt necesare alte importuri:

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

Pasul 3: Criptarea unui document pentru certificatele destinatarului

Document.Save() acceptă o opțiune encrypt care conține unul sau mai multe recipients, fiecare identificat printr-un certificat (șir PEM sau octeți DER), un algorithm, și permissions partajate:

const doc = Document.OpenFile('report.pdf');

const bytes = doc.Save({
  encrypt: {
    recipients: [{ certificate: recipientCertPem }],
    algorithm: 'aes256', // 'aes256' (default) | 'aes128' | 'rc4'
    permissions: { copying: false }, // shared across all recipients
  },
});

Pasul 4: Deschiderea unui document criptat

Transmite o opțiune recipient către Document.Open() cu fie cheia privată și certificatul corespunzător, fie un pachet PKCS#12:

const opened = Document.Open(bytes, {
  recipient: { privateKey, certificate: recipientCertPem },
  // or: recipient: { pkcs12: p12Bytes, passphrase: '…' },
});

console.log(opened.Permissions); // recovered permission flags (not enforced)

Pasul 5: Certificarea și semnarea unui document

Document.Certify() și Document.Sign() sunt ambele asincrone și primesc o identitate (certificate + privateKey) plus opțiuni care descriu câmpul de semnătură, aspectul și motivul. Certificarea ar trebui să aibă loc prima, asupra întregului fișier; semnăturile de aprobare suplimentare sunt adăugate incremental ulterior:

async function certifyAndSign(sourcePath: string, signaturePageIndex: number): Promise<void> {
  const certifying = Document.OpenFile(sourcePath);
  await certifying.Certify(
    { certificate: authorCert, privateKey: authorKey },
    {
      permissions: 'form-fill',
      reason: 'Certifying the document',
      fieldName: 'Certification',
      appearance: { page: signaturePageIndex, rect: [400, 100, 550, 140] },
    },
  );
  const certifiedBytes = certifying.Save();

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

Pasul 6: Verificarea semnăturilor

Document.VerifySignatures() este asincron și returnează un SignatureReport pentru fiecare câmp de semnătură, fiecare raportând integrity criptografic, validitatea signature, și dacă coversWholeFile:

async function verify(path: string): Promise<void> {
  const doc = Document.OpenFile(path);
  const reports = await doc.VerifySignatures();
  for (const r of reports) {
    console.log(`${r.name}: integrity=${r.integrity} signature=${r.signature} `
      + `coversWholeFile=${r.coversWholeFile} docMDP=${r.docMDP}`);
  }
}

Probleme comune și soluții

Document.Sign() / Document.Certify() aruncă sau blochează. Ambele sunt asincrone — await apelul. Uitând await lasă promisiunea returnată nerezolvată și scrierea se întâmplă înainte ca semnarea să se finalizeze.

O semnătură de aprobare ulterioară invalidează certificarea. Semnați incremental: salvați mai întâi octeții certificați (certifying.Save()), redeschideți-i cu Document.Open(), apoi apelați Sign() pe acel document redeschis — scrierea unei rescrieri complete în loc de o adăugare incrementală rupe certificarea /ByteRange rezumatul.

VerifySignatures() reports coversWholeFile: false pentru prima semnătură, dar true pentru ultima. Acest lucru este așteptat pentru un lanț certify-then- sign: certificarea a fost semnată înainte ca aprobarea să fie adăugată, așa că numai semnătura celei mai recente /ByteRange se extinde până la sfârșitul fișierului.

Decriptarea eșuează chiar și cu cheia privată corectă. Confirmă certificate transmis către recipient se potrivește exact cu certificatul în care documentul a fost criptat în Document.Save()’s recipients listă — un certificat reemitet cu o pereche de chei nouă nu va decripta datele criptate cu cea veche.

Întrebări frecvente

Poate un document să fie criptat pentru mai mult de un destinatar?

Da — recipients în opțiunea encrypt a Document.Save() acceptă un array; cheia privată corespunzătoare oricărui destinatar poate deschide fișierul rezultat.

Ce format de semnătură produce `Document.Sign()`?

Transmiterea lui subFilter: 'PAdES' în opțiunile de semnare produce o semnătură compatibilă PAdES; omisiunea acestuia folosește subfiltru de semnătură implicit al bibliotecii.

Cum pot verifica dacă un document este certificat în loc de a fi doar semnat?

Inspectați câmpul docMDP din SignatureReport returnat de Document.VerifySignatures() — o semnătură de certificare raportează un verdict de permisiune DocMDP; o semnătură de aprobare numai nu face acest lucru.

Sunt `Permissions` recuperate după `Document.Open()` impuse de bibliotecă?

Nu — opened.Permissions raportează flagurile de permisiune înregistrate în fișierul criptat pentru inspecție; impunerea lor într-o aplicație este responsabilitatea apelantului.