目標

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

• 設定 Key Protect CLI

• 準備 Key Protect 服務實例以開始匯入金鑰

• 使用 OpenSSL 加密法工具箱來建立及加密金鑰

• 將加密金鑰匯入至 Key Protect 實例

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

開始之前

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

1. 建立 IBM Cloud 帳戶。

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

3. 配置並 設定 Key Protect CLI 外掛程式 以開始管理金鑰。 如果您已完成先前列出的前兩個步驟，請先從鏈結上的步驟號碼 3 開始，再回到本指導教學。

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

   如果您正在嘗試，您可以使用 openssl 指令在本端電腦上產生加密金鑰 Key Protect 第一次。 本指導教學需要 OpenSSL 1.0.2r 版或更新版本。

   如果您使用的是 Mac，您可以透過以下方式下載 OpenSSL Homebrew。 如果您是第一次安裝套件，請執行 brew install openssl，或執行 brew upgrade openssl 以將現有套件升級至最新版本。

5. 下載並安裝 jq。

   jq 可協助您截塊 JSON 資料。 您在本指導教學中使用 jq 來擷取呼叫時所傳回的特定資料 Key Protect API。

步驟 1. 建立 Key Protect 實例

設定 IBM Cloud 帳戶之後，請完成下列步驟來佈建 Key Protect 實例。

1. 在終端機視窗中，執行下列指令以登入 IBM Cloud 與 IBM Cloud CLI。

   ibmcloud login
   

   如果登入失敗，請執行 ibmcloud login --sso 指令再試一次。 當您使用聯合 ID 登入時，需要 --sso 參數。 如果使用這個選項，請前往 CLI 輸出中所列的鏈結，以產生一次性的通行碼。

2. 請選擇您要建立 Key Protect 實例。

   在本指導教學中，您將與華盛頓特區地區互動。 如果您已登入不同的地區，請務必執行下列指令，將華盛頓特區設為您的目標地區。

   ibmcloud target -r us-east
   

3. 在該帳戶及資源群組內佈建 Key Protect 實例。

   首先，透過發出下列指令來指定實例的資源群組:

   ibmcloud target -g <your-resource-group>
   

   例如： ibmcloud target -g Default

   然後，您可以發出下列指令來建立實例:

   ibmcloud resource service-instance-create "import-keys-demo" kms tiered-pricing us-east
   

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

4. 選用項目: 列出可用的 Key Protect 實例，以驗證已順利建立 Key Protect 實例。

   ibmcloud resource service-instances
   

   成功！ 現在您已設定 Key Protect 實例，您可以在其中儲存及管理加密金鑰。 繼續進行下一步。

步驟 2. 設定 Key Protect API

既然您已佈建的實例 Key Protect，您已準備好開始使用 API。

Key Protect 提供圖形使用者介面和 REST API 來建立、追蹤和管理加密金鑰。 該 Key Protect API 需要有效的 IBM Cloud IAM 記號及實例 ID，以向服務進行鑑別。

在此步驟中，您使用 IBM Cloud CLI 來收集開始與互動所需的鑑別認證 Key Protect API。 若要擷取並準備認證以用於後續步驟，您也可以將認證設定為終端機中的環境變數。

1. 在終端機視窗中，設定 Key Protect API 端點作為環境變數。

   export KP_API_URL=https://<region>.kms.cloud.ibm.com
   

2. 使用產生 IBM Cloud 存取記號 Key Protect CLI 外掛程式，並將它設為環境變數。

   環境變數應該以授權類型開頭， Bearer. CLI 指令 (如範例所示) 會自動包含正確的類型。

   export ACCESS_TOKEN=`ibmcloud iam oauth-tokens | grep IAM | cut -d \: -f 2 | sed 's/^ *//'`
   

   IBM Cloud 存取憑證的有效期為 1 小時，但您 可視需要重新產生新的憑證。 若要產生新的存取記號，請執行 ibmcloud iam oauth-tokens 指令。 如欲進一步了解檢索相關資訊 IBM Cloud 存取權限，請參閱 擷取存取權限。

3. 擷取與您的 Key Protect 實例，然後將值設為環境變數。

   export INSTANCE_ID=`ibmcloud resource service-instance "import-keys-demo" --output json | jq -r '.[].guid'`
   

4. 選用項目: 透過將環境變數列印至終端機畫面，驗證已正確設定環境變數。

   $ echo $KP_API_URL
   https://us-east.kms.cloud.ibm.com
   $ echo $ACCESS_TOKEN
   Bearer eyJraWQiOiIyM...
   $ echo $INSTANCE_ID
   c1cf624b-6bed-4d4d-bd54-8e2534258a88
   

   成功！ 您現在已設定鑑別 Key Protect API 所需的服務認證。 繼續進行下一步。

步驟 3. 建立匯入記號

使用您的服務認證，您可以開始與 Key Protect API，以建立加密金鑰並將其帶至服務。

在下列步驟中，您將建立 Key Protect 實例的 匯入記號。 透過 根據您指定的政策建立匯入憑證，您可在加密金鑰傳輸至服務的過程中， 為其提供額外的安全防護。

1. 使用終端機階段作業，切換至新的 key-protect-test 目錄。

   mkdir key-protect-test && cd key-protect-test
   

   您可以使用此目錄來儲存檔案，以供後續步驟使用。

2. 建立您的匯入記號 Key Protect 實例，然後將回應儲存至 JSON 檔案。

   $ curl -X POST \
       "$KP_API_URL/api/v2/import_token" \
       -H "accept: application/vnd.ibm.collection+json" \
       -H "authorization: $ACCESS_TOKEN" \
       -H "bluemix-instance: $INSTANCE_ID" \
       -H "content-type: application/json" \
       -d '{
               "expiration": 1200,
               "maxAllowedRetrievals": 1
           }' > createImportTokenResponse.json
   

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

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

   jq '.' createImportTokenResponse.json
   

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

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

步驟 4. 擷取匯入記號

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

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

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

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

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

   $ curl -X GET \
       "$KP_API_URL/api/v2/import_token" \
       -H "accept: application/vnd.ibm.collection+json" \
       -H "authorization: $ACCESS_TOKEN" \
       -H "bluemix-instance: $INSTANCE_ID" > getImportTokenResponse.json
   

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

   jq '.' getImportTokenResponse.json
   

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

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

   payload 值代表與匯入記號相關聯的公開金鑰。 此值採用 base64 編碼。 nonce 值用來驗證服務要求的原始性。 在後續步驟中匯入加密金鑰時，您需要加密並提供此值。

3. 將公開金鑰解碼並儲存至稱為 PublicKey.pem 的檔案。

   jq -r '.payload' getImportTokenResponse.json | base64 --decode -o PublicKey.pem
   

   公開金鑰現在會以 PEM 格式下載到您的電腦。 繼續進行 下一步。

步驟 5. 建立加密金鑰

使用 Key Protect，您可以透過建立並上傳自己的金鑰以在 IBM Cloud上使用，來啟用「自帶金鑰 (BYOK)」的安全優點。

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

本教學使用 OpenSSL Cryptography toolkit 來產生偽隨機 密鑰，但您也許想 探索不同的選項 根據您的安全需求來產生更強的金鑰。 例如，您 可能希望使用貴組織的內部金鑰管理系統（該系統由 本地部署的硬體安全模組（HSM）提供支援），來建立和匯出金鑰。

1. 在終端機視窗中，執行下列 openssl 指令，以建立 256 位元加密金鑰。

   openssl rand 32 > PlainTextKey.bin
   

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

步驟 6. 加密暫時性要求

若要驗證我們接收的位元與您在要求中傳送的位元完全相同，Key Protect 當您將對稱金鑰上傳至服務時，需要暫時性要求驗證。

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

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

1. 編碼您在前一個步驟中產生的金鑰，並將編碼值設為環境變數。

   KEY_MATERIAL=$(base64 PlainTextKey.bin)
   

2. 收集您在步驟 4 中擷取的 Nonce 值。

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

3. 執行下列步驟，以使用您在步驟 5 中產生的加密金鑰來加密 Nonce 值。 然後，將回應儲存至稱為的檔案 EncryptedValues.json.

   ibmcloud kp import-token nonce-encrypt -k $KEY_MATERIAL -n $NONCE --output json > EncryptedValues.json
   

4. 選用項目: 使用 jq 來檢查 JSON 檔案的內容，如下所示。

   jq '.' EncryptedValues.json
   

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

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

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

步驟 7. 加密金鑰

接下來，使用所配送的公開金鑰 Key Protect，以加密您使用 OpenSSL產生的對稱金鑰。

1. 使用您在步驟 4 中所擷取的公開金鑰來加密產生的金鑰。

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

   如果您在執行 openssl 時遇到參數設定錯誤 命令，您可能需要確保 OpenSSL 已經針對您的環境進行了正確配置。 為您的環境設定。 如果您使用 Homebrew 安裝 OpenSSL、 執行 brew update，然後再執行 brew install openssl 以取得最新版本。 然後，執行 export PATH="/usr/local/opt/openssl/bin:$PATH" >> ~/.bash_profile 以符號鏈結套件。 開啟新的終端機階段作業，然後執行 which openssl && openssl version 驗證最新版本的 OpenSSL 在 /usr/local/ 位置下可用。 如果您繼續發生錯誤，請確保僅使用此範例中列出的參數。

   成功！ 您的加密金鑰現在已儲存至稱為的檔案 EncryptedKey.bin. 您已設定將加密金鑰上傳至 Key Protect. 繼續進行下一步。

步驟 8. 匯入金鑰

您現在可以使用來匯入已加密金鑰 Key Protect API。

若要匯入金鑰，請執行下列動作:

1. 收集加密金鑰、加密 Nonce 及起始設定向量 (IV) 值。

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

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

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

2. 將加密金鑰儲存在 透過執行下列 curl 指令，Key Protect 實例。

   $ curl -X POST \
       "$KP_API_URL/api/v2/keys" \
       -H "accept: application/vnd.ibm.collection+json" \
       -H "authorization: $ACCESS_TOKEN" \
       -H "bluemix-instance: $INSTANCE_ID" \
       -H "content-type: application/json" \
       -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_256",
                       "encryptedNonce": "'"$ENCRYPTED_NONCE"'",
                       "iv": "'"$IV"'"
                   }
               ]
           }' > createRootKeyResponse.json
   

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

   Key Protect 接收 透過 TLS 1.2 或 1.3 通訊協定接收您的加密封包。 在硬體安全模組內，系統會使用私密金鑰來解密對稱金鑰。 最後，系統會使用對稱金鑰和 IV 來解密 Nonce 並驗證要求。

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

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

   jq '.' createRootKeyResponse.json
   

   下列 Snippet 顯示輸出範例。

   {
       "metadata": {
           "collectionType": "application/vnd.ibm.kms.key+json",
           "collectionTotal": 1
       },
       "resources": [
           {
               "id": "02fd6835-6001-4482-a892-13bd2085f75d",
               "type": "application/vnd.ibm.kms.key+json",
               "name": "encrypted-root-key",
               "state": 1,
               "crn": "crn:v1:bluemix:public:kms:us-south:a/f047b55a3362ac06afad8a3f2f5586ea:12e8c9c2-a162-472d-b7d6-8b9a86b815a6:key:02fd6835-6001-4482-a892-13bd2085f75d",
               "extractable": false,
               "imported": true
           }
       ]
   }
   

   id 值是分配給您的金鑰的唯一識別碼，並 用於後續對該 Key Protect API。 state 值設為 1 表示您的加密金鑰現在位於 作用中 金鑰狀態。 crn 值提供索引鍵的完整範圍路徑，該索引鍵指定資源在 IBM Cloud內的位置。 最後，extractable 及 imported 值會將此資源說明為您匯入至服務的根金鑰。

4. 選用項目: 導覽至 Key Protect 儀表板，以檢視及管理加密金鑰。

   

   您可以在應用程式的 詳細資訊頁面上瀏覽您的金鑰的一般特性。 從管理金鑰的選項清單中選擇，例如 旋轉金鑰 或 刪除金鑰。

步驟 9. 清除

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

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

2. 從中移除加密金鑰 Key Protect 實例。

   $ curl -X DELETE \
       "$KP_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 .
   

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

   rm *.json *.bin *.pem
   

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

   cd .. && rm -r key-protect-test
   

5. 選用項目: 移除 Key Protect 服務實例。

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

   如果您在中建立更多測試金鑰 Key Protect 實例，請務必 從您的實體移除所有加密金鑰 在刪除或取消配置實體之前，請務必移除實體中的所有加密金鑰。

下一步

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

• 進一步瞭解 使用根金鑰來保護靜態資料。

• 將根金鑰部署在 支援的雲端服務。

• 進一步瞭解 Key Protect API。