Bezpieczeństwo i eksploatacja compat-legacy

W skrócie

Adapter korzysta z modelu bezpieczeństwa silnika NextPDF i dodaje kilka celowych wzmocnień względem historycznej wersji TCPDF 6.2.13. Ta strona precyzyjnie określa, co jest dostępne, a co nie, bez wykraczania poza faktyczny zakres. Szczególnie uważnie przeczytaj sekcję o podpisywaniu; jej zakres jest celowo wąski.

Wzmocnione zachowania historyczne

Ze względów bezpieczeństwa adapter zmienia trzy historyczne zachowania TCPDF 6.2.13. Nie można przywrócić ich konfiguracją do niebezpiecznej postaci:

Zagadnienie	Historyczne TCPDF 6.2.13	Adapter
Obsługa błędów	Error() wywołuje die() i przerywa proces	Error() zgłasza wyjątek RuntimeException; kod wywołujący może wykryć i przechwycić niepowodzenie bez cichego przerwania procesu.
Wykonywanie kodu z HTML	Historyczna furtka mogła uruchamiać PHP z poziomu znaczników	Stała K_TCPDF_CALLS_IN_HTML jest na stałe ustawiona na false; znaczniki nie mogą wyzwolić wykonania PHP.
Bezpośrednie wyjście	Output() wypisuje dane do aktywnego bufora wyjściowego	Wyjście przechodzi przez bezpieczny mostek docelowy i nie zanieczyszcza bufora wyjściowego kontrolowanego przez kod wywołujący.

Dzięki zmianie w obsłudze błędów możesz wykryć niepowodzenie, zamiast doprowadzać do przerwania procesu. Standard weryfikacji bezpieczeństwa aplikacji (ASVS) 5.0 organizacji Open Worldwide Application Security Project (OWASP), §16.5.3, stanowi, że aplikacja powinna obsługiwać awarie w sposób kontrolowany i bezpieczny oraz zapobiegać stanom fail-open. Zgłaszanie wyjątku zamiast przerywania procesu realizuje tę zasadę. Wzmocnienie obsługi HTML usuwa punkt umożliwiający wykonanie kodu. Kod historyczny, który polegał na dawnym zachowaniu, traktuj jako wadę do usunięcia podczas /integrations/tcpdf-compat/migration/. Przypięty skrót klauzuli znajduje się w nagłówku front-matter strony, w polu citations.

Szyfrowanie

Adapter udostępnia metodę SetProtection() z TCPDF i deleguje ją do standardowej procedury bezpieczeństwa silnika NextPDF.

• Standardowa procedura używa AES-256. Historyczny parametr $mode jest akceptowany ze względu na zgodność sygnatury metody i ignorowany; tą metodą nie można wybrać słabszego szyfru. Gdy tryb ścisły jest włączony, niedomyślny $mode zgłasza wyjątek, aby migracja musiała go uwzględnić (potwierdzone w tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php).
• Jeśli nie podano hasła właściciela, adapter generuje kryptograficznie silne, losowe hasło właściciela, zamiast ponownie używać hasła użytkownika. Zapobiega to uzyskaniu kontroli nad dokumentem na poziomie właściciela przez osoby mające dostęp na poziomie użytkownika.
• Szyfrowanie oparte na certyfikatach (klucz publiczny) nie odbywa się za pośrednictwem SetProtection(); adapter ignoruje jej parametr $pubkeys. Użyj udostępnionego przez adapter nowoczesnego punktu wejścia do szyfrowania kluczem publicznym (setPublicKeyEncryption()), który deleguje do silnika.

Zachowanie szyfrowania odzwierciedla standardową procedurę bezpieczeństwa opisaną w ISO 32000-2 §7. Klauzula ta definiuje wpisy słownika szyfrowania oraz standardową procedurę AES-256, której używa silnik. Niniejsza dokumentacja nie twierdzi, że wynik jest „bezpieczny domyślnie” ani „odporny na manipulacje”. Określa jedynie zastosowany szyfr oraz obsługę hasła właściciela zaimplementowaną w kodzie. Przypięty skrót klauzuli znajduje się w nagłówku front-matter strony, w polu citations.

examples/security-encryption.php

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
$pdf->AddPage();
$pdf->SetFont('helvetica', '', 12);
$pdf->Cell(0, 10, 'Encrypted document');

// User password set; owner password auto-generated (strong, random).
$pdf->SetProtection([], 'user-secret');

$pdf->Output(__DIR__ . '/encrypted.pdf', 'F');

Podpisy cyfrowe — oświadczenie o zakresie

Czytaj tę sekcję dosłownie. Jest celowo zachowawcza.

• Historyczne metody TCPDF setSignature() oraz addEmptySignatureAppearance() są niezaimplementowane w adapterze opartym na silniku core. W trybie domyślnym nie robią nic. W trybie ścisłym zgłaszają wyjątek TcpdfNotImplementedException.
• Podpisywanie cyfrowe nie jest funkcją dystrybucji core za pośrednictwem tego adaptera. Obsługa podpisów na poziomie baseline wymaga komercyjnej edycji NextPDF.
• Jeśli dostępna jest edycja komercyjna, adapter udostępnia nowoczesny punkt wejścia do podpisu (setSignatureV2()), który deleguje do silnika. Jego profilem domyślnym jest profil baseline (B-B).
• Niniejsza dokumentacja nie twierdzi, że jakakolwiek edycja tworzy za pośrednictwem tego adaptera profile podpisu ze znacznikiem czasu, z walidacją długoterminową ani archiwizacyjne. W szczególności nie deklaruje zachowania B-T, B-LT ani B-LTA. Specyfikacja baseline PDF Advanced Electronic Signatures (PAdES), §6.1, definiuje cztery odrębne poziomy baseline: B-B, B-T, B-LT oraz B-LTA. Każdy z nich ma własne wymagania. B-B jest poziomem baseline, a poziomy wyższe (znacznik czasu, długoterminowy, archiwizacyjny) to odrębne, bardziej wymagające profile. Dokumentacja tej warstwy zgodności obejmuje wyłącznie poziom baseline B-B. Poziomy wyższe są wyraźnie poza zakresem i nie są tu deklarowane dla żadnej edycji. Przypięty skrót klauzuli znajduje się w nagłówku front-matter strony, w polu citations.
• Niniejsza dokumentacja nigdzie nie deklaruje podpisu „certyfikowanego”, „gwarantowanego”, „ważnego prawnie” ani „kwalifikowanego zgodnie z eIDAS”. Prawidłowość podpisywania, polityka kotwic zaufania oraz ważność prawna są odpowiedzialnością edycji podpisującej i infrastruktury klucza publicznego (PKI) kodu wywołującego, a nie tej warstwy zgodności.

Jeśli migracja wymaga podpisywania, potraktuj je jako odrębny obszar prac: użyj nowoczesnego API podpisu w edycji komercyjnej i zweryfikuj uzyskany podpis za pomocą niezależnego weryfikatora. Nie polegaj na wywołaniu TCPDF setSignature(); tutaj nie wykonuje ono żadnej operacji.

Historyczna metoda setTimeStamp() jest akceptowana ze względu na zgodność sygnatury metody i emituje powiadomienie; za pośrednictwem tego adaptera nie tworzy podpisu ze znacznikiem czasu.

PDF/A i zgodność

Flaga pdfa w konstruktorze jest akceptowana ze względu na zgodność sygnatury metody. Zgodność archiwizacyjna PDF/A wymaga komercyjnej edycji NextPDF. Adapter udostępnia enablePdfA(), które deleguje do silnika, a silnik zwraca konkretny błąd konfiguracji, gdy brakuje wymaganej edycji. Adapter nie tworzy po cichu niezgodnego pliku, deklarując jednocześnie PDF/A.

Wynik jest zawsze w formacie PDF 2.0 (ISO 32000-2). ISO 32000-2 §7.5.2 określa, że zgodny mechanizm zapisu identyfikuje wersję dokumentu jako 2.0 i nie obniża jej do starszej wersji podczas zapisu. Dlatego setPDFVersion() nie może ustawić jako celu starszej wersji (zobacz /integrations/tcpdf-compat/method-coverage/ §4). Przypięty skrót klauzuli znajduje się w nagłówku front-matter strony, w polu citations.

Wskazówki eksploatacyjne

• Brak przerwania procesu. Ponieważ Error() zgłasza wyjątek zamiast wywoływać die(), opakuj punkty wejścia renderowania w try/catch i mapuj niepowodzenia na kontrakt obsługi błędów swojej aplikacji. Nie zakładaj, że nieudane renderowanie kończy żądanie.
• Bezpieczeństwo bufora wyjściowego. Output() z S zwraca bajty; z F zapisuje plik; z E zwraca treść MIME (Multipurpose Internet Mail Extensions) zakodowaną w base64; z I/D kieruje dane przez ścieżkę wyjściową silnika. W procesach roboczych i procedurach obsługi HTTP (Hypertext Transfer Protocol) preferuj S lub F, aby samodzielnie kontrolować odpowiedź; zobacz /integrations/tcpdf-compat/production-usage/.
• Tryb ścisły nie jest ustawieniem produkcyjnym. Ogranicz go do zadania ciągłej integracji (CI) lub zadania audytowego. Wyjątek w produkcyjnej ścieżce renderowania jest gorszy niż parametr po cichu obniżony.
• Higiena stałych. Zdefiniuj stałe PDF_* / K_* przed pierwszym utworzeniem adaptera. Tych dwóch wzmocnionych flag (K_TCPDF_CALLS_IN_HTML, K_TCPDF_THROW_EXCEPTION_ERROR) nie można osłabić; nie próbuj ich osłabiać.
• Losowe hasła właściciela. Jeśli polegasz na deterministycznym haśle właściciela, ustaw je jawnie. W przeciwnym razie dla każdego dokumentu generowane jest silne, losowe hasło, którego nie da się odzyskać.

Uwagi dotyczące modelu zagrożeń

• W przypadku metod obrazów adapter odrzuca ścieżkę z wrapperem strumienia jeszcze przed jakimkolwiek odczytem z systemu plików. Wykrywanie typu obrazu (TcpdfImages::getImageFileType) traktuje każdą ścieżkę scheme://, w tym phar://, php:// i inne wrappery strumieni PHP, jako wrapper i pomija sondowanie file_get_contents / getimagesize, przechodząc do wnioskowania wyłącznie na podstawie rozszerzenia. Zamyka to wektor deserializacji metadanych phar w celu backportu PHP 7.4; sam silnik odrzuca osadzanie ze ścieżki z wrapperem.
• Adapter nie dodaje walidacji ani oczyszczania ścieżek plików przekazywanych do metod obrazów lub wyjścia ponad to, co robi silnik. Na granicy swojej aplikacji traktuj ścieżki i adresy URL dostarczone przez kod wywołujący jako niezaufane.
• Kod HTML przekazany do metod HTML jest renderowany przez silnik, a nie przez parser HTML TCPDF. Historyczny punkt wykonania PHP jest zamknięty, ale i tak traktuj kod HTML dostarczony przez kod wywołujący jako niezaufane dane wejściowe.
• Szyfrowanie chroni poufność dokumentu w spoczynku w ramach standardowej procedury. Nie zastępuje bezpieczeństwa transportu ani kontroli dostępu w Twojej aplikacji.

Zobacz także

• /integrations/tcpdf-compat/method-coverage/ — dokładne zachowanie SetProtection(), setSignature()
• /integrations/tcpdf-compat/configuration/ — dwie wzmocnione, niekonfigurowalne flagi
• /integrations/tcpdf-compat/production-usage/ — procesy robocze, bufory, obsługa niepowodzeń
• docs/TCPDF_COVERAGE.md — miarodajna macierz pokrycia
• Plik NOTICE pakietu — oświadczenie dotyczące niezależnej implementacji