Core / HasSecurity-Trait

Auf einen Blick

HasSecurity ist das Concern-Trait für den Dokumentenschutz. Es steuert AES-256-Verschlüsselung, Zugriffsberechtigungen, getaggtes PDF und die Übergabe an die digitale Signatur.

Installation

composer require nextpdf/core:^3

Konzeptioneller Überblick

trait HasSecurity liegt in src/Core/Concerns/HasSecurity.php. Es wird in Document eingebunden. Das Trait ergänzt die Fassade um Methoden für Verschlüsselung, Signatur, PDF/A und getaggtes PDF.

Rufen Sie setEncryption() auf, um ein Dokument zu sperren. Die Methode nimmt ein Benutzerkennwort, ein optionales Besitzerkennwort und eine Berechtigungs-Bitmaske entgegen. Mit dem Benutzerkennwort lässt sich das Dokument öffnen. Das Besitzerkennwort gewährt vollen Zugriff. Ist das Besitzerkennwort leer, verwendet die Engine erneut das Benutzerkennwort. Die Standardchiffre ist AES-256.

Gehen Sie für eine strikte Berechtigungssteuerung wie folgt vor:

1. Wählen Sie die Berechtigungs-Bits aus, die Sie erlauben.
2. Rufen Sie setEncryption() auf, bevor Sie eine Seite hinzufügen.
3. Fügen Sie Seiten und Inhalt hinzu.

Die Berechtigungs-Bits richten sich nach ISO 32000-2:2020 Tabelle 22. Bit 3 erlaubt das Drucken. Bit 4 erlaubt Inhaltsänderungen. Bit 5 erlaubt die Textextraktion. Bit 6 erlaubt Änderungen an Anmerkungen und Formularen.

Der PDF-Sicherheits-Handler berechnet einen Dateiverschlüsselungsschlüssel (ISO 32000-2:2020 §7.6.2). Der V-Code im Verschlüsselungsdictionary wählt den Algorithmus aus. Ältere niedrigere V-Werte sind in PDF 2.0 veraltet. NextPDF gibt den modernen AES-256-Handler aus. Ein PDF-Reader prüft das übergebene Kennwort gegen den Dictionary-Eintrag U (§7.6.4).

useAesGcm() aktiviert die AES-256-GCM-Massenverschlüsselung nach ISO/TS 32003:2023. Dieser Modus ist standardmäßig deaktiviert. Bestehende Aufrufer erhalten weiterhin die bytegenau identische AES-256-CBC-Ausgabe. Die Methode verweigert die Ausführung, wenn der PDF/A-Modus aktiv ist. Sie verweigert die Ausführung außerdem, wenn der Host AES-GCM nicht unterstützt.

setSignature() konfiguriert eine PAdES-Signatur. Die Methode nimmt ein Zertifikat, eine Signaturstufe und einen optionalen Zeitstempel-Client entgegen. Die Signierung muss vor der Linearisierung erfolgen. setEncryption() akzeptiert ein #[SensitiveParameter]-Kennwort, sodass der Wert nicht in Stacktraces erscheint.

enableTaggedPdf() baut den Strukturbaum für PDF/UA-2 auf. Die Methode nimmt ein BCP-47-Sprach-Tag entgegen. Der strikte Modus validiert das Tag an der API-Grenze. Bei einem fehlerhaften Tag wird InvalidConfigException geworfen. enablePdfA() aktiviert den PDF/A-Archivmodus. enableLinearization() erzeugt eine linearisierte Datei.

API-Oberfläche

Symbol	Art	Stabilität	Seit
setEncryption(string, string, int): static	Methode	stabil	1.2.0
getEncryptor(): ?Aes256Encryptor	Methode	stabil	1.2.0
useAesGcm(?bool): static	Methode	stabil	1.4.0
setPublicKeyEncryption(...): static	Methode	stabil	1.2.0
setSignature(CertificateInfo, SignatureLevel, ?TsaClient): static	Methode	stabil	1.2.0
enablePdfA(?object): static	Methode	stabil	1.2.0
enableTaggedPdf(string, ?ConformancePolicy): static	Methode	stabil	1.0.0
setConformanceMode(ConformanceMode): static	Methode	stabil	2.8.0
useDocumentMac(?bool): static	Methode	stabil	1.4.0
enableLinearization(): static	Methode	stabil	1.2.0

Codebeispiel — Schnellstart

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Encrypted Document — Restricted Permissions');
$doc->setAuthor('NextPDF Example');

// Enable AES-256 encryption BEFORE adding any pages.
$doc->setEncryption(
    userPassword: 'demo',
    ownerPassword: 'admin',
    permissions: 4, // 4 = allow printing only
);

$doc->addPage();
$doc->setFont('helvetica', 'B', 20);
$doc->cell(0, 14, 'Encrypted PDF Document', newLine: true);

$doc->save(__DIR__ . '/output/22-protection.pdf');

Quelle: examples/22-protection.php.

Codebeispiel — Produktion

Aktivieren Sie AES-256-GCM. Aktivieren Sie anschließend getaggtes PDF für die Barrierefreiheit.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Protected and Tagged');

$doc->setEncryption(userPassword: 'open-me', permissions: 4);
$doc->useAesGcm(true);
$doc->enableTaggedPdf('en');

$doc->addPage();
$doc->setFont('helvetica', '', 12);
$doc->cell(0, 10, 'AES-256-GCM encrypted and PDF/UA-2 tagged.', newLine: true);

$doc->save(__DIR__ . '/output/protected-tagged.pdf');

Quelle: zusammengestellt aus examples/22-protection.php und examples/31-pdfua2-tagged.php.

Grenzfälle & Stolperfallen

• Rufen Sie setEncryption() vor dem ersten addPage() auf. Ein späterer Aufruf wirkt sich nicht auf bereits geschriebene Seiten aus.
• useAesGcm(true) wirft eine Ausnahme, wenn der PDF/A-Modus aktiv ist. ISO 19005 verbietet den Trailer-Schlüssel Encrypt.
• useAesGcm(true) wirft eine Ausnahme, wenn der Host keine AES-GCM-Chiffre bereitstellt. Installieren Sie ext-sodium oder aktualisieren Sie OpenSSL.
• setSignature() ist nicht mit der Linearisierung kompatibel. Konfigurieren Sie die Signatur, bevor Sie die Linearisierung aktivieren.
• Ein leeres Besitzerkennwort verwendet erneut das Benutzerkennwort. Setzen Sie ein eigenes Besitzerkennwort für echte Zugriffssteuerung.

Performance

Die Verschlüsselung fügt für jeden Objektkörper einen Chiffrierdurchlauf hinzu. AES-256-CBC und AES-256-GCM laufen beide in O(Inhalts-Bytes). Im Vergleich zum Layout sind die Kosten gering. Das Seitenbudget beträgt 1500 ms / 64 MB für den kanonischen Schnellstart.

Sicherheitshinweise

Das Benutzerkennwort und das Besitzerkennwort sind mit dem Attribut #[SensitiveParameter] versehen. PHP schwärzt sie in Stacktraces. Die Engine protokolliert niemals Kennwortwerte. Die Berechtigungs-Bitmaske wird im Dokumentmodell für den Writer bereitgestellt. Sie wird nicht erneut aus dem privaten Chiffrierzustand gelesen.

Datenresidenz & PII-Maßnahmen

NextPDF läuft in Ihrem Prozess. In Core führt es keinen Netzwerkaufruf für Verschlüsselungs- oder Signaturschlüsselmaterial aus. Kennwörter bleiben im Prozessspeicher. Sie werden nicht auf die Festplatte geschrieben. Zeitstempel- und HSM-Aufrufe sind Pro- und Enterprise-Funktionen. Diese Funktionen führen explizite Netzwerkaufrufe aus. Core tut das nicht.

Sichere Telemetrie & Log-Bereinigung

Core sendet standardmäßig keine Telemetrie. Warnungen laufen über den WarningCollector. Kennwortwerte gelangen niemals in eine Warnmeldung. Eine Warnung benennt den Konfigurationsschlüssel, nicht den geheimen Wert. Fügen Sie das Kennwort nicht zu einer eigenen Log-Zeile hinzu.

Bedrohungsmodell

Die Hauptbedrohung ist die String-Injektion in den Content-Stream über Benutzertext. Die Engine maskiert jeden Textstring, bevor er in den Stream gelangt. Die Maskierungstabelle deckt die Grenze zwischen PDF-Literal-String und Hex-String gemäß ISO 32000-2:2020 §7.3.4.2 ab. Eine zweite Bedrohung ist ein unvollständiger Dateischreibvorgang während der Ausgabe. HasOutput::save() verwendet einen atomaren Schreibvorgang. Ein Reader sieht entweder die alte oder die neue Datei, niemals eine unvollständige Datei. Eine dritte Bedrohung ist eine schwache Chiffre. NextPDF gibt AES-256 aus und stuft den älteren RC4-Pfad als veraltet ein.

Verhalten im FIPS-Modus

Config akzeptiert ein CryptoPolicyInterface. Eine FIPS 140-3-Policy kann die Chiffrenauswahl einschränken. Wenn dem Host ein zugelassener AES-GCM-Provider fehlt, wirft useAesGcm(true) eine Ausnahme, statt auf einen anderen Modus zurückzufallen. Dieses Fail-closed-Verhalten hält das Dokument innerhalb der konfigurierten Policy.

Konformität

Aussage	Quelle	Klausel	reference_id
Der Sicherheits-Handler berechnet den Dateiverschlüsselungsschlüssel; V wählt den Algorithmus aus	ISO 32000-2:2020	§7.6.2
Der V-Code wählt den Verschlüsselungsalgorithmus aus; ältere V-Werte sind in PDF 2.0 veraltet	ISO 32000-2:2020	§7.6.2
Das Benutzerkennwort wird gegen den Eintrag U geprüft	ISO 32000-2:2020	§7.6.4

Die Klauseln sind paraphrasiert. Es wird kein normativer Text wiedergegeben.

Siehe auch

• /modules/core/core/document-facade/ — die Fassade, die dieses Trait zusammensetzt; strictPdf20FontEmbedding() Font-Policy
• /modules/core/core/ — Core-Überblick: Verschlüsselung und Signatur sind optionale Erweiterungen
• /modules/core/security/ — die Verschlüsselungs- und Signatur-Engine, an die HasSecurity delegiert
• /modules/core/core/has-output/ — HasOutput: atomarer Schreibvorgang, der das TOCTOU-Fenster bei der Ausgabe schließt
• /modules/core/contracts/ — CryptoPolicyInterface (FIPS 140-3-Policy-Hook)
• /modules/core/exception/ — InvalidConfigException und IncompatiblePdfAModeException werden hier geworfen
• /modules/core/conformance/ — PDF/A- und PDF/UA-Konformitätsmodi, die von enablePdfA()/enableTaggedPdf() referenziert werden <!— evidence: src/Core/Concerns/HasSecurity.php (trait HasSecurity @since 1.2.0; setEncryption(#[SensitiveParameter]string userPassword,#[SensitiveParameter]string ownerPassword=”,int permissions=-1):static — empty owner reuses user, surfaces encryptionPermissions on DocumentData, validateNoEncryption when pdfaManager set; getEncryptor():?Aes256Encryptor; useAesGcm(?bool=true) @since 1.4.0 — throws IncompatiblePdfAModeException when PDF/A active, InvalidConfigException when no AES-GCM, ISO/TS 32003:2023 §5.1/§5.2; setSignature(CertificateInfo,SignatureLevel=PAdES_B_B,?TsaClient) throws when linearize set; setPublicKeyEncryption ISO §7.6.5; enablePdfA; enableTaggedPdf(string=‘en’,?ConformancePolicy) @since 1.0.0 — Bcp47Validator strict gate throws InvalidConfigException, ISO 14289-2:2024 §8.4.4; setConformanceMode @since 2.8.0; useDocumentMac @since 1.4.0 ISO/TS 32004:2024; enableLinearization); src/Core/Document.php escapeTextForStream ISO §7.3.4.2; src/Core/Config.php cryptoPolicy CryptoPolicyInterface (FIPS 140-3); src/Core/Concerns/HasOutput.php atomic save; examples/22-protection.php (verbatim quick-start, Table 22 permission bits), examples/31-pdfua2-tagged.php; glossary FIPS 140-3/PAdES. RAG iso32000_2_sec7 §7.6.2 /fb39b318, §7.6.4 >