Bezpieczeństwo i eksploatacja pakietu NextPDF dla Laravel

W skrócie

Pakiet ustawia stałe nagłówki odpowiedzi dla Portable Document Format (PDF), oczyszcza nazwy pobieranych plików, waliduje ścieżki wyjściowe kolejki w procesie roboczym oraz kieruje wywołania Hypertext Transfer Protocol (HTTP) do urzędu znacznika czasu przez klienta z ochroną przed request forgery. Ta strona wyjaśnia model zagrożeń oraz konfigurację wdrożeniową wymaganą przez każde z tych zabezpieczeń.

Instalacja

composer require nextpdf/laravel
php artisan vendor:publish --tag=nextpdf-config

Przegląd koncepcyjny

Pakiet dostosowuje silnik PDF do użycia we frameworku webowym. Żądanie HTTP oraz transport kolejki wyznaczają granicę zaufania. Zabezpieczenia obejmują obsługę odpowiedzi, zdeserializowane ładunki zadań oraz wychodzący ruch HTTP do urzędu znacznika czasu.

Powierzchnia API — model zagrożeń

Zasób	Zagrożenie	Zabezpieczenie w tym pakiecie	Wymagana konfiguracja wdrożeniowa
Odpowiedź HTTP z plikiem PDF	Sniffing typu zawartości, clickjacking, indeksowanie	Stały zestaw nagłówków w każdej fabryce `PdfResponse`	Brak; nagłówki nie są konfigurowalne
Nazwa pobieranego pliku	Wstrzyknięcie nagłówka, path traversal w `Content-Disposition`	Mechanizm oczyszczania nazwy pliku usuwa separatory, znaki sterujące, bajty null	Brak; oczyszczanie działa zawsze
Ścieżka wyjściowa zadania kolejki	Zapis dowolnego pliku za pomocą zmanipulowanego serializowanego ładunku	Ścieżka walidowana w `handle()` w procesie roboczym	Kieruj dane wyjściowe do kontrolowanej ścieżki magazynu
Wychodzący ruch HTTP do urzędu znacznika czasu (TSA)	Server-side request forgery, manipulacja danymi przesyłanymi jawnie	Klient HTTP z ochroną przed request forgery; HTTPS wymuszany, o ile nie zostanie jawnie poluzowany	Pozostaw `tsa.allow_insecure_http = false`; przypnij Subject Public Key Info (SPKI)
Współdzielony stan procesu roboczego	Wyciek stanu między żądaniami w długo działających procesach roboczych	Zablokowany rejestr czcionek; ograniczona pamięć podręczna obrazów; dokument powiązany z fabryką	Ustaw `preload_fonts`; ogranicz pamięć na poziomie kontenera

Utwardzanie odpowiedzi

Każda fabryka PdfResponse ustawia stały zestaw nagłówków:

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

Te wartości są stałymi w PdfResponse. Nie są konfigurowalne. Zestaw testów pakietu sprawdza każdy nagłówek w każdej metodzie fabrycznej, także w wariantach strumieniowych.

Nazwa pobieranego pliku przechodzi przez mechanizm oczyszczania, zanim trafi do nagłówka Content-Disposition. Ten mechanizm usuwa separatory ścieżek, znaki sterujące i bajty null oraz emituje parametr filename*= zgodny z Request for Comments (RFC) 5987 dla nazw spoza zakresu ASCII. Pusta nazwa pliku jest zastępowana przez document.pdf.

Walidacja ładunku kolejki

GeneratePdfJob serializuje domknięcie do transportu kolejki. Proces roboczy waliduje ścieżkę wyjściową w handle(), a nie podczas wysyłania. Walidacja odrzuca:

bajty null w ścieżce,
schematy stream wrapperów (na przykład php://),
segmenty path traversal ..,
każdą ścieżkę, która nie kończy się na .pdf (bez rozróżniania wielkości liter).

Każde odrzucenie skutkuje zgłoszeniem InvalidArgumentException. Walidacja uruchamia się, gdy proces roboczy pobiera zadanie. Serializowany ładunek w transporcie Redis lub bazy danych może zostać zmieniony, zanim odczyta go proces roboczy. Kieruj ścieżkę wyjściową do kontrolowanego katalogu magazynu; nie twórz jej na podstawie niezwalidowanych danych wejściowych żądania.

Wychodzący ruch HTTP do urzędu znacznika czasu

Gdy urząd znacznika czasu jest skonfigurowany, pakiet wiąże Psr\Http\Client\ClientInterface zgodny z PHP Standard Recommendation (PSR)-18. Klient PSR-18 wysyła żądanie PSR-7 i zwraca odpowiedź PSR-7 (PSR-18 §2). Powiązany klient opakowuje klienta opartego na curl warstwą ochrony przed request forgery. Wymusza HTTPS, chyba że tsa.allow_insecure_http jest jawnie ustawione na true.

Urząd znacznika czasu to funkcja warstwy Premium. Opisywany tutaj pakiet Core zapewnia powiązanie klienta HTTP i okablowanie klienta znacznika czasu; samo podpisywanie wymaga nextpdf/premium. Ta strona nie dokumentuje zachowania baseline PDF Advanced Electronic Signatures (PAdES) poza B-B; wyższe poziomy baseline są poza zakresem.

Wskazówki eksploatacyjne dla urzędu znacznika czasu:

Pozostaw tsa.allow_insecure_http ustawione na false w środowisku produkcyjnym.
Ustaw tsa.pinned_public_keys na zakodowane w base64 skróty SHA-256 SPKI certyfikatu urzędu znacznika czasu (postać wg RFC 7469).
Pozostaw tsa.warn_on_key_rotation ustawione na true, aby zmiana SPKI została zapisana w logu, zanim wygaśnie przypięty certyfikat.
Pobieraj tsa.url wyłącznie z zaufanej konfiguracji. Jeśli operator może ustawić ten adres z panelu administracyjnego, zastosuj zaporę ruchu wychodzącego lub politykę DNS, aby zmniejszyć ekspozycję na request forgery.

Rejestrowanie zdarzeń

Używaj Psr\Log\LoggerInterface do diagnostyki. Przekazuj ustrukturyzowany kontekst, a nie interpolowane ciągi znaków. PSR-3 pozostawia escapowanie symboli zastępczych implementacji loggera i wymaga od wywołujących, aby nie escapowali wcześniej wartości kontekstu (PSR-3 §1.2). Loguj klasę wyjątku, a nie jego komunikat ani ślad stosu, aby ograniczyć wewnętrzne szczegóły w logach.

Przykład kodu — produkcja

<?php

declare(strict_types=1);

// .env — production timestamp-authority hardening
// NEXTPDF_TSA_URL=https://tsa.example.test
// NEXTPDF_TSA_ALLOW_INSECURE_HTTP=false
// NEXTPDF_TSA_WARN_ROTATION=true

return [
    'tsa' => [
        'url'                 => env('NEXTPDF_TSA_URL'),
        'allow_insecure_http' => env('NEXTPDF_TSA_ALLOW_INSECURE_HTTP', false),
        'warn_on_key_rotation' => env('NEXTPDF_TSA_WARN_ROTATION', true),
        'pinned_public_keys'  => [
            // base64 SHA-256 SPKI hashes of the TSA certificate
        ],
    ],
];

Przypadki brzegowe i pułapki

Zestaw nagłówków odpowiedzi jest stały. Aplikacje, które potrzebują innej Content Security Policy (CSP), muszą przetworzyć odpowiedź po tym, jak zwróci ją fabryka.
Walidacja ścieżki działa w procesie roboczym. Nieprawidłowa ścieżka przechodzi przez dispatch() i kończy się niepowodzeniem dopiero podczas wykonywania zadania.
tsa.allow_insecure_http = true usuwa wymuszanie HTTPS i osłabia zaufanie do znacznika czasu. Ogranicz tę konfigurację do lokalnego środowiska deweloperskiego.
Rejestr czcionek zostaje zablokowany po rozgrzaniu; pakiet z założenia odrzuca próby rejestracji czcionki podczas działania długo działającego procesu roboczego.

Wydajność

Zabezpieczenia korzystają z operacji na ciągach znaków i tablicach o stałym koszcie wykonania i nie dodają mierzalnego narzutu na żądanie. Parsowanie czcionek przy pierwszym użyciu jest dominującym kosztem eksploatacyjnym; wczytaj wstępnie czcionki podczas uruchamiania procesu roboczego, aby uniknąć opóźnienia pierwszego żądania.

Uwagi dotyczące bezpieczeństwa

Ta strona służy jako odniesienie do modelu zagrożeń dla pakietu. Kod źródłowy wymusza te zabezpieczenia, a zestaw testów je weryfikuje. Tabela modelu zagrożeń oraz kroki dotyczące urzędu znacznika czasu wskazują konfigurację wdrożeniową, którą musi zapewnić operator.

Zgodność

Stwierdzenie	Źródło	Klauzula	reference_id
Klient PSR-18 wysyła żądanie PSR-7, zwraca odpowiedź PSR-7	PSR-18 HTTP Client	§2
Wywołujący przekazuje nieescapowany ustrukturyzowany kontekst logu	PSR-3 Logger	§1.2

Przypinanie SPKI wg RFC 7469 określa postać używaną przez klucz konfiguracyjny tsa.pinned_public_keys. Pakiet wykorzystuje wartości pinów dostarczone przez operatora i sam nie implementuje tego RFC.

Kontekst komercyjny

Podpisywanie PAdES B-B oraz integracja z urzędem znacznika czasu wymagają nextpdf/premium. Ta opcjonalna funkcja Enterprise nie wymaga żadnych zmian w kodzie opisywanego tu pakietu Core. Zobacz https://nextpdf.dev/get-license/?intent=laravel-signing.

Zobacz także

/integrations/laravel/configuration/ — wszystkie klucze TSA, podpisu i kolejki
/integrations/laravel/production-usage/ — wzorce wstrzykiwania zależności (DI) i obsługi błędów
/integrations/laravel/troubleshooting/ — dlaczego kontrole ścieżki odrzucają dane wejściowe
/integrations/laravel/boot-and-discovery/ — czas życia powiązań w długo działających procesach roboczych