Security
Gambaran Umum
Halaman ini mencakup kata sandi, enkripsi, dan tanda tangan digital. Document.OpenFile() / Document.Open() menerima kata sandi untuk membuka dokumen yang dilindungi, Document.Save() menerima opsi encrypt untuk melindungi satu dokumen, dan Document.Sign() / Document.Certify() / Document.VerifySignatures() menambahkan dan memeriksa tanda tangan digital.
Membuka dan Mendekripsi Dokumen yang Dilindungi Kata Sandi
Berikan { password: '...' } ke Document.OpenFile() atau Document.Open() untuk membuka dokumen yang dilindungi dengan kata sandi pengguna. Jika kata sandi tidak ada atau salah, pemanggilan akan melempar 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;
}Enkripsi saat Menyimpan
Document.Save() (dan Document.WriteTo()) menerima opsi encrypt. Enkripsi berbasis kata sandi adalah kasus yang umum; perpustakaan ini juga mendukung enkripsi kunci publik ke satu atau beberapa sertifikat penerima, yang dibuka kembali dengan kunci pribadi penerima.
// 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)
Menandatangani dan Menyertifikasi
Document.Certify() menambahkan tanda tangan sertifikasi (penulis) yang membawa transform DocMDP yang menyatakan perubahan apa yang diizinkan kemudian; Document.Sign() menambahkan tanda tangan persetujuan biasa yang dapat ditambahkan secara bertahap di atasnya. Keduanya menerima penandatangan { certificate, privateKey } dan objek opsi (reason, location, name, fieldName, dan — untuk 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');Memverifikasi Tanda Tangan
Document.VerifySignatures() memeriksa setiap tanda tangan dalam dokumen: ia menghitung ulang setiap digest /ByteRange, memverifikasi CMS terpisah, dan melaporkan apa yang berubah setelah setiap tanda tangan. Ia mengembalikan SignatureReport[], satu entri per tanda tangan.
const reports = await Document.OpenFile('signed.pdf').VerifySignatures();
for (const r of reports) {
console.log(r.name, 'integrity:', r.integrity, 'signature:', r.signature);
}Tips dan Praktik Terbaik
- Tangkap
InvalidPasswordErrorsecara khusus sebelum penangkap umum ketika membuka input yang tidak terpercaya, sehingga Anda dapat bereaksi berbeda terhadap kata sandi yang salah dibandingkan dengan file yang rusak. - Panggil
Certify()sebelum panggilanSign()apa pun — tanda tangan sertifikasi menetapkan izin DocMDP yang kemudian ditumpuk oleh tanda tangan persetujuan. Document.Open()mengembalikanPermissionsyang dipulihkan setelah dekripsi kunci publik, tetapi perpustakaan tidak menegakkannya sendiri — perlakukan sebagai informasi.VerifySignatures()adalahasync—awaititu (atau tanganiPromiseyang dikembalikan) sebelum membaca array laporan.
Masalah Umum
| Masalah | Penyebab | Perbaikan |
|---|---|---|
Document.OpenFile() / Document.Open() melempar InvalidPasswordError | Dokumen dilindungi kata sandi dan tidak ada kata sandi, atau kata sandi yang salah, yang diberikan | Berikan { password: '...' } ke Document.OpenFile() / Document.Open() |
| Dekripsi kunci publik gagal | Kunci privat atau sertifikat yang salah telah diberikan, atau keduanya tidak cocok dengan entri recipients mana pun yang digunakan saat enkripsi | Konfirmasi bahwa privateKey / certificate dari opsi recipient (atau bundel PKCS#12) cocok dengan salah satu penerima asli |
| Tanda tangan persetujuan membatalkan sertifikasi | Sign() dipanggil dengan izin yang tidak diizinkan oleh transformasi DocMDP yang bersertifikat | Tetapkan nilai permissions pada Certify() (misalnya 'form-fill') yang cukup luas untuk perubahan yang akan dibuat oleh penandatangan berikutnya |
VerifySignatures() melaporkan pemeriksaan integritas yang rusak | Byte yang ditandatangani telah dimodifikasi setelah penandatanganan, di luar pembaruan inkremental yang dicakup oleh tanda tangan | Tandatangani kembali dokumen setelah ada penyuntingan lebih lanjut |
FAQ
Apa perbedaan antara Sign dan Certify?
Certify() menambahkan tanda tangan sertifikasi pertama dan menyatakan (melalui transform DocMDP) perubahan apa yang diizinkan kemudian. Sign() menambahkan tanda tangan persetujuan biasa, yang ditambahkan secara bertahap di atas apa pun yang sebelumnya.
Bagaimana cara membuka PDF yang dilindungi kata sandi?
Berikan { password: '...' } ke Document.OpenFile() atau Document.Open(), dan tangkap InvalidPasswordError jika kata sandi mungkin salah.
Apakah perpustakaan ini menegakkan flag izin PDF?
Tidak. Document.Open() memulihkan flag Permissions dari dokumen yang terenkripsi agar Anda dapat memeriksanya, tetapi tidak membatasi apa yang dapat dilakukan kode Anda dengan dokumen yang dibuka.
Bagaimana cara memeriksa apakah tanda tangan pada PDF yang ditandatangani masih berlaku?
Panggil Document.VerifySignatures() (sebuah metode async) dan periksa setiap SignatureReport yang dikembalikan pada bidang integrity dan signature.
Ringkasan API Reference
| Kelas/Metode | Deskripsi |
|---|---|
Document.OpenFile() / Document.Open() | Buka dokumen, secara opsional dilindungi dengan kata sandi atau kunci publik |
InvalidPasswordError | Dilempar ketika kata sandi tidak ada atau salah |
Document.Save() / Document.WriteTo() | Simpan dokumen, secara opsional dengan opsi encrypt |
Permissions | Bendera izin yang dipulihkan dari dokumen terenkripsi |
Document.Certify() | Tambahkan tanda tangan sertifikasi (penulis) dengan transformasi DocMDP |
Document.Sign() | Tambahkan tanda tangan persetujuan |
Document.VerifySignatures() | Verifikasi setiap tanda tangan dalam dokumen |
SignatureReport | Hasil verifikasi satu tanda tangan: name, integrity, signature |