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 InvalidPasswordError secara 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 panggilan Sign() apa pun — tanda tangan sertifikasi menetapkan izin DocMDP yang kemudian ditumpuk oleh tanda tangan persetujuan.
  • Document.Open() mengembalikan Permissions yang dipulihkan setelah dekripsi kunci publik, tetapi perpustakaan tidak menegakkannya sendiri — perlakukan sebagai informasi.
  • VerifySignatures() adalah async — await itu (atau tangani Promise yang dikembalikan) sebelum membaca array laporan.

Masalah Umum

MasalahPenyebabPerbaikan
Document.OpenFile() / Document.Open() melempar InvalidPasswordErrorDokumen dilindungi kata sandi dan tidak ada kata sandi, atau kata sandi yang salah, yang diberikanBerikan { password: '...' } ke Document.OpenFile() / Document.Open()
Dekripsi kunci publik gagalKunci privat atau sertifikat yang salah telah diberikan, atau keduanya tidak cocok dengan entri recipients mana pun yang digunakan saat enkripsiKonfirmasi bahwa privateKey / certificate dari opsi recipient (atau bundel PKCS#12) cocok dengan salah satu penerima asli
Tanda tangan persetujuan membatalkan sertifikasiSign() dipanggil dengan izin yang tidak diizinkan oleh transformasi DocMDP yang bersertifikatTetapkan nilai permissions pada Certify() (misalnya 'form-fill') yang cukup luas untuk perubahan yang akan dibuat oleh penandatangan berikutnya
VerifySignatures() melaporkan pemeriksaan integritas yang rusakByte yang ditandatangani telah dimodifikasi setelah penandatanganan, di luar pembaruan inkremental yang dicakup oleh tanda tanganTandatangani 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/MetodeDeskripsi
Document.OpenFile() / Document.Open()Buka dokumen, secara opsional dilindungi dengan kata sandi atau kunci publik
InvalidPasswordErrorDilempar ketika kata sandi tidak ada atau salah
Document.Save() / Document.WriteTo()Simpan dokumen, secara opsional dengan opsi encrypt
PermissionsBendera 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
SignatureReportHasil verifikasi satu tanda tangan: name, integrity, signature

Lihat Juga

 Bahasa Indonesia