Comment générer une CSR pour un certificat de signature de code avec Java Keytool

L’utilitaire keytool, fourni avec le Java Development Kit (JDK), crée une paire de clés dans un keystore Java et la transforme en CSR (Certificate Signing Request), le bloc encodé qu’une autorité de certification (CA) lit pour vous identifier avant d’émettre un certificat. Pour la signature de code, l’usage légitime de keytool a changé le 1er juin 2023. Ce guide énonce d’abord la règle, puis passe en revue les commandes keytool qui restent correctes : sur un keystore logiciel pour la signature interne, et sur un jeton matériel ou un HSM via PKCS#11.

Les clés de signature de code doivent être générées sur du matériel

Depuis le 1er juin 2023, les exigences de référence du CA/Browser Forum pour la signature de code imposent que la clé privée de tout certificat de signature de code publiquement approuvé soit générée et stockée dans un module cryptographique matériel conforme au niveau FIPS 140-2 Level 2, aux Critères Communs EAL4+, ou à une norme équivalente. La clé doit être non exportable. Cela s’applique aussi bien aux certificats standard (validation d’organisation) qu’aux certificats à validation étendue. Les certificats EV de signature de code ont toujours exigé du matériel ; le changement de 2023 a étendu la même règle aux certificats standard. Ces mêmes exigences fixent une taille de clé minimale de RSA 3072 pour les certificats de signature de code, en vigueur depuis le 1er juin 2021.

La conséquence pour cette page est directe. Un fichier keystore que keytool crée sur votre ordinateur portable ou votre serveur, qu’il soit au format PKCS12 ou à l’ancien format JKS, contient une clé logicielle. Un CSR généré à partir de celui-ci n’est pas accepté par une autorité de certification publique pour un certificat de signature de code. Les autorités de certification ont cessé de prendre en charge la génération de clés dans le navigateur et les fichiers de clés téléchargeables pour ces produits. Votre clé provient désormais de l’un de ces deux endroits :

• Un jeton préconfiguré que la CA vous envoie. La CA génère la paire de clés et le CSR sur un jeton USB certifié de son côté, y charge le certificat émis, et vous envoie le jeton par courrier. Il n’y a aucun CSR à créer de votre côté.
• Votre propre HSM ou jeton, avec attestation de clé. Vous générez la clé à l’intérieur du dispositif, produisez un CSR à partir de celle-ci, et soumettez un fichier d’attestation qui prouve à la CA que la clé a été créée sur du matériel conforme et ne peut pas être exportée. Les deux éléments sont requis ; un CSR sans attestation valide est rejeté.

Le choix de la méthode se fait lors de la commande. Pour la comparaison, consultez les méthodes de livraison des certificats de signature de code. Si vous possédez déjà du matériel conforme, suivez le guide correspondant à votre dispositif : génération de CSR et attestation pour YubiKey 5 FIPS ou le guide de CSR et d’attestation pour Luna Network Attached HSM v7.x.

Où keytool reste pertinent

Rien de ce qui précède ne rend keytool obsolète. Il reste l’outil approprié dans trois situations, et seule la première produit un CSR que vous pouvez envoyer à une CA publique :

• En tant qu’interface PKCS#11 vers votre jeton ou HSM. keytool parle nativement PKCS#11. Pointez-le vers la bibliothèque PKCS#11 de votre fournisseur et la clé ne quitte jamais le dispositif, tandis que la commande familière -certreq produit toujours le CSR. Les commandes figurent dans la section matérielle ci-dessous.
• Pour la signature interne ou d’entreprise. Si vous signez un logiciel interne avec la propre CA de votre organisation, votre politique interne régit le stockage des clés, et non les exigences de référence publiques. Un keystore logiciel y est un choix normal.
• Pour s’entraîner. Obtenir le bon nom d’objet dès la première tentative est plus facile si vous avez déjà répondu aux invites une fois sur un keystore jetable.

Une limite à connaître avant de commencer : keytool ne génère pas d’attestation de clé. L’attestation est produite par l’outillage propre du fournisseur du jeton ou du HSM, donc même sur la voie PKCS#11, vous utiliserez l’utilitaire du fournisseur pour ce fichier et keytool uniquement pour le CSR.

Générer le CSR avec keytool

Si vous avez déjà créé votre CSR et que l’autorité de certification a émis le certificat, passez directement à l’importation de la réponse de la CA, l’étape qui échoue silencieusement lorsque l’alias ne correspond pas.

keytool est fourni avec le JDK, installez donc d’abord un JDK actuel si vous n’en avez pas. JDK 25 est la version actuelle à support à long terme et JDK 26 est la version actuelle à support à court terme. Les commandes ci-dessous fonctionnent sur JDK 17 et versions ultérieures, et les différences de version qui comptent sont notées lorsqu’elles se présentent. Confirmez que l’outil est dans votre chemin :

java -version
keytool -help
jarsigner -version

Un environnement d’exécution Java (JRE) seul ne suffit pas, et un keytool fonctionnel ne prouve pas que vous disposez d’un JDK : l’ancien Oracle JRE 8 fournit keytool mais pas jarsigner. Exécutez les trois commandes maintenant. Si les deux premières répondent et pas la troisième, vous êtes sur un JRE, et installer un JDK à ce stade est plus simple que de le découvrir au moment de signer.

Étape 1 : Créer le keystore et la paire de clés

Exécutez ceci dans un terminal, ou dans l’Invite de commandes ou PowerShell sous Windows, depuis le répertoire où vous voulez que le fichier keystore se trouve :

keytool -genkeypair -alias codesign -keyalg RSA -keysize 3072 -storetype PKCS12 -keystore codesign.p12

Quatre détails de cette commande diffèrent des anciennes instructions, et chacun compte :

• -genkeypair, et non -genkey. L’ancienne orthographe -genkey fonctionne toujours et keytool n’affiche aucun avertissement à ce sujet, mais elle n’est conservée dans le code source qu’en tant qu’alias hérité et n’apparaît plus nulle part dans la documentation du JDK. Écrivez -genkeypair.
• -storetype PKCS12, et non JKS. JKS est le format de keystore propriétaire d’Oracle. PKCS12 est le format standard du secteur et constitue le format par défaut du JDK depuis Java 9. Si vous créez quand même un keystore JKS, keytool vous avertit à chaque commande le concernant : « The JKS keystore uses a proprietary format. It is recommended to migrate to PKCS12 which is an industry standard format. »
• Le nom du fichier ne détermine pas le format. Nommer un fichier keystore.jks ne fait pas de lui un keystore JKS. keytool détermine le type à partir de -storetype, ou de la propriété keystore.type dans le fichier de sécurité du JDK lorsque vous l’omettez. Sur JDK 9 et versions ultérieures, cette propriété vaut pkcs12, donc une commande qui écrit dans keystore.jks sans -storetype produit silencieusement un fichier PKCS12 au nom trompeur.
• -keysize 3072, et non 2048. Les exigences de référence fixent RSA 3072 comme minimum pour la signature de code, donc une demande en 2048 bits est rejetée. Les JDK actuels utilisent par défaut 3072 pour RSA, mais JDK 17 et versions antérieures utilisent par défaut 2048, donc passez l’option explicitement pour que la commande se comporte de la même manière partout.

L’alias, codesign dans l’exemple, est l’étiquette de cette entrée dans le keystore. Choisissez quelque chose que vous reconnaîtrez, et notez-le : chaque commande ultérieure en a besoin, et une incohérence est ce qui rompt l’importation du certificat décrite plus loin.

Une clé ECDSA est également autorisée. Remplacez les options RSA par -keyalg EC -groupname secp256r1 si vous préférez P-256, et confirmez auprès de votre CA que le produit que vous avez commandé prend en charge ECDSA.

Étape 2 : Répondre aux invites qui construisent votre nom distinctif

keytool demande un mot de passe de keystore deux fois, puis pose six questions dans cet ordre exact. L’ordre compte : la deuxième invite demande l’unité organisationnelle, et non l’organisation, et les anciens guides la listent de manière erronée, de sorte qu’un lecteur qui y saisit le nom de l’entreprise le place dans le mauvais composant du nom.

• Quels sont vos nom et prénom ? Cela devient le Common Name (CN), malgré la formulation. Pour un certificat de signature de code, le CN est l’identité de l’éditeur que les utilisateurs verront, saisissez donc le nom légal exact de votre organisation, ou votre propre nom légal complet pour un certificat individuel. Ne saisissez pas de nom de domaine ici.
• Quel est le nom de votre unité organisationnelle ? Le département, par exemple IT. N’appuyez pas sur Entrée pour passer : keytool écrit alors la valeur littérale Unknown dans le nom, et OU=Unknown se retrouve dans votre CSR. Si vous ne voulez aucune unité organisationnelle, utilisez la forme -dname ci-dessous et omettez le composant OU dans la chaîne.
• Quel est le nom de votre organisation ? Le nom légal enregistré, orthographié tel qu’il apparaît dans les registres officiels. La CA le vérifie par rapport aux registres publics.
• Quel est le nom de votre ville ou localité ? La ville d’enregistrement, écrite en entier.
• Quel est le nom de votre état ou province ? Le nom complet, et non une abréviation.
• Quel est le code pays à deux lettres pour cette unité ? Le code ISO, par exemple FR.

keytool affiche ensuite le nom assemblé et vous demande de le confirmer :

Is CN=Example LLC, OU=IT, O=Example LLC, L=Miami, ST=Florida, C=US correct?
  [no]:

La réponse par défaut est no, donc appuyer sur Entrée vous renvoie à travers les six questions. Tapez yes pour accepter. Lisez d’abord attentivement la ligne : il s’agit du nom distinctif complet, pas seulement du Common Name, et chacun de ses composants figure dans le CSR.

Il n’y a pas de mot de passe de clé distinct sur un keystore PKCS12. Les anciens guides terminent cette étape par « saisissez un mot de passe pour la clé », ce qui correspond au comportement de JKS. Sur un keystore PKCS12, le mot de passe de la clé est le mot de passe du magasin, et si vous passez -keypass avec une valeur différente, keytool vous le signale : « Different store and key passwords not supported for PKCS12 KeyStores. Ignoring user-specified -keypass value. »

Pour éviter complètement les invites, fournissez le nom complet avec -dname. Conservez la valeur entre une seule paire de guillemets droits :

keytool -genkeypair -alias codesign -keyalg RSA -keysize 3072 -storetype PKCS12 -keystore codesign.p12 -dname "CN=Example LLC, OU=IT, O=Example LLC, L=Miami, ST=Florida, C=US"

N’incluez pas -storepass dans la ligne de commande et laissez keytool vous le demander. Passer un mot de passe en argument l’écrit dans l’historique de votre shell et l’expose à quiconque peut lister les processus en cours.

Étape 3 : Créer le CSR

Le keystore contient désormais une clé privée et un certificat auto-signé temporaire. Transformez cette entrée en demande de certificat :

keytool -certreq -alias codesign -keystore codesign.p12 -file codesign.csr

Saisissez le mot de passe du keystore lorsque cela vous est demandé. Vous n’avez pas besoin de -storetype ici : keytool détecte le format d’un fichier keystore déjà existant. L’alias doit être celui de l’étape 1, car le CSR est signé par la clé privée de cette entrée.

Cette commande ne crée pas de clé privée. La clé a été créée à l’étape 1 et reste à l’intérieur du keystore, c’est pourquoi le fichier keystore et son mot de passe sont désormais aussi sensibles que la clé elle-même. Quiconque possède les deux peut signer des logiciels en votre nom.

Étape 4 : Vérifier le CSR avant de l’envoyer

Un CSR rejeté coûte un cycle de validation, alors décodez-le et relisez-le :

keytool -printcertreq -file codesign.csr

Confirmez trois éléments dans la sortie. La ligne Subject doit lister vos informations dans les bons composants, avec le nom légal de l’organisation dans O et l’identité de l’éditeur dans CN. La ligne de clé publique doit indiquer 3072-bit RSA key ou plus. L’algorithme de signature doit être un algorithme SHA-2 : les JDK actuels signent une demande RSA de 3072 bits avec SHA384withRSA et les versions plus anciennes utilisent SHA256withRSA, l’un ou l’autre convient. Cet algorithme prouve seulement que vous détenez la clé privée, ce n’est pas l’algorithme que la CA utilisera pour signer votre certificat.

Vous pouvez également coller la demande dans notre décodeur de CSR pour lire les mêmes champs dans un navigateur.

Lorsque vous soumettez la demande, ouvrez le fichier dans un éditeur de texte brut et copiez tout, y compris les première et dernière lignes. keytool écrit ces marqueurs exacts, avec cinq tirets de chaque côté :

-----BEGIN NEW CERTIFICATE REQUEST-----
MIID3TCCAkUCAQAwaDELMAkGA1UEBhMCVVMxEDAOBgNVBAgTB0Zsb3JpZGExDjAM
...base64 encoded request...
-----END NEW CERTIFICATE REQUEST-----

La formulation NEW CERTIFICATE REQUEST est normale pour la sortie de keytool et les formulaires d’inscription l’acceptent. Si votre éditeur a remplacé une suite de tirets par un tiret long, la demande sera refusée : retapez les marqueurs sous forme de tirets simples ou copiez le fichier avec un éditeur de code à la place.

Générer le CSR sur un jeton ou un HSM avec keytool

C’est la voie qui produit un CSR sur lequel une CA publique peut agir. keytool communique avec un jeton matériel via le fournisseur SunPKCS11, de sorte que la paire de clés est créée à l’intérieur du dispositif et n’existe jamais sous forme de fichier. Commencez par rédiger un petit fichier de configuration, par exemple token.cfg, qui nomme votre jeton et pointe vers la bibliothèque PKCS#11 que votre fournisseur a installée :

name = token
library = /usr/local/lib/libeToken.so

Ces deux lignes, name et library, sont les seules requises. Le chemin de la bibliothèque est spécifique au fournisseur et diffère selon le système d’exploitation, prenez-le donc dans la documentation de votre jeton plutôt que dans cet exemple. Sous Windows, il s’agit d’une DLL sous le répertoire système. Sans ligne slot, le fournisseur se rattache au premier emplacement signalé par le dispositif, ce qui convient lorsqu’un seul jeton est branché. Si vous avez plus d’un lecteur ou jeton, ajoutez soit slotListIndex avec la position dans cette liste, en comptant à partir de zéro, soit slot avec l’identifiant numérique d’emplacement que l’utilitaire de votre fournisseur affiche. Un seul des deux peut figurer dans le fichier, et un identifiant d’emplacement n’est pas le même nombre qu’une position dans une liste, ne devinez donc pas slot = 0.

Listez ce qui se trouve sur le dispositif. Le jeton fournit l’alias, vous en avez donc besoin avant tout le reste :

keytool -list -keystore NONE -storetype PKCS11 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg token.cfg

-keystore NONE est requis chaque fois que le keystore n’est pas un fichier, et l’invite de mot de passe demande en fait le code PIN du jeton. keytool accepte également -addprovider SunPKCS11 -providerarg token.cfg à la place de la paire -providerClass et -providerArg ; les deux formes fonctionnent, et la documentation des autorités de certification montre généralement l’ancienne.

Une fois l’alias en main, générez la clé sur le dispositif puis demandez le CSR contre celle-ci :

keytool -genkeypair -alias codesign -keyalg RSA -keysize 3072 -keystore NONE -storetype PKCS11 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg token.cfg -dname "CN=Example LLC, O=Example LLC, L=Miami, ST=Florida, C=US"

keytool -certreq -alias codesign -keystore NONE -storetype PKCS11 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg token.cfg -file codesign.csr

Deux mises en garde s’appliquent. Certains jetons n’autorisent pas la génération de clé via PKCS#11 et attendent que vous utilisiez l’utilitaire propre du fournisseur, ce qui n’est pas un problème : keytool peut toujours créer le CSR contre une clé générée par l’outil du fournisseur. Et keytool ne peut pas produire le fichier d’attestation que votre CA demandera, générez-le donc avec l’outillage du fournisseur en même temps que la clé, en suivant le guide YubiKey ou Luna HSM.

Importer la réponse de la CA dans le même alias

Lorsque le certificat arrive, il doit retourner dans l’entrée qui a généré le CSR. Importez-le ailleurs et keytool signale quand même un succès tout en produisant un keystore incapable de signer, lisez donc cette section avant d’exécuter quoi que ce soit.

Importez d’abord le certificat racine de la CA et tous les certificats intermédiaires, chacun sous son propre alias :

keytool -importcert -trustcacerts -alias caroot -file root.crt -keystore codesign.p12

keytool affiche le certificat qu’il s’apprête à stocker et demande Trust this certificate? avec no comme réponse par défaut, tapez donc yes. Vérifiez l’empreinte par rapport à celle publiée par votre autorité de certification avant de répondre.

Sautez l’importation de la racine et la commande suivante échoue avec un message qui ne donne aucun indice sur la cause :

keytool error: java.lang.Exception: Failed to establish chain from reply

Importez maintenant votre certificat émis en utilisant le même alias que celui utilisé à l’étape 1 :

keytool -importcert -alias codesign -file codesign.crt -keystore codesign.p12

Le message que vous voulez voir est Certificate reply was installed in keystore. Cela signifie que keytool a reconnu une clé privée existante sous cet alias et lui a attaché le certificat émis et sa chaîne.

Si vous inventez un nouvel alias à la place, keytool accepte le fichier et affiche Certificate was added to keystore. Cela ressemble à un succès mais n’en est pas un. keytool a stocké le certificat comme une entrée de confiance autonome sans clé privée derrière, et cette entrée ne pourra jamais rien signer. L’alias d’origine, quant à lui, contient toujours le certificat auto-signé temporaire de l’étape 1. Vérifiez lequel des deux vous avez :

keytool -list -keystore codesign.p12

Votre alias de signature doit être listé comme PrivateKeyEntry. Un alias affiché comme trustedCertEntry correspond à l’erreur décrite ci-dessus. Supprimez-le avec keytool -delete -alias wrongalias -keystore codesign.p12 et répétez l’importation avec le bon alias. Ajoutez -v à la commande de liste pour confirmer que l’entrée porte désormais une chaîne de certificats complète plutôt qu’un simple certificat auto-signé.

Sur un jeton matériel, il n’y a généralement rien à importer, car la CA charge le certificat sur le dispositif avant de l’expédier. Si votre CA vous envoie un fichier de certificat pour une clé que vous avez générée sur votre propre HSM, utilisez la même commande -importcert avec les options PKCS#11 de la section précédente.

Signer un fichier JAR avec le certificat

L’intérêt de placer un certificat de signature de code dans un keystore Java est de signer des fichiers JAR avec jarsigner, également fourni avec le JDK. Une fois le certificat installé sous le bon alias :

jarsigner -keystore codesign.p12 -tsa https://your-ca-timestamp-url application.jar codesign

Passez toujours -tsa avec l’URL d’horodatage publiée par votre autorité de certification. Un horodatage enregistre que le JAR a été signé alors que le certificat était encore valide, donc la signature continue de fonctionner après l’expiration du certificat. Sans cela, chaque copie de votre logiciel cesse d’être valide le jour où le certificat expire.

Lorsque la clé se trouve sur un jeton, orientez jarsigner vers PKCS#11 exactement comme keytool le fait :

jarsigner -keystore NONE -storetype PKCS11 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg token.cfg -tsa https://your-ca-timestamp-url application.jar codesign

Si le jeton dispose de trop peu d’espace pour la chaîne de certificats complète, fournissez-la séparément avec -certchain. Vérifiez ensuite le résultat :

jarsigner -verify -verbose -certs application.jar

Une exécution réussie affiche jar verified ainsi que le nom distinctif du signataire et les détails de l’horodatage. Les JDK actuels utilisent SHA-384 comme algorithme de hachage par défaut, vous avez donc rarement besoin de définir manuellement -digestalg ou -sigalg.

D’autres méthodes pour créer cette demande sont abordées dans les guides OpenSSL, CertReq, Console de gestion Microsoft, et Accès au trousseau macOS, et la même règle matérielle s’applique à tous. Consultez également notre ensemble complet de tutoriels sur la signature de code et l’aperçu de la génération de CSR pour les certificats de signature de code. Si vous avez besoin d’un CSR keytool pour un certificat de site web plutôt que pour la signature de code, suivez plutôt le guide Tomcat ou JBoss.

Questions fréquemment posées