目標

本指導教學將逐步引導您建立加密金鑰並安全地將其匯入至 Hyper Protect Crypto Services 服務。 它適用於 Hyper Protect Crypto Services的金鑰管理功能新手，但可能熟悉金鑰管理系統的使用者。 下列步驟需要大約 20 分鐘才能完成。

• 設定金鑰管理服務 API
• 準備 Hyper Protect Crypto Services 服務實例以開始匯入金鑰
• 使用 OpenSSL 加密法工具箱來建立及加密金鑰
• 將加密金鑰匯入至 Hyper Protect Crypto Services 服務實例

本指導教學不會對您的 IBM Cloud 帳戶產生任何費用。

作業流程

下列流程圖提供如何建立及匯入加密金鑰的概觀。 您可以按一下圖表上的每一個步驟，以檢視步驟的詳細資料。

開始之前

若要開始使用，您需要 IBM Cloud CLI，以便與您在 IBM Cloud上佈建的服務互動。 您也需要在工作站本端安裝 openssl 及 jq 套件。

1. 建立 IBM Cloud 帳戶。

2. 下載並安裝適用於您作業系統的 IBM Cloud CLI。

3. 下載並安裝 IBM Key Protect CLI 外掛程式 v0.6.3 或更新版本，並 配置它以在 Hyper Protect Crypto Services 中使用。 請務必將 KP_PRIVATE_ADDR 變數更新為現行實例金鑰管理端點 URL。

   若要檢查 IBM Key Protect CLI 外掛程式版本，請執行下列動作:

   ibmcloud plugin show key-protect
   

   若要將 IBM Key Protect CLI 外掛程式更新為最新版本，請執行下列動作:

   ibmcloud plugin update key-protect -r 'IBM Cloud'
   

4. 下載並安裝 OpenSSL 加密法程式庫。

   如果您第一次嘗試 Hyper Protect Crypto Services，則可以使用 openssl 指令在本端工作站上建立加密金鑰。 本指導教學需要 OpenSSL 1.0.2r 版或更新版本。

   如果您使用 Mac，則可以使用 Homebrew來快速開始進行 OpenSSL。 如果您是第一次安裝套件，請執行 brew install openssl，或執行 brew upgrade openssl 以將現有套件升級至最新版本。

5. 下載並安裝 jq。

   jq 可協助您截塊 JSON 資料。 在本指導教學中，您將使用 jq 來抓取並使用呼叫 Hyper Protect Crypto Services 金鑰管理服務 API 時所傳回的特定資料。

6. 建立 Hyper Protect Crypto Services 服務實例。

7. 起始設定 Hyper Protect Crypto Services 服務實例。

8. 設定 Hyper Protect Crypto Services 金鑰管理服務 API。

建立匯入記號

使用服務認證，您可以開始與金鑰管理服務 API 互動，以建立加密金鑰並將其帶至服務。

在下列步驟中，您將為 Hyper Protect Crypto Services 服務實例建立 匯入記號。 透過根據您指定的原則建立匯入記號，您可以在加密金鑰進入服務時啟用加密金鑰的額外安全。

1. 從指令行，切換至新的 hs-crypto-test 目錄。

   mkdir hs-crypto-test && cd hs-crypto-test
   

   您將使用此目錄來儲存您將在後續步驟中建立的檔案。

2. 您可以使用 金鑰管理服務 API 或使用 CLI 來建立 Hyper Protect Crypto Services 服務實例的匯入記號，然後將回應儲存至 JSON 檔案。

   • 使用 API

     curl -X POST $HPCS_API_URL/api/v2/import_token \
         -H "Accept: application/vnd.ibm.collection+json" \
         -H "Authorization: $ACCESS_TOKEN" \
         -H "Content-Type: application/json" \
         -H "Bluemix-Instance: $INSTANCE_ID" \
         -d '{
             "expiration": 1200,
             "maxAllowedRetrievals": 1
           }' > createImportTokenResponse.json
     

     在要求內文中，您可以指定匯入記號的原則，以根據時間及使用量計數來限制使用。 在此範例中，您將匯入記號的有效期限設為 1200 秒 (20 分鐘)，而且您也只容許在有效期限內一次擷取該記號。

   • 使用 IBM Key Protect CLI

     ibmcloud kp import-token create --instance-id $INSTANCE_ID --max-retrievals=1 --expiration=1200 -o json > createImportTokenResponse.json
     

3. 檢視匯入記號的詳細資料。

   jq '.' createImportTokenResponse.json
   

   輸出會顯示與匯入記號相關聯的 meta 資料，例如建立日期及原則詳細資料。 下列 Snippet 顯示輸出範例。

   {
     "creationDate": "2020-06-08T16:58:29Z",
     "expirationDate": "2020-06-08T17:18:29Z",
     "maxAllowedRetrievals": 1,
     "remainingRetrievals": 1
   }
   

擷取匯入記號

在前一個步驟中，您已建立匯入記號，並檢視與該記號相關聯的 meta 資料。

在此步驟中，您將擷取與匯入記號相關聯的公開金鑰和 Nonce 值。 您將需要公開金鑰在後續步驟中加密資料，並需要暫時性要求來驗證 Hyper Protect Crypto Services 服務的安全匯入要求。

如果要擷取匯入記號內容，請執行下列動作:

1. 擷取您已產生前一個步驟的匯入記號，然後將回應儲存至 JSON 檔案。

   • 使用 API

     curl -X GET $HPCS_API_URL/api/v2/import_token \
         -H "Accept: application/vnd.ibm.collection+json" \
         -H "Authorization: $ACCESS_TOKEN" \
         -H "Bluemix-Instance: $INSTANCE_ID" > getImportTokenResponse.json
     

   • 使用 IBM Key Protect CLI

     ibmcloud kp import-token show -o json > getImportTokenResponse.json
     

2. 選用項目: 檢查匯入記號的內容。

   jq '.' getImportTokenResponse.json
   

   輸出會顯示匯入記號的詳細資訊。 下列 Snippet 顯示含有截斷值的輸出範例。

   {
     "creationDate": "2020-06-08T16:58:29Z",
     "expirationDate": "2020-06-08T17:18:29Z",
     "maxAllowedRetrievals": 1,
     "remainingRetrievals": 0,
     "payload": "MIICIjANBgkqhkiG...",
     "nonce": "8zJE9pKVdXVe/nLb"
   }
   

   payload 值代表與匯入記號相關聯的公開金鑰。 此值已編碼 base64。 為了額外安全，Hyper Protect Crypto Services 提供 nonce 值，用來驗證服務要求的原始性。 當您匯入加密金鑰時，將需要加密並提供此值。

3. 將公開金鑰解碼並儲存至稱為 PublicKey.pem 的檔案，然後將值擷取至變數以供稍後使用。

   jq -r '.payload' getImportTokenResponse.json | openssl enc -base64 -A -d -out PublicKey.pem
   

   HPCS_PUBKEY="$(jq -r '.payload' getImportTokenResponse.json)"
   NONCE="$(jq -r '.nonce' getImportTokenResponse.json)"
   

   現在會以 PEM 格式將公開金鑰下載至您的工作站。 繼續下一步。

建立加密金鑰

使用 Hyper Protect Crypto Services，您可以透過建立並上傳自己的加密金鑰以在 IBM Cloud上使用，來啟用「保留自己的金鑰 (KYOK)」的安全優點。

在下列步驟中，您將在本端工作站上建立 256 位元 AES 對稱金鑰。

本指導教學使用 OpenSSL 加密法工具箱來產生虛擬隨機金鑰，但您可能想要 探索不同的選項，以根據安全需求來產生更強的金鑰。 例如，您可能想要使用內部部署硬體安全模組 (HSM) 所支援的組織內部金鑰管理系統，來建立及匯出金鑰。

如果您想要建立 256 位元 AES 對稱金鑰，請從指令行執行下列 openssl 指令:

openssl rand 32 > PlainTextKey.bin

如果您在本指導教學中使用自己的金鑰，則可以跳過此步驟。

成功！ 您的加密金鑰現在儲存在稱為 PlainTextKey.bin 的檔案中。 繼續下一步。

將加密金鑰設為環境變數

如果您遵循 步驟 3 來建立金鑰，若要編碼金鑰並將編碼值設為環境變數，請執行下列指令。 如果您在本指導教學中使用自己的金鑰，則可以跳過此步驟:

KEY_MATERIAL=$(openssl enc -base64 -A -in PlainTextKey.bin)

使用加密金鑰來加密暫時性要求

為了額外安全，當您將加密金鑰匯入至服務時，Hyper Protect Crypto Services 需要暫時性要求驗證。

在加密法中，Nonce 會作為階段作業記號，用來檢查要求的原始性，以防範惡意攻擊和未獲授權的呼叫。 透過使用 Hyper Protect Crypto Services所配送的相同 Nonce，您可以協助確保上傳金鑰的要求有效。 Nonce 值必須使用您要匯入至服務的相同金鑰來加密。

如果要加密 nonce 值，請執行下列動作:

1. 如果您要使用 API 來執行後續步驟，請執行下列動作:

   如果您要使用 IBM Key Protect CLI，則不需要執行此步驟。

   1. 下載與作業系統相容的範例 kms-encrypt-nonce 二進位。 解壓縮檔案，然後將二進位檔移至 hs-crypto-test 目錄。

      二進位檔包含一個 Script，您可以使用您在 步驟 2 中產生的金鑰，對 Nonce 值執行 AES-CBC 加密。 若要進一步瞭解 Script，請在 GitHub上移出原始檔。

   2. 如果您使用 Linux，請執行下列 chmod 指令，將檔案標示為可執行。 如果您是使用 Windows，則可以跳過此步驟。

      chmod +x ./kms-encrypt-nonce
      

   3. 執行 Script 以使用您在 步驟 2 中產生的金鑰來加密 Nonce 值。

2. 將已加密的 nonce 儲存至稱為 EncryptedValues.json 的檔案。

   • 使用 API

     ./kms-encrypt-nonce -key $KEY_MATERIAL -nonce $NONCE -alg "CBC" > EncryptedValues.json
     

   • 使用 IBM Key Protect CLI

     ibmcloud kp import-token nonce-encrypt --key "$KEY_MATERIAL" --nonce "$NONCE" --cbc -o json > EncryptedValues.json
     

3. 選用項目: 檢查 JSON 檔案的內容。

   jq '.' EncryptedValues.json
   

   輸出會顯示您需要為下一步提供的值。 下列 Snippet 顯示含有截斷值的輸出範例。

   {
     "encryptedNonce": "DVy/Dbk37X8gSVwRA5U6vrHdWQy8T2ej+riIVw==",
     "iv": "puQrzDX7gU1TcTTx"
   }
   

   encryptedNonce 值代表由您使用 OpenSSL產生的第一個金鑰包裝 (或加密) 的原始 Nonce。 iv 值是 AES-CBC 演算法所建立的起始設定向量 (IV)，稍後需要它，Hyper Protect Crypto Services才能順利解密 Nonce。

加密所建立的加密金鑰

接下來，使用 步驟 2 中 Hyper Protect Crypto Services 所配送的公開金鑰來加密您使用 OpenSSL建立的加密金鑰。

• 使用 API 來加密所建立的加密金鑰，並將金鑰指派給環境變數:

  openssl pkeyutl \
    -encrypt \
    -pubin \
    -keyform PEM \
    -inkey PublicKey.pem \
    -pkeyopt rsa_padding_mode:oaep \
    -pkeyopt rsa_oaep_md:sha1 \
    -in PlainTextKey.bin \
    -out EncryptedKey.bin
  

  ENCRYPTED_KEY=$(openssl enc -base64 -A -in EncryptedKey.bin)
  

  當您在 Mac OSX 上執行 openssl 指令時，如果遇到參數設定錯誤，則可能需要確保針對您的環境適當地配置 OpenSSL。 如果您已使用 Homebrew 來安裝 OpenSSL，請執行 brew update，然後執行 brew install openssl 以取得最新版本。 然後，執行 export PATH="/usr/local/opt/openssl/bin:$PATH"' >> ~/.bash_profile 以符號鏈結套件。 從指令行執行 which openssl && openssl version，以驗證在 /usr/local/ 位置下提供最新版本的 OpenSSL。 如果您繼續發生錯誤，請確保僅使用此範例中列出的參數。

• 使用 IBM Key Protect CLI 來加密已建立的加密金鑰:

  ibmcloud kp import-token key-encrypt -k "$KEY_MATERIAL" -p "$HPCS_PUBKEY" --hash SHA1 -o json > EncryptedKey.json
  ENCRYPTED_KEY=$(jq -r '.encryptedKey' EncryptedKey.json)
  

  成功！ 您已設定將加密金鑰上傳至 Hyper Protect Crypto Services。 繼續下一步。

匯入加密金鑰

您現在可以使用金鑰管理服務 API 來匯入加密金鑰。

如果要匯入加密金鑰，請執行下列動作:

1. 收集已加密的 nonce 和起始設定向量 (IV) 值。

   ENCRYPTED_NONCE=$(jq -r '.encryptedNonce' EncryptedValues.json)
   

   IV=$(jq -r '.iv' EncryptedValues.json)
   

2. 將加密金鑰儲存在 Hyper Protect Crypto Services 服務實例中。

   • 使用 API

     curl -X POST  $HPCS_API_URL/api/v2/keys \
         -H "Accept: application/vnd.ibm.collection+json" \
         -H "Authorization: $ACCESS_TOKEN" \
         -H "Content-Type: application/json" \
         -H "Bluemix-Instance: $INSTANCE_ID" \
         -d '{
           "metadata": {
             "collectionType": "application/vnd.ibm.kms.key+json",
             "collectionTotal": 1
           },
           "resources": [
           {
             "name": "encrypted-root-key",
             "type": "application/vnd.ibm.kms.key+json",
             "payload": "'"$ENCRYPTED_KEY"'",
             "extractable": false,
             "encryptionAlgorithm": "RSAES_OAEP_SHA_1",
             "encryptedNonce": "'"$ENCRYPTED_NONCE"'",
             "iv": "'"$IV"'"
           }
         ]
       }' > createRootKeyResponse.json
     

     在要求內文中，您提供在前一個步驟中準備的加密金鑰。 您也可以提供驗證要求所需的已加密 Nonce 和 IV 值。 最後，extractable 值設為 false 會將您的新金鑰指定為服務中可用於封套加密的根金鑰。

     如果 API 要求失敗，且發生匯入記號過期錯誤，請 回到步驟 1 以建立新的匯入記號。 請記住，匯入記號及其相關聯的公開金鑰會根據您在建立時指定的原則到期。

   • 使用 IBM Key Protect CLI

     ibmcloud kp key create new-imported-key --key-material "$ENCRYPTED_KEY" --encrypted-nonce "$ENCRYPTED_NONCE" --iv "$IV" --sha1 -o json > createRootKeyResponse.json
     

     在幕後，Hyper Protect Crypto Services 會透過 TLS 1.2 連線接收加密封包。 在硬體安全模組內，系統會使用私密金鑰來解密對稱金鑰。 最後，系統會使用對稱金鑰和 IV 來解密 Nonce 並驗證要求。 您的金鑰現在儲存在防竄改的 FIPS 140-2 Level 4 驗證硬體安全模組中。

3. 檢視金鑰的詳細資料。

   jq '.' createRootKeyResponse.json
   

   下列 Snippet 顯示輸出範例。

   {
     "metadata": {
       "collectionType": "application/vnd.ibm.kms.key+json",
       "collectionTotal": 1
     },
     "resources": [
       {
         "id": "644cba65-e240-471f-8b84-14115447d2ae",
         "type": "application/vnd.ibm.kms.key+json",
         "name": "encrypted-root-key",
         "state": 1,
         "crn": "crn:v1:bluemix:public:hs-crypto:us-south:a/f047b55a3362ac06afad8a3f2f5586ea:346d9f67-4bb2-481e-a3e1-3c2c646aa886:key:644cba65-e240-471f-8b84-14115447d2ae",
         "extractable": false,
         "imported": true
       }
     ]
   }
   

   • id 值是指派給金鑰的唯一 ID，用於後續呼叫金鑰管理服務 API。

   • state 值設為 1 表示您的金鑰現在處於 作用中金鑰狀態。

   • crn 值提供索引鍵的完整範圍路徑，該索引鍵指定資源在 IBM Cloud內的位置。

   • 最後，extractable 及 imported 值會將此資源說明為您匯入至服務的根金鑰。 當您將 extractable 屬性設為 true 時，服務會將金鑰指定為您可以儲存在應用程式或服務中的標準金鑰。 否則，當您將 extractable 屬性設為 false 時，服務會將金鑰指定為根金鑰。

4. 選用項目: 導覽至 Hyper Protect Crypto Services 儀表板以檢視及管理金鑰。

   您可以從應用程式詳細資料頁面瀏覽金鑰的一般性質。 從用於管理金鑰的選項清單中選擇，例如 替換金鑰 或 刪除金鑰。

清除

1. 收集您在前一個步驟中匯入之加密金鑰的 ID。

   ROOT_KEY_ID=$(jq -r '.resources[].id' createRootKeyResponse.json)
   

2. 從 Hyper Protect Crypto Services 服務實例移除加密金鑰。

   • 使用 API

     curl -X DELETE $HPCS_API_URL/api/v2/keys/$ROOT_KEY_ID \
       -H "Accept: application/vnd.ibm.collection+json" \
       -H "Authorization: $ACCESS_TOKEN" \
       -H "Bluemix-Instance: $INSTANCE_ID" | jq .
     

   • 使用 IBM Key Protect CLI

     ibmcloud kp key delete {ROOT_KEY_ID}
     

3. 移除與本指導教學相關聯的所有本端檔案。

   rm kms-encrypt-nonce *.json *.bin *.pem
   

4. 刪除您為此指導教學建立的測試目錄。

   cd .. && rm -r hs-crypto-test
   

5. 選用項目: 移除 Hyper Protect Crypto Services 服務實例。

   ibmcloud resource service-instance-delete import-keys-demo
   

   如果您在服務實例中建立了更多測試金鑰，請務必先 從服務實例中移除所有加密金鑰，然後再取消佈建實例。

下一步

在本指導教學中，您已學習如何設定 Hyper Protect Crypto Services 金鑰管理服務 API，建立加密金鑰，並安全地將加密金鑰匯入至 Hyper Protect Crypto Services 服務實例。

• 進一步瞭解 使用根金鑰來保護靜態資料。
• 在 支援的雲端服務 之間部署根金鑰。
• 進一步瞭解 金鑰管理服務 API。