文档中心

密钥管理系统

密钥管理

自带密钥

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

支持导入的密钥类型

密钥种类	密钥规格	密钥用途	密钥保护级别	密钥长度
对称密钥	SYMMETRIC_256	ENCRYPT_DECRYPT	SOFTWARE / HSM	256
对称密钥		SYMMETRIC_128	ENCRYPT_DECRYPT	HSM	128
非对称密钥	RSA_2048	ENCRYPT_DECRYPT、SIGN_VERIFY	SOFTWARE / HSM	2048
		RSA_3072	ENCRYPT_DECRYPT、SIGN_VERIFY	SOFTWARE / HSM	3072
		RSA_4098	ENCRYPT_DECRYPT、SIGN_VERIFY	SOFTWARE / HSM	4098
		EC_P256K	SIGN_VERIFY	SOFTWARE / HSM	256
		EC_P256	SIGN_VERIFY	SOFTWARE / HSM	256
		EC_P384	SIGN_VERIFY	SOFTWARE / HSM	384
		EC_P521	SIGN_VERIFY	SOFTWARE / HSM	521
		EC_SM2	ENCRYPT_DECRYPT、SIGN_VERIFY	HSM	256

步骤一：创建主密钥

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

注意事项

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

使用符合要求的随机源生成密钥材料

每个主密钥只能拥有一个导入密钥材料，当用户首次导入成功后，主密钥将与密钥材料绑定，即使密钥材料过期或被删除，也不能导入其它密钥材料

主密钥之间相互独立，使用某主密钥加密的数据，无法通过其它主密钥解密，即使这些主密钥的密钥材料相同

导入密钥材料时可以设置密钥材料的过期时间，过期后会删除密钥材料，用户也可以主动删除密钥材料，当密钥材料过期或被删除时，主密钥不会被删除

当密钥材料过期或被删除后，用户可以导入相同的密钥材料，用户需要自行保存密钥材料的副本

外部密钥材料的主密钥不支持自动轮转，如果用户需要轮转，只能创建新的主密钥然后导入新的密钥材料

步骤二：导入密钥材料

获取导入参数

导入密钥材料的参数包含一个加密密钥材料的公钥和一个导入令牌，本文以公钥类型RSA_2048、加密算法RSAES_OAEP_SHA_256为例进行介绍。

在用户主密钥的操作栏，单击"获取导入参数"

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

下载公钥和导入令牌

下载公钥可选公钥格式：

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

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

相关API

GetParametersForImport

注意事项

RSA_2048公钥类型，支持 RSAES_OAEP_SHA_256、RSAES_OAEP_SHA_1 加密算法

EC_SM2公钥类型，支持SM2PKE加密算法

导入参数中的公钥和导入令牌必须成对使用

在某主密钥下获取的导入参数，不能用于其它主密钥的密钥材料导入

导入令牌24小时有效期，有效期内可以重复使用，过期后需要重新获取新的导入参数

加密密钥材料

对称密钥

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

创建一个密钥材料，以SYMMETRIC\_256为例：

openssl rand -out KeyMaterial.bin 32

使用指定算法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

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

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

非对称密钥

创建PKCS #8 ASN.1 DER编码格式的私钥，以RSA\_2048为例：

openssl genpkey -algorithm RSA \​
    -pkeyopt rsa_keygen_bits:2048 \​
    -pkeyopt rsa_keygen_pubexp:65537 | \​
openssl pkcs8 -topk8 -nocrypt -outform der > keymaterial.p8​

生成用来加密RSA私钥的对称密钥

openssl rand -out aeskey.bin 32

使用对称密钥加密RSA私钥

openssl enc -id-aes256-wrap-pad \​
        -K "$(xxd -p < aeskey.bin | tr -d '\n')" \​
        -iv A65959A6 \​
        -in keymaterial.p8 \​
        -out keymaterial-wrapped.bin​

使用指定算法RSAES_OAEP_SHA_256加密对称密钥：

openssl pkeyutl \​
    -encrypt \​
    -in aeskey.bin \​
    -out aeskey-wrapped.bin \​
    -inkey pubkey.der \​
    -keyform der \​
    -pubin \​
    -pkeyopt rsa_padding_mode:oaep \​
    -pkeyopt rsa_oaep_md:sha256 \​
    -pkeyopt rsa_mgf1_md:sha256​

PublicKey.der替换成获取导入参数中下载的公钥

示例以DER格式的公钥为例，如果下载了PEM格式，需替换-keyform DER为-keyform PEM

组合加密的对称密钥与加密的RSA私钥

cat aeskey-wrapped.bin keymaterial-wrapped.bin > EncryptedKeyMaterial.bin

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

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

导入密钥材料

上传加密密钥材料中生成的密钥材料文件和获取导入参数中获取的导入令牌文件完成导入：

在用户主密钥的操作栏，单击导入密钥材料

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

注意事项

非对称密钥导入到CloudKMS中的私钥必须采用PKCS #8 ASN.1 DER编码格式进行格式化。

注：在功能验证阶段，您可以使用 ASN.1 JavaScript decoder 检查密钥格式，不建议在未了解功能详情时直接在火山站点上使用自己的生产私钥。

Example of RSA 2048 PKCS#8 ASN.1 DER private key in Base64:

MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDTmr8aEJbDU4KAQEFt6gSKFIBvKZfUM0WnwPB/zKB3PDuLc4+se776zs5sB4lggKT7JHFuLHPodTJrVT9iA8cxfXznrXCk0Ti1d01gqf6iPQOqC9bLnDMOj+2Jfzz0TeNyf10al/545CgYVW6y58WspdbRuL7BHxiqW7LV0DjaO7nwc1IHfwW/vqU5jiiz6GYpGyipNUCHC4tYW+U5n24MvcuI8ekAVhdJSeodSt/A9llAdQryJHCWv23p4eH7MlGxBlt6PZJmuarfVSgCHYbteiDGWQgp9xlS/gaWUvKqVoOVCUCKaGEdliQok8QcxZRw87ejzbXX0q1eW4B4SI1/AgMBAAECggEAWU2dKjhnEC8ty8eSdXtGiCnH3GI+4AD1fCtKtHzdGgUzEhLmx0IAYyQlbOUvXqlcN1t1faxIDIptiWvUUJ7Mkb/ml3YUrJJZ7wfXAZ0syDac1caiU5Lr31DxzE4FIQvAGmHTHraX4FhV7ZMcoWd8fvUMeL0R0Do59Ce4DVGPtNWsioP2OKlZrEEYxlzPZsIYzne+8rhj/jsKxudyj21sN8mAY0FCRoeytkIroCYG0TaIGfm4J20HYunFDmUt4cZVQsgoIzpZrvs20JI+3qtrlWzAj89RZ4fH7CN1er1HCeb3jptZKwKx2qQyhTA6NDhxuzPH90l7zsuhLDMXuL4kXQKBgQDutyY88W2mpwgPY4VyAcIXojLCEp9aOplVajRNR9aK/Ti958nvYqFWoe7+QSwsFVrOTkyIUxqY8mv3aFg9nczWNoNFRGdD3zfjkbp17yec8QOq+yaQWyoBamyytJVmuJjjZUZWeUrQ5Q4YEUDCjYbfyx/mp9Zxwj3vGU2wZt5IvQKBgQDi7RDuhWB0PrSfcHTCFZ8Co3dHHndLI4pAnKawaca+Lw1RvqqvNNkVb87SpO0wRNoKDOUmfitrV0n9bOsWraam1gY8nQsdwMvb1/fEbKMGxxFfp0bWgTaRUkmzdGxOcV49tGuTF4kdyfiZp3Yu/LrSLUaeUCNZpck9+2mtP9to6wKBgFFESqE+s8yjWowanmh0jsYK8uq8+kD2aBL7B/kzNqe0kyebjFSRqElc8YbfWxFa58IKR+W1HP3qsbTVcgzv9rcKceAX7GvfxyATEX5qv3qfVldUDwnf70nyGDUyYxZIS8xGQw7XVhANmqG45eoV0k/H0AFvLAMoVHtciuU97/ilAoGBAKlrdsWtfHqtSirzSaiRfdr5chb9zvChQxnEGssA3emltVr/b+1JFn3jsNUhXxg3f1YblIWtkvsb+1iilc2jrhVHGvbsBJ2dEFY9InVa6kgoHXd9quyBId1TQ0Ugua/DAiotZlc2Lh+4Z8tH9HtWIqDCPsP5brsChIGrD5XSZBwrAoGAUAIw4qr0FpFGpDYkLYY03k614kmDJskFG+jO2RdXQc58HK5QvkhquMoT12mASfMknb2Kn5su4iGB8uirjMCtdVeQK0ztjmmWUhJsu5VsA1Dn5dQeBhpUikXR5flgdzLmJqIFtHLgx0EqNusO4iuUrl20ftGyZK4k8aysfhYbPq8=​

Example of ECC 256 PKCS#8 ASN.1 DER private key in Base64：

MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgDwgzMkOu2yCJekAO70mYCUS0mySg9KW95Fd1pVdUybChRANCAASvXfyC9XmUlW6Kq4TQXHJiUcg4CtlzEj9I+RlkQo6wQWLTFjBW9b6VUFwNwC56yDN7QDN+yndS9pgUh5+kxEom​

用户可以在控制台内上传以base64或二进制格式加密的私钥。对于使用OpenAPI的用户，必须以base64格式上传加密的私钥。