Utilisation du SDK client 5 pour intégrer Java Keytool et Jarsigner

AWS CloudHSM Le magasin de clés est un magasin de clés JCE spécial qui utilise les certificats associés aux clés de votre HSM via des outils tiers tels que et. keytool jarsigner AWS CloudHSM ne stocke pas les certificats sur le HSM, car les certificats sont des données publiques non confidentielles. Le magasin de AWS CloudHSM clés stocke les certificats dans un fichier local et les mappe aux clés correspondantes sur votre HSM.

Lorsque vous utilisez le magasin de AWS CloudHSM clés pour générer de nouvelles clés, aucune entrée n'est générée dans le fichier de magasin de clés local ; les clés sont créées sur le HSM. De même, lorsque vous utilisez le magasin de clés AWS CloudHSM pour rechercher des clés, la recherche est transmise au HSM. Lorsque vous stockez des certificats dans le magasin de AWS CloudHSM clés, le fournisseur vérifie qu'une paire de clés portant l'alias correspondant existe sur le HSM, puis associe le certificat fourni à la paire de clés correspondante.

Prérequis

Pour utiliser le magasin de AWS CloudHSM clés, vous devez d'abord initialiser et configurer le SDK AWS CloudHSM JCE.

Étape 1 : Installation du JCE

Pour installer le JCE, y compris les prérequis du AWS CloudHSM client, suivez les étapes d'installation de la bibliothèque Java.

Étape 2 : Ajouter des informations d'identification de connexion HSM aux variables d'environnement

Configurez les variables d'environnement pour qu'elles contiennent vos informations d'identification de connexion HSM.

Linux

$ export HSM_USER=<HSM user name>

$ export HSM_PASSWORD=<HSM password>

Windows

PS C:\> $Env:HSM_USER=<HSM user name>

PS C:\> $Env:HSM_PASSWORD=<HSM password>

Note

Le AWS CloudHSM JCE propose différentes options de connexion. Pour utiliser le magasin de AWS CloudHSM clés avec des applications tierces, vous devez utiliser une connexion implicite avec des variables d'environnement. Si vous souhaitez utiliser une connexion explicite via le code de l'application, vous devez créer votre propre application à l'aide du magasin de AWS CloudHSM clés. Pour plus d'informations, consultez l'article sur l'utilisation de AWS CloudHSM Key Store.

Étape 3 : Enregistrement du fournisseur JCE

Pour enregistrer le fournisseur JCE dans la CloudProvider configuration Java, procédez comme suit :

1. Ouvrez le fichier de configuration java.security dans votre installation Java, pour modification.

2. Dans le fichier de configuration java.security, ajoutez com.amazonaws.cloudhsm.jce.provider.CloudHsmProvider comme dernier fournisseur. Par exemple, s'il y a neuf fournisseurs dans le fichier java.security, ajoutez le fournisseur suivant comme dernier fournisseur dans la section :

   security.provider.10=com.amazonaws.cloudhsm.jce.provider.CloudHsmProvider

Note

L'ajout du AWS CloudHSM fournisseur à une priorité plus élevée peut avoir un impact négatif sur les performances de votre système, car le AWS CloudHSM fournisseur sera priorisé pour les opérations qui peuvent être déchargées en toute sécurité vers le logiciel. Il est recommandé de toujours spécifier le fournisseur que vous souhaitez utiliser pour une opération, qu'il s'agisse d'un fournisseur logiciel AWS CloudHSM ou d'un fournisseur basé sur un logiciel.

Note

La spécification des options de ligne de commande -providerName, -providerclass et -providerpath lors de la génération de clés à l'aide de keytool avec le magasin de clés AWS CloudHSM peut provoquer des erreurs.

Utilisation du magasin de AWS CloudHSM clés avec keytool

keytool est un utilitaire de ligne de commande populaire pour les tâches courantes de clés et de certificats. La documentation AWS CloudHSM n'inclut pas de didacticiel complet sur keytool. Cet article explique les paramètres spécifiques que vous devez utiliser avec les différentes fonctions de keytool lorsque vous les utilisez AWS CloudHSM comme racine de confiance via le magasin de AWS CloudHSM clés.

Lorsque vous utilisez keytool avec le magasin de AWS CloudHSM clés, spécifiez les arguments suivants pour chaque commande keytool :

Linux

-storetype CLOUDHSM -J-classpath< '-J/opt/cloudhsm/java/*'>

Windows

-storetype CLOUDHSM -J-classpath<'-J"C:\Program Files\Amazon\CloudHSM\java\*"'>

Si vous souhaitez créer un nouveau fichier de stockage de clés à l'aide du magasin de AWS CloudHSM clés, consultezEn utilisant AWS CloudHSM KeyStore. Pour utiliser un magasin de clés existant, spécifiez son nom (y compris le chemin) à l'aide de l'argument —keystore à keytool. Si vous spécifiez un fichier de stockage de clés inexistant dans une commande keytool, le magasin de AWS CloudHSM clés crée un nouveau fichier de stockage de clés.

Créer de nouvelles clés avec keytool

Vous pouvez utiliser keytool pour générer un type de clé RSA, AES et DESede pris en charge par le SDK JCE d’ AWS CloudHSM.

Important

Une clé générée par keytool est générée dans le logiciel, puis importée AWS CloudHSM sous forme de clé persistante extractible.

Nous vous recommandons fortement de générer des clés non exportables en dehors de keytool, puis d'importer les certificats correspondants dans le magasin de clés. Si vous utilisez des clés RSA ou EC extractibles via keytool et Jarsigner, les fournisseurs exportent les clés depuis le, AWS CloudHSM puis les utilisent localement pour les opérations de signature.

Si plusieurs instances clientes sont connectées à votre AWS CloudHSM cluster, sachez que l'importation d'un certificat dans le magasin de clés d'une instance client ne rendra pas automatiquement les certificats disponibles sur d'autres instances clientes. Pour enregistrer la clé et les certificats associés sur chaque instance client, vous devez exécuter une application Java comme décrit dans Générer une CSR à l'aide de Keytool. Vous pouvez également apporter les modifications nécessaires sur un client et copier le fichier de stockage de clés résultant sur chaque autre instance cliente.

Exemple 1 : Pour générer une clé AES-256 symétrique et l'enregistrer dans un fichier de magasin de clés nommé « my_keystore.store », dans le répertoire de travail. Remplacez <secret label> par une étiquette unique.

Linux

$ keytool -genseckey -alias <secret label> -keyalg aes \
	-keysize 256 -keystore my_keystore.store \
	-storetype CloudHSM -J-classpath '-J/opt/cloudhsm/java/*' \	

Windows

PS C:\> keytool -genseckey -alias <secret label> -keyalg aes `
	-keysize 256 -keystore my_keystore.store `
	-storetype CloudHSM -J-classpath '-J"C:\Program Files\Amazon\CloudHSM\java\*"'

Exemple 2 : Pour générer une paire de clés RSA 2048 et l'enregistrer dans un fichier de magasin de clés nommé « my_keystore.store » dans le répertoire de travail. Remplacez <RSA key pair label> par une étiquette unique.

Linux

$ keytool -genkeypair -alias <RSA key pair label> \
	-keyalg rsa -keysize 2048 \
	-sigalg sha512withrsa \
	-keystore my_keystore.store \
	-storetype CLOUDHSM \
	-J-classpath '-J/opt/cloudhsm/java/*'

Windows

PS C:\> keytool -genkeypair -alias <RSA key pair label> `
	-keyalg rsa -keysize 2048 `
	-sigalg sha512withrsa `
	-keystore my_keystore.store `
	-storetype CLOUDHSM `
	-J-classpath '-J"C:\Program Files\Amazon\CloudHSM\java\*"'		

Vous trouverez une liste des algorithmes de signature pris en charge dans la bibliothèque Java.

Supprimer une clé à l'aide de Keytool

Le magasin de AWS CloudHSM clés ne prend pas en charge la suppression de clés. Vous pouvez supprimer des clés à l'aide de la méthode de destruction de l’interface Destroyable.

((Destroyable) key).destroy();

Générer une CSR à l'aide de Keytool

Vous bénéficiez de la plus grande flexibilité dans la génération d'une demande de signature de certificat (CSR) si vous utilisez le OpenSSL Dynamic Engine. La commande suivante utilise keytool pour générer un CSR pour une paire de clés avec l'alias, my-key-pair.

Linux

$ keytool -certreq -alias <key pair label> \
	-file my_csr.csr \
	-keystore my_keystore.store \
	-storetype CLOUDHSM \
	-J-classpath '-J/opt/cloudhsm/java/*'	

Windows

PS C:\> keytool -certreq -alias <key pair label> `
	-file my_csr.csr `
	-keystore my_keystore.store `
	-storetype CLOUDHSM `
	-J-classpath '-J"C:\Program Files\Amazon\CloudHSM\java\*"'

Note

Pour utiliser une paire de clés de keytool, cette paire de clés doit avoir une entrée dans le fichier de stockage de clés spécifié. Si vous souhaitez utiliser une paire de clés générée en dehors de keytool, vous devez importer les métadonnées de clé et de certificat dans le magasin de clés. Pour obtenir des instructions sur l'importation des données du keystore, consultez Utilisation de keytool pour importer des certificats intermédiaires et racines dans le magasin de AWS CloudHSM clés .

Utilisation de keytool pour importer des certificats intermédiaires et racines dans le magasin de AWS CloudHSM clés

Pour importer un certificat d'autorité de certification, vous devez activer la vérification d'une chaîne de certificats complète sur un certificat nouvellement importé. Voici un exemple de commande.

Linux

$ keytool -import -trustcacerts -alias rootCAcert \
	-file rootCAcert.cert -keystore my_keystore.store \
	-storetype CLOUDHSM \
	-J-classpath '-J/opt/cloudhsm/java/*'

Windows

PS C:\> keytool -import -trustcacerts -alias rootCAcert `
	-file rootCAcert.cert -keystore my_keystore.store `
	-storetype CLOUDHSM `
	-J-classpath '-J"C:\Program Files\Amazon\CloudHSM\java\*"'

Si vous connectez plusieurs instances clientes à votre AWS CloudHSM cluster, l'importation d'un certificat dans le magasin de clés d'une instance client ne le rendra pas automatiquement disponible sur les autres instances clientes. Vous devez importer le certificat sur chaque instance client.

Utilisation de keytool pour supprimer des certificats du magasin de AWS CloudHSM clés

La commande suivante montre un exemple de suppression d'un certificat d'un magasin de clés Java keytool.

Linux

$ keytool -delete -alias mydomain \
	-keystore my_keystore.store \
	-storetype CLOUDHSM \
	-J-classpath '-J/opt/cloudhsm/java/*'

Windows

PS C:\> keytool -delete -alias mydomain `
	-keystore my_keystore.store `
	-storetype CLOUDHSM `
	-J-classpath '-J"C:\Program Files\Amazon\CloudHSM\java\*"'

Si vous connectez plusieurs instances clientes à votre AWS CloudHSM cluster, la suppression d'un certificat dans le magasin de clés d'une instance client ne supprimera pas automatiquement le certificat des autres instances clientes. Vous devez supprimer le certificat sur chaque instance cliente.

Importation d'un certificat fonctionnel dans le magasin de AWS CloudHSM clés à l'aide de keytool

Une fois qu'une demande de signature de certificat (CSR) est signée, vous pouvez l'importer dans le magasin de clés AWS CloudHSM et l'associer à la paire de clés appropriée. La commande suivante fournit un exemple.

Linux

$ keytool -importcert -noprompt -alias <key pair label> \
	-file my_certificate.crt \
	-keystore my_keystore.store \
	-storetype CLOUDHSM \
	-J-classpath '-J/opt/cloudhsm/java/*'

Windows

PS C:\> keytool -importcert -noprompt -alias <key pair label> `
	-file my_certificate.crt `
	-keystore my_keystore.store `
	-storetype CLOUDHSM `
	-J-classpath '-J"C:\Program Files\Amazon\CloudHSM\java\*"'

L'alias doit être une paire de clés avec un certificat associé dans le magasin de clés. Si la clé est générée en dehors de keytool, ou si elle est générée sur une autre instance cliente, vous devez d'abord importer la clé et les métadonnées de certificat dans le magasin de clés.

La chaîne de certificats doit être vérifiable. Si vous ne parvenez pas à vérifier le certificat, vous devrez peut-être importer le certificat de signature (autorité de certification) dans le magasin de clés afin que la chaîne puisse être vérifiée.

Exportation d'un certificat à l'aide de Keytool

L'exemple suivant génère un certificat au format binaire X.509. Pour exporter un certificat lisible par l'homme, ajoutez -rfc à la commande -exportcert.

Linux

$ keytool -exportcert -alias <key pair label> \
	-file my_exported_certificate.crt \
	-keystore my_keystore.store \
	-storetype CLOUDHSM \
	-J-classpath '-J/opt/cloudhsm/java/*'

Windows

PS C:\> keytool -exportcert -alias <key pair label> `
	-file my_exported_certificate.crt `
	-keystore my_keystore.store `
	-storetype CLOUDHSM `
	-J-classpath '-J"C:\Program Files\Amazon\CloudHSM\java\*"'

Utiliser le magasin de AWS CloudHSM clés avec Jarsigner

Jarsigner est un utilitaire de ligne de commande populaire permettant de signer des fichiers JAR à l'aide d'une clé stockée de manière sécurisée sur un HSM. Un didacticiel complet sur Jarsigner n'entre pas dans le cadre de la documentation AWS CloudHSM . Cette section explique les paramètres Jarsigner que vous devez utiliser pour signer et vérifier les signatures en utilisant le référentiel de AWS CloudHSM clés AWS CloudHSM comme source de confiance.

Configuration des clés et des certificats

Avant de pouvoir signer des fichiers JAR avec Jarsigner, assurez-vous d'avoir configuré ou effectué les étapes suivantes :

1. Suivez les instructions fournies dans les conditions préalables du magasin de clés AWS CloudHSM.

2. Configurez vos clés de signature ainsi que les certificats et la chaîne de certificats associés, qui doivent être stockés dans le magasin de AWS CloudHSM clés de l'instance actuelle du serveur ou du client. Créez les clés sur le, AWS CloudHSM puis importez les métadonnées associées dans votre magasin de AWS CloudHSM clés. Si vous souhaitez utiliser keytool pour configurer les clés et les certificats, reportez-vous à la section Créer de nouvelles clés avec keytool. Si vous utilisez plusieurs instances clientes pour signer vos fichiers JAR, créez la clé et importez la chaîne de certificats. Copiez ensuite le fichier de stockage de clés obtenu sur chaque instance cliente. Si vous générez fréquemment de nouvelles clés, il peut être plus facile d'importer individuellement des certificats dans chaque instance cliente.

3. Toute la chaîne de certificats doit être vérifiable. Pour que la chaîne de certificats soit vérifiable, vous devrez peut-être ajouter le certificat CA et les certificats intermédiaires au magasin de AWS CloudHSM clés. Veuillez consulter l'extrait de code dans Signer un fichier JAR en utilisant AWS CloudHSM et Jarsigner pour apprendre à utiliser le code Java afin de vérifier la chaîne de certificats. Si vous préférez, vous pouvez utiliser keytool pour importer des certificats. Pour des instructions sur l'utilisation de keytool, consultez Utilisation de keytool pour importer des certificats intermédiaires et racines dans le magasin de AWS CloudHSM clés .

Signer un fichier JAR en utilisant AWS CloudHSM et Jarsigner

Utilisez la commande suivante pour signer un fichier JAR :

Linux;

Pour OpenJDK 8

jarsigner -keystore my_keystore.store \
	-signedjar signthisclass_signed.jar \
	-sigalg sha512withrsa \
	-storetype CloudHSM \
	-J-classpath '-J/opt/cloudhsm/java/*:/usr/lib/jvm/java-1.8.0/lib/tools.jar' \
	-J-Djava.library.path=/opt/cloudhsm/lib \
	signthisclass.jar <key pair label>
						

Pour OpenJDK 11, OpenJDK 17 et OpenJDK 21

jarsigner -keystore my_keystore.store \
	-signedjar signthisclass_signed.jar \
	-sigalg sha512withrsa \
	-storetype CloudHSM \
	-J-classpath '-J/opt/cloudhsm/java/*' \
	-J-Djava.library.path=/opt/cloudhsm/lib \
	signthisclass.jar <key pair label>
						

Windows

Pour OpenJDK8

jarsigner -keystore my_keystore.store `
	-signedjar signthisclass_signed.jar `
	-sigalg sha512withrsa `
	-storetype CloudHSM `
	-J-classpath '-JC:\Program Files\Amazon\CloudHSM\java\*;C:\Program Files\Java\jdk1.8.0_331\lib\tools.jar' `
	 "-J-Djava.library.path='C:\Program Files\Amazon\CloudHSM\lib\'" `
	signthisclass.jar <key pair label>
						

Pour OpenJDK 11, OpenJDK 17 et OpenJDK 21

jarsigner -keystore my_keystore.store `
	-signedjar signthisclass_signed.jar `
	-sigalg sha512withrsa `
	-storetype CloudHSM `
	-J-classpath '-JC:\Program Files\Amazon\CloudHSM\java\*'`
	 "-J-Djava.library.path='C:\Program Files\Amazon\CloudHSM\lib\'" `
	signthisclass.jar <key pair label>
						

Utilisez la commande suivante pour vérifier un JAR signé :

Linux

Pour OpenJDK8

jarsigner -verify \
	-keystore my_keystore.store \
	-sigalg sha512withrsa \
	-storetype CloudHSM \
	-J-classpath '-J/opt/cloudhsm/java/*:/usr/lib/jvm/java-1.8.0/lib/tools.jar' \
	-J-Djava.library.path=/opt/cloudhsm/lib \
	signthisclass_signed.jar <key pair label>
						

Pour OpenJDK 11, OpenJDK 17 et OpenJDK 21

jarsigner -verify \
	-keystore my_keystore.store \
	-sigalg sha512withrsa \
	-storetype CloudHSM \
	-J-classpath '-J/opt/cloudhsm/java/*' \
	-J-Djava.library.path=/opt/cloudhsm/lib \
	signthisclass_signed.jar <key pair label>
						

Windows

Pour OpenJDK 8

jarsigner -verify `
	-keystore my_keystore.store `
	-sigalg sha512withrsa `
	-storetype CloudHSM `
	-J-classpath '-JC:\Program Files\Amazon\CloudHSM\java\*;C:\Program Files\Java\jdk1.8.0_331\lib\tools.jar' `
	"-J-Djava.library.path='C:\Program Files\Amazon\CloudHSM\lib\'" `
	signthisclass_signed.jar <key pair label>
						

Pour OpenJDK 11, OpenJDK 17 et OpenJDK 21

jarsigner -verify `
	-keystore my_keystore.store `
	-sigalg sha512withrsa `
	-storetype CloudHSM `
	-J-classpath '-JC:\Program Files\Amazon\CloudHSM\java\*`
	"-J-Djava.library.path='C:\Program Files\Amazon\CloudHSM\lib\'" `
	signthisclass_signed.jar <key pair label>
						

Problèmes connus

1. Nous ne prenons pas en charge les clés EC avec Keytool et Jarsigner.