NextPDF Symfony — bezpieczeństwo i eksploatacja

W skrócie

Pomocniki odpowiedzi stosują stały zestaw nagłówków bezpieczeństwa. Asynchroniczny komunikat DTO dwukrotnie waliduje swoją ścieżkę wyjściową. Podpisywanie jest opcjonalne, a w warstwie Pro ograniczone do opisanego tutaj profilu baseline.

Nagłówki bezpieczeństwa odpowiedzi HTTP

NextPDF\Symfony\Http\PdfResponse stosuje ten sam zestaw nagłówków dla każdej budowanej odpowiedzi: wariantu osadzonego (inline), wariantu pobrania oraz obu wariantów strumieniowanych. Stała w kodzie źródłowym wymusza dokładnie te nagłówki:

Nagłówek	Wartość
`Cache-Control`	`private, max-age=0, must-revalidate`
`Pragma`	`public`
`X-Content-Type-Options`	`nosniff`
`X-Frame-Options`	`DENY`
`Content-Security-Policy`	`default-src 'none'`
`X-Robots-Tag`	`noindex, nofollow`
`Referrer-Policy`	`no-referrer`

Nagłówki te ograniczają sniffing typu zawartości (content-type), osadzanie w ramkach, indeksowanie oraz wyciek danych odsyłających (referrer) dla generowanych dokumentów. Warianty buforowane ustawiają dodatkowo Content-Type: application/pdf oraz Content-Length. Warianty strumieniowane ustawiają typ zawartości i celowo pomijają Content-Length.

Pakiet definiuje ten zestaw nagłówków na stałe. Aby dodać lub zmienić nagłówki, na przykład bardziej restrykcyjny Cache-Control dla uwierzytelnionych pobrań, zmodyfikuj zwracany obiekt Response w kontrolerze przed zwróceniem.

Content-Disposition i obsługa nazw plików

PdfResponse buduje nagłówek Content-Disposition w sposób defensywny. PdfResponseTest weryfikuje to zachowanie:

Nazwa pliku jest oczyszczana; separatory ścieżki i sekwencje przejścia po katalogach (traversal) są usuwane, więc nazwa taka jak ../../../etc/passwd.pdf nie może wskazać lokalizacji poza katalogiem.
Rozszerzenie .pdf jest dodawane, gdy go brakuje; istniejące rozszerzenie nie jest powielane, w tym zapisane wielkimi literami .PDF.
Cudzysłowy proste i ukośniki wsteczne są poprzedzane znakiem ucieczki na potrzeby postaci quoted-string.
Nazwy plików spoza zakresu ASCII otrzymują zastępczy zapis ASCII oraz wariant filename*=UTF-8'' zgodny z RFC-5987 (Request for Comments 5987).
Pusta nazwa pliku jest zastępowana wartością domyślną document.pdf.

Nazwę pliku zależną od użytkownika przekazuj dopiero po sprawdzeniu autoryzacji na poziomie aplikacji. Pakiet oczyszcza dane pod kątem bezpieczeństwa nagłówka, nie kontroli dostępu.

Asynchroniczna walidacja ścieżki wyjściowej

NextPDF\Symfony\Message\GeneratePdfMessage waliduje ścieżkę wyjściową w swoim konstruktorze. NextPDF\Symfony\Message\GeneratePdfHandler ponownie waliduje ją w czasie wykonania, przed zapisem. Konstruktor odrzuca:

pustą ścieżkę lub ścieżkę zawierającą bajt zerowy (null byte);
schemat wrappera strumienia (stream wrapper), taki jak php://...;
segment przejścia po katalogach .. używający separatora / lub \;
ścieżkę niekończącą się na .pdf (bez rozróżniania wielkości liter);
wartość builderClass, która nie jest składniowo poprawną nazwą klasy.

Druga walidacja w handlerze ma znaczenie, ponieważ komunikat może pozostawać w kolejce między wysłaniem a odebraniem. Handler nie ufa ścieżce z kolejki i ponownie stosuje zabezpieczenie ścieżki przed zapisem. Uruchamiaj procesy robocze na koncie systemu plików o minimalnych uprawnieniach, ograniczonym do docelowego katalogu wyjściowego.

Granica rozwiązywania konstruktorów (builder)

GeneratePdfHandler rozwiązuje konstruktory z lokalizatora usług PHP Standard Recommendation 11 (PSR-11), indeksowanego według nazwy klasy, i odrzuca wszystko, co nie jest typem PdfBuilderInterface. Ponieważ lokalizator udostępnia wyłącznie zarejestrowane konstruktory, kontrolowana przez atakującego wartość builderClass w zmanipulowanym ładunku transportowym nie może utworzyć instancji dowolnej klasy. Zgodnie z PSR-11, gdy kontener zgłasza brak danego identyfikatora, jego rozwiązanie kończy się niepowodzeniem, zamiast po cichu zwrócić coś nieoczekiwanego (PSR-11 §1.1.2). W lokalizatorze rejestruj wyłącznie zaufane klasy konstruktorów.

Opcjonalna konfiguracja podpisu cyfrowego

Podpis cyfrowy nie jest częścią pakietu Core. Aktywuje się wyłącznie wtedy, gdy dostępny jest nextpdf/premium (który instaluje warstwę Pro), a przebieg kompilatora wykryje klasy podpisywania Pro. Po zainstalowaniu pakietu i warstwy Pro obsługiwaną, udokumentowaną konfiguracją podpisywania jest profil baseline B-B.

Węzeł konfiguracji signature.level akceptuje dodatkowe wartości tekstowe na potrzeby zgodności schematu w obrębie rodziny konfiguracji NextPDF. Dostarczaną i obsługiwaną funkcją podpisywania tego pakietu jest B-B. Dokumentacja NextPDF Premium obejmuje profile podpisywania wykraczające poza B-B, ich wymagania oraz związane z nimi kwestie eksploatacyjne. Celowo nie opisano ich tutaj.

Uwagi eksploatacyjne dotyczące ścieżki podpisywania B-B:

Mechanizm podpisujący jest rejestrowany tylko wtedy, gdy signature.enabled ma wartość true oraz ustawiono signature.certificate; w przeciwnym razie sekcja pozostaje nieaktywna.
Certyfikat, klucz prywatny i hasło przekazuj za pośrednictwem sekretów Symfony lub zmiennych środowiskowych. Nigdy nie umieszczaj ich w repozytorium.
Ogranicz uprawnienia do odczytu materiału klucza do konta aplikacji.

Opcjonalne rejestrowanie zdarzeń

Rejestry czcionek i obrazów akceptują opcjonalny interfejs Psr\Log\LoggerInterface powiązany przez nullOnInvalid(). Gdy jest obecny, działa jako współpracownik możliwy do podmiany i zgodny z kontraktem rejestratora PHP Standard Recommendation 3 (PSR-3) (PSR-3). Usuwaj dane identyfikujące użytkownika z każdego kontekstu dziennika dodawanego wokół generowania dokumentu; pakiet nie rejestruje zawartości dokumentu.

Lista kontrolna utwardzania eksploatacyjnego

Zachowaj stałe nagłówki odpowiedzi; bardziej restrykcyjne buforowanie dla uwierzytelnionych pobrań dodaj na poziomie kontrolera.
Autoryzuj żądanie przed wygenerowaniem lub zwróceniem dokumentu; pakiet nie wykonuje kontroli dostępu.
Przechowuj materiał klucza podpisywania w sekretach Symfony / zmiennych środowiskowych z uprawnieniami plików zgodnymi z zasadą minimalnych uprawnień.
Uruchamiaj procesy robocze Messengera na koncie o minimalnych uprawnieniach, z dostępem do zapisu ograniczonym do katalogu wyjściowego.
Pozostaw włączone rozszerzenia ext-mbstring i ext-zlib (w przeciwnym razie pakiet natychmiast zgłasza błąd).
Przypnij w aplikacji jedną wersję główną (major) nextpdf/core, aby wersja silnika była deterministyczna między wdrożeniami.

Zgodność

Każdy wiersz to normatywne twierdzenie zawarte na tej stronie, przypięte do pełnego 64-znakowego szesnastkowego reference_id z kontrolowanego korpusu organizacji opracowującej standardy (SDO). Pochodzenie (manifest korpusu, transport pobierania) znajduje się w _sidecars/rag-citations.yaml.

Specyfikacja	Klauzula	reference_id	Twierdzenie
PSR-11	`psr_11_container#1.1.2.p5`		wartość false zwrócona przez has() oznacza, że get() zgłasza wyjątek NotFoundException
PSR-3	`psr_3_logger#x3.p17`		Opcjonalny współpracownik rejestratora

Kontekst komercyjny

Podpis cyfrowy jest dostępny wyłącznie wtedy, gdy zainstalowano nextpdf/premium (Pro); profilem dostarczanym przez ten pakiet jest baseline B-B. Ta opcjonalna funkcja Pro nie wymaga żadnej zmiany kodu w opisanym tutaj pakiecie Core. Zobacz </get-license/?intent=symfony-pro>.

Zobacz także

/integrations/symfony/production-usage/ — bezpieczeństwo procesów roboczych i strumieniowanie.
/integrations/symfony/configuration/ — tabele signature, tsa oraz usług.
/integrations/symfony/troubleshooting/ — diagnozowanie problemów z podpisywaniem i Messengerem.
/integrations/symfony/integration/ — kompletny przewodnik po integracji (end-to-end).