TypeScriptでPDFドキュメントを保護および署名する方法

このガイドでは、TypeScript 向けの Aspose.PDF FOSS を使用して PDF 文書を暗号化、認証、署名、検証する方法を示します。Document.Save() と Document.Open() は受取人証明書への公開鍵暗号化を処理し、Document.Certify()、Document.Sign()、および Document.VerifySignatures() は PAdES スタイルのデジタル署名を処理します。Node.js 22 以降が必要です。

ステップバイステップガイド

ステップ 1: パッケージをインストールする

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

パッケージをインストールしたら、新しい TypeScript ファイルで Document クラスをインポートしてインストールを検証します — この行はエラーなく解決されるはずです:

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

ステップ 2: 必要なクラスをインポートする

Document をインポートして、ファイルを開く、保存する、署名する、検証する；以下の署名および暗号化手順ではプレーンなオプションオブジェクトを渡すだけなので、追加のインポートは不要です：

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

ステップ 3: 受取人証明書へ文書を暗号化する

Document.Save() は、encrypt オプションを受け取り、1 つ以上の recipients を保持します。それぞれは証明書（PEM 文字列または DER バイト列）、algorithm、および共有 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
  },
});

ステップ 4: 暗号化された文書を開く

recipient オプションを Document.Open() に渡します。マッチするプライベートキーと証明書、または 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)

ステップ 5: 文書を認証し署名する

Document.Certify() と Document.Sign() はどちらも非同期で、アイデンティティ（certificate + privateKey）と署名フィールド、外観、理由を記述するオプションを受け取ります。認証は最初に、ファイル全体に対して行うべきです。その後、追加の承認署名が順次付加されます：

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: 署名を検証する

Document.VerifySignatures()は非同期で、署名フィールドごとにSignatureReportを1つ返し、各々が暗号的integrity、signatureの有効性、そして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}`);
  }
}

一般的な問題と対処法

Document.Sign() / Document.Certify() 例外を投げるかハングする。 どちらも非同期です — await 呼び出し。忘れる await 返された Promise が未解決のまま残り、書き込みが署名完了前に行われます。

後の承認署名が認証を無効にします。 段階的に署名する：最初に認証済みバイトを保存します（certifying.Save()）、それらを再度開く際に Document.Open()、その後呼び出す Sign() 再オープンしたドキュメント上で — 増分の追加ではなく完全な書き換えを行うと、認証の /ByteRange ダイジェストが壊れます。

VerifySignatures() reports coversWholeFile: false 最初の署名では、しかし true 最後の署名では。 これは certify-then-sign のチェーンでは想定される挙動です。認証は承認が付加される前に署名されているため、最新の署名の /ByteRange がファイルの末尾まで適用されます。

正しい秘密鍵を使用しても復号に失敗します。 確認してください。 certificate 渡された recipient 文書が暗号化された正確な証明書と一致します Document.Save()の recipients リスト — 新しい鍵ペアで再発行された証明書は、古い証明書で暗号化されたデータを復号できません。

よくある質問

ドキュメントを複数の受信者に暗号化できますか？

はい — recipients は Document.Save() の encrypt オプションで配列を受け入れます；受信者の一致する秘密鍵であれば、生成されたファイルを開くことができます。

`Document.Sign()` が生成する署名形式は何ですか？

署名オプションに subFilter: 'PAdES' を渡すと、PAdES 互換の署名が生成されます；省略すると、ライブラリのデフォルト署名サブフィルタが使用されます。

ドキュメントが認証されているか、単に署名されているだけかをどうやって確認しますか？

Document.VerifySignatures() が返す SignatureReport の docMDP フィールドを確認してください — 認証署名は DocMDP 権限の判定を報告します；承認のみの署名は報告しません。

`Document.Open()` 後に復元された `Permissions` はライブラリで強制されますか？

いいえ — opened.Permissions は検査のために暗号化ファイルに記録された権限フラグを報告します；それらをアプリケーションで強制することは呼び出し側の責任です。