导入密钥材料

约束条件

• HMAC密钥算法不支持导入密钥材料。
• 副本密钥在创建时会同步主密钥的密钥材料，密钥材料过期后，需在各区域重新独立导入密钥材料。
• 需要创建一个密钥材料来源为外部的空密钥，创建操作参见创建密钥。

操作步骤

1. 登录管理控制台。
2. 单击管理控制台左上角，选择区域或项目。
3. 单击页面左侧，选择“安全与合规 > 数据加密服务”，默认进入“密钥管理”界面。
4. 单击“导入密钥”，弹出“导入密钥”对话框。
5. 在弹出的对话框中填写密钥参数。
   图1 创建空密钥
   
   • 密钥名称：待创建的密钥的名称。
     

     • 输入字符支持数字、字母、“_”、“-”、“:”和“/”。
     • 支持长度为1 ~ 255个字符。
   • 密钥算法：选择密钥算法。KMS支持的密钥算法说明如表1所示。

     表1 KMS支持的密钥算法类型

     密钥类型	算法类型	密钥规格	说明	用途
     对称密钥	AES	AES_256	AES对称密钥	小量数据的加解密或用于加解密数据密钥。
     对称密钥	SM4	SM4	国密SM4对称密钥	小量数据的加解密或用于加解密数据密钥。
     非对称密钥	RSA	RSA_2048 RSA_3072 RSA_4096	RSA非对称密钥	小量数据的加解密或数字签名。
     	ECC	EC_P256 EC_P384	椭圆曲线密码，使用NIST推荐的椭圆曲线	数字签名
     非对称密钥	SM2	SM2	国密SM2非对称密钥	小量数据的加解密或数字签名。

   • 密钥用途：可选择“SIGN_VERIFY”、“ENCRYPT_DECRYPT”、“GENERATE_VERIFY_MAC”。
     • 对于AES_256对称密钥，默认值“ENCRYPT_DECRYPT”。
     • 对于HMAC对称密钥，默认值“GENERATE_VERIFY_MAC”。
     • 对于RSA非对称密钥，可选择“ENCRYPT_DECRYPT”或“SIGN_VERIFY”，省略参数为默认值“SIGN_VERIFY”。
     • 对于ECC非对称密钥，默认值“SIGN_VERIFY”。
     • 对于SM2非对称密钥，可选择“ENCRYPT_DECRYPT”或“SIGN_VERIFY”，省略参数为默认值“SIGN_VERIFY”。
     

     创建密钥时请选择“密钥用途”，密钥创建后不可修改。

   • （可选）描述：可根据自己的需要为自定义密钥添加描述。
     

     支持长度为1 ~ 255个字符。

   • 企业项目：该参数针对企业用户使用。

     如果您是企业用户，且已创建企业项目，则请从下拉列表中为密钥选择需要绑定的企业项目，默认项目为“default”。

     未开通企业管理的用户页面则没有“企业项目”参数项，无需进行配置。

     

     • 企业项目是一种云资源管理方式，企业项目管理服务提供统一的云资源按项目管理，以及项目内的资源管理、成员管理。更多关于企业项目的信息，请参见《什么是企业项目管理？》。
     • 如需开通企业项目，请参考如何开通企业项目/企业多账号。

6. （可选）用户可根据自己的需要为自定义密钥添加标签，输入“标签键”和“标签值”。
   

   • 当用户在创建密钥时，没有为该自定义密钥添加标签。如果用户需要为该自定义密钥添加标签，可单击该自定义密钥的别名，进入密钥详情页面，单击“标签”，为该自定义密钥添加标签。
   • 同一个自定义密钥下，一个标签键只能对应一个标签值；不同的自定义密钥下可以使用相同的标签键。
   • 用户最多可以给单个自定义密钥添加20个标签。
   • 当同时添加多个标签，需要删除其中一个待添加的标签时，可单击该标签所在行的“删除”，删除标签。

7. 单击“安全性与持久性”阅读并了解导入密钥的安全性和持久性。
8. 勾选“我已经了解导入密钥的安全性和持久性”，创建密钥材料为空的自定义密钥。
9. 单击“下一步”，进入“获取包装密钥和导入令牌”页面。根据表 密钥包装算法说明选择密钥包装算法。
   图2 获取包装密钥和导入令牌
   

   表2 密钥包装算法说明

   密钥包装算法	说明	设置
   RSAES_OAEP_SHA_256	具有“SHA-256”哈希函数的OAEP的RSA加密算法。	请您根据自己的HSM功能选择加密算法。 如果您的HSM支持“RSAES_OAEP_SHA_256”加密算法，推荐使用“RSAES_OAEP_SHA_256”加密密钥材料。
   SM2_ENCRYPT	国密推荐的SM2椭圆曲线公钥密码算法。	请在支持国密的局点使用SM2加密算法。

   

   当用户执行“导入密钥”操作，但未成功导入密钥材料便退出操作过程时，可在待导入密钥材料的自定义密钥所在行单击“导入密钥材料”，页面会弹出“导入密钥材料”对话框，用户可继续执行导入密钥材料的操作。

10. 获取“包装密钥”和“导入令牌”，并加密密钥材料，如果您已有密钥材料，可跳过本步骤。
    1. 获取“包装密钥”和“导入令牌”。
       • 方法一：单击“下载并继续”，下载的文件为包装密钥，如图 下载文件所示。
         图3 下载文件
         
         • wrappingKey_密钥ID：即包装密钥，编码为二进制格式，用于加密密钥材料的包装密钥。
         • 导入令牌：引导程序自动传递导入令牌，无需下载，如果中途退出引导程序，导入令牌将自动失效。
         

         包装密钥将在24小时后失效，失效后将不能使用。如果包装密钥失效，请重新下载包装密钥。

         引导程序将自动传递导入令牌，如果创建密钥过程中，关闭或者退出设置则导入令牌失效。重新发起导入密钥材料操作时，导入令牌引导程序自动启动。

       • 方法二：通过调用API接口的方式获取包装密钥和导入令牌。
         1. 调用“get-parameters-for-import”接口，获取包装密钥和导入令牌。
            • public_key：调用API接口返回的base64编码的包装密钥内容。
            • import_token：调用API接口返回的base64编码的导入令牌内容。
            以获取密钥ID为“43f1ffd7-18fb-4568-9575-602e009b7ee8”，加密算法为“RSAES_OAEP_SHA_256”的包装密钥和导入令牌为例。

            • 请求样例

              {      
                  "key_id": "43f1ffd7-18fb-4568-9575-602e009b7ee8",
                  "wrapping_algorithm":"RSAES_OAEP_SHA_256"
              }

            • 响应样例

              {
                  "key_id": "43f1ffd7-18fb-4568-9575-602e009b7ee8",    
                  "public_key":"public key base64 encoded data",
                  "import_token":"import token base64 encoded data",
                  "expiration_time":1501578672
              }

         2. 保存包装密钥，包装密钥需要按照以下步骤转换格式。使用转换格式后的包装密钥加密的密钥材料才能成功导入管理控制台。
            1. 复制包装密钥“public_key”的内容，粘贴到“.txt”文件中，并保存为“PublicKey.b64”。
            2. 使用OpenSSL，执行以下命令，对“PublicKey.b64”文件内容进行base64转码，生成二进制数据，并将转码后的文件保存为“PublicKey.bin”。

               openssl enc -d -base64 -A -in PublicKey.b64 -out PublicKey.bin

         3. 保存导入令牌，复制导入令牌“import_token”的内容，粘贴到“.txt”文件中，并保存为“ImportToken.b64”。
    2. 使用“包装密钥”加密密钥材料。
       

       执行完此步骤后可获得以下文件：

       对称密钥场景：EncryptedKeyMaterial.bin密钥材料

       非对称密钥场景：EncryptedKeyMaterial.bin临时密钥材料和out_rsa_private_key.der/out_sm2_private_key私钥密文

       方法一：使用下载的包装密钥在自己的HSM中加密密钥材料，详细信息请参考您的HSM操作指南。

       方法二：使用OpenSSL生成密钥材料，并用下载的“包装密钥”对密钥材料进行加密。

       

       如果用户需要使用openssl pkeyutl命令，OpenSSL需要是1.0.2及以上版本。

       如果用户使用SM2公钥包装，需要支持gmssl命令。

       1. 生成密钥材料（256位对称密钥），并将生成的密钥材料以“PlaintextKeyMaterial.bin”命名保存。
          • 配套算法为AES256对称密钥时，在已安装OpenSSL工具的客户端上，执行以下命令。

            openssl rand -out PlaintextKeyMaterial.bin 32

          • 配套算法为SM4国密时，在已安装OpenSSL工具的客户端上，执行以下命令。

            openssl rand -out PlaintextKeyMaterial.bin 16

          • 配套算法为RSA、ECC非对称密钥时，在已安装OpenSSL工具的客户端上，执行以下命令。
            1. 生成16进制AES256密钥：

               openssl rand -out 0xPlaintextKeyMaterial.bin -hex 32

            2. 将16进制AES256密钥转换成二进制格式：

               cat 0xPlaintextKeyMaterial.bin | xxd -r -ps > PlaintextKeyMaterial.bin

          • 配套算法为SM2非对称密钥时，在已安装OpenSSL工具的客户端上，执行以下命令。
            1. 生成16进制SM4密钥：

               openssl rand -out 0xPlaintextKeyMaterial.bin -hex 16

            2. 将16进制SM4密钥转换成二进制格式：

               cat 0xPlaintextKeyMaterial.bin | xxd -r -ps > PlaintextKeyMaterial.bin

       2. 使用下载的“包装密钥”加密密钥材料，并将加密后的密钥材料按“EncryptedKeyMaterial.bin”命名保存。

          如果“包装密钥”由控制台下载，以下命令中的PublicKey.bin参数请以下载的包装密钥名称wrappingKey_密钥ID进行替换。

          表3 使用下载的包装密钥加密生成的密钥材料

          包装密钥算法	加密生成的密钥材料
          RSAES_OAEP_SHA_256	openssl pkeyutl -in PlaintextKeyMaterial.bin -inkey PublicKey.bin -out EncryptedKeyMaterial.bin -keyform der -pubin -encrypt -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256
          SM2_ENCRYPT	gmssl pkeyutl -encrypt -pkeyopt ec_scheme:sm2 -pkeyopt ec_encrypt_param:sm3 -in PlaintextKeyMaterial.bin -pubin -inkey PublicKey.bin -keyform der -out EncryptedKeyMaterial.bin

       3. （可选）对于导入非对称密钥的场景，需要生成非对称私钥，并使用临时密钥材料（“ EncryptedKeyMaterial.bin”）对私钥进行加密，加密后的文件作为“私钥密文”导入。
          • 执行以下命令（以配套算法为“RSA4096算法”为例）：
            1. 生成私钥

               openssl genrsa -out pkcs1_rsa_private_key.pem 4096

            2. 格式转换成pkcs8格式

               openssl pkcs8 -topk8 -inform PEM -in pkcs1_rsa_private_key.pem -outform pem -nocrypt -out rsa_private_key.pem

            3. pkcs8格式转换成der格式

               openssl pkcs8 -topk8 -inform PEM -outform DER -in rsa_private_key.pem -out rsa_private_key.der -nocrypt

            4. 使用临时密钥材料对私钥进行加密

               openssl enc -id-aes256-wrap-pad -K $(cat 0xPlaintextKeyMaterial.bin) -iv A65959A6 -in rsa_private_key.der -out out_rsa_private_key.der

               

               默认情况下，OpenSSL命令行工具中未启用包装密码算法-id-aes256-wrap-pad。您可以下载并安装最新版本的OpenSSL，然后对其进行修补，以完成导入非对称密钥所需的信封包装。修补方式可以参考常见问题。

          • （可选）对于使用SM4临时密钥材料加密SM2私钥（以sm2p256v1为例）的场景，参考如下步骤：
            1. 生成私钥

               openssl genrsa -out pkcs1_rsa_private_key.pem 4096

            2. 格式转换成pkcs8格式

               openssl pkcs8 -topk8 -inform PEM -in pkcs1_rsa_private_key.pem -outform pem -nocrypt -out rsa_private_key.pem

            3. 转换成der格式

               gmssl pkcs8 -topk8 -inform PEM -outform DER -in sm2_private_key.pem -out sm2_private_key.der -nocrypt

            4. 使用临时密钥材料对私钥进行加密

               gmssl enc -sms4-wrap-pad -K $(cat 0xPlaintextKeyMaterial.bin) -iv A65959A6 -in sm2_private_key.der -out out_sm2_private_key.der

               

               默认情况下，GmSSL命令行工具中未启用包装密码算法-sms4-wrap-pad。您可以下载并安装最新版本的GmSSL，然后对其进行修补，以完成导入非对称密钥所需的信封包装。修补方式可以参考常见问题。

11. 已有密钥材料时，单击“已有密钥材料”，进入“导入密钥材料”页面。

    表4 导入密钥材料参数说明（对称密钥场景）

    参数	说明
    密钥ID	创建密钥时，随机生成的密钥ID。
    密钥材料	导入密钥材料。 例如：使用10.b.ii中“EncryptedKeyMaterial.bin”文件。

    表5 导入密钥材料参数说明（非对称密钥场景）

    参数	说明
    密钥ID	创建密钥时，随机生成的密钥ID。
    临时密钥材料	选择导入临时密钥材料。 例如：选择10.b.ii中“EncryptedKeyMaterial.bin”文件。
    私钥密文	选择导入私钥密文。 例如：选择10.b.iii中“out_rsa_private_key.der/out_sm2_private_key”文件。

    图4 导入密钥材料
    

12. 单击“下一步”，进入“密钥导入令牌”页面。根据表6设置参数。
    图5 导入密钥令牌
    

    表6 导入密钥令牌参数说明

    参数	操作说明
    密钥ID	创建密钥时，随机生成的密钥ID。
    密钥导入令牌	选择12.b调用API获取的导入令牌。
    密钥材料失效模式	永不失效：导入的密钥材料永久不失效。 失效时间：用户可指定导入的密钥材料的失效时间，默认失效时间为24小时。 密钥材料失效后，KMS会在24小时内自动删除密钥材料，删除后密钥将无法使用，且密钥状态变更为“等待导入”。

13. 单击“确定”，页面右上角弹出“密钥导入成功”，则说明导入密钥成功。
    

    密钥ID、导入的密钥材料和导入的令牌需要全部匹配，密钥材料才能导入成功，否则会导入失败。

    用户可在密钥列表中查看到导入的密钥信息，导入密钥的默认状态为“启用”。