Digitale PAdES-Signatur mit NextPDF Connect (Pro) anwenden

Auf einen Blick

Wenden Sie über NextPDF Connect eine digitale PAdES-Baseline-Signatur auf ein PDF an. Das Tool ist sign_pdf; dies wurde erneut gegen den Pro-Tool-Provider verifiziert: Dieser Provider registriert new SignPdfTool(), dessen Protokollname sign_pdf ist. sign_pdf ist ein Tool der Pro-Stufe. Der Server prüft dies beim Start mit class_exists() und registriert es nur, wenn das Pro-Paket installiert ist.

Standardmäßig erzeugt das Tool PAdES B-B. Es kann PAdES B-T (B-B plus einen RFC 3161-signature-time-stamp) erzeugen, jedoch nur, wenn der Host einen Zeitstempel-Provider in das Tool eingebunden hat; die Anfrage kann nicht auf eine TSA verweisen. Langzeitstufen (B-LT, B-LTA) und ihr Validierungsmaterial (DSS, VRI, LTV) sind nicht Teil dieses Tools und liegen hier außerhalb des Umfangs.

U-1-Vorbehalt. NextPDF behauptet keine eigenständige ETSI EN 319 142-1 Zertifizierung für PAdES B-T. EN 319 142-1 ist nicht im Verifikationskorpus enthalten. Die B-T-signature-time-stamp-Anforderung wird anhand von ETSI EN 319 122-1 §5.3 (der CAdES-Grundlage, die EN 319 142-1/-2 per Verweis übernehmen), zusammen mit RFC 3161, RFC 5652, RFC 5816 und ISO 32000-2 §12.8 verifiziert. Die Unterstützung des B-T-Profils ist keine Zertifizierung der Konformität oder Rechtsgültigkeit; ein unabhängiger Validierer trifft diese Feststellung.

Installation

composer require nextpdf/server
composer require nextpdf/pro

Binden Sie einen Transport ein. Prüfen Sie mit diagnostic.capabilities, dass sign_pdf vorhanden ist. Für B-T muss der Host das Tool mit einem Zeitstempel-Provider konstruieren. Ohne einen solchen Provider schlägt eine pades_b_t: true-Anfrage mit einem typisierten Fehler fehl, statt stillschweigend herabgestuft zu werden.

Konzeptioneller Überblick

sign_pdf berechnet einen Byte-Range-Digest über die Datei und schließt den Platzhalter für den Signaturwert aus (ISO 32000-2 §12.8.1). Anschließend schreibt es DER-kodierte CMS-SignedData in das Signaturwörterbuch Contents (ISO 32000-2 §12.8.1). Unterstützte Algorithmen: RSA-SHA256 (Standard), RSA + SHA-3 (256/384/512) und Ed25519. Ein optionaler AES-GCM-Umschlag kann die eingehende private_key-Nutzlast bei Transporten umhüllen, die nicht Ende-zu-Ende-vertraulich sind.

B-T-Hochstufung. Mit pades_b_t: true und einem vom Host eingebundenen Zeitstempel-Provider wird die Signatur auf PAdES B-T hochgestuft: Der Byte-Range-Hash wird an eine TSA gesendet und ein TimeStampToken wird eingebettet (ISO 32000-2 §12.8.5). B-T entspricht genau B-B plus einem RFC 3161-signature-time-stamp, der als unsigniertes Attribut auf der CMS-SignerInfo getragen wird (RFC 5652 §5.3). Unsignierte Attribute werden nicht von der Signatur abgedeckt, daher bleiben der signierte B-B-Digest und seine Gültigkeit unverändert (RFC 5652 §5.3). Der Attributwert ist ein SignatureTimeStampToken (ETSI EN 319 122-1 §5.3). B-T fügt kein DSS-Wörterbuch, kein VRI, kein Validierungsmaterial und keine Archiv-Zeitstempelschleife hinzu — das ist das B-LT/B-LTA-Enterprise-Delta und liegt außerhalb des Umfangs dieses Tools.

U-1-Vorbehalt (wiederholt bei der B-T-Behauptung). Die B-T-Unterstützung hier ist weder EN 319 142-1-Konformität noch eine Rechtsgültigkeitszertifizierung; ein unabhängiger Validierer entscheidet. EN 319 142-1 ist nicht im Verifikations-Korpus enthalten. B-T ist gestützt auf ETSI EN 319 122-1 §5.3, RFC 3161, RFC 5652, RFC 5816 und ISO 32000-2 §12.8.

Der Tool-Ablauf — einschließlich der host-gegateten TSA-Anbindung (die Anfrage kann nicht auf eine TSA verweisen) und des fail-closed-B-T-Zweigs (niemals eine stille Herabstufung) — ist unten dargestellt.

Diagram

API-Oberfläche

Tool	Stufe	Rolle	Risikostufe
`create_pdf`, `add_text`	Core	Inhalt aufbauen	Sicher / Vorsicht
`sign_pdf`	Pro	PAdES B-B (oder host-gegatetes B-T) anwenden	Genehmigung erforderlich
`output_pdf`	Core	Das PDF rendern und zurückgeben	Genehmigung erforderlich / Prüfung (base64)

Tool-Namen sind die Protokollnamen der Registry; der Tool-Katalog ist der maßgebliche Katalog. Verfügbare Tools hängen von der installierten Stufe ab; Tools für Langzeitstufen sind in Pro nicht vorhanden.

Codebeispiel — Schnellstart

create_pdf → Inhalt mit add_text aufbauen.
sign_pdf mit certificate (PEM), private_key (PKCS#8 PEM), optional signer_name, reason und algorithm. Lassen Sie pades_b_t weg (oder setzen Sie es auf false) für B-B.
output_pdf.

Das Tool gibt den folgenden Ergebnis-Envelope zurück:

{
  "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
}

Für eine host-gegatete B-T-Signatur senden Sie pades_b_t: true; level wird auf "PAdES-B-T" und timestamped auf true gesetzt.

Codebeispiel — Produktion

Signieren Sie als letzten Inhaltsvorgang. Jedes add_text/add_image nach sign_pdf macht die Signatur ungültig. Bei einem nicht vertraulichen Transport umhüllen Sie private_key im AES-GCM-transport_encryption-Umschlag (12-Byte-Nonce; 16/24/32-Byte-Schlüssel). Prüfen Sie, dass das Ergebnis-level dem entspricht, was Sie angefordert haben. Eine pades_b_t: true-Anfrage an ein Tool ohne Provider schlägt explizit fehl: Behandeln Sie diesen Fehler und versuchen Sie es nicht stillschweigend erneut als B-B.

Grenzfälle & Fallstricke

Zertifikat/Schlüssel stimmen nicht überein. Mit einem klaren Fehler abgelehnt; der private Schlüssel muss zum öffentlichen Schlüssel des Zertifikats passen.
Fehlerhaftes PEM / abgelaufenes Zertifikat. Abgelehnt; das Tool signiert standardmäßig nicht mit einem nicht parsbaren oder abgelaufenen Zertifikat.
Inhalt nach dem Signieren. Abgelehnt — zuletzt signieren.
B-T angefordert, kein Provider. Ein typisierter Fehler: Die Signatur wird nicht erzeugt und wird nicht stillschweigend auf B-B herabgestuft.
Selbstsigniertes Zertifikat. Die Signatur wird angewendet, aber Reader zeigen eine unbekannte Vertrauensstellung — das ist erwartet, kein Tooldefekt.
Pro nicht vorhanden. Mit Core allein ist sign_pdf nicht registriert.

Leistung

Beim Signieren kommen der CMS-Aufbau und, bei B-T, ein TSA-Roundtrip hinzu; das Budget deckt dies ab. Das Profil ist semantic: Ein RFC 3161-Token ist von Natur aus nicht reproduzierbar, und der §12.8.1-Byte-Range-Digest schließt den Signaturwert aus, sodass nur ein AST- + Signatur-Metadaten-Vergleich sachgerecht ist.

Sicherheitshinweise

Eine Signatur bietet Integrität und Authentifizierung bezogen auf den Signierschlüssel. Sie macht ein Dokument für sich genommen nicht „sicher“ oder „rechtsgültig“ und garantiert auch keine Nichtabstreitbarkeit — das hängt vom Zertifikat, seinem Vertrauensanker, der Schlüsselverwahrung und der Richtlinie des Prüfers ab, die alle außerhalb dieses Tools liegen. Die Verschlüsselung der Schlüssel-Nutzlast (AES-GCM-Umschlag) schützt die Vertraulichkeit während der Übertragung, nicht die Integrität. Behandeln Sie den privaten Schlüssel als Geheimnis und bevorzugen Sie auf jedem nicht vertraulichen Kanal den Transportverschlüsselungs-Umschlag.

Konformität

Aussage	Spezifikation	Klausel
Der Byte-Range-Digest deckt die Datei ab und schließt den Signaturwert aus.	ISO 32000-2	§12.8.1
`Contents` enthält die DER-kodierten CMS-SignedData.	ISO 32000-2	§12.8.1
Für einen Zeitstempel geht der Byte-Range-Hash an eine TSA und das Token wird in `Contents` platziert.	ISO 32000-2	§12.8.5
Der B-T-Zeitstempel ist ein unsigniertes Attribut auf SignerInfo.	RFC 5652	§5.3
Unsignierte Attribute ändern den signierten B-B-digest/validity nicht.	RFC 5652	§5.3
Der signature-time-stamp-Wert ist ein SignatureTimeStampToken.	ETSI EN 319 122-1	§5.3

NextPDF erzeugt die Signaturstruktur. Es behauptet nicht, dass eine resultierende Signatur konform oder rechtsgültig ist — darüber entscheidet ein unabhängiger Validierer. B-LT/B-LTA werden von diesem Tool nicht erzeugt.

Kommerzieller Kontext

sign_pdf ist ein Tool der Pro-Stufe, das nur registriert wird, wenn das Pro-Paket beim Serverstart aufgelöst wird. PAdES-Langzeitstufen (B-LT, B-LTA) und ihr Validierungsmaterial (DSS, VRI, LTV) sind Enterprise-only und werden weder von diesem Tool noch von diesem Rezept bereitgestellt.

Datenresidenz & PII-Minderungen

Das Zertifikat und der private Schlüssel durchlaufen die Anfrage. Verwenden Sie den AES-GCM-transport_encryption-Umschlag auf jedem Kanal, der nicht Ende-zu-Ende-vertraulich ist. Das signierte PDF und die Signiereridentität (signer_name, reason) sind Dokumentinhalt; halten Sie sie daher innerhalb Ihrer Datenresidenzgrenze. Die Residenz auf Deployment-Ebene liegt in der Verantwortung des Integrators.

Sichere Telemetrie & Log-Bereinigung

Loggen Sie niemals die private_key-Nutzlast, den AES-GCM-key/nonce oder das Bestätigungs-Token. Loggen Sie den Algorithmus, das resultierende level und signature_count — nicht das Schlüsselmaterial. Das Tool gibt im Ergebnis keine Schlüssel-Bytes aus.

Bedrohungsmodell

Berücksichtigte Bedrohungen: Schlüsseloffenlegung während der Übertragung (gemindert durch den AES-GCM-Umschlag und den host-injizierten, per Anfrage nicht konfigurierbaren TSA-Provider); ein MCP-Aufrufer, der den Zeitstempel auf einen beliebigen Endpunkt richtet (verhindert — der Provider ist host-injiziert, nicht per Anfrage konfigurierbar); und Manipulation nach dem Signieren (der Byte-Range-Digest erkennt Modifikationen). Ein Bedrohungsmodell dokumentiert berücksichtigte Bedrohungen und Minderungen; es behauptet nicht die Abwesenheit von Schwachstellen.

FIPS-Modus-Verhalten

Die Algorithmusauswahl (RSA-SHA256, RSA + SHA-3, Ed25519) ist anfragegesteuert; das OpenSSL des Hosts stellt die kryptografischen Primitive bereit. Beschränken Sie den Algorithmus in einem FIPS-eingeschränkten Deployment auf Richtlinienebene und verlassen Sie sich auf das validierte Modul des Hosts. Dieses Tool behauptet selbst keine FIPS-Validierung.

Transportverfügbarkeit

Transport	Verfügbar	Hinweise
MCP (stdio)	Ja (Pro)	Verwenden Sie den AES-GCM-Schlüsselumschlag auf stdio.
REST	Ja (Pro)	Bevorzugen Sie TLS plus Schlüsselumschlag.
gRPC	Ja (Pro)	Bevorzugen Sie TLS plus Schlüsselumschlag.

HITL-Risikostufe

sign_pdf hat die Risikostufe Genehmigung erforderlich (ein destruktiver, irreversibler Vorgang — das Tool kündigt einen destruktiven Hinweis an). Das Bestätigungs-Gate gilt wie für jedes Tool mit Genehmigung erforderlich. output_pdf in eine Datei ist ebenfalls Genehmigung erforderlich; der base64-Modus ist Prüfung (HITL-Risikostufen).

Bestätigungs-Gate-JSON-Envelope

sign_pdf ohne gültiges Token gibt den Challenge-Envelope zurück:

{
  "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>"
}

Rufen Sie das Tool erneut auf, wobei _confirmation_token auf das Token gesetzt ist → { "allowed": true }. Vollständiger Ablauf: Ausgabegenehmigung.