Enterprise edisi

FIPS 140 — Referensi Mendalam

Sekilas pandang

Halaman ini adalah referensi mendalam untuk modul FIPS 140 NextPDF Enterprise. Modul ini merupakan kapabilitas kebijakan dan self-test. Ia membatasi pilihan kriptografi ke allow-list yang selaras dengan FIPS, menjalankan rangkaian power-on known-answer-test, dan menghambat output kriptografi ketika rangkaian tersebut gagal. NextPDF bukan modul kriptografi tervalidasi FIPS 140, tidak memegang sertifikasi apa pun, dan tidak memberikan sertifikasi apa pun. Dukungan tidak sama dengan konformansi, dan konformansi tidak sama dengan sertifikasi. Deployment yang kompatibel dengan FIPS juga memerlukan penyedia kriptografi tervalidasi-FIPS yang disuplai oleh operator.

Ketersediaan & lisensi

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

Permukaan Public API

Semua simbol berada di NextPDF\Enterprise\Security\Fips, kecuali FipsBootstrap di NextPDF\Enterprise\Bootstrap.

Simbol	Parameter	Perilaku default	Mengembalikan	Melempar atau gagal dengan	Catatan
`FipsBootstrap::boot()`	`?CryptoPolicyInterface $policy`, `?FipsSelfTest $selfTest`, `?LoggerInterface $auditLogger` (semua default `null`)	Menjalankan rangkaian power-on satu kali saat start-up; default ke kebijakan strict	`FipsModeGuard`	`FipsModuleErrorStateException` pada kegagalan pengujian power-on apa pun	Composition root; jejak audit mati ketika `$auditLogger` bernilai `null`
`FipsBootstrap::lazy()`	Sama seperti `boot()`	Menunda rangkaian hingga penegasan boundary pertama	`FipsModeGuard`	Tidak ada saat pemanggilan; penegasan pertama dapat melempar `FipsModuleErrorStateException`	Modul tetap `PRE_OPERATIONAL` hingga penegasan pertama
`FipsBootstrap::signatureEnforcer()`	`?CryptoPolicyInterface $policy = null`, `?FipsSelfTest $selfTest = null`	Mem-boot modul, lalu membungkus penjaga untuk chokepoint penanda tangan	`FipsSignatureEnforcer`	`FipsModuleErrorStateException` pada kegagalan pengujian power-on apa pun	Mendelegasikan ke `boot()`
`FipsBootstrap::selfTestReport()`	`?FipsSelfTest $selfTest = null`	Menjalankan rangkaian sesuai permintaan dan meringkasnya	`array{status: FipsSelfTestStatus, operational: bool, failed: list<string>}`	Tidak melempar; kegagalan muncul di `failed`	Untuk endpoint kesehatan admin dan penggunaan CLI
`FipsCryptoPolicy::strict()`	`?FipsSelfTest $selfTest = null`	Preset FIPS 140-3: SHA-256/384/512; OID RSA, RSASSA-PSS, ECDSA yang disetujui; `aes-256-cbc`, `aes-256-gcm`; RSA >= 2048, EC >= 256	`self`	Tidak ada	Konstruktor bersifat privat; preset adalah satu-satunya pintu masuk
`FipsCryptoPolicy::standard()`	`?FipsSelfTest $selfTest = null`	Preset FIPS 140-2: set strict ditambah `aes-128-cbc`	`self`	Tidak ada	Hanya untuk interoperabilitas legacy
`FipsCryptoPolicy::assertPreOperational()`	Tidak ada	Menjalankan, atau memutar ulang hasil yang di-latch dari, rangkaian power-on	`void`	`FipsModuleErrorStateException` ketika pengujian power-on apa pun gagal	Digerakkan oleh seam penegakan Core sebelum operasi pertama
Permukaan kueri `FipsCryptoPolicy`	Input `string` / `int`	Pemeriksaan keanggotaan allow-list; tipe kunci tak dikenal ditolak	`bool` / `string`	Tidak ada	`isHashAlgorithmAllowed`, `isSignatureAlgorithmAllowed`, `isEncryptionAlgorithmAllowed`, `isKeyStrengthAllowed`, `getPreferredHashAlgorithm`, `getName`
`FipsModeGuard::__construct()`	`CryptoPolicyInterface $policy`, `?FipsBootGuard $bootGuard = null`, `?FipsAuditLogger $auditLogger = null`	Membungkus kebijakan dengan boundary gaya assert	—	Tidak ada	Tanpa `$bootGuard` tidak ada gate self-test; komposisi produksi menyuplainya
`FipsModeGuard::assertHashAllowed()`	`string $algorithm`	Katalog penolakan dulu, lalu allow-list	`void`	`FipsViolationException`; `FipsModuleErrorStateException` ketika boot guard terpasang	Rekaman audit mendahului `FipsViolationException` apa pun
`FipsModeGuard::assertSignatureAlgorithmAllowed()`	`string $oid`	Katalog penolakan dulu, lalu allow-list	`void`	Sama seperti di atas	OID dicocokkan secara persis
`FipsModeGuard::assertEncryptionAllowed()`	`string $algorithm`	Katalog penolakan dulu, lalu allow-list	`void`	Sama seperti di atas	Nama dibandingkan dalam huruf kecil
`FipsModeGuard::assertKeyStrengthAllowed()`	`string $keyType`, `int $bitLength`	Katalog penolakan dulu, lalu minimum kebijakan	`void`	Sama seperti di atas	Tipe kunci tak dikenal ditolak
`FipsModeGuard::getPolicy()`	Tidak ada	Mengembalikan kebijakan yang dibungkus	`CryptoPolicyInterface`	Tidak ada	—
`FipsBootGuard::__construct()`	`FipsSelfTest $selfTest`	Menahan rangkaian; tidak menjalankannya	—	Tidak ada	Satu siklus power-on per instans
`FipsBootGuard::report()`	Tidak ada	Menjalankan rangkaian satu kali, meng-cache laporan, mengunci pada error	`FipsSelfTestReport`	Tidak ada	Pemanggilan pertama menjalankan pengujian
`FipsBootGuard::rerun()`	Tidak ada	Memaksa run baru; run yang error mengunci proses	`FipsSelfTestReport`	Tidak ada	Self-test sesuai permintaan; bukan jalur pemulihan error
`FipsBootGuard::assertOperational()`	Tidak ada	Menegaskan modul operasional; lengket sepanjang proses	`void`	`FipsModuleErrorStateException`	Instans yang bersih pun tetap melempar ketika proses telah mengunci error
`FipsBootGuard::status()`	Tidak ada	Melaporkan status yang di-cache	`FipsSelfTestStatus`	Tidak ada	`ERROR` ketika terkunci; `PRE_OPERATIONAL` ketika belum pernah dijalankan
`FipsSelfTest::__construct()`	`?callable $randomBytesProvider = null`, `?callable $hashProvider = null`	Menggunakan `hash()` dan `random_bytes()` platform	—	Tidak ada	Override tersedia untuk pengujian kegagalan deterministik
`FipsSelfTest::run()`	Tidak ada	Menjalankan rangkaian penuh; tidak pernah short-circuit	`FipsSelfTestReport`	Tidak ada	Kegagalan masuk ke laporan, bukan ke eksepsi
`FipsSelfTestReport`	`FipsSelfTestStatus $status`, `array $results`, `array $failedResults`	Agregat immutable dari satu run	—	`assertOperational()` melempar `FipsModuleErrorStateException` dalam keadaan error	Juga `isOperational()`, `isError()`
`FipsSelfTestResult`	`string $algorithm`, `string $kind`, `bool $passed`, `string $message = ''`	Hasil immutable per pengujian	—	Tidak ada	`kind` adalah `KAT`, `PWCT`, atau `HEALTH`; juga `isPassed()`, `isFailed()`
`FipsSelfTestStatus`	—	Enum berbasis string	—	Tidak ada	Case `PRE_OPERATIONAL`, `OPERATIONAL`, `ERROR`
`FipsSignatureEnforcer::__construct()`	`FipsModeGuard $guard`	Membungkus penjaga yang di-gate boot untuk chokepoint penandatanganan	—	Tidak ada	—
`FipsSignatureEnforcer::assertSignatureGenerationAllowed()`	`string $algorithm`, `string $certificatePem`	Menyelesaikan OID dan kekuatan kunci, lalu mendelegasikan ke penjaga	`void`	`FipsViolationException` (algoritma tak dikenal, digest PSS tak disetujui, kunci tak terbukti, atau penolakan kebijakan); `FipsModuleErrorStateException` melalui penjaga	Hanya jalur generasi; verifikasi tidak pernah dirutekan ke sini
`FipsAuditLogger::__construct()`	`CryptoPolicyInterface $policy`, `LoggerInterface $logger`	Membungkus logger PSR-3 dan kebijakan yang sama yang ditegakkan penjaga	—	Tidak ada	Keputusan yang direkam tidak dapat menyimpang dari yang ditegakkan
`FipsAuditLogger::logHashOperation()` / `logSignatureOperation()` / `logEncryptionOperation()` / `logKeyStrengthCheck()`	Input `string` / `int` per keputusan	Mencatat ALLOW pada INFO dan DENY pada WARNING	`bool` (true ketika diizinkan)	Tidak ada	Konteks terstruktur: nama kebijakan, item, keputusan
`FipsTransitioningAlgorithms`	Input `string` / `int`	Katalog penolakan statis SP 800-131A Rev.2	`bool` / `list<string>`	Tidak ada	`isHashDisallowed`, `isSignatureOidDisallowed`, `isEncryptionDisallowed`, `isKeyStrengthDisallowed`, plus `disallowedHashes`, `disallowedSignatureOids`, `disallowedEncryption`
`FipsViolationException`	`string $policyName`, `string $violatingItem`, `string $reason`	Pelanggaran kebijakan bertipe dengan field publik readonly	—	—	Subtipe dari `NextPDF\Exception\NextPdfException`
`FipsModuleErrorStateException`	`array $failedResults`, `?string $message = null`	Penolakan keadaan-error yang membawa hasil pengujian yang gagal	—	—	Subtipe dari `NextPDF\Exception\NextPdfException`

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

public static function strict(?FipsSelfTest $selfTest = null): self
public static function standard(?FipsSelfTest $selfTest = null): self
public function assertPreOperational(): void
public function isHashAlgorithmAllowed(string $algorithm): bool
public function isSignatureAlgorithmAllowed(string $oid): bool
public function isEncryptionAlgorithmAllowed(string $algorithm): bool
public function isKeyStrengthAllowed(string $keyType, int $bitLength): bool
public function getPreferredHashAlgorithm(): string
public function getName(): string

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 function __construct(private readonly FipsSelfTest $selfTest)
public function report(): FipsSelfTestReport
public function rerun(): FipsSelfTestReport
public function assertOperational(): void
public function status(): FipsSelfTestStatus

public function __construct(?callable $randomBytesProvider = null, ?callable $hashProvider = null)
public function run(): FipsSelfTestReport

public function __construct(private readonly FipsModeGuard $guard)
public function assertSignatureGenerationAllowed(string $algorithm, string $certificatePem): void

public function __construct(private CryptoPolicyInterface $policy, private LoggerInterface $logger)
public function logHashOperation(string $algorithm): bool
public function logSignatureOperation(string $oid): bool
public function logEncryptionOperation(string $algorithm): bool
public function logKeyStrengthCheck(string $keyType, int $bitLength): bool

public static function isHashDisallowed(string $algorithm): bool
public static function isSignatureOidDisallowed(string $oid): bool
public static function isEncryptionDisallowed(string $algorithm): bool
public static function isKeyStrengthDisallowed(string $keyType, int $bitLength): bool
public static function disallowedHashes(): array
public static function disallowedSignatureOids(): array
public static function disallowedEncryption(): array

public function __construct(public FipsSelfTestStatus $status, public array $results, public array $failedResults)
public function isOperational(): bool
public function isError(): bool
public function assertOperational(): void

// FipsSelfTestResult
public function __construct(public string $algorithm, public string $kind, public bool $passed, public string $message = '')
public function isPassed(): bool
public function isFailed(): bool

// FipsSelfTestStatus
enum FipsSelfTestStatus: string
{
    case PRE_OPERATIONAL = 'pre_operational';
    case OPERATIONAL = 'operational';
    case ERROR = 'error';
}

Kontrak perilaku

Allow-list kebijakan adalah keputusan otoritatif. FipsTransitioningAlgorithms menambahkan lapisan penolakan SP 800-131A Rev.2 yang eksplisit di atasnya, untuk pesan penolakan yang jelas bagi audit. Lapisan penolakan tidak pernah memperluas atau menimpa allow-list.
FipsCryptoPolicy::strict() mengizinkan SHA-256, SHA-384, dan SHA-512; OID tanda tangan RSA PKCS#1 v1.5, RSASSA-PSS, dan ECDSA yang terikat ke hash tersebut; aes-256-cbc dan aes-256-gcm; serta batas bawah kunci RSA 2048, EC 256, Ed25519 256. standard() juga mengizinkan aes-128-cbc.
Rangkaian power-on mencakup: KAT digest SHA-256/384/512, KAT HMAC-SHA-256, KAT enkripsi-dan-dekripsi AES-256-CBC, KAT tag AES-256-GCM, uji konsistensi pair-wise ECDSA P-256, dan pemeriksaan kesehatan DRBG. FipsSelfTest::run() selalu menjalankan setiap pengujian dan tidak pernah short-circuit, sehingga laporan menjadi lengkap sebagai bukti audit.
Baris DRBG adalah uji kesehatan kontinu (panjang penarikan plus penarikan berturut-turut yang berbeda), bukan known-answer test. Kewajiban known-answer DRBG didelegasikan ke penyedia tervalidasi-FIPS di bawahnya yang disuplai operator.
Keadaan error bersifat lengket pada proses. Laporan ERROR pertama yang diamati oleh FipsBootGuard mana pun mengunci seluruh proses. Instans penjaga atau kebijakan yang baru tidak dapat mencuci error tersebut, dan rerun yang lolos di kemudian hari tidak menghapusnya. Hanya restart proses (power cycle sejati) yang mereset keadaan.
FipsCryptoPolicy mengimplementasikan NextPDF\Contracts\CryptoPolicyInterface dan NextPDF\Contracts\PreOperationalSelfTestInterface. Ketika dikonfigurasi sebagai kebijakan kripto Core, seam penegakan Core menggerakkan assertPreOperational() sebelum tanda tangan atau ciphertext pertama diproduksi.
FipsSignatureEnforcer hanya menjaga jalur generasi. Verifikasi tanda tangan yang sudah dihasilkan adalah penggunaan legacy di bawah SP 800-131A Rev.2 dan tidak pernah dirutekan melalui enforcer.
Ketika logger audit terpasang, setiap boundary assert mengeluarkan satu rekaman ALLOW (INFO) atau DENY (WARNING) sebelum lemparan pelanggaran kebijakan apa pun. Karena itu setiap penolakan FipsViolationException terbukti dalam jejak. Gate boot-guard berjalan lebih dulu, sehingga penolakan keadaan-error diangkat sebelum rekaman audit. FipsAuditLogger merujuk pada kebijakan yang sama yang ditegakkan penjaga, sehingga keputusan yang direkam tidak dapat menyimpang dari yang ditegakkan.

Kasus tepi & mode kegagalan

Tipe kunci tak dikenal ditolak oleh kedua lapisan: kebijakan mengembalikan false dan katalog memperlakukannya sebagai tidak diizinkan.
Identifier algoritma penandatanganan yang tidak dapat dipetakan enforcer ke OID tanda tangan ditolak secara fail-closed dengan FipsViolationException.
Setiap varian RSASSA-PSS berbagi OID 1.2.840.113549.1.1.10, sehingga OID saja tidak dapat membuktikan digest-nya. Enforcer mengikat digest efektif secara eksplisit dan menolak token PSS apa pun yang digest-nya bukan SHA-256/384/512.
Sertifikat yang tidak dapat diurai, atau yang panjang bit kunci publiknya tidak tersedia, ditolak sebagai key:unprovable.
Pada runtime tanpa primitif asimetris OpenSSL, uji konsistensi pair-wise ECDSA merekam kegagalan, bukan skip, dan modul memasuki ERROR.
Dua penarikan acak 32-byte berturut-turut yang identik menggagalkan pemeriksaan kesehatan DRBG (deteksi output macet) dan memaksa ERROR.
FipsModeGuard yang dikonstruksi tanpa boot guard hanya melakukan pemeriksaan kebijakan dan tidak memiliki gate self-test. Komposisi produksi melewati FipsBootstrap, yang selalu memasang gate tersebut.
Nama hash dan cipher dibandingkan dalam huruf kecil; OID tanda tangan dicocokkan secara persis, tanpa normalisasi.
Setelah FipsBootstrap::lazy(), modul tetap PRE_OPERATIONAL hingga boundary assert pertama menjalankan rangkaian. PRE_OPERATIONAL diperlakukan sebagai tidak operasional pada saat penegasan.

Perilaku FIPS-mode

Modul ini adalah permukaan FIPS-mode itu sendiri. Selama modul berada dalam keadaan error, dan selama pre-operational self-test berjalan, output kriptografi dihambat: setiap boundary assert melempar FipsModuleErrorStateException sebelum tanda tangan atau ciphertext apa pun diproduksi (ISO/IEC 19790:2025 §7.3.3 b), AS03.07). FipsBootGuard::status() dan FipsBootstrap::selfTestReport() memaparkan keadaan sehingga operator dapat menentukan bahwa modul memasuki keadaan error (ISO/IEC 19790:2025 §7.10.3). Perilaku-perilaku ini adalah klaim kapabilitas tentang kode NextPDF, bukan klaim validasi: batas modul yang divalidasi FIPS 140 adalah penyedia kriptografi yang disuplai operator, bukan NextPDF.

Konformansi

Klaim	Standar	Klausul
FIPS 140-3 didasarkan pada ISO/IEC 19790 dan ISO/IEC 24759; karena itu halaman ini mengutip klausul ISO/IEC 19790.	FIPS 140-3	Introduction (fips_140_3#x26.x2)
Output dihambat dalam keadaan error dan selama pre-operational self-test.	ISO/IEC 19790:2025	§7.3.3 b) [AS03.07]
Known-answer test membandingkan hasil yang dihitung terhadap keluaran yang diharapkan yang diketahui; rangkaian mengimplementasikan bentuk ini.	ISO/IEC 19790:2025	§7.10.4
Operator dapat menentukan keadaan error melalui output status.	ISO/IEC 19790:2025	§7.10.3 [AS10.10]
Operator dapat menginisiasi self-test sesuai permintaan untuk pengujian periodik; `rerun()` dan `selfTestReport()` menyediakan ini.	ISO/IEC 19790:2025	§7.10.5 [AS10.54]
SHA-1 tidak diizinkan untuk generasi tanda tangan digital baru; katalog penolakan menolaknya.	NIST SP 800-131A Rev.2	§9
Generasi tanda tangan di bawah kekuatan 112-bit (RSA < 2048, order ECDSA < 224) tidak diizinkan; batas bawah kunci menegakkan ini.	NIST SP 800-131A Rev.2	§3 Table 2
Verifikasi tanda tangan SHA-1 yang sudah dihasilkan adalah penggunaan legacy; ia tidak dirutekan melalui gate generasi.	NIST SP 800-131A Rev.2	Change summary (9.x4.p12)

Semua klausul diparafrasekan; tidak ada teks normatif yang direproduksi. NextPDF tidak membuat klaim sertifikasi FIPS 140 apa pun. Modul menyelaraskan perilakunya dengan klausul yang dikutip sebagai kapabilitas bantuan-kepatuhan. Apakah sebuah deployment patuh-FIPS bergantung pada penyedia tervalidasi operator, definisi batas modul, dan program kepatuhan — bukan pada NextPDF semata.

Catatan pengembangan

Pengujian kegagalan deterministik menyuntikkan penyedia rusak melalui konstruktor FipsSelfTest, atau melalui parameter $selfTest pada FipsCryptoPolicy::strict(), standard(), dan metode FipsBootstrap.
Latch keadaan-error yang lengket pada proses memiliki hook reset internal khusus-pengujian. Hook itu bukan bagian dari API yang didukung, dan kode produksi tidak boleh memanggilnya.
Setiap proses worker PHP menjalankan rangkaian power-on-nya sendiri. Laporan di-cache per instans, sehingga penegasan jalur-cepat adalah pemeriksaan status waktu-konstan.
Jangan menangkap FipsModuleErrorStateException lalu melanjutkan. Eksepsi tersebut berarti modul menolak layanan kriptografi; respons yang benar adalah menghentikan dan me-restart proses setelah remediasi.
FipsBootstrap::selfTestReport() melayani kebutuhan self-test sesuai permintaan dan periodik, seperti endpoint kesehatan. Run sesuai permintaan yang lolos tidak pernah menghapus error yang terkunci.

Lihat juga

Kebijakan kriptografi dan self-test FIPS 140-2/3 — halaman kapabilitas dengan setup dan contoh.
Security — Referensi Mendalam — kontrol keamanan Enterprise yang digabungkan.
Signature — Referensi Mendalam — produser jangka-panjang PAdES dan catatan FIPS-mode-nya.
Security — NextPDF Core — permukaan enkripsi dan penandatanganan Core tempat kebijakan terikat.

Batas publikasi

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