Menerapkan tanda tangan digital PAdES lewat NextPDF Connect (Pro)

Sekilas

Terapkan tanda tangan digital baseline PDF Advanced Electronic Signatures (PAdES) pada PDF lewat NextPDF Connect. Gunakan sign_pdf, yang telah diverifikasi ulang terhadap penyedia tool Pro: penyedia tersebut mendaftarkan new SignPdfTool(), dengan nama protokol sign_pdf. sign_pdf adalah tool tingkat Pro. Saat boot, server memeriksanya dengan class_exists() dan mendaftarkannya hanya ketika paket Pro terpasang.

Secara baku, tool ini menghasilkan PAdES B-B. Tool ini dapat menghasilkan PAdES B-T (B-B ditambah satu RFC 3161 signature-time-stamp) hanya ketika host telah menyambungkan penyedia stempel waktu ke tool; permintaan tidak dapat diarahkan ke Time Stamp Authority (TSA). Level jangka panjang (B-LT, B-LTA) dan materi validasinya (DSS, VRI, LTV) bukan bagian dari tool ini dan berada di luar cakupan di sini.

Peringatan U-1. NextPDF tidak mengklaim sertifikasi ETSI EN 319 142-1 independen apa pun untuk PAdES B-T. EN 319 142-1 tidak ada dalam korpus verifikasi. Persyaratan B-T signature-time-stamp diverifikasi terhadap ETSI EN 319 122-1 §5.3 (basis CAdES yang diimpor EN 319 142-1/-2 melalui rujukan), bersama dengan RFC 3161, RFC 5652, RFC 5816, dan ISO 32000-2 §12.8. Dukungan untuk profil B-T bukan merupakan sertifikasi kesesuaian atau keabsahan hukum; penetapan tersebut dilakukan oleh validator independen.

Pemasangan

composer require nextpdf/server
composer require nextpdf/pro

Ikat transport, lalu pastikan bahwa sign_pdf tersedia melalui diagnostic.capabilities. Untuk B-T, host harus membangun tool dengan penyedia stempel waktu. Tanpa penyedia tersebut, permintaan pades_b_t: true gagal dengan galat bertipe, bukan diturunkan secara diam-diam.

Gambaran konseptual

sign_pdf menghitung digest byte-range atas berkas, tanpa menyertakan placeholder nilai tanda tangan (ISO 32000-2 §12.8.1). Lalu, tool menulis Cryptographic Message Syntax (CMS) SignedData yang dienkode dengan Distinguished Encoding Rules (DER) ke dalam kamus tanda tangan Contents (ISO 32000-2 §12.8.1). Algoritme yang didukung adalah RSA-SHA256 (baku), RSA + SHA-3 (256/384/512), dan Ed25519. Untuk transport yang tidak rahasia secara ujung-ke-ujung, Anda dapat membungkus muatan private_key yang masuk dalam amplop AES-GCM opsional.

Peningkatan B-T. Dengan pades_b_t: true dan penyedia stempel waktu yang disambungkan oleh host, tanda tangan ditingkatkan ke PAdES B-T: hash byte-range dikirim ke TSA dan sebuah TimeStampToken disematkan (ISO 32000-2 §12.8.5). Secara tepat, B-T adalah B-B ditambah satu RFC 3161 signature-time-stamp yang dibawa sebagai atribut tidak bertanda tangan pada CMS SignerInfo (RFC 5652 §5.3). Atribut tidak bertanda tangan tidak dicakup oleh tanda tangan, sehingga digest bertanda tangan B-B dan keabsahannya tidak berubah (RFC 5652 §5.3). Nilai atribut tersebut adalah SignatureTimeStampToken (ETSI EN 319 122-1 §5.3). B-T tidak menambahkan kamus Document Security Store (DSS), tidak menambahkan Validation Related Information (VRI), tidak menambahkan materi validasi, dan tidak menambahkan loop stempel waktu arsip. Semua itu adalah delta Enterprise B-LT/B-LTA dan berada di luar cakupan tool ini.

Peringatan U-1 (diulang pada klaim B-T). Dukungan B-T di sini bukanlah sertifikasi kesesuaian EN 319 142-1 atau keabsahan hukum; penetapan tersebut dilakukan oleh validator independen. EN 319 142-1 tidak ada dalam korpus verifikasi. B-T didasarkan pada ETSI EN 319 122-1 §5.3, RFC 3161, RFC 5652, RFC 5816, dan ISO 32000-2 §12.8.

Alur berikut menunjukkan jalur TSA yang dikendalikan host (permintaan tidak dapat diarahkan ke TSA) dan cabang B-T yang fail-closed (tidak pernah mengalami penurunan diam-diam).

Diagram

Permukaan API

Tool	Tingkat	Peran	Tingkat risiko
create_pdf, add_text	Core	Membangun konten	Aman / Hati-hati
sign_pdf	Pro	Menerapkan PAdES B-B (atau B-T yang dikendalikan host)	Approval Required
output_pdf	Core	Merender dan mengembalikan PDF	Approval Required / Review (base64)

Nama tool menggunakan nama protokol registry. katalog tool adalah katalog resmi. Tool yang tersedia bergantung pada tingkat yang terpasang, dan tool untuk level jangka panjang tidak ada di Pro.

Contoh kode — Mulai cepat

1. create_pdf → bangun konten dengan add_text.
2. sign_pdf dengan certificate (PEM), private_key (PKCS#8 PEM), signer_name opsional, reason, dan algorithm. Abaikan pades_b_t (atau setel ke false) untuk B-B.
3. output_pdf.

Tool ini mengembalikan amplop hasil berikut:

{
  "pdf": "<base64 of the signed PDF>",
  "signature_count": 1,
  "is_complete": true,
  "algorithm": "RSA_SHA256",
  "oid": "<algorithm OID>",
  "digest": "<digest algorithm>",
  "level": "PAdES-B-B",
  "timestamped": false
}

Untuk tanda tangan B-T yang dikendalikan host, kirim pades_b_t: true; level menjadi "PAdES-B-T", dan timestamped menjadi true.

Contoh kode — Produksi

Lakukan penandatanganan sebagai operasi konten terakhir. Setiap add_text/add_image setelah sign_pdf membuat tanda tangan tidak valid. Pada transport yang tidak rahasia, bungkus private_key dalam amplop AES-GCM transport_encryption (nonce 12 byte; kunci 16/24/32 byte). Pastikan bahwa level hasil cocok dengan permintaan Anda. Permintaan pades_b_t: true terhadap tool tanpa penyedia gagal secara eksplisit. Tangani galat tersebut, dan jangan mencoba ulang sebagai B-B secara diam-diam.

Kasus pinggir & jebakan

• Ketidakcocokan sertifikat/kunci. Tool menolak permintaan dengan galat yang jelas; kunci privat harus cocok dengan kunci publik sertifikat.
• PEM cacat / sertifikat kedaluwarsa. Tool menolak permintaan; secara baku, tool tidak menandatangani dengan sertifikat yang tidak dapat diurai atau yang kedaluwarsa.
• Konten setelah penandatanganan. Tool menolak permintaan — tandatangani terakhir.
• B-T diminta, tanpa penyedia. Tool mengembalikan galat bertipe: tanda tangan tidak dihasilkan dan tidak diturunkan secara diam-diam ke B-B.
• Sertifikat yang ditandatangani sendiri. Tanda tangan diterapkan, tetapi pembaca menampilkan status kepercayaan yang tidak dikenal. Itu perilaku yang diperkirakan, bukan cacat tool.
• Pro tidak tersedia. Dengan Core saja, server tidak mendaftarkan sign_pdf.

Kinerja

Penandatanganan menambahkan pembuatan CMS dan, untuk B-T, satu kali pulang-pergi TSA; anggaran mencakup keduanya. Profilnya adalah semantic: token RFC 3161 secara inheren tidak dapat direproduksi, dan digest byte-range §12.8.1 tidak menyertakan nilai tanda tangan. Gunakan perbandingan AST + metadata tanda tangan saja.

Catatan keamanan

Tanda tangan memberikan integritas dan autentikasi berdasarkan kunci penandatanganan. Dengan sendirinya, tanda tangan tidak membuat dokumen menjadi “aman” atau “sah secara hukum”, atau menjamin nirsangkal. Hasil tersebut bergantung pada sertifikat, jangkar kepercayaannya, penyimpanan kunci, dan kebijakan pemverifikasi, yang semuanya berada di luar tool ini. Mengenkripsi muatan kunci dengan amplop AES-GCM melindungi kerahasiaan saat transit, bukan integritas. Perlakukan kunci privat sebagai rahasia, dan utamakan amplop enkripsi transport pada kanal apa pun yang tidak rahasia.

Kesesuaian

Pernyataan	Spesifikasi	Klausul	reference_id
Digest byte-range mencakup berkas dan tidak menyertakan nilai tanda tangan.	ISO 32000-2	§12.8.1
Contents menyimpan CMS SignedData yang dienkode DER.	ISO 32000-2	§12.8.1
Untuk stempel waktu, hash byte-range dikirim ke TSA dan token ditempatkan di Contents.	ISO 32000-2	§12.8.5
Stempel waktu B-T adalah atribut tidak bertanda tangan pada SignerInfo.	RFC 5652	§5.3
Atribut tidak bertanda tangan tidak mengubah digest bertanda tangan/validitas B-B.	RFC 5652	§5.3
Nilai signature-time-stamp adalah SignatureTimeStampToken.	ETSI EN 319 122-1	§5.3

NextPDF menghasilkan struktur tanda tangan. NextPDF tidak mengklaim bahwa tanda tangan yang dihasilkan mana pun sesuai atau sah secara hukum; penetapan tersebut dilakukan oleh validator independen. Tool ini tidak menghasilkan B-LT/B-LTA.

Konteks komersial

sign_pdf adalah tool tingkat Pro. Server mendaftarkannya hanya ketika paket Pro berhasil di-resolve saat boot server. Level jangka panjang PAdES (B-LT, B-LTA) dan materi validasinya (DSS, VRI, LTV) bersifat khusus Enterprise dan tidak diekspos oleh tool ini atau resep ini.

Residensi data & mitigasi PII

Sertifikat dan kunci privat dikirim melalui permintaan. Gunakan amplop AES-GCM transport_encryption pada kanal apa pun yang tidak rahasia secara ujung-ke-ujung. PDF yang ditandatangani dan identitas penanda tangan (signer_name, reason) adalah konten dokumen, jadi simpanlah keduanya dalam batas residensi data Anda. Integrator bertanggung jawab atas residensi pada tingkat deployment.

Telemetri aman & pembersihan log

Jangan pernah mencatat muatan private_key, key/nonce AES-GCM, atau token konfirmasi. Catat algoritme, level hasil, dan signature_count, bukan materi kunci. Tool tidak mengeluarkan byte kunci dalam hasilnya.

Model ancaman

Ancaman yang dipertimbangkan: pengungkapan kunci saat transit (dimitigasi oleh amplop AES-GCM dan penyedia TSA yang diinjeksikan oleh host serta tidak dapat dikonfigurasi melalui permintaan); pemanggil MCP yang mencoba mengarahkan stempel waktu ke endpoint sembarang (dicegah karena penyedia diinjeksikan oleh host, bukan dapat dikonfigurasi melalui permintaan); dan perusakan pascapenandatanganan (digest byte-range mendeteksi modifikasi). Model ancaman ini mendokumentasikan ancaman yang dipertimbangkan dan mitigasinya; model ini tidak menegaskan ketiadaan kerentanan.

Perilaku mode FIPS

Pemilihan algoritme (RSA-SHA256, RSA + SHA-3, Ed25519) ditentukan oleh permintaan. OpenSSL pada host menyediakan primitif kriptografi. Dalam deployment yang dibatasi FIPS, batasi algoritme di lapisan kebijakan dan andalkan modul tervalidasi milik host. Tool ini sendiri tidak mengklaim validasi Federal Information Processing Standards (FIPS).

Ketersediaan transport

Transport	Tersedia	Catatan
MCP (stdio)	Ya (Pro)	Gunakan amplop kunci AES-GCM pada stdio.
REST	Ya (Pro)	Utamakan TLS ditambah amplop kunci.
gRPC	Ya (Pro)	Utamakan TLS ditambah amplop kunci.

Tingkat risiko HITL

sign_pdf bersifat Approval Required karena merupakan operasi destruktif yang tidak dapat dibatalkan; tool ini mengiklankan petunjuk destruktif. Gerbang konfirmasi berlaku seperti pada tool Approval Required mana pun. output_pdf ke berkas juga bersifat Approval Required; mode base64 bersifat Review (tingkat risiko HITL).

Amplop JSON gerbang konfirmasi

sign_pdf tanpa token yang valid mengembalikan amplop tantangan:

{
  "allowed": false,
  "challenge": "⚠️ CONFIRMATION REQUIRED\n\nOperation: sign_pdf\nDescription: <tool description>\n\nTo proceed, call sign_pdf again with parameter _confirmation_token: \"confirm_<single-use-hex>\"\nExpires in 300 seconds.",
  "token": "confirm_<single-use-hex>"
}

Panggil kembali dengan _confirmation_token disetel ke token tersebut → { "allowed": true }. Alur lengkap: output-approval.

Lihat juga

• Ekstrak konten teks
• Pemeriksaan aksesibilitas
• Tingkat risiko HITL
• Katalog tool