💡 Volledig werkend voorbeeld beschikbaar op GitHub: sign-pdf-with-vault-managed-key-java

De oude manier was pijnlijk

Het draaiboek voor een Java‑ondertekeningsservice bevat vaak een stap die niemand graag opschrijft: signing.pfx kopiëren naar de nieuwe host en vervolgens het wachtwoord in de omgeving plaatsen. Vanaf dat moment bestaat de privésleutel op minstens drie andere plaatsen dan bedoeld. Hij zit in de imagelaag, in de back‑up van de host en in het geheugen van de JVM die hem laadt, waar een heap‑dump hem vrolijk toont aan iedereen die de dump heeft.

Extern ondertekenen is een GroupDocs.Signature‑functionaliteit voor Java die de document‑digest doorgeeft aan een callback die je levert in plaats van te ondertekenen met een privésleutel die de applicatie laadt. Het is het onderdeel dat je die stap uit het draaiboek laat verwijderen. De ondertekeningssleutel wordt verplaatst naar HashiCorp Vault, de service houdt een token in plaats van een sleutel, en de enige waarde die tijdens het ondertekenen over het netwerk gaat, is een 32‑byte hash.

Teams grijpen hiernaar wanneer een review de voor de hand liggende vraag stelt – wie kan er nog meer in jouw naam ondertekenen – en het eerlijke antwoord is “iedereen die ooit toegang had tot dat bestand”. Het bestand beveiligen met permissies en een versleuteld volume verkleint het venster; het verwijdert de kopie niet.

Er is een betere manier

Vault’s Transit‑engine biedt cryptografie als een service. Je stuurt er een waarde naartoe, het ondertekent met een sleutel die het bezit, en het retourneert het resultaat. Een sleutel die binnen Transit wordt aangemaakt, kan gemarkeerd worden als niet‑exporteerbaar, zodat er in de eerste plaats niets naar een host gekopieerd hoeft te worden, en Vault slaat niet op wat je stuurt.

Dat helpt alleen als de ondertekeningsbibliotheek kan delegeren, en daar komt GroupDocs.Signature in beeld. DigitalSignOptions.setCustomSignHash accepteert een callback. De bibliotheek doet alles tot aan de cryptografie: hij opent de PDF, bepaalt het byte‑bereik dat de handtekening dekt, maakt er een hash van, roept jouw callback aan met de digest, en voegt vervolgens de terugontvangen bytes samen met het certificaat in.

Je hebt JDK 8 of hoger, Maven, Docker voor een lokale Vault en BouncyCastle voor het certificaat nodig. Het voorbeeld draait met GroupDocs.Signature voor Java 26.10; zonder licentie accepteert de evaluatiemodus documenten van maximaal 2 pagina’s.

De nieuwe manier: een callback in plaats van een sleutelbestand

Stap 1 – Lees de sleutel uit Vault

De service vraagt Vault om de sleutel die hij mag gebruiken en krijgt een versienummer met een openbare sleutel. Het private deel zit nooit in de respons.

VaultKey key = vault.readKey(KEY_NAME);
if (key == null) {
    vault.enableTransit();
    vault.createKey(KEY_NAME, "rsa-2048");
    key = vault.readKey(KEY_NAME);
}

Een 404‑antwoord van Vault betekent dat of de sleutel of de Transit‑mount ontbreekt, dus het voorbeeld behandelt dit als een eerste‑run‑setup in plaats van een fout. In productie schakelt een beheerder Transit in en maakt de sleutel vooraf aan, en het token van de applicatie mag geen van beide uitvoeren.

Lees de versie één keer en bewaar die. Een certificaat bevat precies één openbare sleutel, dus het certificaat en elke handtekening moeten van dezelfde versie afkomstig zijn.

Stap 2 – Bouw een certificaat rond de openbare helft

Een PDF‑handtekening bevat een X.509‑certificaat zodat een verifier de openbare sleutel kan vinden. De JDK biedt geen manier om een certificaat te bouwen waarvan de handtekening van elders komt, maar BouncyCastle wel: X509v3CertificateBuilder delegeert aan een ContentSigner, en een ContentSigner ondersteund door Vault bestaat uit ongeveer vijftien regels.

@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 schrijft de te ondertekenen bytes naar de stream van de ondertekenaar en vraagt vervolgens om de handtekening. De bytes worden lokaal gehasht en alleen de digest gaat naar Vault. De interface verklaart geen checked exceptions, dus een Vault‑fout moet verpakt worden en door de aanroeper worden uitgepakt; sla dat over en een 403‑antwoord van Vault verschijnt als een raadselachtige runtime‑fout.

Stap 3 – Onderteken, en verifieer vervolgens in dezelfde run

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()));

Binnen de callback gaat de digest naar transit/sign met twee velden die bepalen of het resultaat geldig is: prehashed = true, omdat de invoer al een hash is, en signature_algorithm = pkcs1v15, omdat Vault standaard PSS gebruikt voor RSA‑sleutels terwijl een PDF‑handtekening sha256WithRSAEncryption vereist.

Verifieer daarna voordat het bestand ergens heen gaat. Ondertekenen en verifiëren in één run is wat de enige stille foutmodus omzet in een directe.

Zij‑aan‑zij: vóór vs. daarna

PFX op de host Vault Transit‑callback
Kopieën van de privésleutel één per host, image en backup één, binnen Vault
Wat de service bezit de sleutel en het wachtwoord een token met twee rechten
Deploy‑stap voor een nieuwe host kopieer de PFX, stel het wachtwoord in niets
Registratie van elke handtekening applicatielogs, indien geschreven één Vault‑audit‑entry
Na een vermoedelijke lek intrekken, opnieuw uitgeven, overal opnieuw deployen roteren in Vault, één keer opnieuw uitgeven
Wie kan namens jou ondertekenen iedereen met het bestand en wachtwoord iedereen met een geldig Vault‑token

De laatste rij is het waard om duidelijk te stellen: dit verplaatst het geheim in plaats van het te elimineren. Het verschil is dat een token kort‑levend is, op één plek intrekbaar, beperkt tot het lezen van één sleutel en het aanroepen van sign, en elke keer dat het wordt gebruikt wordt gelogd.

Praktijkvoorbeeld: een afschriftservice

Een service genereert maandelijkse afschriften en ondertekent elk exemplaar voordat het in een klantportaal wordt geplaatst. Met de oude opzet droeg de container‑image het certificaat, en drie personen hadden het wachtwoord omdat iemand het moest roteren. Met de callback bevat de image helemaal geen geheim: de pod krijgt bij opstarten een AppRole‑token, het beleid in vault/sample-signer.hcl staat lezen van de sleutel en ondertekenen ermee toe, en alles wat het token probeert te doen resulteert in 403 permission denied.

Wanneer de auditor vraagt hoeveel documenten er in maart zijn ondertekend en met welke sleutelversie, komt het antwoord uit het audit‑apparaat van Vault in plaats van uit het doorzoeken van applicatielogs.

Rotatie is waar dit ontwerp zijn waarde bewijst, en ook waar het kan bijten. Na transit/keys/:name/rotate ondertekent Vault met de nieuwste versie tenzij je iets anders aangeeft, dus een certificaat gebouwd voor versie 1 gecombineerd met een handtekening van versie 2 levert een PDF op die geen fout meldt en niet verifieert. Omdat de ondertekenaar is geconstrueerd met één versie, kan dat hier niet per ongeluk gebeuren: de afschriftservice blijft ondertekenen met de versie waar het certificaat bij hoort totdat iemand een nieuw certificaat voor de nieuwe versie uitgeeft. Het later instellen van min_encryption_version op de sleutel maakt de oude versie onbruikbaar, wat Vault meldt als een weigering om te ondertekenen in plaats van als een slechte handtekening.

Welke eigenaardigheden kan ik verwachten in versie 26.10?

Vier, allemaal ontdekt tijdens het uitvoeren van deze build. De ICustomSignHash‑methodenaam is geobfusceerd in de jar, dus geef een methodereferentie door in plaats van de interface te implementeren. De ondertekende output bevat nulbytes achter de handtekening, dus knip die af. DigitalVerifyOptions verwacht een certificaatbestand, geen stream. En het zichtbare handtekeningvak vereist dat Arial geïnstalleerd is.

Wat kun je nog meer doen met GroupDocs.Signature?

De callback weet niet wat erachter zit, dus dezelfde drie stappen werken tegen een hardware‑module, een smartcard of een cloud‑KMS. Ik heb dit geport naar de .NET‑ en Python‑versies van hetzelfde voorbeeld, en de Vault‑request‑body kwam ongewijzigd binnen; de certificaatconstructie en die vier eigenaardigheden zijn de enige echt Java‑specifieke delen. Naast digitale handtekeningen voegt de bibliotheek ook tekst, afbeelding, barcode, QR‑code en metadata‑handtekeningen toe en zoekt die in PDF, Word, Excel, PowerPoint en afbeeldingsformaten.

Conclusie

Een PDF ondertekenen in Java zonder de privésleutel te bezitten vereist een callback, een certificaat gebouwd rond een openbare sleutel, en een token met twee rechten. Het voorbeeld draait tegen een dev‑mode Vault in twee commando’s, en dezelfde code wijst naar een productie‑Vault door VAULT_ADDR en VAULT_TOKEN aan te passen.

Aanvullende bronnen