Enterprise edycjastabilność: Eksperymentalna

Podgląd podpisywania postkwantowego — szczegółowa referencja

W skrócie

Ta strona jest dokumentacją referencyjną na poziomie kontraktu dla powierzchni podglądu podpisywania postkwantowego (PQS) w NextPDF Enterprise. Obejmuje trzy publiczne symbole: wyliczenie zestawów parametrów Pkcs11PqsAlgorithm, bramkę procesu PqsPreviewFeature oraz deskryptor PqsCapabilityStatus. Dokumentuje również bramkę środowiskową NEXTPDF_FEATURE_PREVIEW_PQS_HSM.

Powierzchnia jest eksperymentalna i domyślnie wyłączona. Rozpoznaje identyfikatory algorytmów, zestawy parametrów i długości podpisów ML-DSA (FIPS 204) oraz SLH-DSA (FIPS 205). Rozpoznanie nie jest werdyktem walidacji. Nie istnieje postkwantowa ścieżka weryfikacji. Nie jest składana żadna deklaracja AdES, walidacji FIPS ani zgodności, a flaga podglądu nie może takiej utworzyć. Konsumujący punkt wejścia podpisywania, Pkcs11Signer::signPqs(), jest opisany na stronie możliwości.

Dostępność i licencjonowanie

Ta funkcja jest dostarczana w NextPDF Enterprise (nextpdf/enterprise) i aktywuje się przez kopertę licencyjną poziomu Enterprise. Wdrożenie bez tego uprawnienia nie ładuje klas tej funkcji. Porównaj edycje i uzyskaj licencję.

Licencja aktywuje całą powierzchnię PKCS#11 Enterprise. Ścieżka postkwantowa wewnątrz niej pozostaje podglądem niezależnie od poziomu licencji. Nadal wymagane są dwie niezależne zgody: bramka procesu udokumentowana tutaj oraz flaga konstruktora dla poszczególnych podpisujących w Pkcs11Signer.

Publiczna powierzchnia API

Symbol	Parametry	Zachowanie domyślne	Zwraca	Rzuca lub kończy się błędem	Uwagi
`Pkcs11PqsAlgorithm`	wyliczenie oparte na string, 15 przypadków	Nazywa jeden zestaw parametrów FIPS 204 / FIPS 205 na przypadek	przypadek wyliczenia	Nic przy dostępie do przypadku	Wartości przypadków to nazwy zestawów parametrów, np. `ML-DSA-65`.
`Pkcs11PqsAlgorithm::isMlDsa()`	brak	Test rodziny	`bool`	Nie rzuca	`true` dla `MlDsa44`, `MlDsa65`, `MlDsa87`.
`Pkcs11PqsAlgorithm::isSlhDsa()`	brak	Negacja `isMlDsa()`	`bool`	Nie rzuca	`true` dla dwunastu przypadków SLH-DSA.
`Pkcs11PqsAlgorithm::mechanismId()`	brak	Mapuje rodzinę na kandydujący identyfikator mechanizmu PQ PKCS#11 v3.1	`int`	PHP `Error`, gdy środowisko uruchomieniowe nie ma tymczasowych stałych PQ `Pkcs11`	`CKM_ML_DSA` lub `CKM_SLH_DSA`; oba identyfikatory są tymczasowe.
`Pkcs11PqsAlgorithm::parameterSetId()`	brak	Mapuje przypadek na dyskryminator zestawu parametrów OASIS	`int`	PHP `Error`, gdy środowisko uruchomieniowe nie ma tymczasowych stałych PQ `Pkcs11`	Wartości `CKP_*`; tymczasowe.
`Pkcs11PqsAlgorithm::signatureLength()`	brak	Wymagana przez FIPS długość podpisu w bajtach dla przypadku	`int` (dodatni)	Nie rzuca	Wykorzystywana przez ścieżkę podpisywania do odrzucenia zwróconego podpisu o nieoczekiwanej długości.
`Pkcs11PqsAlgorithm::nistCategory()`	brak	Deklarowana kategoria siły bezpieczeństwa NIST	`int`	Nie rzuca	Zwraca 1, 2, 3 lub 5.
`PqsPreviewFeature`	wyliczenie oparte na string, 1 przypadek	Pojedynczy przypadek `PREVIEW_PQS_HSM`; stała `ENV_PREVIEW_PQS_HSM`	przypadek wyliczenia	Nic przy dostępie do przypadku	Bramka podglądu na poziomie procesu.
`PqsPreviewFeature::isEnabled()`	brak	Odczytuje `getenv()` na żywo; ścisłe porównanie z ciągiem `1`	`bool`	Nie rzuca	Brak zmiennej lub dowolna inna wartość, w tym `0`, `true`, `yes`, oznacza wyłączenie.
`PqsCapabilityStatus::__construct()`	dziewięć nazwanych pól readonly	Buduje dowolną instancję deskryptora	`PqsCapabilityStatus`	Nie rzuca	`current()` jest kanonicznym konstruktorem.
`PqsCapabilityStatus::current()`	brak	Buduje deskryptor dla otaczającego procesu	`PqsCapabilityStatus`	Nie rzuca	Każdy logiczny wskaźnik deklaracji jest stały; tylko `hsmRoundtripPreviewEnabled` zmienia się wraz z bramką.
`PqsCapabilityStatus::summary()`	brak	Jednowierszowy tekst statusu	`string`	Nie rzuca	Sformułowanie nie niesie żadnej deklaracji dostępności, archiwizacji ani walidacji.

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

Kontrakt zachowania

Katalog zestawów parametrów. NextPDF\Enterprise\Security\Signature\Hsm\Pkcs11PqsAlgorithm wylicza trzy zestawy ML-DSA (FIPS 204) i dwanaście zestawów SLH-DSA (FIPS 205 §11.p12, Table 2). Każdy przypadek mapuje się na tymczasowy identyfikator mechanizmu, dyskryminator zestawu parametrów, wymaganą przez FIPS długość podpisu w bajtach oraz deklarowaną kategorię NIST.
Długości podpisów. signatureLength() zwraca 2420, 3309 i 4627 bajtów dla MlDsa44, MlDsa65 i MlDsa87, zgodnie z FIPS 204 §4.p15 (Table 2). Przypadki SLH-DSA zwracają 7856, 17088, 16224, 35664, 29792 i 49856 bajtów zależnie od poziomu i wariantu, zgodnie z FIPS 205 §11 (Table 2). Konsumujący podpisujący rzuca HsmOperationException, gdy zwrócony podpis ma inną długość, odzwierciedlając dyscyplinę odrzucania na podstawie długości z FIPS 204 §x34.
Kategorie. nistCategory() zwraca 2, 3 i 5 dla przypadków ML-DSA, zgodnie z FIPS 204 §4.p9. Przypadki SLH-DSA zwracają 1, 3 i 5 zależnie od poziomu parametru bezpieczeństwa.
Bramka procesu. PqsPreviewFeature::PREVIEW_PQS_HSM jest domyślnie wyłączona. isEnabled() zwraca true tylko wtedy, gdy zmienna środowiskowa NEXTPDF_FEATURE_PREVIEW_PQS_HSM jest dokładnie równa ciągowi 1. Odczyt jest na żywo przy każdym wywołaniu; nic nie jest zapamiętywane.
Uzupełniające bramkowanie. Bramka procesu jest oddzielna od zgody konstruktora $enablePostQuantum dla poszczególnych podpisujących w Pkcs11Signer. Wywołanie podpisywania kończy się bezpiecznym niepowodzeniem bez zgody dla danego podpisującego. Bramka procesu istnieje jako pojedyncza audytowalna granica dla dowolnego przyszłego zachowania round-trip lub archiwizacji.
Niezmiennik uczciwości. NextPDF\Enterprise\Security\Signature\Hsm\PqsCapabilityStatus::current() na sztywno ustawia generallyAvailable, adesCompliant, verificationAvailable i conformanceClaimed na false, a recognitionOnly na true. Żadna konfiguracja, opcja konstruktora ani flaga środowiskowa nie włącza deklaracji. Tylko hsmRoundtripPreviewEnabled odzwierciedla bramkę.
Brak ścieżki weryfikacji. NextPDF nie ma postkwantowej ścieżki weryfikacji. Rozpoznany identyfikator algorytmu lub poprawnie sformułowana długość podpisu nigdy nie jest werdyktem akceptacji.

Przypadki brzegowe i tryby awarii

Ustawienie zmiennej bramki na 0, true, yes, on lub pusty ciąg pozostawia bramkę wyłączoną. Włącza ją tylko dokładny ciąg 1.
Zmiany putenv() wchodzą w życie przy następnym wywołaniu isEnabled(), ponieważ odczyt jest na żywo. Bramka przełączona w trakcie procesu jest obserwowana natychmiast.
mechanismId() i parameterSetId() rozwiązują stałe z przestrzeni nazw rozszerzenia Pkcs11. Środowisko uruchomieniowe bez tymczasowych stałych rozszerzenia postkwantowego kończy się błędem PHP Error (niezdefiniowana stała) w czasie wywołania.
Identyfikatory mechanizmu i zestawu parametrów są tymczasowe. OASIS nie sfinalizował postkwantowego rejestru PKCS#11 v3.1. Token, którego firmware przypisuje inne identyfikatory, zawiedzie na warstwie PKCS#11; operatorzy muszą potwierdzić identyfikatory firmware przed włączeniem podglądu.
Kontekst podpisywania akceptowany przez konsumujący podpisujący jest ograniczony do 255 bajtów, co odpowiada kontraktowi wejścia podpisywania FIPS 204 (§x43.p2). Dłuższy kontekst rzuca InvalidArgumentException przed jakimkolwiek wywołaniem tokena.
PqsCapabilityStatus::__construct() jest publiczny, więc ręcznie zbudowana instancja może nieść dowolne wartości logiczne. Taka instancja jest tylko obiektem wartości. Nie zmienia żadnego zachowania podpisywania. current() jest kanonicznym, na sztywno zakodowanym konstruktorem.
Wybór między losowym a deterministycznym w konsumującym podpisującym jest zgodny z semantyką FIPS 205 §x65.p7: podpisywanie zabezpieczone (hedged) jest domyślne. Flaga jest ignorowana dla ML-DSA, które zawsze losuje za pomocą własnego nonce.

Zachowanie w trybie FIPS

ML-DSA i SLH-DSA są algorytmami FIPS 204 i FIPS 205, ale ten podgląd nie niesie żadnej deklaracji walidacji FIPS 140-3. Dla tej ścieżki nie ustanowiono żadnego zwalidowanego przez FIPS postkwantowego round-trip HSM. Profil polityki kryptograficznej trybu FIPS Enterprise, udokumentowany w szczegółowej dokumentacji Security, bramkuje klasyczne algorytmy podpisywania; nie dopuszcza powierzchni PQS do zwalidowanego zbioru. Włączenie trybu FIPS nie sprawia, że podpisywanie postkwantowe staje się zwalidowane przez FIPS. Nie wdrażaj podglądu tam, gdzie wymagany jest podpis zwalidowany przez FIPS.

Zgodność

Deklaracja	Standard	Klauzula
ML-DSA-44/65/87 niosą deklarowane kategorie NIST 2, 3, 5.	FIPS 204	§4.p9
Rozmiary podpisów ML-DSA to 2420, 3309, 4627 bajtów.	FIPS 204	§4.p15 (Table 2)
Ciąg bajtów kontekstu podpisywania jest ograniczony do 255 bajtów.	FIPS 204	§x43.p2
Podpis lub klucz o nieprawidłowej długości musi zostać odrzucony.	FIPS 204	§x34
Zatwierdzono dwanaście zestawów parametrów SLH-DSA.	FIPS 205	§11.p12 (Table 2)
Rozmiary podpisów SLH-DSA są zgodne z Table 2 (7856 bajtów dla 128s).	FIPS 205	§11.p6
Podpisywanie zabezpieczone (hedged) jest domyślne; istnieje wariant deterministyczny.	FIPS 205	§x65.p7
Katalog zestawów CAdES/PAdES profiluje tylko RSA i EC-DSA.	ETSI TS 119 312 V1.5.1	§7.x7.p10 (Table A.1)
Identyfikatory mechanizmów PQ PKCS#11 są tymczasowe.	OASIS PKCS#11 v3.1	product-source grounded

Wszystkie klauzule są parafrazowane. NextPDF nie odtwarza tekstu normatywnego. NextPDF nie posiada żadnej certyfikacji i żadnej nie udziela. Powyższe stwierdzenia są stwierdzeniami o zgodności strukturalnej dotyczącymi identyfikatorów, długości i granic. Nie są wynikami testów zgodności, atestacjami stron trzecich ani deklaracją zgodności FIPS, OASIS czy ETSI. PqsCapabilityStatus koduje tę postawę w kodzie: conformanceClaimed jest false, adesCompliant jest false, a verificationAvailable jest false, w każdej konfiguracji. Podpis wytworzony przez ten podgląd nie jest zgodny z AdES do długoterminowej archiwizacji, a większość przeglądarek PDF odrzuca go w czasie walidacji.

Uwagi programistyczne

Postkwantowy rejestr mechanizmów OASIS PKCS#11 nie jest sfinalizowany; identyfikatory CKM_ML_DSA / CKM_SLH_DSA oraz stałe zestawów parametrów użyte tutaj są tymczasowe i oparte na źródle produktu, a nie na cytacie ze specyfikacji.
Obecny kamień milowy to gotowość przetestowana na atrapach. Nie zwalidowano jeszcze żadnego rzeczywistego round-trip HSM z postkwantowym firmware.
Utrzymuj obie bramki wyłączone w produkcji. Podgląd nie dodaje żadnej funkcji produkcyjnej, której brakuje klasycznej ścieżce PKCS#11 RSA/ECDSA.
Przed jakąkolwiek oceną z rzeczywistym sprzętem potwierdź identyfikatory mechanizmu i zestawu parametrów firmware tokena względem wartości tymczasowych. Niezgodność zawiedzie na warstwie PKCS#11, a nie wewnątrz NextPDF.
Traktuj PqsCapabilityStatus::current() jako jedyne źródło prawdy przy prezentowaniu statusu PQS w narzędziach lub UI. Nie powtarzaj ręcznie jego wartości logicznych.
Wyjście summary() jest bezpieczne dla logów i punktów końcowych statusu; jest sformułowane tak, aby nie nieść żadnej deklaracji dostępności ani walidacji.

Zobacz także

Granica publikacji

Ta strona dokumentuje wyłącznie zachowanie obserwowalne zewnętrznie oraz wspieraną publiczną powierzchnię API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tabele mechanizmów, nazwy plików runbooków oraz prefiksy zgłoszeń są poza zakresem.