匯入根金鑰

您可以使用 IBM® Key Protect for IBM Cloud®，透過匯入現有的根金鑰來保護和管理這些金鑰。

根金鑰是用來保護雲端中已加密資料安全的對稱金鑰包裝金鑰。如需將根金鑰匯入至 Key Protect 的相關資訊，請參閱自帶加密金鑰到雲端。

藉由檢閱建立及加密金鑰資料的選項，來提前規劃匯入金鑰。為了提高安全性，您可以在將金鑰資料上傳至雲端之前，使用匯入憑證對金鑰資料進行加密，藉此啟用金鑰資料的安全匯入功能。

透過控制台匯入根金鑰

建立服務實例之後，請完成下列步驟，以使用 IBM Cloud 主控台匯入金鑰。

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

登入 IBM Cloud 主控台。
請前往「選單」>「資源清單」以檢視您的資源清單。
從 IBM Cloud 資源清單，選取已佈建的 Key Protect 實例。
若要匯入金鑰，請按一下「新增」，然後選擇「匯入金鑰」視窗。

指定金鑰的詳細資料：

描述匯入您自己的密鑰設定。
設定	說明
金鑰類型	您希望在 Key Protect 中管理的金鑰類型。點選「根金鑰」按鈕。
名稱	一個易於辨識的別名，方便您識別您的金鑰。長度必須在 2-90 個字元 (內含) 內。若要保護您的隱私權，請確定金鑰名稱未包含個人識別資訊 (PII)（例如您的姓名或位置）。請注意，金鑰名稱不需要是唯一的。
金鑰資料	base64-encoded 金鑰資料（例如現有的金鑰封裝金鑰），您希望將其儲存並透過此服務進行管理。如需相關資訊，請參閱 Base64 編碼金鑰資料。請確定金鑰資料長度為 16、24 或 32 個位元組，且長度對應於 128、192 或 256 位元。金鑰也必須是 base64-encoded。
金鑰說明	選用。以無法使用別名或其名稱來新增金鑰相關資訊 (例如，描述其用途的詞組) 的方式，說明是很有用的方法。此說明必須至少兩個字元，且不超過 240 個字元，且稍後無法變更。為保護您的隱私，請勿將個人資料（例如您的姓名或位置）用作金鑰的描述。
金鑰別名	選用。金鑰別名是說明金鑰的方法，可讓您識別並分組超出顯示名稱限制的金鑰。金鑰最多可以有五個別名。
金鑰環	選用。金鑰環是金鑰的分組，容許視需要獨立管理這些分組。每一個金鑰都必須是金鑰環的一部分。如果未選取任何金鑰環，則會將金鑰放置在 `default` 金鑰環中。請注意，若要將您正在建立的金鑰放置在金鑰環中，您必須對該金鑰環具有管理員角色。如需角色的相關資訊，請參閱管理使用者存取權。

填寫完密鑰的詳細資料後，請點擊「新增」以確認。

如果您是某個鑰匙圈_的管理員_，您可以直接從「鑰匙圈」面板新增鑰匙。在鑰匙圈的動作選單（⋯）中，點選「新增鑰匙」。此時會開啟與您在「金鑰」頁面點擊 「新增」 時相同的面板，但「金鑰圈」欄位中已預先填入所選的金鑰圈名稱。

如果您需要跨帳號或環境一致地匯入和管理根金鑰，您可以使用 Key Protect 金鑰模組自動執行。如需完整的設定，同時提供 Key Protect 實例和鑰匙圈，請參閱全包式 Key Protect 模組。如需概覽，請參閱 Terraform IBM 模組。

使用 API 匯入根金鑰

透過對下列端點發出 POST 呼叫，將對稱金鑰匯入至 Key Protect。

https://<region>.kms.cloud.ibm.com/api/v2/keys

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

使用下列 curl 指令呼叫 Key Protect API。

$ curl -X POST \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>" \
    -H "content-type: application/vnd.ibm.kms.key+json" \
    -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": "<expiration_date>",
                    "payload": "<key_material>",
                    "extractable": <key_type>
                }
            ]
        }'

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

描述使用Key Protect API 新增根金鑰所需的變數
變數	說明
區域	必填。代表您的 Key Protect 實例所在地理區域的區域縮寫，例如 `us-south` 或 `eu-gb`。如需更多資訊，請參閱「區域服務端點」。
IAM_token	必填。您的 IBM Cloud 存取記號。請在 curl 請求中包含 IAM 憑證的完整內容，包括 Bearer 值。如需更多資訊，請參閱「取得存取憑證」。
instance_id	必填。分配給您的 Key Protect 服務實例的唯一識別碼。如需更多資訊，請參閱「檢索實例 ID」。
correlation_ID	用來追蹤及關聯交易的唯一 ID。
return_preference	一個用於變更伺服器對 POST 和 DELETE 操作之行為的標頭。當您將 return_preference 變數設定為 return=minimal 時，該服務僅會在回應實體內容中返回金鑰元資料，例如金鑰名稱和 ID 值。當您將變數設定為 return=representation 時，該服務會同時傳回金鑰資料與金鑰元資料。
key_name	必填。方便識別金鑰且人類可閱讀的唯一名稱。為了保護您的隱私權，請不要將個人資料儲存為金鑰的 meta 資料。
別名清單	選用。指派給您金鑰的一或多個唯一且人類可讀的別名。重要事項：若要保護您的隱私權，請不要將個人資料儲存為金鑰的 meta 資料。每一個別名都必須是英數、區分大小寫，且不能包含空格或-或 _ 以外的特殊字元。別名不能是 UUID，且不能是 Key Protect 保留名稱 :allowed_ip、key、keys、metadata、policy、policies。登錄、登錄、環、環、旋轉、覆蓋、解除覆蓋、重新覆蓋、版本、版本。
key_description	選用。金鑰的延伸說明。為了保護您的隱私權，請不要將個人資料儲存為金鑰的 meta 資料。
到期日	選用。金鑰在系統中到期的日期和時間，採用 RFC 3339 格式 (`YYYY-MM-DD HH:MM:SS.SS`，例如 `2019-10-12T07:20:50.52Z`)。金鑰將在金鑰到期日的一小時內轉移至取消啟動狀態。若省略 `expirationDate` 屬性，則該金鑰不會過期。
金鑰資料	必填。 base64-encoded 金鑰資料，這是一組現有的金鑰封裝金鑰，您希望將其儲存並管理於該服務中。如需相關資訊，請參閱 Base64 編碼金鑰資料。確保金鑰資料符合下列需求: 標準金鑰大小最多可達 7,500 個位元組。金鑰必須以 base64-encoded。
key_type	決定金鑰資料是否可以離開服務的布林值。當您將 extractable 屬性設定為 `false` 時，該服務會將該金鑰指定為根金鑰，您可使用它來執行封裝或解封裝操作。

若要保護您個人資料的機密性，請在將金鑰新增至服務時避免輸入個人識別資訊 (PII)（例如您的姓名或位置）。

成功的 POST api/v2/keys 回應會傳回您金鑰的 ID 值，以及其他 meta 資料。 ID 是指派給您金鑰的唯一 ID，並用於後續的 Key Protect API 呼叫。

可選步驟：執行以下呼叫以瀏覽您的 Key Protect 實例中的金鑰，確認該金鑰已成功新增。

$ curl -X GET \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys" \
    -H "accept: application/vnd.ibm.collection+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>"

Base64-encoding 您的金鑰資料

匯入現有的根金鑰時，必須包含您要在服務中儲存及管理的已加密金鑰資料。

使用 OpenSSL 來加密現有的金鑰資料

使用此處理程序來加密檔案中金鑰資料的內容。

下載並安裝 OpenSSL。
執行下列指令，以 Base64-encode 您的金鑰資料字串:
```
openssl base64 -in <infile> -out <outfile>
```
根據下表取代範例要求中的變數。

描述對密鑰材料進行base64-encode所需的變數。
變數	說明
輸入檔	金鑰資料字串所在檔案的名稱。請確定金鑰長度為 16、24 或 32 個位元組，長度對應於 128、192 或 256 位元。金鑰必須以 base64-encoded。
輸出檔案	執行指令之後，將在其中建立 base64-encoded 金鑰資料的檔案名稱。

如果您想直接在命令列輸出 base64 物料，而不是檔案，請發出 openssl enc -base64 <<< '<key_material_string>'，其中 key_material_string 是您匯入的關鍵物料輸入。

使用 OpenSSL 來建立及編碼新的金鑰資料

使用此處理程序來建立具有特定位元組長度的隨機 base64-encoded 金鑰資料。建議使用 32 位元組 (256 位元)。

下載並安裝 OpenSSL。
執行下列指令，以 Base64-encode 您的金鑰資料字串:
```
openssl rand -base64 <byte_length>
```
請根據以下表格，替換範例請求中的變數。

描述建立和編碼新密鑰材料所需的變數。
變數	說明
位元組長度	金鑰的長度，單位為位元組。可接受的位元組長度為 16、24 或 32 個位元組，對應於 128、192 或 256 位元長度。金鑰必須以 base64-encoded。

主要物料建立範例

openssl rand -base64 16 將產生 128 位元金鑰資料。
openssl rand -base64 24 將產生 192 位元金鑰資料。
openssl rand -base64 32 將產生 256 位元金鑰資料。

下一步

若要進一步瞭解如何使用封套加密來保護金鑰，請參閱包裝金鑰。
若要進一步了解如何透過程式方式管理您的金鑰，請參閱 Key Protect 的 API 參考文件。