本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# AWS CloudHSM 用戶端 SDK 5 的 JCE 提供者
AWS CloudHSM JCE 提供者是從 Java 密碼編譯延伸 (JCE) 提供者架構建置的提供者實作。JCE 可讓您使用 Java 開發套件 (JDK) 執行密碼編譯操作。在本指南中， AWS CloudHSM JCE 提供者有時稱為 JCE 提供者。使用 JCE 提供者和 JDK 將密碼編譯操作卸載至 HSM。如需故障診斷，請參閱 [適用於 的 JCE 開發套件的已知問題 AWS CloudHSM](ki-jce-sdk.md)。
如需關於使用用戶端 SDK 3 的資訊，請參閱 [使用先前的 SDK 版本來使用 AWS CloudHSM](choose-client-sdk.md)。
**Topics**
+ [安裝 AWS CloudHSM 用戶端 SDK 5 的 JCE 提供者](java-library-install_5.md)
+ [AWS CloudHSM 用戶端 SDK 5 的 JCE 提供者支援的金鑰類型](java-lib-keys_5.md)
+ [AWS CloudHSM 用戶端 SDK 5 的 JCE 提供者中的金鑰管理基本概念](java-library-key-basics_5.md)
+ [AWS CloudHSM 用戶端 SDK 5 的 JCE 提供者支援的機制](java-lib-supported_5.md)
+ [AWS CloudHSM 用戶端 SDK 5 支援的 Java 金鑰屬性](java-lib-attributes_5.md)
+ [Java for Client SDK 5 AWS CloudHSM 軟體程式庫的程式碼範例](java-samples.md)
+ [AWS CloudHSM JCE 提供者 Javadocs](java-javadocs_5.md)
+ [用戶端 SDK 5 的AWS CloudHSM KeyStore Java 類別](alternative-keystore_5.md)
+ [AWS CloudHSM JCE for Client SDK 5 的進階組態](java-lib-configs.md)
# 安裝 AWS CloudHSM 用戶端 SDK 5 的 JCE 提供者
AWS CloudHSM 用戶端 SDK 5 的 JCE 提供者與 OpenJDK 8、OpenJDK 11、OpenJDK 17、OpenJDK 21 和 OpenJDK 25 相容。您可以從 [OpenJDK 網站](https://openjdk.java.net/)下載 OpenJDK 8 和 OpenJDK11。
使用下列各節來安裝憑證並提供給供應商。
**注意**
若要使用用戶端 SDK 5 執行單一 HSM 叢集，您必須先將 `disable_key_availability_check` 設定為 `True` 來管理用戶端金鑰持久性。如需詳細資訊，請參閱[金鑰同步處理](manage-key-sync.md)和[用戶端 SDK 5 設定工具](configure-sdk-5.md)。
**Topics**
+ [步驟 1：安裝 JCE 提供者](#install-java-library_5)
+ [步驟 2：提供登入資料給 JCE 供應商](#java-library-credentials_5)
## 步驟 1：安裝 JCE 提供者
1. 使用下列命令下載和安裝 JCE 提供者。
------
#### [ Amazon Linux 2023 ]
在 x86\$164 架構上安裝 Amazon Linux 2023 的 JCE 提供者：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Amzn2023/cloudhsm-jce-latest.amzn2023.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.amzn2023.x86_64.rpm
```
在 ARM64 架構上安裝 Amazon Linux 2023 的 JCE 提供者：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Amzn2023/cloudhsm-jce-latest.amzn2023.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.amzn2023.aarch64.rpm
```
------
#### [ Amazon Linux 2 ]
在 x86\$164 架構上安裝 Amazon Linux 2 的 JCE 提供者：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-jce-latest.el7.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.el7.x86_64.rpm
```
在 ARM64 架構上安裝 Amazon Linux 2 的 JCE 提供者：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-jce-latest.el7.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.el7.aarch64.rpm
```
------
#### [ RHEL 10 (10.0\$1) ]
在 x86\$164 架構上安裝 RHEL 10 的 JCE 提供者：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL10/cloudhsm-jce-latest.el10.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.el10.x86_64.rpm
```
在 ARM64 架構上安裝 RHEL 10 的 JCE 提供者：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL10/cloudhsm-jce-latest.el10.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.el10.aarch64.rpm
```
------
#### [ RHEL 9 (9.2\$1) ]
在 x86\$164 架構上安裝 RHEL 9 (9.2\$1) 的 JCE 提供者：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL9/cloudhsm-jce-latest.el9.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.el9.x86_64.rpm
```
在 ARM64 架構上安裝 RHEL 9 (9.2\$1) 的 JCE 提供者：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL9/cloudhsm-jce-latest.el9.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.el9.aarch64.rpm
```
------
#### [ RHEL 8 (8.3\$1) ]
在 x86\$164 架構上安裝 RHEL 8 的 JCE 提供者：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-jce-latest.el8.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.el8.x86_64.rpm
```
在 ARM64 架構上安裝 RHEL 8 的 JCE 提供者：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-jce-latest.el8.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.el8.aarch64.rpm
```
------
#### [ Ubuntu 24.04 LTS ]
在 x86\$164 架構上安裝 Ubuntu 24.04 LTS 的 JCE 提供者：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Noble/cloudhsm-jce_latest_u24.04_amd64.deb
```
```
$ sudo apt install ./cloudhsm-jce_latest_u24.04_amd64.deb
```
在 ARM64 架構上安裝 Ubuntu 24.04 LTS 的 JCE 提供者：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Noble/cloudhsm-jce_latest_u24.04_arm64.deb
```
```
$ sudo apt install ./cloudhsm-jce_latest_u24.04_arm64.deb
```
------
#### [ Ubuntu 22.04 LTS ]
在 x86\$164 架構上安裝 Ubuntu 22.04 LTS 的 JCE 提供者：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Jammy/cloudhsm-jce_latest_u22.04_amd64.deb
```
```
$ sudo apt install ./cloudhsm-jce_latest_u22.04_amd64.deb
```
在 ARM64 架構上安裝 Ubuntu 22.04 LTS 的 JCE 提供者：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Jammy/cloudhsm-jce_latest_u22.04_arm64.deb
```
```
$ sudo apt install ./cloudhsm-jce_latest_u22.04_arm64.deb
```
------
#### [ Windows Server ]
在 x86\$164 架構上安裝適用於 Windows Server 的 JCE 提供者，以管理員身分開啟 PowerShell，然後執行下列命令：
```
PS C:\> wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Windows/AWSCloudHSMJCE-latest.msi -Outfile C:\AWSCloudHSMJCE-latest.msi
```
```
PS C:\> Start-Process msiexec.exe -ArgumentList '/i C:\AWSCloudHSMJCE-latest.msi /quiet /norestart /log C:\client-install.txt' -Wait
```
------
1. 引導用戶端 SDK 5。如需有關啟動程序的詳細資訊，請參閱 [引導用戶端 SDK](cluster-connect.md#connect-how-to)。
1. 找出下列 JCE 提供者檔案：
------
#### [ Linux ]
+ `/opt/cloudhsm/java/cloudhsm-.jar`
+ `/opt/cloudhsm/bin/configure-jce`
+ `/opt/cloudhsm/bin/jce-info`
------
#### [ Windows ]
+ `C:\Program Files\Amazon\CloudHSM\java\cloudhsm-.jar>`
+ `C:\Program Files\Amazon\CloudHSM\bin\configure-jce.exe`
+ `C:\Program Files\Amazon\CloudHSM\bin\jce_info.exe`
------
## 步驟 2：提供登入資料給 JCE 供應商
HSM 需要先驗證您的 Java 應用程式，應用程式才能使用 HSM。HSM 會使用明確登入或隱含登入方法，進行驗證。
**明確登入**：此方法可讓您直接在應用程式中提供 AWS CloudHSM 憑證。它使用 [https://docs.oracle.com/javase/8/docs/api/java/security/AuthProvider.html](https://docs.oracle.com/javase/8/docs/api/java/security/AuthProvider.html) 中的方法，讓您可以在 pin 模式中傳遞 CU 使用者名稱和密碼。如需詳細資訊，請參閱[登入 HSM](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java) 程式碼範例。
**隱含登入**：此方法可讓您在新的屬性檔案、系統屬性或環境變數中設定 AWS CloudHSM 憑證。
+ **系統屬性**：執行應用程式時，您可以透過系統屬性設定憑證。以下範例示範兩種不同的作法：
------
#### [ Linux ]
```
$ java -DHSM_USER= -DHSM_PASSWORD=
```
```
System.setProperty("HSM_USER","");
System.setProperty("HSM_PASSWORD","");
```
------
#### [ Windows ]
```
PS C:\> java -DHSM_USER= -DHSM_PASSWORD=
```
```
System.setProperty("HSM_USER","");
System.setProperty("HSM_PASSWORD","");
```
------
+ **環境變數**：將憑證設定為環境變數。
**注意**
設定環境變數時，您必須逸出 Shell 可能解譯的任何特殊字元。
------
#### [ Linux ]
```
$ export HSM_USER=
$ export HSM_PASSWORD=
```
------
#### [ Windows ]
```
PS C:\> $Env:HSM_USER=""
PS C:\> $Env:HSM_PASSWORD=""
```
------
如果應用程式未提供登入資料，或者，如果您在 HSM 驗證工作階段之前嘗試操作，就可能無法使用登入資料。在這些情況下，適用於 Java 的 CloudHSM 軟體程式庫會按照以下順序，搜尋登入資料：
1. 系統屬性
1. 環境變數
# AWS CloudHSM 用戶端 SDK 5 的 JCE 提供者支援的金鑰類型
適用於 Java AWS CloudHSM 的軟體程式庫可讓您產生下列金鑰類型。
****
| 金鑰類型 | Description |
| --- | --- |
| AES | 產生 128 位元、192 位元和 256 位元的 AES 金鑰。 |
| Triple DES (3DES, DESede) | 產生 192 位元三重 DES 金鑰 [*](#java-lib-keys_5-note-1)。 |
| EC | 產生 EC 金鑰對：NIST curves secp224r1 (P-224)、secp256r1 (P-256)、secp256k1 (Blockchain)、secp384r1 (P-384) 和 secp521r1 (P-521)。 |
| GENERIC\$1SECRET | 產生 1 到 800 位元組的一般機密。 |
| HMAC | 支援 SHA1、SHA224、SHA256、SHA384 和 SHA512 雜湊。 |
| RSA | 產生 2048 位元至 4096 位元的 RSA 金鑰，以 256 位元為單位遞增。 |
\$1 根據 NIST 指引，2023 年之後 FIPS 模式的叢集不允許這樣做。對於處於非 FIPS 模式的叢集，在 2023 年之後仍然允許。如需詳細資訊，請參閱 [FIPS 140 合規性：2024 機制棄用](compliance-dep-notif.md#compliance-dep-notif-1)。
# AWS CloudHSM 用戶端 SDK 5 的 JCE 提供者中的金鑰管理基本概念
JCE 提供者的金鑰管理基本概念包括匯入金鑰、匯出金鑰、透過控制代碼載入金鑰或刪除金鑰。如需管理金鑰的詳細資訊，請參閱[管理金鑰](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java)的程式碼範例。
您也可以在 [程式碼範例](java-samples.md) 中尋找更多 JCE 提供者程式碼範例。
# AWS CloudHSM 用戶端 SDK 5 的 JCE 提供者支援的機制
本主題提供 JCE 供應商使用 AWS CloudHSM 用戶端 SDK 5 支援機制的相關資訊。如需 支援的 Java 密碼編譯架構 (JCA) 介面和引擎類別的相關資訊 AWS CloudHSM，請參閱下列主題。
**Topics**
+ [產生金鑰與金鑰對函數](#java-gen-key-pairs-5)
+ [密碼函數](#java-ciphers_5)
+ [簽署和驗證函數](#java-sign-verify_5)
+ [Digest 函數](#java-digests_5)
+ [雜湊訊息驗證碼 (HMAC) 函數](#java-mac_5)
+ [加密式訊息驗證程式碼 (CMAC) 函數](#java-cmac_5)
+ [金鑰協議函數](#java-key-derivation_5)
+ [使用金鑰 Factory 將金鑰轉換為金錀規格](#java-key-factories)
+ [機制註釋](#w2aac25c21c25c15c23)
## 產生金鑰與金鑰對函數
適用於 Java AWS CloudHSM 的軟體程式庫可讓您使用下列操作來產生金鑰和金鑰對函數。
+ `RSA`
+ `EC`
+ `AES`
+ `DESede (Triple DES)`請參閱備註 [1](#java-gen-key-pairs-5-note-1)
+ `GenericSecret`
## 密碼函數
適用於 Java AWS CloudHSM 的軟體程式庫支援下列演算法、模式和填補組合。
| 演算法 | Mode | 填補 | 備註 |
| --- | --- | --- | --- |
| AES | CBC | `AES/CBC/NoPadding` `AES/CBC/PKCS5Padding` | 實作 `Cipher.ENCRYPT_MODE` 和 `Cipher.DECRYPT_MODE`。 實作 `Cipher.UNWRAP_MODE for AES/CBC NoPadding` |
| AES | ECB | `AES/ECB/PKCS5Padding` `AES/ECB/NoPadding` | 實作 `Cipher.ENCRYPT_MODE` 和 `Cipher.DECRYPT_MODE`。 |
| AES | CTR | `AES/CTR/NoPadding` | 實作 `Cipher.ENCRYPT_MODE` 和 `Cipher.DECRYPT_MODE`。 |
| AES | GCM | `AES/GCM/NoPadding` | 實作 `Cipher.WRAP_MODE`、`Cipher.UNWRAP_MODE`、`Cipher.ENCRYPT_MODE` 和 `Cipher.DECRYPT_MODE`。執行 AES-GCM 加密時，HSM 會忽略請求中的初始化向量 (IV)，並使用自己產生的 IV。操作完成後，您必須呼叫 `Cipher.getIV()` 以取得 IV。 |
| AESWrap | ECB | `AESWrap/ECB/NoPadding` `AESWrap/ECB/PKCS5Padding` `AESWrap/ECB/ZeroPadding` | 實作 `Cipher.WRAP_MODE` 和 `Cipher.UNWRAP_MODE`。 |
| DESede (三重 DES) | CBC | `DESede/CBC/PKCS5Padding` `DESede/CBC/NoPadding` | 實作 `Cipher.ENCRYPT_MODE` 和 `Cipher.DECRYPT_MODE`。請參閱下列備註 [1](#java-gen-key-pairs-5-note-1) 查看即將進行的變更。 |
| DESede (三重 DES) | ECB | `DESede/ECB/NoPadding` `DESede/ECB/PKCS5Padding` | 實作 `Cipher.ENCRYPT_MODE` 和 `Cipher.DECRYPT_MODE`。請參閱下列備註 [1](#java-gen-key-pairs-5-note-1) 查看即將進行的變更。 |
| RSA | ECB | `RSA/ECB/PKCS1Padding` **請參閱備註 [1](#java-gen-key-pairs-5-note-1)** `RSA/ECB/OAEPPadding` `RSA/ECB/OAEPWithSHA-1ANDMGF1Padding` `RSA/ECB/OAEPWithSHA-224ANDMGF1Padding` `RSA/ECB/OAEPWithSHA-256ANDMGF1Padding` `RSA/ECB/OAEPWithSHA-384ANDMGF1Padding` `RSA/ECB/OAEPWithSHA-512ANDMGF1Padding` | 實作 `Cipher.WRAP_MODE`、`Cipher.UNWRAP_MODE`、`Cipher.ENCRYPT_MODE` 和 `Cipher.DECRYPT_MODE`。 |
| RSA | ECB | `RSA/ECB/NoPadding` | 實作 `Cipher.ENCRYPT_MODE` 和 `Cipher.DECRYPT_MODE`。 |
| RSAAESWrap | ECB | `RSAAESWrap/ECB/OAEPPadding` `RSAAESWrap/ECB/OAEPWithSHA-1ANDMGF1Padding` `RSAAESWrap/ECB/OAEPWithSHA-224ANDMGF1Padding` `RSAAESWrap/ECB/OAEPWithSHA-256ANDMGF1Padding` `RSAAESWrap/ECB/OAEPWithSHA-384ANDMGF1Padding` `RSAAESWrap/ECB/OAEPWithSHA-512ANDMGF1Padding` | 實作 `Cipher.WRAP_MODE` 和 `Cipher.UNWRAP_MODE`。 |
## 簽署和驗證函數
適用於 Java AWS CloudHSM 的軟體程式庫支援以下類型的簽章和驗證。使用用戶端 SDK 5 和具有雜湊功能的簽章演算法，資料會先在軟體中進行本機雜湊處理，然後再傳送至 HSM 以進行簽章/驗證。這意味著 SDK 可以對任何大小的資料進行雜湊處理。
**RSA 簽章類型**
+ `NONEwithRSA`
+ `RSASSA-PSS`
+ `SHA1withRSA`
+ `SHA1withRSA/PSS`
+ `SHA1withRSAandMGF1`
+ `SHA224withRSA`
+ `SHA224withRSAandMGF1`
+ `SHA224withRSA/PSS`
+ `SHA256withRSA`
+ `SHA256withRSAandMGF1`
+ `SHA256withRSA/PSS`
+ `SHA384withRSA`
+ `SHA384withRSAandMGF1`
+ `SHA384withRSA/PSS`
+ `SHA512withRSA`
+ `SHA512withRSAandMGF1`
+ `SHA512withRSA/PSS`
**ECDSA 簽章類型**
+ `NONEwithECDSA`
+ `SHA1withECDSA`
+ `SHA224withECDSA`
+ `SHA256withECDSA`
+ `SHA384withECDSA`
+ `SHA512withECDSA`
## Digest 函數
適用於 Java AWS CloudHSM 的軟體程式庫支援下列訊息摘要。使用用戶端 SDK 5，資料會在軟體中進行本機雜湊處理。這意味著 SDK 可以對任何大小的資料進行雜湊處理。
+ `SHA-1`
+ `SHA-224`
+ `SHA-256`
+ `SHA-384`
+ `SHA-512`
## 雜湊訊息驗證碼 (HMAC) 函數
適用於 Java AWS CloudHSM 的軟體程式庫支援下列 HMAC 演算法。
+ `HmacSHA1` （最大資料大小，以位元組為單位：16288)
+ `HmacSHA224` （最大資料大小，以位元組為單位：16256)
+ `HmacSHA256` （最大資料大小，以位元組為單位：16288)
+ `HmacSHA384` （最大資料大小，以位元組為單位：16224)
+ `HmacSHA512` （最大資料大小，以位元組為單位：16224)
## 加密式訊息驗證程式碼 (CMAC) 函數
CMAC (加密式訊息驗證程式碼) 使用區塊密碼和金錀建立訊驗證代碼 (MAC)。與 HMAC 不同之處在於，它們使用 MAC 區塊對稱金錀方法而非雜湊方法。
適用於 Java AWS CloudHSM 的軟體程式庫支援下列 CMAC 演算法。
+ `AESCMAC`
## 金鑰協議函數
適用於 Java AWS CloudHSM 的軟體程式庫支援具有金鑰衍生函數 (KDF) 的 ECDH。支援下列 KDF 類型：
+ `ECDHwithX963SHA1KDF` 支援 X9.63 KDF SHA1 演算法[2](#kdf2)
+ `ECDHwithX963SHA224KDF` 支援 X9.63 KDF SHA224 演算法[2](#kdf2)
+ `ECDHwithX963SHA256KDF` 支援 X9.63 KDF SHA256 演算法[2](#kdf2)
+ `ECDHwithX963SHA384KDF` 支援 X9.63 KDF SHA384 演算法[2](#kdf2)
+ `ECDHwithX963SHA512KDF` 支援 X9.63 KDF SHA512 演算法[2](#kdf2)
## 使用金鑰 Factory 將金鑰轉換為金錀規格
您可以使用金鑰工廠將金鑰轉換為金鑰規格。JCE AWS CloudHSM 有兩種類型的金鑰工廠：
**SecretKeyFactory:** 用於匯入或衍生對稱金錀。使用 SecretKeyFactory，您可以傳遞支援的 Key 或支援的 KeySpec 將對稱金鑰匯入或衍生到 AWS CloudHSM。下列是 KeyFactory 支援的規格：
+ 如採用 SecretKeyFactory 的 `generateSecret` 方法，可支援下列 [KeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/KeySpec.html) 類別：
+ **KeyAttributesMap** 可用來匯入具有額外屬性的金鑰位元組，做為 CloudHSM 金鑰。可從[此處](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java)查看範例。
+ **[SecretKeySpec](https://docs.oracle.com/javase/8/docs/api/javax/crypto/spec/SecretKeySpec.html)** 可將對稱 key spec 匯入為 CloudHSM Key 匯入。
+ **AesCmacKdfParameterSpec** 可使用另一個 CloudHSM AES Key 來衍生對稱金錀。
**注意**
SecretKeyFactory 的 `translateKey` 方法接受任何實現[金鑰](https://docs.oracle.com/javase/8/docs/api/java/security/Key.html)介面的金鑰。
**KeyFactory:** 用於匯入非對稱金鑰。使用 KeyFactory，您可以傳遞支援的 Key 或支援的 KeySpec 將對稱金鑰匯入到 AWS CloudHSM。如需詳細資訊，請參閱下列資源：
+ 如採用 KeyFactory 的 `generatePublic` 方法，可支援下列 [KeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/KeySpec.html) 類別：
+ 適用於 RSA 和 EC KeyTypes 的 CloudHSM KeyAttributesMap 包括：
+ 適用於 RSA 和 EC Public KeyTypes 的 CloudHSM KeyAttributesMap 包括：可從[此處](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java)查看範例。
+ 適用於 RSA 和 EC Public Key 的 [X509EncodedKeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/X509EncodedKeySpec.html)
+ 適用於 RSA Public Key 的 [RSAPublicKeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/RSAPublicKeySpec.html)
+ 適用於 EC Public Key 的 [ECPublicKeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/ECPublicKeySpec.html)
+ 如採用 KeyFactory 的 `generatePrivate` 方法，可支援下列 [KeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/KeySpec.html) 類別：
+ 適用於 RSA 和 EC KeyTypes 的 CloudHSM KeyAttributesMap 包括：
+ 適用於 RSA 和 EC Public KeyTypes 的 CloudHSM KeyAttributesMap 包括：可從[此處](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java)查看範例。
+ 適用於 EC and RSA Private Key 的 [PKCS8EncodedKeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/PKCS8EncodedKeySpec.html)
+ 適用於 RSA Private Key 的 [RSAPrivateCrtKeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/RSAPrivateCrtKeySpec.html)
+ 適用於 EC Private Key 的 [ECPrivateKeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/ECPrivateKeySpec.html)
如採用 KeyFactory 的 `translateKey` 方法，其可接受任何實現[金鑰](https://docs.oracle.com/javase/8/docs/api/java/security/Key.html)介面的金鑰。
## 機制註釋
【1】 根據 NIST 指引，在 2023 年之後，不允許在 FIPS 模式下使用叢集。對於處於非 FIPS 模式的叢集，在 2023 年之後仍然允許。如需詳細資訊，請參閱 [FIPS 140 合規性：2024 機制棄用](compliance-dep-notif.md#compliance-dep-notif-1)。
【2】 金鑰衍生函數 (KDFs) 是在 [NIST 特殊出版物 800-56A 修訂版 3](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-56Ar3.pdf) 中指定。
# AWS CloudHSM 用戶端 SDK 5 支援的 Java 金鑰屬性
本主題提供有關 AWS CloudHSM 用戶端 SDK 5 支援的 Java 金鑰屬性的資訊。本主題說明如何使用 JCE 提供程序的專屬擴充功能來設定金鑰屬性。請在以下操作期間，使用此擴充功能來設定支援的金鑰屬性及其值：
+ 金鑰產生
+ 金鑰匯入
如需如何使用金錀屬性的範例，請參閱 [Java for Client SDK 5 AWS CloudHSM 軟體程式庫的程式碼範例](java-samples.md)。
**Topics**
+ [了解屬性](#java-understanding-attributes_5)
+ [支援的屬性](#java-attributes_5)
+ [設定金鑰的屬性](#java-setting-attributes_5)
## 了解屬性
使用金鑰屬性來指定金鑰物件上允許的動作，包括公有金鑰、私有金鑰或秘密金鑰。在建立金鑰物件操作期間定義金鑰屬性和值。
Java Cryptography Extension (JCE) 未指定應該如何設定金鑰屬性的值，因此預設情況下會允許大部分動作。相反地，PKCS\$111 標準定義了一組具有更嚴格預設值的完整屬性。從 JCE 提供者 3.1 開始， AWS CloudHSM 提供專屬擴充功能，可讓您為常用屬性設定更嚴格的值。
## 支援的屬性
您可以設定下表中屬性的值。最佳實務是，只為您希望更具有限制性的屬性設定值。如果您未指定值， AWS CloudHSM 會使用下表中指定的預設值。預設值欄位中的空白儲存格表示屬性沒有獲派指定預設值。
****
| 屬性 | 預設值 | 備註 | | 對稱金鑰 | 金鑰對中的公有金鑰 | 金鑰對中的私有金鑰 | |
| --- | --- | --- | --- | --- | --- | --- | --- |
| DECRYPT | TRUE | | TRUE | True 表示您可以使用金鑰來解密任何緩衝區。對於其 WRAP 設定為 true 的金鑰，通常將此設定為 FALSE。 |
| DERIVE | | | | 可以使用金鑰來衍生其他金鑰。 |
| ENCRYPT | TRUE | TRUE | | True 表示您可以使用金鑰來加密任何緩衝區。 |
| EXTRACTABLE | TRUE | | TRUE | True 表示您可以從 HSM 匯出此金鑰。 |
| ID | | | | 用於識別金鑰的使用者定義值。 |
| KEY\$1TYPE | | | | 用於識別金鑰的類型 (AES、DESede、一般私密錦綸、EC 或 RSA)。 |
| LABEL | | | | 使用者定義的字串可方便您識別 HSM 上的金鑰。為了遵循最佳實務，請為每個金鑰使用唯一標籤，以便日後更容易找到。 |
| LOCAL | | | | 表示 HSM 產生的金鑰。 |
| OBJECT\$1CLASS | | | | 用於識別金錀 (SecretKey、PublicKey 或 PrivateKey) 的物件類別。 |
| PRIVATE | TRUE | TRUE | TRUE | True 表示在使用者通過驗證之前，使用者可能無法存取金鑰。為了清楚起見，使用者必須經過身分驗證 AWS CloudHSM 才能存取 上的任何金鑰，即使此屬性設為 FALSE。 |
| SIGN | TRUE | | TRUE | True 表示您可以使用金鑰來簽署訊息摘要。對於公有金鑰和您已封存的私有金鑰，這通常會設定為 FALSE。 |
| SIZE | | | | 定義金錀大小的屬性。如需有關支援金鑰大小的詳細資訊，請參閱[用戶端 SDK 5 的支援機制](https://docs.aws.amazon.com/cloudhsm/latest/userguide/java-lib-supported_5.html#java-keys_5)。 |
| TOKEN | FALSE | FALSE | FALSE | 永久金鑰，會跨叢集中的所有 HSM 進行複寫並包含在備份中。TOKEN = FALSE 代表一個暫時性金鑰，該金鑰會在與 HSM 的連接中斷時自動擦除。 |
| UNWRAP | TRUE | | TRUE | True 表示您可以使用金鑰來取消包裝 (匯入) 另一個金鑰。 |
| VERIFY | TRUE | TRUE | | True 表示您可以使用金鑰來驗證簽章。對於私有金鑰，這通常被設定為 FALSE。 |
| WRAP | TRUE | TRUE | | True 表示您可以使用該金鑰來包裝另一個金鑰。對於私有金鑰，您通常將此設定為 FALSE。 |
| WRAP\$1WITH\$1TRUSTED | FALSE | | FALSE | True 表示金鑰只能與 TRUSTED 屬性為 True 的金鑰進行包裝和取消包裝。一旦 金錀 WRAP\$1WITH\$1TRUSTED 設置為 True，該屬性僅為只讀狀態，不能將其設置為 False。如要了解有關信任包裝的資訊，請參閱[使用受信任金鑰控制金鑰解除包裝](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_using_trusted_keys_control_key_wrap.html)。 |
**注意**
您可以在 PKCS \$111 程式庫中獲得更廣泛的屬性支援。如需詳細資訊，請參閱[支援的 PKCS \$111 屬性](pkcs11-attributes.md)。
## 設定金鑰的屬性
`KeyAttributesMap` 是類似 Java 映射的物件，您可以使用它來設定金鑰物件的屬性值。`KeyAttributesMap` 函數的方法類似於用於 Java 映射處理的方法。
若要設定屬性的自訂值，您有兩個選項：
+ 使用下表中列出的方法
+ 使用本文稍後示範的產生器模式
屬性映射物件支援以下列方法設定屬性：
****
| 作業 | 傳回值 | `KeyAttributesMap` 方法 |
| --- | --- | --- |
| 獲取現有金鑰的金鑰屬性的值 | 物件 (包含值) 或 null | **get**(keyAttribute) |
| 填入一個金鑰屬性的值 | 與金鑰屬性相關聯的先前值，如果金鑰屬性沒有映射，則為 null | **put**(keyAttribute, value) |
| 填入多個金鑰屬性的值 | N/A | **putAll**(keyAttributesMap) |
| 從屬性映射中刪除金鑰值對 | 與金鑰屬性相關聯的先前值，如果金鑰屬性沒有映射，則為 *null* | **remove**(keyAttribute) |
**注意**
您未明確指定的任何屬性都會設定為[支援的屬性](#java-attributes_5)中上表所列的預設值。
### 設定金鑰對的屬性
使用 Java 類別 `KeyPairAttributesMap` 來處理金鑰對的金鑰屬性。`KeyPairAttributesMap` 封裝了兩個 `KeyAttributesMap` 物件；一個用於公有金鑰，另一個用於私有金鑰。
若要分別為公有金鑰和私有金鑰設定個別屬性，您可以在該金鑰對應的 `KeyAttributes` 映射物件上使用 `put()` 方法。使用 `getPublic()` 方法來擷取公有金鑰的屬性映射，以及使用 `getPrivate()` 來擷取私有金鑰的屬性映射。使用 `putAll()` 與金鑰對屬性映射作為引數，填入公有金鑰和私有金鑰對的多個金鑰屬性值。
# Java for Client SDK 5 AWS CloudHSM 軟體程式庫的程式碼範例
本主題提供用戶端 SDK 5 Java 程式碼範例 AWS CloudHSM 的資源和資訊。
## 先決條件
執行範例之前，您必須先設定環境：
+ 安裝並設定 [Java 密碼編譯延伸模組 (JCE) 提供者](java-library-install_5.md#install-java-library_5)。
+ 設定有效的 [HSM 使用者名稱和密碼](manage-hsm-users.md)。加密使用者 (CU) 許可足夠執行這些任務。在每個範例中，您的應用程式會使用這些登入資料來登入 HSM。
+ 決定如何提供憑證給 [JCE 提供者](java-library-install_5.md#java-library-credentials_5)。
## 程式碼範例
下列程式碼範例會示範如何使用 [AWS CloudHSM JCE 提供者](java-library.md)來執行基本任務。在 [GitHub](https://github.com/aws-samples/aws-cloudhsm-jce-examples/tree/sdk5) 可取得更多程式碼範例。
+ [登入 HSM](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java)
+ [管理金鑰](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java)
+ [產生對稱金鑰](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/SymmetricKeys.java)
+ [產生非對稱金鑰](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/AsymmetricKeys.java)
+ [使用 AES-GCM 進行加密和解密](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/AESGCMEncryptDecryptRunner.java)
+ [使用 AES-CTR 進行加密和解密](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/AESCTREncryptDecryptRunner.java)
+ [使用 DESede-ECB 加密和解密](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/DESedeECBEncryptDecryptRunner.java)請參閱附註 [1](#java-samples-code-5-note-1)
+ [使用 RSA 金錀簽署和驗證](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/RSAOperationsRunner.java)
+ [使用 EC 金錀簽署和驗證](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/ECOperationsRunner.java)
+ [使用支援的金鑰屬性](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyAttributesRunner.java)
+ [使用 CloudHSM 金鑰存放區](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyStoreExampleRunner.java)
【1】 根據 NIST 指引，在 2023 年之後，不允許在 FIPS 模式下使用叢集。對於處於非 FIPS 模式的叢集，在 2023 年之後仍然允許。如需詳細資訊，請參閱 [FIPS 140 合規性：2024 機制棄用](compliance-dep-notif.md#compliance-dep-notif-1)。
# AWS CloudHSM JCE 提供者 Javadocs
使用 JCE 提供者 Javadocs 取得 AWS CloudHSM JCE SDK 中定義的 Java 類型和方法的使用資訊。若要下載最新的 Javadocs AWS CloudHSM，請參閱下載頁面上的 [AWS CloudHSM 最新的用戶端 SDK 版本](latest-releases.md)一節。
您可以將 Javadocs 匯入整合式開發環境 (IDE)，或在網頁瀏覽器中檢視 Javadocs。
# 用戶端 SDK 5 的AWS CloudHSM KeyStore Java 類別
AWS CloudHSM `KeyStore` 類別提供特殊用途的 PKCS12 金鑰存放區。此金鑰存放區可與您的金鑰資料一起儲存憑證，並將其與在 AWS CloudHSM儲存的金鑰資料連結在一起。`KeyStore` 類別實作 Java AWS CloudHSM 密碼編譯延伸 (JCE) 的`KeyStore`服務提供者界面 (SPI)。如需使用 `KeyStore` 的詳細資訊，請參閱 [Class KeyStore](https://devdocs.io/openjdk~8/java/security/keystore)。
**注意**
由於憑證是公有資訊，且為了最大化密碼編譯金鑰的儲存容量， AWS CloudHSM 不支援在 HSMs上儲存憑證。
## 為 AWS CloudHSM 用戶端 SDK 5 選擇適當的金鑰存放區
AWS CloudHSM Java 密碼編譯延伸 (JCE) 供應商提供特殊用途的 AWS CloudHSM KeyStore。 AWS CloudHSM `KeyStore` 類別支援將金鑰操作卸載至 HSM、本機儲存憑證和憑證型操作。
載入特殊用途的 CloudHSM 金鑰存放區，如下所示：
```
KeyStore ks = KeyStore.getInstance("CloudHSM")
```
## 初始化 AWS CloudHSM KeyStore 用戶端 SDK 5
以與登入 JCE 提供者相同的方式登入 AWS CloudHSM KeyStore。您可以使用環境變數或系統屬性檔案，並且在開始使用 CloudHSM 金鑰存放區之前應先登入。如需使用 JCE 提供者登入 HSM 的範例，請參閱[登入 HSM](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java)。
如有需要，您可以指定一組密碼來加密保存金鑰儲存資料的本機 PKCS12 檔案。當您建立 AWS CloudHSM 金鑰存放區時，您可以設定密碼，並在使用載入、設定和取得方法時提供密碼。
請依照以下方式，將新的 CloudHSM 金鑰存放區物件執行個體化：
```
ks.load(null, null);
```
使用 `store` 方法將金鑰存放區資料寫入檔案。從那時起，您可以依照以下方式，搭配來源檔案和密碼使用 `load` 方法載入現有的金鑰存放區：
```
ks.load(inputStream, password);
```
## Use AWS CloudHSM KeyStore 或 AWS CloudHSM 用戶端 SDK 5
AWS CloudHSM KeyStore 符合 JCE [類別 KeyStore](https://devdocs.io/openjdk~8/java/security/keystore) 規格，並提供下列函數。
+ `load`
從特定的輸入串流載入金鑰存放區。如果在儲存金鑰存放區時設定了密碼，則必須提供相同的密碼才能成功載入。將這兩個參數設為 Null 以初始化一個新的空金鑰存放區。
```
KeyStore ks = KeyStore.getInstance("CloudHSM");
ks.load(inputStream, password);
```
+ `aliases`
傳回特定的金鑰存放區執行個體中的所有項目別名名稱列舉。結果包括本機儲存在 PKCS12 檔案中的物件，以及常駐於 HSM 的物件。
**範本程式碼：**
```
KeyStore ks = KeyStore.getInstance("CloudHSM");
for(Enumeration entry = ks.aliases(); entry.hasMoreElements();) {
String label = entry.nextElement();
System.out.println(label);
}
```
+ `containsalias`
如果金鑰存放區可存取至少一個有指定別名的物件，則傳回 True。金鑰存放區會檢查本機儲存在 PKCS12 檔案中的物件，以及常駐於 HSM 的物件。
+ `deleteEntry`
從本機 PKCS12 檔案刪除憑證項目。不支援使用 AWS CloudHSM KeyStore 刪除存放在 HSM 中的金鑰資料。您可以使用[可銷毀](https://devdocs.io/openjdk~8/javax/security/auth/destroyable#destroy--)介面 `destroy` 的銷毀方法刪除金錀。
```
((Destroyable) key).destroy();
```
+ `getCertificate`
如果可用，則傳回與別名相關聯的憑證。如果別名不存在或參考非憑證的物件，則函數會傳回 NULL。
```
KeyStore ks = KeyStore.getInstance("CloudHSM");
Certificate cert = ks.getCertificate(alias);
```
+ `getCertificateAlias`
傳回第一個資料符合特定憑證的金鑰存放區項目名稱 (別名)。
```
KeyStore ks = KeyStore.getInstance("CloudHSM");
String alias = ks.getCertificateAlias(cert);
```
+ `getCertificateChain`
傳回與特定別名相關聯的憑證鏈。如果別名不存在或參考非憑證的物件，則函數會傳回 NULL。
+ `getCreationDate`
傳回由給定別名辨識的項目建立日期。如果沒有建立日期，則函數會傳回憑證生效的日期。
+ `getKey`
GetKey 會傳遞給 HSM 並傳回與特定標籤對應的金鑰物件。由於 `getKey` 會直接查詢 HSM，因此無論金鑰存放區是否產生金鑰，都可用於 HSM 上的任何金鑰。
```
Key key = ks.getKey(keyLabel, null);
```
+ `isCertificateEntry`
檢查有特定別名的項目是否代表憑證項目。
+ `isKeyEntry`
檢查有特定別名的項目是否代表金鑰項目。此動作會在 PKCS12 檔案和 HSM 中搜尋別名。
+ `setCertificateEntry`
指定特定憑證至特定別名。如果特定的別名已用於識別金鑰或憑證，則會擲出 `KeyStoreException`。您可以使用 JCE 程式碼來取得金鑰物件，然後使用金鑰存放區 `SetKeyEntry` 方法連結憑證至密鑰。
+ 有 `byte[]` 金鑰的 `setKeyEntry`
**用戶端 SDK 5 目前不支援此 API。**
+ 有 `Key` 物件的 `setKeyEntry`
指定特定金鑰至特定別名，並將其儲存在 HSM 內。如果該金鑰未儲存在 HSM 內，則該金錀將做為可擷取的工作階段金鑰匯入至 HSM。
如果 `Key` 物件屬於類型 `PrivateKey`，則必須附有相對應的憑證鏈。
如果別名已經存在，則 `SetKeyEntry` 呼叫會擲出 `KeyStoreException` 並防止覆寫金鑰。如果必須覆寫金鑰，請使用 KMU 或 JCE。
+ `engineSize`
傳回金鑰存放區中的項目數目。
+ `store`
以 PKCS12 檔案格式儲存金鑰存放區至特定輸出串流，並使用特定的密碼加以保護。此外，它仍然保留載入的金鑰 (使用 `setKey` 呼叫的組合)。
# AWS CloudHSM JCE for Client SDK 5 的進階組態
AWS CloudHSM JCE 供應商包含下列進階組態，這些組態不屬於大多數客戶使用的一般組態。
+ [連接至多個叢集](java-lib-configs-multi.md)
+ [使用 JCE 擷取金鑰](java-lib-configs-getencoded.md)
+ [重試適用於 JCE 的組態](java-lib-configs-retry.md)
# 使用 JCE 提供者連線至多個 AWS CloudHSM 叢集
此組態允許單一用戶端執行個體與多個 AWS CloudHSM 叢集通訊。與單一執行個體僅能與單一叢集進行通訊相比，該組態可節省某些使用案例的成本。`CloudHsmProvider` 類別 AWS CloudHSM是 [Java Security 提供者類別](https://docs.oracle.com/javase/8/docs/api/java/security/Provider.html)的實作。此類別的每個執行個體都代表整個 AWS CloudHSM 叢集的連線。您可以將此類別實例化，並將其新增至 Java 安全提供者清單中，以便您可以使用標準的 JCE 類別與其進行互動。
下面範例會將此類別實例化，並將其新增至 Java 安全提供者清單：
```
if (Security.getProvider(CloudHsmProvider.PROVIDER_NAME) == null) {
Security.addProvider(new CloudHsmProvider());
}
```
可以使用下列兩種方式來對 `CloudHsmProvider` 進行設定：
1. 使用檔案進行設定 (預設組態)
1. 使用程式碼設定
下列主題說明這些組態，以及如何連線至多個叢集。
**Topics**
+ [使用 檔案設定 AWS CloudHSM `CloudHsmProvider`類別 （預設組態）](java-lib-configs-default.md)
+ [使用程式碼設定類別 AWS CloudHSM `CloudHsmProvider`](java-lib-configs-using-code.md)
+ [連線至多個 AWS CloudHSM 叢集](java-lib-connecting-to-multiclusters.md)
# 使用 檔案設定 AWS CloudHSM `CloudHsmProvider`類別 （預設組態）
設定 AWS CloudHSM `CloudHsmProvider`類別的預設方法是使用 檔案。
當您使用預設建構函數實例化 `CloudHsmProvider` 時，根據預設，它會在 Linux 的 `/opt/cloudhsm/etc/cloudhsm-jce.cfg` 路徑中尋找組態檔案。可使用 `configure-jce` 設定此組態檔案。
使用預設的建構函數所建立的物件將會使用預設的 CloudHSM 提供者名稱 `CloudHSM`。提供者名稱有助於與 JCE 進行互動，以讓它了解各種作業應使用哪個提供者。以下為使用 CloudHSM 提供者名稱進行加密作業的範例：
```
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding", "CloudHSM");
```
# 使用程式碼設定類別 AWS CloudHSM `CloudHsmProvider`
從用戶端 SDK 5.8.0 版開始，您也可以使用 Java 程式碼來設定 AWS CloudHSM `CloudHsmProvider`類別。使用 `CloudHsmProviderConfig` 類別的物件可以進行設定。您可以使用 `CloudHsmProviderConfigBuilder` 建置此物件。
`CloudHsmProvider` 有另一個接受 `CloudHsmProviderConfig` 物件的建構函數，如下列範例顯示。
**Example**
```
CloudHsmProviderConfig config = CloudHsmProviderConfig.builder()
.withCluster(
CloudHsmCluster.builder()
.withHsmCAFilePath(hsmCAFilePath)
.withClusterUniqueIdentifier("CloudHsmCluster1")
.withServer(CloudHsmServer.builder().withHostIP(hostName).build())
.build())
.build();
CloudHsmProvider provider = new CloudHsmProvider(config);
```
在此範例中，JCE 提供者的名稱為 `CloudHsmCluster1`。這是應用程式接著可用來與 JCE 互動的名稱：
**Example**
```
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding", "CloudHsmCluster1");
```
或者，應用程式還可以使用上面建立的提供者物件，讓 JCE 了解要使用該提供者以進行作業：
```
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding", provider);
```
如果未使用 `withClusterUniqueIdentifier` 方法指定唯一識別碼，則會為您建立一個隨機產生的提供者名稱。若要取得此隨機產生的識別碼，應用程式可以呼叫 `provider.getName()` 以取得識別碼。
# 連線至多個 AWS CloudHSM 叢集
每個 `CloudHsmProvider`代表 AWS CloudHSM 叢集的連線。如果您想要從同一個應用程式與另一個叢集進行通訊，您可以使用其他叢集的組態建立另一個物件 `CloudHsmProvider`，然後您可以使用提供者物件或使用提供者名稱與該叢集互動，如下列範例所顯示。
**Example**
```
CloudHsmProviderConfig config = CloudHsmProviderConfig.builder()
.withCluster(
CloudHsmCluster.builder()
.withHsmCAFilePath(hsmCAFilePath)
.withClusterUniqueIdentifier("CloudHsmCluster1")
.withServer(CloudHsmServer.builder().withHostIP(hostName).build())
.build())
.build();
CloudHsmProvider provider1 = new CloudHsmProvider(config);
if (Security.getProvider(provider1.getName()) == null) {
Security.addProvider(provider1);
}
CloudHsmProviderConfig config2 = CloudHsmProviderConfig.builder()
.withCluster(
CloudHsmCluster.builder()
.withHsmCAFilePath(hsmCAFilePath2)
.withClusterUniqueIdentifier("CloudHsmCluster2")
.withServer(CloudHsmServer.builder().withHostIP(hostName2).build())
.build())
.build();
CloudHsmProvider provider2 = new CloudHsmProvider(config2);
if (Security.getProvider(provider2.getName()) == null) {
Security.addProvider(provider2);
}
```
設定上述兩個提供者 (兩個叢集) 後，您可以使用提供者物件或使用提供者名稱與其進行互動。
此範例顯示了如何與 `cluster1` 進行通訊，在此基礎上，您可以使用下列範例進行 AES/GCM/NoPadding 操作。
```
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding", provider1);
```
在同一個應用程序中使用提供者名稱在第二個叢集上產生「AES」金鑰，您還可以使用下列範例：
```
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding", provider2.getName());
```
# 使用 JCE for 擷取金鑰 AWS CloudHSM
Java 密碼編譯延伸模組 (JCE) 使用允許插入不同密碼編譯實作的架構。 AWS CloudHSM 會運送其中一個 JCE 提供者，將密碼編譯操作卸載至 HSM。對於使用儲存在 AWS CloudHSM 中金鑰的其他大多數 JCE 提供者，他們必須將金鑰位元組以純文字形式從 HSM 擷取到機器的記憶體中以供使用。HSM 通常僅允許將金鑰擷取為包裝物件，而非純文字。不過，為了支援供應商間整合使用案例， AWS CloudHSM 允許選擇加入組態選項，以明確地擷取金鑰位元組。
**重要**
只要指定 AWS CloudHSM 供應商或使用 AWS CloudHSM 金鑰物件，JCE AWS CloudHSM 就會將操作卸載至 。如果您預期在 HSM 內進行作業，則您不需要以純文字形式擷取金鑰。當您的應用程式因第三方程式庫或 JCE 提供者的限制而無法使用安全機制 (例如，包裝和取消包裝金鑰) 時，僅需要以純文字形式擷取金鑰。
根據預設， AWS CloudHSM JCE 提供者允許擷取**公有金鑰**以使用外部 JCE 提供者。一律允許使用下列方法：
| 類別 | Method | Format (getEncoded) |
| --- | --- | --- |
| EcPublicKey | getEncoded() | X.509 |
| | getW() | N/A |
| RSAPublicKey | getEncoded() | X.509 |
| | getPublicExponent() | N/A |
| CloudHsmRsaPrivateCrtKey | getPublicExponent() | N/A |
根據預設， AWS CloudHSM JCE 提供者不允許擷取**私有**或**私密**金鑰的清除金鑰位元組。如果您的使用案例需要，您可在下列情況下以純文字形式擷取**私用**金鑰或**秘密**金鑰的金鑰位元組：
1. 私用金鑰和秘密金鑰的 `EXTRACTABLE` 屬性設定為 **true**。
+ 根據預設，私用金鑰和秘密金鑰的 `EXTRACTABLE` 屬性設定為 **true**。`EXTRACTABLE` 金鑰是允許從 HSM 匯出的金鑰。如需詳細資訊，請參閱 [Client SDK 5](java-lib-attributes_5.md) 支援的 Java 屬性。
1. 私用金鑰和私密金鑰的 `WRAP_WITH_TRUSTED` 屬性設定為 **false**。
+ `getEncoded`、`getPrivateExponent` 和 `getS` 不能與無法以純文字形式匯出的私用金鑰搭配使用。`WRAP_WITH_TRUSTED` 不允許您的私用金鑰以純文字形式匯出 HSM。如需詳細資訊，請參閱[使用受信任的金鑰控制金鑰取消包裝](manage-keys-using-trusted-keys.md)。
# 允許 JCE 提供者從 中擷取私有金鑰秘密 AWS CloudHSM
使用下列步驟允許 AWS CloudHSM JCE 提供者擷取您的私有金鑰秘密。
**重要**
變更此組態後，就可以從 HSM 叢集以純文字形式擷取所有 `EXTRACTABLE` 金鑰位元組。為了獲得更好的安全性，您應考慮使用[金鑰包裝方法](java-lib-supported_5.md)將金鑰安全地從 HSM 擷取出來。這可防止意外從 HSM 擷取金鑰位元組。
1. 使用下列命令，可在 JCE 中啟用您的**私用**金鑰或**秘密**金鑰：
------
#### [ Linux ]
```
$ /opt/cloudhsm/bin/configure-jce --enable-clear-key-extraction-in-software
```
------
#### [ Windows ]
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-jce.exe" --enable-clear-key-extraction-in-software
```
------
1. 啟用以純文字形式擷取金鑰後，即可啟用下列方法將私用金鑰擷取至記憶體。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/get-encoded-take-out-private-keys.html)
如果您想還原預設行為，且不允許 JCE 以純文字形式匯出金鑰，請執行下列命令：
------
#### [ Linux ]
```
$ /opt/cloudhsm/bin/configure-jce --disable-clear-key-extraction-in-software
```
------
#### [ Windows ]
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-jce.exe" --disable-clear-key-extraction-in-software
```
------
# 重試適用於 的 JCE 命令 AWS CloudHSM
AWS CloudHSM 用戶端 SDK 5.8.0 和更新版本具有內建的自動重試策略，將從用戶端重試 HSM 限流操作。當 HSM 因過於忙於執行先前操作而無法接受更多要求而限制操作時，用戶端 SDK 會嘗試重試限流操作 (最多 3 次)，同時以指数形式回退。此自動重試策略可以設定為兩種模式中的其中一種：**關閉**模式和**標準**模式。
+ **關閉**：用戶端 SDK 將不會針對 HSM 的任何限流操作執行任何重試政策。
+ **標準**：這是用戶端 SDK 5.8.0 及更新版本的預設模式。在此模式下，用戶端 SDK 會以指數回退形式自動重試限流操作。
如需詳細資訊，請參閱[HSM 調節](troubleshoot-hsm-throttling.md)。
## 將重試命令設定為關閉模式
------
#### [ Linux ]
**將 Linux 上用戶端 SDK 5 重試命令設定為 **off****
+ 您可以使用下列命令將重試組態設定為 **off** 模式：
```
$ sudo /opt/cloudhsm/bin/configure-jce --default-retry-mode off
```
------
#### [ Windows ]
**將 Windows 上用戶端 SDK 5 重試命令設定為 **off****
+ 您可以使用下列命令將重試組態設定為 **off** 模式：
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-jce.exe" --default-retry-mode off
```
------