💡 Kompletní funkční příklad dostupný na GitHubu:
sign-pdf-with-vault-managed-key-java

Starý způsob byl bolestivý

Postup pro Java podepisovací službu často obsahuje krok, který nikdo nechce zapisovat: zkopírovat signing.pfx na nový hostitel a poté nastavit heslo v prostředí. Od toho okamžiku existuje soukromý klíč na alespoň třech místech, než bylo zamýšleno. Je v obrazové vrstvě, v záloze hostitele a v paměti JVM, která jej načte, kde heap dump jej ochotně ukáže komukoli, kdo má dump.

Externí podepisování je schopnost GroupDocs.Signature pro Java, která předává otisk dokumentu vámi poskytnutému zpětnému volání místo podepisování soukromým klíčem, který aplikace načte. Je to část, která vám umožní odstranit tento krok z postupu. Podepisovací klíč se přesune do HashiCorp Vault, služba si místo klíče uchovává token a jediná hodnota, která během podepisování přejde po síti, je 32‑bajtový hash.

Týmy tuto možnost využívají, když recenze položí zřejmou otázku – kdo jiný může podepisovat vaším jménem – a upřímná odpověď zní „kdokoli, kdo kdy měl přístup k tomuto souboru“. Uzamčení souboru pomocí oprávnění a šifrovaného svazku zúží okno; neodstraní však kopii.

Existuje lepší způsob

Transit engine ve Vaultu poskytuje kryptografii jako službu. Pošlete mu hodnotu, on ji podepíše svým klíčem a vrátí výsledek. Klíč vytvořený v Transit může být označen jako neexportovatelný, takže na hostiteli není nic k kopírování, a Vault neukládá to, co mu pošlete.

To pomáhá jen tehdy, pokud podepisovací knihovna umí delegovat, což je místo, kde vstupuje GroupDocs.Signature. DigitalSignOptions.setCustomSignHash přijímá zpětné volání. Knihovna udělá vše až po kryptografii: otevře PDF, zjistí rozsah bajtů, které podpis pokrývá, vytvoří jejich hash, zavolá vaše zpětné volání s otiskem a poté vloží vrácené bajty spolu s certifikátem.

Potřebujete JDK 8 nebo novější, Maven, Docker pro lokální Vault a BouncyCastle pro certifikát. Ukázka běží s GroupDocs.Signature pro Java 26.10; bez licence režim hodnocení akceptuje dokumenty až do 2 stránek.

Nový způsob: zpětné volání místo souboru s klíčem

Krok 1 – Načtení klíče z Vaultu

Služba požádá Vault o klíč, který je oprávněna použít, a získá číslo verze s veřejným klíčem. Soukromá polovina v odpovědi nikdy není.

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

Chyba 404 od Vaultu znamená, že chybí buď klíč, nebo Transit mount, takže ukázka to interpretuje jako nastavení při prvním spuštění místo chyby. Ve výrobě administrátor nejprve povolí Transit a vytvoří klíč, a token aplikace není oprávněn provádět žádnou z těchto akcí.

Načtěte verzi jednou a uchovejte ji. Certifikát obsahuje právě jeden veřejný klíč, takže certifikát i každý podpis musí pocházet ze stejné verze.

Krok 2 – Vytvoření certifikátu kolem veřejné poloviny

PDF podpis nese X.509 certifikát, aby jej ověřovatel mohl najít veřejný klíč. JDK neumožňuje vytvořit certifikát, jehož podpis pochází z jiného zdroje, ale BouncyCastle ano: X509v3CertificateBuilder deleguje na ContentSigner a ContentSigner podporovaný Vaultem má asi patnáct řádků.

@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 zapíše podepisované bajty do proudu podepisovatele a poté požádá o podpis. Bajty jsou lokálně zahashovány a pouze otisk jde do Vaultu. Rozhraní nevyžaduje kontrolované výjimky, takže selhání Vaultu musí být předáno zabalené a rozbalené volajícím; pokud to vynecháte, 403 od Vaultu se projeví jako záhadná runtime chyba.

Krok 3 – Podepište a poté ověřte ve stejném běhu

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

Uvnitř zpětného volání se otisk posílá na transit/sign se dvěma poli, která rozhodují, zda je výsledek platný: prehashed = true, protože vstup je již hash, a signature_algorithm = pkcs1v15, protože Vault ve výchozím nastavení používá PSS pro RSA klíče, zatímco PDF podpis je sha256WithRSAEncryption.

Pak ověřte, než soubor kamkoli odejde. Podepisování a ověřování v jednom běhu převádí jediný tichý režim selhání na okamžité.

Vedle‑vedle: před vs. po

PFX na hostiteli Vault Transit zpětné volání
Kopie soukromého klíče jedna na hostitele, obraz a zálohu jedna, uvnitř Vaultu
Co služba drží klíč a jeho heslo token s rozsahem na dvě operace
Deploy krok pro nový hostitel zkopírovat PFX, nastavit heslo nic
Záznam o každém podpisu aplikační logy, pokud jsou zapisovány jeden auditní záznam Vaultu
Po podezření na únik odvolat, znovu vydat, nasadit všude rotovat ve Vaultu, jednou znovu vydat
Kdo může podepisovat za vás kdokoli se souborem a heslem kdokoli s platným Vault tokenem

Poslední řádek stojí za jasné vyjádření: přesouvá tajemství místo jeho zrušení. Rozdíl je v tom, že token je krátkodobý, odvolatelný na jednom místě, omezený na čtení jednoho klíče a volání sign, a je zaznamenán při každém použití.

Reálný příklad: služba výpisů

Služba generuje měsíční výpisy a každou před odesláním do zákaznického portálu podepíše. Ve starém uspořádání nesla kontejnerová image certifikát a tři lidé měli heslo, protože někdo ho musel rotovat. Se zpětným voláním image neobsahuje žádné tajemství: pod při startu získá AppRole token, politika v vault/sample-signer.hcl umožňuje číst klíč a podepisovat s ním, a jakýkoli jiný požadavek tokenu vrátí 403 permission denied.

Když auditor požádá, kolik dokumentů bylo v březnu podepsáno a kterou verzí klíče, odpověď pochází z auditního zařízení Vaultu místo prohledávání aplikačních logů.

Rotace je místo, kde tento návrh získává na hodnotě, ale také kde může kousnout. Po transit/keys/:name/rotate Vault podepisuje nejnovější verzí, pokud neřeknete jinak, takže certifikát vytvořený pro verzi 1 spojený s podpisem z verze 2 vytvoří PDF, který nehlásí chybu a neověří se. Protože podepisovatel je konstruován s jednou verzí, k tomu zde nedojde náhodou: služba výpisů bude nadále podepisovat verzí, ke které patří její certifikát, dokud někdo nevydá nový certifikát pro novou verzi. Nastavení min_encryption_version na klíči poté znemožní použití staré verze, což Vault hlásí jako odmítnutí podpisu místo špatného podpisu.

Jaké zvláštnosti mohu očekávat ve verzi 26.10?

Čtyři, všechny objevené během běhu této verze. Název metody ICustomSignHash je v jaru obfuskován, takže místo implementace rozhraní předávejte referenci na metodu. Podepsaný výstup obsahuje nulové bajty za podpisem, takže je potřeba je oříznout. DigitalVerifyOptions požaduje soubor certifikátu, ne proud. A viditelný podpisový rámeček vyžaduje nainstalovaný Arial.

Co dalšího můžete dělat s GroupDocs.Signature?

Zpětné volání neví, co je za ním, takže stejné tři kroky fungují i pro hardwarový modul, chytrou kartu nebo cloudové KMS. Přenesl jsem tuto ukázku z .NET a Python verzí stejného příkladu a tělo požadavku na Vault přišlo nezměněné; konstrukce certifikátu a ty čtyři zvláštnosti jsou jediné skutečně Java‑specifické části. Kromě digitálních podpisů knihovna také přidává a vyhledává text, obrázky, čárové kódy, QR kódy a metadata podpisů napříč PDF, Word, Excel, PowerPoint a obrazovými formáty.

Závěr

Podepsání PDF v Javě bez držení soukromého klíče vyžaduje zpětné volání, certifikát vytvořený kolem veřejného klíče a token se dvěma oprávněními. Ukázka běží proti dev‑mode Vaultu ve dvou příkazech a stejný kód lze nasměrovat na produkční Vault změnou VAINT_ADDR a VAULT_TOKEN.

Další zdroje