چگونه اسناد PDF را در TypeScript امن‌سازی و امضا کنیم

این راهنما نشان می‌دهد چگونه اسناد PDF را با Aspose.PDF FOSS برای TypeScript رمزنگاری، گواهی‌سازی، امضا و تأیید کنیم. Document.Save() و Document.Open() رمزنگاری کلید عمومی به گواهی‌های دریافت‌کننده را مدیریت می‌کنند، در حالی که Document.Certify()، Document.Sign() و Document.VerifySignatures() امضای دیجیتال به سبک PAdES را بر عهده دارند. این راهنما نیاز به Node.js 22 یا بالاتر دارد.

راهنمای گام به گام

مرحله ۱: نصب بسته

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

نصب را با وارد کردن کلاس Document در یک فایل جدید TypeScript تأیید کنید — این خط باید پس از نصب بسته بدون خطا حل شود:

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

مرحله ۲: وارد کردن کلاس‌های مورد نیاز

برای باز کردن، ذخیره، امضا و تأیید فایل، Document را وارد کنید؛ مراحل امضا و رمزنگاری در زیر، اشیای گزینه ساده را عبور می‌دهند، بنابراین نیازی به واردات‌های بیشتر نیست:

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

مرحله ۳: رمزنگاری یک سند به گواهی‌های گیرنده

Document.Save() یک گزینه encrypt را می‌پذیرد که یک یا چند 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
  },
});

مرحله ۴: باز کردن یک سند رمزنگاری‌شده

یک گزینه 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)

مرحله ۵: صدور گواهی و امضای یک سند

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

مرحله ۶: تأیید امضاها

Document.VerifySignatures() غیرهمزمان است و برای هر فیلد امضا یک SignatureReport باز می‌گرداند، که هر کدام اطلاعات رمزنگاری 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() throw یا hang. هر دو asynchronous هستند — await فراخوانی. فراموش کردن await باعث می‌شود promise بازگشتی حل نشود و نوشتن پیش از اتمام امضا انجام شود.

امضای تأیید بعدی گواهی‌نامه را نامعتبر می‌کند. به‌صورت افزایشی امضا کنید: ابتدا بایت‌های گواهی‌شده را ذخیره کنید (certifying.Save()), سپس آن‌ها را باز کنید با Document.Open(), سپس فراخوانی کنید Sign() در آن سند بازنشانی‌شده — نوشتن یک بازنویسی کامل به جای افزودن افزایشی، گواهینامه را خراب می‌کند /ByteRange خلاصه.

VerifySignatures() reports coversWholeFile: false برای امضای اول اما true برای آخرین. این برای زنجیره‌ی certify-then- sign انتظار می‌رود: گواهینامه قبل از افزودن تأیید امضا شده بود، بنابراین تنها امضای جدیدترین /ByteRange تا انتهای فایل گسترش می‌یابد.

رمزگشایی با کلید خصوصی صحیح شکست می‌خورد. تأیید کنید certificate ارسال شده به recipient با گواهی‌نامه دقیق‌اً که سند در آن رمزنگاری شده است مطابقت دارد Document.Save()’s recipients فهرست — گواهی‌نامه‌ای که با جفت کلید جدید دوباره صادر شده است، نمی‌تواند داده‌های رمزنگاری‌شده تحت نسخهٔ قبلی را رمزگشایی کند.

سوالات متداول

آیا می‌توان یک سند را برای بیش از یک گیرنده رمزنگاری کرد؟

بله — recipients در گزینه encrypt Document.Save() یک آرایه را می‌پذیرد؛ هر کلید خصوصی منطبق با گیرنده می‌تواند فایل حاصل را باز کند.

قالب امضای تولید شده توسط `Document.Sign()` چه نوعی است؟

ارسال subFilter: 'PAdES' در گزینه‌های امضا، امضای سازگار با PAdES تولید می‌کند؛ حذف آن باعث استفاده از زیرفیلتر پیش‌فرض امضای کتابخانه می‌شود.

چگونه می‌توانم بررسی کنم که آیا یک سند گواهی‌دار است یا فقط امضا شده؟

فیلد docMDP را در SignatureReport که توسط Document.VerifySignatures() بازگردانده می‌شود بررسی کنید — امضای گواهی‌دار یک حکم اجازهٔ DocMDP را گزارش می‌دهد؛ در حالی که امضای صرفاً تأییدی چنین گزارشی ندارد.

آیا `Permissions` بازیابی‌شده پس از `Document.Open()` توسط کتابخانه اعمال می‌شوند؟

خیر — opened.Permissions پرچم‌های اجازه ثبت‌شده در فایل رمزنگاری‌شده را برای بررسی گزارش می‌دهد؛ اعمال آن‌ها در یک برنامه مسئولیت فراخواننده است.