Security — Diepe referentie

In het kort

Dit is de diepe referentie voor het NextPDF Pro security-oppervlak: masking tijdens generatie, PII-detectie in de tekstlaag, de remote en cloud-KMS-ondertekeningssessie, multi-party sequentieel ondertekenen, het CAdES- en XAdES-ingest-pad, het PAdES B-B-baselineniveau en PAdES B-T-ondertekeningsondersteuning (een B-B-handtekening plus één RFC 3161 signature-time-stamp op de handtekeningwaarde). Het beschrijft het publieke API-contract, het extern waarneembare gedrag en de Enterprise B-LT/B-LTA-grens. Het is op gedragsniveau; het verwijst naar geen interne implementatiepaden.

Beschikbaarheid en licentie

Deze capaciteit wordt geleverd in NextPDF Pro (nextpdf/pro) en wordt geactiveerd met een licentie-envelop van de Pro-tier. Een implementatie zonder die entitlement laadt de klassen van de capaciteit niet. Vergelijk edities en vraag een licentie aan.

Core levert de software-CMS-ondertekenaar, de RFC 3161-tijdstempelclient, RFC 5280-padvalidatie en OCSP- en CRL-revocatiecontrole. Pro voegt de hier beschreven masking, PII-detectie, het remote en cloud-KMS-ondertekeningsoppervlak en PAdES B-T-ondertekeningsondersteuning toe (het stelt de Core-RFC 3161-stack samen om een signature-time-stamp toe te voegen). De capaciteitsvlag voor dit oppervlak is pro: een implementatie zonder een actieve Pro-entitlement laadt deze klassen niet, het Core-ondertekeningscontract blijft ongewijzigd werken, en code die afhangt van het Core-contract breekt niet wanneer de entitlement ontbreekt.

Installatie

composer require nextpdf/pro:^3

Gedragscontract

De masking-engine past een geordende regellijst toe op tekst voordat de pagina wordt geschreven. Een regel matcht een PCRE-patroon en vervangt een match in een van drie modi:

• BlackBox — verwijdert de gematchte tekst uit de contentstream en reserveert een fill-regio. Deze modus verwijdert de onderliggende tekstobjecten zoals getest.
• Asterisks — vervangt elk gematcht teken door een asterisk en behoudt het aantal tekens.
• FixedLabel — vervangt de volledige match door een configureerbaar label, standaard [REDACTED].

Een regel wordt gebouwd vanuit een exacte literal via MaskingRule::exactMatch (de literal wordt regex-escaped) of vanuit een aangepast PCRE-patroon via MaskingRule::regex. MaskingConfig bevat de geordende regellijst, een standaardmodus en de fill-kleur. MaskingConfig::fromArray parseert een configuratiemap en laat stilzwijgend een regelentry vallen die geen bruikbaar string-patroon heeft, in plaats van de hele import te laten falen.

Het PII-oppervlak extraheert de PDF-tekstlaag en past daarna ingebouwde patronen toe voor e-mailadressen, telefoonnummers, United States Social Security numbers en creditcardnummers. Het retourneert een gestructureerd resultaat: een boolean voor of er een match is gevonden, een aantal matches, de gemaskeerde tekstweergave en de lijst van gescande typen. De caller mag de scan beperken tot een subset van de vier typen. Het oppervlak overschrijft de gerenderde paginaglyphs niet; een gescande pagina zonder tekstlaag levert geen matches op. Behandel het resultaat als patroondetectie van de geconfigureerde typen in de tekstlaag, niet als volledige verwijdering van persoonsgegevens en niet als een uitspraak over regelgevingsconformiteit.

De ondertekeningssessie is twee-fasig. RemoteSigningSession::create opent een sessie. prepare berekent de documentdigest over de twee ByteRange-regio’s en bouwt vervolgens de CMS signed attributes. complete roept de strategie aan en bedt het resultaat in; suspend serialiseert de sessie zodat een worker deze later kan hervatten met resume en completeWithRawSignature. De sessie assembleert een CMS SignedData en slaat deze DER-gecodeerd op in de Contents-vermelding van het handtekeningwoordenboek — ISO 32000-2 §12.8.1. Wanneer een parseerbaar X.509-certificaat wordt aangeleverd, zendt de sessie de volledige set verplichte PAdES B-B signed attributes uit: content-type, message-digest, signing-time, signing-certificate-v2 en een algorithm-protection-attribuut — RFC 5652 §5.3 en RFC 5652 §5. De verifier herberekent de content-digest en vergelijkt deze met het message-digest-attribuut; de vergelijking moet kloppen om de handtekening geldig te maken — RFC 5652 §5.4.

Wanneer het geconfigureerde PAdES-niveau B-T is (RemoteSigningConfig::default->withLevel(SignatureLevel::PAdES_B_T), of via SequentialSigner::withTimestamping) en een tijdstempelprovider is aangesloten, bedt de sessie daarnaast precies één RFC 3161 signature-time-stamp in als een CMS unsigned attribuut op de eerste SignerInfo. Een signature-time-stamp is een ongetekend attribuut dat één tijdstempeltoken draagt dat is berekend over de digitale handtekeningwaarde voor een ondertekenaar — ETSI EN 319 122-1 §5.3; zijn MessageImprint is de hash van de SignerInfo-handtekeningveldwaarde met de ASN.1-tag en -lengte uitgesloten — ETSI EN 319 122-1 §5.3 en RFC 3161 Appendix A (OID id-aa-timeStampToken = 1.2.840.113549.1.9.16.2.14). Omdat de tijdstempel een unsigned attribuut is, zijn de B-B signed attributes, de message-digest, de SignerInfo-handtekeningwaarde en de PDF /ByteRange byte-identiek aan de B-B-uitvoer; alleen de CMS groeit door het ongetekende attribuut, en de gereserveerde /Contents-ruimte voor B-T wordt verhoogd zodat het past. Het token wordt aangevraagd bij de geconfigureerde tijdstempelprovider (de standaard Core RFC 3161-client, of een door de caller aangeleverde provider). Op het standaard providerpad is de imprint-digest SHA-256; de SHA-1-gebonden legacy ESSCertID v1-vorm wordt geweigerd en ESSCertIDv2 is vereist — RFC 5816 §1. Een TSA-fout, een geweigerd verzoek, een onjuiste nonce of message-imprint-echo, een misvormd of unsupported-algorithm-token, of een token dat de cryptografische verificatie niet doorstaat, komt naar boven als een getypeerde PadesBt-exception waarbij de oorspronkelijke Core-exception behouden blijft als de vorige throwable. NextPDF Pro implementeert PAdES B-T-ondertekeningsondersteuning volgens ETSI EN 319 122-1 §5.3, RFC 3161, RFC 5652 en RFC 5816, en het is fixture-geverifieerd; het claimt geen onafhankelijke ETSI EN 319 142-1-certificering en claimt geen juridische geldigheid van het document.

SequentialSigner coördineert multi-party ondertekenen. Elke ondertekenaar is een aparte incremental-update-revisie. De eerste ondertekenaar mag een certificeringshandtekening zijn met een DocMDP-beperking ingesteld via certifyFirst. PadesWrapper ingest een bestaande handtekening: fromCades bedt een CMS-structuur direct in, fromXades parseert een XAdES-document en hergebruikt zijn kern-handtekeningmateriaal, en detect selecteert automatisch op formaat. Het XAdES-pad hergebruikt het certificaat, de keten, de handtekeningwaarde en het algoritme; het draagt geen XAdES qualifying properties over.

Publiek API-oppervlak

composer require nextpdf/pro:^3

Type	Soort	Rol	Stabiliteit	Sinds
RemoteSigningSession	class	Twee-fasige remote of asynchrone ondertekeningssessie	stable	1.9.0
RemoteSigningConfig	class	Onveranderlijke sessieconfiguratie, inclusief PAdES-niveau en algoritme	stable	1.9.0
SequentialSigner	class	Multi-party sequentieel ondertekenen met DocMDP-ondersteuning	stable	1.9.0
SequentialSigningResult	class	Resultaat van een sequentiële run: PDF-bytes, keten, aantal, volledigheid	stable	1.9.0
SigningStrategy	interface	Het ondertekeningsmechanismecontract dat een sessie aanroept	stable	1.9.0
PadesWrapper	class	Wikkelt een bestaande CAdES- of XAdES-handtekening voor PAdES-embedding	stable	1.9.0
KmsSignerInterface	interface (SPI)	Driver-contract van derden voor HSM en KMS; breidt het Core-HSM-ondertekenaarcontract uit	stable	2.1.0
SignatureAlgorithm	enum	Pro signature-algorithm-OID’s en digest-namen	stable	2.1.0
GenerationTimeMasker	class	Regelgestuurde masking toegepast voordat de pagina wordt geschreven	stable	1.9.0
MaskingConfig	class	Onveranderlijke masking-configuratie	stable	1.9.0
MaskingRule	class	Een enkele masking-regel (literal of PCRE)	stable	1.9.0
MaskingMode	enum	BlackBox, Asterisks, FixedLabel	stable	1.9.0

SigningStrategy-contract

Een strategie werkt op de DER-gecodeerde signed attributes en retourneert de ruwe handtekeningbytes. De sessie, niet de strategie, assembleert de CMS SignedData. Een strategie biedt de DER van het ondertekenaarcertificaat, de keten-DER geordend van leaf naar root, de signature-algorithm-OID, de digest-algorithm-naam en een isAsync-vlag die een strategie markeert waarvan de sessie kan worden geserialiseerd en hervat.

KmsSignerInterface-SPI

KmsSignerInterface breidt het Core-HSM-ondertekenaarcontract uit. Het voegt een stabiele providerId toe voor registry-lookup, een signWithVersion-methode met een expliciete key-version-parameter per aanroep, en supportsAlgorithm en supportedAlgorithms zodat een caller algoritmecompatibiliteit ontdekt vóór de sign-aanroep. De gereserveerde ingebouwde provider-identifiers zijn aws-kms, azure-keyvault, gcp-kms, pkcs11, openssl-cli en openssl-engine. Een driver van derden moet zijn identifier namespacen om een botsing te voorkomen. De standaard key-version-semantiek varieert per provider: een alias-resolverende provider resolveert de actieve sleutel uit de alias wanneer de versie null is; een provider die de nieuwste enabled versie selecteert, doet dat via zijn transport; een provider zonder server-side actieve-versie-concept moet een versie gebruiken die in zijn configuratie is vastgepind, en moet een key-management-fout opwerpen wanneer noch de aanroep noch de configuratie een versie vastpint. Een niet-lege versie pint die versie vast, en de provider moet een key-management-fout opwerpen wanneer de versie onbekend, disabled of revoked is.

Randgevallen en valkuilen

• Een geproduceerde handtekening is geen geverifieerde handtekening. Padvalidatie draait bij de verifier met de trust anchors en basic-constraint-controles van die verifier — RFC 5280 §6.1. De producer kan het resultaat niet claimen.
• De sessie heeft een legacy three-attribute fallback voor niet-X.509 synthetische certificaatbytes. Productiestrategieën leveren altijd echte X.509-DER, dus de volledige B-B-attribuutset is het productiepad. De fallback bestaat alleen voor het historische DER-mechanica-testoppervlak.
• De CMS-structuur moet passen in de gereserveerde Contents-ruimte. De B-B SignedData met een volledige certificaatketen heeft een grootte; de sessie werpt een overflow-fout wanneer de geassembleerde CMS de gereserveerde hex-ruimte overschrijdt. Dimensioneer de gereserveerde ruimte dienovereenkomstig. Voor B-T vergroot het ingebedde RFC 3161-token (gedomineerd door de TSA-certificaatketen) de CMS; de gereserveerde ruimte voor B-T wordt automatisch verhoogd, en een te krap geconfigureerde ruimte faalt gesloten met een getypeerde configuratiefout in plaats van af te kappen.
• MaskingConfig::fromArray laat een entry zonder bruikbaar string-patroon vallen in plaats van de import te laten falen. Valideer de configuratiebron als een stilzwijgende drop onacceptabel is.
• De black-box-modus van de masking zendt een lege vervanging uit voor de gematchte run en verwijdert de onderliggende tekst. Een regel die een waarde niet matcht, maskeert deze niet; de engine claimt niet dat alle gevoelige inhoud wordt gevonden.
• B-T vereist een aangesloten tijdstempelprovider. Op het standaard Core RFC 3161-providerpad is de imprint-digest SHA-256; een niet-SHA-256-imprint-digest op dat pad wordt afgewezen met een getypeerde configuratiefout in plaats van stilzwijgend te worden gedowngraded, en een door de caller aangeleverde aangepaste provider mag legitiem een ander goedgekeurd digest gebruiken. Een tijdstempel-serialNumber is uniek per token van een gegeven Time-Stamping Authority, en genTime is het UTC-moment waarop het token is aangemaakt — RFC 3161 §2.4.1, §2.4.2. B-LT/B-LTA-validatiemateriaal voor de lange termijn blijft een Enterprise-grenskwestie; Pro produceert geen DSS, geen VRI en geen documenttijdstempel.
• OCSP unknown is niet good, en de versheid van de status wordt begrensd door thisUpdate en nextUpdate — RFC 6960 §2.2, §4.2.

FIPS-modusgedrag

Pro selecteert het algoritme uit het geconfigureerde handtekeningalgoritme en de strategie. Wanneer geconfigureerd tegen een FIPS-gevalideerde KMS of HSM, draait de cryptografische bewerking binnen die gevalideerde grens, en de algoritmeset is wat die grens toestaat. NextPDF Pro voert structurele CMS-assemblage en digest-berekening uit; het is geen FIPS-gevalideerde cryptografische module en doet geen FIPS-certificeringsclaim. Een implementatie die een FIPS-houding vereist, moet een FIPS-gevalideerde KMS of HSM configureren, en het FIPS 140-3 crypto-beleidsprofiel is een Enterprise-capaciteit.

Exportcontrolehouding

Deze module betreft cryptografische functionaliteit; behandel deze als security-gevoelig in je eigen review.

Enterprise-grens

NextPDF Pro produceert de B-B-baseline en het B-T-niveau. Voor B-B assembleert de sessie een CMS SignedData met de B-B signed-attribute-set en past geen tijdstempel toe. Voor B-T voegt het precies één RFC 3161 signature-time-stamp toe als een CMS unsigned attribuut berekend over de digitale handtekeningwaarde voor een ondertekenaar — ETSI EN 319 122-1 §5.3. NextPDF Pro implementeert dit volgens ETSI EN 319 122-1 §5.3, RFC 3161, RFC 5652 en RFC 5816, en het is fixture-geverifieerd; het claimt geen onafhankelijke ETSI EN 319 142-1-certificering, -conformiteit of -compliance, en claimt geen juridische geldigheid van het document.

De B-LT- en B-LTA-niveaus zijn Enterprise-capaciteiten en worden niet geproduceerd door Pro. B-LT en B-LTA voegen een Document Security Store en documenttijdstempels toe voor validatie op lange termijn voor archivering — ETSI EN 319 142-2 §5.5. Een signature handler die die niveaus produceert, ondersteunt DSS-vermeldingen en documenttijdstempels — ETSI EN 319 142-2 §6.3.3.3. De Pro-RemoteSigningConfig kan een niveau boven B-T dragen (B-LT of B-LTA) dat een Document Security Store aanvraagt, maar Pro levert die producer niet en handelt er niet naar; zo’n niveau is een forward-declared waarde. De Core-ondertekeningsflow resolveert de langetermijnproducer tijdens runtime via het Core-contract, en die producer wordt geleverd in het nextpdf/enterprise-pakket. In een Pro-only-implementatie faalt een aanvraag voor B-LT of B-LTA gesloten met een bericht dat de ontbrekende Enterprise-component benoemt. Pro produceert geen DSS, geen VRI-woordenboek, geen documenttijdstempel en geen archiveringslus, en doet geen langetermijnvalidatie (LTV)-claim. Bewaring van hardwaresleutels via PKCS#11 en het FIPS 140-3 crypto-beleidsprofiel zijn eveneens Enterprise-capaciteiten. Deze pagina documenteert de Enterprise-implementatie voor validatie op lange termijn niet; het beschrijft alleen de grens en de publieke pakketnaam.

PAdES-niveau	Voegt toe	Producer-editie
B-B	CMS-handtekening met signed attributes	Core, Pro
B-T	Eén RFC 3161 signature-time-stamp unsigned attribuut op de handtekeningwaarde	Core, Pro
B-LT	Document Security Store met validatiemateriaal	Enterprise (nextpdf/enterprise)
B-LTA	Documenttijdstempels voor archiveringsgeldigheid	Enterprise (nextpdf/enterprise)

Publicatiegrens

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.

Core-fallback

Een implementatie zonder de Pro-entitlement behoudt het Core-ondertekeningscontract. Code die afhangt van het Core-SignerInterface-contract blijft ondertekenen met de software-CMS-ondertekenaar op de B-B-baseline. De masking, PII-detectie en remote en cloud-KMS-strategieën zijn niet aanwezig zonder het Pro-pakket, en een aanroep naar die typen is een harde afhankelijkheidsfout, geen stilzwijgende no-op.

Data residency en PII-mitigaties

De masking- en PII-oppervlakken draaien in-process. Geen documentinhoud verlaat de host voor masking of PII-detectie. Een cloud-KMS-strategie stuurt de signed-attributes-digest, niet het document, naar de provider voor de ondertekeningsbewerking. PII-detectie is patroongematcht op de geconfigureerde typen en verwijdert de onderliggende tekstobjecten voor de black-box-modus zoals getest. Het is geen garantie van volledige verwijdering van persoonsgegevens en geen uitspraak over regelgevingsconformiteit.

Veilige telemetrie en logscrubbing

De library werpt getypeerde exceptions met structurele meldingen. Het schrijft geen documentinhoud of gedetecteerde PII-waarden in exception-meldingen of logs. Een implementatie die rond het ondertekeningspad logt, moet structurele velden loggen, geen documentbytes.

Conformiteit

Claim	Standaard	Clausule
De CMS-handtekening wordt DER-gecodeerd opgeslagen in de Contents-vermelding van het handtekeningwoordenboek.	ISO 32000-2	§12.8.1
Het message-digest-berekeningsproces; signed attributes dragen content-type en message-digest.	RFC 5652	§5.4
De verifier mag niet vertrouwen op door de originator berekende digests; deze herberekent en vergelijkt onafhankelijk (handtekeningverificatieproces).	RFC 5652	§5.6
SignerInfo draagt de digest-algorithm-identifier en het signed-attributes-blok.	RFC 5652	§5
Een tijdstempelverzoek retourneert een TSTInfo-structuur.	RFC 3161	§2.4.1
Een tijdstempel-serialNumber is uniek per token van een gegeven TSA.	RFC 3161	§2.4.2
De tijdstempel-genTime is het UTC-moment waarop het token is aangemaakt.	RFC 3161	§2.4.2
Een PAdES B-T signature-time-stamp is een unsigned attribuut dat één tijdstempeltoken draagt dat is berekend over de digitale handtekeningwaarde voor een ondertekenaar (Pro produceert B-T).	ETSI EN 319 122-1	§5.3
De signature-time-stamp-imprint is de hash van de SignerInfo-handtekeningveldwaarde met de ASN.1-tag en -lengte uitgesloten.	ETSI EN 319 122-1	§5.3
Het signature-time-stamp-token gebruikt de id-aa-timeStampToken-OID; zijn MessageImprint is een hash van de SignerInfo-handtekeningveldwaarde.	RFC 3161	Appendix A
Aan de verificatiekant bindt NextPDF de MessageImprint van een signature-time-stamp aan de SignerInfo-handtekeningwaarde en faalt gesloten bij een mismatch, een ontbrekend/gedupliceerd token of een SHA-1-imprint (strikte verificatie, geen certificering).	RFC 3161	Appendix A
ESSCertIDv2 vervangt de SHA-1-gebonden legacy ESSCertID; het strikte B-T-pad vereist ESSCertIDv2.	RFC 5816	§1
Certificeringspadvalidatie controleert basic constraints en padinvoer naar een trust anchor.	RFC 5280	§6.1
OCSP meldt certStatus als good, revoked of unknown.	RFC 6960	§2.2
OCSP-statusversheid wordt begrensd door thisUpdate en nextUpdate.	RFC 6960	§4.2
B-LT en B-LTA voegen een Document Security Store en documenttijdstempels toe voor validatie op lange termijn (Enterprise-grens).	ETSI EN 319 142-2	§5.5
Een signature handler die langetermijnniveaus produceert, ondersteunt DSS-vermeldingen en documenttijdstempels (Enterprise-grens).	ETSI EN 319 142-2	§6.3.3.3

Alle clausules zijn geparafraseerd. NextPDF reproduceert geen normatieve tekst. Raadpleeg de gepubliceerde standaarden voor de gezaghebbende formulering. NextPDF Pro implementeert PAdES B-T-ondertekeningsondersteuning volgens ETSI EN 319 122-1 §5.3 (signature-time-stamp), RFC 3161, RFC 5652 en RFC 5816, en het is fixture-geverifieerd. ETSI EN 319 142-1 (het deel met PAdES-baselineniveaus) valt buiten de geciteerde bewijsverzameling; NextPDF Pro claimt daarom geen onafhankelijke ETSI EN 319 142-1-certificering, -conformiteit of -compliance, en claimt geen juridische geldigheid van het document. Deze pagina beschrijft de geproduceerde structuur, de standaarden die de B-T-ondersteuning implementeert en de Enterprise B-LT/B-LTA-grens, niet een gecertificeerd conformiteitsniveau.

Zie ook

• Core signing — de CMS-ondertekenaar, RFC 3161-tijdstempel, RFC 5280-padvalidatie, OCSP en CRL.
• PAdES baseline-mapping — B-B, B-T, B-LT, B-LTA over edities heen.
• Security (capaciteitsoverzicht) — de openbare Pro security-capaciteitspagina.
• CMS · PAdES · RFC 3161 timestamp · KMS · DSS — woordenlijsttermen.