💡 Voll funktionsfähiges Beispiel auf GitHub verfügbar: sign-pdf-with-vault-managed-key-java
Der alte Weg war schmerzhaft
Das Runbook für einen Java‑Signing‑Service enthält häufig einen Schritt, den niemand gerne aufschreibt: signing.pfx auf den neuen Host kopieren und dann das Passwort in die Umgebung setzen. Ab diesem Moment existiert der private Schlüssel an mindestens drei weiteren Stellen, als beabsichtigt. Er befindet sich in der Image‑Schicht, im Backup des Hosts und im Speicher der JVM, die ihn lädt, wobei ein Heap‑Dump ihn jedem, der den Dump hat, problemlos zeigt.
Externes Signieren ist eine GroupDocs.Signature‑Funktion für Java, die den Dokument‑Digest an einen von Ihnen bereitgestellten Callback übergibt, anstatt mit einem privaten Schlüssel zu signieren, den die Anwendung lädt. Das ist das Bauteil, das Ihnen erlaubt, diesen Runbook‑Schritt zu entfernen. Der Signierschlüssel wird in HashiCorp Vault verschoben, der Service behält ein Token anstelle eines Schlüssels, und der einzige Wert, der beim Signieren über das Netzwerk geht, ist ein 32‑Byte‑Hash.
Teams greifen darauf zurück, wenn ein Review die offensichtliche Frage stellt – wer kann sonst in Ihrem Namen signieren – und die ehrliche Antwort lautet „jeder, der jemals Zugriff auf diese Datei hatte“. Das Sperren der Datei mit Berechtigungen und einem verschlüsselten Volume verkleinert das Zeitfenster; es entfernt die Kopie nicht.
Es gibt einen besseren Weg
Die Transit‑Engine von Vault bietet Kryptografie als Service. Sie senden ihr einen Wert, sie signiert mit einem Schlüssel, den sie hält, und gibt das Ergebnis zurück. Ein in Transit erstellter Schlüssel kann als nicht exportierbar markiert werden, sodass es überhaupt nichts gibt, das auf einen Host kopiert werden müsste, und Vault speichert nicht, was Sie ihr senden.
Das hilft nur, wenn die Signatur‑Bibliothek delegieren kann, und hier kommt GroupDocs.Signature ins Spiel. DigitalSignOptions.setCustomSignHash akzeptiert einen Callback. Die Bibliothek erledigt alles bis zur Kryptografie: Sie öffnet das PDF, ermittelt den Byte‑Bereich, den die Signatur abdeckt, hash‑t ihn, ruft Ihren Callback mit dem Digest auf und bettet anschließend die zurückgelieferten Bytes zusammen mit dem Zertifikat ein.
Sie benötigen JDK 8 oder höher, Maven, Docker für ein lokales Vault und BouncyCastle für das Zertifikat. Das Beispiel läuft mit GroupDocs.Signature for Java 26.10; ohne Lizenz akzeptiert der Evaluierungsmodus Dokumente von bis zu 2 Seiten.
Der neue Weg: ein Callback anstelle einer Schlüsseldatei
Schritt 1 – Schlüssel aus Vault lesen
Der Service fragt Vault nach dem Schlüssel, den er verwenden darf, und erhält eine Versionsnummer mit einem öffentlichen Schlüssel. Die private Hälfte ist nie in der Antwort enthalten.
VaultKey key = vault.readKey(KEY_NAME);
if (key == null) {
vault.enableTransit();
vault.createKey(KEY_NAME, "rsa-2048");
key = vault.readKey(KEY_NAME);
}
Ein 404 von Vault bedeutet, dass entweder der Schlüssel oder das Transit‑Mount fehlt, sodass das Beispiel dies als Erst‑Run‑Setup behandelt statt als Fehler. In der Produktion aktiviert ein Administrator Transit und erstellt den Schlüssel im Voraus, und das Token der Anwendung ist nicht berechtigt, beides zu tun.
Lesen Sie die Version einmal und behalten Sie sie. Ein Zertifikat enthält exakt einen öffentlichen Schlüssel, daher müssen das Zertifikat und jede Signatur aus derselben Version stammen.
Schritt 2 – Zertifikat um den öffentlichen Teil herum erstellen
Eine PDF‑Signatur trägt ein X.509‑Zertifikat, damit ein Prüfer den öffentlichen Schlüssel finden kann. Das JDK kann kein Zertifikat bauen, dessen Signatur von außen stammt, aber BouncyCastle kann: X509v3CertificateBuilder delegiert an einen ContentSigner, und ein von Vault unterstützter ContentSigner besteht aus etwa fünfzehn Zeilen.
@Override
public byte[] getSignature() {
try {
byte[] digest =
MessageDigest.getInstance("SHA-256").digest(data.toByteArray());
return vault.signHash(keyName, keyVersion, digest, "sha2-256");
} catch (IOException e) {
throw new UncheckedIOException(e);
}
}
BouncyCastle schreibt die zu signierenden Bytes in den Stream des Signierers und fordert anschließend die Signatur an. Die Bytes werden lokal gehasht und nur der Digest wird an Vault gesendet. Die Schnittstelle deklariert keine geprüften Ausnahmen, sodass ein Vault‑Fehler nach außen gewrappt und vom Aufrufer entwrappt werden muss; lässt man das weg, erscheint ein 403 von Vault als verwirrender Laufzeitfehler.
Schritt 3 – Signieren und dann im selben Durchlauf verifizieren
DigitalSignature digitalSignature = new DigitalSignature();
digitalSignature.setX509Certificate(certificate);
DigitalSignOptions options = new DigitalSignOptions();
options.setSignature(digitalSignature);
options.setCustomSignHash(signer::customSignHash);
options.setHashAlgorithm(HashAlgorithm.Sha256);
ByteArrayOutputStream signedPdf = new ByteArrayOutputStream();
signature.sign(signedPdf, options);
Files.write(outputPdf, trimTrailingZeros(signedPdf.toByteArray()));
Im Callback wird der Digest an transit/sign gesendet mit zwei Feldern, die entscheiden, ob das Ergebnis gültig ist: prehashed = true, weil die Eingabe bereits ein Hash ist, und signature_algorithm = pkcs1v15, weil Vault standardmäßig PSS für RSA‑Schlüssel verwendet, während eine PDF‑Signatur sha256WithRSAEncryption ist.
Anschließend verifizieren Sie, bevor die Datei irgendwohin geht. Signieren und Verifizieren in einem Durchlauf verwandelt den einzigen stillen Fehlermodus in einen sofortigen.
Gegenüberstellung: Vorher vs. Nachher
| PFX auf dem Host | Vault Transit Callback | |
|---|---|---|
| Kopien des privaten Schlüssels | eine pro Host, Image und Backup | eine, innerhalb von Vault |
| Was der Dienst hält | der Schlüssel und sein Passwort | ein Token, das auf zwei Vorgänge beschränkt ist |
| Bereitstellungsschritt für einen neuen Host | PFX kopieren, Passwort setzen | nichts |
| Aufzeichnung jeder Signatur | Anwendungsprotokolle, falls geschrieben | ein Vault‑Audit‑Eintrag |
| Nach einem vermuteten Leak | widerrufen, neu ausstellen, überall neu bereitstellen | in Vault rotieren, einmal neu ausstellen |
| Wer kann in Ihrem Namen signieren | jeder mit der Datei und dem Passwort | jeder mit einem gültigen Vault‑Token |
Die letzte Zeile sollte man klar formulieren: Hier wird das Geheimnis verschoben, nicht abgeschafft. Der Unterschied besteht darin, dass ein Token kurzlebig, an einer Stelle widerrufbar, auf das Lesen eines Schlüssels und das Aufrufen von Sign beschränkt und jedes Mal protokolliert wird, wenn es verwendet wird.
Praxisbeispiel: ein Abrechnungsservice
Ein Service erzeugt monatliche Abrechnungen und signiert jede, bevor sie im Kunden‑Portal abgelegt wird. Beim alten Setup trug das Container‑Image das Zertifikat, und drei Personen kannten das Passwort, weil jemand es rotieren musste. Mit dem Callback enthält das Image überhaupt kein Geheimnis: Das Pod erhält beim Start ein AppRole‑Token, die Richtlinie in vault/sample-signer.hcl erlaubt das Lesen des Schlüssels und das Signieren damit, und alles andere, was das Token versucht, liefert 403 permission denied.
Fragt der Prüfer, wie viele Dokumente im März signiert wurden und mit welcher Schlüssel‑Version, so stammt die Antwort aus dem Vault‑Audit‑Device statt aus dem Durchsuchen von Anwendungs‑Logs.
Rotation ist der Punkt, an dem dieses Design seinen Nutzen beweist – und zugleich, wo es Probleme geben kann. Nach transit/keys/:name/rotate signiert Vault mit der neuesten Version, sofern Sie nicht etwas anderes angeben, sodass ein für Version 1 gebautes Zertifikat kombiniert mit einer Signatur aus Version 2 ein PDF erzeugt, das keinen Fehler meldet, aber nicht verifiziert werden kann. Da der Signierer mit einer Version konstruiert wird, kann das hier nicht versehentlich passieren: Der Abrechnungsservice signiert weiter mit der Version, zu der sein Zertifikat gehört, bis jemand ein neues Zertifikat für die neue Version ausstellt. Das Setzen von min_encryption_version auf dem Schlüssel danach macht die alte Version unbrauchbar, was Vault als Verweigerung der Signatur meldet und nicht als fehlerhafte Signatur.
Welche Eigenheiten sollte ich bei Version 26.10 erwarten?
Vier, alle beim Ausführen dieses Builds entdeckt. Der Methodenname ICustomSignHash ist im JAR obfuskiert, daher übergeben Sie eine Method‑Referenz statt die Schnittstelle zu implementieren. Die signierte Ausgabe enthält nach dem Signatur‑Block nachgestellte Null‑Bytes, die Sie abschneiden müssen. DigitalVerifyOptions erwartet eine Zertifikats‑Datei, keinen Stream. Und das sichtbare Signatur‑Feld benötigt die Schriftart Arial.
Was kann man sonst noch mit GroupDocs.Signature machen?
Der Callback weiß nicht, was dahinter steckt, sodass dieselben drei Schritte gegen ein Hardware‑Modul, eine Smart‑Card oder ein Cloud‑KMS funktionieren. Ich habe das Beispiel aus den .NET‑ und Python‑Versionen desselben Samples portiert, und der Vault‑Request‑Body kam unverändert an; die Zertifikatserstellung und diese vier Eigenheiten sind die einzigen wirklich Java‑spezifischen Teile. Neben digitalen Signaturen fügt die Bibliothek auch Text‑, Bild‑, Barcode‑, QR‑Code‑ und Metadaten‑Signaturen hinzu und sucht sie in PDF, Word, Excel, PowerPoint und Bildformaten.
Fazit
Ein PDF in Java zu signieren, ohne den privaten Schlüssel zu besitzen, erfordert einen Callback, ein um einen öffentlichen Schlüssel gebautes Zertifikat und ein Token mit zwei Rechten. Das Beispiel läuft gegen ein Dev‑Mode‑Vault in zwei Befehlen, und derselbe Code kann auf ein Produktions‑Vault umgestellt werden, indem VAULT_ADDR und VAULT_TOKEN geändert werden.