💡 Esempio completo funzionante disponibile su GitHub:
sign-pdf-with-vault-managed-key-java

Il vecchio modo era doloroso

Il runbook per un servizio di firma Java tende a contenere un passaggio che nessuno ama scrivere: copiare signing.pfx sul nuovo host, poi inserire la password nell’ambiente. Da quel momento la chiave privata esiste in almeno tre posti in più rispetto a quanto previsto. È nello strato dell’immagine, nel backup dell’host e nella memoria della JVM che la carica, dove un dump della heap la mostrerà felicemente a chiunque abbia il dump.

La firma esterna è una funzionalità di GroupDocs.Signature per Java che consegna il digest del documento a un callback fornito da te invece di firmare con una chiave privata che l’applicazione carica. È la parte che ti permette di eliminare quel passaggio del runbook. La chiave di firma si sposta in HashiCorp Vault, il servizio conserva un token invece di una chiave, e l’unico valore che attraversa il filo durante la firma è un hash di 32 byte.

I team ricorrono a questa soluzione quando una revisione pone la domanda ovvia – chi altro può firmare a tuo nome – e la risposta onesta è “chiunque abbia avuto accesso a quel file”. Bloccare il file con permessi e un volume crittografato restringe la finestra; non rimuove la copia.

C’è un modo migliore

Il motore Transit di Vault fornisce la crittografia come servizio. Gli invii un valore, firma con una chiave che possiede e restituisce il risultato. Una chiave creata all’interno di Transit può essere contrassegnata come non esportabile, quindi non c’è nulla da copiare su un host in primo luogo, e Vault non memorizza ciò che gli invii.

Ciò aiuta solo se la libreria di firma può delegare, ed è qui che entra in gioco GroupDocs.Signature. DigitalSignOptions.setCustomSignHash accetta un callback. La libreria fa tutto fino alla crittografia: apre il PDF, determina l’intervallo di byte coperto dalla firma, lo hash, chiama il tuo callback con il digest, poi incorpora i byte restituiti insieme al certificato.

Hai bisogno di JDK 8 o successivo, Maven, Docker per un Vault locale e BouncyCastle per il certificato. L’esempio funziona con GroupDocs.Signature per Java 26.10; senza licenza, la modalità di valutazione accetta documenti fino a 2 pagine.

Il nuovo modo: un callback invece di un file chiave

Passo 1 – Leggi la chiave da Vault

Il servizio chiede a Vault la chiave che è autorizzato a usare e ottiene un numero di versione con una chiave pubblica. La metà privata non è mai presente nella risposta.

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

Un 404 da Vault significa che la chiave o il mount Transit mancano, quindi l’esempio lo tratta come configurazione al primo avvio anziché come errore. In produzione un amministratore abilita Transit e crea la chiave in anticipo, e il token dell’applicazione non è autorizzato a fare nessuna delle due cose.

Leggi la versione una volta e conservala. Un certificato contiene esattamente una chiave pubblica, quindi il certificato e ogni firma devono provenire dalla stessa versione.

Passo 2 – Costruisci un certificato attorno alla metà pubblica

Una firma PDF contiene un certificato X.509 affinché un verificatore possa trovare la chiave pubblica. Il JDK non ha modo di costruire un certificato la cui firma provenga da altrove, ma BouncyCastle lo fa: X509v3CertificateBuilder delega a un ContentSigner, e un ContentSigner supportato da Vault è di circa quindici righe.

@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 scrive i byte da firmare nello stream del firmatario e poi richiede la firma. I byte vengono hashati localmente e solo il digest viene inviato a Vault. L’interfaccia non dichiara eccezioni controllate, quindi un fallimento di Vault deve viaggiare fuori avvolto e poi essere deavvolto dal chiamante; se lo si ignora, un 403 da Vault appare come un errore di runtime inspiegabile.

Passo 3 – Firma, poi verifica nella stessa esecuzione

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

All’interno del callback il digest viene inviato a transit/sign con due campi che decidono se il risultato è valido: prehashed = true, perché l’input è già un hash, e signature_algorithm = pkcs1v15, perché Vault usa PSS per le chiavi RSA mentre una firma PDF è sha256WithRSAEncryption.

Poi verifica prima che il file vada da qualche parte. Firmare e verificare in un’unica esecuzione è ciò che trasforma l’unica modalità di fallimento silenzioso in una immediata.

Confronto affiancato: Prima vs. Dopo

PFX sull’host Callback Transit di Vault
Copie della chiave privata una per host, immagine e backup una, dentro Vault
Cosa trattiene il servizio la chiave e la sua password un token limitato a due operazioni
Passo di distribuzione per un nuovo host copia il PFX, imposta la password niente
Registro di ogni firma log dell’applicazione, se scritti una voce di audit di Vault
Dopo una perdita sospetta revoca, riemissione, ridistribuzione ovunque rotazione in Vault, riemissione una sola volta
Chi può firmare al tuo posto chiunque abbia il file e la password chiunque abbia un token Vault valido

L’ultima riga vale la pena affermare chiaramente: questo sposta il segreto invece di abolirlo. La differenza è che un token è a breve durata, revocabile in un unico punto, limitato alla lettura di una chiave e alla chiamata di firma, e registrato ogni volta che viene usato.

Esempio reale: un servizio di estratti conto

Un servizio genera estratti conto mensili e firma ciascuno prima di inserirlo in un portale cliente. Con la vecchia configurazione la sua immagine del container trasportava il certificato, e tre persone conoscevano la password perché qualcuno doveva ruotarla. Con il callback, l’immagine non contiene alcun segreto: il pod ottiene un token AppRole all’avvio, la policy in vault/sample-signer.hcl consente di leggere la chiave e firmare con essa, e qualsiasi altra operazione del token restituisce 403 permission denied.

Quando l’auditor chiede quanti documenti sono stati firmati a marzo e con quale versione di chiave, la risposta proviene dal dispositivo di audit di Vault anziché dal grep dei log dell’applicazione.

La rotazione è dove questo design dimostra il suo valore, ma anche dove può creare problemi. Dopo transit/keys/:name/rotate Vault firma con la versione più recente a meno che non si specifichi diversamente, quindi un certificato costruito per la versione 1 combinato con una firma della versione 2 produce un PDF che non segnala errori ma non verifica. Poiché il firmatario è costruito con una sola versione, ciò non può accadere per caso qui: il servizio di estratti continua a firmare con la versione a cui appartiene il suo certificato finché qualcuno non emette un nuovo certificato per la nuova versione. Impostare min_encryption_version sulla chiave in seguito rende inutilizzabile la vecchia versione, e Vault lo segnala come rifiuto di firma anziché come firma errata.

Quali stranezze devo aspettarmi nella versione 26.10?

Quattro, tutte scoperte durante la compilazione di questo esempio. Il nome del metodo ICustomSignHash è offuscato nel jar, quindi passa un riferimento a metodo anziché implementare l’interfaccia. L’output firmato arriva con byte zero finali al di fuori della firma, quindi è necessario rimuoverli. DigitalVerifyOptions richiede un file certificato, non uno stream. E la casella della firma visibile richiede Arial installato.

Cos’altro puoi fare con GroupDocs.Signature?

Il callback non sa cosa ci sia dietro, quindi gli stessi tre passaggi funzionano con un modulo hardware, una smart card o un KMS cloud. Ho portato questo esempio dalle versioni .NET e Python dello stesso campione, e il corpo della richiesta a Vault è arrivato invariato; la costruzione del certificato e quelle quattro stranezze sono le uniche parti realmente specifiche di Java. Oltre alle firme digitali, la libreria aggiunge e ricerca firme di testo, immagine, codice a barre, QR code e metadati su PDF, Word, Excel, PowerPoint e formati immagine.

Conclusione

Firmare un PDF in Java senza detenere la chiave privata richiede un callback, un certificato costruito attorno a una chiave pubblica e un token con due diritti. L’esempio funziona contro un Vault in modalità dev con due comandi, e lo stesso codice punta a un Vault di produzione modificando VAINT_ADDR e VAULT_TOKEN.

Risorse aggiuntive