docs: pdf_siegel.md – Trust-Hinweis + SAPP-ByteRange-Fix

tasks/pdf_siegel.md

@@ -1,8 +1,18 @@
 # `pdf_siegel` — PDF kryptografisch siegeln (PAdES-T, Zeitstempel, Grund)
 
-**Zweck:** Siegelt eine PDF mit dem VLN-Organisationszertifikat (`autosign.p12`) als **PAdES-T**-Signatur inkl. **DigiCert-Zeitstempel (LTV)** und optionalem **Signatur-Grund**. Unsichtbare Signatur; in Acrobat als „Grund"/„Zeitstempel" in den Unterschrifteneigenschaften sichtbar, langzeit-validierbar. Rechtlich = **AES** (Org-Soft-Zertifikat, keine QES).
+**Zweck:** Siegelt eine PDF mit dem VLN-Organisationszertifikat (`autosign.p12`) als **PAdES-T**-Signatur inkl. **DigiCert-Zeitstempel (LTV)** und optionalem **Signatur-Grund**. Unsichtbare Signatur; in Acrobat als „Grund" / „Zeitstempel" in den Unterschrifteneigenschaften sichtbar, langzeit-validierbar. Rechtlich = **AES** (Org-Soft-Zertifikat, keine QES).
 
-**Parameter**
+## ⚠️ Wichtig: „Identität nicht bestätigt" in Acrobat ist normal
+
+Das VLN-Zertifikat ist eine **eigene CA** (kein öffentlich verankertes Root-Zertifikat). Acrobat/Reader zeigt deshalb zunächst:
+
+- „Unterschrieben von **Unbekannt**" / „Identität des Unterzeichners wurde noch nicht bestätigt"
+
+Das ist **kein Fehler der Signatur** — kryptografisch ist sie gültig und das Dokument nachweislich unverändert (poppler: *„Signature is Valid / Total document signed"*). Es ist reine **Vertrauensfrage**. Voll grün wird es erst, wenn die **VLN-Stamm-CA** einmalig in Acrobat unter *Vertrauenswürdige Zertifikate* importiert wird — oder man ein öffentlich vertrautes/QES-Zertifikat kauft.
+
+Wenn Acrobat dagegen **„SigDict /Contents illegal data"** oder **„ungültig"** meldet, ist die Signatur strukturell kaputt — das war ein SAPP-Bug (siehe unten), inzwischen behoben.
+
+## Parameter
 
 | Name | Pflicht? | Default | Beschreibung |
 |---|---|---|---|
@@ -14,7 +24,7 @@
 | `output` | nein | Temp | Ausgabepfad. |
 | `output_var` | nein | `siegel` | Ergebnis-Präfix; setzt auch `latest_pdf_path`. |
 
-**Ausgangswerte**
+## Ausgangswerte
 
 | Variable | Beschreibung |
 |---|---|
@@ -22,7 +32,7 @@
 | `{{<prefix>_name}}` | Dateiname |
 | `{{latest_pdf_path}}` | = gesiegelte PDF |
 
-**Beispiel**
+## Beispiel
 
 ```xml
 <task type="pdf_siegel" id="siegeln">
@@ -35,8 +45,8 @@
 </task>
 ```
 
-**Technik / Hinweise**
+## Technik / Hinweise
 
-- Nutzt `pdfsign_tsa()` (require-sign.php / SAPP). **Nur dieser Weg macht echten RFC-3161-Zeitstempel** — die `tsa`-Option des alten `pdf_sign` (TCPDF) ist wirkungslos.
-- Poppler `pdfsig` meldet fälschlich „Illegal ByteRange" — Acrobat akzeptiert die Signatur.
+- Nutzt `pdfsign_tsa()` (require-sign.php / SAPP). **Nur dieser Weg macht einen echten RFC-3161-Zeitstempel** — die `tsa`-Option des alten `pdf_sign` (TCPDF) ist wirkungslos.
+- **Robustheits-Fix (2026-07-04):** SAPP maß die Signaturlänge mit *einem* TSA-Abruf und signierte dann mit einem *zweiten* — RFC-3161-Tokens variieren um wenige Bytes, wodurch die reservierte `/Contents`-Länge nicht zur echten passte → ByteRange verrechnet → in Acrobat „illegal data / Digest Mismatch". Gepatcht in `PDFDoc.php` (Reserve-Marge + `/Contents` auf reservierte Länge auffüllen). Zusätzlich prüft `pdfsign_tsa()` nach dem Schreiben die ByteRange-Konsistenz und wirft bei Abweichung eine Exception (keine still-kaputten Siegel mehr).
 - Für **QES** (rechtsverbindlich = handschriftlich) wäre ein QTSP nötig; dies ist AES.