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

# 使用 AWS CloudHSM CloudHSM CLI 时启用法定身份验证的密钥管理和使用
<a name="key-quorum-auth-chsm-cli-crypto-user"></a>

为 AWS CloudHSM 集群配置法定身份验证后，如果加密用户的密钥具有关联的法定值，则他们无法自行执行 HSM 密钥管理或使用操作。本主题说明加密用户如何获取临时令牌来执行 HSM 密钥管理或密钥使用操作。

**注意**  
每个仲裁令牌对一个操作有效。该操作成功后，令牌将不再有效，加密用户必须获取新令牌。仲裁令牌仅在您当前登录会话期间有效。如果您登出 CloudHSM CLI 或者断开网络连接，则令牌将不再有效，您需要获取新令牌。您只能在 CloudHSM CLI 中使用 CloudHSM 令牌。您无法将其用于在其他应用程序中进行身份验证。

以下示例显示了配置仲裁身份验证后，加密用户尝试在 HSM 上使用仲裁关联密钥创建签名时的输出。该命令失败，并出现 `Quorum Failed` 错误，这表示仲裁身份验证失败：

```
aws-cloudhsm > crypto sign rsa-pkcs --key-filter attr.label=rsa-private-key-example --hash-function sha256 --data YWJjMTIz
{
  "error_code": 1,
  "data": "Quorum Failed"
}
```

加密用户必须完成以下任务才能获得用于在 HSM 上执行密钥管理或密钥使用操作的临时令牌：

**Topics**
+ [

## 步骤 1：获取仲裁令牌
](#key-quorum-admin-gen-token-chsm-cli)
+ [

## 步骤 2：获得批准加密用户的签名
](#key-quorum-crypto-user-get-approval-signatures-chsm-cli)
+ [

## 步骤 3：在 CloudHSM; 集群上批准令牌并执行操作
](#key-quorum-crypto-user-approve-token-chsm-cli)

## 步骤 1：获取仲裁令牌
<a name="key-quorum-admin-gen-token-chsm-cli"></a>

1. 启动 CloudHSM CLI。

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

   ```
   $ /opt/cloudhsm/bin/cloudhsm-cli interactive
   ```

------
#### [ Windows ]

   ```
   PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\cloudhsm-cli.exe" interactive
   ```

------

1. 以加密用户身份登录集群。

   ```
   aws-cloudhsm > login --username <crypto_user1> --role crypto-user --password password123
   ```

   此示例使用 `crypto-user` 角色将 `crypto_user1` 登录 CloudHSM CLI。将这些值替换为您自己的值。

   ```
   {
     "error_code": 0,
     "data": {
       "username": "crypto_user1",
       "role": "crypto-user"
     }
   }
   ```

1. 使用 **quorum token-sign generate** 命令生成仲裁令牌。

   在以下命令中，`key-usage` 标识您将在其中使用所生成之令牌的*服务名称*。在这种情况下，令牌用于密钥使用操作（`key-usage` 服务）。此示例使用 `--filter` 标志将令牌与特定密钥相关联。

   ```
   aws-cloudhsm > quorum token-sign generate --service key-usage --token </path/crypto_user1.token> --filter attr.label=rsa-private-key-example
   {
     "error_code": 0,
     "data": {
       "path": "/home/crypto_user1.token"
     }
   }
   ```

   此示例将为用户名为 `crypto_user1` 的加密用户获取一个仲裁令牌，并将该令牌保存到一个名为 `crypto_user1.token` 的文件中。要使用示例命令，可将这些值替换为您自己的值：

   **quorum token-sign generate** 命令在指定的文件路径上生成密钥使用服务仲裁令牌。可以查看以下令牌文件：

   ```
   $ cat </path/crypto_user1.token>
   {
     "version": "2.0",
     "service": "key-usage",
     "key_reference": "0x0000000000680006",
     "approval_data": "AAIABQAAABkAAAAAAGgABi5CDa9x9VyyRIaFbkSrHgJjcnlwdG9fdXNlcgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABnPQBLAAAAAAAAAAAAAgAFAAAAGgAAAAAAaAAGQvd2qKY+GJj8gXo9lKuANGNyeXB0b191c2VyAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAGc9AEsAAAAAAAAAAA==",
     "token": "5GlgoWOlQU4fw4QIlbxkPGZVOVoDugFGuSKE/k67ncM=",
     "signatures": []
   }
   ```

   令牌路径包含以下内容：
   + **service**：与令牌关联的仲裁服务的标识符。
   + **key\$1reference**：与此仲裁令牌关联的密钥的标识符。
   + **approval\$1data**：由 HSM 生成的 base64 编码原始数据令牌。
   + **令牌**：approval\$1data 的 base64 编码和 SHA-256 哈希令牌
   + **signatures**：未签名令牌的 base64 编码签名令牌（签名）的数组。每个批准者签名都采用 JSON 对象文字的形式：

     ```
     {
           "username": "<APPROVER_USERNAME>",
           "role": "<APPROVER_ROLE>",
           "signature": "<APPROVER_RSA2048_BIT_SIGNATURE>"
     }
     ```

     每个签名均由批准者使用相应的 RSA 2048 位私有密钥创建，其公有密钥通过 HSM 注册。

1. 验证新的用户服务仲裁令牌。**quorum token-sign list** 命令确认该令牌存在于 CloudHSM 上。

   ```
   aws-cloudhsm > quorum token-sign list
   {
     "error_code": 0,
     "data": {
       "tokens": [
         {
           "username": "crypto_user",
           "service": "key-usage",
           "key-reference": "0x0000000000680006",
           "minimum-token-count": 2
         }
       ]
     }
   }
   ```

   `minimum-token-count` 显示了从集群中单个 HSM 检索到的与用户名、服务和密钥引用相对应的最小可用密钥令牌数量的聚合集群视图。

   例如，假设一个 2-HSM 集群，如果我们从集群中的第一个 HSM 接收到由用户 `crypto_user1` 为引用为 `0x0000000000680006` 的密钥生成的两（2）个密钥使用令牌，并且我们从集群中的另一个 HSM 接收到由用户 `crypto_user1` 为引用为 `0x0000000000680006` 的密钥生成的一（1）个密钥使用令牌，我们将显示 `"minimum-token-count": 1`。

## 步骤 2：获得批准加密用户的签名
<a name="key-quorum-crypto-user-get-approval-signatures-chsm-cli"></a>

具有仲裁令牌的加密用户必须获得其他加密用户批准的令牌。为了提供其批准，其他加密用户使用其签名密钥以加密方式对 HSM 外的令牌进行签名。

可通过多种不同方式对令牌进行签名。以下示例显示了如何使用 [OpenSSL](https://www.openssl.org/) 对令牌进行签名。要使用其他签名工具，请确保该工具使用加密用户的私有密钥（签名密钥）对令牌的 SHA-256 摘要进行签名。

在此示例中，具有令牌（`crypto-user`）的加密用户至少需要两（2）次批准。以下示例命令显示两（2）个加密用户如何使用 OpenSSL 以加密方式对令牌进行签名。

1. 解码 base64 编码的未签名令牌，并将其放入二进制文件：

   ```
   $echo -n '5GlgoWOlQU4fw4QIlbxkPGZVOVoDugFGuSKE/k67ncM=' | base64 -d > crypto_user1.bin
   ```

1. 使用 OpenSSL 和批准者的私有密钥为未签名的二进制仲裁令牌签名，以获取用户服务和创建二进制签名文件：

   ```
   $openssl pkeyutl -sign \
   -inkey crypto_user1.key \
   -pkeyopt digest:sha256 \
   -keyform PEM \
   -in crypto_user1.bin \
   -out crypto_user1.sig.bin
   ```

1. 将二进制签名编码为 base64：

   ```
   $ base64 -w0 crypto_user1.sig.bin > crypto_user1.sig.b64
   ```

1. 按此前批准者签名指定的 JSON 对象文字格式，将 base64 编码签名复制并粘贴至令牌文件。

   ```
   {
     "version": "2.0",
     "service": "key-usage",
     "key_reference": "0x0000000000680006",
     "approval_data": "AAIABQAAABkAAAAAAGgABi5CDa9x9VyyRIaFbkSrHgJjcnlwdG9fdXNlcgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABnPQBLAAAAAAAAAAAAAgAFAAAAGgAAAAAAaAAGQvd2qKY+GJj8gXo9lKuANGNyeXB0b191c2VyAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAGc9AEsAAAAAAAAAAA==",
     "token": "5GlgoWOlQU4fw4QIlbxkPGZVOVoDugFGuSKE/k67ncM=",
     "signatures": [
       {
         "username": "crypto_user1",
         "role": "crypto-user",
         "signature": "wa7aPzmGwBjcEoZ6jAzYASp841AfgOvcI27Y/tGlCj1E9DawnFw5Uf0IJT2Ca7T5XD2ThVkUi0B+dhAomdqYNl6aUUFrJyH9GBJ+E0PmA5jNVm25tzeRWBJzneTg4/zTeE2reNqrHFHicWnttQLe9jS09J1znuDGWDe0HaBKWUaz2gUInJRqmeXDsZYdSvZksrqUH5dci/RsaDE2+tGiS9g0RcIkFbsPW4HpGe2e5HVzGsqrV8O3PKlYQv6+fymfcNTTuoxKcHAkOjpl43QSuSIu2gVq7KI8mSmmWaPJL47NPjmcBVB5vdEQU+oiukaNfLJr+MoDKzAvCGDg4cDArg=="
       },
       {
         "username": "crypto_user2",
         "role": "crypto-user",
         "signature": "wa7aPzmGwBjcEoZ6jAzYASp841AfgOvcI27Y/tGlCj1E9DawnFw5Uf0IJT2Ca7T5XD2ThVkUi0B+dhAomdqYNl6aUUFrJyH9GBJ+E0PmA5jNVm25tzeRWBJzneTg4/zTeE2reNqrHFHicWnttQLe9jS09J1znuDGWDe0HaBKWUaz2gUInJRqmeXDsZYdSvZksrqUH5dci/RsaDE2+tGiS9g0RcIkFbsPW4HpGe2e5HVzGsqrV8O3PKlYQv6+fymfcNTTuoxKcHAkOjpl43QSuSIu2gVq7KI8mSmmWaPJL47NPjmcBVB5vdEQU+oiukaNfLJr+MoDKzAvCGDg4cDArg=="
       }
     ]
   }
   ```

## 步骤 3：在 CloudHSM; 集群上批准令牌并执行操作
<a name="key-quorum-crypto-user-approve-token-chsm-cli"></a>

在加密用户获得必要的批准和签名后，他们可以将该令牌以及密钥管理或密钥使用操作提供给 CloudHSM 集群。

确保密钥操作对应于与仲裁令牌关联的相应仲裁服务。有关更多信息，请参阅 [支持的服务和类型](key-quorum-auth-chsm-cli-service-names.md) 了解更多信息。

在交易过程中，令牌将在 AWS CloudHSM 集群内获得批准并执行所请求的密钥操作。密钥操作的成功取决于已批准的仲裁令牌和密钥操作是否有效。

**Example 使用 RSA-PKCS 机制生成签名**  
在以下示例中，已登录加密用户将使用 HSM 上的密钥创建一个签名：  

```
aws-cloudhsm > crypto sign rsa-pkcs --key-filter attr.label=rsa-private-key-example --hash-function sha256 --data YWJjMTIz --approval /path/crypto_user1.token
      
{
  "error_code": 0,
  "data": {
    "key-reference": "0x0000000000640007",
    "signature": "h6hMqXacBrT3x3MXV13RXHdQno0+IQ6iy0kVrGzo23+eoWT0ZZgrSpBCu5KcuP6IYYHw9goQ5CfPf4jI1nO5m/IUJtF1A1lmcz0HjEy1CJ7ICXNReDRyeOU8m43dkJzt0OUdkbtkDJGAcxkbKHLZ02uWsGXaQ8bOKhoGwsRAHHF6nldTXquICfOHgSd4nimObKTqzUkghhJW5Ot5oUyLMYP+pZmUS38ythybney94Wj6fzYOER8v7VIY5ijQGa3LfxrjSG4aw6QijEEbno5LSf18ahEaVKmVEnDBL54tylCJBGvGsYSY9HNhuJoHPgiDL/TDd2wfvP4PaxbFRyyHaw=="
  }
}
```
如果加密用户尝试使用相同的令牌执行另一个 HSM 密钥使用操作，则操作将失败：  

```
aws-cloudhsm > crypto sign rsa-pkcs --key-filter attr.label=rsa-private-key-example --hash-function sha256 --data YWJjMTIz --approval /home/crypto_user1.token
{
  "error_code": 1,
  "data": "Quorum approval is required for this operation"
}
```
要执行其他 HSM 密钥操作，加密用户必须生成新的仲裁令牌，从批准者处获取新签名，然后使用 --approver 参数执行所需的密钥操作，以提供仲裁令牌。  
使用 **quorum token-sign list** 检查是否有可用的令牌。此示例显示加密用户没有已批准的令牌。  

```
aws-cloudhsm > quorum token-sign list
{
  "error_code": 0,
  "data": {
    "tokens": []
  }
}
```