Status zdolności podglądowej postkwantowego podpisywania HSM (PQS)

W skrócie

Status zdolności podglądowej. Opcjonalny, domyślnie wyłączony, fail-closed. To podgląd podpisywania postkwantowego delegowanego do HSM. Nie jest ogólnie dostępny, nie jest zgodny z AdES, nie jest zwalidowany wg FIPS i nie wysuwa żadnego twierdzenia o certyfikacji ani zgodności. Podgląd jest wyłączony, dopóki się nie zgodzisz; gdy jest wyłączony, wywołanie podpisywania kończy się niepowodzeniem fail-closed z typowanym wyjątkiem.

NextPDF Enterprise udostępnia eksperymentalną powierzchnię podpisu postkwantowego (PQS), która napędza podpisywanie ML-DSA (FIPS 204) i SLH-DSA (FIPS 205) przez sprzętowy token PKCS#11. Ścieżka to Pkcs11Signer::signPqs(), bramkowana za jawną opcją na poziomie podpisującego ($enablePostQuantum) i, osobno, za flagą env na poziomie procesu (NEXTPDF_FEATURE_PREVIEW_PQS_HSM). Obie są domyślnie wyłączone.

Ta strona to uczciwa granica. Mówi, co podgląd robi — deleguje rzeczywistą operację podpisywania postkwantowego do tokenu — i z równą uczciwością, czym nie jest: nie jest GA, nie jest AdES, nie jest zwalidowany wg FIPS i nie jest twierdzeniem o zgodności z FIPS, OASIS ani ETSI. Normy, które uczyniłyby postkwantowy podpis PDF interoperacyjnym dla długoterminowej archiwizacji, jeszcze się nie pojawiły (zob. Granica norm).

Dostępność i licencjonowanie

Ta zdolność jest dostarczana w NextPDF Enterprise (nextpdf/enterprise) i aktywuje się przy kopercie licencyjnej poziomu Enterprise. Wdrożenie bez tego uprawnienia nie wczytuje klas tej zdolności. Porównaj edycje i zdobądź licencję.

Bazuje na sprzętowym podpisującym tokenem PKCS#11 z Enterprise — zob. Podpisywanie HSM. Klasyczna (RSA / ECDSA) ścieżka podpisywania PKCS#11 to wspierana, stabilna zdolność Enterprise; opisana tu ścieżka postkwantowa to eksperymentalny podgląd nałożony na nią. NextPDF Enterprise zawiera zestaw funkcji Pro.

Status zdolności podglądowej

Podgląd napędza prawdziwą operację podpisywania: po włączeniu signPqs() wysyła zadanie do kandydackiego postkwantowego mechanizmu PKCS#11 v3.1 na tokenie, klucz prywatny nigdy nie opuszcza granicy tokenu, a zwrócone bajty są sprawdzane co do długości względem narzuconej przez FIPS długości podpisu dla wybranego zestawu parametrów, zanim zostaną zaakceptowane.

Jednocześnie jest to podgląd, a nie ogólnie dostępna zdolność produktu:

• Identyfikatory postkwantowego mechanizmu i zestawu parametrów PKCS#11 są prowizoryczne — OASIS PKCS#11 v3.1 nie sfinalizował rejestru mechanizmów postkwantowych, więc użyte wartości są śledzone jako prowizoryczne, a operatorzy HSM muszą potwierdzić, że firmware PQ ich tokenu jest z nimi zgodne, przed włączeniem.
• W NextPDF nie istnieje żadna ścieżka weryfikacji postkwantowej, a żaden zestaw ETSI nie rejestruje postkwantowego podpisu dla długoterminowej archiwizacji AdES, więc wytworzony tu podpis nie jest jeszcze interoperacyjny, a większość czytników PDF odrzuci go w czasie walidacji.
• Towarzyszący deskryptor PqsCapabilityStatus zgłasza te fakty w formie czytelnej maszynowo. Każdy boolean pozytywnego twierdzenia — generallyAvailable, adesCompliant, verificationAvailable, conformanceClaimed — jest na sztywno ustawiony na false i pozostaje false nawet przy włączonej fladze podglądu, a żadna konfiguracja nie może go włączyć. (Niesie też flagę recognitionOnly, na sztywno true, która zapisuje, że rozpoznanie algorytmu nigdy nie jest werdyktem o zgodności; nie oznacza to, że powierzchnia nie potrafi podpisywać — podpisywanie odbywa się przez signPqs(), jak opisano powyżej.)

Dlaczego działa to w ten sposób

NextPDF potrafi już obliczyć rzeczywisty podpis ML-DSA lub SLH-DSA przez token. Mimo to każdy boolean zgodności pozostaje na sztywno ustawiony na false, za dwiema domyślnie wyłączonymi bramkami. Podpis jest wart tyle, ile możliwość jego późniejszej weryfikacji. W przypadku postkwantowym nie ma jeszcze ścieżki weryfikacji, zarejestrowanego zestawu ETSI AdES ani zwalidowanego wg FIPS cyklu round-trip HSM. Dostarczenie tego jako ogólnie dostępnego wydawałoby podpisy, których żaden czytnik nie potrafi zwalidować i żadne archiwum nie może im zaufać. Dlatego projekt oddziela wytwarzanie bajtów od twierdzenia, że ktokolwiek może na nich polegać, i żadna flaga podglądu nie może zatrzeć tej granicy.

Tło projektowe: Walidacja długoterminowa.

Zestawy parametrów algorytmów

signPqs() wybiera algorytm i zestaw parametrów przez enum Pkcs11PqsAlgorithm. Każdy przypadek mapuje zestaw parametrów NIST na prowizoryczny identyfikator mechanizmu / zestawu parametrów PKCS#11 oraz na narzuconą przez FIPS długość podpisu w bajtach używaną w sprawdzeniu długości w ramach obrony w głąb.

ML-DSA — FIPS 204 (oparte na kratach modułowych). Trzy zestawy parametrów, deklarowane na pokazanych kategoriach siły bezpieczeństwa NIST:

Zestaw parametrów	Kategoria NIST	Długość podpisu (bajty)
ML-DSA-44	2	2420
ML-DSA-65 (zalecany domyślny)	3	3309
ML-DSA-87	5	4627

SLH-DSA — FIPS 205 (bezstanowe, oparte na haszu). Dwanaście zestawów parametrów, utworzonych jako SHA2 / SHAKE x 128 / 192 / 256 x małe (s) / szybkie (f). Warianty s minimalizują rozmiar podpisu; warianty f minimalizują opóźnienie podpisywania:

Rodzina zestawu parametrów	Kategoria NIST	Długość podpisu (bajty)
SLH-DSA-{SHA2,SHAKE}-128s	1	7856
SLH-DSA-{SHA2,SHAKE}-128f	1	17088
SLH-DSA-{SHA2,SHAKE}-192s	3	16224
SLH-DSA-{SHA2,SHAKE}-192f	3	35664
SLH-DSA-{SHA2,SHAKE}-256s	5	29792
SLH-DSA-{SHA2,SHAKE}-256f	5	49856

Włączanie podglądu

Dwie niezależne bramki muszą być otwarte. Obie są domyślnie wyłączone.

1. Bramka procesu. Ustaw NEXTPDF_FEATURE_PREVIEW_PQS_HSM=1, zanim proces wystartuje (lub przez putenv() przed odczytem statusu). Wymagana jest ścisła równość z łańcuchem 1; każda inna wartość — w tym 0, true, yes lub pusta — jest traktowana jako wyłączona.
2. Opcja na poziomie podpisującego. Przekaż $enablePostQuantum: true do konstruktora Pkcs11Signer.

use NextPDF\Enterprise\Security\Signature\Hsm\Pkcs11Signer;
use NextPDF\Enterprise\Security\Signature\Hsm\Pkcs11PqsAlgorithm;
use NextPDF\Enterprise\Security\Signature\Hsm\PqsCapabilityStatus;
use NextPDF\Enterprise\Security\Signature\Hsm\PqsPreviewFeature;

// 1. Open the process-level preview gate (default-off).
putenv(PqsPreviewFeature::ENV_PREVIEW_PQS_HSM . '=1');

// 2. The capability status is honest even with the gate open:
//    generallyAvailable / adesCompliant / verificationAvailable stay false.
$status = PqsCapabilityStatus::current();

// 3. Construct the PKCS#11 signer with the per-signer opt-in.
$signer = new Pkcs11Signer(
    libraryPath: '/usr/lib/softhsm/libsofthsm2.so',
    slotId: 0,
    pin: '1234',
    certLabel: 'my-pqc-signing-cert',
    enablePostQuantum: true,
);

// 4. Sign with a chosen parameter set. The returned bytes are length-checked
//    against Pkcs11PqsAlgorithm::signatureLength() before being accepted.
$signature = $signer->signPqs(
    data: $tbsBytes,
    algorithm: Pkcs11PqsAlgorithm::MlDsa65,
);

isPostQuantumEnabled() zgłasza, czy opcja na poziomie podpisującego została ustawiona, a PqsCapabilityStatus::current() zgłasza stan na poziomie procesu oraz uczciwe booleany twierdzeń.

Granica fail-closed

Powierzchnia jest fail-closed i zgłasza awarie przez nazwane, typowane wyjątki, a nie przez ciche wycofanie:

• Brak opcji. Jeśli signPqs() zostanie wywołane, gdy $enablePostQuantum jest false, zgłasza HsmOperationException. Podpisywanie nie następuje.
• Zbyt długi kontekst. Łańcuch oktetów kontekstu podpisu dłuższy niż 255 bajtów zgłasza InvalidArgumentException (zgodnie z ograniczeniem kontekstu FIPS 204 / FIPS 205) przed jakimkolwiek wywołaniem tokenu.
• Brak klucza. Jeśli żaden klucz prywatny nie pasuje do skonfigurowanej etykiety na tokenie, signPqs() zgłasza HsmOperationException.
• Niezgodność długości. Jeśli token zwróci podpis, którego długość w bajtach nie równa się narzuconej przez FIPS długości dla danego zestawu parametrów, signPqs() zgłasza HsmOperationException — zniekształcony (skrócony lub nadmiarowy) podpis jest odrzucany, zanim dotrze do kodowania CMS SignedData.
• Błąd tokenu. Każdy bazowy błąd PKCS#11 jest opakowywany w HsmOperationException.

Flaga env na poziomie procesu nic nie zmienia w tej granicy: nawet gdy flaga jest włączona, booleany zdolności pozostają fałszem, a ścieżka podpisywania pozostaje sprawdzana co do długości i fail-closed.

Uczciwa granica

Następujące twierdzenia nie są wysuwane dla tej powierzchni i nie mogą pojawiać się w żadnej dokumentacji, interfejsie ani materiałach marketingowych z niej wywodzonych:

• „GA” / „generally available”.
• „AdES” / „PAdES-compliant” — żaden zestaw ETSI nie rejestruje postkwantowego podpisu dla długoterminowej archiwizacji.
• „FIPS-validated” — nie ustanowiono żadnego zwalidowanego wg FIPS-140-3 postkwantowego cyklu round-trip HSM dla tej ścieżki.
• „certified” ani „conformant” względem FIPS, OASIS PKCS#11 v3.1 czy ETSI.
• „production-ready”.

Czym powierzchnia uczciwie jest: opcjonalnym, domyślnie wyłączonym, fail-closed podglądem postkwantowego podpisywania delegowanego do HSM, który napędza ML-DSA / SLH-DSA przez token PKCS#11 i sprawdza wynik co do długości. Czym nie jest: ogólnie dostępną, zgodną z AdES, zwalidowaną wg FIPS ani certyfikowaną zdolnością podpisywania.

Granica norm

Zaangażowane normy są utrzymywane przez zewnętrzne ciała, a podgląd nie zajmuje stanowiska co do zgodności z którąkolwiek z nich:

• Zestawy parametrów algorytmów i długości podpisów podążają za FIPS 204 (ML-DSA) i FIPS 205 (SLH-DSA).
• Identyfikatory mechanizmów tokenu podążają za OASIS PKCS#11; rejestr mechanizmów postkwantowych w PKCS#11 v3.1 nie jest jeszcze sfinalizowany, więc NextPDF używa identyfikatorów prowizorycznych.
• Profile długoterminowej archiwizacji podpisów PDF to ETSI EN 319 142-2 (profile rozszerzone PAdES, zbudowane na CMS SignerInfo) oraz katalog zestawów kryptograficznych ETSI TS 119 312, który obecnie profiluje wyłącznie RSA i ECDSA — żaden zestaw postkwantowy nie jest zarejestrowany dla CAdES/PAdES. Postkwantowy podpis PDF wytworzony dzisiaj nie jest zatem jeszcze zgodny z AdES dla archiwizacji.

Na tej stronie nie odtwarza się żadnego tekstu normatywnego.

Uwagi dotyczące bezpieczeństwa

Podgląd nie jest mechanizmem kontroli bezpieczeństwa. Obecność postkwantowego podpisu wytworzonego tą ścieżką nie ustanawia ważności AdES, nie implikuje zaufanego klucza i nie jest weryfikowalna przez NextPDF (nie ma ścieżki weryfikacji postkwantowej). Nie polegaj na tym podglądzie dla zapewnienia podpisu i nie wdrażaj go tam, gdzie wymagany jest podpis zgodny z AdES lub zwalidowany wg FIPS. Trzymaj obie bramki wyłączone w produkcji, dopóki normy się nie pojawią.

Powierzchnia API

Symbol	Rola
Pkcs11Signer::signPqs()	Opcjonalne, fail-closed postkwantowe podpisywanie delegowane do HSM przez PKCS#11. Zgłasza HsmOperationException, gdy wyłączone, gdy brak klucza lub przy niezgodności długości podpisu.
Pkcs11Signer::isPostQuantumEnabled()	Czy ustawiono opcję $enablePostQuantum na poziomie podpisującego.
Pkcs11PqsAlgorithm	Enum zestawów parametrów ML-DSA (FIPS 204) i SLH-DSA (FIPS 205); mapuje każdy na prowizoryczny identyfikator mechanizmu i narzuconą przez FIPS długość podpisu.
PqsPreviewFeature	Bramka env na poziomie procesu, domyślnie wyłączona (NEXTPDF_FEATURE_PREVIEW_PQS_HSM).
PqsCapabilityStatus	Uczciwy, czytelny maszynowo status: każdy boolean pozytywnego twierdzenia (generally-available, AdES, weryfikacja, zgodność) jest na sztywno false niezależnie od flagi podglądu.
HsmOperationException	Typowany wyjątek zgłaszany na ścieżkach fail-closed.

Granica publikacji

Ta strona dokumentuje wyłącznie zewnętrznie obserwowalne zachowanie 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.

Zobacz także

• Podpisywanie HSM (PKCS#11)
• Bezpieczeństwo Enterprise
• Podpisywanie w Core
• Strona główna zgodności
• Status zdolności podglądowej C2PA