💡 Exemple complet fonctionnel disponible sur GitHub : sign-pdf-with-vault-managed-key-java

L’ancienne méthode était pénible

Le runbook d’un service de signature Java a tendance à contenir une étape que personne n’aime écrire : copier signing.pfx vers le nouvel hôte, puis placer le mot de passe dans l’environnement. Dès ce moment, la clé privée existe dans au moins trois endroits supplémentaires que quiconque n’avait prévu. Elle se trouve dans la couche d’image, dans la sauvegarde de l’hôte, et dans la mémoire de la JVM qui la charge, où un dump de heap l’affichera volontiers à quiconque possède le dump.

La signature externe est une capacité de GroupDocs.Signature pour Java qui transmet le digest du document à un rappel que vous fournissez au lieu de signer avec une clé privée que l’application charge. C’est l’élément qui vous permet de supprimer cette étape du runbook. La clé de signature est déplacée dans HashiCorp Vault, le service conserve un jeton au lieu d’une clé, et la seule valeur qui traverse le réseau pendant la signature est un hash de 32 octets.

Les équipes utilisent cela lorsqu’une revue pose la question évidente — qui d’autre peut signer en votre nom — et la réponse honnête est « toute personne ayant eu accès à ce fichier ». Verrouiller le fichier avec des permissions et un volume chiffré réduit la fenêtre ; cela ne supprime pas la copie.

Il existe une meilleure façon

Le moteur Transit de Vault fournit la cryptographie en tant que service. Vous lui envoyez une valeur, il signe avec une clé qu’il détient, et il renvoie le résultat. Une clé créée dans Transit peut être marquée comme non exportable, il n’y a donc rien à copier sur un hôte dès le départ, et Vault ne stocke pas ce que vous lui envoyez.

Cela n’aide que si la bibliothèque de signature peut déléguer, ce qui est le rôle de GroupDocs.Signature. DigitalSignOptions.setCustomSignHash accepte un rappel. La bibliothèque fait tout jusqu’à la cryptographie : elle ouvre le PDF, détermine la plage d’octets couverte par la signature, le hache, appelle votre rappel avec le digest, puis intègre les octets retournés avec le certificat.

Vous avez besoin de JDK 8 ou supérieur, Maven, Docker pour un Vault local, et BouncyCastle pour le certificat. L’exemple fonctionne avec GroupDocs.Signature for Java 26.10 ; sans licence, le mode d’évaluation accepte les documents jusqu’à 2 pages.

La nouvelle méthode : un rappel au lieu d’un fichier de clé

Étape 1 - Lire la clé depuis Vault

Le service demande à Vault la clé qu’il est autorisé à utiliser et obtient un numéro de version avec une clé publique. La moitié privée n’est jamais présente dans la réponse.

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

Un 404 provenant de Vault signifie que la clé ou le point de montage Transit est manquant, donc l’exemple le traite comme une configuration de première exécution plutôt que comme une erreur. En production, un administrateur active Transit et crée la clé à l’avance, et le jeton de l’application n’est pas autorisé à faire l’une ou l’autre de ces actions.

Lisez la version une fois et conservez‑la. Un certificat ne contient qu’une seule clé publique, ainsi le certificat et chaque signature doivent provenir de la même version.

Étape 2 - Construire un certificat autour de la moitié publique

Une signature PDF porte un certificat X.509 afin qu’un vérificateur puisse trouver la clé publique. Le JDK ne permet pas de créer un certificat dont la signature provient d’ailleurs, mais BouncyCastle le fait : X509v3CertificateBuilder délègue à un ContentSigner, et un ContentSigner soutenu par Vault tient en environ quinze lignes.

@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 écrit les octets à signer dans le flux du signataire, puis demande la signature. Les octets sont hachés localement et seul le digest est envoyé à Vault. L’interface ne déclare aucune exception vérifiée, donc un échec de Vault doit être propagé enveloppé et dé‑enveloppé par l’appelant ; si l’on ignore cela, un 403 de Vault apparaît comme une erreur d’exécution déroutante.

Étape 3 - Signer, puis vérifier dans la même exécution

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

À l’intérieur du rappel, le digest est envoyé à transit/sign avec deux champs qui décident de la validité du résultat : prehashed = true, car l’entrée est déjà un hash, et signature_algorithm = pkcs1v15, car Vault utilise par défaut PSS pour les clés RSA alors qu’une signature PDF est sha256WithRSAEncryption.

Ensuite, vérifiez avant que le fichier ne parte nulle part. Signer et vérifier en une seule exécution transforme le seul mode d’échec silencieux en un échec immédiat.

Comparaison côte à côte : Avant vs. Après

PFX sur l’hôte Rappel Vault Transit
Copies de la clé privée une par hôte, image et sauvegarde une, à l’intérieur de Vault
Ce que le service détient la clé et son mot de passe un jeton limité à deux opérations
Étape de déploiement pour un nouvel hôte copier le PFX, définir le mot de passe rien
Enregistrement de chaque signature journaux d’application, si écrits une entrée d’audit Vault
Après une fuite suspectée révoquer, réémettre, redéployer partout faire pivoter dans Vault, réémettre une fois
Qui peut signer à votre place tout le monde avec le fichier et le mot de passe tout le monde avec un jeton Vault valide

La dernière ligne mérite d’être énoncée clairement : cela déplace le secret plutôt que de l’abolir. La différence réside dans le fait qu’un jeton est de courte durée, révoquable en un seul endroit, limité à la lecture d’une clé et à l’appel de la signature, et journalisé à chaque utilisation.

Exemple réel : un service de relevés

Un service génère des relevés mensuels et signe chacun d’eux avant de les déposer dans un portail client. Avec l’ancienne configuration, son image de conteneur transportait le certificat, et trois personnes connaissaient le mot de passe parce que quelqu’un devait le faire pivoter. Avec le rappel, l’image ne porte aucun secret : le pod obtient un jeton AppRole au démarrage, la politique dans vault/sample-signer.hcl autorise la lecture de la clé et la signature avec celle‑ci, et toute autre tentative du jeton renvoie 403 permission denied.

Lorsque l’auditeur demande combien de documents ont été signés en mars et avec quelle version de clé, la réponse provient du dispositif d’audit de Vault plutôt que d’un grep dans les journaux d’application.

La rotation est l’endroit où ce design justifie son existence, mais aussi où il peut poser problème. Après transit/keys/:name/rotate, Vault signe avec la version la plus récente sauf indication contraire, de sorte qu’un certificat construit pour la version 1 combiné à une signature de la version 2 produit un PDF qui ne signale aucune erreur et ne se vérifie pas. Comme le signataire est construit avec une version unique, cela ne peut pas se produire accidentellement ici : le service de relevés continue de signer avec la version à laquelle appartient son certificat jusqu’à ce que quelqu’un émette un nouveau certificat pour la nouvelle version. Fixer min_encryption_version sur la clé par la suite rend l’ancienne version inutilisable, ce que Vault signale comme un refus de signer plutôt que comme une mauvaise signature.

Quels particularités dois‑je attendre sur la version 26.10 ?

Quatre, toutes découvertes en exécutant cette construction. Le nom de méthode ICustomSignHash est obfusqué dans le JAR, donc passez une référence de méthode plutôt que d’implémenter l’interface. La sortie signée arrive avec des octets zéro de fin en dehors de la signature, il faut donc les tronquer. DigitalVerifyOptions attend un fichier de certificat, pas un flux. Et la boîte de signature visible nécessite Arial installé.

Que pouvez‑vous faire d’autre avec GroupDocs.Signature ?

Le rappel n’a aucune idée de ce qui se trouve derrière, ainsi les mêmes trois étapes fonctionnent contre un module matériel, une carte à puce ou un KMS cloud. J’ai porté cela depuis les versions .NET et Python du même exemple, et le corps de la requête Vault est resté inchangé ; la construction du certificat et ces quatre particularités sont les seules parties réellement spécifiques à Java. Au‑delà des signatures numériques, la bibliothèque ajoute et recherche des signatures texte, image, code‑barres, QR‑code et métadonnées dans les formats PDF, Word, Excel, PowerPoint et image.

Conclusion

Signer un PDF en Java sans détenir la clé privée nécessite un rappel, un certificat construit autour d’une clé publique, et un jeton avec deux droits. L’exemple fonctionne contre un Vault en mode dev en deux commandes, et le même code pointe vers un Vault de production en modifiant VAULT_ADDR et VAULT_TOKEN.

Ressources supplémentaires