Lewati ke konten
getnextpdf.com

Enterprise edisi

Keamanan — Referensi Mendalam (HSM, PKCS#11, mode FIPS)

Halaman ini adalah referensi mendalam gabungan untuk permukaan keamanan NextPDF Enterprise. Halaman ini mencakup penandatanganan token perangkat keras melalui PKCS#11, penandatanganan subproses melalui antarmuka baris perintah (CLI) OpenSSL, preset kebijakan kripto FIPS, guard FIPS runtime, dan guard self-test power-on. Ada dua pendamping yang terfokus: HSM — Referensi Mendalam untuk detail signer dan FIPS 140 — Referensi Mendalam untuk detail modul FIPS. Jalur penandatanganan pasca-kuantum adalah pratinjau tanpa klaim konformansi apa pun. NextPDF tidak memegang sertifikasi apa pun dan tidak memberikannya; dukungan tidak sama dengan konformansi, dan konformansi tidak sama dengan sertifikasi.

Kapabilitas ini disertakan dalam NextPDF Enterprise (nextpdf/enterprise) dan aktif dengan envelope lisensi tier Enterprise. Deployment tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Bandingkan edisi dan dapatkan lisensi.

Terminal window
composer require nextpdf/enterprise:^3

Tipe-tipe penandatanganan berada di NextPDF\Enterprise\Security\Signature\Hsm; tipe-tipe FIPS berada di NextPDF\Enterprise\Security\Fips; composition root berada di NextPDF\Enterprise\Bootstrap. Kedua signer mengimplementasikan kontrak Core NextPDF\Contracts\HsmSignerInterface. Kebijakan mengimplementasikan kontrak Core NextPDF\Contracts\CryptoPolicyInterface dan NextPDF\Contracts\PreOperationalSelfTestInterface.

SimbolParameterPerilaku defaultMengembalikanMelempar atau gagal denganCatatan
Pkcs11Signer::__construct()string $libraryPath, int $slotId, string $pin, string $certLabel, ?string $keyLabel = null, array $chainDer = [], bool $enablePostQuantum = false, ?FipsSignatureEnforcer $fipsEnforcer = nullMembuka library vendor, login ke slot, memuat metadata sertifikat dan algoritma kunciHsmOperationException ketika ext-pkcs11 tidak ada atau akses token gagalPIN dan label bersifat #[SensitiveParameter]; satu handle modul di-cache per jalur library per proses
Pkcs11Signer::isAvailable()Tidak adaMelaporkan apakah ext-pkcs11 dimuatboolTidak adaStatis; periksa sebelum konstruksi
Pkcs11Signer::sign()string $data, string $algorithm = 'sha256WithRSAEncryption'Menandatangani di token; keluaran ECDSA mentah dikonversi ke DER ECDSA-Sig-Valuestring byte tanda tangan mentahHsmOperationException (kunci tidak ditemukan, kegagalan token); InvalidArgumentException (algoritma tidak terpetakan); FipsViolationException / FipsModuleErrorStateException sebelum penandatanganan ketika enforcer terpasangHimpunan algoritma tertutup; lihat Kontrak perilaku
Pkcs11Signer::signPqs()string $data, Pkcs11PqsAlgorithm $algorithm, string $context = '', bool $randomized = trueDitolak kecuali $enablePostQuantum disetel; mengirim mekanisme pasca-kuantum PKCS#11 provisionalstring byte tanda tangan mentahHsmOperationException (dinonaktifkan, kegagalan token, ketidakcocokan panjang tanda tangan); InvalidArgumentException (konteks lebih dari 255 byte)Pratinjau; tanpa klaim konformansi
Permukaan accessor Pkcs11SignerTidak adaHasil konstruksi read-onlybool / string / array<string>Tidak adaisPostQuantumEnabled, getCertificateDer, getCertificateChainDer, getPublicKeyAlgorithm
OpenSslCliSigner::__construct()string $keyUri, string $certPath, string $pin, array $extraCertPaths = [], OpenSslCliBackend $backend = OpenSslCliBackend::Auto, string $opensslBinary = 'openssl', int $timeoutSeconds = 30, ?string $modulePath = null, ?string $configPath = null, bool $legacyPinDelivery = false, ?FipsSignatureEnforcer $fipsEnforcer = nullMemverifikasi proc_open, menyelidiki binary, menyelesaikan backend, memuat sertifikatHsmOperationException (proc_open dinonaktifkan, file modul/config/sertifikat hilang, tidak ada backend); InvalidArgumentException (pin-value di dalam $keyUri)Auto mengutamakan provider OpenSSL 3.x, lalu engine
OpenSslCliSigner::sign()string $data, string $algorithm = 'sha256WithRSAEncryption'Menandatangani dalam subproses openssl; PIN melewati file pin-source 0600 ephemeral secara defaultstring byte tanda tangan mentahHsmOperationException (timeout, PIN ditolak, kunci tidak ditemukan, keluaran kosong); InvalidArgumentException (algoritma tidak terpetakan); eksepsi FIPS-gate sebelum penandatangananSubproses dihentikan setelah $timeoutSeconds; stderr diredaksi
Permukaan accessor OpenSslCliSignerTidak adaHasil konstruksi read-onlystring / array<string> / OpenSslCliBackendTidak adagetCertificateDer, getCertificateChainDer, getPublicKeyAlgorithm, getCertificatePem, getResolvedBackend, getOpensslVersion
OpenSslCliBackendEnum: Provider, Engine, AutoTidak adaPemilihan backend untuk signer CLI
Pkcs11PqsAlgorithmEnum dari set parameter ML-DSA dan SLH-DSATidak adaHelper: isMlDsa, isSlhDsa, mechanismId, parameterSetId, signatureLength, nistCategory
PqsCapabilityStatus::current()Tidak adaMembangun postur pasca-kuantum yang jujur untuk prosesPqsCapabilityStatusTidak adaSetiap boolean klaim konformansi di-hard-code false; tidak ada flag yang dapat mengaktifkannya
HsmSignerProviderAdapterHsmSignerInterface $hsm, string $providerId, SignatureAlgorithm $algorithm = SignatureAlgorithm::Pkcs1v15Mengekspos konkret HSM sebagai SignerProviderInterface terpaduPer SPIKeyManagementException (versi kunci non-null); SignatureFailedException (kegagalan driver, tanda tangan kosong)Id provider: pkcs11-{module-id}, openssl-cli
HsmOperationExceptionKegagalan bertipe untuk setiap jalur penandatanganan HSMMemperluas Core NextPdfException
FipsCryptoPolicy::strict() / ::standard()?FipsSelfTest $selfTest = nullPreset factory; strict adalah profil FIPS 140-3, standard menambahkan AES-128-CBCFipsCryptoPolicyTidak adaAllow-list imutabel; lihat Perilaku mode FIPS
Permukaan predikat FipsCryptoPolicyInput string / intPemeriksaan keanggotaan allow-listbool / stringTidak adaisHashAlgorithmAllowed, isSignatureAlgorithmAllowed, isEncryptionAlgorithmAllowed, isKeyStrengthAllowed, getPreferredHashAlgorithm, getName
FipsCryptoPolicy::assertPreOperational()Tidak adaMenjalankan (atau memutar ulang) self-test power-onvoidFipsModuleErrorStateExceptionDijalankan oleh seam enforcement Core pada operasi kriptografis pertama
FipsModeGuard::__construct()CryptoPolicyInterface $policy, ?FipsBootGuard $bootGuard = null, ?FipsAuditLogger $auditLogger = nullMembungkus kebijakan dengan batas bergaya assertTidak adaTanpa boot guard, gate self-test tidak ada (hanya kebijakan)
Permukaan assert FipsModeGuardInput string / intKatalog deny terlebih dahulu, lalu allow-list; catatan audit sebelum setiap throwvoidFipsViolationException; FipsModuleErrorStateException (boot guard terpasang)assertHashAllowed, assertSignatureAlgorithmAllowed, assertEncryptionAllowed, assertKeyStrengthAllowed, ditambah getPolicy
FipsBootGuard::report() / ::rerun()Tidak adaMenjalankan baterai self-test (di-cache / dipaksa)FipsSelfTestReportTidak adaLaporan ERROR mengunci proses; re-run yang lolos tidak pernah membersihkan kunci
FipsBootGuard::assertOperational()Tidak adaMenegaskan modul dalam keadaan OPERATIONALvoidFipsModuleErrorStateExceptionSticky: ERROR yang terkunci pada proses menolak bahkan instance yang bersih
FipsBootGuard::status()Tidak adaMelaporkan status yang di-cacheFipsSelfTestStatusTidak adaPRE_OPERATIONAL, OPERATIONAL, atau ERROR
FipsSelfTest::run()Tidak adaMengeksekusi baterai known-answer-test penuh; tidak pernah short-circuitFipsSelfTestReportTidak adaKonstruktor menerima provider hash dan random-bytes yang dapat diinjeksi untuk tes deterministik
FipsSelfTestReport / FipsSelfTestResult / FipsSelfTestStatusValue object laporan dan enum statusFipsSelfTestReport::assertOperational() melempar FipsModuleErrorStateExceptionresults selalu mencantumkan setiap hasil untuk bukti audit
FipsSignatureEnforcer::assertSignatureGenerationAllowed()string $algorithm, string $certificatePemMenyelesaikan OID tanda tangan dan kekuatan kunci, lalu mendelegasikan ke guardvoidFipsViolationException (tidak diizinkan atau tidak terklasifikasi, fail-closed)Titik hambatan yang dipanggil kedua signer di awal sign() dalam mode FIPS
FipsAuditLoggerCryptoPolicyInterface $policy, LoggerInterface $loggerMemancarkan catatan ALLOW (INFO) / DENY (WARNING) per keputusanbool per panggilan logTidak adalogHashOperation, logSignatureOperation, logEncryptionOperation, logKeyStrengthCheck
FipsTransitioningAlgorithmsInput string / intKatalog deny statis NIST SP 800-131Abool / arrayTidak adaLapisan explicit-deny di bawah setiap batas guard
FipsBootstrap::boot() / ::lazy()?CryptoPolicyInterface $policy = null, ?FipsSelfTest $selfTest = null, ?LoggerInterface $auditLogger = nullMenyusun boot guard, kebijakan, dan mode guard; boot() menjalankan self-test seketika, lazy() menundanya ke batas pertamaFipsModeGuardboot(): FipsModuleErrorStateException pada tes yang gagalDefault ke kebijakan strict
FipsBootstrap::signatureEnforcer()?CryptoPolicyInterface $policy = null, ?FipsSelfTest $selfTest = nullMem-boot modul dan mengembalikan gate waktu-pembuatan untuk signerFipsSignatureEnforcerFipsModuleErrorStateExceptionBerikan hasilnya ke parameter $fipsEnforcer sebuah signer
FipsBootstrap::selfTestReport()?FipsSelfTest $selfTest = nullMenjalankan baterai sesuai permintaan dan meringkasnyaarray{status, operational, failed}Tidak adaDitujukan untuk endpoint health dan subperintah CLI
FipsViolationException / FipsModuleErrorStateExceptionKegagalan FIPS bertipeMengekspos masing-masing policyName / violatingItem / reason dan failedResults
public function __construct(private readonly string $libraryPath, private readonly int $slotId, #[SensitiveParameter] private readonly string $pin, #[SensitiveParameter] private readonly string $certLabel, #[SensitiveParameter] private readonly ?string $keyLabel = null, array $chainDer = [], private readonly bool $enablePostQuantum = false, ?FipsSignatureEnforcer $fipsEnforcer = null)
public static function isAvailable(): bool
public function sign(string $data, string $algorithm = 'sha256WithRSAEncryption'): string
public function signPqs(string $data, Pkcs11PqsAlgorithm $algorithm, string $context = '', bool $randomized = true): string
public function __construct(private string $keyUri, string $certPath, #[SensitiveParameter] private string $pin, array $extraCertPaths = [], private OpenSslCliBackend $backend = OpenSslCliBackend::Auto, private string $opensslBinary = 'openssl', private int $timeoutSeconds = 30, private ?string $modulePath = null, private ?string $configPath = null, private bool $legacyPinDelivery = false, private ?FipsSignatureEnforcer $fipsEnforcer = null)
public function sign(string $data, string $algorithm = 'sha256WithRSAEncryption'): string
public static function strict(?FipsSelfTest $selfTest = null): self
public static function standard(?FipsSelfTest $selfTest = null): self
public function assertPreOperational(): void
public function __construct(private CryptoPolicyInterface $policy, private ?FipsBootGuard $bootGuard = null, private ?FipsAuditLogger $auditLogger = null)
public function assertHashAllowed(string $algorithm): void
public function assertSignatureAlgorithmAllowed(string $oid): void
public function assertEncryptionAllowed(string $algorithm): void
public function assertKeyStrengthAllowed(string $keyType, int $bitLength): void
public function getPolicy(): CryptoPolicyInterface
public static function boot(?CryptoPolicyInterface $policy = null, ?FipsSelfTest $selfTest = null, ?LoggerInterface $auditLogger = null): FipsModeGuard
public static function lazy(?CryptoPolicyInterface $policy = null, ?FipsSelfTest $selfTest = null, ?LoggerInterface $auditLogger = null): FipsModeGuard
public static function signatureEnforcer(?CryptoPolicyInterface $policy = null, ?FipsSelfTest $selfTest = null): FipsSignatureEnforcer
public static function selfTestReport(?FipsSelfTest $selfTest = null): array
  • Resolusi kontrak. Kedua signer mengimplementasikan Core HsmSignerInterface; kebijakan mengimplementasikan Core CryptoPolicyInterface. Kode pemanggil bergantung pada kontrak, sehingga peningkatan edisi mengubah komposisi, bukan call site.
  • Kustodian kunci. Kunci privat tidak pernah meninggalkan batas token. Pkcs11Signer mendelegasikan operasi ke token; OpenSslCliSigner meneruskan referensi kunci URI PKCS#11 ke subproses. NextPDF tidak menyimpan, membuat, atau menjamin keamanan kunci penandatanganan. Perlindungan kunci adalah tanggung jawab kustodian operator (NIST SP 800-57 Part 1 Rev.5 §5.5.2).
  • Sesi dan login. Operasi sign token, sesi, dan login pengguna mengikuti PKCS#11 v3.1 §5. Label sertifikat dan label kunci privat boleh berbeda; konstruktor menerima label kunci terpisah untuk token semacam itu.
  • Himpunan algoritma tertutup. Signer menerima persis: RSA PKCS#1 v1.5 dengan SHA-256/384/512, RSASSA-PSS dengan SHA-256/384/512, dan ECDSA dengan SHA-256/384/512 (Pkcs11Signer juga menerima ecdsa-raw). Identifier lain apa pun memunculkan InvalidArgumentException; tidak ada algoritma pengganti yang pernah ditandatangani.
  • Pengikatan salt PSS. Untuk setiap varian PSS, panjang salt sama dengan panjang digest — 32, 48, atau 64 byte — dan parameter hash serta mask-generation cocok dengan digest yang dipilih (PKCS#11 v3.1 §5).
  • Konversi ECDSA. Mekanisme ECDSA token mengembalikan tanda tangan mentah; sign() mengonversinya ke bentuk ECDSA-Sig-Value yang diberkode DER untuk interoperabilitas PDF dan OpenSSL. Pembuatan tanda tangan mengikuti FIPS 186-5 §6.3.2.
  • Isi preset. Preset strict mengizinkan SHA-256/384/512; OID tanda tangan RSA dan ECDSA dengan hash tersebut; RSASSA-PSS; AES-256-CBC dan AES-256-GCM; minimum RSA 2048 dan EC 256. Preset standard tambahan mengizinkan AES-128-CBC untuk interoperabilitas legacy. Setiap penggunaan AES-GCM memerlukan initialization vector yang unik per kunci (NIST SP 800-38D §5).
  • Enforcement dua lapis. Setiap batas guard berkonsultasi ke katalog deny eksplisit NIST SP 800-131A terlebih dahulu, lalu allow-list kebijakan. Lapisan deny menghasilkan sinyal “disallowed” yang audit-clear; allow-list tetap otoritatif.
  • Self-test power-on. Baterai mencakup SHA-256/384/512, HMAC-SHA-256, AES-256-CBC, AES-256-GCM, tes pairwise-consistency ECDSA P-256, dan pemeriksaan kesehatan random-bit. Operasi kriptografis pertama di bawah kebijakan pada jalur Core menjalankannya sekali per proses, fail-closed. Kegagalan menempatkan modul dalam keadaan ERROR; layanan kriptografis ditolak hingga di-reset. Ini mengikuti ISO/IEC 19790:2025 §7.10, §7.10.2, §7.10.3, dan §7.10.3.p3.
  • Keadaan ERROR yang sticky. ERROR yang teramati terkunci untuk seluruh proses. Membangun kebijakan atau boot guard baru tidak dapat menghapusnya; re-run yang lolos tidak membersihkannya. Hanya restart proses — power cycle sejati — yang me-reset keadaan tersebut.
  • Hanya gate pembuatan. FipsSignatureEnforcer mengatur pembuatan tanda tangan baru. Validasi tanda tangan yang sudah ada adalah penggunaan legacy dan tidak pernah melalui enforcer.
  • Jejak audit. Ketika sebuah guard disusun dengan audit logger, setiap batas memancarkan catatan ALLOW atau DENY sebelum mengizinkan atau menolak operasi. Logger berkonsultasi ke kebijakan yang sama yang diberlakukan guard, sehingga keputusan yang tercatat tidak dapat menyimpang.
  • Membangun Pkcs11Signer tanpa ext-pkcs11 memunculkan HsmOperationException seketika; ekstensi tersebut tidak disertakan dalam distribusi PHP standar.
  • Label sertifikat atau kunci privat yang tidak cocok dengan objek token mana pun memunculkan HsmOperationException yang menyebutkan kelas objek yang hilang.
  • OpenSslCliSigner menolak $keyUri yang mengandung pin-value saat konstruksi, fail-closed; PIN melewati jalur pin-source yang aman sebagai gantinya.
  • Dalam mode FIPS, identifier algoritma yang tidak dapat dipetakan ke OID tanda tangan yang dikenal ditolak fail-closed; demikian pula sertifikat yang kekuatan kunci publiknya tidak dapat ditentukan.
  • Tipe kunci yang tidak dikenal ditolak secara default; kebijakan tidak pernah mundur ke algoritma yang lebih lemah.
  • Known-answer test yang gagal memunculkan FipsModuleErrorStateException yang membawa hasil yang gagal; setiap batas berikutnya dalam proses mengulang kegagalan hingga restart.
  • Guard yang dibangun tanpa boot guard memberlakukan allow-list tetapi tidak menyediakan gate self-test; komposisi FIPS produksi menyediakannya melalui bootstrap.
  • signPqs() menolak berjalan kecuali opt-in konstruktor telah disetel. String konteks lebih dari 255 byte memunculkan InvalidArgumentException (FIPS 204 §5.4). Tanda tangan yang dikembalikan yang panjang byte-nya tidak cocok dengan set parameter yang dipilih ditolak sebelum mencapai encoding.

Diizinkan-FIPS dalam mode strict: SHA-256/384/512; RSA PKCS#1 v1.5 dan RSA-PSS dengan hash tersebut; ECDSA dengan hash tersebut; AES-256-CBC dan AES-256-GCM; RSA setidaknya 2048 bit, EC setidaknya 256 bit. Ditolak-FIPS dalam mode strict: hash yang lebih lemah atau legacy, OID tanda tangan yang tidak disetujui, AES-128 (diizinkan hanya dalam preset standard), dan kunci apa pun di bawah kekuatan minimum. Panjang kunci RSA minimum dan status transisi mengikuti NIST SP 800-131A Rev.2 §3. Pasangan kurva dan hash ECDSA mengikuti FIPS 186-5 §6.1.1. Jalur ini fail-closed dan tidak pernah menggantikan algoritma yang lebih lemah.

NextPDF Enterprise bukan modul kriptografis tervalidasi-FIPS dan tidak membuat klaim sertifikasi FIPS. NextPDF Enterprise beroperasi dalam mode kompatibel-FIPS hanya ketika dikonfigurasi dengan provider kriptografis tervalidasi-FIPS — misalnya provider OpenSSL tervalidasi-FIPS — atau HSM tervalidasi-FIPS. Kebijakan mode FIPS membantu kepatuhan; ini bukan sertifikasi. Tidak ada artefak sertifikasi FIPS dalam repositori ini.

KlaimStandarKlausul
Semantik operasi sign token, sesi, dan login penggunaPKCS#11 v3.1§5 (sign)
Panjang salt PSS sama dengan panjang digestPKCS#11 v3.1§5 (PSS sLen)
Pembuatan tanda tangan ECDSA; pasangan kurva dan hashFIPS 186-5§6.3.2; §6.1.1
Panjang kunci RSA minimum dan status transisi pembuatan tanda tanganNIST SP 800-131A Rev.2§3
Kategori self-test, dokumentasi, pemicu kondisional, himpunan disjointISO/IEC 19790:2025§7.10, §7.10.2, §7.10.3, §7.10.3.p3
Keunikan initialization-vector AES-GCMNIST SP 800-38D§5
Tanggung jawab perlindungan dan kustodian kunciNIST SP 800-57 Part 1 Rev.5§5.5.2
String konteks penandatanganan pasca-kuantum dibatasi 255 byteFIPS 204§5.4

Semua klausul diparafrasekan; tidak ada teks normatif yang direproduksi. Ini adalah klaim kapabilitas tentang kode NextPDF, bukan sertifikasi. Apakah tanda tangan yang dihasilkan terverifikasi adalah keputusan verifier terhadap konfigurasi trust-nya sendiri. Kebijakan mode FIPS adalah fitur bantuan kepatuhan, bukan opini hukum; konsultasikan penasihat kepatuhan dan hukum Anda sendiri. Modul ini menyangkut fungsionalitas kriptografis; perlakukan sebagai sensitif-keamanan dalam tinjauan Anda sendiri.

  • Susun mode FIPS melalui bootstrap: boot() untuk gate saat start-up, lazy() untuk menunda baterai ke batas pertama, dan factory enforcer untuk parameter $fipsEnforcer signer. Deployment non-FIPS meneruskan null dan perilakunya tidak berubah.
  • Subperintah fips:self-test pada bin/nextpdf-enterprise menjalankan baterai sesuai permintaan dan keluar non-zero dalam keadaan ERROR; sambungkan ke job pemeliharaan atau endpoint health khusus-admin (self-test sesuai permintaan ISO/IEC 19790:2025).
  • FipsBootGuard::resetProcessErrorLatchForTesting() bersifat @internal dan hanya untuk tes; kode produksi tidak pernah memanggilnya, karena itu akan mengalahkan keadaan ERROR yang sticky.
  • Bangun signer sekali dan gunakan kembali; konstruksi login dan membaca sertifikat, dan cache modul per-library membuat konstruksi berulang terhadap library yang sama aman.
  • Sediakan PIN dari secret manager. PIN adalah #[SensitiveParameter], tidak pernah dicatat atau diserialisasi; jangan commit ke konfigurasi.
  • Operator memiliki penyediaan token, penanganan PIN, konfigurasi slot, perlindungan jaringan HSM terpasang-jaringan, dan konfigurasi trust. Halaman ini tidak mengekspos internal kebijakan PIN token atau materi kredensial vendor.
  • Jangan aktifkan pratinjau pasca-kuantum untuk tanda tangan AdES produksi. Katalog cryptographic-suites AdES belum mengenali suite pasca-kuantum, sebagian besar viewer PDF menolak tanda tangan semacam itu, dan validasi round-trip perangkat keras belum lengkap. Detail mekanisme internal tetap berada dalam dokumentasi internal repositori sumber dan berada di luar cakupan manual ini.

Halaman ini mendokumentasikan perilaku yang dapat diamati secara eksternal dan permukaan API publik yang didukung saja. Jalur namespace internal, kelas helper, tabel mekanisme, nama file runbook, dan prefiks tiket berada di luar cakupan.