Hur man säkrar och signerar PDF-dokument i TypeScript

Den här guiden visar hur man krypterar, certifierar, signerar och verifierar PDF-dokument med Aspose.PDF FOSS för TypeScript. Document.Save() och Document.Open() hanterar offentlig-nyckelkryptering till mottagarcertifikat, medan Document.Certify(), Document.Sign() och Document.VerifySignatures() hanterar digitala signaturer i PAdES-stil. Den kräver Node.js 22 eller senare.

Steg-för-steg-guide

Steg 1: Installera paketet

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

Verifiera installationen genom att importera Document-klassen i en ny TypeScript-fil — den här raden bör lösa utan fel när paketet är installerat:

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

Steg 2: Importera nödvändiga klasser

Importera Document för att öppna, spara, signera och verifiera filen; signerings- och krypteringsstegen nedan skickar enkla alternativobjekt, så inga ytterligare import behövs:

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

Steg 3: Kryptera ett dokument till mottagarcertifikat

Document.Save() accepterar ett encrypt-alternativ som innehåller en eller flera recipients, var och en identifierad av ett certifikat (PEM-sträng eller DER-bytes), ett algorithm, och delade 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
  },
});

Steg 4: Öppna ett krypterat dokument

Skicka ett recipient-alternativ till Document.Open() med antingen den matchande privata nyckeln och certifikatet, eller ett PKCS#12-paket:

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

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

Steg 5: Certifiera och signera ett dokument

Document.Certify() och Document.Sign() är båda asynkrona och tar en identitet (certificate + privateKey) samt alternativ som beskriver signaturfältet, utseendet och orsaken. Certifiering bör ske först, över hela filen; ytterligare godkännandesignaturer läggs till successivt därefter:

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

Steg 6: Verifiera signaturer

Document.VerifySignatures() är asynkron och returnerar en SignatureReport per signaturfält, var och en rapporterar kryptografisk integrity, signature giltighet och om den 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}`);
  }
}

Vanliga problem och lösningar

Document.Sign() / Document.Certify() kasta eller hänga. Båda är asynkrona — await anropet. Glömmer await lämnar det returnerade löftet olöst och skrivningen sker innan signeringen är klar.

En senare godkännandesignatur ogiltigförklarar certifieringen. Signera inkrementellt: spara de certifierade bytena först (certifying.Save()), öppna dem igen med Document.Open(), anropa sedan Sign() på det återöppnade dokumentet — att skriva en fullständig omskrivning istället för ett inkrementellt tillägg bryter certifikatets /ByteRange digest.

VerifySignatures() reports coversWholeFile: false för den första signaturen men true för den sista. Detta är förväntat för en certifiera-sedan-signera-kedja: certifikatet signerades innan godkännandet lades till, så endast den senaste signaturens /ByteRange sträcker sig till filens slut.

Dekryptering misslyckas med rätt privat nyckel. Bekräfta certificate skickas till recipient matchar exakt det certifikat som dokumentet krypterades till i Document.Save()’s recipients lista — ett certifikat som utfärdas på nytt med ett nytt nyckelpar kommer inte att dekryptera data som krypterats med det gamla.

Vanliga frågor

Kan ett dokument krypteras till fler än en mottagare?

Ja — recipients i Document.Save()s encrypt-alternativ accepterar en array; vilken mottagares matchande privata nyckel som helst kan öppna den resulterande filen.

Vilket signaturformat producerar `Document.Sign()`?

Att skicka subFilter: 'PAdES' i signeringsalternativen skapar en PAdES-kompatibel signatur; att utelämna den använder bibliotekets standard-signatursubfilter.

Hur kontrollerar jag om ett dokument är certifierat eller bara signerat?

Inspektera docMDP-fältet på SignatureReport som returneras av Document.VerifySignatures() — en certifieringssignatur rapporterar ett DocMDP behörighetsbeslut; en signatur som bara godkänner gör det inte.

Tvingas återställda `Permissions` efter `Document.Open()` av biblioteket?

Nej — opened.Permissions rapporterar behörighetsflaggorna som lagrats i den krypterade filen för inspektion; att verkställa dem i en applikation är anroparens ansvar.