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

# 啟用規定人數身分驗證以 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": []
   }
   ```

   權杖檔案由以下項目組成：
   + **服務**：權杖相關聯的規定人數服務識別符。
   + **key\$1reference**：與此規定人數字符相關聯的金鑰識別符。
   + **approval\$1data**：由 HSM 產生的 base64 編碼原始資料權杖。
   + **token**：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 叢集，如果我們從叢集中`0x0000000000680006`的第一個 HSM 參考收到使用者`crypto_user1`為金鑰產生的兩 (2) 個金鑰用量權杖，並且收到使用者`crypto_user1`為金鑰產生的一 (1) 個金鑰用量權杖，`0x0000000000680006`並參考叢集中的另一個 HSM，則會顯示 `"minimum-token-count": 1`。

## 步驟 2. 從核准加密使用者取得簽章
<a name="key-quorum-crypto-user-get-approval-signatures-chsm-cli"></a>

具有規定人數字符的加密使用者必須取得其他加密使用者核准的字符。為了提供核准，其他加密 =-users 會使用其簽署金鑰，在 HSM 外部以密碼編譯方式簽署字符。

簽署權杖的方式有很多。下列範例示範如何使用 [OpenSSL](https://www.openssl.org/) 簽署權杖。若要使用不同的簽署工具，請確定工具使用 crypto-user 的私有金鑰 （簽署金鑰） 來簽署字符的 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 機制產生簽章**  
在下列範例中，登入的 crypto-user 會在 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 金鑰操作，加密使用者必須產生新的規定人數字符、從核准者取得新的簽章，並使用 -- 核准引數執行所需的金鑰操作，以提供規定人數字符。  
使用 **quorum token-sign list**來檢查可用的字符。此範例顯示 crypto-user 沒有核准的字符。  

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