Enterprise редакциястабильность: Экспериментальная

Предпросмотр постквантовой подписи — глубокий справочник

Кратко

Эта страница — справочник контрактного уровня по поверхности предпросмотра постквантовой подписи (PQS) в NextPDF Enterprise. Она охватывает три публичных символа: перечисление наборов параметров Pkcs11PqsAlgorithm, процессный шлюз PqsPreviewFeature и дескриптор PqsCapabilityStatus. Также она документирует шлюз окружения NEXTPDF_FEATURE_PREVIEW_PQS_HSM.

Поверхность является экспериментальной и выключена по умолчанию. Она распознаёт идентификаторы алгоритмов, наборы параметров и длины подписей ML-DSA (FIPS 204) и SLH-DSA (FIPS 205). Распознавание не является вердиктом проверки. Пути постквантовой проверки не существует. Не делается никаких заявлений о AdES, FIPS-валидации или соответствии, и флаг предпросмотра не может их создать. Потребляющая точка входа подписи, Pkcs11Signer::signPqs(), описана на странице возможности.

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

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

Лицензия активирует поверхность Enterprise PKCS#11 целиком. Постквантовый путь внутри неё остаётся предпросмотром независимо от уровня лицензии. По-прежнему требуются два независимых согласия: процессный шлюз, документированный здесь, и флаг конструктора уровня подписанта на Pkcs11Signer.

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

Символ	Параметры	Поведение по умолчанию	Возвращает	Бросает или падает с	Примечания
`Pkcs11PqsAlgorithm`	перечисление на основе string, 15 вариантов	Именует один набор параметров FIPS 204 / FIPS 205 на вариант	вариант перечисления	Ничего при доступе к варианту	Значения вариантов — имена наборов параметров, например `ML-DSA-65`.
`Pkcs11PqsAlgorithm::isMlDsa()`	нет	Проверка семейства	`bool`	Не бросает	`true` для `MlDsa44`, `MlDsa65`, `MlDsa87`.
`Pkcs11PqsAlgorithm::isSlhDsa()`	нет	Отрицание `isMlDsa()`	`bool`	Не бросает	`true` для двенадцати вариантов SLH-DSA.
`Pkcs11PqsAlgorithm::mechanismId()`	нет	Сопоставляет семейство с кандидатным идентификатором PQ-механизма PKCS#11 v3.1	`int`	PHP `Error`, когда среде выполнения не хватает предварительных PQ-констант `Pkcs11`	`CKM_ML_DSA` или `CKM_SLH_DSA`; оба идентификатора предварительные.
`Pkcs11PqsAlgorithm::parameterSetId()`	нет	Сопоставляет вариант с дискриминатором набора параметров OASIS	`int`	PHP `Error`, когда среде выполнения не хватает предварительных PQ-констант `Pkcs11`	Значения `CKP_*`; предварительные.
`Pkcs11PqsAlgorithm::signatureLength()`	нет	Предписанная FIPS длина подписи в байтах для варианта	`int` (положительный)	Не бросает	Используется путём подписи для отклонения возвращённой подписи неожиданной длины.
`Pkcs11PqsAlgorithm::nistCategory()`	нет	Заявленная категория стойкости безопасности NIST	`int`	Не бросает	Возвращает 1, 2, 3 или 5.
`PqsPreviewFeature`	перечисление на основе string, 1 вариант	Единственный вариант `PREVIEW_PQS_HSM`; константа `ENV_PREVIEW_PQS_HSM`	вариант перечисления	Ничего при доступе к варианту	Шлюз предпросмотра уровня процесса.
`PqsPreviewFeature::isEnabled()`	нет	Читает `getenv()` вживую; строгое сравнение со строкой `1`	`bool`	Не бросает	Отсутствие переменной или любое другое значение, включая `0`, `true`, `yes`, означает выключено.
`PqsCapabilityStatus::__construct()`	девять именованных readonly-полей	Строит произвольный экземпляр дескриптора	`PqsCapabilityStatus`	Не бросает	`current()` — канонический конструктор.
`PqsCapabilityStatus::current()`	нет	Строит дескриптор для окружающего процесса	`PqsCapabilityStatus`	Не бросает	Каждый булев признак заявления фиксирован; только `hsmRoundtripPreviewEnabled` меняется вместе со шлюзом.
`PqsCapabilityStatus::summary()`	нет	Однострочный текст статуса	`string`	Не бросает	Формулировка не несёт заявления о доступности, архивировании или проверке.

enum Pkcs11PqsAlgorithm: string

case MlDsa44 = 'ML-DSA-44';
case MlDsa65 = 'ML-DSA-65';
case MlDsa87 = 'ML-DSA-87';

case SlhDsaSha2_128s = 'SLH-DSA-SHA2-128s';
case SlhDsaShake_128s = 'SLH-DSA-SHAKE-128s';
case SlhDsaSha2_128f = 'SLH-DSA-SHA2-128f';
case SlhDsaShake_128f = 'SLH-DSA-SHAKE-128f';

case SlhDsaSha2_192s = 'SLH-DSA-SHA2-192s';
case SlhDsaShake_192s = 'SLH-DSA-SHAKE-192s';
case SlhDsaSha2_192f = 'SLH-DSA-SHA2-192f';
case SlhDsaShake_192f = 'SLH-DSA-SHAKE-192f';

case SlhDsaSha2_256s = 'SLH-DSA-SHA2-256s';
case SlhDsaShake_256s = 'SLH-DSA-SHAKE-256s';
case SlhDsaSha2_256f = 'SLH-DSA-SHA2-256f';
case SlhDsaShake_256f = 'SLH-DSA-SHAKE-256f';

public function isMlDsa(): bool
public function isSlhDsa(): bool
public function mechanismId(): int
public function parameterSetId(): int
public function signatureLength(): int
public function nistCategory(): int

enum PqsPreviewFeature: string

case PREVIEW_PQS_HSM = 'preview_pqs_hsm';

public const string ENV_PREVIEW_PQS_HSM = 'NEXTPDF_FEATURE_PREVIEW_PQS_HSM';

public function isEnabled(): bool

final readonly class PqsCapabilityStatus

public const string MATURITY_PREVIEW_EXPERIMENTAL = 'preview-experimental';
public const string MECHANISM_STATUS_PROVISIONAL = 'provisional';

public function __construct(
    public bool $hsmRoundtripPreviewEnabled,
    public bool $generallyAvailable,
    public bool $adesCompliant,
    public bool $verificationAvailable,
    public bool $conformanceClaimed,
    public bool $recognitionOnly,
    public string $maturity,
    public string $mechanismIdStatus,
    public string $envGate,
)

public static function current(): self
public function summary(): string

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

Каталог наборов параметров. NextPDF\Enterprise\Security\Signature\Hsm\Pkcs11PqsAlgorithm перечисляет три набора ML-DSA (FIPS 204) и двенадцать наборов SLH-DSA (FIPS 205 §11.p12, Table 2). Каждый вариант сопоставляется с предварительным идентификатором механизма, дискриминатором набора параметров, предписанной FIPS длиной подписи в байтах и заявленной категорией NIST.
Длины подписей. signatureLength() возвращает 2420, 3309 и 4627 байт для MlDsa44, MlDsa65 и MlDsa87, согласно FIPS 204 §4.p15 (Table 2). Варианты SLH-DSA возвращают 7856, 17088, 16224, 35664, 29792 и 49856 байт по уровню и варианту, согласно FIPS 205 §11 (Table 2). Потребляющий подписант бросает HsmOperationException, когда возвращённая подпись имеет другую длину, отражая дисциплину отклонения по длине FIPS 204 §x34.
Категории. nistCategory() возвращает 2, 3 и 5 для вариантов ML-DSA, согласно FIPS 204 §4.p9. Варианты SLH-DSA возвращают 1, 3 и 5 по уровню параметра безопасности.
Процессный шлюз. PqsPreviewFeature::PREVIEW_PQS_HSM по умолчанию выключен. isEnabled() возвращает true только когда переменная окружения NEXTPDF_FEATURE_PREVIEW_PQS_HSM в точности равна строке 1. Чтение выполняется вживую при каждом вызове; ничего не мемоизируется.
Взаимодополняющее шлюзование. Процессный шлюз отделён от согласия конструктора уровня подписанта $enablePostQuantum на Pkcs11Signer. Вызов подписи безопасно падает без согласия уровня подписанта. Процессный шлюз существует как единственная поддающаяся аудиту граница для любого будущего поведения round-trip или архивирования.
Инвариант честности. NextPDF\Enterprise\Security\Signature\Hsm\PqsCapabilityStatus::current() жёстко зашивает generallyAvailable, adesCompliant, verificationAvailable и conformanceClaimed в false, а recognitionOnly в true. Никакая конфигурация, опция конструктора или флаг окружения не включают заявление. Только hsmRoundtripPreviewEnabled отражает шлюз.
Нет пути проверки. У NextPDF нет пути постквантовой проверки. Распознанный идентификатор алгоритма или корректно сформированная длина подписи никогда не являются вердиктом приёмки.

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

Установка переменной шлюза в 0, true, yes, on или пустую строку оставляет шлюз выключенным. Включает его только точная строка 1.
Изменения putenv() вступают в силу при следующем вызове isEnabled(), потому что чтение выполняется вживую. Шлюз, переключённый в середине процесса, наблюдается немедленно.
mechanismId() и parameterSetId() разрешают константы из пространства имён расширения Pkcs11. Среда выполнения без предварительных постквантовых констант расширения падает с PHP Error (неопределённая константа) во время вызова.
Идентификаторы механизма и набора параметров предварительные. OASIS не завершил постквантовый реестр PKCS#11 v3.1. Токен, чья прошивка назначает другие идентификаторы, упадёт на уровне PKCS#11; операторы должны подтвердить идентификаторы прошивки перед включением предпросмотра.
Контекст подписи, принимаемый потребляющим подписантом, ограничен 255 байтами, что соответствует контракту входа подписи FIPS 204 (§x43.p2). Более длинный контекст бросает InvalidArgumentException до любого обращения к токену.
PqsCapabilityStatus::__construct() публичен, поэтому вручную собранный экземпляр может нести произвольные булевы значения. Такой экземпляр — лишь объект-значение. Он не изменяет никакого поведения подписи. current() — канонический, жёстко зашитый конструктор.
Выбор между рандомизированным и детерминированным на потребляющем подписанте следует семантике FIPS 205 §x65.p7: подпись с хеджированием является умолчанием. Флаг игнорируется для ML-DSA, который всегда рандомизирует через собственный nonce.

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

ML-DSA и SLH-DSA — алгоритмы FIPS 204 и FIPS 205, но этот предпросмотр не несёт никакого заявления о валидации FIPS 140-3. Для этого пути не установлен ни один FIPS-валидированный постквантовый round-trip HSM. Профиль крипто-политики режима FIPS в Enterprise, документированный в глубоком справочнике по безопасности, шлюзует классические алгоритмы подписи; он не допускает поверхность PQS в валидированный набор. Включение режима FIPS не делает постквантовую подпись FIPS-валидированной. Не развёртывайте предпросмотр там, где требуется FIPS-валидированная подпись.

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

Заявление	Стандарт	Пункт
ML-DSA-44/65/87 несут заявленные категории NIST 2, 3, 5.	FIPS 204	§4.p9
Размеры подписей ML-DSA — 2420, 3309, 4627 байт.	FIPS 204	§4.p15 (Table 2)
Байтовая строка контекста подписи ограничена 255 байтами.	FIPS 204	§x43.p2
Подпись или ключ неверной длины должны быть отклонены.	FIPS 204	§x34
Одобрены двенадцать наборов параметров SLH-DSA.	FIPS 205	§11.p12 (Table 2)
Размеры подписей SLH-DSA следуют Table 2 (7856 байт для 128s).	FIPS 205	§11.p6
Подпись с хеджированием — умолчание; детерминированный вариант существует.	FIPS 205	§x65.p7
Каталог наборов CAdES/PAdES профилирует только RSA и EC-DSA.	ETSI TS 119 312 V1.5.1	§7.x7.p10 (Table A.1)
Идентификаторы PQ-механизмов PKCS#11 предварительные.	OASIS PKCS#11 v3.1	обосновано исходным кодом продукта

Все пункты пересказаны. NextPDF не воспроизводит нормативный текст. NextPDF не имеет сертификации и не предоставляет её. Приведённые выше утверждения — это утверждения о структурном соответствии идентификаторов, длин и границ. Они не являются результатами тестов соответствия, не являются сторонними аттестациями и не являются заявлением о соответствии FIPS, OASIS или ETSI. PqsCapabilityStatus кодирует эту позицию в коде: conformanceClaimed равен false, adesCompliant равен false, а verificationAvailable равен false в любой конфигурации. Подпись, созданная этим предпросмотром, не является AdES-совместимой для долгосрочного архивирования, и большинство просмотрщиков PDF отклоняют её во время проверки.

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

Постквантовый реестр механизмов OASIS PKCS#11 не завершён; используемые здесь идентификаторы CKM_ML_DSA / CKM_SLH_DSA и константы наборов параметров предварительны и обоснованы исходным кодом продукта, а не цитатой из спецификации.
Текущая веха — готовность, проверенная на моках. Ни один реальный round-trip HSM с постквантовой прошивкой ещё не валидирован.
Держите оба шлюза выключенными в продакшене. Предпросмотр не добавляет никакой продакшен-возможности, которой не было бы у классического пути RSA/ECDSA PKCS#11.
Перед любой оценкой на реальном оборудовании подтвердите идентификаторы механизма и набора параметров прошивки токена относительно предварительных значений. Несовпадение падает на уровне PKCS#11, а не внутри NextPDF.
Рассматривайте PqsCapabilityStatus::current() как единственный источник истины при отображении статуса PQS в инструментарии или UI. Не пересказывайте его булевы значения вручную.
Вывод summary() безопасен для журналов и статусных эндпоинтов; он сформулирован так, чтобы не нести заявления о доступности или проверке.

См. также

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

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