建立關鍵別名

您可以使用 IBM® Key Protect for IBM Cloud® 與 Key Protect API 建立金鑰別名。

您可以使用 IBM® Key Protect for IBM Cloud® 與 Key Protect 主控台建立金鑰別名。

密鑰別名是唯一的人類可讀名稱，它們是對密鑰的引用，允許在顯示名稱的限制之外對其進行識別和分組。別名可讓您的服務透過可識別的自訂名稱來引用金鑰，而不是透過Key Protect服務提供的自動產生的識別碼。例如，如果您建立 ID 為 02fd6835-6001-4482-a892-13bd2085f75d 且別名為 US-South-Test-Key 金鑰，則在呼叫Key Protect api 時，可以使用 US-South-Test-Key 別名來引用您的金鑰檢索金鑰或其元數據。該別名也可用於在Key Protect控制台中組織金鑰。

使用控制台建立和編輯關鍵別名

密鑰別名可以在建立或匯入密鑰的過程中新增至密鑰。

有關建立根密鑰或標準密鑰的更多信息，請查看建立根密鑰或建立標準密鑰。
有關導入根密鑰或標準密鑰的更多信息，請查看導入根密鑰或導入標準密鑰。

若要編輯鍵盤快捷鍵別名，請點擊 ⋯ 並選擇「編輯別名」。在該標籤中，您將看到分配給該金鑰的任何現有別名（並且能夠刪除它們），並且能夠新增更多別名。一個金鑰最多可擁有五個別名。

使用 API 建立金鑰別名

透過向以下端點發出 POST 呼叫，建立一個金鑰別名。

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

檢索您的驗證憑證以使用服務中的金鑰。

若要建立金鑰別名，必須為您指派_管理者_或_編寫者_服務存取角色。了解 IAM 角色如何映射到 Key Protect 服務動作，查看服務存取角色。

透過執行以下 curl 命令建立金鑰別名。

$ curl -X POST \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys/<keyID_or_alias>/aliases/<key_alias>" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>" \
    -H "content-type: application/vnd.ibm.kms.key+json" \
    -H "correlation-id: <correlation_ID>"

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

描述使用Key Protect API 建立金鑰別名所需的變數
變數	說明
區域	必填。代表您的 Key Protect 實例所在地理區域的區域縮寫，例如 `us-south` 或 `eu-gb`。如需更多資訊，請參閱「區域服務端點」。
keyID_or_alias	必填。您想要與別名關聯的金鑰的識別碼或別名。若要檢索金鑰 ID，請參閱清單金鑰 API。
密鑰別名	必填。方便識別金鑰且人類可閱讀的唯一名稱。別名必須是字母數字、區分大小寫，且不能包含空格或破折號 (-) 或底線 (_) 以外的特殊字元。別名不能是版本 4 UUID，也不能是Key Protect保留名稱：allowed_ip、key、keys、metadata、policy、policy、registration、registrations、ring、rings、rotate、wrap、展開、重新包裝、版本、versions.Alias 注意您的Key Protect實例中不能有重複的別名。
IAM_token	必填。您的 IBM Cloud 存取記號。請在 curl 請求中包含 IAM 憑證的完整內容，包括 Bearer 值。有關詳細信息，請參閱檢索訪問令牌。
instance_id	必填。分配給您的 Key Protect 服務實例的唯一識別碼。如需更多資訊，請參閱「檢索實例 ID」。
關聯ID	可選。用於追蹤和關聯交易的唯一識別碼。

為保護您的個人資料機密性，請避免在建立金鑰別名時輸入可識別個人身分的資訊（PII），例如您的姓名或位置。有關個人識別資訊（PII）的更多範例，請參閱《 NIST 特別出版物 800-122 》第 2.2 節。

成功的 POST api/v2/keys/<keyID_or_alias>/aliases/<key_alias> 回應會回傳您的金鑰別名，以及其他元資料。別名是分配給您的密鑰的唯一名稱，可用於檢索有關關聯密鑰的更多資訊。

{
    "metadata": {
        "collectionType": "application/vnd.ibm.kms.key+json",
        "collectionTotal": 1
    },
    "resources": [
        {
            "keyId": "02fd6835-6001-4482-a892-13bd2085f75d",
            "alias": "test-alias",
            "creationDate": "2020-03-12T03:37:32Z",
            "createdBy": "..."
        }
    ]
}

響應參數的詳細說明請參見 Key Protect REST API 參考文件。

每個金鑰最多可擁有五個別名。每個實例的別名限制為 1,000 個。

使用 API 刪除金鑰別名

透過對以下端點進行 DELETE 呼叫來刪除金鑰別名。

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

檢索您的驗證憑證以使用服務中的金鑰。

透過執行以下 curl 指令刪除金鑰別名。

$ curl -X DELETE \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys/<keyID_or_alias>/aliases/<key_alias>" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>" \
    -H "content-type: application/vnd.ibm.kms.key+json" \
    -H "correlation-id: <correlation_ID>"

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

描述使用Key Protect API 刪除金鑰別名所需的變數
變數	說明
區域	必填。代表您的 Key Protect 實例所在地理區域的區域縮寫，例如 `us-south` 或 `eu-gb`。如需更多資訊，請參閱「區域服務端點」。
keyID_or_alias	必填。您在步驟 1 中檢索到的密鑰的識別碼或別名。
密鑰別名	必填。識別您的密鑰的唯一的、人類可讀的名稱。
IAM_token	必填。您的 IBM Cloud 存取記號。請在 curl 請求中包含 IAM 憑證的完整內容，包括 Bearer 值。如需更多資訊，請參閱「取得存取憑證」。
instance_id	必填。指派給您 Key Protect 服務實例的唯一 ID。如需更多資訊，請參閱「檢索實例 ID」。
關聯ID	可選。用於追蹤和關聯交易的唯一識別碼。

成功的 DELETE api/v2/keys/<keyID_or_alias>/aliases/<key_alias> 請求返回 HTTP 204 No Content 回應，表示與您的密鑰相關的別名已被刪除。已被刪除。

從服務中完全刪除別名最多需要五分鐘。

關鍵別名常見問題解答

以下是關於關鍵別名的更多詳細資訊：

別名獨立於密鑰。 別名是它自己的資源，對其執行的任何操作都不會影響關聯的密鑰。例如，刪除別名不會刪除關聯的鍵。
一個別名一次只能與一個金鑰相關聯。 別名只能與位於相同實例和區域的一個鍵關聯。如果您想要變更與別名關聯的鍵，則需要刪除別名，等待最多五分鐘，然後重新建立別名並將其對應到必要的鍵。
您可以在不同實例或區域建立同名別名。 每個別名將與每個實例或區域中的不同鍵關聯。這使得您的服務的應用程式程式碼可以在不同的實例或區域中重複使用。例如，如果您有一個名為 Application Key 在美國南部和美國東部區域，每個區域都連結到不同的密鑰。

使用金鑰別名的 API

下表列出了可用於建立和使用金鑰別名的 API。

描述作為使用鍵別名的 API 的變數。
API	關鍵別名影響
建立根密鑰	建立根密鑰時最多可建立 5 個別名。
建立標準密鑰	建立標準金鑰時您最多可以建立 5 個別名。
取回鑰匙	您可以透過 ID 或別名檢索金鑰。
查看關鍵元數據	您可以透過 ID 或別名檢索金鑰的元資料。