Enterprise редакция

FIPS 140 — глубокий справочник

Кратко

Эта страница — подробный справочник по модулю FIPS 140 в NextPDF Enterprise. Модуль представляет собой возможность политики и самотестирования. Он ограничивает выбор криптографии FIPS-выровненным списком разрешённого, запускает при включении батарею тестов методом известного ответа и запрещает вывод криптографических данных, если батарея не пройдена. NextPDF не является FIPS 140 валидированным криптографическим модулем, не имеет сертификации и не предоставляет её. Поддержка не равна соответствию, а соответствие не равно сертификации. FIPS-совместимое развёртывание дополнительно требует FIPS-валидированного криптографического провайдера, предоставляемого оператором.

Доступность и лицензирование

Эта возможность поставляется в NextPDF Enterprise (nextpdf/enterprise) и активируется лицензионным конвертом уровня Enterprise. Развёртывание без этого права не загружает классы возможности. Сравнить редакции и получить лицензию.

Публичная поверхность API

Все символы находятся в NextPDF\Enterprise\Security\Fips, кроме FipsBootstrap в NextPDF\Enterprise\Bootstrap.

Символ	Параметры	Поведение по умолчанию	Возвращает	Бросает или завершается с	Примечания
`FipsBootstrap::boot()`	`?CryptoPolicyInterface $policy`, `?FipsSelfTest $selfTest`, `?LoggerInterface $auditLogger` (все по умолчанию `null`)	Один раз при запуске прогоняет батарею; по умолчанию строгая политика	`FipsModeGuard`	`FipsModuleErrorStateException` при любом провале теста запуска	Корень композиции; аудит-трейл отключён, когда `$auditLogger` равен `null`
`FipsBootstrap::lazy()`	То же, что у `boot()`	Откладывает батарею до первой проверки границы	`FipsModeGuard`	Ничего в момент вызова; первая проверка может бросить `FipsModuleErrorStateException`	Модуль остаётся в `PRE_OPERATIONAL` до первой проверки
`FipsBootstrap::signatureEnforcer()`	`?CryptoPolicyInterface $policy = null`, `?FipsSelfTest $selfTest = null`	Загружает модуль, затем оборачивает страж для узловых точек подписанта	`FipsSignatureEnforcer`	`FipsModuleErrorStateException` при любом провале теста запуска	Делегирует `boot()`
`FipsBootstrap::selfTestReport()`	`?FipsSelfTest $selfTest = null`	Прогоняет батарею по запросу и подводит итог	`array{status: FipsSelfTestStatus, operational: bool, failed: list<string>}`	Не бросает; провалы попадают в `failed`	Для админ-эндпоинтов здоровья и использования в CLI
`FipsCryptoPolicy::strict()`	`?FipsSelfTest $selfTest = null`	Пресет FIPS 140-3: SHA-256/384/512; одобренные OID RSA, RSASSA-PSS, ECDSA; `aes-256-cbc`, `aes-256-gcm`; RSA >= 2048, EC >= 256	`self`	Ничего	Конструктор приватный; пресеты — единственная точка входа
`FipsCryptoPolicy::standard()`	`?FipsSelfTest $selfTest = null`	Пресет FIPS 140-2: строгий набор плюс `aes-128-cbc`	`self`	Ничего	Только для устаревшей совместимости
`FipsCryptoPolicy::assertPreOperational()`	Нет	Прогоняет или воспроизводит зафиксированный результат батареи запуска	`void`	`FipsModuleErrorStateException`, когда проваливается любой тест запуска	Приводится в действие швом енфорсмента Core перед первой операцией
`FipsCryptoPolicy` — поверхность запросов	Входы `string` / `int`	Проверки членства в списке разрешённого; неизвестный тип ключа запрещается	`bool` / `string`	Ничего	`isHashAlgorithmAllowed`, `isSignatureAlgorithmAllowed`, `isEncryptionAlgorithmAllowed`, `isKeyStrengthAllowed`, `getPreferredHashAlgorithm`, `getName`
`FipsModeGuard::__construct()`	`CryptoPolicyInterface $policy`, `?FipsBootGuard $bootGuard = null`, `?FipsAuditLogger $auditLogger = null`	Оборачивает политику границами в стиле assert	—	Ничего	Без `$bootGuard` нет затвора самотеста; продакшн-композиция его предоставляет
`FipsModeGuard::assertHashAllowed()`	`string $algorithm`	Сначала каталог запретов, затем список разрешённого	`void`	`FipsViolationException`; `FipsModuleErrorStateException`, когда подключён страж запуска	Запись аудита предшествует любому `FipsViolationException`
`FipsModeGuard::assertSignatureAlgorithmAllowed()`	`string $oid`	Сначала каталог запретов, затем список разрешённого	`void`	То же, что выше	OID сопоставляются точно
`FipsModeGuard::assertEncryptionAllowed()`	`string $algorithm`	Сначала каталог запретов, затем список разрешённого	`void`	То же, что выше	Имена сравниваются в нижнем регистре
`FipsModeGuard::assertKeyStrengthAllowed()`	`string $keyType`, `int $bitLength`	Сначала каталог запретов, затем минимумы политики	`void`	То же, что выше	Неизвестный тип ключа запрещается
`FipsModeGuard::getPolicy()`	Нет	Возвращает обёрнутую политику	`CryptoPolicyInterface`	Ничего	—
`FipsBootGuard::__construct()`	`FipsSelfTest $selfTest`	Держит батарею; не запускает её	—	Ничего	Один цикл запуска на экземпляр
`FipsBootGuard::report()`	Нет	Один раз прогоняет батарею, кеширует отчёт, залипает при ошибке	`FipsSelfTestReport`	Ничего	Первый вызов запускает тесты
`FipsBootGuard::rerun()`	Нет	Принудительно выполняет свежий прогон; прогон с ошибкой залипает на процесс	`FipsSelfTestReport`	Ничего	Самотест по запросу; не путь восстановления после ошибки
`FipsBootGuard::assertOperational()`	Нет	Утверждает, что модуль работоспособен; залипает на весь процесс	`void`	`FipsModuleErrorStateException`	Чистый экземпляр всё равно бросает, если процесс зафиксировал ошибку
`FipsBootGuard::status()`	Нет	Сообщает кешированный статус	`FipsSelfTestStatus`	Ничего	`ERROR` при залипании; `PRE_OPERATIONAL`, когда ещё ни разу не запущен
`FipsSelfTest::__construct()`	`?callable $randomBytesProvider = null`, `?callable $hashProvider = null`	Использует платформенные `hash()` и `random_bytes()`	—	Ничего	Переопределения существуют для детерминированных тестов на провал
`FipsSelfTest::run()`	Нет	Выполняет полную батарею; никогда не срабатывает по короткому пути	`FipsSelfTestReport`	Ничего	Провалы попадают в отчёт, а не в исключения
`FipsSelfTestReport`	`FipsSelfTestStatus $status`, `array $results`, `array $failedResults`	Неизменяемый агрегат одного прогона	—	`assertOperational()` бросает `FipsModuleErrorStateException` в состоянии ошибки	Также `isOperational()`, `isError()`
`FipsSelfTestResult`	`string $algorithm`, `string $kind`, `bool $passed`, `string $message = ''`	Неизменяемый результат отдельного теста	—	Ничего	`kind` — это `KAT`, `PWCT` или `HEALTH`; также `isPassed()`, `isFailed()`
`FipsSelfTestStatus`	—	Перечисление на основе строки	—	Ничего	Случаи `PRE_OPERATIONAL`, `OPERATIONAL`, `ERROR`
`FipsSignatureEnforcer::__construct()`	`FipsModeGuard $guard`	Оборачивает страж с затвором запуска для узловых точек подписи	—	Ничего	—
`FipsSignatureEnforcer::assertSignatureGenerationAllowed()`	`string $algorithm`, `string $certificatePem`	Разрешает OID и стойкость ключа, затем делегирует стражу	`void`	`FipsViolationException` (неизвестный алгоритм, неодобренный дайджест PSS, недоказуемый ключ или запрет политики); `FipsModuleErrorStateException` через страж	Только путь генерации; проверка сюда никогда не направляется
`FipsAuditLogger::__construct()`	`CryptoPolicyInterface $policy`, `LoggerInterface $logger`	Оборачивает PSR-3 логгер и ту же политику, которую применяет страж	—	Ничего	Записанные решения не могут расходиться с применёнными
`FipsAuditLogger::logHashOperation()` / `logSignatureOperation()` / `logEncryptionOperation()` / `logKeyStrengthCheck()`	Входы `string` / `int` по решению	Логирует ALLOW на уровне INFO и DENY на уровне WARNING	`bool` (true, когда разрешено)	Ничего	Структурированный контекст: имя политики, элемент, решение
`FipsTransitioningAlgorithms`	Входы `string` / `int`	Статический каталог запретов SP 800-131A Rev.2	`bool` / `list<string>`	Ничего	`isHashDisallowed`, `isSignatureOidDisallowed`, `isEncryptionDisallowed`, `isKeyStrengthDisallowed`, плюс `disallowedHashes`, `disallowedSignatureOids`, `disallowedEncryption`
`FipsViolationException`	`string $policyName`, `string $violatingItem`, `string $reason`	Типизированное нарушение политики с публичными readonly-полями	—	—	Подтип `NextPDF\Exception\NextPdfException`
`FipsModuleErrorStateException`	`array $failedResults`, `?string $message = null`	Отказ в состоянии ошибки, несущий результаты проваленных тестов	—	—	Подтип `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';
}

Контракт поведения

Список разрешённого политики — авторитетное решение. FipsTransitioningAlgorithms добавляет над ним явный слой запретов SP 800-131A Rev.2 для однозначных при аудите сообщений об отказе. Слой запретов никогда не расширяет и не переопределяет список разрешённого.
FipsCryptoPolicy::strict() разрешает SHA-256, SHA-384 и SHA-512; OID подписей RSA PKCS#1 v1.5, RSASSA-PSS и ECDSA, привязанные к этим хешам; aes-256-cbc и aes-256-gcm; и нижние границы ключей RSA 2048, EC 256, Ed25519 256. standard() дополнительно разрешает aes-128-cbc.
Батарея запуска покрывает: KAT дайджестов SHA-256/384/512, KAT HMAC-SHA-256, KAT шифрования-и-расшифровки AES-256-CBC, KAT тега AES-256-GCM, тест попарной согласованности ECDSA P-256 и проверку здоровья DRBG. FipsSelfTest::run() всегда выполняет каждый тест и никогда не срабатывает по короткому пути, поэтому отчёт полон для аудиторских доказательств.
Строка DRBG — это непрерывная проверка здоровья (длина выборки плюс различие последовательных выборок), а не тест методом известного ответа. Обязательство известного ответа для DRBG делегируется базовому FIPS-валидированному провайдеру, который предоставляет оператор.
Состояние ошибки залипает на процесс. Первый отчёт ERROR, наблюдаемый любым FipsBootGuard, залипает на весь процесс. Свежий экземпляр стража или политики не может отмыть ошибку, а последующий успешный повторный прогон её не очищает. Только перезапуск процесса (настоящий цикл питания) сбрасывает состояние.
FipsCryptoPolicy реализует NextPDF\Contracts\CryptoPolicyInterface и NextPDF\Contracts\PreOperationalSelfTestInterface. Будучи настроенной как криптополитика Core, шов енфорсмента Core приводит в действие assertPreOperational() перед созданием первой подписи или шифротекста.
FipsSignatureEnforcer контролирует только путь генерации. Проверка уже созданных подписей — это устаревшее использование по SP 800-131A Rev.2, и она никогда не проходит через енфорсер.
Когда подключён аудит-логгер, каждая граница assert выдаёт одну запись ALLOW (INFO) или DENY (WARNING) перед любым выбросом нарушения политики. Поэтому каждый отказ FipsViolationException задокументирован в трейле. Затвор стража запуска срабатывает первым, поэтому отказ в состоянии ошибки поднимается до записи аудита. FipsAuditLogger сверяется с той же политикой, которую применяет страж, поэтому записанные решения не могут расходиться с применёнными.

Граничные случаи и режимы отказа

Неизвестный тип ключа запрещается обоими слоями: политика возвращает false, а каталог трактует его как запрещённый.
Идентификатор алгоритма подписи, который енфорсер не может сопоставить с OID подписи, отклоняется отказоустойчиво-закрыто (fail-closed) с FipsViolationException.
Каждый вариант RSASSA-PSS использует один и тот же OID 1.2.840.113549.1.1.10, поэтому по одному OID нельзя доказать дайджест. Енфорсер явно привязывает эффективный дайджест и запрещает любой токен PSS, чей дайджест не является SHA-256/384/512.
Сертификат, который не удаётся разобрать или для которого недоступна битовая длина открытого ключа, запрещается как key:unprovable.
В среде выполнения без асимметричных примитивов OpenSSL тест попарной согласованности ECDSA записывает провал, а не пропуск, и модуль переходит в ERROR.
Две одинаковые последовательные 32-байтовые случайные выборки проваливают проверку здоровья DRBG (обнаружение застрявшего вывода) и вынуждают ERROR.
FipsModeGuard, сконструированный без стража запуска, выполняет только проверки политики и не имеет затвора самотеста. Продакшн-композиция проходит через FipsBootstrap, который всегда подключает затвор.
Имена хешей и шифров сравниваются в нижнем регистре; OID подписей сопоставляются точно, без нормализации.
После FipsBootstrap::lazy() модуль остаётся в PRE_OPERATIONAL до тех пор, пока первая граница assert не запустит батарею. PRE_OPERATIONAL при проверке трактуется как «не работоспособен».

Поведение в режиме FIPS

Этот модуль сам по себе является поверхностью режима FIPS. Пока модуль находится в состоянии ошибки и пока выполняются предоперационные самотесты, вывод криптографических данных запрещён: каждая граница assert бросает FipsModuleErrorStateException до создания любой подписи или шифротекста (ISO/IEC 19790:2025 §7.3.3 b), AS03.07). FipsBootGuard::status() и FipsBootstrap::selfTestReport() раскрывают состояние, так что оператор может определить, что модуль перешёл в состояние ошибки (ISO/IEC 19790:2025 §7.10.3). Эти поведения — заявления о возможностях кода NextPDF, а не заявление о валидации: граница модуля, которую валидирует FIPS 140, — это криптографический провайдер, предоставленный оператором, а не NextPDF.

Соответствие

Заявление	Стандарт	Пункт
FIPS 140-3 основан на ISO/IEC 19790 и ISO/IEC 24759; поэтому эта страница цитирует пункты ISO/IEC 19790.	FIPS 140-3	Introduction (fips_140_3#x26.x2)
Вывод запрещён в состоянии ошибки и во время предоперационных самотестов.	ISO/IEC 19790:2025	§7.3.3 b) [AS03.07]
Тест методом известного ответа сравнивает вычисленный результат с известным ожидаемым выводом; батарея реализует эту форму.	ISO/IEC 19790:2025	§7.10.4
Оператор может определить состояние ошибки по выводу статуса.	ISO/IEC 19790:2025	§7.10.3 [AS10.10]
Операторы могут инициировать самотесты по запросу для периодического тестирования; `rerun()` и `selfTestReport()` это обеспечивают.	ISO/IEC 19790:2025	§7.10.5 [AS10.54]
SHA-1 запрещён для генерации новых цифровых подписей; каталог запретов его отклоняет.	NIST SP 800-131A Rev.2	§9
Генерация подписи ниже 112-битной стойкости (RSA < 2048, порядок ECDSA < 224) запрещена; нижние границы ключей это обеспечивают.	NIST SP 800-131A Rev.2	§3 Table 2
Проверка уже созданных подписей SHA-1 — устаревшее использование; она не проходит через затвор генерации.	NIST SP 800-131A Rev.2	Change summary (9.x4.p12)

Все пункты пересказаны; нормативный текст не воспроизводится. NextPDF не делает никакого заявления о сертификации FIPS 140. Модуль выравнивает своё поведение с цитируемыми пунктами как возможность содействия соответствию. Является ли развёртывание FIPS-совместимым, зависит от валидированного провайдера оператора, определения границы модуля и программы соответствия — а не только от NextPDF.

Заметки по разработке

Детерминированные тесты на провал внедряют сломанные провайдеры через конструктор FipsSelfTest или через параметры $selfTest в FipsCryptoPolicy::strict(), standard() и методах FipsBootstrap.
У залипающей на процесс защёлки состояния ошибки есть внутренний, только для тестов, хук сброса. Он не является частью поддерживаемого API, и продакшн-код не должен его вызывать.
Каждый рабочий процесс PHP запускает свою собственную батарею при включении. Отчёт кешируется на экземпляр, поэтому проверки на горячем пути — это проверки статуса за постоянное время.
Не перехватывайте FipsModuleErrorStateException и не продолжайте работу. Исключение означает, что модуль отказывает в криптографических услугах; правильная реакция — остановиться и перезапустить процесс после устранения проблемы.
FipsBootstrap::selfTestReport() обслуживает потребности в самотестах по запросу и периодических, таких как эндпоинты здоровья. Успешный прогон по запросу никогда не очищает зафиксированную ошибку.

Смотрите также

Криптополитика FIPS 140-2/3 и самотесты — страница возможности с настройкой и примерами.
Безопасность — подробный справочник — сводные средства контроля безопасности Enterprise.
Подпись — подробный справочник — производитель долгосрочных PAdES и его заметка о режиме FIPS.
Безопасность — NextPDF Core — поверхность шифрования и подписи Core, к которой привязывается политика.

Граница публикации

Эта страница документирует только внешне наблюдаемое поведение и поддерживаемую публичную поверхность API. Внутренние пути пространств имён, вспомогательные классы, таблицы механизмов, имена файлов ранбуков и префиксы тикетов выходят за рамки.