

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# PKCS \$111 适用于 AWS CloudHSM 客户端 SDK 的库 3
<a name="pkcs11-v3-library"></a>

PKCS \$111 是在 AWS CloudHSM中对硬件安全模块（HSM）执行加密操作的标准。

有关引导的信息，请参阅 [连接到集群](cluster-connect.md)。

**Topics**
+ [安装 PKCS \$111 库](install-pkcs11-v3.md)
+ [对 PKCS \$111 库进行身份验证](pkcs11-v3-pin.md)
+ [密钥类型](pkcs11-v3-key-types.md)
+ [机制](pkcs11-v3-mechanisms.md)
+ [API 操作](pkcs11-v3-apis.md)
+ [密钥属性](pkcs11-v3-attributes.md)
+ [代码示例](pkcs11-v3-samples.md)

# 为 AWS CloudHSM 客户端 SDK 3 安装 PKCS \$111 库
<a name="install-pkcs11-v3"></a>

本主题提供安装 AWS CloudHSM 客户端 SDK 3 版本系列的 PKCS \$111 库的说明。有关客户端软件开发工具包 或 PKCS \$111 库的更多信息，请参阅[使用客户端软件开发工具包](use-hsm.md) 和 [PKCS \$111 库](pkcs11-library.md)。

## 客户端软件开发工具包 3 的先决条件
<a name="pkcs11-library-prerequisites"></a>

PKCS \$111 库需要 AWS CloudHSM 客户端。

如果您尚未安装和配置 AWS CloudHSM 客户端，请立即按照中的步骤进行操作[安装客户端 (Linux)](cmu-install-and-configure-client-linux.md)。在您安装和配置客户端之后，可以使用以下命令来启动客户端。

------
#### [ Amazon Linux ]

```
$ sudo start cloudhsm-client
```

------
#### [ Amazon Linux 2 ]

```
$ sudo systemctl start cloudhsm-client
```

------
#### [ CentOS 7 ]

```
$ sudo systemctl start cloudhsm-client
```

------
#### [ CentOS 8 ]

```
$ sudo systemctl start cloudhsm-client
```

------
#### [ RHEL 7 ]

```
$ sudo systemctl start cloudhsm-client
```

------
#### [ RHEL 8 ]

```
$ sudo systemctl start cloudhsm-client
```

------
#### [ Ubuntu 16.04 LTS ]

```
$ sudo systemctl start cloudhsm-client
```

------
#### [ Ubuntu 18.04 LTS ]

```
$ sudo systemctl start cloudhsm-client
```

------
#### [ Ubuntu 20.04 LTS ]

```
$ sudo systemctl start cloudhsm-client
```

------

## 安装适用于客户端软件开发工具包 3 的 PKCS \$111 库
<a name="install-pkcs11-library"></a>

以下命令将下载并安装 PKCS \$111 库。

------
#### [ Amazon Linux ]

```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL6/cloudhsm-client-pkcs11-latest.el6.x86_64.rpm
```

```
$ sudo yum install ./cloudhsm-client-pkcs11-latest.el6.x86_64.rpm
```

------
#### [ Amazon Linux 2 ]

```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-client-pkcs11-latest.el7.x86_64.rpm
```

```
$ sudo yum install ./cloudhsm-client-pkcs11-latest.el7.x86_64.rpm
```

------
#### [ CentOS 7 ]

```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-client-pkcs11-latest.el7.x86_64.rpm
```

```
$ sudo yum install ./cloudhsm-client-pkcs11-latest.el7.x86_64.rpm
```

------
#### [ CentOS 8 ]

```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-client-pkcs11-latest.el8.x86_64.rpm
```

```
$ sudo yum install ./cloudhsm-client-pkcs11-latest.el8.x86_64.rpm
```

------
#### [ RHEL 7 ]

```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-client-pkcs11-latest.el7.x86_64.rpm
```

```
$ sudo yum install ./cloudhsm-client-pkcs11-latest.el7.x86_64.rpm
```

------
#### [ RHEL 8 ]

```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-client-pkcs11-latest.el8.x86_64.rpm
```

```
$ sudo yum install ./cloudhsm-client-pkcs11-latest.el8.x86_64.rpm
```

------
#### [ Ubuntu 16.04 LTS ]

```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Xenial/cloudhsm-client-pkcs11_latest_amd64.deb
```

```
$ sudo apt install ./cloudhsm-client-pkcs11_latest_amd64.deb
```

------
#### [ Ubuntu 18.04 LTS ]

```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Bionic/cloudhsm-client-pkcs11_latest_u18.04_amd64.deb
```

```
$ sudo apt install ./cloudhsm-client-pkcs11_latest_u18.04_amd64.deb
```

------
+ 如果您所安装的 PKCS \$111 库的 EC2 实例未安装客户端软件开发工具包 3 中的其他组件，则必须引导客户端软件开发工具包 3。您只需使用客户端软件开发工具包 3 中的组件在每个实例上执行一次此操作。
+ 您可在以下位置找到 PKCS \$111 库的文件：

  Linux 二进制文件、配置脚本、证书和日志文件：

  ```
  /opt/cloudhsm/lib
  ```

# 向 AWS CloudHSM 客户端 SDK 3 的 PKCS \$111 库进行身份验证
<a name="pkcs11-v3-pin"></a>

当您使用 PKCS \$111 库时，您的应用程序将在您的 HSMs 中以特定的[加密用户 (CU)](manage-hsm-users.md) 的身份运行。 AWS CloudHSM您的应用程序只能查看和管理 CU 拥有和共享的密钥。您可以使用现有的 CU HSMs 或创建新的 CU。有关管理的信息 CUs，请参阅使用 Cloud [HSM CLI 管理 HSM 用户和使用 CloudHSM](manage-hsm-users-chsm-cli.md) [管理实用程序 (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，pin 参数采用以下格式：

```
<CU_user_name>:<password>
```

例如，以下命令会将 PKCS \$111 库 PIN 设置为用户名为 `CryptoUser`、密码为 `CUPassword123!` 的 CU。

```
CryptoUser:CUPassword123!
```

# AWS CloudHSM 客户端 SDK 3 的 PKCS \$111 库支持的密钥类型
<a name="pkcs11-v3-key-types"></a>

PKCS \$111 库通过 AWS CloudHSM 客户端 SDK 3 支持以下密钥类型。


****  

| 密钥类型 | 说明 | 
| --- | --- | 
| RSA | 生成 2048 位到 4096 位的 RSA 密钥，增量为 256 位。 | 
| EC | 通过 secp224r1 (P-224)、secp256r1 (P-256)、secp256k1（区块链）、secp384r1 (P-384) 和 secp521r1 (P-521) 曲线生成密钥。 | 
| AES | 生成 128 位、192 位和 256 位 AES 密钥。 | 
| DES3 （三重 DES） | 生成 192 位密钥 DES3 。有关即将发生的更改，请参阅下面的注释 [1](#pkcs11-v3-key-note)。 | 
| GENERIC\$1SECRET | 生成 1 到 64 字节的常规密钥。 | 
+ [1] 根据 NIST 指导，2023 年以后处于 FIPS 模式的集群不允许这样做。对于处于非 FIPS 模式的集群，2023 年之后仍然允许。有关详细信息，请参阅 [FIPS 140 合规：2024 年机制弃用](compliance-dep-notif.md#compliance-dep-notif-1)。

# AWS CloudHSM 客户端 SDK 3 支持的机制
<a name="pkcs11-v3-mechanisms"></a>

PKCS \$111 库支持 AWS CloudHSM 客户端 SDK 3 的以下算法：
+ **加密和解密** — AES-CBC、AES-CTR、AES-ECB、AES-GCM、-CBC、-ECB、RSA-OAEP 和 RSA-PKCS DES3 DES3
+ **签名和验证** - RSA、HMAC 和 ECDSA；带和不带哈希
+ **哈希/摘要** — SHA1、 SHA224、 SHA256、和 SHA384 SHA512
+ **密钥包装** - AES 密钥包装、[4](#pkcs11-v3-mech4)AES-GCM、RSA-AES 和 RSA-OAEP
+ **密钥推导** — ECDH，[5](#pkcs11-v3-mech5) SP800-108 CTR KDF

## PKCS \$111 库机制函数表
<a name="pkcs11-v3-mech-function"></a>

PKCS \$111 库符合 2.40 版 PKCS \$111 规格。要使用 PKCS＃11 调用加密功能，请使用给定机制调用函数。下表汇总了 AWS CloudHSM支持的函数和机制的组合。

**解释支持的 PKCS \$111 机制函数表**  
✔ 标记表示 AWS CloudHSM 支持该功能的机制。我们不支持 PKCS \$111 规范中列出的所有可能的函数。✖ 标记表示尚 AWS CloudHSM 不支持给定函数的机制，即使 PKCS \$111 标准允许。空单元格表示 PKCS \$111 标准不支持给定函数的机制。


**支持的 PKCS \$111 库机制和函数**  
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/cloudhsm/latest/userguide/pkcs11-v3-mechanisms.html)

**机制注释**
+ [1] 仅限单部分操作。
+ [2] 机制的功能与 `p` 机制相同，但为生成 `CKM_RSA_PKCS_KEY_PAIR_GEN` 和 `q` 提供了更强有力的保证。
+ [3.1] 根据客户端 SDK，哈希 AWS CloudHSM 处理方法有所不同。对于客户端软件开发工具包 3，我们的哈希处理时机取决于数据大小以及您所用的是单个还是多个操作。

  **客户端软件开发工具包 3 中的单部分操作**

  表 3.1 列出了客户端软件开发工具包 3 的每种机制的最大数据集大小。整个哈希值均在 HSM 内部计算。不支持 16KB 以上的数据。  
**表 3.1：单部分操作的最大数据集大小**    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/cloudhsm/latest/userguide/pkcs11-v3-mechanisms.html)

  **多部分操作客户端软件开发工具包 3**

  支持 16KB 以上的数据，但是数据大小决定了哈希发生的位置。小于 16KB 的数据缓冲区在 HSM 内部进行哈希处理。对于系统中的 16KB 和最大数据大小之间的缓冲区，在软件中进行本地哈希处理。*请切记*：哈希函数不需要加密，因此您可以在 HSM 之外安全计算。
+ [3.2] 基于客户端 SDK 的哈希 AWS CloudHSM 方法有所不同。对于客户端软件开发工具包 3，我们的哈希处理时机取决于数据大小以及您所用的是单个还是多个操作。

  **单部分操作客户端软件开发工具包 3**

  表 3.2 列出了客户端软件开发工具包 3 的每种机制的最大数据集大小。不支持 16KB 以上的数据。  
**表 3.2：单部分操作的最大数据集大小**    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/cloudhsm/latest/userguide/pkcs11-v3-mechanisms.html)

  **多部分操作客户端软件开发工具包 3**

  支持 16KB 以上的数据，但是数据大小决定了哈希发生的位置。小于 16KB 的数据缓冲区在 HSM 内部进行哈希处理。对于系统中的 16KB 和最大数据大小之间的缓冲区，在软件中进行本地哈希处理。*请切记*：哈希函数不需要加密，因此您可以在 HSM 之外安全计算。
+ [3.3] 使用以下任何机制对数据进行操作时，如果数据缓冲区超出最大数据大小，则操作会导致错误。对此机制，所有数据处理均应在 HSM 内发生。下表列出了为每个机制设置的最大数据大小：  
**表 3.3：最大数据集大小**    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/cloudhsm/latest/userguide/pkcs11-v3-mechanisms.html)
+ [4] 在执行 AES-GCM 加密时，HSM 不会接受应用程序中的初始化向量 (IV) 数据。您必须使用其生成的 IV。HSM 提供的 12 字节 IV 将写入您提供的 `CK_GCM_PARAMS` 参数结构的 pIV 元素所指向的内存参考。为了防止用户混淆，版本 1.1.1 及更高版本中的 PKCS \$111 开发工具包将在初始化 AES-GCM 加密时确保该 pIV 指向已清零的缓冲区。
+ [5] **仅客户端软件开发工具包 3**。机制的实施旨在支持 SSL/TLS 卸载案例，只能在 HSM 内部分执行。使用此机制之前，请参阅 [PKCS \$111 库的已知问题 AWS CloudHSMPKCS\$111 库的已知问题](ki-pkcs11-sdk.md) 中的“问题：ECDH 密钥派生只能在 HSM 内部分执行”。`CKM_ECDH1_DERIVE` 不支持 secp521r1 (P-521) 曲线。
+ [6] 以下 `CK_MECHANISM_TYPE` 和 `CK_RSA_PKCS_MGF_TYPE` 出于 `CKM_RSA_PKCS_OAEP` 作为 `CK_RSA_PKCS_OAEP_PARAMS` 受到支持：
  + 使用 `CKG_MGF1_SHA1` 的 `CKM_SHA_1`
  + 使用 `CKG_MGF1_SHA224` 的 `CKM_SHA224`
  + 使用 `CKG_MGF1_SHA256` 的 `CKM_SHA256`
  + 使用 `CKM_MGF1_SHA384` 的 `CKM_SHA384`
  + 使用 `CKM_MGF1_SHA512` 的 `CKM_SHA512`
+ [7.1] 供应商定义的机制。为了使用 CloudHSM 供应商定义的机制，PKCS \$111 应用程序必须在编译过程中包含 `/opt/cloudhsm/include/pkcs11/cloudhsm_pkcs11_vendor_defs.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`：带 PKCS \$15 填充的 AES 密钥包装

  `CKM_CLOUDHSM_AES_KEY_WRAP_ZERO_PAD`：零填充的 AES 密钥包装

  有关其他 AES 密钥包装的其他信息，请参阅 [AES 密钥包装](manage-aes-key-wrapping.md)。
+ [8] 根据 NIST 指导，2023 年以后处于 FIPS 模式的集群不允许这样做。对于处于非 FIPS 模式的集群，2023 年之后仍然允许。有关详细信息，请参阅 [FIPS 140 合规：2024 年机制弃用](compliance-dep-notif.md#compliance-dep-notif-1)。

# AWS CloudHSM 客户端 SDK 支持的 API 操作 3
<a name="pkcs11-v3-apis"></a>

PKCS \$111 库支持 AWS CloudHSM 客户端 SDK 3 的以下 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_SignRecover`（仅支持客户端软件开发工具包 3）
+ `C_SignRecoverInit`（仅支持客户端软件开发工具包 3）
+ `C_SignUpdate`
+ `C_UnWrapKey`
+ `C_Verify`
+ `C_VerifyFinal`
+ `C_VerifyInit`
+ `C_VerifyRecover`（仅支持客户端软件开发工具包 3）
+ `C_VerifyRecoverInit`（仅支持客户端软件开发工具包 3）
+ `C_VerifyUpdate`
+ `C_WrapKey`

# AWS CloudHSM 客户端 SDK 3 的 PKCS \$111 库中的关键属性
<a name="pkcs11-v3-attributes"></a>

密钥对象可以是公有、私有或秘密密钥。通过属性指定密钥对象上允许的操作。属性是在创建密钥对象时定义的。当您使用 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)样例。

以下主题提供了有关客户端 SDK 3 AWS CloudHSM 关键属性的更多信息。

**Topics**
+ [属性表](pkcs11-v3-attributes-interpreting.md)
+ [修改属性](pkcs11-v3-modify-attr.md)
+ [解释 AWS CloudHSM 客户端 SDK 3 的 PKCS \$111 库错误代码](pkcs11-v3-attr-errors.md)

# PKCS \$111 AWS CloudHSM 客户端 SDK 3 的库属性表
<a name="pkcs11-v3-attributes-interpreting"></a>

 AWS CloudHSM 客户端 SDK 3 的 PKCS \$111 库表包含因密钥类型而异的属性列表。它表示在使用特定加密函数时，特定密钥类型是否支持给定属性。 AWS CloudHSM

**图例：**
+ ✔ 表示 CloudHSM 对特定密钥类型支持此属性。
+ ✖ 表示 CloudHSM 对特定密钥类型不支持此属性。
+ R 表示特定密钥类型的属性值设置为只读的。
+ S 表示无法通过 `GetAttributeValue` 读取该属性，因为它是敏感属性。
+ 默认值列中的空单元格表示没有给该属性分配特定的默认值。

## GenerateKeyPair
<a name="pkcs11-v3-generatekeypair"></a>

[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/cloudhsm/latest/userguide/pkcs11-v3-attributes-interpreting.html)

## GenerateKey
<a name="pkcs11-v3-generatekey"></a>

[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/cloudhsm/latest/userguide/pkcs11-v3-attributes-interpreting.html)

## CreateObject
<a name="pkcs11-v3-createobject"></a>

[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/cloudhsm/latest/userguide/pkcs11-v3-attributes-interpreting.html)

## UnwrapKey
<a name="pkcs11-v3-unwrapkey"></a>

[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/cloudhsm/latest/userguide/pkcs11-v3-attributes-interpreting.html)

## DeriveKey
<a name="pkcs11-v3-derivekey"></a>

[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/cloudhsm/latest/userguide/pkcs11-v3-attributes-interpreting.html)

## GetAttributeValue
<a name="pkcs11-v3-getattributevalue"></a>

[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/cloudhsm/latest/userguide/pkcs11-v3-attributes-interpreting.html)

**属性注释**
+ [1] 此属性由固件部分支持且必须明确地仅设置为默认值。
+ [2] 必需属性。
+ [3] **仅客户端软件开发工具包 3**。`CKA_SIGN_RECOVER` 属性派生自 `CKA_SIGN` 属性。如果要设置它，只能将其设置为与为 `CKA_SIGN` 设置的值相同。如果不设置，它获得默认值 `CKA_SIGN`。由于 CloudHSM 仅支持基于 RSA 的可恢复签名机制，此属性目前仅适用于 RSA 公有密钥。
+ [4] **仅客户端软件开发工具包 3**。`CKA_VERIFY_RECOVER` 属性派生自 `CKA_VERIFY` 属性。如果要设置它，只能将其设置为与为 `CKA_VERIFY` 设置的值相同。如果不设置，它获得默认值 `CKA_VERIFY`。由于 CloudHSM 仅支持基于 RSA 的可恢复签名机制，此属性目前仅适用于 RSA 公有密钥。

# 修改 AWS CloudHSM 客户端 SDK 3 的 PKCS \$111 库属性
<a name="pkcs11-v3-modify-attr"></a>

对象的一些属性可以在对象创建后修改，有一些则不能。若要修改属性，请使用 cloudhsm\$1mgmt\$1util [中的 setAttribute](cloudhsm_mgmt_util-setAttribute.md) 命令。您还可通过 cloudhsm\$1mgmt\$1util 中的 [listAttribute](cloudhsm_mgmt_util-listAttributes.md) 命令派生出属性列表和代表这些属性的常量。

以下列表显示了对象创建后允许修改的属性：
+ `CKA_LABEL`
+ `CKA_TOKEN`
**注意**  
修改仅允许将会话密钥更改为令牌密钥。使用 key\$1mgmt\$1util 中的 [setAttribute](key_mgmt_util-setAttribute.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 3 的 PKCS \$111 库错误代码
<a name="pkcs11-v3-attr-errors"></a>

在模板中指定特定密钥不支持的 PKCS \$111 库属性会导致错误。下表包含当您违反规范时生成的错误代码：

[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/cloudhsm/latest/userguide/pkcs11-v3-attr-errors.html)

# 适用于 AWS CloudHSM 客户端 SDK 3 的 PKCS \$111 库的代码示例
<a name="pkcs11-v3-samples"></a>

上的代码示例 GitHub 向您展示了如何使用 PKCS \$111 库完成基本任务。 AWS CloudHSM

## 示例代码先决条件
<a name="pkcs11-v3-samples-prereqs"></a>

在运行示例之前，请执行以下步骤以设置您的环境：
+ 为客户端软件开发工具包 3 安装和配置 [PKCS \$111 库](install-pkcs11-v3.md)。
+ 设置[加密用户 (CU)](manage-hsm-users.md)。您的应用程序使用此 HSM 账户在 HSM 运行代码示例。

## 代码示例
<a name="pkcs11-v3-samples-code"></a>

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)
+ [使用 AES 对密钥进行包装和解开包装（使用 PKCS \$15 填充）](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)