本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# AWS CloudHSM 用戶端 SDK 5 的 PKCS \#11 程式庫支援的機制
<a name="pkcs11-mechanisms"></a>

PKCS \#11 程式庫與 PKCS \#11 規格的 2.40 版相容。若要使用 PKCS \#11 叫用加密功能，請利用指定機制呼叫函數。下列各節摘要了 AWS CloudHSM 用戶端 SDK 5 支援的函數和機制組合。

PKCS \#11 程式庫支援下列演算法：
+ **加密和解密**：AES-CBC、AES-CTR、AES-ECB、AES-GCM、DES3-CBC、DES3-ECB、RSA-OAEP 和 RSA-PKCS
+ **簽署和驗證** – RSA、HMAC、ECDSA （含和不含雜湊）、EdDSA (Ed25519 和 Ed25519ph) 和 ML-DSA （含純外部 mu 模式）
+ **雜湊/摘要**：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)

## 產生金鑰與金鑰對函數
<a name="pkcs11-mech-function-genkey"></a>

適用於 PKCS \#11 程式庫 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_CLOUDHSM_ML_DSA_KEY_PAIR_GEN`[3](#mech3)
+ `CKM_GENERIC_SECRET_KEY_GEN`
+ `CKM_AES_KEY_GEN`
+ `CKM_DES3_KEY_GEN`：註腳 [5](#mech5) 所列的即將進行的變更。

## 簽署和驗證函數
<a name="pkcs11-mech-function-signverify"></a>

PKCS \#11 程式庫 AWS CloudHSM 的軟體程式庫可讓您針對 Sign and Verify 函數使用下列機制。使用用戶端 SDK 5，資料會在軟體中進行本機雜湊處理。這意味著 SDK 可以對任何大小的資料進行雜湊處理。

使用用戶端 SDK 5 RSA 和 ECDSA 時，雜湊在本機完成，因此沒有資料限制。HMAC 和 PureEdDSA (Ed25519) 有資料限制。如需詳細咨詢，請參閱註腳 [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`

**ML-DSA**
+ `CKM_CLOUDHSM_ML_DSA_KEY_PAIR_GEN`[3](#mech3) – 產生 ML-DSA 金鑰對。
+ `CKM_CLOUDHSM_ML_DSA`[3](#mech3) – Pure ML-DSA 簽署和驗證。
+ `CKM_CLOUDHSM_EXT_MU_ML_DSA`[3](#mech3) – ML-DSA 使用外部 mu 簽署和驗證。

**EdDSA**
+ `CKM_CLOUDHSM_EDDSA`[6](#kdf6)、 [7](#mech7) – 使用 NULL 參數 (PureEdDSA)，僅限單一部分操作。

**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`

## 簽名恢復和驗證復原函數
<a name="pkcs11-mech-function-sr-vr"></a>

用戶端 SDK 5 不支援簽名恢復和驗證復原函數。

## Digest 函數
<a name="pkcs11-mech-function-digest"></a>

適用於 PKCS \#11 程式庫 AWS CloudHSM 的軟體程式庫可讓您針對摘要函數使用下列機制。使用用戶端 SDK 5，資料會在軟體中進行本機雜湊處理。這意味著 SDK 可以對任何大小的資料進行雜湊處理。
+ `CKM_SHA_1`
+ `CKM_SHA224`
+ `CKM_SHA256`
+ `CKM_SHA384`
+ `CKM_SHA512`

## 加密和解密函數
<a name="pkcs11-mech-function-enc-dec"></a>

適用於 PKCS \#11 程式庫 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)

## 衍生金鑰函數
<a name="pkcs11-mech-function-derive-key"></a>

適用於 PKCS \#11 程式庫 AWS CloudHSM 的軟體程式庫支援下列金鑰衍生機制：
+ `CKM_SP800_108_COUNTER_KDF`
+ `CKM_ECDH1_DERIVE` - 支援下列廠商定義 KDF 類型的 ECDH 金鑰衍生[6](#kdf6)：
  + `CKD_CLOUDHSM_X963_SHA1_KDF` - X9.63 KDF 搭配 SHA1[8](#kdf7)
  + `CKD_CLOUDHSM_X963_SHA224_KDF` - X9.63 KDF 搭配 SHA224[8](#kdf7)
  + `CKD_CLOUDHSM_X963_SHA256_KDF` - X9.63 KDF 搭配 SHA256[8](#kdf7)
  + `CKD_CLOUDHSM_X963_SHA384_KDF` - X9.63 KDF 搭配 SHA384[8](#kdf7)
  + `CKD_CLOUDHSM_X963_SHA512_KDF` - X9.63 KDF 搭配 SHA512[8](#kdf7)

## 包裝和解包函數
<a name="pkcs11-mech-function-wrap-unwrap"></a>

PKCS \#11 程式庫 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)

## 每個機制的資料大小上限
<a name="pkcs11-mech-max"></a>

下表列出每個機制設定的資料大小上限：


**資料集大小上限**  

| **Mechanism** | **資料大小上限 (位元組)** | 
| --- | --- | 
| CKM\_SHA\_1\_HMAC | 16288 | 
| CKM\_SHA224\_HMAC | 16256 | 
| CKM\_SHA256\_HMAC | 16288 | 
| CKM\_SHA384\_HMAC | 16224 | 
| CKM\_SHA512\_HMAC | 16224 | 
| CKM\_AES\_CBC | 16272 | 
| CKM\_AES\_GCM | 16224 | 
| CKM\_CLOUDHSM\_AES\_GCM | 16224 | 
| CKM\_DES3\_CBC | 16280 | 
| CKM\_CLOUDHSM\_EDDSA (PureEdDSA、NULL 參數） | 16000 | 

## 機制註釋
<a name="pkcs11-mech-annotations"></a>
+  [1] 當執行 AES-GCM 加密時，HSM 不會接受來自應用程式的初始化向量 (IV) 資料。請務必使用其產生的 IV。系統會將 HSM 所提供的 12 位元組 IV 寫入記憶體參考，該記憶體參考是由您提供的 `CK_GCM_PARAMS` 參數結構 pIV 元素所指向。為了確保使用者不會混淆，在初始化 AES-GCM 加密時，1.1.1 版和更新版本中的 PKCS \# 11 開發套件會強制將該 pIV 指向歸零的緩衝區。
+  [2] 當使用下列任一機制操作資料時，若資料緩衝區超過資料大小上限，該操作就會導致錯誤。對於這些機制，所有資料處理都必須在 HSM 內進行。如需每個機制的最大資料大小集資訊，請參閱 [每個機制的資料大小上限](#pkcs11-mech-max)。
+  [3] 廠商定義的機制。為了能使用 CloudHSM 廠商定義的機制，編譯期間 PKCS \#11 應用程式必須加入 `/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 \#5 填補。

  `CKM_CLOUDHSM_AES_KEY_WRAP_ZERO_PAD`：AES 金鑰包裝，零填補。

  `CKM_CLOUDHSM_ML_DSA_KEY_PAIR_GEN`：產生 ML-DSA 金鑰對。使用 `CKA_CLOUDHSM_PARAMETER_SET` 屬性 （類型 `CK_CLOUDHSM_ML_DSA_PARAMETER_SET_TYPE`) 指定參數集。有效值：`CKP_CLOUDHSM_ML_DSA_44`、`CKP_CLOUDHSM_ML_DSA_65`、`CKP_CLOUDHSM_ML_DSA_87`。

  `CKM_CLOUDHSM_ML_DSA`：Pure ML-DSA 簽署並驗證。使用 ML-DSA 金鑰對簽署或驗證原始資料。

  `CKM_CLOUDHSM_EXT_MU_ML_DSA`：ML-DSA 使用外部 mu 簽署和驗證。簽署或驗證已預先處理為外部 mu 值的資料。

  `CKM_CLOUDHSM_EDDSA`：EdDSA 簽署機制。使用 NULL 參數：PureEdDSA (Ed25519)，僅限單一部分，最多 16，000 個位元組。使用 `CK_EDDSA_PARAMS`(`phFlag = CK_TRUE`、`ulContextDataLen = 0`)：Ed25519ph，單一部分和分段，無大小限制。`CK_EDDSA_PARAMS` 結構遵循 [PKCS \#11 v3.0 規格。](https://docs.oasis-open.org/pkcs11/pkcs11-curr/v3.0/pkcs11-curr-v3.0.html)
+ [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\#11 應用程式必須在編譯`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】 僅支援非 FIPS 模式的 hsm2m.medium 執行個體。
+ 【8】 金鑰衍生函數 (KDFs) 是在 [NIST 特殊出版物 800-56A 修訂版 3](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-56Ar3.pdf) 中指定。