Podpisywanie z użyciem HSM

Spec: ISO 32000-2, §12.8 Spec: FIPS 140-3 Evidence: Standard-backed

W skrócie

Sprzętowy moduł bezpieczeństwa (HSM) przenosi klucz podpisujący poza proces, do urządzenia, które podpisuje na żądanie, lecz nigdy nie zwraca klucza. Ta strona wyjaśnia szew PKCS#11, przez który podpisuje NextPDF, dokładny przebieg granicy klucza oraz to, które części wyniku należą do odpowiedzialności silnika, a które do urządzenia albo operatora.

Dlaczego to ma znaczenie

Klucz podpisujący w pamięci procesu jest narażony na wszystko, co może odczytać proces: zrzut sterty, debuger, błąd w logowaniu lub zależność z luką w zabezpieczeniach. Gdy klucz prywatny zostanie skopiowany, każdy podpis kiedykolwiek złożony tym kluczem staje się wątpliwy i nie można go ponownie utajnić. Sens modułu HSM polega na tym, że nie ma kopii, którą można by przejąć.

Błędne wyznaczenie granicy potrafi być po cichu kosztowne. Proces, który wygląda na oparty na sprzęcie, lecz wczytuje klucz do pamięci, aby podpisać, ponosi koszty operacyjne modułu HSM, a zachowuje profil ryzyka klucza programowego. Różnica nie jest widoczna w gotowym PDF, więc trzeba ją zaprojektować i zweryfikować, a nie zakładać.

Wersja skrócona

Norma PKCS#11 definiuje obiekt klucza oznaczony jako wrażliwy i niemożliwy do wyodrębnienia. Jego wartość prywatna nie może zostać ujawniona w postaci jawnej poza tokenem. Spec: PKCS#11, v3.1 §10.9
NextPDF buduje strukturę podpisu PDF oraz kontener CMS. Przekazuje bajty do podpisania przez szew PKCS#11 i odbiera podpis. Klucz nigdy nie przekracza tego szwu.
Szew jest stabilnym kontraktem. Ten sam kontrakt spełniają token w postaci karty inteligentnej, moduł HSM na USB, sieciowy moduł HSM oraz chmurowy system KMS. Kod silnika między nimi się nie zmienia.
NextPDF to oprogramowanie silnika podpisującego. Gwarancje sprzętowe urządzenia, jego status walidacji, polityka kodu PIN oraz wdrożenie nie są czymś, co silnik certyfikuje. Korzysta z urządzenia; nie ręczy za nie.

Jak podchodzi do tego NextPDF

Szew w szczegółach

NextPDF oddziela składanie podpisu od obliczania wartości podpisu. Składanie jest zadaniem silnika: umieszczenie pola podpisu, zarezerwowanie miejsca w pliku, obliczenie zakresu bajtów oraz zbudowanie obiektu CMS SignedData wraz z jego atrybutami podpisanymi. Spec: ISO 32000-2, §12.8

Obliczanie wartości podpisu jest delegowane. Silnik definiuje niewielki kontrakt dostawcy podpisu: otrzymuje nieprzezroczystą sekwencję bajtów (w praktyce atrybuty podpisane zakodowane w DER) i zwraca surowe oktety podpisu. Tym kontraktem jest szew. Wiedza o PDF i CMS pozostaje po jednej stronie; klucz pozostaje po drugiej. Dostawca może przechowywać ten klucz w procesie w przypadku lokalnego klucza programowego, w chmurowym systemie KMS albo na tokenie sprzętowym przez PKCS#11. Kod silnika powyżej szwu jest w każdym przypadku identyczny. Różni się jedynie dostawca po drugiej stronie.

Gdzie faktycznie przebiega granica

PKCS#11 — interfejs tokena kryptograficznego OASIS, historycznie „Cryptoki” — to standardowy interfejs w języku C dla tokenów sprzętowych. Ścieżka sprzętowa NextPDF porozumiewa się przez PKCS#11 (bezpośrednio lub przez mostek wiersza poleceń OpenSSL przy wdrożeniach z silnikiem lub dostawcą, w których powiązanie wewnątrzprocesowe nie może wczytać tokena).

Obiekt klucza na tokenie jest tworzony z dwoma atrybutami, które definiują granicę. Gdy klucz jest oznaczony jako wrażliwy lub jako niemożliwy do wyodrębnienia, pewne atrybuty prywatne nie mogą zostać ujawnione w postaci jawnej poza tokenem. Spec: PKCS#11, v3.1 §10.9 Sama operacja podpisywania sprowadza się do wywołania tokena — C_SignInit, a następnie C_Sign — wykonywanego przez urządzenie. Spec: PKCS#11, v3.1 §5.10 Postacią jawną, którą NextPDF obsługuje przy operacji podpisywania, są bajty do podpisania. Zwracane są podpis i certyfikat. Klucz prywatny nie znajduje się na żadnej z tych ścieżek. To jest granica, a egzekwuje ją token, nie biblioteka.

Step 1 of 4: ISO 32000-2 §12.8 — signature dictionary, ByteRange, Contents
Step 2 of 4: RFC 5652 CMS SignedData — the signature container
Step 4 of 4: FIPS 140-3 / ISO/IEC 19790 cryptographic module assurance (device-level, deployment-dependent)

Na czym opiera się sprzętowy podpis PDF, w kolejności: nośnik PDF (ISO 32000-2 §12.8), kontener CMS, który ten nośnik przechowuje, interfejs tokena, przez który podpisuje NextPDF (PKCS#11), oraz normy gwarancji modułu, które opisują — lecz same w sobie nie gwarantują — urządzenia za nim stojącego.

Jeden kod PIN, jedno ponowne uwierzytelnienie

PKCS#11 pozwala skonfigurować klucz tak, aby wymagał ponownego uwierzytelnienia przy każdym użyciu: gdy atrybut CKA_ALWAYS_AUTHENTICATE jest ustawiony, użytkownik musi podać kod PIN ponownie przy każdej operacji kryptograficznej, a nie raz na sesję. Spec: PKCS#11, v3.1 §10.9 Ścieżka PKCS#11 w NextPDF jest napisana właśnie z myślą o tym. Kod PIN jest parametrem wrażliwym. Nie jest zapisywany w dzienniku ani serializowany. Gdy sesja zgłasza istniejące logowanie, NextPDF przywraca ją do czystego stanu, tak aby kolejny podpis wymagał świeżego sprawdzenia kodu PIN. Ma to znaczenie dla tokenów typu PIV, których polityka wymaga kodu PIN przy każdym podpisie. Jest to zachowanie silnika, które respektuje politykę urządzenia; nie osłabia jej.

Co mówią dowody

Evidence: Standard-backed Właściwość niemożliwego do wyodrębnienia klucza nie jest twierdzeniem NextPDF. To model PKCS#11: obiekt klucza, którego CKA_SENSITIVE ma wartość prawda lub CKA_EXTRACTABLE ma wartość fałsz, nie ujawnia swojej wartości prywatnej w postaci jawnej poza tokenem. Spec: PKCS#11, v3.1 §10.9 Wkładem NextPDF jest to, że nigdy nie potrzebuje tej wartości: podpisuje przez operację C_Sign tokena, zamiast prosić o materiał klucza.

Evidence: Standard-backed Część dotycząca PDF jest zakotwiczona w Spec: ISO 32000-2, §12.8 . Skrót zakresu bajtów jest obliczany dla pliku z pominięciem wartości podpisu. Wartość podpisu umieszczona we wpisie Contents to zakodowany w DER obiekt CMS SignedData dla podpisów z kluczem publicznym. Moduł HSM wytwarza wyłącznie najgłębiej zagnieżdżone oktety podpisu. NextPDF buduje wszystko wokół nich i zapisuje je w strukturze, którą definiuje norma.

Evidence: Standard-backed Zakres gwarancji urządzenia opisują Spec: FIPS 140-3 oraz powiązana norma bazowa ISO/IEC 19790, które definiują cztery rosnące jakościowe poziomy bezpieczeństwa w jedenastu obszarach wymagań — od specyfikacji algorytmu po fizyczne ślady manipulacji. Te normy opisują, co moduł musi spełniać, aby zadeklarować dany poziom. Są właściwością urządzenia i jego walidacji, a nie NextPDF, oraz — według słów samej normy ISO/IEC 19790 — zgodność sama w sobie nie jest wystarczająca, aby zapewnić, że moduł jest bezpieczny w danym wdrożeniu.

Przykład praktyczny

Poniższy przykład ma charakter poglądowy. Pokazuje szew, a nie wdrożenie gotowe do skopiowania. Chodzi o to, że silnik otrzymuje obiekt podpisujący i nigdy nie widzi klucza: metoda sign() obiektu podpisującego jest wywołaniem do urządzenia.

<?php

declare(strict_types=1);

use NextPDF\Contracts\HsmSignerInterface;

/**
 * Sign a PDF where the private key lives on a PKCS#11 token.
 *
 * `$hsm` is a hardware-backed signer. Its sign() delegates to the token;
 * the key never enters this process. Everything that makes the bytes a
 * valid PDF signature — field, byte range, CMS SignedData — is built by
 * the engine around the value the device returns.
 *
 * Token wiring (library path, slot, PIN, key label) is deployment
 * configuration and is intentionally out of scope here: those values are
 * operator-owned secrets, not library inputs to hardcode.
 */
function signWithToken(
    string $pdfPath,
    HsmSignerInterface $hsm,
): string {
    // The engine asks the signer only for: the certificate (to embed in
    // the CMS) and a signature over the bytes it computes. It never asks
    // for, and the contract never exposes, the private key.
    $certificateDer = $hsm->getCertificateDer();
    $chainDer       = $hsm->getCertificateChainDer();

    // Pseudocode for the engine's own assembly step: build the signature
    // dictionary + CMS SignedData, then hand the signed-attributes bytes
    // to $hsm->sign(...) and place the returned octets in /Contents.
    return nextpdf_sign_pdf(
        pdfPath: $pdfPath,
        signer: $hsm,
        certificateDer: $certificateDer,
        chainDer: $chainDer,
    );
}

Dwie istotne uwagi do tego przykładu. Wewnątrzprocesowe powiązanie PKCS#11 to osobne rozszerzenie PHP, którego standardowe kompilacje PHP nie zawierają. Wdrożenie sprzętowe instaluje je i weryfikuje (lub korzysta z mostka wiersza poleceń OpenSSL) jako element platformy, a nie jako dodatek dopinany później. Ponadto algorytm żądany od urządzenia musi być jednym z tych, które klucz faktycznie potrafi wykonać. Silnik odmawia wcześnie, gdy skonfigurowany algorytm nie ma odwzorowania dla wybranego dostawcy, zamiast zawodzić głęboko w wywołaniu tokena.

Częste nieporozumienie

„Użycie modułu HSM oznacza, że podpisywanie ma walidację FIPS.”

Nie. Pułapką jest mylenie tych dwóch rzeczy. Moduł HSM to miejsce, w którym żyje klucz i wykonywana jest operacja. Walidacja FIPS 140-3 / ISO/IEC 19790 jest właściwością, którą może mieć urządzenie (lub konkretna konfiguracja modułu), ustanowioną przez program walidacji — a nie czymś, co nadaje biblioteka wywołująca, ani czymś, co NextPDF deklaruje w imieniu urządzenia. NextPDF jest zgodny z podpisywaniem przez urządzenie PKCS#11, a jego ścieżka podpisywania została przetestowana z tokenami reprezentatywnymi dla kategorii. To, czy dane wdrożenie jest poddane walidacji na poziomie modułu FIPS, zależy w całości od sprzętu, jego certyfikatu oraz sposobu jego konfiguracji i obsługi. Używaj precyzyjnego terminu dla tego, co faktycznie posiadasz.

Ograniczenia i granice

Ta strona opisuje szew oraz normy, na których się opiera. Nie stanowi gwarancji wdrożenia; tę granicę warto nazwać wprost:

Odpowiedzialność silnika. Zbudowanie pola podpisu, zarezerwowanie miejsca, obliczenie zakresu bajtów, złożenie obiektu CMS SignedData, wywołanie dostawcy podpisu oraz zapisanie strukturalnie poprawnego podpisu zgodnie z Spec: ISO 32000-2, §12.8 . Ścieżka sprzętowa NextPDF jest do tego celu zgodna z interfejsem podpisywania PKCS#11.
Odpowiedzialność urządzenia i operatora. Odporność sprzętu na manipulacje, jego status walidacji FIPS 140-3 / ISO/IEC 19790, generowanie i przechowywanie klucza, polityka kodu PIN, konfiguracja slotu, oprogramowanie układowe oraz bezpieczeństwo fizyczne. Żadna z tych rzeczy nie jest czymś, co silnik certyfikuje.
„Przetestowane z” nie znaczy „certyfikowane”. To, że NextPDF ma zweryfikowaną ścieżkę dla reprezentatywnych kategorii tokenów — postaci karty inteligentnej, USB, sieciowej oraz chmurowego KMS osiąganych przez ten sam kontrakt PKCS#11 — jest oświadczeniem o zgodności. Nie jest certyfikacją, liczbą zwalidowanych modułów ani twierdzeniem o Twoim konkretnym urządzeniu. Poniższe kategorie sprzętu to postaci integracji przez jeden standardowy interfejs. Traktuj je jako „miejsca, w których szew był sprawdzany”, nigdy jako gwarancję dla modelu, którego samodzielnie nie przetestowałeś.
Podpisywanie postkwantowe jest eksperymentalne. Tam, gdzie silnik udostępnia podpisywanie postkwantowe przez token, jest ono opcjonalne, bramkowane i walidowane wobec atrap, a nie wobec postkwantowego oprogramowania układowego HSM. Katalogi pakietów kryptograficznych PAdES oraz AdES nie rozpoznają jeszcze tych pakietów do długoterminowej archiwizacji. Nie traktuj takiego podpisywania jako gotowego do produkcji.

HSM-backed signing via PKCS#11 — edition availability
Edition	Availability
Core	Niedostępne w tej edycji. Edycja Core udostępnia silnik podpisujący oraz szew dostawcy podpisu, z lokalnym dostawcą klucza programowego.
Pro	Zarządzanie kluczami w chmurze — podpisywanie kluczami zarządzanymi przez system KMS — to funkcja edycji Pro, opisana wyłącznie na poziomie zachowania.
Enterprise	Dostępne. Podpisywanie tokenem sprzętowym przez interfejs PKCS#11 (oraz mostek wiersza poleceń OpenSSL dla wdrożeń z engine/provider) to funkcja edycji Enterprise. Dostępność jest oświadczeniem o funkcji, a nie certyfikacją jakiegokolwiek urządzenia lub wdrożenia.

Postaci integracji przez jeden interfejs

To są postaci, wobec których sprawdzano szew PKCS#11. Kolumna mówi „jak wygląda integracja”, a nie „zwalidowana, certyfikowana lub policzona lista urządzeń”.

Postać integracji	Jak jest osiągana	Granica klucza	Gwarancja jest właściwością
Token karty inteligentnej / PIV	moduł PKCS#11; zwykle kod PIN przy każdym użyciu	Na karcie; niemożliwy do wyodrębnienia	Karty i jej operatora
Moduł HSM na USB	moduł PKCS#11	Na urządzeniu; niemożliwy do wyodrębnienia	Urządzenia i jego operatora
Sieciowy moduł HSM / urządzenie sprzętowe	moduł PKCS#11 do urządzenia sieciowego	Na urządzeniu sprzętowym; niemożliwy do wyodrębnienia	Urządzenia sprzętowego, jego konfiguracji, operatora
Chmurowy system KMS	Dostawca kluczy zarządzanych (Pro)	W usłudze chmurowej; nigdy nie zwracany	Dostawcy chmurowego i jego poświadczeń
Mostek dostawcy OpenSSL	PKCS#11 przez mostek OpenSSL	Na tokenie; niemożliwy do wyodrębnienia	Tokena i jego operatora

Mini-FAQ

Czy klucz kiedykolwiek trafia do procesu PHP? Nie. W przypadku niemożliwego do wyodrębnienia klucza PKCS#11 wartość prywatna nie może zostać ujawniona w postaci jawnej poza tokenem. NextPDF podpisuje przez operację tokena i zawsze widzi tylko bajty do podpisania oraz zwrócony podpis.

Czy podpis oparty na module HSM różni się wewnątrz PDF? Nie. Struktura podpisu to ten sam obiekt CMS SignedData w tym samym wpisie Contents dla tego samego zakresu bajtów. Moduł HSM zmienia miejsce, w którym następuje podpisywanie, a nie postać na dysku.

Czy mogę twierdzić, że spełniam wymogi FIPS, ponieważ użyłem modułu HSM przez NextPDF? Tylko z rozwagą. NextPDF nie twierdzi niczego o statusie FIPS urządzenia. Każde takie twierdzenie musi wynikać z własnej walidacji urządzenia i sposobu jego wdrożenia, a nie z faktu, że wywołał je NextPDF.

Co, jeśli wewnątrzprocesowe powiązanie PKCS#11 jest niedostępne? Silnik zgłasza, że podpisywanie sprzętowe jest niedostępne, zamiast po cichu wracać do klucza programowego. Dla wdrożeń, w których powiązanie wewnątrzprocesowe nie może wczytać tokena, dostępna jest ścieżka mostka wiersza poleceń OpenSSL.

Powiązane dokumenty

Podpisy kwalifikowane, wyjaśnione — do czego klucz sprzętowy jest konieczny, lecz niewystarczający, oraz role, których NextPDF nie pełni.
Jak podpisy są osadzone w PDF — mechanizm zakresu bajtów i słownika podpisu, w którym zapisywany jest wynik z modułu HSM.
Eksploatacja NextPDF w środowisku produkcyjnym — powierzchnia operacyjna, którą obejmuje wdrożenie podpisywania sprzętowego.

Słowniczek

HSM (sprzętowy moduł bezpieczeństwa) — utwardzone urządzenie, które przechowuje klucze i wykonuje operacje kryptograficzne, tak aby materiał klucza nigdy go nie opuszczał.
PKCS#11 — norma interfejsu tokena kryptograficznego OASIS (historycznie „Cryptoki”); interfejs w języku C, którego NextPDF używa do porozumiewania się z tokenami sprzętowymi.
Klucz niemożliwy do wyodrębnienia — obiekt klucza PKCS#11, którego wartość prywatna nie może zostać ujawniona w postaci jawnej poza tokenem (CKA_SENSITIVE prawda lub CKA_EXTRACTABLE fałsz).
Szew — granica dostawcy podpisu w NextPDF: nieprzezroczyste bajty na wejściu, oktety podpisu na wyjściu. Wiedza o PDF i CMS znajduje się nad nim; klucz znajduje się za nim.
CMS SignedData — struktura składni komunikatu kryptograficznego (RFC 5652), która przenosi podpis i certyfikaty wewnątrz PDF.
FIPS 140-3 / ISO/IEC 19790 — normy bezpieczeństwa modułów kryptograficznych definiujące cztery jakościowe poziomy; właściwość urządzenia i jego walidacji, a nie biblioteki wywołującej.