自带密钥

火山引擎KMS支持自带密钥（Bring Your Own Key，简称BYOK），用户可以将自己的密钥材料导入到用户主密钥中托管。

创建主密钥

用户使用 CreateKey 接口创建托管用户主密钥时，需指定密钥来源为External（外部），此时火山引擎KMS会为用户创建主密钥，但不会生成主密钥的密钥材料。密钥来源为外部的主密钥初始状态为待导入，用户可以将自己的密钥材料导入到该用户主密钥中，导入成功后，主密钥状态变更为启用中。

注意事项

用户使用由外部导入的密钥材料时，需要注意以下几点：

• 使用符合要求的随机源生成密钥材料
• 只能导入256位（SYMMETRIC_256）或者128位（SYMMETRIC_128）的对称密钥作为密钥材料
• 每个主密钥只能拥有一个导入密钥材料，当用户首次导入成功后，主密钥将与密钥材料绑定，即使密钥材料过期或被删除，也不能导入其它密钥材料
• 主密钥之间相互独立，使用某主密钥加密的数据，无法通过其它主密钥解密，即使这些主密钥的密钥材料相同
• 导入密钥材料时可以设置密钥材料的过期时间，过期后会删除密钥材料，用户也可以主动删除密钥材料，当密钥材料过期或被删除时，主密钥不会被删除
• 当密钥材料过期或被删除后，用户可以导入相同的密钥材料，用户需要自行保存密钥材料的副本
• 外部密钥材料的主密钥不支持自动轮转，如果用户需要轮转，只能创建新的主密钥然后导入新的密钥材料

导入密钥材料

1. 获取导入参数

导入密钥材料的参数包含一个加密密钥材料的公钥和一个导入令牌，本文以公钥类型RSA_2048、加密算法RSAES_OAEP_SHA_256为例进行介绍。
i. 在用户主密钥的操作栏，单击"获取导入参数"

ii. 在获取导入参数对话框，选择"公钥类型"和"加密算法"，单击"获取"

iii. 下载公钥和导入令牌
下载公钥可选公钥格式：

• PEM格式：后缀为.pem，例如：publickey_7a20e103-0871-437a-a120-985102c9c57b.pem
• DER格式：后缀为.der，例如：publickey_7a20e103-0871-437a-a120-985102c9c57b.der

相关API
GetParametersForImport

注意事项

• 用户主密钥的保护级别为SOFTWARE时，支持RSA_2048公钥类型；用户主密钥的保护级别为HSM时，支持RSA_2048、EC_SM2公钥类型
• RSA_2048公钥类型，支持RSAES_OAEP_SHA_256、RSAES_OAEP_SHA_1、RSAES_PKCS1_V1_5加密算法
• EC_SM2公钥类型，支持SM2PKE加密算法
• 导入参数中的公钥和导入令牌必须成对使用
• 在某主密钥下获取的导入参数，不能用于其它主密钥的密钥材料导入
• 导入令牌24小时有效期，有效期内可以重复使用，过期后需要重新获取新的导入参数

2. 加密密钥材料

下载公钥和导入令牌后，用户使用公钥加密自己的密钥材料，加密算法需使用获取导入参数时选择的加密算法。本文以OpenSSL加密密钥材料为例，以下命令在OpenSSL3.0+版本上运行通过：
i. 创建一个密钥材料，以SYMMETRIC_256为例：

openssl rand -out KeyMaterial.bin 32

ii. 使用指定算法RSAES_OAEP_SHA_256加密密钥材料：

openssl pkeyutl \
    -in KeyMaterial.bin \
    -out EncryptedKeyMaterial.bin \
    -inkey PublicKey.der \
    -keyform DER -pubin \
    -encrypt \
    -pkeyopt rsa_padding_mode:oaep \
    -pkeyopt rsa_oaep_md:sha256

• PublicKey.der替换成获取导入参数中下载的公钥
• 示例以DER格式的公钥为例，如果下载了PEM格式，需替换-keyform DER为-keyform PEM

iii. 如果选择上传Binary格式的密钥材料，可直接上传EncryptedKeyMaterial.bin，如果选择上传Base64格式密钥材料，可进行Base64编码：

openssl enc -e -base64 -A -in EncryptedKeyMaterial.bin -out EncryptedKeyMaterial_base64.txt

3. 导入密钥材料

上传加密密钥材料中生成的密钥材料文件和获取导入参数中获取的导入令牌文件完成导入：
i. 在用户主密钥的操作栏，单击"导入密钥材料"

ii. 在导入密钥材料对话框，上传"密钥材料"和"导入令牌"，选择"密钥材料过期时间"，单击"导入"

相关API
ImportKeyMaterial

删除密钥材料

用户可以直接删除密钥材料，删除密钥材料后，主密钥状态变更为待导入（若当前主密钥状态为计划删除中，删除密钥材料不会变更主密钥状态），此状态下主密钥将无法用于数据加解密。用户可以再次导入相同的密钥材料，重新启用主密钥，建议用户自行保存密钥材料的副本。
i. 在用户主密钥的操作栏，单击"删除密钥材料"

ii. 在删除密钥材料确认框中，单击"确认"

相关API
DeleteKeyMaterial