# 导入外部密钥 在密钥管理场景中，部分用户出于安全合规、数据主权或业务定制化需求，可能希望使用自身生成并保管的密钥材料，而非直接采用 KMS 系统自动生成的密钥材料。针对这类需求，平台支持用户通过密钥管理界面，将自有密钥材料安全导入至KMS服务中，由KMS对导入的密钥材料进行统一的生命周期管理、权限控制和安全运维，从而在满足自主可控要求的同时，享受KMS提供的密钥安全存储、访问审计、加密解密等标准化能力。 本任务将详细指导用户如何通过密钥管理界面，完成自有密钥材料的导入与配置操作。 #### 约束条件 - 摘要密钥HMAC密钥算法不支持导入密钥材料，非对称密钥不支持重置密钥材料。 - 副本密钥在创建时会同步主密钥的密钥材料，密钥材料过期后，需在各区域重新独立导入密钥材料。 #### 注意事项 导入的密钥材料需要注意以下事项： - 安全性 用户需要确保符合自己安全要求的随机源生成密钥材料。用户在使用导入密钥材料时，需要对自己密钥材料的安全性负责。请保存密钥材料的原始备份，以便在意外重置密钥材料时，能及时将备份的密钥材料重新导入KMS。 - 可用性与持久性 在将密钥材料导入KMS之前，用户需要确保密钥材料的可用性和持久性。 - 关联性 当用户将密钥材料导入自定义密钥时，该自定义密钥与该密钥材料永久关联，不能将其他密钥材料导入该自定义密钥中。 - 唯一性 当用户使用导入的密钥加密数据时，加密后的数据必须使用加密时采用的自定义密钥（即自定义密钥的元数据及密钥材料与导入的密钥匹配）才能解密数据，否则解密会失败。 #### 操作流程 | 场景 | 操作步骤 | |:---|:---| | 已有密钥材料 | 1. [创建托管类型为外部BYOK的密钥]：创建一个托管类型为外部BYOK的空密钥。 2. [导入密钥材料（导入已有密钥材料）]：导入密钥材料、导入令牌到创建的空密钥。 | | 通过调用API接口下载密钥材料 | 1. [创建托管类型为外部BYOK的密钥]：创建一个托管类型为外部BYOK的空密钥。 2. [下载包装密钥和导入令牌（通过调用API接口下载）]：通过调用API接口下载包装密钥、导入令牌。 3. [使用包装密钥加密密钥材料]：使用HSM或OpenSSL，将包装密钥加密为密钥材料。 4. [导入密钥材料（导入已有密钥材料）]：导入密钥材料、导入令牌到创建的空密钥。 | | 通过KMS控制台下载密钥材料 | 1. [创建托管类型为外部BYOK的密钥]：创建一个托管类型为外部BYOK的空密钥。 2. [下载包装密钥和导入令牌（通过KMS控制台下载）]：通过KMS控制台下载包装密钥。导入令牌由控制台自动引导。 须知： 下载包装密钥后，请勿关闭或中途退出"导入密钥材料"对话框，加密密钥材料后，需要继续在该对话框，执行[导入密钥材料（继续导入密钥材料）]。 3. [使用包装密钥加密密钥材料]：使用HSM或OpenSSL，将包装密钥加密为密钥材料。 4. [导入密钥材料（继续导入密钥材料）]：导入密钥材料到创建的空密钥。 | #### 导入外部密钥 导入外部密钥的步骤如下。 #### 步骤一：创建托管类型为外部BYOK的密钥 1. [登录DEW服务控制台](https://console.huaweicloud.com/dew/?locale=zh-cn#/dew/)。 2. 单击管理控制台左上角![](https://support.huaweicloud.com/usermanual-dew/zh-cn_image_0000002259682412.png)，选择区域或项目。 3. 单击界面右上角"创建密钥"，创建一个"托管类型"为"外部BYOK"的空密钥。 #### 步骤二：下载包装密钥和导入令牌 密钥管理提供两种下载方式： - 通过调用API接口下载：获取到包装密钥、导入令牌。 - 通过KMS控制台下载：获取到包装密钥。导入令牌将由控制台自动传递。因此，下载密钥材料后，请勿关闭或中途退出"导入密钥材料"对话框，否则将导致导入的令牌自动失效。 - [通过调用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"。 - [通过KMS控制台下载] 1. [登录DEW服务控制台](https://console.huaweicloud.com/dew/?locale=zh-cn#/dew/)。 2. 单击管理控制台左上角![](https://support.huaweicloud.com/usermanual-dew/zh-cn_image_0000002259682412.png)，选择区域或项目。 3. 在"自定义密钥"页签，定位到[步骤一：创建托管类型为外部BYOK的密钥]创建的密钥，单击"操作"列的"导入密钥材料"。 4. 在"获取包装密钥和导入令牌"配置项，根据[表 密钥包装算法说明]，选择密钥包装算法。 图1获取包装密钥和导入令牌 ![](https://support.huaweicloud.com/usermanual-dew/zh-cn_image_0000002532710756.png "点击放大") 表1密钥包装算法说明 | 密钥包装算法 | 说明 | 设置 | |:---|:---|:---| | RSAES_OAEP_SHA_256 | 具有"SHA-256"哈希函数的OAEP的RSA加密算法。 | 请您根据自己的HSM功能选择加密算法。 如果您的HSM支持"RSAES_OAEP_SHA_256"加密算法，推荐使用"RSAES_OAEP_SHA_256"加密密钥材料。 | | SM2_ENCRYPT | 国密推荐的SM2椭圆曲线公钥密码算法。 | 请在支持国密的局点使用SM2加密算法。 | 5. 单击"下载密钥材料"，下载的文件为包装密钥，如[图 下载文件]所示。 图2下载文件 ![](https://support.huaweicloud.com/usermanual-dew/zh-cn_image_0000002294275689.png) - wrappingKey_*密钥ID*：即包装密钥，编码为二进制格式，用于加密密钥材料的包装密钥。 - 导入令牌：引导程序自动传递导入令牌，无需下载，如果中途退出引导程序，导入令牌将自动失效。 ![](https://support.huaweicloud.com/usermanual-dew/public_sys-resources/notice_3.0-zh-cn.png) 包装密钥将在24小时后失效，失效后将不能使用。如果包装密钥失效，请重新下载包装密钥。 控制台将自动传递导入令牌。因此，下载密钥材料后，请勿关闭或中途退出"导入密钥材料"对话框，否则将导致导入的令牌自动失效。 下载包装密钥后，需要[使用包装密钥加密密钥材料]，然后继续在"导入密钥材料"对话框，导入密钥材料。具体操作，请参见[继续导入密钥材料]。 #### 步骤三：使用包装密钥加密密钥材料 对称密钥和非对称密钥加密方式不同，生成的密钥材料也不同： - 对称密钥：密钥材料为"EncryptedKeyMaterial.bin"。 - 非对称密钥：密钥材料为"EncryptedKeyMaterial.bin"临时密钥材料、"out_rsa_private_key.der/out_sm2_private_key"私钥密文。 - [对称密钥] - **方法一**：使用下载的包装密钥在自己的HSM中加密密钥材料，详细信息请参考您的HSM操作指南。 - **方法二** ：使用OpenSSL生成密钥材料，并用下载的"包装密钥"对密钥材料进行加密。 ![](https://support.huaweicloud.com/usermanual-dew/public_sys-resources/note_3.0-zh-cn.png) 如果用户需要使用**openssl** **pkeyutl**命令，OpenSSL需要是1.0.2及以上版本。 如果用户使用SM2公钥包装，需要支持gmssl命令。 1. 在已安装OpenSSL工具的客户端上，执行以下命令，生成密钥材料（256位对称密钥），并将生成的密钥材料以"PlaintextKeyMaterial.bin"命名保存。 - AES256对称密钥 **openssl** **rand** **-out** ***PlaintextKeyMaterial.bin*** **32** - SM4国密 **openssl rand -out *PlaintextKeyMaterial.bin*16** 2. 使用下载的"包装密钥"加密密钥材料，并将加密后的密钥材料按"EncryptedKeyMaterial.bin"命名保存。 如果"包装密钥"由控制台下载，以下命令中的***PublicKey.bin*** 参数请以下载的包装密钥名称*wrappingKey_密钥ID*进行替换。 表2使用下载的包装密钥加密生成的密钥材料 | 包装密钥算法 | 加密生成的密钥材料 | |:---|:---| | 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*** | - [非对称密钥] - **方法一**：使用下载的包装密钥在自己的HSM中加密密钥材料，详细信息请参考您的HSM操作指南。 - **方法二** ：使用OpenSSL生成密钥材料，并用下载的"包装密钥"对密钥材料进行加密。 ![](https://support.huaweicloud.com/usermanual-dew/public_sys-resources/note_3.0-zh-cn.png) 如果用户需要使用**openssl** **pkeyutl**命令，OpenSSL需要是1.0.2及以上版本。 如果用户使用SM2公钥包装，需要支持gmssl命令。 1. 在已安装OpenSSL工具的客户端上，执行以下命令，生成密钥材料（256位对称密钥），并将生成的密钥材料以"PlaintextKeyMaterial.bin"命名保存。 - RSA、ECC非对称密钥 1. 生成16进制AES256密钥： **openssl rand -out 0xPlaintextKeyMaterial.bin -hex 32** 2. 将16进制AES256密钥转换成二进制格式： **cat 0xPlaintextKeyMaterial.bin \| xxd -r -ps \> PlaintextKeyMaterial.bin** - SM2非对称密钥 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** ![](https://support.huaweicloud.com/usermanual-dew/public_sys-resources/note_3.0-zh-cn.png) 默认情况下，OpenSSL命令行工具中未启用包装密码算法-id-aes256-wrap-pad。您可以下载并安装最新版本的OpenSSL，然后对其进行修补，以完成导入非对称密钥所需的信封包装。修补方式可以参考常见问题。 - （可选）对于使用SM4临时密钥材料加密SM2私钥（以sm2p256v1为例）的场景，参考如下步骤： 1. 生成私钥。使用openssl 1.1.1及之后的版本执行以下命令。 openssl ecparam -genkey -name SM2 -out pkcs1_sm2_private_key.pem 2. 格式转换成pkcs8格式 **openssl pkcs8 -topk8 -inform PEM -in pkcs1_sm2_private_key.pem -outform pem -nocrypt -out sm2_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** ![](https://support.huaweicloud.com/usermanual-dew/public_sys-resources/note_3.0-zh-cn.png) 默认情况下，GmSSL命令行工具中未启用包装密码算法-sms4-wrap-pad。您可以下载并安装最新版本的GmSSL，然后对其进行修补，以完成导入非对称密钥所需的信封包装。修补方式可以参考常见问题。 #### 步骤四：导入密钥材料 密钥材料下载方式不同，导入操作方式不同： - 如果通过调用API接口下载密钥材料，或已有密钥材料，执行[导入已有密钥材料]。 - 如果通过KMS控制台下载密钥材料，执行[继续导入密钥材料]。 - [导入已有密钥材料] 1. [登录DEW服务控制台](https://console.huaweicloud.com/dew/?locale=zh-cn#/dew/)。 2. 单击管理控制台左上角![](https://support.huaweicloud.com/usermanual-dew/zh-cn_image_0000002259682412.png)，选择区域或项目。 3. 在"自定义密钥"页签，定位到[步骤一：创建托管类型为外部BYOK的密钥](https://support.huaweicloud.com/usermanual-dew/dew_01_0089.html#dew_01_0089__section1232061165711)创建的密钥，单击"操作"列的"导入密钥材料"。 4. 在"获取包装密钥和导入令牌"配置项，根据[表 密钥包装算法说明]，选择密钥包装算法。 图3获取包装密钥和导入令牌 ![](https://support.huaweicloud.com/usermanual-dew/zh-cn_image_0000002532710756.png "点击放大") 表4密钥包装算法说明 | 密钥包装算法 | 说明 | 设置 | |:---|:---|:---| | RSAES_OAEP_SHA_256 | 具有"SHA-256"哈希函数的OAEP的RSA加密算法。 | 请您根据自己的HSM功能选择加密算法。 如果您的HSM支持"RSAES_OAEP_SHA_256"加密算法，推荐使用"RSAES_OAEP_SHA_256"加密密钥材料。 | | SM2_ENCRYPT | 国密推荐的SM2椭圆曲线公钥密码算法。 | 请在支持国密的局点使用SM2加密算法。 | 5. 单击"已有密钥材料"，在"导入密钥材料"配置项，填写"密钥材料"内容。 图4导入密钥材料 ![](https://support.huaweicloud.com/usermanual-dew/zh-cn_image_0000002563749571.png "点击放大") 表5密钥材料说明 | 场景 | 说明 | |:---|:---| | 对称密钥 | 使用包装密钥加密后的密钥材料。 例如：[步骤三：使用包装密钥加密密钥材料]中的"EncryptedKeyMaterial.bin"文件。 | | 非对称密钥 | 使用包装密钥加密后的临时密钥材料、私钥密文。 例如：[步骤三：使用包装密钥加密密钥材料]中的临时密钥材料"EncryptedKeyMaterial.bin"、私钥密文"out_rsa_private_key.der/out_sm2_private_key"。 | 6. 单击"下一步"，在"密钥导入令牌"配置项，根据[表6]设置参数。 图5导入密钥令牌 ![](https://support.huaweicloud.com/usermanual-dew/zh-cn_image_0000002525018334.png "点击放大") 表6导入密钥令牌参数说明 | 参数 | 操作说明 | |:---|:---| | 密钥ID | 创建密钥时，随机生成的密钥ID。 | | 密钥导入令牌 | 填写[通过调用API接口下载]获取的导入令牌。 | | 密钥材料失效模式 | - 永不失效：导入的密钥材料永久不失效。 - 失效时间：用户可指定导入的密钥材料的失效时间，默认失效时间为24小时。 密钥材料失效后，KMS会在24小时内自动重置密钥材料，重置后密钥将无法使用，且密钥状态变更为"等待导入"。 | 7. 单击"确定"，页面右上角弹出"密钥导入成功"，则说明导入密钥成功。 ![](https://support.huaweicloud.com/usermanual-dew/public_sys-resources/notice_3.0-zh-cn.png) 密钥ID、导入的密钥材料和导入的令牌需要全部匹配，密钥材料才能导入成功，否则会导入失败。 用户可在密钥列表中查看到导入的密钥信息，导入密钥的默认状态为"启用"。 - [继续导入密钥材料] 1. 返回控制台"导入密钥材料"对话框（[5]），在"导入密钥材料"配置项，添加"密钥材料"文件。 图6导入密钥材料 ![](https://support.huaweicloud.com/usermanual-dew/zh-cn_image_0000002655030083.png "点击放大") 2. 单击"下一步"，进入"密钥导入令牌"页面。根据[表7]设置参数。 图7导入密钥令牌 ![](https://support.huaweicloud.com/usermanual-dew/zh-cn_image_0000002624908260.png "点击放大") 表7导入密钥令牌参数说明 | 参数 | 操作说明 | |:---|:---| | 密钥ID | 创建密钥时，随机生成的密钥ID。 | | 密钥材料失效模式 | - 永不失效：导入的密钥材料永久不失效。 - 失效时间：用户可指定导入的密钥材料的失效时间，默认失效时间为24小时。 密钥材料失效后，KMS会在24小时内自动重置密钥材料，重置后密钥将无法使用，且密钥状态变更为"等待导入"。 | 3. 单击"确定"，页面右上角弹出"密钥导入成功"，则说明导入密钥成功。 ![](https://support.huaweicloud.com/usermanual-dew/public_sys-resources/notice_3.0-zh-cn.png) 密钥ID、导入的密钥材料需要全部匹配，密钥材料才能导入成功，否则会导入失败。 用户可在密钥列表中查看到导入的密钥信息，导入密钥的默认状态为"启用"。 #### 相关操作 以下为您提供重置密钥材料和重新导入相同的密钥材料的操作。 #### 重置密钥材料 导入的密钥材料过期或者被重置后，其密钥将无法使用，且当前密钥的状态切换为"等待导入"，需要[重新导入相同的密钥材料]才可以正常使用。重新导入相同的密钥材料后，该自定义密钥可以解密删除密钥材料前加密的所有数据。 ![](https://support.huaweicloud.com/usermanual-dew/public_sys-resources/note_3.0-zh-cn.png) 非对称密钥不支持重置密钥材料。 KMS支持两种重置密钥材料的方法： - **方法一** ：过期后由KMS重置 在导入密钥材料时，指定密钥材料的失效时间，当密钥材料失效后，KMS将重置密钥材料。 - **方法二** ：通过控制台直接重置密钥材料 1. 在需要重置的密钥材料所在行，单击"重置密钥材料"。 2. 在需要重置的密钥材料所在行，单击"更多 \> 重置密钥材料"。 3. 在弹出的对话框中输入"DELETE"后单击"确定"，页面右上角弹出"密钥材料重置成功"，则说明重置密钥材料的成功。 #### 重新导入相同的密钥材料 密钥材料过期或重置后，您可以再次导入相同的密钥材料，密钥才可继续使用。 1. 重新下载包装公钥和导入令牌。具体操作，请参见[步骤二：下载包装密钥和导入令牌]。 ![](https://support.huaweicloud.com/usermanual-dew/public_sys-resources/note_3.0-zh-cn.png) 密钥包装过程不会影响密钥材料的内容，因此，您可以使用不同的包装公钥和不同的包装算法来导入相同的密钥材料。 2. 使用包装公钥加密密钥材料，密钥材料必须与之前过期的密钥材料为同一个。具体操作，请参见[步骤三：使用包装密钥加密密钥材料]。 3. 使用导入令牌，导入加密后的密钥材料。具体操作，请参见[步骤四：导入密钥材料]。