Dodawanie podpisu cyfrowego PAdES w NextPDF Connect (Pro)

W skrócie

Dodawanie bazowego podpisu cyfrowego PDF Advanced Electronic Signatures (PAdES) do pliku PDF w NextPDF Connect. Użyj sign_pdf; zostało ono ponownie zweryfikowane względem dostawcy narzędzi Pro: ten dostawca rejestruje new SignPdfTool(), którego nazwa protokołu to sign_pdf. sign_pdf to narzędzie poziomu Pro. Podczas uruchamiania serwer sprawdza jego dostępność za pomocą class_exists() i rejestruje je tylko wtedy, gdy pakiet Pro jest zainstalowany.

Domyślnie narzędzie tworzy PAdES B-B. Może utworzyć PAdES B-T (B-B plus jeden RFC 3161 signature-time-stamp) tylko wtedy, gdy host skonfigurował dostawcę znacznika czasu dla narzędzia; żądanie nie może wskazywać urzędu znaczników czasu (TSA). Poziomy długoterminowe (B-LT, B-LTA) oraz ich materiał walidacyjny (DSS, VRI, LTV) nie są częścią tego narzędzia i pozostają tutaj poza zakresem.

Zastrzeżenie U-1. NextPDF nie deklaruje żadnej niezależnej certyfikacji ETSI EN 319 142-1 dla PAdES B-T. EN 319 142-1 nie jest w korpusie weryfikacyjnym. Wymóg B-T dotyczący signature-time-stamp został zweryfikowany względem ETSI EN 319 122-1 §5.3 (podstawa CAdES, którą EN 319 142-1/-2 importują przez odwołanie), wraz z RFC 3161, RFC 5652, RFC 5816 oraz ISO 32000-2 §12.8. Obsługa profilu B-T nie oznacza certyfikacji zgodności ani certyfikacji ważności prawnej; o tym rozstrzyga niezależny walidator.

Instalacja

composer require nextpdf/server
composer require nextpdf/pro

Skonfiguruj transport, a następnie potwierdź obecność sign_pdf za pomocą diagnostic.capabilities. Dla B-T host musi skonstruować narzędzie z dostawcą znacznika czasu. Bez niego żądanie pades_b_t: true kończy się typowanym błędem zamiast cichego obniżenia poziomu.

Przegląd koncepcyjny

sign_pdf oblicza skrót zakresu bajtów pliku, z wyłączeniem symbolu zastępczego wartości podpisu (ISO 32000-2 §12.8.1). Następnie zapisuje strukturę Cryptographic Message Syntax (CMS) SignedData zakodowaną w Distinguished Encoding Rules (DER) w słowniku podpisu Contents (ISO 32000-2 §12.8.1). Obsługiwane algorytmy to RSA-SHA256 (domyślny), RSA + SHA-3 (256/384/512) oraz Ed25519. W przypadku transportów, które nie są poufne od końca do końca, przychodzący ładunek private_key można opakować w opcjonalną kopertę AES-GCM.

Uaktualnienie do B-T. Gdy ustawiono pades_b_t: true oraz host skonfigurował dostawcę znacznika czasu, podpis jest uaktualniany do PAdES B-T: skrót zakresu bajtów jest wysyłany do TSA i osadzany jest TimeStampToken (ISO 32000-2 §12.8.5). B-T to dokładnie B-B plus jeden RFC 3161 signature-time-stamp przenoszony jako niepodpisany atrybut w CMS SignerInfo (RFC 5652 §5.3). Niepodpisane atrybuty nie są objęte podpisem, więc podpisany skrót B-B i jego ważność pozostają niezmienione (RFC 5652 §5.3). Wartością atrybutu jest SignatureTimeStampToken (ETSI EN 319 122-1 §5.3). B-T nie dodaje słownika Document Security Store (DSS), Validation Related Information (VRI), materiału walidacyjnego ani pętli archive-timestamp. Jest to różnica właściwa dla Enterprise w przypadku B-LT/B-LTA; te poziomy są poza zakresem tego narzędzia.

Zastrzeżenie U-1 (powtórzone przy deklaracji B-T). Obsługa B-T w tym miejscu nie jest certyfikacją zgodności EN 319 142-1 ani ważności prawnej; niezależny rozstrzyga o tym niezależny walidator. EN 319 142-1 nie jest w korpusie weryfikacyjnym. B-T opiera się na ETSI EN 319 122-1 §5.3, RFC 3161, RFC 5652, RFC 5816 oraz ISO 32000-2 §12.8.

Poniższy przepływ pokazuje ścieżkę TSA kontrolowaną przez host (żądanie nie może wskazywać TSA) oraz gałąź B-T typu fail-closed (nigdy ciche obniżenie poziomu).

Diagram

Powierzchnia API

Narzędzie	Poziom	Rola	Poziom ryzyka
create_pdf, add_text	Core	Tworzenie treści	Bezpieczne / Ostrożnie
sign_pdf	Pro	Stosuje PAdES B-B (lub B-T kontrolowane przez host)	Wymagane zatwierdzenie
output_pdf	Core	Renderuje i zwraca PDF	Wymagane zatwierdzenie / Przegląd (base64)

Nazwy narzędzi odpowiadają nazwom protokołów w rejestrze. Katalog narzędzi opisuje rejestr. Dostępne narzędzia zależą od zainstalowanego poziomu, a narzędzia poziomów długoterminowych nie są obecne w Pro.

Przykład kodu — Szybki start

1. create_pdf → zbuduj treść za pomocą add_text.
2. sign_pdf z certificate (PEM), private_key (PKCS#8 PEM), opcjonalnie signer_name, reason oraz algorithm. Pomiń pades_b_t (lub ustaw je na false) dla B-B.
3. output_pdf.

Narzędzie zwraca tę kopertę wyniku:

{
  "pdf": "<base64 of the signed PDF>",
  "signature_count": 1,
  "is_complete": true,
  "algorithm": "RSA_SHA256",
  "oid": "<algorithm OID>",
  "digest": "<digest algorithm>",
  "level": "PAdES-B-B",
  "timestamped": false
}

Aby uzyskać podpis B-T kontrolowany przez host, wyślij pades_b_t: true; level staje się "PAdES-B-T", a timestamped staje się true.

Przykład kodu — Produkcja

Podpis wykonuj jako ostatnią operację na treści. Każde add_text/add_image po sign_pdf unieważnia podpis. W transporcie niepoufnym opakuj private_key w kopertę AES-GCM transport_encryption (12-bajtowy nonce; klucz 16/24/32-bajtowy). Sprawdź, czy level w wyniku odpowiada żądaniu. Żądanie pades_b_t: true skierowane do narzędzia bez dostawcy kończy się jawnie błędem. Obsłuż ten błąd i nie ponawiaj go cicho jako B-B.

Przypadki brzegowe i pułapki

• Niezgodność certyfikatu/klucza. Narzędzie odrzuca żądanie z jasnym błędem; klucz prywatny musi pasować do klucza publicznego certyfikatu.
• Nieprawidłowy PEM / wygasły certyfikat. Narzędzie odrzuca żądanie; domyślnie nie podpisuje certyfikatem, którego nie da się sparsować, ani certyfikatem wygasłym.
• Treść po podpisaniu. Narzędzie odrzuca żądanie — podpisuj na końcu.
• Zażądano B-T, brak dostawcy. Narzędzie zwraca typowany błąd: podpis nie jest tworzony i nie jest cicho obniżany do B-B.
• Certyfikat z podpisem własnym. Podpis zostaje zastosowany, ale czytniki pokazują nieznane zaufanie. To zachowanie oczekiwane, nie wada narzędzia.
• Brak Pro. Mając tylko Core, serwer nie rejestruje sign_pdf.

Wydajność

Podpisywanie dodaje budowanie CMS, a dla B-T jeden cykl wymiany z TSA; budżet obejmuje oba elementy. Profil ma wartość semantic: token RFC 3161 jest z natury niereprodukowalny, a skrót zakresu bajtów z §12.8.1 wyklucza wartość podpisu. Stosuj wyłącznie porównanie AST + metadanych podpisu.

Uwagi dotyczące bezpieczeństwa

Podpis zapewnia integralność i uwierzytelnienie względem klucza podpisującego. Sam w sobie nie czyni dokumentu „bezpiecznym” ani „ważnym prawnie”, ani nie gwarantuje niezaprzeczalności. Te właściwości zależą od certyfikatu, jego kotwicy zaufania, pieczy nad kluczem oraz polityki weryfikatora — wszystko to pozostaje poza tym narzędziem. Zaszyfrowanie ładunku klucza kopertą AES-GCM chroni poufność w tranzycie, a nie integralność. Traktuj klucz prywatny jako sekret i preferuj kopertę transport-encryption na każdym kanale niepoufnym.

Zgodność

Stwierdzenie	Specyfikacja	Klauzula	reference_id
Skrót zakresu bajtów obejmuje plik i wyklucza wartość podpisu.	ISO 32000-2	§12.8.1
Contents przechowuje strukturę CMS SignedData zakodowaną w DER.	ISO 32000-2	§12.8.1
Dla znacznika czasu skrót zakresu bajtów trafia do TSA, a token jest umieszczany w Contents.	ISO 32000-2	§12.8.5
Znacznik czasu B-T to niepodpisany atrybut w SignerInfo.	RFC 5652	§5.3
Niepodpisane atrybuty nie zmieniają podpisanego skrótu B-B ani jego ważności.	RFC 5652	§5.3
Wartością signature-time-stamp jest SignatureTimeStampToken.	ETSI EN 319 122-1	§5.3

NextPDF tworzy strukturę podpisu. Nie deklaruje zgodności ani ważności prawnej żadnego wynikowego podpisu; o tym rozstrzyga niezależny walidator. To narzędzie nie tworzy B-LT/B-LTA.

Kontekst komercyjny

sign_pdf to narzędzie poziomu Pro. Serwer rejestruje je tylko wtedy, gdy pakiet Pro zostanie rozpoznany podczas uruchamiania serwera. Poziomy długoterminowe PAdES (B-LT, B-LTA) oraz ich materiał walidacyjny (DSS, VRI, LTV) są tylko dla Enterprise i nie są udostępniane przez to narzędzie ani w tym przepisie.

Rezydencja danych i ograniczanie PII

Certyfikat i klucz prywatny są przekazywane w żądaniu. Używaj koperty AES-GCM transport_encryption na każdym kanale, który nie jest poufny od końca do końca. Podpisany PDF oraz tożsamość podpisującego (signer_name, reason) stanowią treść dokumentu, więc utrzymuj je w granicach swojej rezydencji danych. Za rezydencję na poziomie wdrożenia odpowiada integrator.

Bezpieczna telemetria i czyszczenie logów

Nigdy nie loguj ładunku private_key, klucza/nonce AES-GCM (key/nonce) ani tokenu potwierdzenia. Loguj algorytm, wynikowy level oraz signature_count, a nie materiał klucza. Narzędzie nie emituje bajtów klucza w swoim wyniku.

Model zagrożeń

Rozważane zagrożenia: ujawnienie klucza w tranzycie (ograniczane przez kopertę AES-GCM oraz dostawcę TSA wstrzykiwanego przez host, którego nie da się skonfigurować przez żądanie); skierowanie przez wywołującego MCP znacznika czasu na dowolny punkt końcowy (uniemożliwione, ponieważ dostawca jest wstrzykiwany przez host, a nie konfigurowalny przez żądanie); oraz manipulacja po podpisaniu (skrót zakresu bajtów wykrywa modyfikację). Model zagrożeń dokumentuje rozważane zagrożenia i środki zaradcze; nie deklaruje braku podatności.

Zachowanie w trybie FIPS

Wybór algorytmu (RSA-SHA256, RSA + SHA-3, Ed25519) jest sterowany żądaniem. Prymitywy kryptograficzne zapewnia OpenSSL hosta. W przypadku wdrożenia z ograniczeniami FIPS ogranicz algorytm w warstwie polityki i polegaj na walidowanym module hosta. To narzędzie samo w sobie nie deklaruje walidacji Federal Information Processing Standards (FIPS).

Dostępność transportu

Transport	Dostępny	Uwagi
MCP (stdio)	Tak (Pro)	Używaj koperty klucza AES-GCM na stdio.
REST	Tak (Pro)	Preferuj TLS wraz z kopertą klucza.
gRPC	Tak (Pro)	Preferuj TLS wraz z kopertą klucza.

Poziom ryzyka HITL

sign_pdf wymaga zatwierdzenia, ponieważ jest operacją destrukcyjną i nieodwracalną; narzędzie deklaruje podpowiedź o destrukcyjności. Bramka potwierdzenia działa tak jak dla każdego narzędzia wymagającego zatwierdzenia. output_pdf do pliku również wymaga zatwierdzenia; tryb base64 ma poziom Przegląd (poziomy ryzyka HITL).

Koperta JSON bramki potwierdzenia

sign_pdf bez ważnego tokenu zwraca kopertę wyzwania:

{
  "allowed": false,
  "challenge": "⚠️ CONFIRMATION REQUIRED\n\nOperation: sign_pdf\nDescription: <tool description>\n\nTo proceed, call sign_pdf again with parameter _confirmation_token: \"confirm_<single-use-hex>\"\nExpires in 300 seconds.",
  "token": "confirm_<single-use-hex>"
}

Wywołaj ponownie z _confirmation_token ustawionym na token → { "allowed": true }. Pełny przepływ: output-approval.

Zobacz także

• Wyodrębnianie treści tekstowej
• Kontrola dostępności
• Poziomy ryzyka HITL
• Katalog narzędzi