使用使用者介面建立根金鑰

建立服務實例之後，請完成下列步驟，以使用使用者介面來建立根金鑰。

如果您啟用 Hyper Protect Crypto Services 實例的雙重授權設定，請記住，您新增至服務的任何金鑰都需要兩個使用者的授權，才能刪除金鑰。

1. 登入使用者介面。

2. 移至 功能表 > 資源清單，以檢視資源清單。

3. 從 IBM Cloud 資源清單，選取已佈建的 Hyper Protect Crypto Services 實例。

4. 若要建立新的金鑰，請選取側邊功能表中的 KMS 金鑰 標籤。

5. 在「金鑰」表格中，按一下 新增金鑰，然後選取 建立金鑰。

   指定金鑰的詳細資料：

   表 1. 說明用來建立金鑰的設定

   設定	說明
   金鑰類型	您想要在 Hyper Protect Crypto Services 中管理的金鑰類型。 從金鑰類型清單中，選取 根金鑰。
   金鑰名稱	方便識別金鑰且人類可閱讀的唯一名稱。 長度必須在 2-90 個字元內。 若要保護您的隱私權，請確定金鑰名稱未包含個人識別資訊 (PII)（例如您的姓名或位置）。
   金鑰別名	(選用) 您要指派給金鑰的一或多個唯一、人類可讀的別名，以方便辨識。 別名大小可以是 2-90 個字元。 您可以為金鑰設定最多五個金鑰別名，每個別名以逗點區隔。 附註: 每一個別名都必須是英數、區分大小寫，且不能包含橫線 (-) 或底線 (_) 以外的空格或特殊字元。別名不能是第 4 版 UUID，且不能是 Hyper Protect Crypto Services 保留名稱: allowed_ip、key、keys、metadata、policy、policies、registration、registrations、ring、rings、rotate、wrap、unwrap、rewrap、version、versions。
   金鑰環 ID	從清單中選取包含現有金鑰環的金鑰環。 如果您未指派金鑰環，則會將金鑰新增至 default 金鑰環。 如需金鑰環的相關資訊，請參閱 管理金鑰環。
   到期日	(選用) 設定金鑰到期的日期和時間。 在到期日之後，金鑰會進入「已停用」狀態。 如需金鑰狀態的相關資訊，請參閱 監視加密金鑰的生命週期。
   說明	(選用) 新增金鑰的延伸說明。 其長度可以為 2 到 240 個字元。

6. 當您完成填寫金鑰的詳細資料時，請按一下 建立金鑰 以確認。

在服務中所建立的金鑰是 AES-CBC 演算法所支援的對稱 256 位元金鑰。 為了增加安全，金鑰由 FIPS 140-2 Level 4 認證的 硬體安全模組(HSM)A physical appliance that provides on-demand encryption, key management, and key storage as a managed service. 所產生，這些模組位於安全 IBM Cloud 資料中心。

使用 API 建立根金鑰

對下列端點發出 POST 呼叫來建立根金鑰。

https://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/api/v2/keys

1. 擷取服務及鑑別認證以在服務中使用金鑰。

2. 使用下列 curl 指令呼叫 Hyper Protect Crypto Services 金鑰管理服務 API。

   curl -X POST \
     "https://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/api/v2/keys" \
     -H "authorization: Bearer <IAM_token>" \
     -H "bluemix-instance: <instance_ID>" \
     -H "content-type: application/vnd.ibm.kms.key+json" \
     -H "x-kms-key-ring: <key_ring_ID>" \
     -H "correlation-id: <correlation_ID>" \
     -d '{
             "metadata": {
                 "collectionType": "application/vnd.ibm.kms.key+json",
                 "collectionTotal": 1
             },
             "resources": [
                 {
                     "type": "application/vnd.ibm.kms.key+json",
                      "name": "<key_name>",
                      "aliases": [alias_list],
                      "description": "<key_description>",
                      "expirationDate": "<YYYY-MM-DDTHH:MM:SS.SSZ>",
                      "extractable": <key_type>
                 }
             ]
         }'
   

   根據下表取代範例要求中的變數。

   表 2. 說明使用 API 新增根金鑰所需的變數

   變數	說明
   region	必要。 代表 Hyper Protect Crypto Services 服務實例所在地理區域的地區縮寫，例如 us-south 或 au-syd。 如需相關資訊，請參閱地區服務端點。
   port	必要。 API 端點的埠號。
   IAM_token	必要。 您的 IBM Cloud 存取記號。 請在 cURL 要求中包含 IAM 記號的完整內容，包括 Bearer 值。 如需相關資訊，請參閱 擷取存取記號。
   instance_ID	必要。 指派給您 Hyper Protect Crypto Services 服務實例的唯一 ID。 如需相關資訊，請參閱 擷取實例 ID。
   key_ring_ID	選用。 您要對其指派金鑰之目標金鑰環的唯一 ID。 如果未指定，則標頭會自動設為 default ，且金鑰屬於指定 Hyper Protect Crypto Services 實例中的預設金鑰環。 如需相關資訊，請參閱 管理金鑰環。
   correlation_ID	用來追蹤及關聯交易的唯一 ID。
   key_name	必要。 方便識別金鑰且人類可閱讀的唯一名稱。 重要事項: 若要保護您的隱私權，請不要將個人資料儲存為金鑰的 meta 資料。
   alias_list	選用。 指派給您金鑰的一或多個唯一且人類可讀的別名。 重要事項: 若要保護您的隱私權，請不要將個人資料儲存為金鑰的 meta 資料。 每一個別名都必須是英數、區分大小寫，且不能包含橫線 (-) 或底線 (_) 以外的空格或特殊字元。別名不能是第 4 版 UUID，且不能是 Hyper Protect Crypto Services 保留名稱: allowed_ip、key、keys、metadata、policy、policies、registration、registrations、ring、rings、rotate、wrap、unwrap、rewrap、version、versions。別名大小可以是 2-90 個字元 (內含)。
   key_description	選用項目：金鑰的延伸說明。 重要事項: 若要保護您的隱私權，請不要將個人資料儲存為金鑰的 meta 資料。
   YYYY-MM-DD HH:MM:SS.SS	選用項目：系統中的金鑰到期的日期和時間，以 RFC 3339 格式表示。 如果省略 expirationDate 屬性，則金鑰不會到期。
   key_type	決定金鑰資料是否可以離開服務的布林值。 當您將 extractable 屬性設為 false 時，服務會建立可用於 wrap 或 unwrap 作業的根金鑰。

   若要保護您個人資料的機密性，請在將金鑰新增至服務時避免輸入個人識別資訊 (PII)（例如您的姓名或位置）。 如需 PII 的其他範例，請參閱 NIST 特殊出版品 800-122的 2.2 小節。

   如果您在要求中設定 expirationDate，則金鑰會在金鑰到期日之後的 1 小時內移至取消啟動狀態。

   成功的 POST /v2/keys 回應會傳回您金鑰的 ID 值，以及其他 meta 資料。 ID 是指派給金鑰的唯一 ID，用於後續呼叫 Hyper Protect Crypto Services 金鑰管理服務 API。

   {
       "metadata": {
           "collectionType": "application/vnd.ibm.kms.key+json",
           "collectionTotal": 1
       },
       "resources": [
           {
               "type": "application/vnd.ibm.kms.key+json",
               "id": "02fd6835-6001-4482-a892-13bd2085f75d",
               "name": "test-root-key",
               "aliases": [
                   "alias-1",
                   "alias-2"
                 ],
               "description": "A test root key",
               "state": 1,
               "extractable": false,
               "crn": "crn:v1:bluemix:public:hs-crypto:us-south:a/f047b55a3362ac06afad8a3f2f5586ea:12e8c9c2-a162-472d-b7d6-8b9a86b815a6:key:02fd6835-6001-4482-a892-13bd2085f75d",
               "imported": false,
               "creationDate": "2020-03-12T03:37:32Z",
               "createdBy": "...",
               "algorithmType": "AES",
               "algorithmMetadata": {
                   "bitLength": "256",
                   "mode": "CBC_PAD"
               },
               "algorithmBitSize": 256,
               "algorithmMode": "CBC_PAD",
               "lastUpdateDate": "2020-03-12T03:37:32Z",
               "keyVersion": {
                   "id": "2291e4ae-a14c-4af9-88f0-27c0cb2739e2",
                   "creationDate": "2020-03-12T03:37:32Z"
               },
               "dualAuthDelete": {
                   "enabled": false
               },
               "deleted": false
           }
       ]
   }
   

   如需回應參數的詳細說明，請參閱 Hyper Protect Crypto Services REST API 參考資料文件。

3. 選用項目：執行下列呼叫來瀏覽 Hyper Protect Crypto Services 服務實例中的金鑰，確認已建立金鑰。

   curl -X GET \
     https://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/api/v2/keys \
     -H 'accept: application/vnd.ibm.collection+json' \
     -H 'authorization: Bearer <IAM_token>' \
     -H 'bluemix-instance: <instance_ID>' \
     -H 'correlation-id: <correlation_ID>' \
   

使用服務建立根金鑰之後，金鑰會停留在 Hyper Protect Crypto Services的範圍內，且無法擷取金鑰資料。