Cara Mengamankan dan Menandatangani Dokumen PDF dengan TypeScript

Panduan ini menunjukkan cara mengenkripsi, mensertifikasi, menandatangani, dan memverifikasi dokumen PDF dengan Aspose.PDF FOSS untuk TypeScript. Document.Save() dan Document.Open() menangani enkripsi kunci publik ke sertifikat penerima, sementara Document.Certify(), Document.Sign(), dan Document.VerifySignatures() menangani tanda tangan digital gaya PAdES. Diperlukan Node.js 22 atau yang lebih baru.

Panduan Langkah-demi-Langkah

Langkah 1: Instal Paket

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

Verifikasi instalasi dengan mengimpor kelas Document dalam file TypeScript baru — baris ini harus dapat diselesaikan tanpa error setelah paket diinstal:

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

Langkah 2: Impor Kelas yang Diperlukan

Impor Document untuk membuka, menyimpan, menandatangani, dan memverifikasi file; langkah penandatanganan dan enkripsi di bawah ini melewatkan objek opsi biasa, jadi tidak diperlukan impor tambahan:

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

Langkah 3: Enkripsi Dokumen ke Sertifikat Penerima

Document.Save() menerima opsi encrypt yang membawa satu atau lebih recipients, masing-masing diidentifikasi oleh sertifikat (string PEM atau byte DER), sebuah algorithm, dan permissions bersama:

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

Langkah 4: Buka Dokumen yang Dienkripsi

Berikan opsi recipient ke Document.Open() dengan kunci pribadi dan sertifikat yang cocok, atau bundel 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)

Langkah 5: Sertifikasi dan Tanda Tangani Dokumen

Document.Certify() dan Document.Sign() keduanya bersifat asynchronous dan menerima sebuah identitas (certificate + privateKey) plus opsi yang menjelaskan bidang tanda tangan, tampilan, dan alasan. Sertifikasi harus dilakukan terlebih dahulu, pada seluruh file; tanda tangan persetujuan selanjutnya ditambahkan secara bertahap setelahnya:

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

Langkah 6: Verifikasi Tanda Tangan

Document.VerifySignatures() bersifat asynchronous dan mengembalikan satu SignatureReport per bidang tanda tangan, masing-masing melaporkan integrity kriptografis, validitas signature, dan apakah itu 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}`);
  }
}

Masalah Umum dan Solusinya

Document.Sign() / Document.Certify() lempar atau menggantung. Keduanya bersifat asynchronous — await pemanggilan. Melupakan await meninggalkan promise yang dikembalikan tidak terselesaikan dan penulisan terjadi sebelum penandatanganan selesai.

Tanda tangan persetujuan selanjutnya membatalkan sertifikasi. Tandatangani secara inkremental: simpan byte yang disertifikasi terlebih dahulu (certifying.Save()), buka kembali dengan Document.Open(), kemudian panggil Sign() pada dokumen yang dibuka kembali — menulis ulang penuh alih-alih menambahkan secara inkremental merusak sertifikasi /ByteRange ringkasan.

VerifySignatures() reports coversWholeFile: false untuk tanda tangan pertama tetapi true untuk yang terakhir. Ini diharapkan untuk rantai certify-then- sign: sertifikasi ditandatangani sebelum persetujuan ditambahkan, sehingga hanya tanda tangan terbaru yang /ByteRange berlaku hingga akhir berkas.

Dekripsi gagal meskipun dengan kunci pribadi yang benar. Konfirmasikan certificate dikirim ke recipient cocok dengan sertifikat yang tepat yang dokumen dienkripsi ke dalam Document.Save()’s recipients daftar — sebuah sertifikat yang diterbitkan ulang dengan pasangan kunci baru tidak akan dapat mendekripsi data yang dienkripsi dengan yang lama.

Pertanyaan yang Sering Diajukan

Apakah sebuah dokumen dapat dienkripsi untuk lebih dari satu penerima?

Ya — recipients dalam opsi encrypt milik Document.Save() menerima sebuah array; kunci pribadi yang cocok dari penerima mana pun dapat membuka file yang dihasilkan.

Format tanda tangan apa yang dihasilkan oleh `Document.Sign()`?

Menyertakan subFilter: 'PAdES' dalam opsi penandatanganan menghasilkan tanda tangan yang kompatibel dengan PAdES; menghilangkannya menggunakan subfilter tanda tangan default perpustakaan.

Bagaimana cara saya memeriksa apakah sebuah dokumen bersertifikat atau hanya ditandatangani?

Periksa bidang docMDP pada SignatureReport yang dikembalikan oleh Document.VerifySignatures() — tanda tangan sertifikasi melaporkan keputusan izin DocMDP; tanda tangan hanya persetujuan tidak melakukannya.

Apakah `Permissions` yang dipulihkan setelah `Document.Open()` ditegakkan oleh perpustakaan?

Tidak — opened.Permissions melaporkan flag izin yang tercatat dalam file terenkripsi untuk inspeksi; menegakkannya dalam aplikasi merupakan tanggung jawab pemanggil.