Beveiliging en beheer van het NextPDF Laravel-pakket

In het kort

Het pakket stelt vaste Portable Document Format (PDF)-responseheaders in, schoont downloadbestandsnamen op, valideert queue-uitvoerpaden op de worker en stuurt Hypertext Transfer Protocol (HTTP)-aanroepen naar de timestamp-autoriteit via een client die request forgery herkent. Deze pagina licht het dreigingsmodel toe en beschrijft de deploymentconfiguratie die elke maatregel vereist.

Installeren

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

Conceptueel overzicht

Het pakket maakt een PDF-engine geschikt voor een webframework. Het HTTP-verzoek en het queue-transport vormen de vertrouwensgrens. Deze maatregelen richten zich op responseafhandeling, gedeserialiseerde job-payloads en uitgaand HTTP-verkeer naar een timestamp-autoriteit.

API-oppervlak — dreigingsmodel

Asset	Dreiging	Maatregel in dit pakket	Vereiste deploymentconfiguratie
PDF HTTP-response	Content-type sniffing, clickjacking, indexering	Vaste headerset op elke `PdfResponse`-factory	Geen; de headers zijn niet configureerbaar
Downloadbestandsnaam	Header injection, path traversal in `Content-Disposition`	Bestandsnaam-sanitizer verwijdert padscheidingstekens, stuurtekens en null-bytes	Geen; de sanitizer draait altijd
Uitvoerpad van queue-job	Schrijven naar een willekeurig bestand via een gemanipuleerde geserialiseerde payload	Pad wordt gevalideerd in `handle()` op de worker	Stuur de uitvoer naar een gecontroleerd opslagpad
Uitgaand HTTP naar timestamp-autoriteit (TSA)	Server-side request forgery, manipulatie van platte tekst	HTTP-client die request forgery herkent; HTTPS wordt afgedwongen tenzij dit expliciet wordt versoepeld	Houd `tsa.allow_insecure_http = false`; pin de Subject Public Key Info (SPKI)
Gedeelde worker-status	Statuslekken tussen verzoeken in langlevende workers	Vergrendeld lettertyperegister; begrensde afbeeldingscache; aan de factory gebonden document	Stel `preload_fonts` in; begrens het geheugen van de container

Hardening van responses

Elke PdfResponse-factory stelt deze vaste headerset in:

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

Deze waarden zijn constanten in PdfResponse. Ze zijn niet configureerbaar. De testsuite van het pakket controleert elke header op elke factory-methode, inclusief de gestreamde varianten.

De downloadbestandsnaam wordt door een sanitizer gehaald voordat deze de Content-Disposition-header bereikt. De sanitizer verwijdert padscheidingstekens, stuurtekens en null-bytes, en voegt voor niet-ASCII-namen een Request for Comments (RFC) 5987 filename*=-parameter toe. Een lege bestandsnaam wordt document.pdf.

Validatie van queue-payloads

GeneratePdfJob serialiseert een closure naar het queue-transport. De worker valideert het uitvoerpad in handle(), niet bij dispatch. De validatie weigert:

null-bytes in het pad,
stream-wrapper-schema’s (bijvoorbeeld php://),
.. path-traversal-segmenten,
elk pad dat niet eindigt op .pdf (hoofdletterongevoelig).

Elke weigering resulteert in InvalidArgumentException. De validatie draait wanneer de worker de job verwerkt. Een geserialiseerde payload in een Redis- of database-transport kan worden gewijzigd voordat de worker deze leest. Gebruik voor het uitvoerpad een gecontroleerde opslagmap; leid het niet af uit niet-gevalideerde verzoekinvoer.

Uitgaand HTTP naar een timestamp-autoriteit

Wanneer een timestamp-autoriteit is geconfigureerd, bindt het pakket een PHP Standard Recommendation (PSR)-18 Psr\Http\Client\ClientInterface. Een PSR-18-client verstuurt een PSR-7-verzoek en geeft een PSR-7-response terug (PSR-18 §2). De gebonden client omhult een op curl gebaseerde client met een laag die request forgery herkent. Die laag dwingt HTTPS af tenzij tsa.allow_insecure_http expliciet true is.

De timestamp-autoriteit is een Premium-functie. Het hier gedocumenteerde Core-pakket bindt de HTTP-client en verzorgt de aansluiting van de timestamp-client; het ondertekenen zelf vereist nextpdf/premium. Deze pagina documenteert geen baselinegedrag van PDF Advanced Electronic Signatures (PAdES) verder dan B-B; hogere baselines vallen buiten het bereik.

Operationele richtlijnen voor de timestamp-autoriteit:

Laat tsa.allow_insecure_http in productie op false staan.
Stel tsa.pinned_public_keys in op de base64 SHA-256 SPKI-hashes van het certificaat van de timestamp-autoriteit (RFC 7469-indeling).
Laat tsa.warn_on_key_rotation op true staan, zodat een gewijzigde SPKI wordt gelogd voordat het gepinde certificaat verloopt.
Haal tsa.url uitsluitend uit vertrouwde configuratie. Als een beheerder dit via een admininterface kan instellen, pas dan een egress-firewall of DNS-beleid toe om het risico op request forgery te beperken.

Logging

Gebruik Psr\Log\LoggerInterface voor diagnostiek. Geef gestructureerde context door, geen geïnterpoleerde strings. PSR-3 laat het escapen van placeholders over aan de logger-implementatie en schrijft aanroepers voor om contextwaarden niet vooraf te escapen (PSR-3 §1.2). Log de exception-klasse, niet het bericht of de trace, om interne details in logs te beperken.

Codevoorbeeld — productie

<?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
        ],
    ],
];

Randgevallen en valkuilen

De responseheaderset ligt vast. Applicaties die een ander Content Security Policy (CSP) nodig hebben, moeten de response nabewerken nadat de factory deze heeft teruggegeven.
De padvalidatie draait op de worker. Een ongeldig pad passeert dispatch() en faalt pas wanneer de job wordt uitgevoerd.
tsa.allow_insecure_http = true schakelt de HTTPS-afdwinging uit en verzwakt het vertrouwen in de timestamp. Beperk dit tot lokale ontwikkeling.
Het lettertyperegister wordt na de warmup vergrendeld; het pakket weigert pogingen om tijdens runtime een lettertype te registreren in een langlevende worker, en dat is opzettelijk.

Prestaties

De beveiligingsmaatregelen gebruiken string- en array-bewerkingen met constante looptijd en voegen geen meetbare kosten per verzoek toe. Het parsen van lettertypes bij het eerste gebruik is de grootste operationele kostenpost; laad lettertypes vooraf bij het opstarten van de worker om latentie bij het eerste verzoek te voorkomen.

Beveiligingsnotities

Deze pagina is de referentie voor het dreigingsmodel van het pakket. De broncode dwingt deze maatregelen af en de testsuite controleert ze. De dreigingsmodeltabel en de stappen voor de timestamp-autoriteit beschrijven de deploymentconfiguratie die de beheerder moet aanleveren.

Conformiteit

Bewering	Bron	Clausule	reference_id
PSR-18-client verstuurt een PSR-7-verzoek en geeft een PSR-7-response terug	PSR-18 HTTP Client	§2
Aanroeper geeft niet-geëscapete, gestructureerde logcontext door	PSR-3 Logger	§1.2

RFC 7469 SPKI-pinning beschrijft de vorm die de configuratiesleutel tsa.pinned_public_keys gebruikt. Het pakket verwerkt door de beheerder aangeleverde pinwaarden en implementeert de RFC niet zelf.

Commerciële context

PAdES B-B-ondertekening en integratie met een timestamp-autoriteit vereisen nextpdf/premium. Deze optionele Enterprise-functie vereist geen codewijziging in het hier gedocumenteerde Core-pakket. Zie https://nextpdf.dev/get-license/?intent=laravel-signing.

Zie ook

/integrations/laravel/configuration/ — elke TSA-, handtekening- en queue-sleutel
/integrations/laravel/production-usage/ — patronen voor dependency injection (DI) en foutafhandeling
/integrations/laravel/troubleshooting/ — waarom de padcontroles invoer weigeren
/integrations/laravel/boot-and-discovery/ — bindinglevensduur in langlevende workers