Penandatanganan berbasis HSM

Spec: ISO 32000-2, §12.8 Spec: FIPS 140-3 Evidence: Standard-backed

Sekilas pandang

Hardware security module (HSM) memindahkan kunci penandatanganan keluar dari proses Anda dan menempatkannya di balik perangkat yang menandatangani saat diminta, tetapi tidak pernah mengembalikan kuncinya. Halaman ini menjelaskan seam PKCS#11 tempat NextPDF menandatangani, letak persis batas kunci, dan bagian hasil mana yang menjadi tanggung jawab mesin, bukan tanggung jawab perangkat atau Anda.

Mengapa ini penting

Kunci penandatanganan yang berada di memori proses terekspos ke apa pun yang dapat membaca proses tersebut: heap dump, debugger, kesalahan pencatatan log, atau dependensi yang rentan. Begitu kunci privat disalin, setiap tanda tangan yang pernah dibuatnya menjadi diragukan, dan Anda tidak dapat membuatnya rahasia kembali. Inti dari HSM adalah tidak ada salinan yang bisa diambil.

Salah menempatkan batas itu diam-diam mahal. Alur kerja yang tampak didukung perangkat keras tetapi menarik kunci ke memori untuk menandatangani menanggung biaya operasional sebuah HSM sekaligus profil risiko kunci perangkat lunak. Perbedaan ini tidak terlihat pada PDF yang sudah jadi, jadi batas tersebut harus dirancang sejak awal dan diverifikasi, bukan diasumsikan.

Versi singkatnya

Standar PKCS#11 mendefinisikan objek kunci yang ditandai sensitif dan non-extractable. Nilai privatnya tidak dapat diungkapkan dalam bentuk teks biasa di luar token. Spec: PKCS#11, v3.1 §10.9
NextPDF membangun struktur tanda tangan PDF dan kontainer CMS. Ia menyerahkan byte yang akan ditandatangani melalui seam PKCS#11 dan menerima kembali tanda tangannya. Kunci tidak pernah melewati seam itu.
Seam ini adalah kontrak yang stabil. Kontrak yang sama dipenuhi oleh token smart-card, USB HSM, network HSM, dan cloud KMS. Kode mesin tidak berubah di antara semuanya.
NextPDF adalah perangkat lunak mesin penandatanganan. Jaminan perangkat tersebut, status validasinya, kebijakan PIN, dan penyebarannya bukan hal-hal yang disertifikasi oleh mesin. Mesin ini menggunakan perangkat tersebut; ia tidak menjaminnya.

Bagaimana NextPDF menanganinya

Seam-nya secara persis

NextPDF memisahkan perakitan tanda tangan dari penghitungan nilai tanda tangan. Perakitan adalah tugas mesin: menempatkan kolom tanda tangan, mencadangkan ruang di berkas, menghitung byte range, dan membangun CMS SignedData beserta atribut bertanda tangannya. Spec: ISO 32000-2, §12.8

Penghitungan nilai tanda tangan didelegasikan. Mesin mendefinisikan kontrak penyedia penandatanganan yang kecil: ia menerima urutan byte buram (dalam praktiknya berupa atribut bertanda tangan yang dikodekan DER), lalu mengembalikan oktet tanda tangan mentah. Kontrak itulah seam-nya. Pengetahuan tentang PDF dan CMS tetap di satu sisi; kunci tetap di sisi yang lain. Penyedia dapat menyimpan kunci itu di dalam proses untuk kunci perangkat lunak lokal, di cloud KMS, atau pada token perangkat keras melalui PKCS#11. Kode mesin di atas seam itu identik dalam setiap kasus. Hanya penyedia di baliknya yang berbeda.

Di mana batas itu sebenarnya berada

PKCS#11 — OASIS Cryptographic Token Interface, yang secara historis disebut “Cryptoki” — adalah antarmuka C standar untuk token perangkat keras. Jalur perangkat keras milik NextPDF berbicara PKCS#11 (secara langsung, atau melalui jembatan command-line OpenSSL untuk penyebaran engine atau provider di mana binding dalam-proses tidak dapat memuat sebuah token).

Objek kunci pada token dibuat dengan dua atribut yang mendefinisikan batas tersebut. Ketika kunci ditandai sensitif, atau ditandai non-extractable, atribut privat tertentu tidak dapat diungkapkan dalam bentuk teks biasa di luar token. Spec: PKCS#11, v3.1 §10.9 Operasi penandatanganan itu sendiri adalah satu panggilan token tunggal — C_SignInit lalu C_Sign — yang dilakukan oleh perangkat. Spec: PKCS#11, v3.1 §5.10 Teks biasa yang ditangani NextPDF untuk operasi penandatanganan adalah byte yang akan ditandatangani. Yang dikembalikan adalah tanda tangan dan sertifikat. Kunci privat tidak berada di jalur mana pun. Itulah batasnya, dan token-lah yang menegakkannya, bukan pustaka.

Step 1 of 4: ISO 32000-2 §12.8 — signature dictionary, ByteRange, Contents
Step 2 of 4: RFC 5652 CMS SignedData — the signature container
Step 4 of 4: FIPS 140-3 / ISO/IEC 19790 cryptographic module assurance (device-level, deployment-dependent)

Tempat sebuah tanda tangan PDF yang didukung perangkat keras berlandas, secara berurutan: pembawa PDF (ISO 32000-2 §12.8), kontainer CMS yang ditampungnya, antarmuka token yang menjadi tempat NextPDF menandatangani (PKCS#11), dan standar jaminan modul yang menggambarkan — tetapi tidak dengan sendirinya menjamin — perangkat di baliknya.

Satu PIN, satu autentikasi ulang

PKCS#11 memungkinkan sebuah kunci mensyaratkan autentikasi ulang untuk setiap penggunaan: ketika atribut CKA_ALWAYS_AUTHENTICATE disetel, pengguna harus memasukkan PIN lagi untuk setiap operasi kriptografis, bukan sekali per sesi. Spec: PKCS#11, v3.1 §10.9 Jalur PKCS#11 milik NextPDF ditulis untuk ini. PIN adalah parameter yang sensitif. Ia tidak dicatat dalam log maupun diserialisasi. Ketika sesi melaporkan login yang sudah ada, NextPDF mengembalikannya ke keadaan bersih sehingga tanda tangan berikutnya mendapatkan pemeriksaan PIN baru. Ini penting untuk token bergaya PIV yang kebijakannya menuntut PIN per tanda tangan. Ini adalah perilaku mesin yang menghormati kebijakan perangkat; ia tidak melonggarkannya.

Apa yang dikatakan bukti

Evidence: Standard-backed Properti kunci non-extractable bukan klaim NextPDF. Itu adalah model PKCS#11: sebuah objek kunci yang CKA_SENSITIVE-nya bernilai true atau CKA_EXTRACTABLE-nya bernilai false tidak akan menghasilkan nilai privatnya dalam bentuk teks biasa di luar token. Spec: PKCS#11, v3.1 §10.9 Kontribusi NextPDF adalah bahwa ia tidak pernah membutuhkan nilai itu: ia menandatangani melalui operasi C_Sign milik token alih-alih meminta materi kunci.

Evidence: Standard-backed Sisi PDF berlandas pada Spec: ISO 32000-2, §12.8 . Digest byte range dihitung atas berkas dengan mengecualikan nilai tanda tangan. Nilai tanda tangan yang ditempatkan dalam entri Contents adalah objek CMS SignedData yang dikodekan DER untuk tanda tangan kunci publik. HSM hanya menghasilkan oktet tanda tangan yang paling dalam. NextPDF membangun semua yang mengelilinginya dan menuliskannya ke dalam struktur yang didefinisikan standar.

Evidence: Standard-backed Jaminan perangkat dijelaskan oleh Spec: FIPS 140-3 dan standar dasarnya ISO/IEC 19790, yang mendefinisikan empat tingkat keamanan kualitatif yang meningkat di sebelas area persyaratan — mulai dari spesifikasi algoritma hingga bukti perusakan fisik. Standar-standar ini menjelaskan apa yang harus dipenuhi sebuah modul untuk mengklaim tingkat tertentu. Itu adalah properti dari perangkat dan validasinya, bukan dari NextPDF, dan — dalam rumusan ISO/IEC 19790 itu sendiri — konformitas tidak dengan sendirinya cukup untuk memastikan modul aman dalam suatu penyebaran tertentu.

Contoh praktis

Bentuk di bawah ini bersifat ilustratif. Ia menunjukkan seam-nya, bukan penyebaran siap salin-tempel. Intinya, mesin diberi penanda tangan dan tidak pernah melihat kunci: sign() milik penanda tangan adalah panggilan ke dalam perangkat.

<?php

declare(strict_types=1);

use NextPDF\Contracts\HsmSignerInterface;

/**
 * Sign a PDF where the private key lives on a PKCS#11 token.
 *
 * `$hsm` is a hardware-backed signer. Its sign() delegates to the token;
 * the key never enters this process. Everything that makes the bytes a
 * valid PDF signature — field, byte range, CMS SignedData — is built by
 * the engine around the value the device returns.
 *
 * Token wiring (library path, slot, PIN, key label) is deployment
 * configuration and is intentionally out of scope here: those values are
 * operator-owned secrets, not library inputs to hardcode.
 */
function signWithToken(
    string $pdfPath,
    HsmSignerInterface $hsm,
): string {
    // The engine asks the signer only for: the certificate (to embed in
    // the CMS) and a signature over the bytes it computes. It never asks
    // for, and the contract never exposes, the private key.
    $certificateDer = $hsm->getCertificateDer();
    $chainDer       = $hsm->getCertificateChainDer();

    // Pseudocode for the engine's own assembly step: build the signature
    // dictionary + CMS SignedData, then hand the signed-attributes bytes
    // to $hsm->sign(...) and place the returned octets in /Contents.
    return nextpdf_sign_pdf(
        pdfPath: $pdfPath,
        signer: $hsm,
        certificateDer: $certificateDer,
        chainDer: $chainDer,
    );
}

Dua catatan jujur tentang bentuk ini. Binding PKCS#11 dalam-proses adalah ekstensi PHP terpisah yang tidak disertakan oleh build PHP standar. Penyebaran perangkat keras memasang dan memverifikasinya (atau menggunakan jembatan command-line OpenSSL) sebagai bagian dari platform, bukan sebagai sesuatu yang baru dipikirkan belakangan. Dan algoritma yang diminta dari perangkat haruslah algoritma yang benar-benar dapat dilakukan oleh kunci tersebut. Mesin menolak lebih awal ketika algoritma yang dikonfigurasi tidak memiliki pemetaan untuk penyedia yang dipilih, alih-alih gagal jauh di dalam panggilan token.

Kesalahpahaman umum

“Menggunakan sebuah HSM berarti penandatanganannya tervalidasi FIPS.”

Tidak. Menyamakan keduanya adalah jebakannya. HSM adalah tempat kunci berada dan operasi berjalan. Validasi FIPS 140-3 / ISO/IEC 19790 adalah properti yang mungkin dimiliki oleh perangkat (atau konfigurasi modul tertentu), ditetapkan oleh program validasi — bukan sesuatu yang diberikan oleh pustaka pemanggil dan bukan sesuatu yang diklaim NextPDF atas nama sebuah perangkat. NextPDF kompatibel dengan penandatanganan melalui perangkat PKCS#11 dan jalur penandatanganannya telah diuji dengan token yang mewakili kategorinya. Apakah suatu penyebaran tervalidasi pada tingkat modul FIPS sepenuhnya bergantung pada perangkat keras, sertifikatnya, dan bagaimana ia dikonfigurasi serta dioperasikan. Gunakan istilah yang tepat untuk apa yang benar-benar Anda miliki.

Batas dan ruang lingkup

Halaman ini menjelaskan seam dan standar yang menjadi landasannya. Ini bukan jaminan penyebaran, dan batasnya perlu dinyatakan dengan jelas:

Tanggung jawab mesin. Membangun kolom tanda tangan, mencadangkan ruang, menghitung byte range, merakit CMS SignedData, memanggil penyedia penandatanganan, dan menuliskan tanda tangan yang benar secara struktural sesuai Spec: ISO 32000-2, §12.8 . Jalur perangkat keras milik NextPDF sesuai dengan antarmuka penandatanganan PKCS#11 untuk tujuan ini.
Tanggung jawab perangkat dan operator. Ketahanan perangkat keras terhadap perusakan, status validasi FIPS 140-3 / ISO/IEC 19790-nya, pembangkitan dan penyimpanan kunci, kebijakan PIN, konfigurasi slot, firmware, dan keamanan fisik. Tidak satu pun hal ini disertifikasi oleh mesin.
Diuji dengan bukan berarti tersertifikasi. Bahwa NextPDF memiliki jalur terverifikasi terhadap kategori token yang representatif — bentuk smart-card, USB, jaringan, dan cloud-KMS yang dijangkau melalui kontrak PKCS#11 yang sama — adalah pernyataan kompatibilitas. Itu bukan sertifikasi, jumlah modul tervalidasi, atau klaim tentang perangkat spesifik Anda. Kategori perangkat keras di bawah ini adalah bentuk integrasi melalui satu antarmuka standar. Perlakukan mereka sebagai “tempat seam telah dilatih”, jangan pernah sebagai jaminan untuk model yang belum Anda uji sendiri.
Penandatanganan pasca-kuantum bersifat eksperimental. Ketika mesin mengekspos penandatanganan pasca-kuantum melalui sebuah token, hal itu bersifat opt-in, di-gate, dan divalidasi terhadap mock alih-alih firmware HSM pasca-kuantum. Katalog jaringan kriptografis PAdES dan AdES belum mengenali jaringan tersebut untuk pengarsipan jangka panjang. Jangan perlakukan ini sebagai siap produksi.

HSM-backed signing via PKCS#11 — edition availability
Edition	Availability
Core	Tidak tersedia di edisi ini. Core menyediakan mesin penandatanganan dan seam penyedia-penandatanganan, dengan penyedia kunci-perangkat-lunak lokal.
Pro	Manajemen kunci cloud — penandatanganan melalui kunci KMS terkelola — adalah kapabilitas Pro yang hanya dijelaskan pada tingkat perilaku.
Enterprise	Tersedia. Penandatanganan token perangkat keras melalui antarmuka PKCS#11 (dan sebuah jembatan command-line OpenSSL untuk penyebaran engine/provider) adalah kapabilitas Enterprise. Ketersediaan adalah pernyataan kapabilitas, bukan sertifikasi perangkat atau penyebaran apa pun.

Bentuk integrasi melalui satu antarmuka

Ini adalah bentuk yang telah digunakan untuk melatih seam PKCS#11. Kolomnya menunjukkan “seperti apa integrasinya terlihat”, bukan “daftar perangkat yang tervalidasi, tersertifikasi, atau dihitung”.

Bentuk integrasi	Cara ia dijangkau	Batas kunci	Jaminan adalah properti dari
Token smart-card / PIV	Modul PKCS#11; PIN per penggunaan lazim	Pada kartu; non-extractable	Kartu dan operatornya
USB HSM	Modul PKCS#11	Pada perangkat; non-extractable	Perangkat dan operatornya
Network / appliance HSM	Modul PKCS#11 ke perangkat jaringan	Pada appliance; non-extractable	Appliance, konfigurasinya, operator
Cloud KMS	Penyedia kunci terkelola (Pro)	Di dalam layanan cloud; tidak pernah dikembalikan	Penyedia cloud dan atestasinya
Jembatan provider OpenSSL	PKCS#11 melalui jembatan OpenSSL	Pada token; non-extractable	Token dan operatornya

Mini-FAQ

Apakah kunci pernah masuk ke proses PHP? Tidak. Untuk kunci PKCS#11 non-extractable, nilai privatnya tidak dapat diungkapkan dalam bentuk teks biasa di luar token. NextPDF menandatangani melalui operasi token dan hanya melihat byte yang akan ditandatangani serta tanda tangan yang dikembalikan.

Apakah tanda tangan yang didukung HSM berbeda di dalam PDF? Tidak. Struktur tanda tangannya adalah CMS SignedData yang sama dalam entri Contents yang sama atas byte range yang sama. HSM mengubah di mana penandatanganan terjadi, bukan bentuknya di disk.

Bisakah saya mengklaim kepatuhan FIPS karena saya menggunakan HSM melalui NextPDF? Hanya dengan kehati-hatian. NextPDF tidak menyatakan apa pun tentang status FIPS sebuah perangkat. Klaim semacam itu harus berasal dari validasi perangkat itu sendiri dan bagaimana ia disebarkan, bukan dari fakta bahwa NextPDF memanggilnya.

Bagaimana jika binding PKCS#11 dalam-proses tidak tersedia? Mesin melaporkan bahwa penandatanganan perangkat keras tidak tersedia alih-alih secara diam-diam beralih ke kunci perangkat lunak. Jalur jembatan command-line OpenSSL tersedia untuk penyebaran di mana binding dalam-proses tidak dapat memuat token.

Dokumen terkait

Tanda tangan berkualifikasi, dijelaskan — kapan kunci perangkat keras diperlukan tetapi belum memadai, dan peran-peran yang bukan merupakan peran NextPDF.
Bagaimana tanda tangan tersimpan di dalam PDF — mekanisme byte-range dan kamus tanda tangan tempat hasil HSM dituliskan.
Mengoperasikan NextPDF di produksi — permukaan operasional yang harus ditanggung oleh penyebaran penandatanganan perangkat keras.

Glosarium

HSM (hardware security module) — perangkat yang diperkeras yang menyimpan kunci dan melakukan operasi kriptografis sehingga materi kunci tidak pernah meninggalkannya.
PKCS#11 — standar OASIS Cryptographic Token Interface (yang secara historis disebut “Cryptoki”); antarmuka C yang digunakan NextPDF untuk berbicara dengan token perangkat keras.
Kunci non-extractable — objek kunci PKCS#11 yang nilai privatnya tidak dapat diungkapkan dalam bentuk teks biasa di luar token (CKA_SENSITIVE true atau CKA_EXTRACTABLE false).
Seam — batas penyedia-penandatanganan di dalam NextPDF: byte buram masuk, oktet tanda tangan keluar. Pengetahuan tentang PDF dan CMS berada di atasnya; kunci berada di baliknya.
CMS SignedData — struktur Cryptographic Message Syntax (RFC 5652) yang membawa tanda tangan dan sertifikat di dalam PDF.
FIPS 140-3 / ISO/IEC 19790 — standar keamanan modul kriptografis yang mendefinisikan empat tingkat kualitatif; properti dari perangkat dan validasinya, bukan dari pustaka pemanggil.