Ga naar inhoud
getnextpdf.com

Enterprise editie

Security — Diepe referentie (HSM, PKCS#11, FIPS-modus)

Deze pagina is de gecombineerde diepe referentie voor het NextPDF Enterprise-beveiligingsoppervlak. Ze behandelt hardwaretoken-ondertekening via PKCS#11, subprocess-ondertekening via de OpenSSL-command-line-interface (CLI), de FIPS-crypto-beleidspresets, de runtime-FIPS-bewaking en de power-on-zelftestbewaking. Er bestaan twee gerichte begeleiders: HSM — Diepe referentie voor het detail van de ondertekenaar en FIPS 140 — Diepe referentie voor het detail van de FIPS-module. Het post-quantum-ondertekeningspad is een preview zonder conformiteitsclaim. NextPDF houdt geen certificering aan en verleent er geen; ondersteuning staat niet gelijk aan conformiteit, en conformiteit staat niet gelijk aan certificering.

Deze functionaliteit wordt geleverd in NextPDF Enterprise (nextpdf/enterprise) en activeert met een licentie-envelop op Enterprise-niveau. Een deployment zonder die rechten laadt de klassen van de functionaliteit niet. Vergelijk edities en verkrijg een licentie.

Terminal window
composer require nextpdf/enterprise:^3

De ondertekeningstypes leven in NextPDF\Enterprise\Security\Signature\Hsm; de FIPS-types leven in NextPDF\Enterprise\Security\Fips; de compositie-root leeft in NextPDF\Enterprise\Bootstrap. Beide ondertekenaars implementeren het Core-contract NextPDF\Contracts\HsmSignerInterface. Het beleid implementeert de Core-contracten NextPDF\Contracts\CryptoPolicyInterface en NextPDF\Contracts\PreOperationalSelfTestInterface.

SymboolParametersStandaardgedragRetourneertWerpt of faalt metOpmerkingen
Pkcs11Signer::__construct()string $libraryPath, int $slotId, string $pin, string $certLabel, ?string $keyLabel = null, array $chainDer = [], bool $enablePostQuantum = false, ?FipsSignatureEnforcer $fipsEnforcer = nullOpent de leveranciersbibliotheek, logt in op het slot, laadt certificaat- en sleutelalgoritme-metadataHsmOperationException wanneer ext-pkcs11 ontbreekt of tokentoegang faaltPIN en labels zijn #[SensitiveParameter]; één modulehandle wordt per bibliotheekpad per proces gecachet
Pkcs11Signer::isAvailable()GeenRapporteert of ext-pkcs11 geladen isboolGeenStatisch; controleer vóór constructie
Pkcs11Signer::sign()string $data, string $algorithm = 'sha256WithRSAEncryption'Ondertekent op het token; ruwe ECDSA-uitvoer wordt omgezet naar DER ECDSA-Sig-Valuestring ruwe handtekeningbytesHsmOperationException (sleutel niet gevonden, tokenfout); InvalidArgumentException (niet-gemapt algoritme); FipsViolationException / FipsModuleErrorStateException vóór het ondertekenen wanneer een enforcer is bekabeldGesloten algoritmeset; zie Gedragscontract
Pkcs11Signer::signPqs()string $data, Pkcs11PqsAlgorithm $algorithm, string $context = '', bool $randomized = trueGeweigerd tenzij $enablePostQuantum was gezet; verstuurt het voorlopige PKCS#11-post-quantum-mechanismestring ruwe handtekeningbytesHsmOperationException (uitgeschakeld, tokenfout, handtekeninglengte-mismatch); InvalidArgumentException (context boven 255 bytes)Preview; geen conformiteitsclaim
Pkcs11Signer accessor-oppervlakGeenAlleen-lezen constructieresultatenbool / string / array<string>GeenisPostQuantumEnabled, getCertificateDer, getCertificateChainDer, getPublicKeyAlgorithm
OpenSslCliSigner::__construct()string $keyUri, string $certPath, string $pin, array $extraCertPaths = [], OpenSslCliBackend $backend = OpenSslCliBackend::Auto, string $opensslBinary = 'openssl', int $timeoutSeconds = 30, ?string $modulePath = null, ?string $configPath = null, bool $legacyPinDelivery = false, ?FipsSignatureEnforcer $fipsEnforcer = nullVerifieert proc_open, sondeert de binary, resolveert de backend, laadt de certificatenHsmOperationException (proc_open uitgeschakeld, ontbrekend module-/config-/certificaatbestand, geen backend); InvalidArgumentException (pin-value in $keyUri)Auto geeft de voorkeur aan de OpenSSL 3.x-provider, daarna de engine
OpenSslCliSigner::sign()string $data, string $algorithm = 'sha256WithRSAEncryption'Ondertekent in een openssl-subprocess; de PIN reist standaard via een kortstondig 0600-pin-source-bestandstring ruwe handtekeningbytesHsmOperationException (timeout, PIN geweigerd, sleutel niet gevonden, lege uitvoer); InvalidArgumentException (niet-gemapt algoritme); FIPS-poort-excepties vóór het ondertekenenHet subprocess wordt na $timeoutSeconds beëindigd; stderr wordt geredigeerd
OpenSslCliSigner accessor-oppervlakGeenAlleen-lezen constructieresultatenstring / array<string> / OpenSslCliBackendGeengetCertificateDer, getCertificateChainDer, getPublicKeyAlgorithm, getCertificatePem, getResolvedBackend, getOpensslVersion
OpenSslCliBackendEnum: Provider, Engine, AutoGeenBackend-selectie voor de CLI-ondertekenaar
Pkcs11PqsAlgorithmEnum van ML-DSA- en SLH-DSA-parametersetsGeenHelpers: isMlDsa, isSlhDsa, mechanismId, parameterSetId, signatureLength, nistCategory
PqsCapabilityStatus::current()GeenBouwt de eerlijke post-quantum-positie voor het procesPqsCapabilityStatusGeenElke conformiteitsclaim-boolean is hard-coded false; geen enkele vlag kan er een omzetten naar aan
HsmSignerProviderAdapterHsmSignerInterface $hsm, string $providerId, SignatureAlgorithm $algorithm = SignatureAlgorithm::Pkcs1v15Stelt een HSM-concreet bloot als een uniform SignerProviderInterfacePer SPIKeyManagementException (niet-null sleutelversie); SignatureFailedException (driverfout, lege handtekening)Provider-id’s: pkcs11-{module-id}, openssl-cli
HsmOperationExceptionGetypeerde fout voor elk HSM-ondertekeningspadBreidt de Core-NextPdfException uit
FipsCryptoPolicy::strict() / ::standard()?FipsSelfTest $selfTest = nullFabriekspresets; strict is het FIPS 140-3-profiel, standard voegt AES-128-CBC toeFipsCryptoPolicyGeenOnveranderlijke allow-lists; zie FIPS-modusgedrag
FipsCryptoPolicy predicaat-oppervlakstring / int invoerAllow-list-lidmaatschapscontrolesbool / stringGeenisHashAlgorithmAllowed, isSignatureAlgorithmAllowed, isEncryptionAlgorithmAllowed, isKeyStrengthAllowed, getPreferredHashAlgorithm, getName
FipsCryptoPolicy::assertPreOperational()GeenVoert de power-on-zelftest uit (of speelt die opnieuw af)voidFipsModuleErrorStateExceptionAangedreven door de Core-handhavingsnaad bij de eerste cryptografische bewerking
FipsModeGuard::__construct()CryptoPolicyInterface $policy, ?FipsBootGuard $bootGuard = null, ?FipsAuditLogger $auditLogger = nullOmhult een beleid met assert-stijl-grenzenGeenZonder een boot-guard ontbreekt de zelftestpoort (alleen-beleid)
FipsModeGuard assert-oppervlakstring / int invoerEerst de deny-catalogus, daarna de allow-list; auditrecord vóór elke throwvoidFipsViolationException; FipsModuleErrorStateException (boot-guard bekabeld)assertHashAllowed, assertSignatureAlgorithmAllowed, assertEncryptionAllowed, assertKeyStrengthAllowed, plus getPolicy
FipsBootGuard::report() / ::rerun()GeenVoert de zelftestbatterij uit (gecachet / geforceerd)FipsSelfTestReportGeenEen ERROR-rapport vergrendelt het proces; een geslaagde re-run heft de vergrendeling nooit op
FipsBootGuard::assertOperational()GeenAsserteert dat de module OPERATIONAL isvoidFipsModuleErrorStateExceptionKleverig: een proces-vergrendelde ERROR weigert zelfs een schone instantie
FipsBootGuard::status()GeenRapporteert de gecachete statusFipsSelfTestStatusGeenPRE_OPERATIONAL, OPERATIONAL of ERROR
FipsSelfTest::run()GeenVoert de volledige known-answer-test-batterij uit; kortsluit nooitFipsSelfTestReportGeenDe constructor accepteert injecteerbare hash- en random-bytes-providers voor deterministische tests
FipsSelfTestReport / FipsSelfTestResult / FipsSelfTestStatusRapport-value-objects en status-enumFipsSelfTestReport::assertOperational() werpt FipsModuleErrorStateExceptionresults somt altijd elke uitkomst op als auditbewijs
FipsSignatureEnforcer::assertSignatureGenerationAllowed()string $algorithm, string $certificatePemResolveert de handtekening-OID en de sleutelsterkte, delegeert daarna aan de guardvoidFipsViolationException (niet-toegestaan of niet-classificeerbaar, fail-closed)Het knelpunt dat beide ondertekenaars bovenaan sign() aanroepen in FIPS-modus
FipsAuditLoggerCryptoPolicyInterface $policy, LoggerInterface $loggerZendt ALLOW (INFO) / DENY (WARNING) records per beslissing uitbool per log-aanroepGeenlogHashOperation, logSignatureOperation, logEncryptionOperation, logKeyStrengthCheck
FipsTransitioningAlgorithmsstring / int invoerStatische NIST SP 800-131A deny-catalogusbool / arrayGeenDe expliciete-deny-laag onder elke guard-grens
FipsBootstrap::boot() / ::lazy()?CryptoPolicyInterface $policy = null, ?FipsSelfTest $selfTest = null, ?LoggerInterface $auditLogger = nullStelt boot-guard, beleid en modusbewaking samen; boot() voert de zelftest meteen uit, lazy() stelt die uit tot de eerste grensFipsModeGuardboot(): FipsModuleErrorStateException bij een gefaalde testGebruikt standaard het strict-beleid
FipsBootstrap::signatureEnforcer()?CryptoPolicyInterface $policy = null, ?FipsSelfTest $selfTest = nullBoot de module en retourneert de generatie-tijd-poort voor de ondertekenaarsFipsSignatureEnforcerFipsModuleErrorStateExceptionGeef het resultaat door aan de $fipsEnforcer-parameter van een ondertekenaar
FipsBootstrap::selfTestReport()?FipsSelfTest $selfTest = nullVoert de batterij op aanvraag uit en vat die samenarray{status, operational, failed}GeenBedoeld voor health-endpoints en het CLI-subcommando
FipsViolationException / FipsModuleErrorStateExceptionGetypeerde FIPS-foutenStellen respectievelijk policyName / violatingItem / reason en failedResults bloot
public function __construct(private readonly string $libraryPath, private readonly int $slotId, #[SensitiveParameter] private readonly string $pin, #[SensitiveParameter] private readonly string $certLabel, #[SensitiveParameter] private readonly ?string $keyLabel = null, array $chainDer = [], private readonly bool $enablePostQuantum = false, ?FipsSignatureEnforcer $fipsEnforcer = null)
public static function isAvailable(): bool
public function sign(string $data, string $algorithm = 'sha256WithRSAEncryption'): string
public function signPqs(string $data, Pkcs11PqsAlgorithm $algorithm, string $context = '', bool $randomized = true): string
public function __construct(private string $keyUri, string $certPath, #[SensitiveParameter] private string $pin, array $extraCertPaths = [], private OpenSslCliBackend $backend = OpenSslCliBackend::Auto, private string $opensslBinary = 'openssl', private int $timeoutSeconds = 30, private ?string $modulePath = null, private ?string $configPath = null, private bool $legacyPinDelivery = false, private ?FipsSignatureEnforcer $fipsEnforcer = null)
public function sign(string $data, string $algorithm = 'sha256WithRSAEncryption'): string
public static function strict(?FipsSelfTest $selfTest = null): self
public static function standard(?FipsSelfTest $selfTest = null): self
public function assertPreOperational(): void
public function __construct(private CryptoPolicyInterface $policy, private ?FipsBootGuard $bootGuard = null, private ?FipsAuditLogger $auditLogger = null)
public function assertHashAllowed(string $algorithm): void
public function assertSignatureAlgorithmAllowed(string $oid): void
public function assertEncryptionAllowed(string $algorithm): void
public function assertKeyStrengthAllowed(string $keyType, int $bitLength): void
public function getPolicy(): CryptoPolicyInterface
public static function boot(?CryptoPolicyInterface $policy = null, ?FipsSelfTest $selfTest = null, ?LoggerInterface $auditLogger = null): FipsModeGuard
public static function lazy(?CryptoPolicyInterface $policy = null, ?FipsSelfTest $selfTest = null, ?LoggerInterface $auditLogger = null): FipsModeGuard
public static function signatureEnforcer(?CryptoPolicyInterface $policy = null, ?FipsSelfTest $selfTest = null): FipsSignatureEnforcer
public static function selfTestReport(?FipsSelfTest $selfTest = null): array
  • Contractresolutie. Beide ondertekenaars implementeren de Core-HsmSignerInterface; het beleid implementeert de Core-CryptoPolicyInterface. Aanroepende code hangt af van de contracten, dus een editie-upgrade wijzigt de compositie, niet de aanroeplocaties.
  • Sleutelbeheer. De privésleutel verlaat de tokengrens nooit. Pkcs11Signer delegeert de bewerking aan het token; OpenSslCliSigner geeft een PKCS#11-URI-sleutelreferentie door aan het subprocess. NextPDF slaat de ondertekeningssleutel niet op, genereert die niet en garandeert de beveiliging ervan niet. Sleutelbescherming is de bewaarverantwoordelijkheid van de operator (NIST SP 800-57 Part 1 Rev.5 §5.5.2).
  • Sessie en login. De token-sign-operatie, de sessie en de gebruikerslogin volgen PKCS#11 v3.1 §5. Het certificaatlabel en het privésleutel-label mogen verschillen; de constructor accepteert een apart sleutellabel voor zulke tokens.
  • Gesloten algoritmeset. De ondertekenaars accepteren precies: RSA PKCS#1 v1.5 met SHA-256/384/512, RSASSA-PSS met SHA-256/384/512 en ECDSA met SHA-256/384/512 (Pkcs11Signer accepteert ook ecdsa-raw). Elke andere identifier werpt InvalidArgumentException; er wordt nooit een vervangend algoritme ondertekend.
  • PSS-saltbinding. Voor elke PSS-variant is de saltlengte gelijk aan de digestlengte — 32, 48 of 64 bytes — en de hash- en mask-generation-parameters komen overeen met de gekozen digest (PKCS#11 v3.1 §5).
  • ECDSA-conversie. Token-ECDSA-mechanismen retourneren een ruwe handtekening; sign() zet die om naar de DER-gecodeerde ECDSA-Sig-Value-vorm voor PDF- en OpenSSL-interoperabiliteit. Handtekeninggeneratie volgt FIPS 186-5 §6.3.2.
  • Preset-inhoud. De strict-preset staat SHA-256/384/512 toe; RSA- en ECDSA-handtekening-OID’s met die hashes; RSASSA-PSS; AES-256-CBC en AES-256-GCM; minimaal RSA 2048 en EC 256. De standard-preset staat daarnaast AES-128-CBC toe voor legacy-interoperabiliteit. Elk AES-GCM-gebruik vereist een unieke initialisatievector per sleutel (NIST SP 800-38D §5).
  • Tweelaagse handhaving. Elke guard-grens raadpleegt eerst de expliciete NIST SP 800-131A deny-catalogus, daarna de allow-list van het beleid. De deny-laag produceert het audit-heldere “niet-toegestaan”-signaal; de allow-list blijft gezaghebbend.
  • Power-on-zelftest. De batterij dekt SHA-256/384/512, HMAC-SHA-256, AES-256-CBC, AES-256-GCM, een ECDSA P-256-pairwise-consistency-test en een random-bit-gezondheidscontrole. De eerste cryptografische bewerking onder het beleid op het Core-pad voert die eenmaal per proces uit, fail-closed. Een fout zet de module in de ERROR-status; cryptografische diensten worden geweigerd tot een reset. Dit volgt ISO/IEC 19790:2025 §7.10, §7.10.2, §7.10.3 en §7.10.3.p3.
  • Kleverige ERROR-status. Een waargenomen ERROR vergrendelt voor het hele proces. Het construeren van een nieuw beleid of een nieuwe boot-guard kan die niet witwassen; een geslaagde re-run heft die niet op. Alleen een procesherstart — een echte power cycle — reset de status.
  • Alleen generatiepoort. FipsSignatureEnforcer beheert het produceren van nieuwe handtekeningen. Validatie van reeds bestaande handtekeningen is legacy-gebruik en routeert nooit via de enforcer.
  • Audittrail. Wanneer een guard wordt samengesteld met een audit-logger, zendt elke grens een ALLOW- of DENY-record uit voordat de bewerking wordt toegestaan of afgewezen. De logger raadpleegt hetzelfde beleid dat de guard handhaaft, dus de vastgelegde beslissing kan niet afwijken.
  • Het construeren van Pkcs11Signer zonder ext-pkcs11 werpt onmiddellijk HsmOperationException; de extensie wordt niet meegeleverd met standaard PHP-distributies.
  • Een certificaat- of privésleutel-label dat met geen enkel tokenobject overeenkomt, werpt HsmOperationException met vermelding van de ontbrekende objectklasse.
  • OpenSslCliSigner weigert bij constructie een $keyUri die pin-value bevat, fail-closed; de PIN reist in plaats daarvan via het beveiligde pin-source-pad.
  • In FIPS-modus wordt een algoritme-identifier die niet naar een bekende handtekening-OID kan worden gemapt fail-closed geweigerd; net als een certificaat waarvan de sterkte van de publieke sleutel niet kan worden bepaald.
  • Een onbekend sleuteltype wordt standaard geweigerd; het beleid valt nooit terug op een zwakker algoritme.
  • Een gefaalde known-answer-test werpt FipsModuleErrorStateException met de gefaalde resultaten; elke latere grens in het proces herhaalt de fout tot een herstart.
  • Een guard die zonder boot-guard is geconstrueerd handhaaft de allow-lists maar biedt geen zelftestpoort; de productie-FIPS-compositie levert er een via de bootstrap.
  • signPqs() weigert te draaien tenzij de constructor-opt-in was gezet. Een contextstring boven 255 bytes werpt InvalidArgumentException (FIPS 204 §5.4). Een geretourneerde handtekening waarvan de bytelengte niet overeenkomt met de geselecteerde parameterset wordt geweigerd voordat die de codering bereikt.

FIPS-toegestaan in strict-modus: SHA-256/384/512; RSA PKCS#1 v1.5 en RSA-PSS met die hashes; ECDSA met die hashes; AES-256-CBC en AES-256-GCM; RSA minimaal 2048 bits, EC minimaal 256 bits. FIPS-afgewezen in strict-modus: zwakkere of legacy-hashes, niet-goedgekeurde handtekening-OID’s, AES-128 (alleen toegestaan in de standard-preset) en elke sleutel onder de minimale sterkte. De minimale RSA-sleutellengte en de overgangsstatus volgen NIST SP 800-131A Rev.2 §3. De ECDSA-curve en hash-pairing volgt FIPS 186-5 §6.1.1. Het pad is fail-closed en vervangt nooit door een zwakker algoritme.

NextPDF Enterprise is geen FIPS-gevalideerde cryptografische module en maakt geen FIPS-certificeringsclaim. NextPDF Enterprise werkt alleen in een FIPS-compatibele modus wanneer het is geconfigureerd met een FIPS-gevalideerde cryptografische provider — bijvoorbeeld een FIPS-gevalideerde OpenSSL-provider — of een FIPS-gevalideerde HSM. Het FIPS-modusbeleid ondersteunt compliance; het is geen certificering. Er bestaat geen FIPS-certificeringsartefact in deze repository.

ClaimStandaardClausule
Token-sign-operatie, sessie en gebruikerslogin-semantiekPKCS#11 v3.1§5 (sign)
PSS-saltlengte gelijk aan de digestlengtePKCS#11 v3.1§5 (PSS sLen)
ECDSA-handtekeninggeneratie; curve- en hash-pairingFIPS 186-5§6.3.2; §6.1.1
Minimale RSA-sleutellengte en overgangsstatus van handtekeninggeneratieNIST SP 800-131A Rev.2§3
Zelftestcategorie, documentatie, voorwaardelijke trigger, disjoint-setISO/IEC 19790:2025§7.10, §7.10.2, §7.10.3, §7.10.3.p3
AES-GCM-initialisatievector-uniciteitNIST SP 800-38D§5
Sleutelbescherming en bewaarverantwoordelijkhedenNIST SP 800-57 Part 1 Rev.5§5.5.2
Post-quantum-ondertekeningscontextstring beperkt tot 255 bytesFIPS 204§5.4

Alle clausules zijn geparafraseerd; er wordt geen normatieve tekst gereproduceerd. Dit zijn capaciteitsclaims over NextPDF-code, geen certificeringen. Of een geproduceerde handtekening verifieert, is de beslissing van de verifieerder tegen zijn eigen vertrouwensconfiguratie. Het FIPS-modusbeleid is een compliance-ondersteunende functie, geen juridisch oordeel; raadpleeg je eigen compliance- en juridische adviseurs. Deze module betreft cryptografische functionaliteit; behandel die als beveiligingsgevoelig in je eigen review.

  • Stel FIPS-modus samen via de bootstrap: boot() voor een start-up-poort, lazy() om de batterij uit te stellen tot de eerste grens, en de enforcer-fabriek voor de $fipsEnforcer-parameter van de ondertekenaars. Niet-FIPS-deployments geven null door en het gedrag blijft ongewijzigd.
  • Het bin/nextpdf-enterprise-subcommando fips:self-test voert de batterij op aanvraag uit en sluit af met een niet-nul-code in de ERROR-status; koppel het aan onderhoudsopdrachten of alleen-admin-health-endpoints (ISO/IEC 19790:2025 on-demand-zelftests).
  • FipsBootGuard::resetProcessErrorLatchForTesting() is @internal en alleen voor tests; productiecode roept die nooit aan, omdat dat de kleverige ERROR-status zou ondermijnen.
  • Construeer ondertekenaars eenmaal en hergebruik ze; de constructie logt in en leest het certificaat, en de per-bibliotheek-modulecache maakt herhaalde constructie tegen dezelfde bibliotheek veilig.
  • Lever de PIN vanuit een secret manager. Het is een #[SensitiveParameter], wordt nooit gelogd of geserialiseerd; commit die niet naar de configuratie.
  • De operator is eigenaar van token-provisioning, PIN-afhandeling, slotconfiguratie, netwerkbescherming van een netwerkgekoppelde HSM en vertrouwensconfiguratie. Deze pagina stelt geen token-PIN-beleid-internals of leverancier-referentiemateriaal beschikbaar.
  • Schakel de post-quantum-preview niet in voor productie-AdES-handtekeningen. De AdES-cryptografische-suites-catalogus herkent nog geen post-quantum-suites, de meeste PDF-viewers wijzen zulke handtekeningen af, en hardware-round-trip-validatie is niet voltooid. Intern mechanismedetail blijft in de interne documentatie van de bron-repository en valt buiten de scope van deze handleiding.

Deze pagina documenteert alleen extern waarneembaar gedrag en het ondersteunde publieke API-oppervlak. Interne namespace-paden, helperklassen, mechanismetabellen, runbook-bestandsnamen en ticketprefixen vallen buiten de scope.