导入对称密钥材料 - 密钥管理服务

当您需要自行管理并控制密钥材料时，您可以在KMS实例中创建密钥材料来源为外部的密钥，然后导入您自己的密钥材料。本文介绍如何为对称密钥导入密钥材料。

重要

如果您的软件密钥管理实例、硬件密钥管理实例不支持导入密钥材料，或者导入密钥材料时返回失败，请联系阿里云技术支持升级实例。

功能介绍

密钥是KMS的基本资源，由密钥ID、基本元数据（如密钥状态等）以及密钥材料组成。创建密钥时，您可以选择由KMS生成密钥材料，也可以选择外部来源的密钥材料。如果选择了外部来源的密钥材料，您需要将外部密钥材料导入到密钥中，该功能通常被称为自带密钥（BYOK）。

不同KMS密钥管理类型对导入密钥材料的支持情况，请参见下表。关于密钥管理类型的更多信息，请参见密钥管理类型和密钥规格。

：表示支持导入相应的密钥材料。
：表示不支持导入相应的密钥材料。

密钥管理类型	导入对称密钥材料	导入非对称密钥材料
默认密钥	主密钥：√ 服务密钥：×	主密钥：× 服务密钥：×
软件密钥	√	√
硬件密钥	√	×

注意事项

请确保使用了符合要求的随机数发生器生成密钥材料。
为密钥首次导入密钥材料后，密钥即和该密钥材料绑定，不再支持导入其他密钥材料。
您可以根据需要将相同的密钥材料多次导入到KMS密钥中，但不能将不同的密钥材料导入到一个KMS密钥。
如果密钥的密钥材料过期或被删除，您可以为密钥再次导入相同的密钥材料，使得该密钥再次可用，导入密钥材料后不支持导出，因此请您妥善保管密钥材料。

前提条件

已购买和启用KMS实例。具体操作，请参见购买和启用KMS实例。

说明

为默认密钥（主密钥）导入密钥材料时，无需购买KMS实例。

步骤一：创建密钥材料来源为外部的对称密钥

导入密钥材料前，请创建密钥材料来源为外部的对称密钥。

默认密钥（主密钥）

登录密钥管理服务控制台，在顶部菜单栏选择地域后，在左侧导航栏单击资源 > 密钥管理。

单击默认密钥页签，单击主密钥操作列的启用，在创建密钥页签完成配置项设置，然后单击确定。

配置项	说明
密钥别名	密钥的标识符。支持英文字母、数字、下划线（_）、短划线（-）和正斜线（/）。
描述信息	密钥的说明信息。
高级选项	密钥材料来源。选择外部（导入密钥材料）。说明请仔细阅读并选中我了解使用外部密钥材料的方法和意义。

软件密钥

登录密钥管理服务控制台，在顶部菜单栏选择地域后，在左侧导航栏单击资源 > 密钥管理。
在用户主密钥页签，实例ID选择软件密钥管理实例，单击创建密钥。

在创建密钥面板，完成配置项设置，然后单击确定。

配置项	说明
密钥类型	选择对称密钥。重要如果您创建的密钥用于加密凭据值，请选择对称密钥。
密钥规格	对称密钥规格：Aliyun_AES_256
密钥用途	Encrypt/Decrypt：密钥的用途，用于数据加密和解密。
密钥别名	密钥的别名标识符。支持英文字母、数字、下划线（_）、短划线（-）和正斜线（/）。
标签	密钥的标签，方便您对密钥进行分类管理。每个标签由一个键值对（Key:Value）组成，包含标签键（Key）、标签值（Value）。说明标签键和标签值的格式：最多支持128个字符，可以包含英文大小写字母、数字、正斜线（/）、反斜线（\）、下划线（_）、短划线（-）、半角句号（.）、加号（+）、等于号（=）、半角冒号（:）、字符at（@）、空格。标签键不能以aliyun或acs:开头。每个密钥最多可以设置20个标签键值对。
描述信息	密钥的说明信息。
高级选项	策略配置：详细信息，请参见密钥策略概述。密钥材料来源：选择外部（导入密钥材料）。说明请仔细阅读并选中我了解使用外部密钥材料的方法和意义。

硬件密钥

登录密钥管理服务控制台，在顶部菜单栏选择地域后，在左侧导航栏单击资源 > 密钥管理。
在用户主密钥页签，实例ID选择硬件密钥管理实例，单击创建密钥。

在创建密钥面板，完成配置项设置，然后单击确定。

配置项	说明
密钥类型	选择对称密钥。重要如果您创建的密钥用于加密凭据值，请选择对称密钥。
密钥规格	对称密钥规格：Aliyun_AES_256、Aliyun_AES_192、Aliyun_AES_128、
密钥用途	密钥的用途。取值： Encrypt/Decrypt：数据加密和解密。 Sign/Verify：产生和验证数字签名。
密钥别名	密钥的别名标识符。支持英文字母、数字、下划线（_）、短划线（-）和正斜线（/）。
标签	密钥的标签，方便您对密钥进行分类管理。每个标签由一个键值对（Key:Value）组成，包含标签键（Key）、标签值（Value）。说明标签键和标签值的格式：最多支持128个字符，可以包含英文大小写字母、数字、正斜线（/）、反斜线（\）、下划线（_）、短划线（-）、半角句号（.）、加号（+）、等于号（=）、半角冒号（:）、字符at（@）、空格。标签键不能以aliyun或acs:开头。每个密钥最多可以设置20个标签键值对。
描述信息	密钥的说明信息。
高级选项	策略配置：详细信息，请参见密钥策略概述。密钥材料来源：选择外部（导入密钥材料）。说明请仔细阅读并选中我了解使用外部密钥材料的方法和意义。

创建完成后，密钥状态为待导入。

步骤二：下载包装公钥和导入令牌

导入密钥材料的参数包含包装公钥和导入令牌，包装公钥用于加密密钥材料，在导入过程中保护您的密钥材料，导入令牌用于导入密钥材料。

定位到目标密钥，单击操作列的详情，在密钥材料区域，单击获取导入参数。

在获取导入密钥材料的参数对话框，选择公钥类型和加密算法，单击下一步。

密钥管理类型	包装公钥类型	加密算法
默认密钥（主密钥）	RSA_2048	RSAES_OAEP_SHA_1 RSAES_OAEP_SHA_256 RSAES_PKCS1_V1_5（不推荐）
软件密钥	RSA_2048	RSAES_OAEP_SHA_256 RSAES_PKCS1_V1_5（不推荐）
硬件密钥	RSA_2048	RSAES_OAEP_SHA_256 RSAES_PKCS1_V1_5（不推荐）

重要

RSAES_PKCS1_V1_5：美国国家标准与技术研究院（National Institute of Standards and Technology，NIST）关于密码算法和密钥长度的使用指导规范Transitioning the Use of Cryptographic Algorithms and Key Lengths中已明确表示2023年12月31日后应停止使用该加密算法用于加密传输密钥。

RSAES_OAEP_SHA_1：RSA加密，按照RFC 3447/PKCS#1中定义的RSAES-OAEP模式，使用MGF1和SHA-1。
RSAES_OAEP_SHA_256：RSA加密，按照RFC 3447/PKCS#1中定义的RSAES-OAEP模式，使用MGF1和SHA-256。

下载包装公钥以及导入令牌，并妥善保存。
- 公钥格式：
  - pem格式：下载后文件名默认为publickey_******.pem。
  - der格式：下载后文件名默认为publickey_******.bin。
- 导入令牌：下载后文件名默认为token_******.txt。
  重要
  - 导入令牌的有效期为24小时，在有效期内可以重复使用，失效后需要获取新的导入令牌和公钥。
  - 包装公钥和导入令牌必须配套使用。即不允许下载两次包装公钥和导入令牌，使用其中一个的包装公钥，另一个的导入令牌。

步骤三：使用包装公钥加密密钥材料

使用步骤二：下载包装公钥和导入令牌下载的包装公钥和指定的包装算法，对密钥材料进行加密。

下面以使用OpenSSL生成密钥材料，并通过RSA公钥、RSAES_OAEP_SHA_256算法加密密钥材料为例。

使用OpenSSL产生一个32字节的随机数，生成一个密钥材料。如果您已有密钥材料，请跳过本步骤。
```
openssl rand -out KeyMaterial.bin 32
```
根据指定的加密算法加密密钥材料。
```
openssl pkeyutl -encrypt -in KeyMaterial.bin -inkey PublicKey.bin -keyform DER -pubin -out EncryptedKeyMaterial.bin -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256 -pkeyopt rsa_mgf1_md:sha256
```
说明
- 示例代码中加密算法使用RSAES_OAEP_SHA_256。
- 示例代码以公钥格式为der格式为例，如果您下载公钥文件时选择了pem格式，需要将示例代码中的-keyform DER替换为-keyform PEM。
- 请将PublicKey.bin替换为步骤二：下载包装公钥和导入令牌中下载的公钥文件名称。
将加密后的密钥材料进行Base64编码，保存为文本文件。
```
openssl enc -e -base64 -A -in EncryptedKeyMaterial.bin -out EncryptedKeyMaterial_base64.txt
```
说明
EncryptedKeyMaterial_base64.txt即为可导入KMS的密钥材料文件。

步骤四：导入密钥材料

在密钥详情页面，单击导入密钥材料，在导入打包后的密钥材料对话框，完成各项配置后，单击确定。

配置项	说明
打包后的密钥材料	上传步骤三：使用包装公钥加密密钥材料中生成的密钥材料文件。
导入令牌	上传步骤二：下载包装公钥和导入令牌中下载的令牌文件。
密钥材料过期时间	支持选择永不过期，也可以自定义过期时间。重要如果设置了密钥材料过期时间，在设置的时间点之后KMS会删除已过期的密钥材料，您将无法使用该密钥材料。如需恢复使用，可以为密钥再次导入相同的密钥材料。

导入密钥材料成功后，密钥状态从待导入更新为启用中。

常见问题

是否支持删除密钥材料？

支持删除。

重要

导入的密钥材料过期或者被删除后，其密钥将无法使用，需要再次导入相同的密钥材料才可正常使用。

直接删除密钥材料
- 控制台：在密钥详情页的密钥材料区域，单击删除密钥材料。
- API接口：调用DeleteKeyMaterial接口删除，该操作不会删除您的密钥。
过期后由KMS删除
在导入密钥材料时设置过期时间，在时间点之后KMS会删除已过期的密钥材料。

如何重新导入相同的密钥材料？

密钥材料过期或删除后，您可以再次导入相同的密钥材料，密钥才可继续使用。

删除过期的密钥材料。
在密钥详情页，单击密钥材料页签，单击删除密钥材料。
重新下载包装公钥和导入令牌。具体操作，请参见步骤二：下载包装公钥和导入令牌。
说明
密钥包装过程不会影响密钥材料的内容，因此，您可以使用不同的包装公钥和不同的包装算法来导入相同的密钥材料。
使用包装公钥加密密钥材料。具体操作，请参见步骤三：使用包装公钥加密密钥材料。
说明
密钥材料必须与之前过期的密钥材料为同一个。
使用导入令牌，导入加密后的密钥材料。具体操作，请参见步骤四：导入密钥材料。

如何判断密钥材料是由外部导入还是由KMS生成？

方式一：在密钥管理服务控制台查看。
- 默认密钥：在密钥管理页面，单击默认密钥页签，定位到目标密钥，单击操作列的详情，在详情页面查看密钥材料来源。
- 软件密钥、硬件密钥：在密钥管理页面，单击用户主密钥页签，选择实例ID后定位到目标密钥，单击操作列的详情，在详情页面查看密钥材料来源。
方式二：通过调用DescribeKey接口查看。
如果Origin值为EXTERNAL，说明密钥材料由外部导入。如果Origin值为Aliyun_KMS，说明密钥材料由KMS生成。

如何轮转使用外部密钥材料的密钥？

对导入外部密钥材料的密钥，KMS不提供定期自动轮转功能。如果您需要轮转，只能创建一个新的密钥然后导入新的密钥材料。

密钥管理服务：导入对称密钥材料