火山引擎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为例进行介绍。 1. 在用户主密钥的操作栏，单击"获取导入参数" 2. 在获取导入参数对话框，选择"公钥类型"和"加密算法"，单击"获取" 3. 下载公钥和导入令牌下载公钥可选公钥格式： * PEM格式：后缀为.pem，例如：publickey_7a20e103\-0871\-437a\-a120\-985102c9c57b.pem * DER格式：后缀为.der，例如：publickey_7a20e103\-0871\-437a\-a120\-985102c9c57b.der **相关API** [GetParametersForImport](https://www.volcengine.com/docs/6476/1337051) **注意事项** * RSA_2048公钥类型，支持 RSAES_OAEP_SHA_256、RSAES_OAEP_SHA_1 加密算法 * EC_SM2公钥类型，支持SM2PKE加密算法 * 导入参数中的公钥和导入令牌必须成对使用 * 在某主密钥下获取的导入参数，不能用于其它主密钥的密钥材料导入 * 导入令牌24小时有效期，有效期内可以重复使用，过期后需要重新获取新的导入参数 ### 加密密钥材料 #### 对称密钥下载公钥和导入令牌后，用户使用公钥加密自己的密钥材料，加密算法需使用获取导入参数时选择的加密算法。本文以OpenSSL加密密钥材料为例，以下命令在OpenSSL3.0+版本上运行通过： 1. 创建一个密钥材料，以SYMMETRIC\_256为例： ```bash openssl rand -out KeyMaterial.bin 32 ``` 2. 使用指定算法RSAES_OAEP_SHA_256加密密钥材料： ```bash 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 3. 如果选择上传Binary格式的密钥材料，可直接上传EncryptedKeyMaterial.bin，如果选择上传Base64格式密钥材料，可进行Base64编码： ```bash openssl enc -e -base64 -A -in EncryptedKeyMaterial.bin -out EncryptedKeyMaterial_base64.txt ``` #### 非对称密钥下载公钥和导入令牌后，用户使用公钥加密自己的密钥材料，加密算法需使用获取导入参数时选择的加密算法。本文以OpenSSL加密密钥材料为例，以下命令在OpenSSL3.0+版本上运行通过： 1. 创建PKCS #8 ASN.1 DER编码格式的私钥，以RSA\_2048为例： ```Bash openssl genpkey -algorithm RSA \ -pkeyopt rsa_keygen_bits:2048 \ -pkeyopt rsa_keygen_pubexp:65537 | \ openssl pkcs8 -topk8 -nocrypt -outform der > keymaterial.p8 ``` 2. 生成用来加密RSA私钥的对称密钥 ```Bash openssl rand -out aeskey.bin 32 ``` 3. 使用对称密钥加密RSA私钥 ```Bash openssl enc -id-aes256-wrap-pad \ -K "$(xxd -p < aeskey.bin | tr -d '\n')" \ -iv A65959A6 \ -in keymaterial.p8 \ -out keymaterial-wrapped.bin ``` 4. 使用指定算法RSAES_OAEP_SHA_256加密对称密钥： ```Bash 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 5. 组合加密的对称密钥与加密的RSA私钥 ```Bash cat aeskey-wrapped.bin keymaterial-wrapped.bin > EncryptedKeyMaterial.bin ``` 6. 如果选择上传Binary格式的密钥材料，可直接上传EncryptedKeyMaterial.bin，如果选择上传Base64格式密钥材料，可进行Base64编码： ```Bash openssl enc -e -base64 -A -in EncryptedKeyMaterial.bin -out EncryptedKeyMaterial_base64.txt ``` ### 导入密钥材料上传加密密钥材料中生成的密钥材料文件和获取导入参数中获取的导入令牌文件完成导入： 1. 在用户主密钥的操作栏，单击**导入密钥材料** 2. 在导入密钥材料对话框，上传**密钥材料**和**导入令牌**，选择**密钥材料过期时间**，单击**导入** **注意事项** 非对称密钥导入到CloudKMS中的私钥必须采用PKCS #8 ASN.1 DER编码格式进行格式化。注：在功能验证阶段，您可以使用 [ASN.1 JavaScript decoder](https://lapo.it/asn1js/#) 检查密钥格式，不建议在未了解功能详情时直接在火山站点上使用自己的生产私钥。 Example of RSA 2048 PKCS#8 ASN.1 DER private key in Base64: ```bash 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： ```bash MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgDwgzMkOu2yCJekAO70mYCUS0mySg9KW95Fd1pVdUybChRANCAASvXfyC9XmUlW6Kq4TQXHJiUcg4CtlzEj9I+RlkQo6wQWLTFjBW9b6VUFwNwC56yDN7QDN+yndS9pgUh5+kxEom ``` 用户可以在控制台内上传以base64或二进制格式加密的私钥。对于使用OpenAPI的用户，必须以base64格式上传加密的私钥。 **相关API** [ImportKeyMaterial](https://www.volcengine.com/docs/6476/1337050) ## 步骤三：删除密钥材料用户可以直接删除密钥材料，删除密钥材料后，主密钥状态变更为待导入（若当前主密钥状态为计划删除中，删除密钥材料不会变更主密钥状态），此状态下主密钥将无法用于数据加解密。用户可以再次导入相同的密钥材料，重新启用主密钥，建议用户自行保存密钥材料的副本。 1. 在用户主密钥的操作栏，单击**删除密钥材料** 2. 在删除密钥材料确认框中，单击**确认** **相关API** [DeleteKeyMaterial](https://www.volcengine.com/docs/6476/1337049)

密钥管理系统