Security
بررسی کلی
این صفحه به رمزهای عبور، رمزنگاری و امضای دیجیتال میپردازد. Document.OpenFile() / Document.Open() برای باز کردن سند محافظتشده با رمز عبور، Document.Save() یک گزینه encrypt را برای محافظت میپذیرد، و Document.Sign() / Document.Certify() / Document.VerifySignatures() امضای دیجیتال را اضافه و بررسی میکنند.
باز کردن و رمزگشایی اسناد محافظتشده با رمز عبور
{ password: '...' } را به Document.OpenFile() یا Document.Open() بدهید تا سندی که با رمز عبور کاربر محافظت شده است باز شود. اگر رمز عبور موجود نباشد یا نادرست باشد، فراخوانی InvalidPasswordError را پرتاب میکند.
import { Document, InvalidPasswordError } from '@asposefoss/pdf';
try {
const doc = Document.OpenFile('secret.pdf', { password: 'hunter2' });
doc.WriteTo('decrypted.pdf'); // output is plaintext
} catch (e) {
if (e instanceof InvalidPasswordError) console.error('wrong password');
else throw e;
}رمزنگاری هنگام ذخیره
Document.Save() (و Document.WriteTo()) یک گزینه encrypt میپذیرند. رمزنگاری مبتنی بر رمز عبور رایج است؛ کتابخانه همچنین از رمزنگاری کلید عمومی به یک یا چند گواهی گیرنده پشتیبانی میکند که دوباره با کلید خصوصی گیرنده باز میشود.
// Encrypt to one or more recipient certificates (PEM string or DER bytes):
const bytes = doc.Save({
encrypt: {
recipients: [{ certificate: recipientCertPem }],
algorithm: 'aes256', // 'aes256' (default) | 'aes128' | 'rc4'
permissions: { copying: false }, // shared across all recipients
},
});
// Open with the recipient's private key + certificate, or a PKCS#12 bundle:
const opened = Document.Open(bytes, {
recipient: { privateKey, certificate: recipientCertPem },
});
console.log(opened.Permissions); // recovered permission flags (not enforced)
امضا و گواهیدهی
Document.Certify() یک امضای گواهی (نویسنده) اضافه میکند که شامل یک تبدیل DocMDP است و اعلام میکند که چه تغییرات بعدیای مجاز هستند؛ Document.Sign() یک امضای معمولی تأیید دیگری اضافه میکند که میتواند بهصورت افزایشی در بالای آن اضافه شود. هر دو یک امضاکننده { certificate, privateKey } و یک شیء گزینهها (reason, location, name, fieldName، و — برای Certify() — permissions) میگیرند.
const certifying = Document.OpenFile('report.pdf');
await certifying.Certify(
{ certificate: author.certificate, privateKey: author.privateKey },
{ permissions: 'form-fill', reason: 'Certifying the report', fieldName: 'Certification' },
);
const certifiedBytes = certifying.Save();
const approving = Document.Open(certifiedBytes);
await approving.Sign(
{ certificate: approver.certificate, privateKey: approver.privateKey },
{ reason: 'Approved for publication', fieldName: 'Approval' },
);
approving.WriteTo('signed.pdf');تأیید امضاها
Document.VerifySignatures() هر امضای موجود در سند را بررسی میکند: هضم /ByteRange هرکدام را مجدداً محاسبه میکند، CMS جداشده را تأیید مینماید و گزارش میدهد چه چیزی پس از هر امضا تغییر کرده است. این یک SignatureReport[] برمیگرداند، یک ورودی برای هر امضا.
const reports = await Document.OpenFile('signed.pdf').VerifySignatures();
for (const r of reports) {
console.log(r.name, 'integrity:', r.integrity, 'signature:', r.signature);
}نکات و بهترین روشها
- بهطور خاص
InvalidPasswordErrorرا قبل از یک بلوک عمومیتر هنگام باز کردن ورودیهای غیرقابل اعتماد بگیرید، تا بتوانید به رمز عبور نادرست بهجای پرونده خراب واکنش متفاوتی نشان دهید. - قبل از هر فراخوانی
Sign()،Certify()را صدا بزنید — یک امضای گواهی، مجوزهای DocMDP را تعیین میکند که امضاهای تأیید بعدی بر روی آن لایهبندی میشوند. Document.Open()پس از رمزگشایی کلید عمومی،Permissionsبازیابیشده را برمیگرداند، اما کتابخانه خود بهطور خودکار آنها را اعمال نمیکند — آنها را بهعنوان اطلاعاتی در نظر بگیرید.VerifySignatures()asyncاست —awaitآن (یا پردازشPromiseبازگشتی) قبل از خواندن آرایهٔ گزارش.
مشکلات رایج
| مشکل | دلیل | راهحل |
|---|---|---|
Document.OpenFile() / Document.Open() خطای InvalidPasswordError را میاندازد | سند با رمز عبور محافظت میشود و هیچ رمز عبوری ارائه نشده یا رمز نادرست ارائه شده است | مقدار { password: '...' } را به Document.OpenFile() / Document.Open() بدهید |
| رمزگشایی کلید عمومی ناموفق است | کلید خصوصی یا گواهی اشتباه ارسال شده است، یا هیچکدام با هیچ ورودی recipients که در زمان رمزنگاری استفاده شده مطابقت ندارند | اطمینان حاصل کنید که recipient گزینهی privateKey / certificate (یا بسته PKCS#12) با یکی از گیرندگان اصلی مطابقت دارد |
| امضای تأیید اعتبار، گواهینامه را باطل میکند | Sign() با مجوزهایی فراخوانی شد که تبدیل DocMDP معتبر اجازهٔ آن را نمیدهد | مقدار permissions را بر روی Certify() تنظیم کنید (مثلاً 'form-fill') بهگونهای که برای تغییراتی که امضاکنندگان بعدی اعمال میکنند، کافی باشد |
VerifySignatures() گزارش میدهد که بررسی صحت یکپارچگی خراب است | بایتهای امضا شده پس از امضا تغییر یافتند، در محدودهای که بهروزرسانی افزایشی توسط امضا پوشش داده میشود، نیستند | پس از هر ویرایش جدید، سند را مجدداً امضا کنید |
FAQ
تفاوت بین Sign و Certify چیست؟
Certify() اولین امضای گواهی را اضافه میکند و (از طریق یک DocMDP تبدیل) اعلام میسازد که چه تغییرات بعدی مجاز هستند. Sign() یک امضای تأیید عادی اضافه میکند که بهصورت افزایشی بر روی هر چه پیش از آن بوده اضافه میشود.
چگونه یک PDF محافظتشده با رمز عبور را باز کنم؟
{ password: '...' } را به Document.OpenFile() یا Document.Open() بدهید و اگر ممکن است رمز عبور اشتباه باشد، InvalidPasswordError را دریافت کنید.
آیا این کتابخانه پرچمهای دسترسی PDF را اعمال میکند؟
نه. Document.Open() پرچمهای Permissions را از یک سند رمزگذاریشده بازیابی میکند تا شما آنها را بررسی کنید، اما خود آن محدودیتی بر آنچه کد شما میتواند با سند باز شده انجام دهد اعمال نمیکند.
چگونه میتوانم بررسی کنم که امضاهای یک PDF امضا شده هنوز معتبر هستند؟
متد Document.VerifySignatures() را فراخوانی کنید (یک روش async) و فیلدهای integrity و signature هر SignatureReport برگرداندهشده را بررسی کنید.
API Reference خلاصه
| کلاس/متد | توضیح |
|---|---|
Document.OpenFile() / Document.Open() | یک سند را باز کنید، بهصورت اختیاری با رمز عبور یا کلید عمومی محافظت شده |
InvalidPasswordError | در صورتی که رمز عبور موجود نباشد یا نادرست باشد، پرتاب میشود |
Document.Save() / Document.WriteTo() | سندی را ذخیره کنید، بهصورت اختیاری با گزینه encrypt |
Permissions | پرچمهای دسترسی از سند رمزگذاریشده بازیابی شد |
Document.Certify() | امضای گواهی (نویسنده) را با تبدیل DocMDP اضافه کنید |
Document.Sign() | یک امضای تأیید اضافه کنید |
Document.VerifySignatures() | هر امضا را در سند تأیید کنید |
SignatureReport | نتیجهٔ تأیید یک امضا: name, integrity, signature |