Verwendung von Client-SDK 5 zur Integration mit Java Keytool und Jarsigner

AWS CloudHSM Der Schlüsselspeicher ist ein spezieller JCE-Schlüsselspeicher, der Zertifikate verwendet, die mit Schlüsseln auf Ihrem HSM verknüpft sind, und zwar über Tools von Drittanbietern wie und. keytool jarsigner AWS CloudHSM speichert keine Zertifikate auf dem HSM, da es sich bei Zertifikaten um öffentliche, nicht vertrauliche Daten handelt. Der AWS CloudHSM Schlüsselspeicher speichert die Zertifikate in einer lokalen Datei und ordnet die Zertifikate den entsprechenden Schlüsseln auf Ihrem HSM zu.

Wenn Sie den AWS CloudHSM Schlüsselspeicher verwenden, um neue Schlüssel zu generieren, werden keine Einträge in der lokalen Schlüsselspeicherdatei generiert — die Schlüssel werden auf dem HSM erstellt. Wenn Sie den AWS CloudHSM -Schlüsselspeicher verwenden, um nach Schlüsseln zu suchen, wird die Suche an das HSM übergeben. Wenn Sie Zertifikate im AWS CloudHSM Schlüsselspeicher speichern, überprüft der Anbieter, ob ein key pair mit dem entsprechenden Alias auf dem HSM vorhanden ist, und ordnet dann das bereitgestellte Zertifikat dem entsprechenden key pair zu.

Voraussetzungen

Um den AWS CloudHSM Schlüsselspeicher verwenden zu können, müssen Sie zuerst das JCE SDK initialisieren und konfigurieren. AWS CloudHSM

Schritt 1: Installieren der JCE

Folgen Sie den Schritten zur Installation der Java-Bibliothek, um JCE einschließlich der AWS CloudHSM Client-Voraussetzungen zu installieren.

Schritt 2: Hinzufügen von HSM-Anmeldeinformationen zu Umgebungsvariablen

Richten Sie Umgebungsvariablen so ein, dass sie Ihre HSM-Anmeldeinformationen enthalten.

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>

Anmerkung

Das AWS CloudHSM JCE bietet verschiedene Anmeldeoptionen. Um den AWS CloudHSM Schlüsselspeicher mit Anwendungen von Drittanbietern zu verwenden, müssen Sie die implizite Anmeldung mit Umgebungsvariablen verwenden. Wenn Sie die explizite Anmeldung über Anwendungscode verwenden möchten, müssen Sie mithilfe des AWS CloudHSM Schlüsselspeichers Ihre eigene Anwendung erstellen. Weitere Informationen finden Sie im Artikel Verwenden des AWS CloudHSM Schlüsselspeichers.

Schritt 3: Registrieren des JCE-Providers

Gehen Sie folgendermaßen vor, um den JCE-Anbieter in der CloudProvider Java-Konfiguration zu registrieren:

1. Öffnen Sie die java.security-Konfigurationsdatei in Ihrer Java-Installation zur Bearbeitung.

2. Fügen Sie in der java.security-Konfigurationsdatei com.amazonaws.cloudhsm.jce.provider.CloudHsmProvider als letzten Anbieter hinzu. Wenn sich beispielsweise neun Anbieter in der java.security-Datei befinden, fügen Sie den folgenden Anbieter als letzten Anbieter in dem Abschnitt hinzu:

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

Anmerkung

Wenn Sie den AWS CloudHSM Anbieter mit höherer Priorität hinzufügen, kann sich dies negativ auf die Leistung Ihres Systems auswirken, da dem AWS CloudHSM Anbieter bei Vorgängen, die sicher in Software ausgelagert werden können, Priorität eingeräumt wird. Es hat sich bewährt, immer den Anbieter anzugeben, den Sie für einen Vorgang verwenden möchten, unabhängig davon, ob es sich um den AWS CloudHSM oder einen softwarebasierten Anbieter handelt.

Anmerkung

Die Angabe von -providerName-, -providerclass- und -providerpath-Befehlszeilenoptionen beim Generieren von Schlüsseln mithilfe von Keytool mit dem AWS-CloudHSM-Schlüsselspeicher kann zu Fehlern führen.

Verwenden des AWS CloudHSM Schlüsselspeichers mit Keytool

Keytool ist ein beliebtes Befehlszeilenprogramm für allgemeine Schlüssel- und Zertifikataufgaben. Ein vollständiges Tutorial zu keytool liegt außerhalb des Umfangs der AWS CloudHSM -Dokumentation. In diesem Artikel werden die spezifischen Parameter erläutert, die Sie mit verschiedenen Keytool-Funktionen verwenden sollten, wenn Sie sie über den AWS CloudHSM Schlüsselspeicher AWS CloudHSM als Vertrauensbasis verwenden.

Wenn Sie Keytool mit dem AWS CloudHSM Schlüsselspeicher verwenden, geben Sie die folgenden Argumente für jeden Keytool-Befehl an:

Linux

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

Windows

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

Wenn Sie mithilfe des Schlüsselspeichers eine neue Schlüsselspeicherdatei erstellen möchten, finden Sie AWS CloudHSM weitere Informationen unter. Verwenden AWS CloudHSM KeyStore Um einen vorhandenen Schlüsselspeicher zu verwenden, geben Sie seinen Namen (einschließlich Pfad) mit dem Argument -keystore zu keytool an. Wenn Sie in einem Keytool-Befehl eine nicht existierende Schlüsselspeicherdatei angeben, erstellt der AWS CloudHSM Schlüsselspeicher eine neue Schlüsselspeicherdatei.

Erstellen neuer Schlüssel mit Keytool

Sie können keytool verwenden, um RSA-, AES- und DESede-Schlüssel zu erzeugen, die von JCE SDK des AWS CloudHSM unterstützt werden.

Wichtig

Ein mit Keytool generierter Schlüssel wird in der Software generiert und dann AWS CloudHSM als extrahierbarer, persistenter Schlüssel importiert.

Wir empfehlen nachdrücklich, nicht exportierbare Schlüssel außerhalb von keytool zu generieren und dann entsprechende Zertifikate in den Schlüsselspeicher zu importieren. Wenn Sie extrahierbare RSA- oder EC-Schlüssel über Keytool und Jarsigner verwenden, exportieren die Anbieter Schlüssel aus dem AWS CloudHSM und verwenden den Schlüssel dann lokal für Signaturvorgänge.

Wenn Sie mehrere Client-Instanzen mit Ihrem AWS CloudHSM Cluster verbunden haben, beachten Sie, dass der Import eines Zertifikats in den Schlüsselspeicher einer Client-Instanz die Zertifikate nicht automatisch auf anderen Client-Instances verfügbar macht. Um den Schlüssel und die zugehörigen Zertifikate auf jeder Client-Instance zu registrieren, müssen Sie eine Java-Anwendung ausführen, wie in Erstellen eines CSR mit Keytool beschrieben. Alternativ können Sie die erforderlichen Änderungen auf einem Client vornehmen und die resultierende Schlüsselspeicherdatei auf jede andere Client-Instanz kopieren.

Beispiel 1: So generieren Sie einen symmetrischen AES-256-Schlüssel und speichern ihn in einer Schlüsselspeicherdatei namens „my_keystore.store“ im Arbeitsverzeichnis. Ersetzen Sie <secret label> durch ein eindeutiges Label.

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\*"'

Beispiel 2: So generieren Sie ein RSA 2048-Schlüsselpaar und speichern es in einer Schlüsselspeicherdatei namens „my_keystore.store“ im Arbeitsverzeichnis. Ersetzen Sie <RSA key pair label> durch ein eindeutiges Label.

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\*"'		

Sie finden eine Liste der unterstützten Signaturalgorithmen in der Java-Bibliothek.

Löschen eines Schlüssels mit Keytool

Der AWS CloudHSM Schlüsselspeicher unterstützt das Löschen von Schlüsseln nicht. Sie können Schlüssel mit der Destroyable-Methode der Destroyable-Schnittstelle löschen.

((Destroyable) key).destroy();

Erstellen eines CSR mit Keytool

Sie erhalten die größte Flexibilität beim Generieren einer Zertifikatsignieranforderung (Certificate Signing Request, CSR), wenn Sie die OpenSSL Dynamic Engine verwenden. Der folgende Befehl verwendet keytool, um eine CSR für ein Schlüsselpaar mit dem Alias, my-key-pair, zu generieren.

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\*"'

Anmerkung

Um ein Schlüsselpaar von keytool zu verwenden, muss dieses Schlüsselpaar einen Eintrag in der angegebenen Schlüsselspeicherdatei haben. Wenn Sie ein Schlüsselpaar verwenden möchten, das außerhalb von keytool generiert wurde, müssen Sie die Schlüssel- und Zertifikatmetadaten in den Schlüsselspeicher importieren. Anweisungen zum Importieren der Keystore-Daten finden Sie unter Verwenden von Keytool zum Importieren von Zwischen- und Stammzertifikaten in den AWS CloudHSM Schlüsselspeicher .

Verwenden von Keytool zum Importieren von Zwischen- und Stammzertifikaten in den AWS CloudHSM Schlüsselspeicher

Um ein CA-Zertifikat zu importieren, müssen Sie die Überprüfung einer vollständigen Zertifikatkette für ein neu importiertes Zertifikat aktivieren. Im Folgenden wird ein Beispielbefehl gezeigt.

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\*"'

Wenn Sie mehrere Client-Instances mit Ihrem AWS CloudHSM Cluster verbinden, wird durch den Import eines Zertifikats in den Schlüsselspeicher einer Client-Instanz das Zertifikat nicht automatisch auf anderen Client-Instances verfügbar. Sie müssen das Zertifikat auf jeder Client-Instanz importieren.

Verwenden von Keytool zum Löschen von Zertifikaten aus dem AWS CloudHSM Schlüsselspeicher

Der folgende Befehl zeigt ein Beispiel für das Löschen eines Zertifikats aus einem Java-Keytool-Schlüsselspeicher.

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\*"'

Wenn Sie mehrere Client-Instances mit Ihrem AWS CloudHSM Cluster verbinden, wird durch das Löschen eines Zertifikats im Schlüsselspeicher einer Client-Instanz das Zertifikat nicht automatisch aus anderen Client-Instances entfernt. Sie müssen das Zertifikat auf jeder Client-Instanz löschen.

Ein funktionierendes Zertifikat mit Keytool in den AWS CloudHSM Schlüsselspeicher importieren

Sobald eine Zertifikatsignieranforderung (CSR) signiert ist, können Sie sie in den AWS CloudHSM -Schlüsselspeicher importieren und mit dem entsprechenden Schlüsselpaar verknüpfen. Der folgende Befehl bietet ein Beispiel.

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\*"'

Der Alias sollte ein Schlüsselpaar mit einem zugeordneten Zertifikat im Schlüsselspeicher sein. Wenn der Schlüssel außerhalb von keytool oder auf einer anderen Client-Instanz generiert wird, müssen Sie zuerst die Schlüssel- und Zertifikatmetadaten in den Schlüsselspeicher importieren.

Die Zertifikatkette muss überprüfbar sein. Wenn Sie das Zertifikat nicht überprüfen können, müssen Sie möglicherweise das Signaturzertifikat (Zertifizierungsstelle) in den Schlüsselspeicher importieren, damit die Kette überprüft werden kann.

Exportieren eines Zertifikats mit Keytool

Im folgenden Beispiel wird ein Zertifikat im Binärformat X.509 generiert. Um ein menschlich lesbares Zertifikat zu exportieren, fügen Sie dem -exportcert-Befehl -rfc hinzu.

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\*"'

Verwenden des AWS CloudHSM Schlüsselspeichers mit Jarsigner

Jarsigner ist ein beliebtes Befehlszeilenprogramm zum Signieren von JAR-Dateien mithilfe eines Schlüssels, der sicher auf einem HSM gespeichert ist. Ein komplettes Tutorial zu Jarsigner liegt außerhalb der AWS CloudHSM -Dokumentation. In diesem Abschnitt werden die Jarsigner-Parameter erläutert, die Sie verwenden sollten, um Signaturen zu signieren und zu verifizieren, wobei AWS CloudHSM sie als Vertrauensbasis über den Schlüsselspeicher dienen. AWS CloudHSM

Einrichten von Schlüsseln und Zertifikaten

Bevor Sie JAR-Dateien mit Jarsigner signieren können, stellen Sie sicher, dass Sie die folgenden Schritte eingerichtet oder ausgeführt haben:

1. Folgen Sie den Anweisungen unter AWS CloudHSM -Schlüsselspeichervoraussetzungen.

2. Richten Sie Ihre Signaturschlüssel und die zugehörigen Zertifikate und die Zertifikatskette ein, die im AWS CloudHSM Schlüsselspeicher der aktuellen Server- oder Client-Instanz gespeichert werden sollten. Erstellen Sie die Schlüssel auf dem AWS CloudHSM und importieren Sie dann die zugehörigen Metadaten in Ihren AWS CloudHSM Schlüsselspeicher. Informationen zum Einrichten der Schlüssel und Zertifikate mit keytool finden Sie unter Erstellen neuer Schlüssel mit Keytool. Wenn Sie mehrere Client-Instanzen verwenden, um Ihre JARs zu signieren, erstellen Sie den Schlüssel, und importieren Sie die Zertifikatkette. Kopieren Sie dann die resultierende Schlüsselspeicherdatei auf jede Client-Instanz. Wenn Sie häufig neue Schlüssel generieren, ist es möglicherweise einfacher, Zertifikate einzeln in jede Client-Instanz zu importieren.

3. Die gesamte Zertifikatskette sollte überprüfbar sein. Damit die Zertifikatskette verifizierbar ist, müssen Sie möglicherweise das CA-Zertifikat und die Zwischenzertifikate zum AWS CloudHSM Schlüsselspeicher hinzufügen. Im Codeausschnitt in Signieren einer JAR-Datei mit AWS CloudHSM und Jarsigner finden Sie eine Anleitung zur Verwendung von Java-Code zur Überprüfung der Zertifikatskette. Wenn Sie möchten, können Sie keytool verwenden, um Zertifikate zu importieren. Eine Anleitung zur Verwendung von keytool finden Sie unter Verwenden von Keytool zum Importieren von Zwischen- und Stammzertifikaten in den AWS CloudHSM Schlüsselspeicher .

Signieren einer JAR-Datei mit AWS CloudHSM und Jarsigner

Verwenden Sie den folgenden Befehl, um eine JAR-Datei zu signieren:

Linux;

Für 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>
						

Für OpenJDK 11, OpenJDK 17 und 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

Für 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>
						

Für OpenJDK 11, OpenJDK 17 und 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>
						

Verwenden Sie den folgenden Befehl, um eine signierte JAR zu überprüfen:

Linux

Für 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>
						

Für OpenJDK 11, OpenJDK 17 und 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

Für 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>
						

Für OpenJDK 11, OpenJDK 17 und 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>
						

Bekannte Probleme

1. Wir unterstützen keine EC-Schlüssel mit Keytool und Jarsigner.