创建密钥别名

You can use IBM® Key Protect for IBM Cloud® to create a key alias with the Key Protect API.

您可以使用IBM® Key Protect for IBM Cloud®通过Key Protect控制台创建密钥别名。

密钥别名是人类可读的唯一名称，是对密钥的引用，可使密钥的识别和分组超出显示名称的限制。别名可让您的服务使用可识别的自定义名称来引用键，而不是使用Key Protect服务提供的自动生成标识符。 For example, if you create a key that has the the ID 02fd6835-6001-4482-a892-13bd2085f75d and it is aliased as US-South-Test-Key, you can use the US-South-Test-Key alias to refer to your key when you make calls to the Key Protect api to 取键 or its 元数据. 别名还可用于在Key Protect控制台中组织键值。

使用控制台创建和编辑按键别名

在创建或导入密钥的过程中，可以为密钥添加密钥别名。

有关创建根密钥或标准密钥的更多信息，请查看创建根密钥或创建标准密钥。
有关导入根密钥或标准密钥的更多信息，请查看导入根密钥或导入标准密钥。

要编辑键别名，请单击 ⋯ 并选择编辑键别名。在该选项卡中，你将看到分配给该键的任何现有别名（并能删除它们），还能添加更多别名。一个密钥最多可以有五个别名。

使用应用程序接口创建密钥别名

通过 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
变量	描述
区域	需要。地区缩写，如 `us-south` `eu-gb`，表示您的Key Protect实例所在的地理区域。 For more information, see 区域服务终端.
keyID_or_alias	需要。要与别名关联的密钥的标识符或别名。要检索密钥 ID，请参阅列表密钥 API。
key_alias	需要。密钥的人类可读的唯一名称，以便可轻松识别密钥。 Alias must be alphanumeric, case sensitive, and cannot contain spaces or special characters other than dashes (-) or underscores (_). The alias cannot be a version 4 UUID and must not be a Key Protect reserved name: allowed_ip, key, keys, metadata, policy, policies, registration, registrations, ring, rings,rotate, wrap, unwrap, rewrap, version, versions.Alias size can be between 2 - 90 characters (inclusive). Note You cannot have duplicate alias names in your Key Protect instance.
IAM_token	需要。您的 IBM Cloud 访问令牌。在curl请求中包含IAM令牌的全部内容，包括承载器值 For more information, see 读取访问令牌.
instance_ID	需要。分配给Key Protect服务实例的唯一标识符 For more information, see 检索实例 ID.
correlation_ID	可选。用于跟踪和关联交易的唯一标识符。

为保护您个人数据的机密性，请避免输入以下信息个人身份信息 (PII)，例如您的姓名或所在位置、创建密钥别名时。有关 PII 的更多示例，请参见第2.2节。第 2.2 节。 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 参考文档。

每个密钥最多可以有五个别名。每个实例。

使用应用程序接口删除密钥别名

通过 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 ProtectAPI 删除键别名所需的变量。API
变量	描述
区域	需要。地区缩写，如 `us-south` `eu-gb`，表示您的Key Protect实例所在的地理区域 For more information, see 区域服务终端.
keyID_or_alias	需要。您在步骤 1 中获取的密钥的标识符或别名。
key_alias	需要。可识别密钥的唯一、人类可读的名称。
IAM_token	需要。您的 IBM Cloud 访问令牌。在curl请求中包含IAM令牌的全部内容，包括承载器值 For more information, see 读取访问令牌.
instance_ID	需要。指定给您的 Key Protect 服务实例的唯一标识。 For more information, see 检索实例 ID.
correlation_ID	可选。用于跟踪和关联交易的唯一标识符。

A successful DELETE api/v2/keys/<keyID_or_alias>/aliases/<key_alias> request returns an HTTP 204 No Content response, which indicates that the alias associated with your key was deleted.

从服务中完全删除别名最长需要 5 分钟。

键别名常见问题

下面是有关关键别名的其他详细信息：

别名独立于密钥。 别名是它自己的资源，对它执行的任何操作都不会影响到相关键。例如，删除别名不会删除相关的键。
一个别名一次只能与一个密钥关联。 别名只能与位于同一实例和区域中的一个密钥关联。实例和区域中的一个密钥相关联。如果要更改别名所关联的密钥关联的密钥，则需要删除别名，最多等待五分钟、然后重新创建别名，并将其映射到必要的密钥。
您可以在不同的实例或区域中创建具有相同名称的别名。 在每个实例或区域中，每个别名都与不同的密钥相关联。这样，您的服务应用代码就可以在不同的实例或区域中重复使用。实例或区域中重复使用。例如，如果您有一个名为 Application Key in both the US-South and US-East regions, with each linked to a different key.

使用密钥别名的应用程序接口

下表列出了可用于创建和使用密钥别名。

描述使用密钥别名的 API 变量。
API	关键别名的影响
创建根密钥	创建根密钥时最多可创建 5 个别名。
创建标准密钥	创建标准密钥时最多可创建 5 个别名。
读取密钥	您可以通过 ID 或别名检索密钥。
查看关键元数据	您可以通过 ID 或别名检索键的元数据。