Hoe PDF-documenten te beveiligen en te ondertekenen in TypeScript

Deze gids toont hoe PDF-documenten te versleutelen, te certificeren, te ondertekenen en te verifiëren met Aspose.PDF FOSS voor TypeScript. Document.Save() en Document.Open() verzorgen openbare-sleutelversleuteling naar ontvangercertificaten, terwijl Document.Certify(), Document.Sign() en Document.VerifySignatures() PAdES-stijl digitale handtekeningen afhandelen. Het vereist Node.js 22 of hoger.

Stapsgewijze handleiding

Stap 1: Installeer het pakket

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

Verifieer de installatie door de Document klasse te importeren in een nieuw TypeScript bestand — deze regel zou zonder fout moeten resolven zodra het pakket geïnstalleerd is:

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

Stap 2: Importeer vereiste klassen

Importeer Document om het bestand te openen, op te slaan, te ondertekenen en te verifiëren; de ondertekenings- en encryptiestappen hieronder geven eenvoudige optiereeksen door, dus er zijn geen extra imports nodig:

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

Stap 3: Versleutel een document naar ontvangercertificaten

Document.Save() accepteert een encrypt optie die één of meer recipients bevat, elk geïdentificeerd door een certificaat (PEM-string of DER-bytes), een algorithm, en gedeelde permissions:

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
  },
});

Stap 4: Open een versleuteld document

Geef een recipient optie door aan Document.Open() met ofwel de bijpassende privésleutel en het certificaat, of een PKCS#12-bundel:

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

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

Stap 5: Certificeer en onderteken een document

Document.Certify() en Document.Sign() zijn beide asynchroon en nemen een identiteit (certificate + privateKey) plus opties die het handtekeningsveld, de weergave en de reden beschrijven. Certificeren moet eerst plaatsvinden, over het hele bestand; verdere goedkeuringshandtekeningen worden daarna stapsgewijs toegevoegd:

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');
}

Stap 6: Verifieer handtekeningen

Document.VerifySignatures() is asynchroon en retourneert één SignatureReport per handtekeningsveld, elk rapporteert cryptografische integrity, signature geldigheid, en of het 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}`);
  }
}

Veelvoorkomende problemen en oplossingen

Document.Sign() / Document.Certify() throw of hang. Beiden zijn asynchroon — await de oproep. Vergeten await laat de geretourneerde promise onopgelost en gebeurt het schrijven voordat ondertekenen voltooid is.

Een latere goedkeuringshandtekening maakt de certificering ongeldig. Onderteken incrementeel: sla de gecertificeerde bytes eerst op (certifying.Save()), heropen ze met Document.Open(), roep vervolgens aan Sign() op dat heropende document — het schrijven van een volledige herschrijving in plaats van een incrementele toevoeging breekt de certificering /ByteRange digest.

VerifySignatures() reports coversWholeFile: false voor de eerste handtekening maar true voor de laatste. Dit is verwacht voor een certificeer-dan-onderteken keten: de certificering werd ondertekend voordat de goedkeuring werd toegevoegd, dus alleen de meest recente handtekening’s /ByteRange strekt zich uit tot het einde van het bestand.

Decryptie mislukt met de juiste privésleutel. Bevestig de certificate doorgegeven aan recipient komt overeen met het exacte certificaat waaraan het document versleuteld is in Document.Save()’s recipients lijst — een certificaat dat opnieuw is uitgegeven met een nieuw sleutelpaar zal geen gegevens ontcijferen die onder de oude zijn versleuteld.

Veelgestelde vragen

Kan een document worden versleuteld voor meer dan één ontvanger?

Ja — recipients in de encrypt optie van Document.Save() accepteert een array; elke bijpassende privésleutel van een ontvanger kan het resulterende bestand openen.

Welk handtekeningformaat produceert `Document.Sign()`?

Het doorgeven van subFilter: 'PAdES' in de ondertekeningsopties resulteert in een PAdES-compatibele handtekening; het weglaten ervan gebruikt de standaard subfilter voor handtekeningen van de bibliotheek.

Hoe controleer ik of een document gecertificeerd is in plaats van alleen ondertekend?

Inspecteer het docMDP veld op de SignatureReport die wordt geretourneerd door Document.VerifySignatures() — een certificeringshandtekening rapporteert een DocMDP permissie-verdict; een handtekening die alleen goedkeuring aangeeft dat niet.

Worden herstelde `Permissions` na `Document.Open()` afgedwongen door de bibliotheek?

Nee — opened.Permissions rapporteert de permissievlaggen die in het versleutelde bestand zijn vastgelegd voor inspectie; het afdwingen ervan in een applicatie is de verantwoordelijkheid van de aanroeper.