Beveiliging: versleuteling, crypto-beleid en ondertekeningsoppervlak

In een oogopslag

De Core-beveiligingsmodule past 256-bits Advanced Encryption Standard (AES-256)-documentversleuteling toe, laat elke algoritmekeuze via een crypto-beleidscontract lopen en biedt integratiepunten voor een door de implementatie beheerde key-managementservice. Effectieve documentbescherming hangt af van het sleutelbeheer, de wachtwoordsterkte, de lezende applicatie en de implementatieomgeving. Deze pagina maakt die grenzen expliciet.

Installatie

composer require nextpdf/core:^3

Conceptueel overzicht

De beveiligingsmodule kent drie oppervlakken. Het versleutelingsoppervlak gebruikt het documenttoegangspunt setEncryption() om de AES-256 Standard-securityhandler te configureren. De crypto-beleidspoort gebruikt CryptoPolicyInterface om te bepalen welke hash, handtekening, cipher en sleutelsterkte een implementatie toestaat. Het ondertekeningsoppervlak wordt hier genoemd, maar apart gedocumenteerd; zie Ondertekening.

Versleuteling gebruikt AES-256 zoals gedefinieerd in ISO 32000-2:2020 §7.6. Het standaardpad is de V=5 / R=6 Standard-securityhandler met het AESV3-cryptfilter. De bestandssleutel is 32 bytes (256 bits), wat overeenkomt met Federal Information Processing Standards (FIPS) 197. Een opt-in-pad voegt ISO/TS 32003:2023 V=6 / R=7 AES-256 in Galois/Counter Mode (AES-256-GCM) authenticated encryption toe. De uitgebreide pagina beschrijft beide paden: Versleuteling.

De crypto-beleidspoort is een predicaat dat toestaat of weigert. Core raadpleegt CryptoPolicyInterface vóór elke ondertekenings-, versleutelings- of hashingstap. Als er geen beleid is ingesteld, staat Core elk algoritme toe. Die open standaardinstelling is geschikt voor ontwikkeling, niet voor productie. Een gereguleerde implementatie moet een expliciet beleid instellen. Contracts / Security Policy documenteert het contractoppervlak.

Permissievlaggen zijn de meest voorkomende bron van overdreven claims, dus deze pagina is daar expliciet over. Het permissie-bitmasker wordt opgeslagen in de versleutelde /Perms-vermelding en de /P-waarde. Van een conforme lezer wordt verwacht dat deze die beperkingen respecteert. De vlaggen worden niet afgedwongen door cryptografie. Een processor die de bits negeert, kan inhoud nog steeds lezen, kopiëren of wijzigen zodra deze over de ontsleutelingssleutel beschikt. Maak deze beperking expliciet voor elke partij die op permissievlaggen vertrouwt.

Key-management en integratie met Public-Key Cryptography Standards #11 (PKCS#11) zijn contractpunten. Core levert een pad voor lokale sleutels. Het KeyMaterial-value-object omhult een sleutel van 256 bits waarvan de lengte is gecontroleerd en voorkomt blootstelling in string- en debuguitvoer. Het sleutelbewaringspad via hardware security module (HSM)/PKCS#11 is een Enterprise-functie die achter dezelfde contracten is afgeschermd; deze pagina benoemt het integratiepunt maar documenteert de Enterprise-implementatie niet.

API-oppervlak

Type	Soort	Belangrijkste leden	Stabiliteit	Sinds
Document::setEncryption()	methode (concern HasSecurity)	userPassword, ownerPassword, permissions	stabiel	1.0.0
Document::useAesGcm()	methode (concern HasSecurity)	?bool $enabled — opt-in ISO/TS 32003 V=6/R=7	stabiel	2.18.0
Aes256Encryptor	class	encrypt(), decrypt(), buildEncryptionDictionary(), verifyUserPassword(), verifyOwnerPassword(), validatePerms()	stabiel	1.0.0
Aes256GcmEncryptor	class	encrypt(), decrypt(), encryptStream(), assertWithinSafetyBound(), invocationCount()	stabiel	2.18.0
KeyMaterial	final readonly class	generate(), exposeKey(), fingerprint()	stabiel	2.18.0
CryptoPolicyInterface	interface	isHashAlgorithmAllowed(), isSignatureAlgorithmAllowed(), isEncryptionAlgorithmAllowed(), isKeyStrengthAllowed(), getPreferredHashAlgorithm(), getName()	stabiel	1.9.0
Config::withCryptoPolicy()	methode	CryptoPolicyInterface $policy	stabiel	1.9.0
CryptoCapabilities	final class	hasAesGcm(), detectFipsMode(), assertFipsAvailableForProfile()	stabiel	2.0.0

Codevoorbeeld — snelle start

examples/22-protection.php

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

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

// Call setEncryption() BEFORE addPage().
// Permission bit 3 (value 4) = printing allowed; all other operations denied.
$doc->setEncryption(
    userPassword: 'demo',
    ownerPassword: 'admin',
    permissions: 4,
);

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

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

Het gebruikerswachtwoord opent het document. Het eigenaarswachtwoord verleent volledige toegang. Permissievlaggen beperken alleen het gedrag van een conforme lezer.

Codevoorbeeld — productie

examples/security/policy-gated-encryption.php

<?php

declare(strict_types=1);

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

use NextPDF\Contracts\CryptoPolicyInterface;
use NextPDF\Core\Document;
use Psr\Log\LoggerInterface;

final readonly class PolicyGatedEncryption
{
    public function __construct(
        private CryptoPolicyInterface $cryptoPolicy,
        private LoggerInterface $logger,
    ) {}

    /**
     * Encrypt only when the active policy permits AES-256-CBC.
     *
     * @param non-empty-string $userPassword  Opens the document.
     * @param non-empty-string $ownerPassword Grants full access.
     */
    public function protect(
        Document $doc,
        string $userPassword,
        string $ownerPassword,
        int $permissions,
    ): void {
        if (!$this->cryptoPolicy->isEncryptionAlgorithmAllowed('aes-256-cbc')) {
            $this->logger->error('Encryption refused by crypto policy', [
                'policy' => $this->cryptoPolicy->getName(),
            ]);

            throw new \RuntimeException('AES-256-CBC denied by the active crypto policy.');
        }

        $doc->setEncryption($userPassword, $ownerPassword, $permissions);

        $this->logger->info('Document encrypted', [
            'policy' => $this->cryptoPolicy->getName(),
            'algorithm' => 'aes-256-cbc',
        ]);
    }
}

De poort controleert het beleid vóór de versleuteling, logt de beleidsnaam voor de audittrail en werpt een specifieke uitzondering wanneer het beleid de cipher weigert.

Randgevallen en valkuilen

• Roep setEncryption() vóór addPage() aan. Een latere aanroep versleutelt inhoud die de writer al heeft weggeschreven niet met terugwerkende kracht.
• De PDF/A-modus en versleuteling sluiten elkaar uit. ISO 19005 verbiedt in elke PDF/A-variant de Encrypt-sleutel in de trailer, dus setEncryption() en useAesGcm() werpen een uitzondering wanneer een PDF/A-manager actief is.
• Binnen setEncryption() valt een leeg eigenaarswachtwoord terug op het gebruikerswachtwoord. Een document met één gedeeld wachtwoord geeft degene met het gebruikerswachtwoord toegang op eigenaarsniveau.
• Wanneer er geen beleid wordt geïnjecteerd, staat CryptoPolicyInterface elk algoritme toe. Behandel de open standaardinstelling als een ontwikkelgemak en stel een expliciet beleid in bij elke gereguleerde implementatie.
• Permissievlaggen zijn adviserend voor de lezer. Beschrijf ze niet als toegangscontrole die een kwaadwillende processor niet kan omzeilen.

Prestaties

setEncryption() voert tijdens de opbouw van het document een geïtereerde sleutelafleidingsroutine uit (Algorithm 2.B, revisie 6). De kosten zijn begrensd en constant per document; ze schalen niet mee met het aantal pagina’s. Bij versleuteling per object wordt één AES-bewerking per stream of string uitgevoerd. Het opt-in-pad voor AES-256-GCM voegt 28 bytes overhead per object toe (12-byte initialization vector (IV) plus 16-byte tag) en streamt grote inhoud in chunks van 16 MiB. Daardoor blijft de streaming-pass onder de gedocumenteerde piek van 64 MB. Het performance_budget van 1500 ms wall en 64 MB piek wordt bepaald door documentweergave, niet door versleuteling.

Beveiligingsnotities

Het dreigingsmodel is expliciet. De crypto-beleidspoort beperkt algoritmedowngrades door zwakke ciphers, zwakke hashes en korte sleutels vóór elke bewerking te weigeren. De engine vervangt een gevraagde primitive niet stilzwijgend door een zwakkere wanneer deze ontbreekt; in plaats daarvan werpt de engine een uitzondering zodat de operator kan ingrijpen. KeyMaterial beperkt sleutelblootstelling in logs: de string- en debugvormen redigeren de bytes en tonen alleen een niet-omkeerbare fingerprint. Manipulatie van ciphertext wordt alleen gedetecteerd op het opt-in-AES-256-GCM-pad, waar de authenticatietag wordt geverifieerd en een mismatch een uitzondering oplevert in plaats van plaintext terug te geven. Het standaardpad voor AES-256 Cipher Block Chaining (AES-256-CBC) biedt alleen vertrouwelijkheid en detecteert op zichzelf geen wijzigingen. Op het GCM-pad wordt IV-hergebruik beperkt met een monotone teller plus een defense-in-depth-collisieset, in lijn met de unieke-IV-vereiste in NIST SP 800-38D §8.

De grenzen zijn even expliciet. AES-256-versleuteling wordt toegepast zoals gedefinieerd in ISO 32000-2:2020 §7.6. Effectieve bescherming hangt af van de wachtwoordsterkte, het sleutelbeheer, de implementatieomgeving en de lezende applicatie. Conforme lezers respecteren permissievlaggen, maar cryptografie dwingt ze niet af. De FIPS-modusprobe rapporteert of de host-OpenSSL-build een FIPS-provider heeft geladen. De bibliotheek werkt in een FIPS-compatibele modus wanneer de host een gevalideerde module levert; ze certificeert zelf geen module. NIST SP 800-57 Part 1 §4 behandelt sleutellevensduur en cryptoperiode als verantwoordelijkheden van de implementatie. Core stelt de besturingselementen beschikbaar; de implementatie bepaalt het rotatiebeleid.

Dataresidentie en PII-mitigaties

Het versleutelingsoppervlak verzendt geen documentbytes off-host, inclusief eventuele personally identifiable information (PII) die ze bevatten. Sleutelafleiding, versleuteling en ontsleuteling draaien in-process. Het opt-in-GCM-pad indexeert een in-memory IV-collisieset op een niet-omkeerbare sleutel-fingerprint, niet op sleutelbytes. De beveiligingsmodule schrijft geen wachtwoord- of sleutelwaarden naar schijf. Een implementatie die sleutels via een externe key-managementservice leidt, is verantwoordelijk voor de dataresidentie van die service.

Veilige telemetrie en logscrubbing

KeyMaterial::__toString() en __debugInfo() geven een geredigeerde placeholder terug, zodat een onbedoelde log van een sleutelobject een fingerprint oplevert, geen sleutelbytes. Wachtwoorden die aan setEncryption() worden doorgegeven, dragen het #[\SensitiveParameter]-attribuut, waardoor ze uit stack traces worden geredigeerd. Gebruik voor audits de beleidsnaam uit CryptoPolicyInterface::getName() en de sleutel-fingerprint van 8 tekens als identificatoren voor de crypto-bewerking. Log die waarden, nooit de sleutel of het wachtwoord.

Dreigingsmodel

Dreiging	Mitigatie in Core	Resterende grens
Algoritmedowngrade / vervanging door een zwakke cipher	Crypto-beleidspoort; geen stilzwijgende degradatie (werpt UnsupportedAlgorithmException)	Alleen effectief wanneer er een beleid is geïnjecteerd
Sleutelblootstelling via logs	KeyMaterial-redactie; #[\SensitiveParameter] op wachtwoorden	Een aanroeper die exposeKey() aan een logger doorgeeft, ondermijnt dit
Manipulatie van ciphertext	GCM-tagverificatie op het opt-in-pad	Het standaard-CBC-pad biedt alleen vertrouwelijkheid
IV-hergebruik (GCM)	Monotone teller plus collisieset; weigert bij overloop	—
Omzeiling van permissievlaggen	Geen; vlaggen zijn adviserend	Een niet-conforme lezer negeert de vlaggen
Brute-force op een zwak wachtwoord	SASLprep plus geïtereerde sleutelafleiding verhogen de kosten	Een zwak wachtwoord blijft het dominante risico

FIPS-modusgedrag

Core is geen FIPS-gevalideerde cryptografische module en is niet FIPS-gecertificeerd. CryptoCapabilities::detectFipsMode() is een best-effort runtime-probe: deze leest een operator-override, vervolgens de OpenSSL-providerlijst, daarna de legacy-FIPS-modusaanroep, en rapporteert active, absent of indeterminate. assertFipsAvailableForProfile() faalt gesloten wanneer een FIPS-profiel wordt geselecteerd op een host die geen FIPS-provider kan aantonen. De bibliotheek werkt in een FIPS-compatibele modus wanneer ze is geconfigureerd met een host-OpenSSL-build die een FIPS-gevalideerde provider heeft geladen. Een gevalideerde, gecertificeerde FIPS-status is een Enterprise-aangelegenheid; zie de Enterprise-documentatie.

Conformiteit

Claim	Standaard	Clausule	Bewijs
Het GCM-pad houdt elke IV per invocatie uniek, in lijn met de uniciteitsvereiste van de standaard.	NIST SP 800-38D	§8.2.1
Core stelt besturingselementen beschikbaar voor sleutellevensduur en cryptoperiode; de implementatie is eigenaar van het beleid.	NIST SP 800-57 Part 1 Rev. 5	§4
De AES-bestandssleutel is 256 bits, wat overeenkomt met de sleutellengte van de standaard.	FIPS 197	§4.2.1
Token-residente sleutelgeneratie is het integratiepunt voor een externe sleutelopslag.	OASIS PKCS#11 v3.1	C_GenerateKey

ISO 32000-2:2020 §7.6 is de normatieve basis voor de Standard-securityhandler. De tekst ervan is licentiebeperkt en wordt hier geparafraseerd, nooit geciteerd; deze pagina verwijst naar de clausule aan de hand van het nummer. Elk punt hierboven is geparafraseerd uit de geciteerde standaard.

Commerciële context

Core definieert en bevriest het crypto-beleidscontract, levert het AES-256-versleutelingspad en biedt een oppervlak voor lokale sleutels. De Enterprise-editie levert een sleutelbewaringspad via HSM/PKCS#11 en een FIPS-modus-crypto-beleidsprofiel achter dezelfde CryptoPolicyInterface. Het contractoppervlak is identiek voor alle edities; de implementatie injecteert een andere beleidsimplementatie en sleutelbewaringsbackend.

Zie ook

• Security / Encryption — de uitgebreide referentie voor AES-256 en AES-256-GCM.
• Contracts / Security Policy — de crypto-beleids- en resource-beleidscontracten.
• Security / Signing — PDF Advanced Electronic Signatures (PAdES), Cryptographic Message Syntax (CMS) en timestamps.
• Audit — audit-logging van beleidsnaam en bewerkingen.
• Conformance — interactie van PDF/A met versleuteling.