使用用戶端 SDK 5 與 Java Keytool 和 Jarsigner 整合

AWS CloudHSM 金鑰存放區是一種特殊用途的 JCE 金鑰存放區，可透過第三方工具 (例如和) 利用與 HSM 上金鑰相關聯的憑證。keytool jarsigner AWS CloudHSM 不會將憑證儲存在 HSM 上，因為憑證是公開的非機密資料。金 AWS CloudHSM 鑰存放區會將憑證儲存在本機檔案中，並將憑證對應至 HSM 上對應的金鑰。

當您使用金 AWS CloudHSM 鑰存放區產生新金鑰時，本機金鑰存放區檔案中不會產生任何項目 — 金鑰會在 HSM 上建立。同樣的，當您使用 AWS CloudHSM 金鑰存放區搜尋金鑰時，搜尋會傳遞至 HSM。當您將憑證儲存在 AWS CloudHSM 金鑰存放區中時，提供者會驗證 HSM 上是否存在 key pair 與對應別名的 key pair，然後將提供的憑證與對應的金鑰配對產生關聯。

必要條件

若要使用 AWS CloudHSM 金鑰存放區，您必須先初始化並設定 AWS CloudHSM JCE SDK。

步驟 1：安裝 JCE

要安裝 JCE（包括 AWS CloudHSM 客戶端的先決條件），請按照安裝 Java 庫的步驟進行操作。

步驟 2：將 HSM 登入憑證新增至環境變數

設定環境變數以包含您的 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>

注意

AWS CloudHSM JCE 提供多種登入選項。若要將 AWS CloudHSM 金鑰存放區與第三方應用程式搭配使用，您必須搭配環境變數使用隱含登入。如果您想要透過應用程式程式碼使用明確登入，您必須使用 AWS CloudHSM 金鑰存放區建置自己的應用程式。如需其他資訊，請參閱使用 AWS CloudHSM 金鑰存放區的文章。

步驟 3：註冊 JCE 提供商

若要在 Java CloudProvider 組態中註冊 JCE 提供者，請依照下列步驟執行：

1. 在 Java 安裝中開啟 java.security 組態檔案進行編輯。

2. 在 java.security 組態檔案中，新增 com.amazonaws.cloudhsm.jce.provider.CloudHsmProvider 為最後一個提供者。例如，如果 java.security 檔案中有九個供應商，請將下列提供商新增為區段中的最後一個供應商。

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

注意

將 AWS CloudHSM 提供者新增為較高優先順序可能會對您的系統效能造成負面影響，因為 AWS CloudHSM 提供者會優先處理可能會安全卸載到軟體的作業。最佳作法是永遠指定您要用於作業的提供者，無論是軟體提供者還是以軟體為基礎的提供者。 AWS CloudHSM

注意

使用 Keytool 和 AWS CloudHSM 金鑰存放區產生金鑰時，指定 -providerName、-providerclass 和 -providerpath 命令列選項可能會出現錯誤。

使用 AWS CloudHSM 密鑰存儲與密鑰工具

Keytool 是常見的金鑰和憑證任務的常用命令列公用程式。完整的 Keytool 教學並不在 AWS CloudHSM 文件範圍之內。本文說明在透過 AWS CloudHSM 金鑰存放區 AWS CloudHSM 做為信任根使用時，您應該搭配各種 keytool 函式使用的特定參數。

將 keytool 與 AWS CloudHSM 金鑰存放區搭配使用時，請為任何 keytool 命令指定下列引數：

Linux

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

Windows

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

如果要使用金鑰存放區建立新金鑰存放區檔 AWS CloudHSM 案，請參閱使用 AWS CloudHSM KeyStore。若要要使用現有的金鑰存放區，請使用金鑰存放區引數指定其名稱 (包含路徑) 至 Keytool。如果您在 keytool 指令中指定不存在的金鑰存放區檔案，則金鑰存放區會建立新的 AWS CloudHSM 金鑰存放區檔案。

使用 Keytool 建立新金鑰

您可以使用 Keytool 產生由 AWS CloudHSM的 JCE SDK 支援的 RSA、AES 和 DESede 類型金鑰。

重要

通過 keytool 生成的密鑰在軟件中生成，然後導入到一個可提取 AWS CloudHSM 的，持久的密鑰。

我們強烈建議您不要在 Keytool 中產生不可匯出的金鑰，然後又匯入相對應的憑證至金鑰存放區。如果您透過 keytool 和 Jarsigner 使用可擷取的 RSA 或 EC 金鑰，則提供者會從匯出金鑰，然後在本機使用金鑰進行簽署作業。 AWS CloudHSM

如果您有多個用戶端執行個體連線到 AWS CloudHSM 叢集，請注意，在一個用戶端執行個體的金鑰存放區匯入憑證不會自動讓憑證可用於其他用戶端執行個體。若要在每個用戶端執行個體上註冊金鑰和相關憑證，您必須執行 Java 應用程式，如 使用 Keytool 產生 CSR 所述。或者，您可以在一個用戶端上進行必要的變更，並將產生的金鑰存放區檔案複製到其他每個用戶端執行個體。

範例 1：產生帶對稱 AES-256 金鑰，並將其儲存在工作目錄中名為「my_keystore.store」的金鑰存放區檔案中。將 <secret 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\*"'

範例 2：產生 RSA 2048 金鑰對，並將其儲存在工作目錄中名為「my_keystore.store」的金鑰存放區檔案中。將 <RSA key pair 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\*"'		

您可以在 Java 程式庫中找到支援的簽章演算法清單。

使用 Keytool 刪除金鑰

金 AWS CloudHSM 鑰存放區不支援刪除金鑰。您可以使用可銷毀介面的銷毀方法刪除金鑰。

((Destroyable) key).destroy();

使用 Keytool 產生 CSR

如果您使用 OpenSSL 動態引擎，您可以在產生憑證簽署要求 (CSR) 時獲得最大的彈性。以下命令使用 Keytool 來產生具有別名 my-key-pair 的金鑰對適用 CSR。

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

注意

若要使用 Keytool 的金鑰對，該金鑰對必須再指定的金鑰存放區檔案中有項目。如果您要使用非 Keytool 產生的金鑰對，則必須將金鑰和憑證中繼資料匯入至金鑰存放區。如需匯入金鑰存放區資料的說明，請參閱 使用 keytool 將中繼憑證和根憑證匯入 AWS CloudHSM 金鑰存放區 。

使用 keytool 將中繼憑證和根憑證匯入 AWS CloudHSM 金鑰存放區

若要匯入 CA 憑證，您必須在新匯入的憑證上啟用完整憑證鏈的驗證。以下為命令的範例。

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

如果您將多個用戶端執行個體連接到 AWS CloudHSM 叢集，則在一個用戶端執行個體的金鑰存放區匯入憑證不會自動讓憑證可用於其他用戶端執行個體。您必須在每個用戶端執行個體上匯入憑證。

使用 keytool 從 AWS CloudHSM 密鑰存儲中刪除證書

下列範例顯示命令如何從 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\*"'

如果您將多個用戶端執行個體連接到 AWS CloudHSM 叢集，刪除一個用戶端執行個體金鑰存放區上的憑證並不會自動從其他用戶端執行個體移除憑證。您必須在每個用戶端執行個體上刪除憑證。

使用 keytool 將工作證書導入 AWS CloudHSM 密鑰存儲中

憑證簽署要求 (CSR) 簽署後，您就可以將其匯入 AWS CloudHSM 金鑰存放區，並與適當的金鑰對建立關聯。以下是命令範例。

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

別名應為金鑰存放區中具有關聯憑證的金鑰對。如果金鑰是非 Keytool 產生，或是在不同的用戶端執行個體上產生，您就必須先將金鑰和憑證中繼資料匯入金鑰存放區。

憑證鏈必須是可驗證的。如果您無法驗證憑證，則可能需要將簽署 (憑證授權單位) 憑證匯入金鑰存放區，以便驗證該鏈結。

使用 Keytool 匯出憑證

下列範例會產生二進位 X.509 格式的憑證。若要匯出人類可讀的憑證，請新增 -rfc 至 -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\*"'

使用 AWS CloudHSM 金鑰存放區與 Jarsigner

Jarsigner 是一種流行的命令行實用程序，用於使用安全地存儲在 HSM 上的密鑰簽名 JAR 文件。完整的 Jarsigner 教學並不在 AWS CloudHSM 文件範圍之內。本節說明您應該使用的 Jarsigner 參數，透過 AWS CloudHSM 金鑰存放區以信任的根目錄來簽署和驗證簽名。 AWS CloudHSM

設定金鑰和憑證

在您可以使用 Jarsigner 簽署 JAR 文件之前，請確保您已經設定或完成以下步驟：

1. 遵循 AWS CloudHSM 金鑰存放區必要條件中的指引。

2. 設定您的簽署金鑰以及應儲存在目前伺服器或用戶端執行個體的金 AWS CloudHSM 鑰存放區中的相關憑證和憑證鏈結。在上建立金鑰， AWS CloudHSM 然後將關聯的中繼資料匯入金 AWS CloudHSM 鑰存放區。如果您要使用 Keytool 設定金鑰和憑證，請參閱 使用 Keytool 建立新金鑰。如果您使用多個用戶端執行個體來簽署 JAR，請建立金鑰並匯入憑證鏈。然後將生成的金鑰存放區文件複製到每個用戶端執行個體。如果您經常產生新的金鑰，您可能會發現將憑證個別匯入至每個用戶端執行個體更容易。

3. 整個憑證鏈必須是可驗證的。若要讓憑證鏈結可驗證，您可能需要將 CA 憑證和中繼憑證新增至 AWS CloudHSM 金鑰存放區。有關使用 Java 程式碼驗證憑證鏈的說明，請參閱 使用 AWS CloudHSM 和 Jarsigner 簽署 JAR 檔案 中的程式碼片段。如果需要，您也可以使用 Keytool 匯入憑證。如需使用 Keytool 的說明，請參閱 使用 keytool 將中繼憑證和根憑證匯入 AWS CloudHSM 金鑰存放區 。

使用 AWS CloudHSM 和 Jarsigner 簽署 JAR 檔案

使用以下命令來簽署 JAR 檔案：

Linux;

對於 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>
						

適用於 OpenJDK 11、第 17 OpenJDK 和第 21 OpenJDK

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

對於 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>
						

適用於 OpenJDK 11、第 17 OpenJDK 和第 21 OpenJDK

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>
						

使用以下命令來驗證已簽署的 JAR：

Linux

對於 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>
						

適用於 OpenJDK 11、第 17 OpenJDK 和第 21 OpenJDK

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

對於 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>
						

適用於 OpenJDK 11、第 17 OpenJDK 和第 21 OpenJDK

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>
						

已知問題

1. 不支持使用 Keytool 和 Jarsigner 的 EC 金錀。