Podpisywanie sprzętowym modułem bezpieczeństwa (PKCS#11)

W skrócie

NextPDF Enterprise podpisuje plik PDF kluczem przechowywanym wewnątrz sprzętowego modułu bezpieczeństwa (HSM). Kierujesz podpisującego na token PKCS#11 — kartę inteligentną, token Universal Serial Bus (USB) lub sieciowy HSM — a operacja podpisywania działa na urządzeniu. Klucz prywatny nigdy nie opuszcza granicy tokenu. Ta strona jest na poziomie zachowania: stwierdza, co robi podpisujący, co dostarczasz Ty oraz gdzie piecza nad kluczem przestaje być odpowiedzialnością NextPDF.

Podpisujący HSM rozwiązuje się przez kontrakt podpisującego w Core, więc Twoja aplikacja zależy od kontraktu, a nie od konkretnego typu Enterprise. Rozszerza tę samą ścieżkę podpisywania Cryptographic Message Syntax (CMS), której używa Core, z tą różnicą, że operacja kryptograficzna jest delegowana do tokenu.

Wymagania wstępne podano w nagłówku (front matter) i powtórzono w sekcji Wymagania wstępne, aby nic Cię nie zaskoczyło w trakcie zadania.

Dostępność i licencjonowanie

Ta możliwość jest dostarczana w NextPDF Enterprise (nextpdf/enterprise) i aktywuje się z kopertą licencji poziomu Enterprise. Wdrożenie bez tego uprawnienia nie ładuje klas tej możliwości. Porównaj edycje i uzyskaj licencję.

NextPDF Core dostarcza programowego podpisującego CMS, który przechowuje klucz w obrębie procesu lub przyjmuje go przez kontrakt strategii podpisywania Core; NextPDF Pro dodaje zdalne oraz chmurowe strategie podpisywania key-management-service (KMS). Sprzętowa piecza nad kluczem przez PKCS#11 to możliwość Enterprise, nie dostarczana przez Core ani Pro.

Co robi ta możliwość

Token PKCS#11 udostępnia obiekty kryptograficzne — certyfikaty i klucze prywatne — za biblioteką współdzieloną dostawcy. Podpisujący Enterprise adaptuje tę bibliotekę:

1. Otwiera bibliotekę współdzieloną tokenu raz na proces i buforuje uchwyt modułu, ponieważ PKCS#11 wymaga, aby moduł był inicjalizowany dokładnie raz na proces.
2. Otwiera sesję na skonfigurowanym slocie i loguje się przy użyciu dostarczonego PIN-u. Logowanie uwierzytelnia użytkownika przed jakąkolwiek operacją na kluczu prywatnym, zgodnie z PKCS#11 v3.1 §5.6.8.
3. Lokalizuje certyfikat podpisujący na tokenie po etykiecie, odczytuje certyfikat w postaci Distinguished Encoding Rules (DER) i wykrywa algorytm klucza publicznego.
4. W czasie podpisywania lokalizuje klucz prywatny po etykiecie — która na niektórych tokenach może różnić się od etykiety certyfikatu — i prosi token o obliczenie podpisu. Dane do podpisania są przekazywane; klucz pozostaje na urządzeniu.

Podpisujący obsługuje RSA z dopełnieniem PKCS#1 v1.5 (SHA-256, SHA-384, SHA-512), RSA z dopełnieniem Probabilistic Signature Scheme (PSS), gdzie długość soli równa się długości skrótu, oraz Elliptic Curve Digital Signature Algorithm (ECDSA) z SHA-256, SHA-384 i SHA-512. Krzywa ECDSA i skrót są parowane konwencjonalnie — P-256 z SHA-256, P-384 z SHA-384, P-521 z SHA-512 — zgodnie z zalecanym parowaniem w RFC 5480. Token zwraca podpis ECDSA jako surową konkatenację dwóch liczb całkowitych; podpisujący przekształca ją do postaci zakodowanej w DER, której oczekują PDF i OpenSSL.

Na potrzeby generowania podpisu klucz RSA o długości co najmniej 2048 bitów oraz rząd krzywej ECDSA co najmniej 224 bity to akceptowalne minima zgodnie z NIST SP 800-131A Rev.2 §3. Udostępnij klucz tokenu o tych rozmiarach lub większych.

Istnieje alternatywna ścieżka silnika OpenSSL dla tokenów opartych na silniku. W OpenSSL 3.x rozszerzenie OpenSSL dla PHP nie udostępnia interfejsu programowania aplikacji (API) silnika, więc klasa silnika jest przestarzała; wspierana trasa oparta na silniku uruchamia binarny program wiersza poleceń OpenSSL. Preferuj bezpośrednią ścieżkę PKCS#11 tam, gdzie Twój token ma bibliotekę PKCS#11.

Dlaczego działa to w ten sposób

Decyzją nośną jest to, że klucz prywatny nigdy nie opuszcza tokenu. Dlatego podpisujący deleguje operację kryptograficzną do urządzenia i przenosi przez szew PKCS#11 jedynie dane do podpisania. Nigdy nie odczytuje ani nie rekonstruuje materiału klucza w pamięci PHP. Rozwiązuje się przez kontrakt HsmSignerInterface w Core, a nie przez konkretny typ Enterprise, więc kod podpisywania jest identyczny niezależnie od tego, czy klucz znajduje się w oprogramowaniu, chmurowym KMS czy tokenie sprzętowym. Buforuje uchwyt modułu raz na proces, ponieważ PKCS#11 inicjalizuje każdy moduł dokładnie raz na proces, a następnie przekształca surowe wyjście ECDSA tokenu do DER, aby walidatory widziały kodowanie, którego oczekują. Kształt wyznacza piecza, a nie wygoda: granica zaufania pozostaje na krawędzi urządzenia.

Tło projektowe: Podpisywanie oparte na HSM.

Wymagania wstępne

Zanim podpiszesz za pomocą HSM, potwierdź każdy element:

1. Zainstaluj NextPDF Core oraz pakiet Enterprise: composer require nextpdf/core:^3 oraz composer require nextpdf/enterprise.
2. Utrzymuj aktywną licencję NextPDF Enterprise; rozwiązuj pakiet względem swoich poświadczeń licencyjnych na Private Packagist.
3. Zainstaluj na hoście bibliotekę współdzieloną PKCS#11 dostawcy tokenu (na przykład .so w systemie Linux lub .dll w systemie Windows) i zanotuj jej ścieżkę bezwzględną, numer slotu oraz etykiety obiektów.
4. Załaduj rozszerzenie PHP ext-pkcs11. Nie jest dołączone do standardowego PHP i musi zostać zainstalowane osobno. Konstruktor podpisującego zgłasza typizowany błąd operacji, gdy rozszerzenie jest nieobecne.

Konfiguracja

Dostarcz podpisującemu te dane wejściowe:

• Ścieżka biblioteki — ścieżka bezwzględna do biblioteki współdzielonej PKCS#11 dostawcy.
• Identyfikator slotu — numer slotu tokenu, zazwyczaj 0.
• PIN — PIN tokenu. Traktuj go jak sekret: dostarczaj go z menedżera sekretów, nigdy ze źródła ani z logów. Podpisujący oznacza parametr PIN jako wrażliwy, dzięki czemu jest wyłączony ze śladów stosu i serializacji.
• Etykieta certyfikatu — etykieta obiektu certyfikatu na tokenie.
• Etykieta klucza — etykieta obiektu klucza prywatnego, gdy różni się od etykiety certyfikatu.
• Łańcuch — opcjonalne certyfikaty pośrednie w postaci DER, gdy token ich nie przechowuje.

Sprawdź dostępność tokenu przed skonstruowaniem podpisującego. Konstrukcja odczytuje certyfikat z tokenu, więc źle skonfigurowany slot lub etykieta zawodzi szybko z typizowanym błędem, a nie dopiero w czasie podpisywania.

Krok po kroku

1. Potwierdź, że środowisko uruchomieniowe wspiera PKCS#11, sprawdzając dostępność rozszerzenia. Nie konstruuj podpisującego, gdy rozszerzenie jest nieobecne.
2. Odczytaj PIN z menedżera sekretów do zmiennej, która nigdy nie jest logowana.
3. Skonstruuj podpisującego HSM ze ścieżką biblioteki, slotem, PIN-em oraz etykietami. Konstrukcja loguje się i odczytuje certyfikat.
4. Przekaż podpisującego do orkiestratora podpisywania Core przez HsmSignerInterface. Orkiestrator oblicza zakres bajtów, buduje podpisane atrybuty CMS, przekazuje dane do tokenu i składa podpisany plik PDF.
5. Przechwyć najbardziej szczegółowe niepowodzenie, zaloguj komunikat strukturalny bez PIN-u i ponownie zgłoś wyjątek.

examples/contracts/hsm-signer-availability.php

<?php

declare(strict_types=1);

require_once __DIR__ . '/../../vendor/autoload.php';

use NextPDF\Contracts\HsmSignerInterface;

/**
 * Build a hardware-token signer only when the runtime supports it.
 *
 * The concrete PKCS#11 signer is resolved through the Core contract so the
 * caller depends on the interface, not the Enterprise implementation type.
 * The PIN arrives from a secret resolver; it is never written to source.
 *
 * @param callable(): bool                $pkcs11Available Reports ext-pkcs11 availability.
 * @param callable(): HsmSignerInterface  $signerFactory   Builds the configured token signer.
 *
 * @throws \RuntimeException When the PKCS#11 extension is not loaded.
 *
 * @return HsmSignerInterface The token signer, ready for the Core orchestrator.
 */
function resolveHsmSigner(callable $pkcs11Available, callable $signerFactory): HsmSignerInterface
{
    if ($pkcs11Available() !== true) {
        throw new \RuntimeException(
            'PKCS#11 signing requires the ext-pkcs11 extension; install it before signing.',
        );
    }

    return $signerFactory();
}

Połączenie produkcyjne — dokładna lista argumentów konstruktora oraz typizowane typy wyjątków — jest udokumentowane w głębokiej referencji HSM.

examples/contracts/hsm-sign-guarded.php

<?php

declare(strict_types=1);

require_once __DIR__ . '/../../vendor/autoload.php';

use NextPDF\Contracts\HsmSignerInterface;
use NextPDF\Exception\NextPdfException;
use Psr\Log\LoggerInterface;

final readonly class HsmSigningService
{
    public function __construct(
        private HsmSignerInterface $signer,
        private LoggerInterface $logger,
    ) {}

    /**
     * Sign data on the token through the Core HSM contract.
     *
     * The byte range is computed by the engine, never accepted from the
     * caller. The token performs the signing operation; the private key
     * does not leave the device.
     *
     * @param string $data      The bytes the orchestrator hands to the token.
     * @param string $algorithm The OpenSSL-style signing algorithm identifier.
     *
     * @throws NextPdfException When the token operation fails.
     *
     * @return string The raw signature bytes returned by the token.
     */
    public function sign(string $data, string $algorithm): string
    {
        try {
            return $this->signer->sign($data, $algorithm);
        } catch (NextPdfException $e) {
            // Structural message only — never the PIN or key material.
            $this->logger->error('HSM signing failed', ['reason' => $e->getMessage()]);

            throw $e;
        }
    }
}

Weryfikacja

Potwierdź wynik tak, jak zrobiłby to weryfikator:

1. Odczytaj zwrotnie certyfikat podpisującego i łańcuch w postaci DER od podpisującego i potwierdź, że pasują do certyfikatu udostępnionego na tokenie.
2. Otwórz podpisany plik PDF w walidatorze skonfigurowanym z Twoimi kotwicami zaufania i potwierdź, że podpis jest raportowany jako kryptograficznie nienaruszony. Wytworzony podpis nie jest podpisem zweryfikowanym; decyzja o zaufaniu należy do weryfikatora i jego kotwic zaufania, a nie do producenta.
3. W przypadku podpisu ECDSA potwierdź, że osadzony podpis jest zakodowany w DER — podpisujący przekształca surowe wyjście tokenu za Ciebie, więc walidator, który odrzuca surową postać konkatenowaną, powinien mimo to zaakceptować osadzony podpis.
4. Potwierdź, że w logach Twojej aplikacji nie pojawia się żaden PIN, etykieta tokenu ani materiał klucza.

Bezpieczeństwo i zgodność

• Klucz pozostaje na tokenie. Dane do podpisania są przekazywane tokenowi; operacja podpisywania działa wewnątrz granicy tokenu. Klucz prywatny nigdy nie jest ładowany do pamięci PHP.
• PIN to sekret. Jest wrażliwym parametrem konstruktora, wyłączonym z logów i serializacji. Dostarczaj go z menedżera sekretów. Wielokrotnie nieudane ponowne uwierzytelnienie może zablokować PIN na tokenie; tę politykę egzekwuje token, a nie NextPDF.
• Fail-closed. Błąd tokenu lub HSM zgłasza typizowany wyjątek. Podpisujący nie wytwarza wyniku niepodpisanego ani częściowo podpisanego i nigdy nie podstawia słabszego algorytmu.
• Siła algorytmu. Udostępnij klucze RSA o długości co najmniej 2048 bitów oraz krzywe ECDSA o rzędzie co najmniej 224 bity, akceptowalne minima dla generowania podpisu zgodnie z NIST SP 800-131A Rev.2 §3.
• Podpisywanie postkwantowe jest eksperymentalne i domyślnie wyłączone. Ścieżka postkwantowa istnieje za jawną flagą opt-in. Standardowe profile długoterminowej archiwizacji PDF Advanced Electronic Signatures (PAdES) nie rozpoznają jeszcze pakietów postkwantowych, a większość przeglądarek odrzuca je przy walidacji. Nie włączaj jej dla produkcyjnych podpisów PAdES.

Ta strona dotyczy podpisywania kryptograficznego oraz integracji ze sprzętowym modułem bezpieczeństwa. Każde źródło normatywne jest sparafrazowane; żaden tekst normatywny nie jest odtwarzany. ### Granica pieczy klucza

NextPDF Enterprise integruje się z tokenem PKCS#11 lub HSM. Nie przechowuje, nie generuje ani nie gwarantuje bezpieczeństwa klucza podpisującego. Bezpieczeństwo klucza zależy od tokenu lub HSM, wdrożenia oraz operatora — a nie od samego NextPDF Enterprise. Jesteś odpowiedzialny za udostępnianie tokenu, obsługę PIN-u, konfigurację slotu oraz ochronę sieciową sieciowego HSM.

Obsługa błędów

• Brak rozszerzenia. Skonstruowanie podpisującego PKCS#11 zgłasza typizowany wyjątek operacji, gdy ext-pkcs11 nie jest załadowane. Najpierw sprawdź dostępność.
• Certyfikat lub klucz nieznaleziony po etykiecie. Konstrukcja lub podpisywanie zgłasza typizowany wyjątek nazywający brakujący obiekt. Potwierdź etykietę i slot.
• Już zalogowano. Gdy kilka instancji podpisującego współdzieli buforowany moduł dla tego samego slotu, podpisujący wylogowuje się i loguje ponownie, aby zapewnić świeżą weryfikację PIN-u — wymaganą przez tokeny personal-identity-verification z polityką „PIN za każdym razem”.
• Nieobsługiwany algorytm. Zażądanie algorytmu, którego podpisujący nie mapuje, zgłasza błąd argumentu, zamiast podpisywać zastępczym.
• Sieciowy HSM nieosiągalny. Błąd sieci lub urządzenia zgłasza typizowany wyjątek; podpisujący nigdy po cichu nie wytwarza niepodpisanego dokumentu.

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 — referencja — głęboka referencja podpisującego PKCS#11.
• Security — NextPDF Enterprise — połączona powierzchnia bezpieczeństwa Enterprise.
• Signature — NextPDF Enterprise — producent długoterminowy PAdES B-LT i B-LTA.
• Polityka kryptograficzna FIPS 140 — polityka trybu FIPS oraz strażnik autotestu.
• Podpisywanie chmurowym KMS — NextPDF Pro — strategie key-management-service dla AWS, Azure i GCP.
• Security / Signing (Core) — rdzeniowy podpisujący CMS oraz kontrakt strategii podpisywania.
• HSM · PKCS#11 · CMS · ECDSA — terminy ze słownika.