Pas een PAdES-handtekening toe via NextPDF Connect (Pro)

In het kort

Pas via NextPDF Connect een baseline PDF Advanced Electronic Signatures-handtekening (PAdES) toe op een PDF. Gebruik sign_pdf; die is opnieuw geverifieerd tegen de Pro-toolprovider: die provider registreert new SignPdfTool(), waarvan de protocolnaam sign_pdf is. sign_pdf is een tool op Pro-niveau. Bij het opstarten controleert de server met class_exists() of de tool bestaat en registreert deze alleen wanneer het Pro-pakket is geïnstalleerd.

Standaard produceert de tool PAdES B-B. De tool kan PAdES B-T produceren (B-B plus één RFC 3161-signature-time-stamp) alleen wanneer de host een tijdstempelprovider aan de tool heeft gekoppeld; het verzoek kan niet naar een Time Stamp Authority (TSA) verwijzen. Langetermijnniveaus (B-LT, B-LTA) en het bijbehorende validatiemateriaal (DSS, VRI, LTV) maken geen deel uit van deze tool en vallen buiten het bereik van deze pagina.

U-1-voorbehoud. NextPDF claimt geen onafhankelijke ETSI EN 319 142-1 certificering voor PAdES B-T. EN 319 142-1 zit niet in het verificatiecorpus. De vereiste voor de B-T-signature-time-stamp is geverifieerd tegen ETSI EN 319 122-1 §5.3 (de CAdES-basis die EN 319 142-1/-2 via verwijzing overnemen), samen met RFC 3161, RFC 5652, RFC 5816 en ISO 32000-2 §12.8. Ondersteuning voor het B-T-profiel is geen conformiteits- of rechtsgeldigheidscertificering; dat bepaalt een onafhankelijke validator.

Installeren

composer require nextpdf/server
composer require nextpdf/pro

Bind een transport en controleer daarna met diagnostic.capabilities dat sign_pdf bestaat. Voor B-T moet de host de tool met een tijdstempelprovider initialiseren. Zonder zo’n provider mislukt een pades_b_t: true-verzoek met een getypeerde fout in plaats van stilzwijgend te downgraden.

Conceptueel overzicht

sign_pdf berekent een byte-range-digest over het bestand, waarbij de placeholder voor de handtekeningwaarde wordt uitgesloten (ISO 32000-2 §12.8.1). Vervolgens schrijft de tool met Distinguished Encoding Rules (DER) gecodeerde Cryptographic Message Syntax (CMS) SignedData naar de sleutel Contents van het handtekeningwoordenboek (ISO 32000-2 §12.8.1). Ondersteunde algoritmen zijn RSA-SHA256 (standaard), RSA + SHA-3 (256/384/512) en Ed25519. Voor transporten die niet end-to-end vertrouwelijk zijn, kun je de inkomende private_key-payload in een optionele AES-GCM-envelop verpakken.

B-T-upgrade. Met pades_b_t: true én een door de host gekoppelde tijdstempelprovider wordt de handtekening geüpgraded naar PAdES B-T: de byte-range-hash gaat naar een TSA en er wordt een TimeStampToken ingebed (ISO 32000-2 §12.8.5). B-T is precies B-B plus één RFC 3161-signature-time-stamp die als ongetekend attribuut wordt meegevoerd op de CMS SignerInfo (RFC 5652 §5.3). Ongetekende attributen vallen niet onder de handtekening, dus de getekende B-B-digest en de geldigheid ervan blijven ongewijzigd (RFC 5652 §5.3). De attribuutwaarde is een SignatureTimeStampToken (ETSI EN 319 122-1 §5.3). B-T voegt geen Document Security Store (DSS)-woordenboek, geen Validation Related Information (VRI), geen validatiemateriaal en geen archieftijdstempellus toe. Dat is de B-LT/B-LTA-Enterprise-delta en die valt buiten het bereik van deze tool.

U-1-voorbehoud (herhaald bij de B-T-claim). B-T-ondersteuning is hier geen EN 319 142-1-conformiteit of rechtsgeldigheidscertificering; een onafhankelijke validator beslist. EN 319 142-1 zit niet in het verificatiecorpus. B-T is gebaseerd op ETSI EN 319 122-1 §5.3, RFC 3161, RFC 5652, RFC 5816 en ISO 32000-2 §12.8.

Onderstaande flow toont het door de host gestuurde TSA-pad (het verzoek kan niet naar een TSA verwijzen) en de fail-closed B-T-tak (nooit een stilzwijgende downgrade).

Diagram

API-oppervlak

Tool	Niveau	Rol	Risiconiveau
`create_pdf`, `add_text`	Core	Inhoud opbouwen	Veilig / Voorzichtig
`sign_pdf`	Pro	PAdES B-B toepassen (of door de host gestuurde B-T)	Goedkeuring vereist
`output_pdf`	Core	De PDF renderen en retourneren	Goedkeuring vereist / Beoordeling (base64)

Toolnamen zijn protocolnamen in het register. De toolcatalogus is de gezaghebbende catalogus. Welke tools beschikbaar zijn, hangt af van het geïnstalleerde niveau; tools voor langetermijnniveaus zijn niet aanwezig in Pro.

Codevoorbeeld — Snelstart

create_pdf → bouw inhoud op met add_text.
sign_pdf met certificate (PEM), private_key (PKCS#8 PEM), optioneel signer_name, reason en algorithm. Laat pades_b_t weg (of stel het in op false) voor B-B.
output_pdf.

De tool retourneert deze resultatenvelop:

{
  "pdf": "<base64 of the signed PDF>",
  "signature_count": 1,
  "is_complete": true,
  "algorithm": "RSA_SHA256",
  "oid": "<algorithm OID>",
  "digest": "<digest algorithm>",
  "level": "PAdES-B-B",
  "timestamped": false
}

Stuur voor een door de host gestuurde B-T-handtekening pades_b_t: true; level wordt "PAdES-B-T" en timestamped wordt true.

Codevoorbeeld — Productie

Onderteken als laatste inhoudsbewerking. Elke add_text/add_image na sign_pdf maakt de handtekening ongeldig. Verpak private_key bij een niet-vertrouwelijk transport in de AES-GCM-transport_encryption-envelop (12-byte nonce; 16/24/32-byte sleutel). Controleer of het level van het resultaat overeenkomt met je verzoek. Een pades_b_t: true-verzoek bij een tool zonder provider mislukt expliciet. Handel die fout af en probeer het niet stilzwijgend opnieuw als B-B.

Randgevallen en valkuilen

Certificaat/sleutel komen niet overeen. De tool weigert het verzoek met een duidelijke fout; de privésleutel moet overeenkomen met de openbare sleutel van het certificaat.
Misvormde PEM / verlopen certificaat. De tool weigert het verzoek; de tool ondertekent standaard niet met een niet-parseerbaar of verlopen certificaat.
Inhoud na ondertekenen. De tool weigert het verzoek — onderteken als laatste.
B-T aangevraagd, geen provider. De tool retourneert een getypeerde fout: de handtekening wordt niet geproduceerd en niet stilzwijgend gedowngradet naar B-B.
Zelfondertekend certificaat. De handtekening wordt toegepast, maar lezers tonen onbekend vertrouwen. Dat is verwacht gedrag, geen tooldefect.
Pro afwezig. Met alleen Core registreert de server sign_pdf niet.

Prestaties

Ondertekenen voegt de CMS-opbouw toe en, voor B-T, één TSA-rondrit; het budget dekt beide. Het profiel is semantic: een RFC 3161-token is inherent niet-reproduceerbaar, terwijl de byte-range-digest van §12.8.1 de handtekeningwaarde uitsluit. Gebruik daarom alleen een vergelijking van AST + handtekeningmetadata.

Beveiligingsnotities

Een handtekening biedt integriteit en authenticatie ten opzichte van de ondertekeningssleutel. Op zichzelf maakt zo’n handtekening een document niet „veilig” of „rechtsgeldig”, en ze garandeert geen onweerlegbaarheid. Die uitkomsten hangen af van het certificaat, het vertrouwensanker ervan, het sleutelbeheer en het beleid van de verificateur, die allemaal buiten deze tool vallen. Het versleutelen van de sleutelpayload met de AES-GCM-envelop beschermt de vertrouwelijkheid tijdens transport, niet de integriteit. Behandel de privésleutel als een geheim en geef op elk niet-vertrouwelijk kanaal de voorkeur aan de transportversleutelingsenvelop.

Conformiteit

Stelling	Spec	Clausule
De byte-range-digest dekt het bestand en sluit de handtekeningwaarde uit.	ISO 32000-2	§12.8.1
`Contents` bevat de met DER gecodeerde CMS SignedData.	ISO 32000-2	§12.8.1
Voor een tijdstempel gaat de byte-range-hash naar een TSA en wordt het token in `Contents` geplaatst.	ISO 32000-2	§12.8.5
De B-T-tijdstempel is een ongetekend attribuut op SignerInfo.	RFC 5652	§5.3
Ongetekende attributen veranderen de getekende B-B-digest of geldigheid niet.	RFC 5652	§5.3
De waarde van signature-time-stamp is een SignatureTimeStampToken.	ETSI EN 319 122-1	§5.3

NextPDF produceert de handtekeningstructuur. Het claimt niet dat een resulterende handtekening conform of rechtsgeldig is; een onafhankelijke validator beslist. Deze tool produceert geen B-LT/B-LTA.

Commerciële context

sign_pdf is een tool op Pro-niveau. De server registreert de tool alleen wanneer het Pro-pakket tijdens het opstarten van de server kan worden geladen. PAdES-langetermijnniveaus (B-LT, B-LTA) en het bijbehorende validatiemateriaal (DSS, VRI, LTV) zijn alleen Enterprise en worden niet blootgesteld door deze tool of dit recipe.

Dataresidentie en PII-mitigaties

Het certificaat en de privésleutel gaan mee in het verzoek. Gebruik de AES-GCM-transport_encryption-envelop voor elk kanaal dat niet end-to-end vertrouwelijk is. De ondertekende PDF en de ondertekenaarsidentiteit (signer_name, reason) zijn documentinhoud, dus houd ze binnen je dataresidentiegrens. De integrator is verantwoordelijk voor residentie op implementatieniveau.

Veilige telemetrie en logscrubbing

Log nooit de private_key-payload, de AES-GCM-sleutel/nonce of het bevestigingstoken. Log het algoritme, het resulterende level en signature_count, niet het sleutelmateriaal. De tool zendt geen sleutelbytes uit in het resultaat.

Dreigingsmodel

Beschouwde dreigingen: blootstelling van de sleutel tijdens transport (gemitigeerd door de AES-GCM-envelop en de door de host geïnjecteerde, niet via het verzoek configureerbare TSA-provider); een MCP-aanroeper die de tijdstempel naar een willekeurig eindpunt richt (voorkomen omdat de provider door de host wordt geïnjecteerd en niet via het verzoek configureerbaar is); en manipulatie na ondertekening (de byte-range-digest detecteert wijzigingen). Een dreigingsmodel documenteert beschouwde dreigingen en mitigaties; het claimt niet dat er geen kwetsbaarheden zijn.

FIPS-modusgedrag

Algoritmeselectie (RSA-SHA256, RSA + SHA-3, Ed25519) wordt door het verzoek bepaald. OpenSSL op de host levert de cryptografische primitieven. Beperk in een FIPS-beperkte implementatie het algoritme in de beleidslaag en vertrouw op de gevalideerde module van de host. Deze tool claimt zelf geen Federal Information Processing Standards (FIPS)-validatie.

Transportbeschikbaarheid

Transport	Beschikbaar	Opmerkingen
MCP (stdio)	Ja (Pro)	Gebruik de AES-GCM-sleutelenvelop op stdio.
REST	Ja (Pro)	Geef de voorkeur aan TLS plus de sleutelenvelop.
gRPC	Ja (Pro)	Geef de voorkeur aan TLS plus de sleutelenvelop.

HITL-risiconiveau

sign_pdf is Goedkeuring vereist omdat het een destructieve, onomkeerbare bewerking is; de tool kondigt een destructieve hint aan. De bevestigingspoort werkt zoals bij elke tool met Goedkeuring vereist. output_pdf naar een bestand is eveneens Goedkeuring vereist; base64-modus is Beoordeling (HITL-risiconiveaus).

JSON-envelop van de bevestigingspoort

sign_pdf retourneert zonder een geldig token de challenge-envelop:

{
  "allowed": false,
  "challenge": "⚠️ CONFIRMATION REQUIRED\n\nOperation: sign_pdf\nDescription: <tool description>\n\nTo proceed, call sign_pdf again with parameter _confirmation_token: \"confirm_<single-use-hex>\"\nExpires in 300 seconds.",
  "token": "confirm_<single-use-hex>"
}

Roep de tool opnieuw aan met _confirmation_token ingesteld op het token → { "allowed": true }. Volledige flow: output-approval.