Enterprise phiên bản

FIPS 140 — Tài liệu tham chiếu chuyên sâu

Tổng quan nhanh

Trang này là tham chiếu chuyên sâu cho module FIPS 140 của NextPDF Enterprise. Module này là một năng lực chính sách (policy) và self-test. Nó giới hạn các lựa chọn mật mã vào một allow-list tuân theo FIPS, chạy một loạt known-answer-test khi khởi động, và ngăn xuất ra kết quả mật mã khi loạt test thất bại. NextPDF không phải là một module mật mã được kiểm định FIPS 140, không nắm giữ chứng nhận nào, và không cấp chứng nhận nào. Hỗ trợ không đồng nghĩa với tuân thủ (conformance), và tuân thủ không đồng nghĩa với chứng nhận. Một triển khai tương thích FIPS còn cần thêm một nhà cung cấp mật mã đã được kiểm định FIPS do người vận hành cung cấp.

Tính khả dụng & cấp phép

Năng lực này được cung cấp trong NextPDF Enterprise (nextpdf/enterprise) và kích hoạt bằng một license envelope hạng Enterprise. Một triển khai không có quyền đó sẽ không nạp các lớp của năng lực này. So sánh các phiên bản và nhận giấy phép.

Bề mặt public API

Tất cả các ký hiệu nằm trong NextPDF\Enterprise\Security\Fips, ngoại trừ FipsBootstrap nằm trong NextPDF\Enterprise\Bootstrap.

Ký hiệu	Tham số	Hành vi mặc định	Trả về	Ném ra hoặc thất bại với	Ghi chú
`FipsBootstrap::boot()`	`?CryptoPolicyInterface $policy`, `?FipsSelfTest $selfTest`, `?LoggerInterface $auditLogger` (tất cả mặc định `null`)	Chạy loạt test khởi động một lần khi khởi động; mặc định dùng chính sách strict	`FipsModeGuard`	`FipsModuleErrorStateException` khi bất kỳ test khởi động nào thất bại	Composition root; dấu vết kiểm toán tắt khi `$auditLogger` là `null`
`FipsBootstrap::lazy()`	Giống như `boot()`	Trì hoãn loạt test đến lần assertion biên đầu tiên	`FipsModeGuard`	Không có tại thời điểm gọi; assertion đầu tiên có thể ném `FipsModuleErrorStateException`	Module vẫn ở `PRE_OPERATIONAL` cho đến assertion đầu tiên
`FipsBootstrap::signatureEnforcer()`	`?CryptoPolicyInterface $policy = null`, `?FipsSelfTest $selfTest = null`	Khởi động module, rồi bọc guard cho các điểm nghẽn ký (signer chokepoints)	`FipsSignatureEnforcer`	`FipsModuleErrorStateException` khi bất kỳ test khởi động nào thất bại	Ủy quyền cho `boot()`
`FipsBootstrap::selfTestReport()`	`?FipsSelfTest $selfTest = null`	Chạy loạt test theo yêu cầu và tóm tắt lại	`array{status: FipsSelfTestStatus, operational: bool, failed: list<string>}`	Không ném; các thất bại xuất hiện trong `failed`	Dùng cho health endpoint quản trị và CLI
`FipsCryptoPolicy::strict()`	`?FipsSelfTest $selfTest = null`	Preset FIPS 140-3: SHA-256/384/512; các OID RSA, RSASSA-PSS, ECDSA được chấp thuận; `aes-256-cbc`, `aes-256-gcm`; RSA >= 2048, EC >= 256	`self`	Không	Constructor là private; các preset là lối vào duy nhất
`FipsCryptoPolicy::standard()`	`?FipsSelfTest $selfTest = null`	Preset FIPS 140-2: bộ strict cộng thêm `aes-128-cbc`	`self`	Không	Chỉ để tương tác kế thừa (legacy)
`FipsCryptoPolicy::assertPreOperational()`	Không	Chạy, hoặc phát lại kết quả đã chốt của, loạt test khởi động	`void`	`FipsModuleErrorStateException` khi bất kỳ test khởi động nào thất bại	Được điều khiển bởi seam thực thi của Core trước thao tác đầu tiên
Bề mặt truy vấn `FipsCryptoPolicy`	Đầu vào `string` / `int`	Kiểm tra thành viên allow-list; loại khóa không xác định bị từ chối	`bool` / `string`	Không	`isHashAlgorithmAllowed`, `isSignatureAlgorithmAllowed`, `isEncryptionAlgorithmAllowed`, `isKeyStrengthAllowed`, `getPreferredHashAlgorithm`, `getName`
`FipsModeGuard::__construct()`	`CryptoPolicyInterface $policy`, `?FipsBootGuard $bootGuard = null`, `?FipsAuditLogger $auditLogger = null`	Bọc một policy bằng các biên kiểu assert	—	Không	Nếu không có `$bootGuard` thì không có cổng self-test; composition production sẽ cung cấp nó
`FipsModeGuard::assertHashAllowed()`	`string $algorithm`	Danh mục từ chối trước, rồi đến allow-list	`void`	`FipsViolationException`; `FipsModuleErrorStateException` khi một boot guard được nối	Bản ghi kiểm toán đứng trước bất kỳ `FipsViolationException` nào
`FipsModeGuard::assertSignatureAlgorithmAllowed()`	`string $oid`	Danh mục từ chối trước, rồi đến allow-list	`void`	Giống như trên	Các OID được so khớp chính xác
`FipsModeGuard::assertEncryptionAllowed()`	`string $algorithm`	Danh mục từ chối trước, rồi đến allow-list	`void`	Giống như trên	Tên được so sánh ở dạng chữ thường
`FipsModeGuard::assertKeyStrengthAllowed()`	`string $keyType`, `int $bitLength`	Danh mục từ chối trước, rồi đến các mức tối thiểu của policy	`void`	Giống như trên	Loại khóa không xác định bị từ chối
`FipsModeGuard::getPolicy()`	Không	Trả về policy đã được bọc	`CryptoPolicyInterface`	Không	—
`FipsBootGuard::__construct()`	`FipsSelfTest $selfTest`	Giữ loạt test; không chạy nó	—	Không	Một chu kỳ khởi động cho mỗi instance
`FipsBootGuard::report()`	Không	Chạy loạt test một lần, cache bản báo cáo, chốt lại khi có lỗi	`FipsSelfTestReport`	Không	Lần gọi đầu tiên chạy các test
`FipsBootGuard::rerun()`	Không	Bắt buộc chạy lại mới; một lần chạy lỗi sẽ chốt lại tiến trình	`FipsSelfTestReport`	Không	Self-test theo yêu cầu; không phải đường khôi phục lỗi
`FipsBootGuard::assertOperational()`	Không	Khẳng định module đang hoạt động; bám theo toàn bộ tiến trình	`void`	`FipsModuleErrorStateException`	Một instance sạch vẫn ném khi tiến trình đã chốt một lỗi
`FipsBootGuard::status()`	Không	Báo cáo trạng thái đã cache	`FipsSelfTestStatus`	Không	`ERROR` khi đã chốt; `PRE_OPERATIONAL` khi chưa bao giờ chạy
`FipsSelfTest::__construct()`	`?callable $randomBytesProvider = null`, `?callable $hashProvider = null`	Dùng `hash()` và `random_bytes()` của nền tảng	—	Không	Có các override cho các test thất bại tất định
`FipsSelfTest::run()`	Không	Thực thi toàn bộ loạt test; không bao giờ short-circuit	`FipsSelfTestReport`	Không	Các thất bại nằm trong báo cáo, không nằm trong exception
`FipsSelfTestReport`	`FipsSelfTestStatus $status`, `array $results`, `array $failedResults`	Tập hợp bất biến của một lần chạy	—	`assertOperational()` ném `FipsModuleErrorStateException` ở trạng thái lỗi	Còn có `isOperational()`, `isError()`
`FipsSelfTestResult`	`string $algorithm`, `string $kind`, `bool $passed`, `string $message = ''`	Kết quả bất biến cho mỗi test	—	Không	`kind` là `KAT`, `PWCT`, hoặc `HEALTH`; còn có `isPassed()`, `isFailed()`
`FipsSelfTestStatus`	—	Enum nền chuỗi (string-backed)	—	Không	Các case `PRE_OPERATIONAL`, `OPERATIONAL`, `ERROR`
`FipsSignatureEnforcer::__construct()`	`FipsModeGuard $guard`	Bọc một guard đã gated qua boot cho các điểm nghẽn ký	—	Không	—
`FipsSignatureEnforcer::assertSignatureGenerationAllowed()`	`string $algorithm`, `string $certificatePem`	Phân giải OID và độ mạnh khóa, rồi ủy quyền cho guard	`void`	`FipsViolationException` (thuật toán không xác định, digest PSS không được chấp thuận, khóa không thể chứng minh, hoặc bị policy từ chối); `FipsModuleErrorStateException` thông qua guard	Chỉ đường tạo (generation); việc xác minh không bao giờ đi qua đây
`FipsAuditLogger::__construct()`	`CryptoPolicyInterface $policy`, `LoggerInterface $logger`	Bọc một logger PSR-3 và cùng một policy mà guard thực thi	—	Không	Các quyết định được ghi lại không thể sai khác với các quyết định được thực thi
`FipsAuditLogger::logHashOperation()` / `logSignatureOperation()` / `logEncryptionOperation()` / `logKeyStrengthCheck()`	Đầu vào `string` / `int` cho mỗi quyết định	Ghi ALLOW ở mức INFO và DENY ở mức WARNING	`bool` (true khi được cho phép)	Không	Ngữ cảnh có cấu trúc: tên policy, mục, quyết định
`FipsTransitioningAlgorithms`	Đầu vào `string` / `int`	Danh mục từ chối SP 800-131A Rev.2 tĩnh	`bool` / `list<string>`	Không	`isHashDisallowed`, `isSignatureOidDisallowed`, `isEncryptionDisallowed`, `isKeyStrengthDisallowed`, cùng với `disallowedHashes`, `disallowedSignatureOids`, `disallowedEncryption`
`FipsViolationException`	`string $policyName`, `string $violatingItem`, `string $reason`	Vi phạm policy có kiểu với các trường public readonly	—	—	Kiểu con của `NextPDF\Exception\NextPdfException`
`FipsModuleErrorStateException`	`array $failedResults`, `?string $message = null`	Từ chối ở trạng thái lỗi, mang theo các kết quả test thất bại	—	—	Kiểu con của `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';
}

Hợp đồng hành vi

Allow-list của policy là quyết định có thẩm quyền. FipsTransitioningAlgorithms bổ sung một lớp từ chối SP 800-131A Rev.2 tường minh phía trên nó, để có các thông báo từ chối rõ ràng cho kiểm toán. Lớp từ chối không bao giờ mở rộng hay ghi đè allow-list.
FipsCryptoPolicy::strict() cho phép SHA-256, SHA-384, và SHA-512; RSA PKCS#1 v1.5, RSASSA-PSS, và các OID chữ ký ECDSA gắn với các hash đó; aes-256-cbc và aes-256-gcm; và các mức sàn khóa RSA 2048, EC 256, Ed25519 256. standard() còn cho phép thêm aes-128-cbc.
Loạt test khởi động bao gồm: các KAT digest SHA-256/384/512, một KAT HMAC-SHA-256, một KAT mã hóa-và-giải mã AES-256-CBC, một KAT tag AES-256-GCM, một test nhất quán theo cặp ECDSA P-256, và một kiểm tra sức khỏe DRBG. FipsSelfTest::run() luôn thực thi mọi test và không bao giờ short-circuit, nên bản báo cáo là đầy đủ để làm bằng chứng kiểm toán.
Hàng DRBG là một test sức khỏe liên tục (độ dài lần rút cùng các lần rút liên tiếp khác nhau), không phải một known-answer test. Nghĩa vụ known-answer của DRBG được ủy quyền cho nhà cung cấp đã kiểm định FIPS bên dưới mà người vận hành cung cấp.
Trạng thái lỗi bám theo tiến trình. Bản báo cáo ERROR đầu tiên được bất kỳ FipsBootGuard nào quan sát thấy sẽ chốt lại toàn bộ tiến trình. Một instance guard hay policy mới không thể tẩy rửa lỗi đó, và một lần chạy lại đạt sau đó cũng không xóa nó. Chỉ việc khởi động lại tiến trình (một chu kỳ nguồn thực sự) mới reset trạng thái.
FipsCryptoPolicy hiện thực NextPDF\Contracts\CryptoPolicyInterface và NextPDF\Contracts\PreOperationalSelfTestInterface. Khi được cấu hình làm crypto policy của Core, seam thực thi của Core điều khiển assertPreOperational() trước khi chữ ký hoặc ciphertext đầu tiên được tạo ra.
FipsSignatureEnforcer chỉ gác đường tạo. Việc xác minh các chữ ký đã được tạo là cách dùng kế thừa theo SP 800-131A Rev.2 và không bao giờ đi qua bộ thực thi.
Khi một audit logger được nối, mọi biên assert phát ra một bản ghi ALLOW (INFO) hoặc DENY (WARNING) trước bất kỳ lần ném vi phạm policy nào. Do đó mọi lần từ chối FipsViolationException đều được ghi bằng chứng trong dấu vết. Cổng boot-guard chạy trước, nên một lần từ chối ở trạng thái lỗi được nêu ra trước bản ghi kiểm toán. FipsAuditLogger tham chiếu cùng một policy mà guard thực thi, nên các quyết định được ghi lại không thể sai khác với các quyết định được thực thi.

Trường hợp biên & chế độ thất bại

Một loại khóa không xác định bị từ chối bởi cả hai lớp: policy trả về false và danh mục coi nó là bị cấm.
Một định danh thuật toán ký mà bộ thực thi không thể ánh xạ tới một signature OID sẽ bị từ chối theo kiểu fail-closed với FipsViolationException.
Mọi biến thể RSASSA-PSS đều dùng chung OID 1.2.840.113549.1.1.10, nên riêng OID không thể chứng minh digest. Bộ thực thi gắn digest hiệu lực một cách tường minh và từ chối bất kỳ token PSS nào có digest không phải SHA-256/384/512.
Một chứng chỉ không thể phân tích được, hoặc có độ dài bit của khóa công khai không khả dụng, sẽ bị từ chối là key:unprovable.
Trên một runtime không có các nguyên thủy bất đối xứng của OpenSSL, test nhất quán theo cặp ECDSA ghi nhận một thất bại, không phải một lần bỏ qua, và module chuyển sang ERROR.
Hai lần rút ngẫu nhiên 32 byte liên tiếp giống hệt nhau sẽ làm thất bại kiểm tra sức khỏe DRBG (phát hiện đầu ra bị kẹt) và bắt buộc chuyển sang ERROR.
Một FipsModeGuard được khởi tạo không có boot guard chỉ thực hiện kiểm tra policy và không có cổng self-test. Composition production đi qua FipsBootstrap, luôn nối cổng đó.
Tên hash và cipher được so sánh ở dạng chữ thường; các signature OID được so khớp chính xác, không chuẩn hóa.
Sau FipsBootstrap::lazy(), module vẫn ở PRE_OPERATIONAL cho đến khi biên assert đầu tiên chạy loạt test. PRE_OPERATIONAL được coi là không hoạt động tại thời điểm assertion.

Hành vi chế độ FIPS

Module này chính là bề mặt chế độ FIPS. Trong khi module ở trạng thái lỗi, và trong khi các self-test tiền vận hành chạy, đầu ra mật mã bị ngăn: mọi biên assert ném FipsModuleErrorStateException trước khi bất kỳ chữ ký hay ciphertext nào được tạo ra (ISO/IEC 19790:2025 §7.3.3 b), AS03.07). FipsBootGuard::status() và FipsBootstrap::selfTestReport() phơi bày trạng thái để người vận hành có thể xác định rằng module đã chuyển sang trạng thái lỗi (ISO/IEC 19790:2025 §7.10.3). Những hành vi này là các tuyên bố về năng lực của mã NextPDF, không phải một tuyên bố kiểm định: biên module mà FIPS 140 kiểm định là nhà cung cấp mật mã do người vận hành cung cấp, không phải NextPDF.

Tuân thủ

Tuyên bố	Tiêu chuẩn	Điều khoản
FIPS 140-3 dựa trên ISO/IEC 19790 và ISO/IEC 24759; do đó trang này trích dẫn các điều khoản ISO/IEC 19790.	FIPS 140-3	Introduction (fips_140_3#x26.x2)
Đầu ra bị ngăn ở trạng thái lỗi và trong khi các self-test tiền vận hành chạy.	ISO/IEC 19790:2025	§7.3.3 b) [AS03.07]
Một known-answer test so sánh một kết quả tính được với một đầu ra kỳ vọng đã biết; loạt test hiện thực hình thái này.	ISO/IEC 19790:2025	§7.10.4
Người vận hành có thể xác định trạng thái lỗi thông qua một đầu ra trạng thái.	ISO/IEC 19790:2025	§7.10.3 [AS10.10]
Người vận hành có thể khởi động các self-test theo yêu cầu để kiểm thử định kỳ; `rerun()` và `selfTestReport()` cung cấp điều này.	ISO/IEC 19790:2025	§7.10.5 [AS10.54]
SHA-1 bị cấm để tạo chữ ký số mới; danh mục từ chối loại bỏ nó.	NIST SP 800-131A Rev.2	§9
Việc tạo chữ ký dưới độ mạnh 112-bit (RSA < 2048, bậc ECDSA < 224) bị cấm; các mức sàn khóa thực thi điều này.	NIST SP 800-131A Rev.2	§3 Table 2
Việc xác minh các chữ ký SHA-1 đã được tạo là cách dùng kế thừa; nó không đi qua cổng tạo.	NIST SP 800-131A Rev.2	Change summary (9.x4.p12)

Mọi điều khoản đều được diễn giải lại; không có văn bản quy chuẩn nào được tái tạo. NextPDF không đưa ra tuyên bố chứng nhận FIPS 140 nào. Module căn chỉnh hành vi của nó theo các điều khoản được trích dẫn như một năng lực hỗ trợ tuân thủ. Việc một triển khai có tuân thủ FIPS hay không phụ thuộc vào nhà cung cấp đã kiểm định của người vận hành, định nghĩa biên module, và chương trình tuân thủ — không phải chỉ dựa vào NextPDF.

Ghi chú phát triển

Các test thất bại tất định tiêm vào các nhà cung cấp hỏng thông qua constructor của FipsSelfTest, hoặc thông qua các tham số $selfTest trên FipsCryptoPolicy::strict(), standard(), và các phương thức của FipsBootstrap.
Chốt lỗi bám theo tiến trình có một hook reset nội bộ, chỉ dùng cho test. Nó không thuộc API được hỗ trợ, và mã production không được gọi nó.
Mỗi tiến trình worker PHP chạy loạt test khởi động của riêng nó. Bản báo cáo được cache theo từng instance, nên các assertion trên hot-path là các kiểm tra trạng thái thời gian hằng.
Không được bắt FipsModuleErrorStateException rồi tiếp tục. Exception này nghĩa là module từ chối các dịch vụ mật mã; phản ứng đúng là dừng lại và khởi động lại tiến trình sau khi khắc phục.
FipsBootstrap::selfTestReport() phục vụ các nhu cầu self-test theo yêu cầu và định kỳ, chẳng hạn health endpoint. Một lần chạy theo yêu cầu đạt không bao giờ xóa một lỗi đã chốt.

Xem thêm

Chính sách mật mã và self-test FIPS 140-2/3 — trang năng lực với thiết lập và ví dụ.
Bảo mật — Tham chiếu chuyên sâu — các kiểm soát bảo mật Enterprise được gộp chung.
Chữ ký — Tham chiếu chuyên sâu — bộ tạo dài hạn PAdES và ghi chú chế độ FIPS của nó.
Bảo mật — NextPDF Core — bề mặt mã hóa và ký của Core mà policy gắn vào.

Ranh giới xuất bản

Trang này chỉ tài liệu hóa hành vi quan sát được từ bên ngoài và bề mặt public API được hỗ trợ. Các đường namespace nội bộ, các lớp helper, các bảng cơ chế, tên file runbook, và các tiền tố ticket đều nằm ngoài phạm vi.