Jak zabezpečit a podepsat PDF dokumenty v TypeScript

Tento návod ukazuje, jak šifrovat, certifikovat, podepisovat a ověřovat PDF dokumenty pomocí Aspose.PDF FOSS pro TypeScript. Document.Save() a Document.Open() zajišťují šifrování pomocí veřejného klíče k certifikátům příjemců, zatímco Document.Certify(), Document.Sign() a Document.VerifySignatures() zpracovávají digitální podpisy ve stylu PAdES. Vyžaduje Node.js 22 nebo novější.

Návod krok za krokem

Krok 1: Nainstalujte balíček

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

Ověřte instalaci importováním třídy Document do nového souboru TypeScript — tento řádek by se měl po instalaci balíčku vyřešit bez chyby:

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

Krok 2: Importujte požadované třídy

Importujte Document pro otevření, uložení, podepsání a ověření souboru; kroky podepisování a šifrování níže předávají jednoduché objekty možností, takže nejsou potřeba další importy:

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

Krok 3: Zašifrovat dokument pro certifikáty příjemců

Document.Save() přijímá možnost encrypt, která nese jeden nebo více recipients, z nichž každý je identifikován certifikátem (PEM řetězec nebo DER bajty), algorithm a sdíleným 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
  },
});

Krok 4: Otevřít zašifrovaný dokument

Předávejte možnost recipient do Document.Open() buď s odpovídajícím soukromým klíčem a certifikátem, nebo s balíčkem 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)

Krok 5: Certifikovat a podepsat dokument

Document.Certify() a Document.Sign() jsou oba asynchronní a přijímají identitu (certificate + privateKey) plus možnosti popisující pole podpisu, vzhled a důvod. Certifikace by měla proběhnout jako první, nad celým souborem; další schvalovací podpisy jsou následně přidávány postupně:

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

Krok 6: Ověřit podpisy

Document.VerifySignatures() je asynchronní a vrací jeden SignatureReport na pole podpisu, každý hlásí kryptografické integrity, signature platnost a zda 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}`);
  }
}

Časté problémy a opravy

Document.Sign() / Document.Certify() vyhodit nebo zavěsit. Obě jsou asynchronní — await volání. Zapomínání await zanechává vrácený promise nevyřešený a zápis se provede dříve, než se dokončí podepisování.

Pozdější podpis schválení zneplatňuje certifikaci. Podepisujte postupně: nejprve uložte certifikované bajty (certifying.Save()), znovu je otevřete pomocí Document.Open(), pak zavolejte Sign() na tom znovu otevřeném dokumentu — zápis úplného přepsání místo inkrementálního doplnění narušuje certifikaci /ByteRange digest.

VerifySignatures() reports coversWholeFile: false pro první podpis, ale true pro poslední. To je očekávané pro řetězec certify-then-sign: certifikace byla podepsána před tím, než bylo schválení připojeno, takže pouze nejnovější podpis /ByteRange protahuje se až do konce souboru.

Dešifrování selže i při správném soukromém klíči. Potvrďte certificate předáno do recipient odpovídá přesnému certifikátu, pro který byl dokument zašifrován v Document.Save()’s recipients list — certifikát znovu vydaný s novým párem klíčů nebude dešifrovat data zašifrovaná pod starým.

Často kladené otázky

Může být dokument zašifrován pro více než jednoho příjemce?

Ano — recipients v Document.Save()’s encrypt možnosti přijímá pole; jakýkoli odpovídající soukromý klíč příjemce může otevřít výsledný soubor.

Jaký formát podpisu vytváří `Document.Sign()`?

Předání subFilter: 'PAdES' v možnostech podepisování vytvoří podpis kompatibilní s PAdES; pokud jej vynecháte, použije se výchozí subfilter podpisu knihovny.

Jak zjistím, zda je dokument certifikován, nebo jen podepsán?

Prozkoumejte pole docMDP v SignatureReport vráceném Document.VerifySignatures() — certifikační podpis uvádí verdikt oprávnění DocMDP; podpis pouze pro schválení takový verdikt neuvádí.

Jsou obnovená `Permissions` po `Document.Open()` vynucována knihovnou?

Ne — opened.Permissions hlásí příznaky oprávnění zaznamenané v zašifrovaném souboru k inspekci; jejich vynucení v aplikaci je odpovědností volajícího.