本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用用戶端 SDK 5 來使用 AWS CloudHSM
AWS CloudHSM 包含兩個主要用戶端 SDK 版本：
+ 用戶端 SDK 5：這是我們最新預設的用戶端 SDK。如需有關其優點和優勢的資訊，請參閱 [AWS CloudHSM 用戶端 SDK 5 的優點](client-sdk-5-benefits.md)。
+ 用戶端 SDK 3：這是我們較舊的用戶端 SDK。它包括一組完整的組件，用於基於平台和語言的應用程序兼容性和管理工具。
如需從用戶端 SDK 3 遷移至用戶端 SDK 5 的指示，請參閱 [從 AWS CloudHSM 用戶端 SDK 3 遷移至用戶端 SDK 5](client-sdk-migration.md)。
本主題說明用戶端 SDK 5。若要檢查您正在使用的用戶端 SDK 版本，請參閱
**Topics**
+ [AWS CloudHSM 用戶端 SDK 5 的優點](client-sdk-5-benefits.md)
+ [AWS CloudHSM 用戶端 SDK 5 支援的平台](client-supported-platforms.md)
+ [AWS CloudHSM 用戶端 SDK 5 的 PKCS \$111 程式庫](pkcs11-library.md)
+ [適用於 AWS CloudHSM 用戶端 SDK 5 的 OpenSSL 動態引擎](openssl-library.md)
+ [AWS CloudHSM 用戶端 SDK 5 的 OpenSSL 提供者](openssl-provider-library.md)
+ [AWS CloudHSM 用戶端 SDK 5 的金鑰儲存提供者 (KSP)](ksp-library.md)
+ [AWS CloudHSM 用戶端 SDK 5 的 JCE 提供者](java-library.md)
# AWS CloudHSM 用戶端 SDK 5 的優點
相較於 AWS CloudHSM 用戶端 SDK 3，用戶端 SDK 5 更易於管理，提供卓越的可設定性和更高的可靠性。用户端 SDK 5 還為用户端 SDK 3 提供了一些額外的關鍵優勢。
**專為無伺服器架構所設計**
用戶端 SDK 5 不需要用戶端常駐程式，因此您不再需要管理背景服務。其可以通過幾種重要方式幫助用戶：
+ 簡化應用程式的啟動程序。開始使用 CloudHSM 需在執行應用程式之前先設定 SDK。
+ 无需持續執行程序，可更輕鬆地與 Lambda 和彈性容器服務 (ECS) 等無伺服器元件的集成。
**更好的第三方集成和更輕鬆的可攜性**
用户端 SDK 5 嚴格遵循 JCE 規範，並在不同的 JCE 提供者和更好的第三方集成之間提供了更輕鬆的可移植性
**改善使用者體驗和可設定性**
用戶端 SDK 5 提高了日誌消息的可讀性，並提供了更清晰的異常和錯誤處理機制，让使用者更容易进行自助分類。SDK 5 還提供了各種組態，這些組態列在[設定工具頁面](https://docs.aws.amazon.com/cloudhsm/latest/userguide/configure-sdk-5.html)中。
**更廣泛的平台支援**
用户端 SDK 5 為現代作業平台提供了更多支援。其包括對 ARM 技術的支援，以及對 [JCE](https://docs.aws.amazon.com/cloudhsm/latest/userguide/java-library_5.html)、[PKCS \$111](https://docs.aws.amazon.com/cloudhsm/latest/userguide/pkcs11-library.html) 和 [OpenSSL](https://docs.aws.amazon.com/cloudhsm/latest/userguide/openssl-library.html) 的更多支援。如需詳細資訊，請參閱 [支援的平台](client-supported-platforms.md)。
**IPv6 連線支援**
用戶端 SDK 5.14\$1 支援使用 IPv6 連線至雙堆疊 HSMs。
**附加功能和機制**
用戶端 SDK 5 包含用戶端 SDK 3 中無法使用的其他功能和機制，而用戶端 SDK 5 未來會繼續新增更多機制。
# AWS CloudHSM 用戶端 SDK 5 支援的平台
AWS CloudHSM 用戶端 SDK 的每個版本的基本支援都不同。SDK 中元件的平台支援通常符合基礎支援，但並非總是如此。若要判斷特定元件的平台支援，請先確定您想要的平台出現在 SDK 的基礎區段中，然後檢查元件區段中是否有任何排除或任何其他相關資訊。
AWS CloudHSM 僅支援 64 位元作業系統。
平台支援會隨時間變更。舊版 CloudHSM 用戶端 SDK 可能不支援此處列出的所有作業系統。使用版本說明來判斷舊版 CloudHSM 用戶端 SDK 的作業系統支援。如需詳細資訊，請參閱 [AWS CloudHSM 用戶端 SDK 的下載](client-history.md)。
如需先前用戶端 SDK 支援的平台，請參閱 [AWS CloudHSM 用戶端 SDK 3 支援的平台](sdk3-support.md)
用戶端 SDK 5 不需要用戶端常駐程式。
**Topics**
+ [Linux 支援用戶端 SDK 5](sdk8-linux.md)
+ [Windows 支援用戶端 SDK 5](sdk8-windows.md)
+ [無伺服器支援用戶端 SDK 5](sdk8-serverless.md)
+ [用戶端 SDK 5 的 HSM 相容性](sdk5-hsm-types.md)
# Linux 支援 AWS CloudHSM 用戶端 SDK 5
AWS CloudHSM 用戶端 SDK 5 支援下列 Linux 作業系統和平台。
| 支援平台 | X86\$164 架構 | ARM 架構 |
| --- | --- | --- |
| Amazon Linux 2 | 是 | 是 |
| Amazon Linux 2023 | 是 | 是 |
| Red Hat Enterprise Linux 8 (8.3\$1) | 是 | 是 |
| Red Hat Enterprise Linux 9 (9.2\$1) | 是 | 是 |
| Red Hat Enterprise Linux 10 (10.0\$1) | 是 | 是 |
| Ubuntu 22.04 LTS | 是 | 是 |
| Ubuntu 24.04 LTS | 是 | 是 |
+ SDK 5.16 是提供 Ubuntu 20.04 LTS 平台支援的最後版本。如需詳細資訊，請參閱 [Ubuntu 網站](https://ubuntu.com/blog/ubuntu-20-04-lts-end-of-life-standard-support-is-coming-to-an-end-heres-how-to-prepare)。
+ SDK 5.12 是提供 CentOS 7 (7.8\$1) 平台支援的最後版本。如需詳細資訊，請參閱 [CentOS 網站](https://blog.centos.org/2023/04/end-dates-are-coming-for-centos-stream-8-and-centos-linux-7/)。
+ SDK 5.12 是提供 Red Hat Enterprise Linux 7 (7.8\$1) 平台支援的最後版本。如需詳細資訊，請參閱 [Red Hat 網站](https://www.redhat.com/en/technologies/linux-platforms/enterprise-linux/rhel-7-end-of-maintenance)。
+ SDK 5.4.2 是提供 CentOS 8 平台支援的最後版本。如需詳細資訊，請參閱 [CentOS 網站](https://www.centos.org/centos-linux-eol/)。
# Windows 支援 AWS CloudHSM 用戶端 SDK 5
AWS CloudHSM 用戶端 SDK 5 支援下列版本的 Windows Server。
+ Microsoft Windows Server 2016
+ Microsoft Windows Server 2019
+ Microsoft Windows Server 2022
+ Microsoft Windows Server 2025
# AWS CloudHSM 用戶端 SDK 5 的無伺服器支援
AWS CloudHSM 用戶端 SDK 5 支援下列無 AWS 伺服器服務。
+ AWS Lambda
+ Docker/ECS
# AWS CloudHSM 用戶端 SDK 5 的 HSM 相容性
下表說明 HSMs 的 AWS CloudHSM 用戶端 SDK 5 相容性。
| hsm1.medium | hsm2m.medium |
| --- | --- |
| 與用戶端 SDK 5.0.0 版及更新版本相容。 | 與用戶端 SDK 5.9.0 版及更新版本相容。 |
# AWS CloudHSM 用戶端 SDK 5 的 PKCS \$111 程式庫
PKCS \$111 是在硬體安全模組 (HSMs) 上執行加密作業的標準。 AWS CloudHSM 提供與 PKCS \$111 2.40 版相容的 PKCS \$111 程式庫的實作方式。
如需關於啟動載入的資訊，請參閱 [連接至叢集](cluster-connect.md)。如需故障診斷，請參閱 [的 PKCS \$111 程式庫已知問題 AWS CloudHSMPKCS \$111 程序庫的已知問題](ki-pkcs11-sdk.md)。
如需關於使用用戶端 SDK 3 的資訊，請參閱 [使用先前的 SDK 版本來使用 AWS CloudHSM](choose-client-sdk.md)。
**Topics**
+ [安裝 PKCS \$111 程式庫](pkcs11-library-install.md)
+ [驗證為 PKCS \$111 程式庫](pkcs11-pin.md)
+ [金鑰類型](pkcs11-key-types.md)
+ [機制](pkcs11-mechanisms.md)
+ [API 操作](pkcs11-apis.md)
+ [金錀屬性](pkcs11-attributes.md)
+ [程式碼範例](pkcs11-samples.md)
+ [進階組態。](pkcs11-library-configs.md)
+ [憑證儲存](pkcs11-certificate-storage.md)
# 安裝 AWS CloudHSM 用戶端 SDK 5 的 PKCS \$111 程式庫
本主題提供安裝 AWS CloudHSM 用戶端 SDK 5 版本系列的最新版 PKCS \$111 程式庫的說明。如需關於用戶端 SDK 或 PKCS \$111 程式庫的詳細資訊，請參閱[使用用戶端 SDK](use-hsm.md) 和 [PKCS \$111 程式庫](pkcs11-library.md)。
使用用戶端 SDK 5 時，您無需安裝或執行用戶端常駐程式。
若要使用用戶端 SDK 5 執行單一 HSM 叢集，您必須先將 `disable_key_availability_check` 設定為 `True` 來管理用戶端金鑰持久性。如需詳細資訊，請參閱[金鑰同步處理](manage-key-sync.md)和[用戶端 SDK 5 設定工具](configure-sdk-5.md)。
如需關於用戶端 SDK 5 中 PKCS \$111 程式庫的詳細資訊，請參閱 [PKCS \$111 程式庫](pkcs11-library.md)。
**注意**
若要使用用戶端 SDK 5 執行單一 HSM 叢集，您必須先將 `disable_key_availability_check` 設定為 `True` 來管理用戶端金鑰持久性。如需詳細資訊，請參閱[金鑰同步處理](manage-key-sync.md)和[用戶端 SDK 5 設定工具](configure-sdk-5.md)。
**若要安裝和設定 PKCS \$111 程式庫**
1. 使用以下命令來下載和安裝 PKCS \$111 程式庫。
------
#### [ Amazon Linux 2023 ]
在 X86\$164 架構上安裝 Amazon Linux 2023 的 PKCS \$111 程式庫：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Amzn2023/cloudhsm-pkcs11-latest.amzn2023.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-pkcs11-latest.amzn2023.x86_64.rpm
```
在 ARM64 架構上安裝 Amazon Linux 2023 的 PKCS \$111 程式庫：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Amzn2023/cloudhsm-pkcs11-latest.amzn2023.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-pkcs11-latest.amzn2023.aarch64.rpm
```
------
#### [ Amazon Linux 2 ]
安裝適用於 Amazon Linux 2 (X86\$164 架構) 的 PKCS \$111 程式庫：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-pkcs11-latest.el7.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-pkcs11-latest.el7.x86_64.rpm
```
安裝適用於 Amazon Linux 2 (ARM64 架構) 的 PKCS \$111 程式庫：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-pkcs11-latest.el7.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-pkcs11-latest.el7.aarch64.rpm
```
------
#### [ RHEL 10 (10.0\$1) ]
在 X86\$164 架構上安裝 RHEL 10 的 PKCS \$111 程式庫：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL10/cloudhsm-pkcs11-latest.el10.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-pkcs11-latest.el10.x86_64.rpm
```
在 ARM64 架構上安裝 RHEL 10 的 PKCS \$111 程式庫：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL10/cloudhsm-pkcs11-latest.el10.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-pkcs11-latest.el10.aarch64.rpm
```
------
#### [ RHEL 9 (9.2\$1) ]
在 X86\$164 架構上安裝 RHEL 9 的 PKCS \$111 程式庫：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL9/cloudhsm-pkcs11-latest.el9.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-pkcs11-latest.el9.x86_64.rpm
```
在 ARM64 架構上安裝 RHEL 9 的 PKCS \$111 程式庫：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL9/cloudhsm-pkcs11-latest.el9.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-pkcs11-latest.el9.aarch64.rpm
```
------
#### [ RHEL 8 (8.3\$1) ]
在 X86\$164 架構上安裝 RHEL 8 的 PKCS \$111 程式庫：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-pkcs11-latest.el8.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-pkcs11-latest.el8.x86_64.rpm
```
在 ARM64 架構上安裝 RHEL 8 的 PKCS \$111 程式庫：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-pkcs11-latest.el8.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-pkcs11-latest.el8.aarch64.rpm
```
------
#### [ Ubuntu 24.04 LTS ]
在 X86\$164 架構上安裝適用於 Ubuntu 24.04 LTS 的 PKCS \$111 程式庫：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Noble/cloudhsm-pkcs11_latest_u24.04_amd64.deb
```
```
$ sudo apt install ./cloudhsm-pkcs11_latest_u24.04_amd64.deb
```
在 ARM64 架構上安裝適用於 Ubuntu 24.04 LTS 的 PKCS \$111 程式庫：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Noble/cloudhsm-pkcs11_latest_u24.04_arm64.deb
```
```
$ sudo apt install ./cloudhsm-pkcs11_latest_u24.04_arm64.deb
```
------
#### [ Ubuntu 22.04 LTS ]
安裝適用於 Ubuntu 22.04 LTS (X86\$164 架構) 的 PKCS \$111 程式庫：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Jammy/cloudhsm-pkcs11_latest_u22.04_amd64.deb
```
```
$ sudo apt install ./cloudhsm-pkcs11_latest_u22.04_amd64.deb
```
在 ARM64 架構上安裝適用於 Ubuntu 22.04 LTS 的 PKCS \$111 程式庫：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Jammy/cloudhsm-pkcs11_latest_u22.04_arm64.deb
```
```
$ sudo apt install ./cloudhsm-pkcs11_latest_u22.04_arm64.deb
```
------
#### [ Windows Server ]
在 X86\$164 架構上安裝適用於 Windows Server 的 PKCS \$111 程式庫：
1. 下載[適用於用戶端 SDK 5 的 PKCS \$111 程式庫](https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Windows/AWSCloudHSMPKCS11-latest.msi)。
1. 以 Windows 管理權限執行 PKCS \$111 程式庫安裝程式 (**AWSCloudHSMPKCS11-latest.msi**)。
------
1. 使用設定工具指定發行憑證的位置。如需說明，請參閱[指定憑證的位置。](cluster-connect.md#specify-cert-location)。
1. 若要連線到您的叢集，請參閱 [引導用戶端 SDK](cluster-connect.md#connect-how-to)。
1. 您可於下列位置找到 PKCS \$111 程式庫檔案：
+ Linux 二進位檔案、組態指令碼和日誌文檔：
```
/opt/cloudhsm
```
Windows 二進位檔案：
```
C:\Program Files\Amazon\CloudHSM
```
Windows組態指令碼和日誌檔案：
```
C:\ProgramData\Amazon\CloudHSM
```
# 驗證至 AWS CloudHSM 用戶端 SDK 5 的 PKCS \$111 程式庫
當您使用 PKCS \$111 程式庫時，您的應用程式會在 HSMs 中以特定[加密使用者 (CU)](manage-hsm-users.md) 身分執行 AWS CloudHSM。您的應用程式只能檢視和管理 CU 所擁有和共用的金鑰。您可以使用 HSM 中現有的 CU，或為應用程式建立新的 CU。如需關於管理 CU 的資訊，請參閱[使用 CloudHSM CLI 管理 HSM 使用者](manage-hsm-users-chsm-cli.md)和[使用 CloudHSM 管理公用程式 (CMU) 管理 HSM 使用者](manage-hsm-users-cmu.md)。
若要將 CU 指定給 PKCS \$111 程式庫，請使用 PKCS \$111 [C\$1Login 函數](http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/os/pkcs11-base-v2.40-os.html#_Toc385057915)的 pin 參數。對於 AWS CloudHSM，接腳參數的格式如下：
```
:
```
例如，以下命令會將 PKCS \$111 程式庫 pin 設定給使用者名稱為 `CryptoUser` 和密碼為 `CUPassword123!` 的 CU。
```
CryptoUser:CUPassword123!
```
# AWS CloudHSM 用戶端 SDK 5 的 PKCS \$111 程式庫支援的金鑰類型
AWS CloudHSM 用戶端 SDK 5 的 PKCS \$111 程式庫支援下列金鑰類型。
****
| 金鑰類型 | Description |
| --- | --- |
| AES | 產生 128 位元、192 位元和 256 位元的 AES 金鑰。 |
| Triple DES (3DES, DESede) | 產生 192 位元的三重 DES 金鑰。請參閱下列備註 [1](#key-types-1) 查看即將進行的變更。 |
| EC | 使用 secp224r1 (P-224)、secp256r1 (P-256)、secp256k1 (Blockchain)、secp384r1 (P-384) 和 secp521r1 (P-521)曲線產生金鑰。 |
| GENERIC\$1SECRET | 產生 1 到 800 位元組的一般機密。 |
| 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 的 PKCS \$111 程式庫支援的機制
PKCS \$111 程式庫與 PKCS \$111 規格的 2.40 版相容。若要使用 PKCS \$111 叫用加密功能，請利用指定機制呼叫函數。下列各節摘要了 AWS CloudHSM 用戶端 SDK 5 支援的函數和機制組合。
PKCS \$111 程式庫支援下列演算法：
+ **加密和解密**：AES-CBC、AES-CTR、AES-ECB、AES-GCM、DES3-CBC、DES3-ECB、RSA-OAEP 和 RSA-PKCS
+ **簽署和驗證**：RSA、HMAC 和 ECDSA；無論是否使用雜湊皆不影響
+ **雜湊/摘要**：SHA1、SHA224、SHA256、SHA384 和 SHA512
+ **金鑰包裝**：AES 金鑰包裝、[1](#mech1) AES-GCM、RSA-AES 和 RSA-OAEP
+ **金鑰衍生** – SP800-108 計數器 KDF 和 ECDH 搭配 KDF （支援的 KDF 演算法為 X9.63 搭配 SHA1, SHA224, SHA256, SHA384, SHA512)
**Topics**
+ [產生金鑰與金鑰對函數](#pkcs11-mech-function-genkey)
+ [簽署和驗證函數](#pkcs11-mech-function-signverify)
+ [簽名恢復和驗證復原函數](#pkcs11-mech-function-sr-vr)
+ [Digest 函數](#pkcs11-mech-function-digest)
+ [加密和解密函數](#pkcs11-mech-function-enc-dec)
+ [衍生金鑰函數](#pkcs11-mech-function-derive-key)
+ [包裝和解包函數](#pkcs11-mech-function-wrap-unwrap)
+ [每個機制的資料大小上限](#pkcs11-mech-max)
+ [機制註釋](#pkcs11-mech-annotations)
## 產生金鑰與金鑰對函數
PKCS \$111 程式庫 AWS CloudHSM 的軟體程式庫可讓您使用下列機制來產生金鑰和金鑰對函數。
+ `CKM_RSA_PKCS_KEY_PAIR_GEN`
+ `CKM_RSA_X9_31_KEY_PAIR_GEN`：此機制的功能與 `CKM_RSA_PKCS_KEY_PAIR_GEN` 機制完全相同，但在產生 `p` 和 `q` 時提供更強大的保證。
+ `CKM_EC_KEY_PAIR_GEN`
+ `CKM_GENERIC_SECRET_KEY_GEN`
+ `CKM_AES_KEY_GEN`
+ `CKM_DES3_KEY_GEN`：註腳 [5](#mech5) 所列的即將進行的變更。
## 簽署和驗證函數
PKCS \$111 程式庫 AWS CloudHSM 的軟體程式庫可讓您針對 Sign and Verify 函數使用下列機制。使用用戶端 SDK 5，資料會在軟體中進行本機雜湊處理。這意味著 SDK 可以對任何大小的資料進行雜湊處理。
使用用戶端 SDK 5 RSA 和 ECDSA 時，雜湊在本機完成，因此沒有資料限制。使用 HMAC 時，會有資料限制。如需詳細咨詢，請參閱註腳 [2](#mech2)。
**RSA**
+ `CKM_RSA_X_509`
+ `CKM_RSA_PKCS`：僅限單一部分操作。
+ `CKM_RSA_PKCS_PSS`：僅限單一部分操作。
+ `CKM_SHA1_RSA_PKCS`
+ `CKM_SHA224_RSA_PKCS`
+ `CKM_SHA256_RSA_PKCS`
+ `CKM_SHA384_RSA_PKCS`
+ `CKM_SHA512_RSA_PKCS`
+ `CKM_SHA512_RSA_PKCS`
+ `CKM_SHA1_RSA_PKCS_PSS`
+ `CKM_SHA224_RSA_PKCS_PSS`
+ `CKM_SHA256_RSA_PKCS_PSS`
+ `CKM_SHA384_RSA_PKCS_PSS`
+ `CKM_SHA512_RSA_PKCS_PSS`
**ECDSA**
+ `CKM_ECDSA`：僅限單一部分操作。
+ `CKM_ECDSA_SHA1`
+ `CKM_ECDSA_SHA224`
+ `CKM_ECDSA_SHA256`
+ `CKM_ECDSA_SHA384`
+ `CKM_ECDSA_SHA512`
**HMAC**
+ `CKM_SHA_1_HMAC`[2](#mech2)
+ `CKM_SHA224_HMAC`[2](#mech2)
+ `CKM_SHA256_HMAC`[2](#mech2)
+ `CKM_SHA384_HMAC`[2](#mech2)
+ `CKM_SHA512_HMAC`[2](#mech2)
**CMAC**
+ `CKM_AES_CMAC`
## 簽名恢復和驗證復原函數
用戶端 SDK 5 不支援簽名恢復和驗證復原函數。
## Digest 函數
適用於 PKCS \$111 程式庫 AWS CloudHSM 的軟體程式庫可讓您針對摘要函數使用下列機制。使用用戶端 SDK 5，資料會在軟體中進行本機雜湊處理。這意味著 SDK 可以對任何大小的資料進行雜湊處理。
+ `CKM_SHA_1`
+ `CKM_SHA224`
+ `CKM_SHA256`
+ `CKM_SHA384`
+ `CKM_SHA512`
## 加密和解密函數
適用於 PKCS \$111 程式庫 AWS CloudHSM 的軟體程式庫可讓您針對加密和解密函數使用下列機制。
+ `CKM_RSA_X_509`
+ `CKM_RSA_PKCS`：僅限單一部分操作。註腳 [5](#mech5) 所列的即將進行的變更。
+ `CKM_RSA_PKCS_OAEP`：僅限單一部分操作。
+ `CKM_AES_ECB`
+ `CKM_AES_CTR`
+ `CKM_AES_CBC`
+ `CKM_AES_CBC_PAD`
+ `CKM_DES3_CBC`：註腳 [5](#mech5) 所列的即將進行的變更。
+ `CKM_DES3_ECB`：註腳 [5](#mech5) 所列的即將進行的變更。
+ `CKM_DES3_CBC_PAD`：註腳 [5](#mech5) 所列的即將進行的變更。
+ `CKM_AES_GCM` [1](#mech1), [2](#mech2)
+ `CKM_CLOUDHSM_AES_GCM`[3](#mech3)
## 衍生金鑰函數
PKCS \$111 程式庫 AWS CloudHSM 的軟體程式庫支援下列金鑰衍生機制：
+ `CKM_SP800_108_COUNTER_KDF`
+ `CKM_ECDH1_DERIVE` - 支援下列廠商定義 KDF 類型的 ECDH 金鑰衍生[6](#kdf6)：
+ `CKD_CLOUDHSM_X963_SHA1_KDF` - X9.63 KDF 搭配 SHA1[7](#kdf7)
+ `CKD_CLOUDHSM_X963_SHA224_KDF` - X9.63 KDF 搭配 SHA224[7](#kdf7)
+ `CKD_CLOUDHSM_X963_SHA256_KDF` - X9.63 KDF 搭配 SHA256[7](#kdf7)
+ `CKD_CLOUDHSM_X963_SHA384_KDF` - X9.63 KDF 搭配 SHA384[7](#kdf7)
+ `CKD_CLOUDHSM_X963_SHA512_KDF` - X9.63 KDF 搭配 SHA512[7](#kdf7)
## 包裝和解包函數
PKCS \$111 程式庫 AWS CloudHSM 的軟體程式庫可讓您針對包裝和取消包裝函數使用下列機制。
如需有關 AES 金鑰包裝的其他資訊，請參閱[AES 金鑰包裝](manage-aes-key-wrapping.md)。
+ `CKM_RSA_PKCS`：僅限單一部分操作。註腳 [5](#mech5) 所列的即將進行的變更。
+ `CKM_RSA_PKCS_OAEP`[4](#mech4)
+ `CKM_AES_GCM`[1](#mech1), [3](#mech3)
+ `CKM_CLOUDHSM_AES_GCM`[3](#mech3)
+ `CKM_RSA_AES_KEY_WRAP`
+ `CKM_CLOUDHSM_AES_KEY_WRAP_NO_PAD`[3](#mech3)
+ `CKM_CLOUDHSM_AES_KEY_WRAP_PKCS5_PAD`[3](#mech3)
+ `CKM_CLOUDHSM_AES_KEY_WRAP_ZERO_PAD`[3](#mech3)
## 每個機制的資料大小上限
下表列出每個機制設定的資料大小上限：
**資料集大小上限**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/pkcs11-mechanisms.html)
## 機制註釋
+ [1] 當執行 AES-GCM 加密時，HSM 不會接受來自應用程式的初始化向量 (IV) 資料。請務必使用其產生的 IV。系統會將 HSM 所提供的 12 位元組 IV 寫入記憶體參考，該記憶體參考是由您提供的 `CK_GCM_PARAMS` 參數結構 pIV 元素所指向。為了確保使用者不會混淆，在初始化 AES-GCM 加密時，1.1.1 版和更新版本中的 PKCS \$1 11 開發套件會強制將該 pIV 指向歸零的緩衝區。
+ [2] 當使用下列任一機制操作資料時，若資料緩衝區超過資料大小上限，該操作就會導致錯誤。對於這些機制，所有資料處理都必須在 HSM 內進行。如需每個機制的最大資料大小集資訊，請參閱 [每個機制的資料大小上限](#pkcs11-mech-max)。
+ [3] 廠商定義的機制。為了能使用 CloudHSM 廠商定義的機制，編譯期間 PKCS \$111 應用程式必須加入 `/opt/cloudhsm/include/pkcs11/pkcs11t.h`。
`CKM_CLOUDHSM_AES_GCM`：這個專屬機制是標準 `CKM_AES_GCM` 程式設計更安全的替代方案。這將 HSM 生成的 IV 加入至加密文字的開頭，而不是將它寫回加密初始化期間提供的 `CK_GCM_PARAMS` 結構中。您可以搭配 `C_Encrypt`、`C_WrapKey`、`C_Decrypt` 和 `C_UnwrapKey` 函數搭配使用此機制。使用此機制時，`CK_GCM_PARAMS` 結構中的 pIV 變數必須設定為 `NULL`。與 `C_Decrypt` 和 `C_UnwrapKey` 搭配使用此機制時，IV 應至於取消包裝的加密文字之前。
`CKM_CLOUDHSM_AES_KEY_WRAP_PKCS5_PAD`：AES 金鑰包裝與 PKCS \$15 填補。
`CKM_CLOUDHSM_AES_KEY_WRAP_ZERO_PAD`：AES 金鑰包裝，零填補。
+ [4] 支援下列 `CK_MECHANISM_TYPE` 和 `CK_RSA_PKCS_MGF_TYPE`，作為 `CKM_RSA_PKCS_OAEP` 的 `CK_RSA_PKCS_OAEP_PARAMS`：
+ `CKM_SHA_1` 使用 `CKG_MGF1_SHA1`
+ `CKM_SHA224` 使用 `CKG_MGF1_SHA224`
+ `CKM_SHA256` 使用 `CKG_MGF1_SHA256`
+ `CKM_SHA384` 使用 `CKM_MGF1_SHA384`
+ `CKM_SHA512` 使用 `CKM_MGF1_SHA512`
+ 【5】 根據 NIST 指引，在 2023 年之後，不允許在 FIPS 模式下使用叢集。對於處於非 FIPS 模式的叢集，在 2023 年之後仍然允許。如需詳細資訊，請參閱 [FIPS 140 合規性：2024 機制棄用](compliance-dep-notif.md#compliance-dep-notif-1)。
+ 【6】 供應商定義的類型。為了使用 CloudHSM 廠商定義的類型，PKCS\$111 應用程式必須在編譯`cloudhsm_pkcs11_vendor_defs.h`期間包含 。這可在`/opt/cloudhsm/include/pkcs11/cloudhsm_pkcs11_vendor_defs.h`適用於 Linux 型平台的 和`C:\Program Files\Amazon\CloudHSM\include\pkcs11\cloudhsm_pkcs11_vendor_defs.h`適用於 Windows 型平台的 中找到
+ 【7】 金鑰衍生函數 (KDFs) 是在 [NIST 特殊出版物 800-56A 修訂版 3](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-56Ar3.pdf) 中指定。
# AWS CloudHSM 用戶端 SDK 5 的 PKCS \$111 程式庫支援的 API 操作
PKCS \$111 程式庫支援 AWS CloudHSM 用戶端 SDK 5 的下列 PKCS \$111 API 操作。
+ `C_CloseAllSessions`
+ `C_CloseSession`
+ `C_CreateObject`
+ `C_Decrypt`
+ `C_DecryptFinal`
+ `C_DecryptInit`
+ `C_DecryptUpdate`
+ `C_DeriveKey`
+ `C_DestroyObject`
+ `C_Digest`
+ `C_DigestFinal`
+ `C_DigestInit`
+ `C_DigestUpdate`
+ `C_Encrypt`
+ `C_EncryptFinal`
+ `C_EncryptInit`
+ `C_EncryptUpdate`
+ `C_Finalize`
+ `C_FindObjects`
+ `C_FindObjectsFinal`
+ `C_FindObjectsInit`
+ `C_GenerateKey`
+ `C_GenerateKeyPair`
+ `C_GenerateRandom`
+ `C_GetAttributeValue`
+ `C_GetFunctionList`
+ `C_GetInfo`
+ `C_GetMechanismInfo`
+ `C_GetMechanismList`
+ `C_GetSessionInfo`
+ `C_GetSlotInfo`
+ `C_GetSlotList`
+ `C_GetTokenInfo`
+ `C_Initialize`
+ `C_Login`
+ `C_Logout`
+ `C_OpenSession`
+ `C_Sign`
+ `C_SignFinal`
+ `C_SignInit`
+ `C_SignUpdate`
+ `C_UnWrapKey`
+ `C_Verify`
+ `C_VerifyFinal`
+ `C_VerifyInit`
+ `C_VerifyUpdate`
+ `C_WrapKey`
# AWS CloudHSM 用戶端 SDK 5 的 PKCS \$111 程式庫中的金鑰屬性
AWS CloudHSM 金鑰物件可以是公有、私有或私密金鑰。系統會透過屬性來指定金鑰物件上允許的動作。金鑰物件建立時，即會一併建立屬性。當您使用 PKCS \$111 程式庫時 AWS CloudHSM，我們會依 PKCS \$111 標準指定預設值。
AWS CloudHSM 不支援 PKCS \$111 規格中列出的所有屬性。我們會符合所有支援屬性的規格，並在個別表格中列出這些屬性。
用來建立、修改或複製物件的加密函數 (如 `C_CreateObject`、`C_GenerateKey`、`C_GenerateKeyPair`、`C_UnwrapKey` 和 `C_DeriveKey`) 會採用屬性範本做為其中一個參數。如需關於在建立物件期間傳遞屬性範本的詳細資訊，請參閱[透過 PKCS \$111 程式庫產生金鑰](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/tree/master/src/generate) (以此為例)。
下列主題提供有關 AWS CloudHSM 金鑰屬性的詳細資訊。
**Topics**
+ [屬性資料表](pkcs11-attributes-interpreting.md)
+ [修改屬性](modify-attr.md)
+ [解譯錯誤代碼](attr-errors.md)
# AWS CloudHSM 用戶端 SDK 5 的 PKCS \$111 程式庫屬性資料表
的 PKCS \$111 程式庫資料表 AWS CloudHSM 包含因金鑰類型而異的屬性清單。它會指出使用特定密碼編譯函數時，特定金鑰類型是否支援指定的屬性 AWS CloudHSM。
**圖例：**
+ ✔ 表示 CloudHSM 支援特定金鑰類型的屬性。
+ ✖ 表示 CloudHSM 不支援特定金鑰類型的屬性。
+ R 表示特定金鑰類型的屬性值設定為唯讀模式。
+ S 表示屬性較為敏感，因此無法透過 `GetAttributeValue` 讀取。
+ 預設值欄位中的空白儲存格表示屬性沒有獲派指定預設值。
## GenerateKeyPair
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/pkcs11-attributes-interpreting.html)
## GenerateKey
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/pkcs11-attributes-interpreting.html)
## CreateObject
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/pkcs11-attributes-interpreting.html)
## UnwrapKey
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/pkcs11-attributes-interpreting.html)
## DeriveKey
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/pkcs11-attributes-interpreting.html)
## GetAttributeValue
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/pkcs11-attributes-interpreting.html)
**屬性註釋**
+ [1] 此屬性受韌體部分支援，且需明確設定為僅限預設值。
+ [2] 必要屬性。
# 修改 AWS CloudHSM 用戶端 SDK 5 的 PKCS \$111 程式庫屬性
物件的某些 PKCS \$111 程式庫屬性 AWS CloudHSM 可以在建立物件後修改，而有些則無法修改。若要修改屬性，請使用 CloudHSM CLI 中的[金鑰 set-attribute](cloudhsm_cli-key-set-attribute.md) 命令。您也可以使用 CloudHSM CLI 的[金鑰清單](cloudhsm_cli-key-list.md)命令來衍生屬性清單。
下列清單會顯示物件建立後可修改的屬性：
+ `CKA_LABEL`
+ `CKA_TOKEN`
**注意**
只有在將工作階段金鑰變更為符記金鑰時，才允許進行修改。使用 CloudHSM CLI 的[金鑰 set-attribute](cloudhsm_cli-key-set-attribute.md) 命令來變更屬性值。
+ `CKA_ENCRYPT`
+ `CKA_DECRYPT`
+ `CKA_SIGN`
+ `CKA_VERIFY`
+ `CKA_WRAP`
+ `CKA_UNWRAP`
+ `CKA_LABEL`
+ `CKA_SENSITIVE`
+ `CKA_DERIVE`
**注意**
這個屬性支援金鑰衍生。所有公有金鑰的屬性須為 `False`，不能設定為 `True`。如果是私密金鑰和 EC 私有金鑰，則該屬性可設定為 `True` 或 `False`。
+ `CKA_TRUSTED`
**注意**
唯有加密管理員 (CO) 可將這個屬性設定成 `True` 或 `False`。
+ `CKA_WRAP_WITH_TRUSTED`
**注意**
將此屬性套用於可匯出的資料金鑰，以表明只能使用標記為 `CKA_TRUSTED` 的金鑰包裝此金鑰。一旦設定 `CKA_WRAP_WITH_TRUSTED` 為 true，屬性就會變成唯讀，而且您無法變更或移除屬性。
# 解譯 AWS CloudHSM 用戶端 SDK 5 的 PKCS \$111 程式庫錯誤代碼
在範本中指定特定金鑰不支援的 PKCS \$111 程式庫屬性會導致錯誤。下表包含違反規格時所產生的錯誤代碼：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/attr-errors.html)
# AWS CloudHSM 用戶端 SDK 5 的 PKCS \$111 程式庫程式碼範例
GitHub 上的程式碼範例示範如何使用 AWS CloudHSM 用戶端 SDK 5 的 PKCS \$111 程式庫來完成基本任務。
## 先決條件
執行範例之前，請執行以下步驟來設定您的環境：
+ 安裝並設定適用於用戶端 SDK 5 的 [PKCS \$111 程式庫](pkcs11-library-install.md)。
+ 設定[密碼編譯使用者 (CU)](manage-hsm-users.md)。您的應用程式會使用此 HSM 帳戶在 HSM 上執行程式碼範例。
## 程式碼範例
適用於 PKCS\$111 AWS CloudHSM 的軟體程式庫程式碼範例可在 [GitHub](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples) 上取得。此儲存庫包括如何使用 PKCS \$111 執行一般作業的範例，包括加密、解密、簽署和驗證。
+ [產生金鑰 (AES、RSA、EC)](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/tree/master/src/generate)
+ [列出金鑰屬性](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/src/attributes/)
+ [使用 AES GCM 加密和解密資料](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/src/encrypt/aes_gcm.c)
+ [使用 AES\$1CTR 加密和解密資料](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/tree/master/src/encrypt/aes_ctr.c)
+ [使用 3DES 加密和解密資料](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/tree/master/src/encrypt/des_ecb.c)
+ [使用 RSA 簽署和驗證資料](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/src/sign/rsa_sign.c)
+ [使用 HMAC KDF 衍生金鑰](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/src/derivation/hmac_kdf.c)
+ [使用以 PKCS \$15 填補的 AES 包裝和取消包裝金鑰](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/src/wrapping/aes_wrapping.c)
+ [使用不填補的 AES 包裝和取消包裝金鑰](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/src/wrapping/aes_no_padding_wrapping.c)
+ [使用零填補的 AES 包裝和取消包裝金鑰](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/src/wrapping/aes_zero_padding_wrapping.c)
+ [使用 AES-GCM 包裝和取消包裝金鑰](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/tree/master/src/wrapping/aes_gcm_wrapping.c)
+ [使用 RSA 包裝和取消包裝金鑰](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/src/wrapping/rsa_wrapping.c)
# 的 PKCS \$111 程式庫進階組態 AWS CloudHSM
AWS CloudHSM PKCS \$111 供應商包含下列進階組態，這不屬於大多數客戶使用的一般組態。這些組態提供額外的功能。
+ [使用 PKCS \$111 連線到多個插槽](pkcs11-library-configs-multi-slot.md)
+ [PKCS \$111 的重試組態](pkcs11-library-configs-retry.md)
# 適用於 的 PKCS \$111 程式庫的多個槽組態 AWS CloudHSM
用戶端 SDK 5 PKCS \$111 程式庫中的單一插槽代表 AWS CloudHSM中叢集的單一連線。使用用戶端 SDK 5，您可以將 PKCS11 程式庫設定為允許多個插槽，從單一 PKCS \$111 應用程式將使用者連線到多個 CloudHSM 叢集。
使用本主題中的說明，讓您的應用程式使用多插槽功能來連線到多個叢集。
**Topics**
+ [適用於 的 PKCS \$111 程式庫的多槽先決條件 AWS CloudHSM](#pkcs11-multi-slot-prereqs)
+ [針對 的多槽功能設定 PKCS \$111 程式庫 AWS CloudHSM](pkcs11-multi-slot-config-run.md)
+ [為 新增具有多插槽功能的叢集 AWS CloudHSM](pkcs11-multi-slot-add-cluster.md)
+ [移除具有 多插槽功能的叢集 AWS CloudHSM](pkcs11-multi-slot-remove-cluster.md)
## 適用於 的 PKCS \$111 程式庫的多槽先決條件 AWS CloudHSM
為 PKCS \$111 程式庫設定多個插槽之前 AWS CloudHSM，請完成下列先決條件。
+ 您要連線的兩個或多個 AWS CloudHSM 叢集及其叢集憑證。
+ 具有安全群組的 EC2 執行個體正確設定為連線到上述所有叢集。如需如何設定叢集和用戶端執行個體的詳細資訊，請參閱 [入門 AWS CloudHSM](getting-started.md)。
+ 若要設定多插槽功能，您必須已下載並安裝 PKCS \$111 程式庫。若您尚未完成此動作，請參閱 [安裝 AWS CloudHSM 用戶端 SDK 5 的 PKCS \$111 程式庫](pkcs11-library-install.md) 中的說明。
# 針對 的多槽功能設定 PKCS \$111 程式庫 AWS CloudHSM
若要設定 PKCS \$111 程式庫的多槽功能 AWS CloudHSM，請遵循下列步驟：
1. 使用多插槽功能識別要連線到的叢集。
1. 依照 [為 新增具有多插槽功能的叢集 AWS CloudHSM](pkcs11-multi-slot-add-cluster.md) 中的說明，將這些叢集新增至 PKCS \$111 組態
1. PKCS \$111 應用程式下次執行時，其將具有多插槽功能。
# 為 新增具有多插槽功能的叢集 AWS CloudHSM
[使用 PKCS \$111 連線到多個插槽](pkcs11-library-configs-multi-slot.md)時 AWS CloudHSM，請使用 **configure-pkcs11 add-cluster**命令將叢集新增至您的組態。
## 語法
```
configure-pkcs11 add-cluster [OPTIONS]
--cluster-id
[--region ]
[--endpoint ]
[--hsm-ca-cert ]
[--client-cert-hsm-tls-file ]
[--client-key-hsm-tls-file ]
[-h, --help]
```
## 範例
### 使用 `cluster-id` 參數新增叢集
**Example**
搭配使用 **configure-pkcs11 add-cluster** 和 `cluster-id` 參數，將叢集 (ID為 `cluster-1234567`) 新增至您的組態。
```
$ sudo /opt/cloudhsm/bin/configure-pkcs11 add-cluster --cluster-id
```
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-pkcs11.exe" add-cluster --cluster-id
```
**提示**
如果 **configure-pkcs11 add-cluster** 與 `cluster-id` 參數搭配使用不會導致新增叢集，請參閱下列範例，以取得此命令的更長版本，此命令也需要 `--region` 和 `--endpoint` 參數來識別要新增的叢集。例如，如果叢集區域與設定為 AWS CLI 預設值的區域不同，則應使用 `--region` 參數來使用正確的區域。此外，您可以指定用於呼叫的 AWS CloudHSM API 端點，這對於各種網路設定而言可能是必要的，例如使用不使用預設 DNS 主機名稱的 VPC 介面端點 AWS CloudHSM。
### 使用 `cluster-id`、`endpoint` 和 `region` 參數新增叢集
**Example**
搭配使用 **configure-pkcs11 add-cluster** 以及 `cluster-id`、`endpoint` 和 `region` 參數將叢集 (ID為 `cluster-1234567`) 新增至您的組態。
```
$ sudo /opt/cloudhsm/bin/configure-pkcs11 add-cluster --cluster-id --region --endpoint
```
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-pkcs11.exe" add-cluster --cluster-id --region --endpoint
```
如需 `--cluster-id`、`--region` 和 `--endpoint` 參數的詳細資訊，請參閱 [AWS CloudHSM 用戶端 SDK 5 組態參數](configure-tool-params5.md)。
## Parameters
**--cluster-id ****
進行 `DescribeClusters` 呼叫以尋找叢集中與叢集 ID 關聯的所有 HSM 彈性網路介面 (ENI) IP 地址。系統會將 ENI IP 地址新增至 AWS CloudHSM 組態檔案。
如果您在無法存取公有網際網路的 VPC 中使用來自 EC2 執行個體的 `--cluster-id` 參數，則必須建立要連線的介面 VPC 端點 AWS CloudHSM。如需 VPC 端點的詳細資訊，請參閱 [AWS CloudHSM 和 VPC 端點](cloudhsm-vpc-endpoint.md)。
必要：是
**--endpoint ****
指定用於進行`DescribeClusters`呼叫的 AWS CloudHSM API 端點。您必須結合 `--cluster-id` 設定此選項。
必要：否
**--hsm-ca-cert ****
指定 HSM CA 憑證的檔案路徑。
必要：否
**--region ****
指您叢集的區域。您必須結合 `--cluster-id` 設定此選項。
如果您未提供 `--region` 參數，系統會嘗試讀取 `AWS_DEFAULT_REGION` 或 `AWS_REGION` 環境變數來選擇區域。如果未設定這些變數，則除非您在 `AWS_CONFIG_FILE` 環境變數中指定了不同的檔案，否則系統會檢查 AWS config 檔案中 (通常是 `~/.aws/config`) 與您的設定檔相關聯的區域。如果未設定上述任何變數，系統會預設為 `us-east-1` 區域。
必要：否
**--client-cert-hsm-tls-file ****
用於 TLS 用戶端-HSM 交互身分驗證的用戶端憑證路徑。
只有在您已使用 CloudHSM CLI 在 HSM 上註冊至少一個信任錨點時，才使用此選項。您必須結合 `--client-key-hsm-tls-file` 設定此選項。
必要：否
**--client-key-hsm-tls-file ****
用於 TLS 用戶端-HSM 交互身分驗證的用戶端金鑰路徑。
只有在您已使用 CloudHSM CLI 在 HSM 上註冊至少一個信任錨點時，才使用此選項。您必須結合 `--client-cert-hsm-tls-file` 設定此選項。
必要：否
# 移除具有 多插槽功能的叢集 AWS CloudHSM
[使用 PKCS \$111 連線到多個插槽](pkcs11-library-configs-multi-slot.md)時，請使用 **configure-pkcs11 remove-cluster** 命令從可用的 PKCS \$111 插槽中移除叢集。
## 語法
```
configure-pkcs11 remove-cluster [OPTIONS]
--cluster-id
[-h, --help]
```
## 範例
### 使用 `cluster-id` 參數移除叢集
**Example**
搭配使用 **configure-pkcs11 remove-cluster** 和 `cluster-id` 參數，從您的組態中移除叢集 (ID 為 `cluster-1234567`)。
```
$ sudo /opt/cloudhsm/bin/configure-pkcs11 remove-cluster --cluster-id
```
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-pkcs11.exe" remove-cluster --cluster-id
```
如需 `--cluster-id` 參數的詳細資訊，請參閱 [AWS CloudHSM 用戶端 SDK 5 組態參數](configure-tool-params5.md)。
## 參數
**--cluster-id ****
需從組態中移除的叢集的 ID
必要：是
# 的 PKCS \$111 程式庫重試命令 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-pkcs11 --default-retry-mode off
```
------
#### [ Windows ]
**將 Windows 上用戶端 SDK 5 重試命令設定為 **off****
+ 您可以使用下列命令將重試組態設定為 **off** 模式：
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-pkcs11.exe" --default-retry-mode off
```
------
# 具有 PKCS \$111 程式庫的憑證儲存
AWS CloudHSM PKCS \$111 程式庫支援將公有金鑰憑證儲存為 hsm2m.medium 叢集上的「公有物件」（如 PKCS \$111 2.40 中所定義）。此功能允許公有和私有 PKCS \$111 工作階段建立、擷取、修改和刪除公有金鑰憑證。
若要搭配 PKCS \$111 程式庫使用憑證儲存，您需要在用戶端組態中啟用它。啟用後，您可以從 PKCS \$111 應用程式管理憑證物件。同時套用到憑證和金鑰物件的操作，例如 [C\$1FindObjects](http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/os/pkcs11-base-v2.40-os.html#_Toc323205461)，將會傳回金鑰和憑證儲存的結果。
**Topics**
+ [啟用憑證儲存](pkcs11-certificate-storage-configuration.md)
+ [憑證儲存 API](pkcs11-certificate-storage-api.md)
+ [憑證屬性](pkcs11-certificate-storage-attributes.md)
+ [憑證儲存體稽核日誌](pkcs11-certificate-storage-audit-logs.md)
# 啟用憑證儲存
您可以使用 PKCS \$111 程式庫組態工具，在 hsm2m.medium 叢集上啟用憑證儲存。此功能適用於 SDK 5.13 版和更新版本。如需支援憑證物件類型的操作清單，請參閱[憑證儲存 API 操作](pkcs11-certificate-storage-api.md)。
若要啟用憑證儲存，請依照下列步驟操作您的作業系統：
------
#### [ Linux ]
+
****啟用憑證儲存****
執行以下命令：
```
$ sudo /opt/cloudhsm/bin/configure-pkcs11 --enable-certificate-storage
```
------
#### [ Windows ]
+
****啟用憑證儲存****
開啟命令提示字元並執行下列命令：
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-pkcs11.exe" --enable-certificate-storage
```
------
# 憑證儲存 API 操作
下列 PKCS \$111 操作支援憑證物件類型 (`CKO_CERTIFICATE`)：
## 一般憑證操作
**`C_CreateObject`**
建立新的憑證物件。
**`C_DestroyObject`**
刪除現有的憑證物件。
**`C_GetAttributeValue`**
取得憑證物件的一或多個屬性的值。
**`C_SetAttributeValue`**
更新憑證物件的一或多個屬性的值。
## 憑證物件搜尋操作
**`C_FindObjectsInit`**
開始搜尋憑證物件。
**`C_FindObjects`**
繼續搜尋憑證物件。
**`C_FindObjectsFinal`**
結束憑證物件的搜尋。
# 憑證儲存屬性
下表列出支援的憑證物件屬性及其值：
| 屬性 | 預設值 | Description |
| --- | --- | --- |
| `CKA_CLASS` | 必要 | 必須為 `CKO_CERTIFICATE`。 |
| `CKA_TOKEN` | True | 必須為 `True`。 |
| `CKA_MODIFIABLE` | True | 必須為 `True`。 |
| `CKA_PRIVATE` | False | 必須為 `False`。 |
| `CKA_LABEL` | 空白 | 限制 127 個字元。 |
| `CKA_COPYABLE` | False | 必須為 `False`。 |
| `CKA_DESTROYABLE` | True | 必須為 `True`。 |
| `CKA_CERTIFICATE_TYPE` | 必要 | 必須為 `CKC_X_509`。 |
| `CKA_TRUSTED` | False | 必須為 `False`。 |
| `CKA_CERTIFICATE_CATEGORY` | `CK_CERTIFICATE_CATEGORY_UNSPECIFIED` | 必須為 `CK_CERTIFICATE_CATEGORY_UNSPECIFIED`。 |
| `CKA_CHECK_VALUE` | 衍生自 `CKA_VALUE` | 根據 自動設定`CKA_VALUE`。 |
| `CKA_START_DATE` | 空白 | 憑證 'not before' date。 |
| `CKA_END_DATE` | 空白 | 憑證 'not after' date。 |
| `CKA_PUBLIC_KEY_INFO` | 空白 | 大小上限為 16 KB。 |
| `CKA_SUBJECT` | 必要 | 憑證主體。 |
| `CKA_ID` | 空白 | 大小上限為 128 個位元組。不強制執行唯一性。 |
| `CKA_ISSUER` | 空白 | 憑證發行者。 |
| `CKA_SERIAL_NUMBER` | 空白 | 憑證序號。 |
| `CKA_VALUE` | 必要 | 大小上限為 32 KB。 |
# 憑證儲存體稽核日誌
AWS CloudHSM 會寫入憑證儲存操作的稽核日誌，以將資料修改為叢集 Amazon CloudWatch CloudWatch Events 日誌串流。此日誌串流會針對叢集命名，而不是針對叢集內的特定 HSM。
如需有關在 CloudWatch 中存取稽核日誌的資訊，請參閱 [使用 Amazon CloudWatch Logs 和 AWS CloudHSM 稽核日誌](get-hsm-audit-logs-using-cloudwatch.md)。
## 日誌項目欄位
`object_handle`
憑證物件的唯一識別符。
`op_code`
執行或嘗試的操作。可能的值如下：
+ `CreateObject`
+ `DestroyObject`
+ `SetAttributeValues`
`response`
`OK` 如果操作成功，或下列其中一個錯誤類型：
+ `DuplicateAttribute`
+ `InvalidAttributeValue`
+ `ObjectNotFound`
+ `MaxObjectsReached`
+ `InternalFailure`
`attributes`
已修改屬性，如果有的話。
`timestamp`
操作發生的時間，以 Unix epoch 後的毫秒為單位。
## 稽核日誌範例
### CreateObject 範例
```
{
"object_handle": 463180677312929947,
"op_code": "CreateObject",
"response": "OK",
"attributes": null,
"timestamp": 1725482483671
}
```
### DestroyObject 範例
```
{
"object_handle": 463180677312929947,
"op_code": "DestroyObject",
"response": "OK",
"attributes": null,
"timestamp": 1725482484559
}
```
### SetAttributeValues 範例
```
{
"object_handle": 463180678453346687,
"op_code": "SetAttributeValues",
"response": "OK",
"attributes": [
"Label"
],
"timestamp": 1725482488004
}
```
### 不成功的 CreateObject 範例
```
{
"object_handle": null,
"op_code": "CreateObject",
"response": "MaxObjectsReached",
"attributes": null,
"timestamp": 1726084937125
}
```
# 適用於 AWS CloudHSM 用戶端 SDK 5 的 OpenSSL 動態引擎
AWS CloudHSM OpenSSL 動態引擎可讓您透過 OpenSSL API 將密碼編譯操作卸載至 CloudHSM 叢集。
AWS CloudHSM 提供 OpenSSL 動態引擎，您可以在 [AWS CloudHSM 在 Linux 上使用 Tomcat 搭配 JSSE 的 SSL/TLS 卸載](third-offload-linux-jsse.md)或 中閱讀相關文章[AWS CloudHSM 使用 NGINX 或 Apache 搭配 OpenSSL 在 Linux 上卸載 SSL/TLS](third-offload-linux-openssl.md)。如需 AWS CloudHSM 搭配 OpenSSL 使用 的範例，請參閱[此 AWS 安全部落格](https://aws.amazon.com/blogs/security/automate-the-deployment-of-an-nginx-web-service-using-amazon-ecs-with-tls-offload-in-cloudhsm/)。如需關於 SDK 平台支援的詳細資訊，請參閱 [AWS CloudHSM 用戶端 SDK 5 支援的平台](client-supported-platforms.md)。如需故障診斷，請參閱 [的 OpenSSL 動態引擎已知問題 AWS CloudHSM](ki-openssl-sdk.md)。
使用下列各節，使用用戶端 SDK 5 安裝和設定 OpenSSL 的 AWS CloudHSM 動態引擎。
如需關於使用用戶端 SDK 3 的資訊，請參閱 [使用先前的 SDK 版本來使用 AWS CloudHSM](choose-client-sdk.md)。
**Topics**
+ [安裝適用於 AWS CloudHSM 用戶端 SDK 5 的 OpenSSL 動態引擎](openssl5-install.md)
+ [AWS CloudHSM 用戶端 SDK 5 的 OpenSSL 動態引擎支援的金鑰類型](openssl-key-types.md)
+ [AWS CloudHSM 用戶端 SDK 5 的 OpenSSL 動態引擎支援機制](openssl-mechanisms.md)
+ [適用於 的 OpenSSL 進階組態 AWS CloudHSM](openssl-library-configs.md)
# 安裝適用於 AWS CloudHSM 用戶端 SDK 5 的 OpenSSL 動態引擎
使用以下章節安裝適用於 AWS CloudHSM 用戶端 SDK 5 的 OpenSSL 動態引擎。
**注意**
若要使用用戶端 SDK 5 執行單一 HSM 叢集，您必須先將 `disable_key_availability_check` 設定為 `True` 來管理用戶端金鑰持久性。如需詳細資訊，請參閱[金鑰同步處理](manage-key-sync.md)和[用戶端 SDK 5 設定工具](configure-sdk-5.md)。
**安裝和設定 OpenSSL 動態引擎**
1. 使用以下命令來下載和安裝 OpenSSL 引擎。
------
#### [ Amazon Linux 2023 ]
在 x86\$164 架構上安裝適用於 Amazon Linux 2023 的 OpenSSL 動態引擎：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Amzn2023/cloudhsm-dyn-latest.amzn2023.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-dyn-latest.amzn2023.x86_64.rpm
```
在 ARM64 架構上安裝適用於 Amazon Linux 2023 的 OpenSSL 動態引擎：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Amzn2023/cloudhsm-dyn-latest.amzn2023.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-dyn-latest.amzn2023.aarch64.rpm
```
------
#### [ Amazon Linux 2 ]
在 x86\$164 架構上安裝適用於 Amazon Linux 2 的 OpenSSL 動態引擎：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-dyn-latest.el7.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-dyn-latest.el7.x86_64.rpm
```
在 ARM64 架構上安裝適用於 Amazon Linux 2 的 OpenSSL 動態引擎：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-dyn-latest.el7.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-dyn-latest.el7.aarch64.rpm
```
------
#### [ RHEL 9 (9.2\$1) ]
在 x86\$164 架構上安裝適用於 RHEL 9 的 OpenSSL 動態引擎：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL9/cloudhsm-dyn-latest.el9.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-dyn-latest.el9.x86_64.rpm
```
在 ARM64 架構上安裝適用於 RHEL 9 的 OpenSSL 動態引擎：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL9/cloudhsm-dyn-latest.el9.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-dyn-latest.el9.aarch64.rpm
```
------
#### [ RHEL 8 (8.3\$1) ]
在 x86\$164 架構上安裝適用於 RHEL 8 的 OpenSSL 動態引擎：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-dyn-latest.el8.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-dyn-latest.el8.x86_64.rpm
```
在 ARM64 架構上安裝適用於 RHEL 8 的 OpenSSL 動態引擎：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-dyn-latest.el8.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-dyn-latest.el8.aarch64.rpm
```
------
#### [ Ubuntu 24.04 LTS ]
在 x86\$164 架構上安裝適用於 Ubuntu 24.04 LTS 的 OpenSSL 動態引擎：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Noble/cloudhsm-dyn_latest_u24.04_amd64.deb
```
```
$ sudo apt install ./cloudhsm-dyn_latest_u24.04_amd64.deb
```
在 ARM64 架構上安裝適用於 Ubuntu 24.04 LTS 的 OpenSSL 動態引擎：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Noble/cloudhsm-dyn_latest_u24.04_arm64.deb
```
```
$ sudo apt install ./cloudhsm-dyn_latest_u24.04_arm64.deb
```
------
#### [ Ubuntu 22.04 LTS ]
在 x86\$164 架構上安裝適用於 Ubuntu 22.04 LTS 的 OpenSSL 動態引擎：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Jammy/cloudhsm-dyn_latest_u22.04_amd64.deb
```
```
$ sudo apt install ./cloudhsm-dyn_latest_u22.04_amd64.deb
```
在 ARM64 架構上安裝適用於 Ubuntu 22.04 LTS 的 OpenSSL 動態引擎：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Jammy/cloudhsm-dyn_latest_u22.04_arm64.deb
```
```
$ sudo apt install ./cloudhsm-dyn_latest_u22.04_arm64.deb
```
------
您已在 `/opt/cloudhsm/lib/libcloudhsm_openssl_engine.so` 中安裝動態引擎的共用程式庫。
1. 引導用戶端 SDK 5。如需關於啟動程序的詳細資訊，請參閱 [引導用戶端 SDK](cluster-connect.md#connect-how-to)。
1. 使用加密使用者 (CU) 的憑證設定環境變數。如需關於建立 CU 的資訊，請參閱 [使用 CloudHSM CLI 建立 AWS CloudHSM 使用者](cloudhsm_cli-user-create.md)。
```
$ export CLOUDHSM_PIN=:
```
**注意**
用戶端 SDK 5 引入了用於存儲 CU 憑證的 `CLOUDHSM_PIN` 環境變量。在用戶端 SDK 3 中，您可以將 CU 憑證儲存在 `n3fips_password` 環境變數中。用戶端 SDK 5 支援這兩個環境變數，但建議使用 `CLOUDHSM_PIN`。
設定`CLOUDHSM_PIN`環境變數時，您必須逸出 Shell 可能解譯的任何特殊字元。
1. 將您的 OpenSSL 動態引擎連接到叢集。如需詳細資訊，請參閱[連接至叢集](cluster-connect.md)。
1. 引導用戶端 SDK 5。如需詳細資訊，請參閱[引導用戶端 SDK](cluster-connect.md#connect-how-to)。
## 驗證用戶端 SDK 5 OpenSSL 的動態引擎
使用下面的命令來驗證您的 OpenSSL 動態引擎的安裝。
```
$ openssl engine -t cloudhsm
```
下列輸出會驗證組態：
```
(cloudhsm) CloudHSM OpenSSL Engine
[ available ]
```
# AWS CloudHSM 用戶端 SDK 5 的 OpenSSL 動態引擎支援的金鑰類型
AWS CloudHSM OpenSSL 動態引擎支援用戶端 SDK 5 的下列金鑰類型。
****
| 金鑰類型 | Description |
| --- | --- |
| EC | 對 P-256、P-384 和 secp256k1 金鑰類型進行 ECDSA 簽署/驗證。若要產生可與 OpenSSL 引擎互通的 EC 金鑰，請參閱 [使用 CloudHSM CLI 匯出非對稱金鑰](cloudhsm_cli-key-generate-file.md)。 |
| RSA | 2048、3072 和 4096 位元金鑰的 RSA 金鑰產生。RSA 簽署/驗證。驗證程序已卸載到 OpenSSL 軟件中。 |
# AWS CloudHSM 用戶端 SDK 5 的 OpenSSL 動態引擎支援機制
AWS CloudHSM OpenSSL 動態引擎支援使用用戶端 SDK 5 簽署和驗證函數的下列機制。
## 簽署和驗證函數
使用用戶端 SDK 5，資料會在軟體中進行本機雜湊處理。這表示可以雜湊的資料大小沒有限制。
RSA 簽章類型
+ SHA1withRSA
+ SHA224withRSA
+ SHA256withRSA
+ SHA384withRSA
+ SHA512withRSA
ECDSA 簽章類型
+ SHA1withECDSA
+ SHA224withECDSA
+ SHA256withECDSA
+ SHA384withECDSA
+ SHA512withECDSA
# 適用於 的 OpenSSL 進階組態 AWS CloudHSM
AWS CloudHSM OpenSSL 提供者包含下列進階組態，這不屬於大多數客戶使用的一般組態。這些組態提供額外的功能。
+ [適用於 OpenSSL 的重試命令](openssl-library-configs-retry.md)
# 的 OpenSSL 重試命令 AWS CloudHSM
AWS CloudHSM 用戶端 SDK 5.8.0 和更新版本具有內建的自動重試策略，將從用戶端重試 HSM 限流操作。當 HSM 因過於忙於執行先前操作而無法接受更多要求而限制操作時，用戶端 SDK 會嘗試重試限流操作 (最多 3 次)，同時以指数形式回退。此自動重試策略可以設定為兩種模式中的其中一種：**關閉**模式和**標準**模式。
+ **關閉**：用戶端 SDK 將不會針對 HSM 的任何限流操作執行任何重試政策。
+ **標準**：這是用戶端 SDK 5.8.0 及更新版本的預設模式。在此模式下，用戶端 SDK 會以指數回退形式自動重試限流操作。
如需詳細資訊，請參閱[HSM 調節](troubleshoot-hsm-throttling.md)。
## 將重試命令設定為關閉模式
您可以使用下列命令將重試命令設定為 **off** 模式：
```
$ sudo /opt/cloudhsm/bin/configure-dyn --default-retry-mode off
```
# AWS CloudHSM 用戶端 SDK 5 的 OpenSSL 提供者
AWS CloudHSM OpenSSL 提供者可讓您透過 OpenSSL 提供者 API 將 TLS 密碼編譯操作卸載至 CloudHSM 叢集。對於使用 OpenSSL 3.2 和更新版本的新部署，建議使用提供者界面。
使用下列各節，使用用戶端 SDK 5 安裝和設定 AWS CloudHSM OpenSSL 提供者。
**警告**
OpenSSL 提供者目前不支援與 AWS CloudHSM OpenSSL CLI 整合。如需支援的整合[AWS CloudHSM Linux 上使用 NGINX 或 HAProxy 搭配 OpenSSL 提供者的 SSL/TLS 卸載](third-offload-linux-openssl-provider.md)，請參閱 。
## 支援平台
OpenSSL 提供者需要 OpenSSL 3.2 或更新版本，可在 EL9\$1、Ubuntu 24.04\$1 和 Amazon Linux 2023\$1 上使用。
驗證相容性： `openssl version`
**Topics**
+ [支援平台](#openssl-provider-supported-platforms)
+ [安裝適用於 AWS CloudHSM 用戶端 SDK 5 的 OpenSSL 提供者](openssl-provider-install.md)
+ [OpenSSL Provider for AWS CloudHSM Client SDK 5 支援的金鑰類型](openssl-provider-key-types.md)
+ [OpenSSL 提供者支援的機制](openssl-provider-mechanisms.md)
+ [OpenSSL 提供者進階組態](openssl-provider-advanced-config.md)
# 安裝適用於 AWS CloudHSM 用戶端 SDK 5 的 OpenSSL 提供者
使用以下章節安裝適用於 AWS CloudHSM 用戶端 SDK 5 的 OpenSSL 提供者。
**注意**
若要使用用戶端 SDK 5 執行單一 HSM 叢集，您必須先將 `disable_key_availability_check` 設定為 `True` 來管理用戶端金鑰持久性。如需詳細資訊，請參閱[金鑰同步處理](working-client-sync.md#client-sync-sdk8)和[用戶端 SDK 5 設定工具](configure-sdk-5.md)。
## 要求
OpenSSL 提供者需要 **hsm2m.medium** 叢集類型和最低 CloudHSM 用戶端 SDK 5.17.0 版或更新版本。
## 安裝 OpenSSL 提供者
**安裝 OpenSSL 提供者**
1. 使用下列命令下載並安裝 OpenSSL 提供者。
------
#### [ Amazon Linux 2023 ]
在 x86\$164 架構上安裝 Amazon Linux 2023 的 OpenSSL 提供者：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Amzn2023/cloudhsm-openssl-provider-latest.amzn2023.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-openssl-provider-latest.amzn2023.x86_64.rpm
```
在 ARM64 架構上安裝 Amazon Linux 2023 的 OpenSSL 提供者：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Amzn2023/cloudhsm-openssl-provider-latest.amzn2023.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-openssl-provider-latest.amzn2023.aarch64.rpm
```
------
#### [ RHEL 9 (9.2\$1) ]
在 x86\$164 架構上安裝 RHEL 9 的 OpenSSL 提供者：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL9/cloudhsm-openssl-provider-latest.el9.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-openssl-provider-latest.el9.x86_64.rpm
```
在 ARM64 架構上安裝 RHEL 9 的 OpenSSL 提供者：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL9/cloudhsm-openssl-provider-latest.el9.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-openssl-provider-latest.el9.aarch64.rpm
```
------
#### [ RHEL 10 (10.0\$1) ]
在 x86\$164 架構上安裝 RHEL 10 的 OpenSSL 提供者：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL10/cloudhsm-openssl-provider-latest.el10.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-openssl-provider-latest.el10.x86_64.rpm
```
在 ARM64 架構上安裝 RHEL 10 的 OpenSSL 提供者：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL10/cloudhsm-openssl-provider-latest.el10.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-openssl-provider-latest.el10.aarch64.rpm
```
------
#### [ Ubuntu 24.04 ]
在 x86\$164 架構上安裝適用於 Ubuntu 24.04 的 OpenSSL 提供者：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Noble/cloudhsm-openssl-provider_latest_u24.04_amd64.deb
```
```
$ sudo dpkg -i ./cloudhsm-openssl-provider_latest_u24.04_amd64.deb
```
在 ARM64 架構上安裝適用於 Ubuntu 24.04 的 OpenSSL 提供者：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Noble/cloudhsm-openssl-provider_latest_u24.04_arm64.deb
```
```
$ sudo dpkg -i ./cloudhsm-openssl-provider_latest_u24.04_arm64.deb
```
------
您已在 安裝 OpenSSL 提供者的共用程式庫`/opt/cloudhsm/lib/licloudhsm_openssl_provider.so`。
1. 引導用戶端 SDK 5。如需關於啟動程序的詳細資訊，請參閱 [引導用戶端 SDK](cluster-connect.md#connect-how-to)。
1. 使用加密使用者 (CU) 登入資料設定`CLOUDHSM_PIN`環境變數：
```
$ export CLOUDHSM_PIN=:
```
1. 將 OpenSSL 提供者的安裝連接至叢集。如需詳細資訊，請參閱[連接至叢集](cluster-connect.md)。
## 驗證安裝
確認 OpenSSL 提供者已正確安裝：
```
$ CLOUDHSM_PIN=: openssl list -providers -provider cloudhsm
```
您應該會看到類似以下的輸出：
```
Providers:
cloudhsm
name: AWS CloudHSM OpenSSL Provider
version: 5.17.0
status: active
default
name: OpenSSL Default Provider
version: 3.2.2
status: active
```
# OpenSSL Provider for AWS CloudHSM Client SDK 5 支援的金鑰類型
AWS CloudHSM OpenSSL 提供者使用用戶端 SDK 5 支援下列金鑰類型。
****
| 金鑰類型 | Description |
| --- | --- |
| RSA | RSA 簽署/驗證和非對稱加密操作。驗證程序已卸載到 OpenSSL 軟件中。若要產生與 OpenSSL 提供者互通的 RSA 金鑰，請參閱 [使用 CloudHSM CLI 匯出非對稱金鑰](cloudhsm_cli-key-generate-file.md)。 |
| EC | ECDSA 簽署/驗證 P-256, P-384 和 P-521 曲線。驗證程序已卸載到 OpenSSL 軟件中。若要產生可與 OpenSSL 提供者互通的 EC 金鑰，請參閱 [使用 CloudHSM CLI 匯出非對稱金鑰](cloudhsm_cli-key-generate-file.md)。 |
# OpenSSL 提供者支援的機制
AWS CloudHSM OpenSSL 提供者 SDK 支援一組完整的密碼編譯機制，可用於各種操作，包括數位簽章、非對稱加密、對稱加密、金鑰交換等。
## RSA 簽章類型
OpenSSL 提供者支援具有多個雜湊演算法和填補結構描述的 RSA 數位簽章：
SHA1withRSA
使用 SHA-1 雜湊演算法的 RSA 簽章
+ PKCS\$11 v1.5 填補
+ PSS （概率簽章結構描述） 填補
SHA224withRSA
使用 SHA-224 雜湊演算法的 RSA 簽章
+ PKCS\$11 v1.5 填補
+ PSS 填補
SHA256withRSA
使用 SHA-256 雜湊演算法的 RSA 簽章
+ PKCS\$11 v1.5 填補
+ PSS 填補
SHA384withRSA
使用 SHA-384 雜湊演算法的 RSA 簽章
+ PKCS\$11 v1.5 填補
+ PSS 填補
SHA512withRSA
使用 SHA-512 雜湊演算法的 RSA 簽章
+ PKCS\$11 v1.5 填補
+ PSS 填補
## ECDSA 簽章類型
OpenSSL 提供者支援具有多個雜湊演算法的 ECDSA 數位簽章：
SHA1withECDSA
使用 SHA-1 雜湊演算法的 ECDSA 簽章
SHA224withECDSA
使用 SHA-224 雜湊演算法的 ECDSA 簽章
SHA256withECDSA
使用 SHA-256 雜湊演算法的 ECDSA 簽章
SHA384withECDSA
使用 SHA-384 雜湊演算法的 ECDSA 簽章
SHA512withECDSA
使用 SHA-512 雜湊演算法的 ECDSA 簽章
# OpenSSL 提供者進階組態
AWS CloudHSM OpenSSL 提供者 SDK 提供進階組態選項，可針對不同的使用案例和環境自訂其行為。使用 設定工具來設定這些選項。
+ [OpenSSL 提供者的重試組態](openssl-provider-configs-retry.md)
# 的 OpenSSL 提供者重試命令 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-openssl-provider --default-retry-mode off
```
------
# AWS CloudHSM 用戶端 SDK 5 的金鑰儲存提供者 (KSP)
Key Storage Provider (KSP) 是 Microsoft Windows 作業系統特有的密碼編譯 API。金鑰儲存提供者 (KSP) 可讓開發人員使用密碼編譯技術來保護以 Windows 為基礎的應用程式。
如需關於啟動載入的資訊，請參閱 [連接至叢集](cluster-connect.md)。
如需關於使用用戶端 SDK 3 的資訊，請參閱 [使用先前的 SDK 版本來使用 AWS CloudHSM](choose-client-sdk.md)。
**Topics**
+ [安裝 AWS CloudHSM 用戶端 SDK 5 的金鑰儲存提供者 (KSP)](ksp-library-install.md)
+ [向 AWS CloudHSM 用戶端 SDK 5 的金鑰儲存提供者 (KSP) 驗證](ksp-library-authentication.md)
+ [AWS CloudHSM 用戶端 SDK 5 金鑰儲存提供者 (KSP) 支援的金鑰類型](ksp-library--key-types.md)
+ [用戶端 AWS CloudHSM SDK 5 支援的 API 操作金鑰儲存提供者 (KSP)](ksp-library-apis.md)
+ [適用於 的 KSP 進階組態 AWS CloudHSM](ksp-library-configs.md)
# 安裝 AWS CloudHSM 用戶端 SDK 5 的金鑰儲存提供者 (KSP)
使用下列各節來安裝 AWS CloudHSM 用戶端 SDK 5 的金鑰儲存提供者 (KSP)。
**注意**
若要使用用戶端 SDK 5 執行單一 HSM 叢集，您必須先將 `disable_key_availability_check` 設定為 `True` 來管理用戶端金鑰持久性。如需詳細資訊，請參閱[金鑰同步處理](manage-key-sync.md)和[用戶端 SDK 5 設定工具](configure-sdk-5.md)。
**安裝和設定金鑰儲存提供者 (KSP)**
1. 在 x86\$164 架構上安裝 Windows Server 的金鑰儲存提供者 (KSP)，以管理員身分開啟 PowerShell，然後執行下列命令：
```
PS C:\> wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Windows/AWSCloudHSMKSP-latest.msi -Outfile C:\AWSCloudHSMKSP-latest.msi
```
```
PS C:\> Start-Process msiexec.exe -ArgumentList '/i C:\AWSCloudHSMKSP-latest.msi /quiet /norestart /log C:\client-install.txt' -Wait
```
1. 使用設定工具指定發行憑證的位置。如需說明，請參閱[指定憑證的位置。](cluster-connect.md#specify-cert-location)。
1. 若要連線到您的叢集，請參閱 [引導用戶端 SDK](cluster-connect.md#connect-how-to)。
1. 您可以在下列位置找到金鑰儲存提供者 (KSP) 檔案：
+ Windows 二進位檔案：
```
C:\Program Files\Amazon\CloudHSM
```
Windows組態指令碼和日誌檔案：
```
C:\ProgramData\Amazon\CloudHSM
```
# 向 AWS CloudHSM 用戶端 SDK 5 的金鑰儲存提供者 (KSP) 驗證
在 AWS CloudHSM 用戶端 SDK 5 使用金鑰儲存提供者 (KSP) 之前，您必須在系統上設定 HSM 的登入憑證。您有兩種選擇：
+ Windows Credentials Manager （建議提高安全性）
+ 系統環境變數 （簡易設定）
## Windows 認證管理員
您可以使用 `set_cloudhsm_credentials`公用程式或 Windows Credentials Manager 介面來設定登入資料。
+ **使用 `set_cloudhsm_credentials` 公用程式**：
Windows 安裝程式包含 `set_cloudhsm_credentials`公用程式。您可以使用此公用程式，輕鬆地將 HSM 登入資料傳遞到 Windows 認證管理員。如果您想要從來源編譯此公用程式，您可以使用安裝程式中包含的 Python 程式碼。
1. 導覽至 `C:\Program Files\Amazon\CloudHSM\tools\`。
1. 執行以下命令：
```
set_cloudhsm_credentials.exe --username --password
```
+ **使用認證管理員界面**：
1. 開啟登入資料管理員：
+ `credential manager` 在任務列搜尋方塊中輸入
+ 選取**登入資料管理員**
1. 選取 **Windows 認證**以管理 Windows 認證。
1. 選取**新增一般登入**資料
1. 輸入下列詳細資訊：
+ **網路或網路地址**：`CLOUDHSM_PIN`。
+ **使用者名稱**：**。
+ **密碼**：**。
1. 選擇 **OK (確定)**。
## 系統環境變數
您可以設定系統環境變數來識別 HSM 和[加密使用者](understanding-users.md#crypto-user-chsm-cli) (CU)。
**警告**
透過系統環境變數設定登入資料會將您的密碼以純文字形式存放在您的系統上。為了提高安全性，請改用 Windows Credential Manager。
您可以使用下列方式設定環境變數：
+ [https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/setx](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/setx)。
+ Windows **系統屬性**控制面板 **（進階**索引標籤）。
+ 設定永久系統環境變數[程式設計](https://msdn.microsoft.com/en-us/library/system.environment.setenvironmentvariable(v=vs.110).aspx)方法。
若要設定系統環境變數：
**`CLOUDHSM_PIN=:`**
識別 HSM 中的[加密使用者](understanding-users.md#crypto-user-chsm-cli) (CU)，並提供所有必要的登入資訊。您的應用程式會以這個 CU 的身分進行驗證和執行。這個應用程式具有此 CU 的許可，並僅可以檢視和管理該 CU 擁有和共用的金鑰。若要建立新的 CU，請使用 CloudHSM CLI 中的[使用者建立](cloudhsm_cli-user-create.md)命令。若要尋找現有的 CUs，請使用 CloudHSM CLI 中的[使用者清單](cloudhsm_cli-user-list.md)命令。
例如：
```
setx /m CLOUDHSM_PIN test_user:password123
```
**注意**
設定 CLOUDHSM\$1PIN 環境變數時，您必須逸出 Shell 可能解譯的任何特殊字元。
# AWS CloudHSM 用戶端 SDK 5 金鑰儲存提供者 (KSP) 支援的金鑰類型
AWS CloudHSM 金鑰儲存提供者 (KSP) 透過用戶端 SDK 5 支援下列金鑰類型。
****
| 金鑰類型 | Description |
| --- | --- |
| EC | 使用 secp256r1 (P-256)、secp384r1 (P-384) 和 secp521r1 (P-521) 曲線產生金鑰。 |
| RSA | 產生 2048、3072 和 4096 位元 RSA 金鑰。 |
# 用戶端 AWS CloudHSM SDK 5 支援的 API 操作金鑰儲存提供者 (KSP)
KSP 中的參數由 Microsoft KSP 定義。如需詳細資訊，請參閱 [Microsoft 文件](https://learn.microsoft.com/en-us/windows/win32/api/ncrypt/)。
金鑰儲存提供者 (KSP) 支援 AWS CloudHSM 用戶端 SDK 5 的下列 KSP API 操作。
+ [`NCryptOpenStorageProvider`](ksp-library-apis-open-provider.md)
+ [NCryptOpenKey](ksp-library-apis-open-key.md)
+ [NCryptCreatePersistedKey](ksp-library-apis-create-persisted-key.md)
+ [NCryptGetProperty](ksp-library-apis-get-property.md)
+ [NCryptSetProperty](ksp-library-apis-set-property.md)
+ [NCryptFinalizeKey](ksp-library-apis-finalize-key.md)
+ [NCryptDeleteKey](ksp-library-apis-delete-key.md)
+ [NCryptFreeObject](ksp-library-apis-free-object.md)
+ [NCryptFreeBuffer](ksp-library-apis-free-buffer.md)
+ [NCryptIsAlgSupported](ksp-library-apis-is-alg-supported.md)
+ [NCryptEnumAlgorithms](ksp-library-apis-enum-algorithms.md)
+ [NCryptEnumKeys](ksp-library-apis-enum-keys.md)
+ [NCryptExportKey](ksp-library-apis-export-key.md)
+ [NCryptSignHash](ksp-library-apis-sign-hash.md)
+ [NCryptVerifySignature](ksp-library-apis-verify-signature.md)
# NCryptOpenStorageProvider 函數與金鑰儲存提供者 (KSP)
`NCryptOpenStorageProvider` 函數會載入並初始化金鑰儲存提供者 (KSP)。
## Parameters
`phProvider` 【輸出】
儲存提供者控點之`NCRYPT_PROV_HANDLE`變數的指標。
`pszProviderName` 【in】
識別金鑰儲存提供者的 null 終止 Unicode 字串指標。AWS CloudHSM Key Storage Provider (KSP) 支援下列值：
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/ksp-library-apis-open-provider.html)
值為廣字元字串常值，如常值前的 L 所示。
`dwFlags` 【in】
修改函數行為的旗標。此函數未定義任何旗標。
## 傳回值
函數會傳回狀態碼，表示成功或失敗。
常見的傳回代碼包括：
****
| 傳回代碼 | Description |
| --- | --- |
| ERROR\$1SUCCESS | 操作已成功完成。 |
| NTE\$1INVALID\$1PARAMETER | 一或多個參數無效。 |
| NTE\$1FAIL | 操作無法完成。 |
# NCryptOpenKey 與金鑰儲存提供者 (KSP)
`NCryptOpenKey` 函數會開啟金鑰儲存提供者 (KSP) 中存在的金鑰。
## Parameters
`hProvider` 【in】
包含金鑰的 KSP 控制代碼。使用 [`NCryptOpenStorageProvider`](ksp-library-apis-open-provider.md)取得控點。
`phKey` 【輸出】
儲存金鑰控制代碼之`NCRYPT_KEY_HANDLE`變數的指標。
`pszKeyName` 【in】
包含金鑰名稱的 null 終止 Unicode 字串指標。
`dwLegacyKeySpec` 【in、未使用】
AWS CloudHSM 金鑰儲存提供者 (KSP) 不會使用此參數。
`dwFlags` 【in】
修改函數行為的旗標。此函數未定義任何旗標。
## 傳回值
函數會傳回狀態碼，表示成功或失敗。
常見的傳回代碼包括：
****
| 傳回代碼 | Description |
| --- | --- |
| ERROR\$1SUCCESS | 操作已成功完成。 |
| NTE\$1INVALID\$1PARAMETER | 一或多個參數無效。 |
| NTE\$1FAIL | 操作無法完成。 |
| NTE\$1INVALID\$1HANDLE | 中的控點`hProvider`無效。 |
| NTE\$1BAD\$1KEYSET | 提供的金鑰名稱未傳回唯一結果。 |
# NCryptCreatePersistedKey 與金鑰儲存提供者 (KSP)
`NCryptCreatePersistedKey` 函數會建立新的金鑰，並將其存放在金鑰儲存提供者 (KSP) 中。您可以使用 [`NCryptSetProperty`](ksp-library-apis-set-property.md)函數在建立後設定其屬性。您必須先呼叫 [`NCryptFinalizeKey`](ksp-library-apis-finalize-key.md)，才能使用 金鑰。
## Parameters
`hProvider` 【in】
您將建立金鑰之金鑰儲存提供者的控制代碼。使用 [`NCryptOpenStorageProvider`](ksp-library-apis-open-provider.md)取得此控制代碼。
`phKey` 【輸出】
存放金鑰控制代碼的 `NCRYPT_KEY_HANDLE`變數地址。
`pszAlgId` 【in】
指向 null 終止的 Unicode 字串的指標，指定用於建立金鑰的密碼編譯演算法識別符。
AWS CloudHSM 金鑰儲存提供者 (KSP) 支援下列演算法：
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/ksp-library-apis-create-persisted-key.html)
`pszKeyName` 【in，選用】
指向包含金鑰名稱的 null 終止 Unicode 字串的指標。如果此參數為 NULL，則此函數會建立不會保留的暫時性金鑰。
`dwLegacyKeySpec` 【in、未使用】
AWS CloudHSM 金鑰儲存提供者 (KSP) 不會使用此參數。
`dwFlags` 【in】
用於修改函數行為的旗標。使用下列零或多個值：
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/ksp-library-apis-create-persisted-key.html)
## 傳回值
函數會傳回狀態碼，表示成功或失敗。
常見的傳回代碼包括：
****
| 傳回代碼 | Description |
| --- | --- |
| ERROR\$1SUCCESS | 函數已成功完成。 |
| NTE\$1INVALID\$1PARAMETER | 一或多個參數無效。 |
| NTE\$1FAIL | 操作無法完成。 |
| NTE\$1BAD\$1FLAGS | `dwFlags` 參數包含無效的值。 |
| NTE\$1NOT\$1SUPPORTED | `pszAlgId` 參數包含不支援的值。 |
| NTE\$1EXISTS | 具有指定名稱的金鑰已存在，且操作未使用 ` NCRYPT_OVERWRITE_KEY_FLAG`。 |
# NCryptGetProperty 與金鑰儲存提供者 (KSP)
`NCryptGetProperty` 函數會擷取金鑰儲存物件的屬性值。
## Parameters
`hObject` 【in】
您要擷取其屬性的物件控點。您可以使用：
+ 供應商控制代碼 (`NCRYPT_PROV_HANDLE`)
+ 金鑰控制代碼 (`NCRYPT_KEY_HANDLE`)
`pszProperty ` 【in】
指向 null 終止的 Unicode 字串的指標，其中包含要擷取的屬性名稱。
使用 時`NCRYPT_PROV_HANDLE`， AWS CloudHSM 金鑰儲存提供者 (KSP) 支援下列 KSP 識別符：
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/ksp-library-apis-get-property.html)
使用 時`NCRYPT_KEY_HANDLE`， AWS CloudHSM 金鑰儲存提供者 (KSP) 支援下列 KSP 識別符：
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/ksp-library-apis-get-property.html)
值為廣字元字串常值，如常值前的 L 所示。
`pbOutput` 【輸出】
儲存屬性值的緩衝區地址。使用 指定緩衝區大小`cbOutput`。
若要判斷所需的緩衝區大小，請將此參數設定為 NULL。函數會將所需的大小 （以位元組為單位） 存放在 指向的位置`pcbResult`。
`cbOutput` 【in】
`pbOutput` 緩衝區的大小，以位元組為單位。
`pcbResult` 【輸出】
指向 DWORD 變數的指標，可存放複製到緩衝區的`pbOutput`位元組數。
如果 `pbOutput`是 NULL，這會儲存所需的大小 （以位元組為單位）。
`dwFlags` 【in】
用於修改函數行為的旗標。您可以使用零或：
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/ksp-library-apis-get-property.html)
當 pszProperty 為 時`NCRYPT_SECURITY_DESCR_PROPERTY`，請使用下列其中一項或組合：
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/ksp-library-apis-get-property.html)
## 傳回值
函數會傳回狀態碼，表示成功或失敗。
常見的傳回碼包括：
****
| 傳回代碼 | Description |
| --- | --- |
| ERROR\$1SUCCESS | 操作已成功完成。 |
| NTE\$1INVALID\$1PARAMETER | 一或多個參數無效。 |
| NTE\$1FAIL | 操作無法完成。 |
| NTE\$1BAD\$1FLAGS | `dwFlags` 參數包含無效的值。 |
| NTE\$1NOT\$1SUPPORTED | `pszAlgId` 參數包含不支援的值。 |
| NTE\$1INVALID\$1HANDLE | 中的控點`hObject`無效。 |
| NTE\$1BUFFER\$1TOO\$1SMALL | `cbOutput` 參數太小，無法傳回值。 |
# NCryptSetProperty 與金鑰儲存提供者 (KSP)
`NCryptSetProperty` 函數會設定金鑰儲存物件的屬性值。
## Parameters
`hObject` 【in】
您要設定其屬性的物件控點。您可以使用：
+ 供應商控制代碼 (`NCRYPT_PROV_HANDLE`)
+ 金鑰控制代碼 (`NCRYPT_KEY_HANDLE`)
`pszProperty ` 【in】
指向 null 終止的 Unicode 字串的指標，其中包含要擷取的屬性名稱。
使用 時`NCRYPT_PROV_HANDLE`， AWS CloudHSM 金鑰儲存提供者 (KSP) 支援下列 KSP 識別符：
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/ksp-library-apis-set-property.html)
使用 時`NCRYPT_KEY_HANDLE`， AWS CloudHSM 金鑰儲存提供者 (KSP) 支援下列 KSP 識別符：
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/ksp-library-apis-set-property.html)
值為廣字元字串常值，如常值前的 L 所示。
`pbInput` 【in】
包含新屬性值的緩衝區地址。 `cbInput`包含緩衝區的大小。
`cbInput` 【in】
`pbInput` 緩衝區的大小，以位元組為單位。
`dwFlags` 【in】
修改函數行為的旗標。此函數未定義任何旗標。
## 傳回值
函數會傳回狀態碼，表示成功或失敗。
常見的傳回代碼包括：
****
| 傳回代碼 | Description |
| --- | --- |
| ERROR\$1SUCCESS | 操作已成功完成。 |
| NTE\$1INVALID\$1PARAMETER | 一或多個參數無效。 |
| NTE\$1FAIL | 操作無法完成。 |
| NTE\$1BAD\$1FLAGS | `dwFlags` 參數包含無效的值。 |
| NTE\$1NOT\$1SUPPORTED | `pszProperty` 參數包含不支援的值。 |
| NTE\$1INVALID\$1HANDLE | 中的控點`hObject`無效。 |
| NTE\$1BAD\$1DATA | 指向 `pbInput`和 的資料`cbInput`無效。 |
# NCryptFinalizeKey 與金鑰儲存提供者 (KSP)
`NCryptFinalizeKey` 函數會完成 KSP 金鑰。您必須呼叫此函數，才能使用 金鑰。
## Parameters
`hKey` 【in】
要完成的金鑰控制代碼。呼叫 [NCryptCreatePersistedKey](ksp-library-apis-create-persisted-key.md) 函數來取得此控制代碼。
`dwFlags` 【in】
用於修改函數行為的旗標。您可以使用零或這些值：
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/ksp-library-apis-finalize-key.html)
## 傳回值
函數會傳回狀態碼，表示成功或失敗。
常見的傳回碼包括：
****
| 傳回代碼 | Description |
| --- | --- |
| ERROR\$1SUCCESS | 操作已成功完成。 |
| NTE\$1FAIL | 操作無法完成。 |
| NTE\$1INVALID\$1HANDLE | 中的控點`hKey`無效。 |
| NTE\$1NOT\$1SUPPORTED | `dwFlags` 參數包含不支援的值。 |
| NTE\$1BAD\$1FLAGS | `dwFlags` 參數包含無效的值。 |
# NCryptDeleteKey 與金鑰儲存提供者 (KSP)
`NCryptDeleteKey` 函數會從金鑰儲存提供者 (KSP) 刪除 KSP 金鑰。
## Parameters
`hKey` 【in】
要刪除之金鑰的控制代碼。
`dwFlags` 【in】
用於修改函數行為的旗標。您可以使用下列零或多個值：
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/ksp-library-apis-delete-key.html)
## 傳回值
函數會傳回狀態碼，表示成功或失敗。
常見的傳回碼包括：
****
| 傳回代碼 | Description |
| --- | --- |
| ERROR\$1SUCCESS | 函數已成功。 |
| NTE\$1INVALID\$1PARAMETER | 一或多個參數無效。 |
| NTE\$1BAD\$1FLAGS | `dwFlags` 參數包含無效的值。 |
| NTE\$1FAIL | 操作無法完成。 |
| NTE\$1INVALID\$1HANDLE | 中的控點`hKey`無效。 |
| NTE\$1INTERNAL\$1ERROR | 刪除金鑰時發生內部錯誤。 |
# NCryptFreeObject 與金鑰儲存提供者 (KSP)
`NCryptFreeObject` 函數會從金鑰儲存提供者 (KSP) 釋出提供者或金鑰控制代碼。
## Parameters
`hObject` 【in】
要釋放之物件的控制代碼。您可以使用：
+ 供應商控制代碼 (`NCRYPT_PROV_HANDLE`)
+ 金鑰控制代碼 (`NCRYPT_KEY_HANDLE`)
## 傳回值
函數會傳回狀態碼，表示成功或失敗。
常見的傳回碼包括：
****
| 傳回代碼 | Description |
| --- | --- |
| ERROR\$1SUCCESS | 操作已成功完成。 |
| NTE\$1INVALID\$1HANDLE | 中的控點`hObject`無效。 |
# NCryptFreeBuffer 與金鑰儲存提供者 (KSP)
`NCryptFreeBuffer` 函數會釋出金鑰儲存提供者 (KSP) 配置的記憶體區塊。
## Parameters
`pvInput` 【in】
要釋放的記憶體地址。
## 傳回值
函數會傳回狀態碼，表示成功或失敗。
常見的傳回碼包括：
****
| 傳回代碼 | Description |
| --- | --- |
| ERROR\$1SUCCESS | 操作已成功完成。 |
| NTE\$1FAIL | 操作無法完成。 |
# 使用金鑰儲存提供者 (KSP) NCryptIsAlgSupported
NCryptIsAlgSupported 函數會判斷金鑰儲存提供者 (KSP) 是否支援特定的密碼編譯演算法。
## Parameters
`hProvider` 【in】
金鑰儲存提供者的控制代碼。使用 [`NCryptOpenStorageProvider`](ksp-library-apis-open-provider.md)取得控點。
`pszAlgId` 【in】
指向 null 終止的 Unicode 字串的指標，其中包含用於建立金鑰的密碼編譯演算法識別符。AWS CloudHSM Key Storage Provider (KSP) 支援下列演算法：
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/ksp-library-apis-is-alg-supported.html)
`dwFlags` 【in】
修改函數行為的旗標。這可以是零或下列值：
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/ksp-library-apis-is-alg-supported.html)
## 傳回值
函數會傳回狀態碼，表示成功或失敗。
常見的傳回代碼包括：
****
| 傳回代碼 | Description |
| --- | --- |
| ERROR\$1SUCCESS | 操作已成功完成。 |
| NTE\$1INVALID\$1PARAMETER | 一或多個參數無效。 |
| NTE\$1BAD\$1FLAGS | `dwFlags` 參數包含無效的值。 |
| NTE\$1NOT\$1SUPPORTED | `pszAlgId` 參數包含不支援的值。 |
| NTE\$1INVALID\$1HANDLE | 中的控點`hProvider`無效。 |
# 具有金鑰儲存提供者 (KSP) 的 NCryptEnumAlgorithms
`NCryptEnumAlgorithms` 函數會擷取金鑰儲存提供者 (KSP) 支援的演算法名稱。
## Parameters
`hProvider` 【in】
要列舉演算法之金鑰儲存提供者的控制代碼。使用 [`NCryptOpenStorageProvider`](ksp-library-apis-open-provider.md)函數取得此控點。
`dwAlgOperations` 【in】
指定要列舉哪些演算法類別的一組值。您可以使用零列舉所有演算法，或結合下列一或多個值：
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/ksp-library-apis-enum-algorithms.html)
`pdwAlgCount` 【輸出】
`ppAlgList` 陣列中存放元素數目的 DWORD 地址。
`ppAlgList` 【輸出】
儲存已註冊演算法名稱陣列的`NCryptAlgorithmName`結構指標地址。`pdwAlgCount` 參數指出此陣列中的元素數目。
`dwFlags` 【in】
用於修改函數行為的旗標。使用零或下列值：
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/ksp-library-apis-enum-algorithms.html)
## 傳回值
函數會傳回狀態碼，表示成功或失敗。
常見的傳回代碼包括：
****
| 傳回代碼 | Description |
| --- | --- |
| ERROR\$1SUCCESS | 操作已成功完成。 |
| NTE\$1INVALID\$1PARAMETER | 一或多個參數無效。 |
| NTE\$1FAIL | 操作無法完成。 |
| NTE\$1BAD\$1FLAGS | `dwFlags` 參數包含無效的值。 |
| NTE\$1NOT\$1SUPPORTED | `dwAlgOperations` 參數包含不支援的值。 |
# NCryptEnumKeys 與金鑰儲存提供者 (KSP)
NCryptEnumKeys 函數會列出儲存在金鑰儲存提供者 (KSP) 中的金鑰。
## Parameters
`hProvider` 【in】
金鑰儲存提供者控制代碼。使用 [`NCryptOpenStorageProvider`](ksp-library-apis-open-provider.md)取得此控制代碼。
`pszScope` 【in、未使用】
將此參數設定為 NULL。
`ppKeyName` 【輸出】
儲存金鑰名稱之`NCryptKeyName`結構的指標地址。若要在使用後釋放此記憶體，請呼叫 `NCryptFreeBuffer`。
`ppEnumState` 【輸入、輸出】
追蹤列舉進度的 VOID 指標地址。金鑰儲存提供者會在內部使用此資訊來管理列舉序列。若要從頭開始新的列舉，請將此指標設定為 NULL。
若要在完成列舉後釋放此記憶體，請將此指標傳遞至 `NCryptFreeBuffer`。
`dwFlags` 【in】
用於修改函數行為的旗標。此函數沒有旗標。
## 傳回值
函數會傳回狀態碼，表示成功或失敗。
常見的傳回碼包括：
****
| 傳回代碼 | Description |
| --- | --- |
| ERROR\$1SUCCESS | 操作已成功完成。 |
| NTE\$1INVALID\$1PARAMETER | 一或多個參數無效。 |
| NTE\$1FAIL | 操作無法完成。 |
| NTE\$1INVALID\$1HANDLE | 中的控點`hProvider`無效。 |
| NTE\$1NO\$1MORE\$1ITEMS | 列舉已列出所有可用的金鑰。 |
# NCryptExportKey 與金鑰儲存提供者 (KSP)
`NCryptExportKey` 函數會將 KSP 金鑰匯出至記憶體 BLOB。此函數僅支援匯出公有金鑰。
## Parameters
`hKey` 【in】
要匯出之金鑰的控制代碼。
`hExportKey` 【in、未使用】
AWS CloudHSM 金鑰儲存提供者 (KSP) 不會使用此參數。
`pszBlobType` 【in】
null 終止的 Unicode 字串，指定要匯出的BLOB類型。 AWS CloudHSM 金鑰儲存提供者 (KSP) 支援下列值：
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/ksp-library-apis-export-key.html)
`pParameterList` 【in、未使用】
AWS CloudHSM 金鑰儲存提供者 (KSP) 不會使用此參數。
`pbOutput` 【輸出，選用】
儲存金鑰 BLOB 的緩衝區地址。使用 指定緩衝區大小`cbOutput`。如果設定為 NULL，函數會將所需的大小 （以位元組為單位） 存放在 指向的 DWORD 中`pcbResult`。
`cbOutput` 【in】
`pbOutput` 緩衝區的大小，以位元組為單位。
`pcbResult` 【輸出】
存放複製到`pbOutput`緩衝區的位元組數的 DWORD 變數地址。如果 `pbOutput`是 NULL，則函數會以位元組為單位存放所需的緩衝區大小。
`dwFlags` 【in】
修改函數運作方式的旗標。您可以使用零或下列項目：
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/ksp-library-apis-export-key.html)
## 傳回值
函數會傳回狀態碼，表示成功或失敗。
常見的傳回代碼包括：
****
| 傳回代碼 | Description |
| --- | --- |
| ERROR\$1SUCCESS | 操作已成功完成。 |
| NTE\$1INVALID\$1PARAMETER | 一或多個參數無效。 |
| NTE\$1FAIL | 操作無法完成。 |
| NTE\$1INVALID\$1HANDLE | 中的控點`hProvider`無效。 |
| NTE\$1BAD\$1FLAGS | `dwFlags` 參數包含無效的值。 |
| NTE\$1BAD\$1KEY\$1STATE | 金鑰狀態無效。 |
| NTE\$1NOT\$1SUPPORTED | `pszBlobType` 或 `dwFlags` 參數包含不支援的值。 |
| STATUS\$1INTERNAL\$1ERROR | 操作期間發生內部錯誤。 |
# NCryptSignHash 與金鑰儲存提供者 (KSP)
`NCryptSignHash` 函數會建立雜湊值的簽章。
## Parameters
`hKey` 【in】
用來簽署雜湊之金鑰的控制代碼。
`pPaddingInfo` 【in，選用】
包含填補資訊的結構指標。結構類型取決於 `dwFlags`值。僅將此參數與非對稱金鑰搭配使用；將其他金鑰類型設為 NULL。
`pbHashValue` 【in】
緩衝區的指標，其中包含要簽署的雜湊值。使用 指定緩衝區大小`cbHashValue`。
`cbHashValue` 【in】
要簽署之`pbHashValue`緩衝區的大小，以位元組為單位。
`pbSignature` 【輸出】
儲存簽章的緩衝區地址。使用 指定緩衝區大小`cbSignature`。
若要判斷所需的緩衝區大小，請將此參數設定為 NULL。函數會將所需的大小 （以位元組為單位） 存放在 指向的位置`pcbResult`。
`cbSignature` 【in】
`pbSignature` 緩衝區的大小，以位元組為單位。如果 `pbSignature`是 NULL，則函數會忽略此參數。
`pcbResult` 【輸出】
指向 DWORD 變數的指標，可存放複製到`pbSignature`緩衝區的位元組數。
如果 `pbSignature`是 NULL，則會以位元組為單位存放所需的緩衝區大小。
`dwFlags` 【in】
用於修改函數行為的旗標。允許的旗標取決於您的金鑰類型。使用下列其中一個值：
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/ksp-library-apis-sign-hash.html)
## 傳回值
函數會傳回狀態碼，表示成功或失敗。
常見的傳回碼包括：
****
| 傳回代碼 | Description |
| --- | --- |
| ERROR\$1SUCCESS | 操作已成功完成。 |
| NTE\$1INVALID\$1PARAMETER | 一或多個參數無效。 |
| NTE\$1FAIL | 操作無法完成。 |
| NTE\$1INVALID\$1HANDLE | 中的控點`hKey`無效。 |
| NTE\$1BAD\$1FLAGS | `dwFlags` 參數包含無效的值。 |
| NTE\$1BUFFER\$1TOO\$1SMALL | `pcbOutput` 參數太小，無法傳回值。 |
| NTE\$1BAD\$1KEY\$1STATE | 金鑰狀態無效。 |
| NTE\$1INTERNAL\$1ERROR | 簽署雜湊時發生內部錯誤。 |
# NCryptVerifySignature with Key Storage Provider (KSP)
`NCryptVerifySignature` 函數會確認簽章是否符合指定的雜湊。
## Parameters
`hKey` 【in】
用來解密簽章的金鑰控點。您必須使用用來使用 簽署資料的金鑰對公有金鑰部分[`NCryptSignHash`](ksp-library-apis-sign-hash.md)。
`pPaddingInfo` 【in，選用】
包含填補資訊的結構指標。結構類型取決於 `dwFlags`值。僅將此參數與非對稱金鑰搭配使用；將其他金鑰類型設為 NULL。
`pbHashValue` 【in】
緩衝區的指標，其中包含要簽署的雜湊值。使用 指定緩衝區大小`cbHashValue`。
`cbHashValue` 【in】
`pbHashValue` 緩衝區的大小，以位元組為單位。
`pbSignature` 【輸出】
包含資料簽署雜湊的緩衝區地址。使用 [`NCryptSignHash`](ksp-library-apis-sign-hash.md)建立此簽章。使用 指定緩衝區大小`cbSignature`。
`cbSignature` 【in】
`pbSignature` 緩衝區的大小，以位元組為單位。使用 [`NCryptSignHash`](ksp-library-apis-sign-hash.md)建立簽章。
`dwFlags` 【in】
用於修改函數行為的旗標。允許的旗標取決於您的金鑰類型。使用下列其中一個值：
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/ksp-library-apis-verify-signature.html)
## 傳回值
函數會傳回狀態碼，表示成功或失敗。
常見的傳回代碼包括：
****
| 傳回代碼 | Description |
| --- | --- |
| ERROR\$1SUCCESS | 操作已成功完成。 |
| NTE\$1INVALID\$1PARAMETER | 一或多個參數無效。 |
| NTE\$1FAIL | 操作無法完成。 |
| NTE\$1INVALID\$1HANDLE | 中的控點`hKey`無效。 |
| NTE\$1BAD\$1FLAGS | `dwFlags` 參數包含無效的值。 |
| NTE\$1BAD\$1SIGNATURE | 簽章未驗證。 |
| NTE\$1BAD\$1KEY\$1STATE | 金鑰狀態無效。 |
| NTE\$1INTERNAL\$1ERROR | 驗證簽章時發生內部錯誤。 |
# 適用於 的 KSP 進階組態 AWS CloudHSM
AWS CloudHSM 金鑰儲存提供者 (KSP) 包含下列進階組態，這不屬於大多數客戶使用的一般組態。這些組態提供額外的功能。
+ [KSP 的 SDK3 相容性模式](ksp-library-configs-sdk3-compatibility-mode.md)
# 適用於 金鑰儲存提供者 (KSP) 的 SDK3 相容性模式 AWS CloudHSM
金鑰儲存提供者 (KSP) 實作 HSM 金鑰互動的不同方法：
+ 用戶端 SDK 5：與存放在 HSM 中的金鑰直接通訊，無需本機參考檔案
+ 用戶端 SDK 3：在 Windows 伺服器上維護本機檔案，做為 HSM 中所存放金鑰的參考，使用這些檔案來促進金鑰操作
對於從用戶端 SDK 3 遷移至用戶端 SDK 5 的客戶，啟用 SDK3 相容性模式選項支援使用現有金鑰參考檔案的操作，同時保留基礎 HSM 金鑰儲存架構。
## 啟用 SDK3 相容性模式
------
#### [ Windows ]
**在 Windows 中為用戶端 SDK3 5 啟用金鑰儲存提供者 (KSP) 的 SDK3 相容性模式**
+ 您可以使用下列命令來啟用 SDK3 相容性模式：
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-ksp.exe" --enable-sdk3-compatibility-mode
```
------
## 停用 SDK3 相容性模式
------
#### [ Windows ]
**在 Windows 中停用用戶端 SDK3 5 金鑰儲存提供者 (KSP) 的 SDK3 相容性模式**
+ 您可以使用下列命令來停用 SDK3 相容性模式：
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-ksp.exe" --disable-sdk3-compatibility-mode
```
------
# 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
```
------