Bezpieczeństwo

W skrócie

NextPDF Pro dodaje powierzchnię bezpieczeństwa na bazie NextPDF Core: maskowanie treści w czasie generowania, wykrywanie PII w warstwie tekstu, strategie podpisywania zdalnego i przez chmurowy KMS oraz wielostronne podpisywanie sekwencyjne. NextPDF Core wytwarza poziomy PAdES B-B i B-T; Pro wytwarza te same poziomy i dodaje nad nimi te przepływy podpisywania (dla B-T podpis B-B plus jeden znacznik czasu podpisu RFC 3161 na wartości podpisu). Ta strona jest na poziomie zachowania. Opisuje, co robi każda część, czego nie robi i gdzie zaczyna się granica Enterprise.

Dostępność i licencjonowanie

Ta funkcja jest dostarczana w NextPDF Pro (nextpdf/pro) i aktywuje się przy pomocy koperty licencyjnej poziomu Pro. Wdrożenie bez tego uprawnienia nie ładuje klas tej funkcji. Porównaj edycje i uzyskaj licencję.

Core dostarcza programowy moduł podpisujący CMS, klienta znaczników czasu RFC 3161, walidację ścieżki RFC 5280 oraz sprawdzanie unieważnień OCSP i CRL. Pro dodaje maskowanie, wykrywanie PII oraz przepływy podpisywania zdalnego/przez chmurowy KMS/sekwencyjnego; te przepływy wytwarzają te same poziomy B-B i B-T z Core przez stos RFC 3161 z Core (dla B-T jeden znacznik czasu podpisu na wartości podpisu). Wdrożenie bez aktywnego uprawnienia Pro nie ładuje tych klas; kontrakt podpisywania Core nadal działa bez zmian.

Instalacja

composer require nextpdf/pro:^3

Przegląd koncepcyjny

Silnik maskowania stosuje uporządkowaną listę reguł do tekstu, zanim strona zostanie zapisana. Każda reguła dopasowuje wyrażenie regularne. Reguła zastępuje dopasowanie na jeden z trzech sposobów: wypełnienie black-box, które usuwa tekst ze strumienia treści, ciąg gwiazdek o tej samej liczbie znaków lub stała etykieta, taka jak [REDACTED]. Silnik usuwa leżące u podstaw obiekty tekstowe w trybie black-box, co zostało przetestowane; nie deklaruje, że odnajdywana jest każda postać wrażliwej treści. Wykrywanie zależy od skonfigurowanych reguł.

Powierzchnia PII jest narzędziem wykrywania, a nie gwarancją redakcji. Wyodrębnia warstwę tekstu, a następnie stosuje wbudowane wzorce dla adresów e-mail, numerów telefonów, numerów ubezpieczenia społecznego Stanów Zjednoczonych (Social Security) oraz numerów kart kredytowych. Zwraca zamaskowany widok tekstu oraz liczbę dopasowań. Nie nadpisuje wyrenderowanych glifów w obrazie strony. Przeskanowana strona bez warstwy tekstu nie daje żadnych dopasowań. Traktuj wynik jako wykrywanie przez dopasowanie wzorców dla skonfigurowanych typów, a nie jako kompletne usunięcie danych osobowych.

Powierzchnia podpisywania dodaje przepływy zdalne i asynchroniczne na bazie modułu podpisującego Core. Sesja oblicza skrót dokumentu, buduje podpisane atrybuty CMS i przekazuje bajty podpisanych atrybutów do strategii podpisywania. Strategią może być chmurowy KMS, odroczony zewnętrzny moduł podpisujący lub ścieżka przyjmowania opakowująca istniejący podpis CAdES lub XAdES. Sesja następnie składa CMS SignedData i przechowuje je zakodowane w DER we wpisie Contents słownika podpisu — ISO 32000-2 §12.8.1. SignerInfo niesie podpisane atrybuty content-type i message-digest; proces obliczania skrótu komunikatu to RFC 5652 §5.4. Weryfikator nie może polegać na skrótach obliczonych przez nadawcę; samodzielnie ponownie oblicza skrót treści i porównuje go z atrybutem message-digest, a porównanie musi się zgadzać, aby podpis był ważny — proces weryfikacji podpisu RFC 5652 §5.6.

NextPDF Core wytwarza poziomy PAdES B-B i B-T; NextPDF Pro wytwarza te same poziomy i dodaje nad nimi swoje przepływy podpisywania. Dla B-B sesja składa CMS SignedData z zestawem podpisanych atrybutów B-B i nie stosuje znacznika czasu. Dla B-T sesja dodaje dokładnie jeden signature-time-stamp RFC 3161 jako niepodpisany atrybut CMS na wartości podpisu: signature-time-stamp to niepodpisany atrybut niosący jeden znacznik czasu obliczony na wartości podpisu cyfrowego dla danego podpisującego — ETSI EN 319 122-1 §5.3, a jego MessageImprint to skrót wartości pola podpisu SignerInfo, identyfikowany przez OID id-aa-timeStampToken — RFC 3161 Appendix A. genTime znacznika czasu to chwila UTC, w której token został utworzony — RFC 3161 §2.4.2. Ponieważ znacznik czasu jest atrybutem niepodpisanym, podpisany skrót B-B, wartość podpisu SignerInfo oraz /ByteRange PDF pozostają niezmienione; rośnie wyłącznie CMS. Token RFC 3161 jest pozyskiwany od skonfigurowanego dostawcy znaczników czasu (domyślnego klienta RFC 3161 z Core lub dostawcy wskazanego przez wywołującego); B-T używa odcisku komunikatu SHA-256 na ścieżce dostawcy domyślnego. NextPDF Pro implementuje obsługę podpisywania PAdES B-T zgodnie z ETSI EN 319 122-1 §5.3, RFC 3161, RFC 5652 oraz RFC 5816; jest to zweryfikowane na fixtures. NextPDF Pro nie deklaruje niezależnej certyfikacji ETSI EN 319 142-1 i nie deklaruje mocy prawnej dokumentu. B-LT i B-LTA dodają Document Security Store oraz znaczniki czasu dokumentu na potrzeby długoterminowej walidacji archiwalnej — ETSI EN 319 142-2 §5.5; te poziomy są możliwością Enterprise (nextpdf/enterprise) i nie są wytwarzane przez Pro. Zobacz Granica Enterprise poniżej.

Dlaczego działa to w ten sposób

Powierzchnia podpisywania przekazuje bajty podpisanych atrybutów do SigningStrategy, zamiast przechowywać klucz prywatny. Ta jedna decyzja jest nośna. Chmurowy KMS, odroczony zewnętrzny moduł podpisujący czy ścieżka przyjmowania CAdES/XAdES spełniają ten sam kontrakt, więc kod wywołujący pozostaje identyczny, a materiał klucza nigdy nie trafia do NextPDF. Rozdzielenie sesji na RemoteSigningSession::prepare() i RemoteSigningSession::complete() pozwala zwrócić podpis asynchronicznie, ponieważ skrót jest ustalony, zanim w ogóle dojdzie do klucza. Znacznik czasu jest dołączany jako niepodpisany atrybut CMS, więc B-T pozostaje addytywne: podpisany skrót B-B, wartość podpisu SignerInfo oraz /ByteRange pozostają nietknięte. Każdy szew jest fail-closed, ponieważ ścieżka podpisywania, która po cichu degraduje, jest gorsza niż taka, która się zatrzymuje. Tło projektowe: Podpisywanie na dużą skalę, bez kompromisów.

Powierzchnia API

Typ	Rodzaj	Rola	Stabilność	Od wersji
RemoteSigningSession	class	Dwufazowa sesja podpisywania zdalnego lub asynchronicznego	stable	1.9.0
RemoteSigningConfig	class	Niemutowalna konfiguracja sesji, w tym poziom PAdES	stable	1.9.0
SequentialSigner	class	Wielostronne podpisywanie sekwencyjne z obsługą DocMDP	stable	1.9.0
SigningStrategy	interface	Kontrakt mechanizmu podpisywania wywoływany przez sesję	stable	1.9.0
PadesWrapper	class	Opakowuje istniejący podpis CAdES lub XAdES do osadzenia w PAdES	stable	1.9.0
KmsSignerInterface	interface (SPI)	Kontrakt sterownika HSM i KMS firm trzecich	stable	2.1.0
GenerationTimeMasker	class	Maskowanie sterowane regułami stosowane przed zapisem strony	stable	1.9.0
MaskingConfig / MaskingRule / MaskingMode	types	Konfiguracja maskowania, reguła i tryb zastępowania	stable	1.9.0

RemoteSigningConfig niesie pole poziomu PAdES, którego wyliczeniem jest SignatureLevel z Core. Ścieżka podpisywania Pro wytwarza poziom bazowy B-B i poziom B-T: skonfiguruj RemoteSigningConfig::default()->withLevel(SignatureLevel::PAdES_B_T) (albo użyj SequentialSigner::withTimestamping()) i dostarcz dostawcę znaczników czasu, a sesja doda niepodpisany atrybut signature-time-stamp RFC 3161. Zarezerwowana przestrzeń /Contents dla B-T jest podnoszona automatycznie, aby token się zmieścił; niedowymiarowana skonfigurowana przestrzeń kończy się błędem konfiguracji o typowanym wyjątku (fail closed) zamiast obcinania. Poziom powyżej B-T niesiony w konfiguracji (B-LT lub B-LTA) jest wartością zadeklarowaną z wyprzedzeniem (forward-declared), na której Pro nie działa; ten wytwórca długoterminowy rozwiązuje się w czasie wykonania przez kontrakt Core i jest dostarczany w pakiecie nextpdf/enterprise.

Przykład kodu — Szybki start

Sign with a cloud-KMS strategy

<?php

declare(strict_types=1);

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

use NextPDF\Pro\Security\Signing\RemoteSigningSession;
use NextPDF\Pro\Security\Signing\SigningStrategy;

/**
 * Produce a signed PDF using any signing strategy.
 *
 * @param string          $pdfWithPlaceholder PDF bytes with a signature placeholder.
 * @param SigningStrategy  $strategy           A cloud-KMS, deferred, or ingest strategy.
 *
 * @return string The signed PDF bytes.
 */
function signWithStrategy(string $pdfWithPlaceholder, SigningStrategy $strategy): string
{
    $session = RemoteSigningSession::create($pdfWithPlaceholder);

    $session->prepare(
        certDer: $strategy->getCertificateDer(),
        chainDer: $strategy->getCertificateChainDer(),
        algorithmOid: $strategy->getSignatureAlgorithmOid(),
        digestAlgorithm: $strategy->getDigestAlgorithm(),
        contentsHexStart: 0,
        contentsHexEnd: 0,
    );

    return $session->complete($strategy);
}

Wywołujący zależy od kontraktu SigningStrategy. Strategia chmurowego KMS i strategia przyjmowania CAdES obie go spełniają, więc ten kod nie zmienia się między strategiami.

Przykład kodu — Produkcja

Multi-party sequential signing with audit logging

<?php

declare(strict_types=1);

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

use NextPDF\Pro\Security\Signing\SequentialSigner;
use NextPDF\Pro\Security\Signing\SigningStrategy;
use Psr\Log\LoggerInterface;

final readonly class ApprovalWorkflow
{
    public function __construct(private LoggerInterface $logger) {}

    /**
     * Sign a PDF with two parties in sequence.
     *
     * @param string          $pdfData   The PDF bytes to sign.
     * @param SigningStrategy  $approver  The first-party strategy.
     * @param SigningStrategy  $reviewer  The second-party strategy.
     *
     * @return string The signed PDF bytes.
     */
    public function run(string $pdfData, SigningStrategy $approver, SigningStrategy $reviewer): string
    {
        try {
            $result = SequentialSigner::create($pdfData)
                ->addSigner($approver, 'Approver', reason: 'Approved')
                ->addSigner($reviewer, 'Reviewer', reason: 'Reviewed')
                ->sign();

            $this->logger->info('Sequential signing complete', [
                'signatures' => $result->signatureCount,
            ]);

            return $result->pdfData;
        } catch (\Throwable $e) {
            $this->logger->error('Sequential signing failed', ['error' => $e->getMessage()]);

            throw $e;
        }
    }
}

Każdy podpisujący to oddzielna rewizja przyrostowa. Blok catch loguje i ponownie rzuca; nie połyka awarii, co utrzymuje ścieżkę podpisywania w trybie fail-closed.

Przypadki brzegowe i pułapki

• Wytworzony podpis nie jest podpisem zweryfikowanym. Walidacja ścieżki przebiega u weryfikatora z jego kotwicami zaufania — RFC 5280 §6.1. Wytwórca nie może deklarować wyniku.
• Wykrywanie maskowania zależy od skonfigurowanych reguł. Zestaw reguł, który nie dopasowuje wartości, nie maskuje jej. Silnik nie deklaruje, że cała wrażliwa treść została znaleziona.
• Wykrywanie PII dotyczy wyłącznie warstwy tekstu. Przeskanowana strona bez warstwy tekstu nie daje żadnych dopasowań. Narzędzie nie nadpisuje wyrenderowanych glifów strony.
• Struktura CMS musi zmieścić się w zarezerwowanej przestrzeni Contents. CMS SignedData B-B z pełnym łańcuchem certyfikatów ma pewien rozmiar; odpowiednio wymiaruj zarezerwowaną przestrzeń, w przeciwnym razie sesja zgłosi błąd przepełnienia.
• Strategia chmurowego KMS zależy od osiągalności sieci i dostępności dostawcy. Błąd sieci lub dostawcy zgłasza typowany wyjątek; sesja nie wytwarza po cichu niepodpisanego dokumentu.
• OCSP unknown to nie good. Traktuj unknown jako brak rozstrzygnięcia — RFC 6960 §2.2.

Wydajność

Podpis programowy to jednocyfrowe milisekundy. Podpis chmurowego KMS dodaje jedną rundę sieciową do dostawcy. Podpis B-T dodaje jedną rundę do skonfigurowanego dostawcy znaczników czasu ponad operację podpisywania. Budżet czasu ściany 1500 ms obejmuje pojedynczy podpis B-B ze zdalnym dostawcą na rozgrzanym połączeniu. Koszt maskowania skaluje się z liczbą reguł i długością tekstu. Profil powtarzalności to structural: podpisane atrybuty B-B osadzają chwilę podpisu, a podpis B-T dodatkowo osadza token znacznika czasu, więc dwa przebiegi różnią się bajtami czasu podpisu i znacznika czasu, podczas gdy podpisana struktura jest identyczna.

Uwagi dotyczące bezpieczeństwa

To granica kryptograficzna, więc model zagrożeń jest jawny. Zakres bajtów (byte range) jest obliczany przez silnik i nigdy nie jest przyjmowany od wywołującego. Ścieżka podpisywania jest fail-closed: awaria prymitywu lub luka w możliwościach zgłasza typowany wyjątek i nigdy po cichu nie degraduje do słabszego algorytmu. Strategia chmurowego KMS jest punktem integracji, a nie magazynem kluczy. Ochrona klucza zależy od obsługi klucza, skonfigurowanego KMS oraz wdrożenia; NextPDF Pro nie przechowuje klucza prywatnego dla strategii KMS. Pro działa w trybie zgodnym z FIPS, gdy skonfigurowany jest względem zwalidowanego zgodnie z FIPS KMS lub HSM; NextPDF Pro sam nie jest zwalidowanym zgodnie z FIPS modułem kryptograficznym. Ta strona dotyczy podpisywania kryptograficznego; każde źródło normatywne jest sparafrazowane, a żadne nie jest powielone.

Rezydencja danych i ograniczanie ryzyka PII

Powierzchnie maskowania i PII działają w obrębie procesu. Żadna treść dokumentu nie opuszcza hosta na potrzeby maskowania ani wykrywania PII. Strategia chmurowego KMS wysyła do dostawcy skrót podpisanych atrybutów, a nie dokument, na potrzeby operacji podpisywania. Wykrywanie PII odbywa się przez dopasowywanie wzorców dla skonfigurowanych typów i usuwa leżące u podstaw obiekty tekstowe w trybie black-box, co zostało przetestowane; nie jest to gwarancja kompletnego usunięcia danych osobowych i nie jest to oświadczenie o zgodności regulacyjnej.

Bezpieczna telemetria i czyszczenie logów

Biblioteka zgłasza typowane wyjątki ze strukturalnymi komunikatami. Nie zapisuje treści dokumentu ani wykrytych wartości PII do komunikatów wyjątków ani logów. Wdrożenie logujące wokół ścieżki podpisywania powinno logować pola strukturalne pokazane w przykładzie produkcyjnym, a nie bajty dokumentu.

Zachowanie w trybie FIPS

Pro wybiera algorytm na podstawie skonfigurowanego algorytmu podpisu i strategii. Gdy skonfigurowany jest względem zwalidowanego zgodnie z FIPS KMS lub HSM, operacja kryptograficzna przebiega w tej zwalidowanej granicy. Sam NextPDF Pro wykonuje strukturalne składanie i obliczanie skrótu; nie jest zwalidowanym zgodnie z FIPS modułem i nie formułuje żadnego twierdzenia o certyfikacji FIPS.

Granica Enterprise

NextPDF Pro wytwarza poziom bazowy B-B oraz poziom B-T. B-T dodaje jeden signature-time-stamp RFC 3161 jako niepodpisany atrybut CMS na wartości podpisu, obliczony na wartości podpisu cyfrowego dla danego podpisującego — ETSI EN 319 122-1 §5.3. NextPDF Pro implementuje to zgodnie z ETSI EN 319 122-1 §5.3, RFC 3161, RFC 5652 oraz RFC 5816; jest to zweryfikowane na fixtures. NextPDF Pro nie deklaruje niezależnej certyfikacji ETSI EN 319 142-1 i nie deklaruje mocy prawnej dokumentu.

Poziomy B-LT i B-LTA są możliwościami Enterprise i nie są wytwarzane przez Pro. B-LT i B-LTA dodają Document Security Store oraz znaczniki czasu dokumentu na potrzeby długoterminowej walidacji archiwalnej — ETSI EN 319 142-2 §5.5. Konfiguracja żądająca Document Security Store lub pętli archiwalnej długoterminowej rozwiązuje tego wytwórcę w czasie wykonania przez kontrakt Core; ten wytwórca jest dostarczany w pakiecie nextpdf/enterprise. We wdrożeniu wyłącznie Pro żądanie B-LT lub B-LTA kończy się błędem (fail closed) z komunikatem nazywającym brakujący komponent Enterprise. Pro nie wytwarza żadnego Document Security Store, żadnego słownika VRI, żadnego znacznika czasu dokumentu ani żadnej pętli archiwalnej i nie formułuje żadnego twierdzenia o walidacji długoterminowej (LTV). Sprzętowe przechowywanie kluczy przez PKCS#11 oraz profil polityki kryptograficznej FIPS 140-3 są również możliwościami Enterprise.

Poziom PAdES	Dodaje	Edycja wytwórcy
B-B	Podpis CMS z podpisanymi atrybutami	Core, Pro, Enterprise
B-T	Jeden niepodpisany atrybut signature-time-stamp RFC 3161 na wartości podpisu	Core, Pro, Enterprise
B-LT	Document Security Store z materiałem walidacyjnym	Enterprise (nextpdf/enterprise)
B-LTA	Znaczniki czasu dokumentu dla ważności archiwalnej	Enterprise (nextpdf/enterprise)

Kontrakt zachowania

• Maskowanie stosuje skonfigurowane reguły przed zapisem strony i usuwa leżące u podstaw obiekty tekstowe w trybie black-box, co zostało przetestowane.
• Wykrywanie PII wyodrębnia warstwę tekstu, stosuje skonfigurowane wzorce i zwraca zamaskowany widok oraz liczbę dopasowań. Nie nadpisuje wyrenderowanych glifów.
• Podpisywanie zdalne jest dwufazowe: prepare oblicza skrót i buduje podpisane atrybuty; complete składa CMS i osadza je.
• Pro wytwarza poziom bazowy B-B oraz poziom B-T. Dla B-T sesja dodaje jeden signature-time-stamp RFC 3161 jako niepodpisany atrybut CMS na wartości podpisu; podpisany skrót B-B oraz /ByteRange pozostają niezmienione. Żądanie B-T bez dostawcy znaczników czasu lub z niedowymiarowaną skonfigurowaną przestrzenią Contents kończy się błędem konfiguracji o typowanym wyjątku (fail closed). Żądanie B-LT lub B-LTA bez pakietu Enterprise kończy się błędem (fail closed) z nazwanym komunikatem.
• Strategia chmurowego KMS otrzymuje skrót podpisanych atrybutów, a nie dokument, i zwraca surowe bajty podpisu.

Zgodność ze standardami

Twierdzenie	Standard	Klauzula
Podpis CMS jest przechowywany zakodowany w DER we wpisie Contents słownika podpisu.	ISO 32000-2	§12.8.1
Proces obliczania skrótu komunikatu; podpisane atrybuty niosą content-type i message-digest.	RFC 5652	§5.4
Weryfikator nie może polegać na skrótach obliczonych przez nadawcę; samodzielnie ponownie oblicza i porównuje (proces weryfikacji podpisu).	RFC 5652	§5.6
signature-time-stamp PAdES B-T to niepodpisany atrybut niosący jeden znacznik czasu obliczony na wartości podpisu cyfrowego dla danego podpisującego (Pro wytwarza B-T).	ETSI EN 319 122-1	§5.3
MessageImprint tokenu id-aa-timeStampToken signature-time-stamp to skrót wartości pola podpisu SignerInfo.	RFC 3161	Appendix A
Po stronie weryfikacji NextPDF wiąże MessageImprint znacznika czasu podpisu z wartością podpisu SignerInfo i kończy się błędem (fail closed) przy niezgodności, braku lub zdublowaniu tokenu albo odcisku SHA-1 (ścisła weryfikacja, a nie certyfikacja).	RFC 3161	Appendix A
Token znacznika czasu B-T niesie genTime w UTC, będący chwilą utworzenia tokenu.	RFC 3161	§2.4.2
Walidacja ścieżki certyfikacji sprawdza podstawowe ograniczenia oraz dane wejściowe ścieżki do kotwicy zaufania.	RFC 5280	§6.1
OCSP raportuje certStatus jako good, revoked lub unknown.	RFC 6960	§2.2
B-LT i B-LTA dodają Document Security Store oraz znaczniki czasu dokumentu na potrzeby walidacji długoterminowej (granica Enterprise).	ETSI EN 319 142-2	§5.5

Wszystkie klauzule są sparafrazowane. NextPDF nie powiela tekstu normatywnego. Po autorytatywne brzmienie sięgnij do opublikowanych standardów. NextPDF Pro implementuje obsługę podpisywania PAdES B-T zgodnie z ETSI EN 319 122-1 §5.3 (signature-time-stamp), RFC 3161, RFC 5652 oraz RFC 5816 i jest to zweryfikowane na fixtures. ETSI EN 319 142-1 (część dotycząca poziomów bazowych PAdES) leży poza przywołanym zbiorem dowodów; NextPDF Pro nie deklaruje zatem niezależnej certyfikacji, zgodności (conformance) ani zgodności (compliance) z ETSI EN 319 142-1 i nie deklaruje mocy prawnej dokumentu. Ta strona opisuje wytwarzaną strukturę, standardy, które implementuje obsługa B-T, oraz granicę Enterprise B-LT/B-LTA, a nie certyfikowany poziom zgodności.

Granica publikacji

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

• Security — Deep Reference — pełne opracowanie referencyjne tej powierzchni bezpieczeństwa Pro.
• Core signing — moduł podpisujący CMS, znacznik czasu RFC 3161, walidacja ścieżki RFC 5280, OCSP i CRL.
• PAdES clause map — B-B, B-T, B-LT, B-LTA w poszczególnych edycjach.
• NextPDF Pro — pełna powierzchnia funkcji Pro.
• Core security — szyfrowanie oraz szersza powierzchnia podpisu.
• CMS · PAdES · RFC 3161 timestamp · KMS · DSS — terminy ze słownika.