Hogyan lehet biztonságossá tenni és aláírni a PDF dokumentumokat TypeScriptben

Ez az útmutató bemutatja, hogyan lehet titkosítani, tanúsítani, aláírni és ellenőrizni a PDF dokumentumokat a Aspose.PDF nyílt forráskódú szoftverrel a TypeScript számára. A Document.Save() és a Document.Open() a nyilvános kulcsú titkosítást kezeli a címzett tanúsítványaihoz, míg a Document.Certify(), Document.Sign() és a Document.VerifySignatures() a PAdES-stílusú digitális aláírásokat végzi. Node.js 22 vagy újabb verzió szükséges.

Lépésről lépésre útmutató

1. lépés: A csomag telepítése

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

Ellenőrizze a telepítést a Document osztály importálásával egy új TypeScript fájlban — ennek a sornak hibamentesen kell feloldódnia a csomag telepítése után:

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

2. lépés: A szükséges osztályok importálása

Importálja a(z) Document modult a fájl megnyitásához, mentéséhez, aláírásához és ellenőrzéséhez; az alábbi aláírási és titkosítási lépések egyszerű opcióobjektumokat adnak át, így nincs szükség további importálásra:

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

3. lépés: Dokumentum titkosítása a címzett tanúsítványaihoz

Document.Save() elfogad egy encrypt opciót, amely egy vagy több recipients-t tartalmaz, mindegyik egy tanúsítvány (PEM karakterlánc vagy DER bájtok), egy algorithm, és közös permissions alapján azonosítva:

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

4. lépés: Titkosított dokumentum megnyitása

Adjon át egy recipient opciót a(z) Document.Open() számára, amely vagy a megfelelő privát kulcsot és tanúsítványt, vagy egy PKCS#12 csomagot tartalmaz:

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

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

5. lépés: Dokumentum hitelesítése és aláírása

Document.Certify() és Document.Sign() egyaránt aszinkronok, és egy azonosítót (certificate + privateKey) valamint olyan opciókat várnak, amelyek leírják az aláírásmezőt, a megjelenést és az okot. A hitelesítést először, a teljes fájlra kell alkalmazni; a további jóváhagyó aláírások ezt követően fokozatosan kerülnek hozzáadásra:

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

6. lépés: Aláírások ellenőrzése

Document.VerifySignatures() aszinkron, és egy SignatureReport-t ad vissza aláírási mezőnként, mindegyik kriptográfiai integrity, signature érvényességet jelentve, és hogy 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}`);
  }
}

Gyakori problémák és megoldások

Document.Sign() / Document.Certify() dob vagy akadozz. Mindkettő aszinkron — await a hívás. Elfelejtve await a visszaadott ígéretet feloldatlanul hagyja, és az írás a aláírás befejezése előtt történik.

Egy későbbi jóváhagyó aláírás érvényteleníti a tanúsítványt. Aláírás fokozatosan: először mentse a tanúsított bájtokat (certifying.Save()), nyissa meg őket újra a Document.Open(), majd hívja meg Sign() az újra megnyitott dokumentumon — a teljes újraírás írása az inkrementális hozzáfűzés helyett felbontja a tanúsítványt /ByteRange kivonat.

VerifySignatures() reports coversWholeFile: false az első aláírásra, de true az utolsóra. Ez várható egy tanúsítvány-azután-aláírás láncnál: a tanúsítványt aláírták, mielőtt a jóváhagyást hozzáfűzték, ezért csak a legújabb aláírás /ByteRange kiterjed a fájl végéig.

A visszafejtés a helyes privát kulccsal is sikertelen. Erősítse meg a certificate átadva recipient pontosan egyezik azzal a tanúsítvánnyal, amivel a dokumentum titkosítva lett in Document.Save()’s recipients lista — egy új kulcspárral újrakibocsátott tanúsítvány nem fog feloldani olyan adatot, amelyet a régi kulccsal titkosítottak.

Gyakran Ismételt Kérdések

Lehet egy dokumentumot több mint egy címzettnek titkosítani?

Igen — a recipients a Document.Save() encrypt opciójában tömböt fogad el; bármelyik címzett megfelelő privát kulcsa megnyithatja a keletkezett fájlt.

Milyen aláírásformátumot állít elő a `Document.Sign()`?

A subFilter: 'PAdES' átadása az aláírási beállításokban PAdES-kompatibilis aláírást eredményez; annak kihagyása a könyvtár alapértelmezett aláírás-alatszűrőjét használja.

Hogyan ellenőrizhetem, hogy egy dokumentum tanúsítvánnyal rendelkezik-e, vagy csak alá van írva?

Vizsgálja meg a docMDP mezőt a Document.VerifySignatures() által visszaadott SignatureReport objektumban — egy tanúsítvány-aláírás DocMDP jogosultsági döntést jelent; egy csak jóváhagyásra szolgáló aláírás nem.

A `Document.Open()` után visszaállított `Permissions` értékeket a könyvtár érvényesíti?

Nem — a opened.Permissions a titkosított fájlban rögzített jogosultsági jelzőket jelenti ki ellenőrzés céljából; ezek érvényesítése az alkalmazásban a hívó felelőssége.