导入密钥材料
当用户希望使用自己的密钥材料，而不是KMS生成的密钥材料时，可通过密钥管理界面将自己的密钥材料导入到KMS，由KMS统一管理。
该任务指导用户通过密钥管理界面导入密钥材料。
约束条件
- HMAC密钥算法不支持导入密钥材料。
- 副本密钥在创建时会同步主密钥的密钥材料，密钥材料过期后，需在各区域重新独立导入密钥材料。
操作流程
|
场景 |
操作步骤 |
|---|---|
|
已有密钥材料 |
|
|
通过调用API接口下载密钥材料 |
|
|
通过KMS控制台下载密钥材料 |
|
步骤二：下载包装密钥和导入令牌
- 通过调用API接口下载：获取到包装密钥、导入令牌。
- 通过KMS控制台下载：获取到包装密钥。导入令牌将由控制台自动传递。因此，下载密钥材料后，请勿关闭或中途退出“导入密钥材料”对话框，否则将导致导入的令牌自动失效。
- 调用“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 }
- 保存包装密钥，包装密钥需要按照以下步骤转换格式。使用转换格式后的包装密钥加密的密钥材料才能成功导入管理控制台。
- 复制包装密钥“public_key”的内容，粘贴到“.txt”文件中，并保存为“PublicKey.b64”。
- 使用OpenSSL，执行以下命令，对“PublicKey.b64”文件内容进行base64转码，生成二进制数据，并将转码后的文件保存为“PublicKey.bin”。
openssl enc -d -base64 -A -in PublicKey.b64 -out PublicKey.bin
- 保存导入令牌，复制导入令牌“import_token”的内容，粘贴到“.txt”文件中，并保存为“ImportToken.b64”。
- 登录管理控制台。
- 单击管理控制台左上角
，选择区域或项目。 - 单击页面左侧
，选择，默认进入“密钥管理”界面。 - 在“自定义密钥”页签，定位到步骤一：创建密钥材料来源为外部的密钥创建的密钥，单击“操作”列的“导入密钥材料”。
- 在“获取包装密钥和导入令牌”配置项，根据表 密钥包装算法说明，选择密钥包装算法。
图1 获取包装密钥和导入令牌
- 单击“下载并继续”，下载的文件为包装密钥，如图 下载文件所示。
- wrappingKey_密钥ID：即包装密钥，编码为二进制格式，用于加密密钥材料的包装密钥。
- 导入令牌：引导程序自动传递导入令牌，无需下载，如果中途退出引导程序，导入令牌将自动失效。
包装密钥将在24小时后失效，失效后将不能使用。如果包装密钥失效，请重新下载包装密钥。
控制台将自动传递导入令牌。因此，下载密钥材料后，请勿关闭或中途退出“导入密钥材料”对话框，否则将导致导入的令牌自动失效。
下载包装密钥后，需要使用包装密钥加密密钥材料，然后继续在“导入密钥材料”对话框，导入密钥材料。具体操作，请参见继续导入密钥材料。
步骤三：使用包装密钥加密密钥材料
- 对称密钥：密钥材料为“EncryptedKeyMaterial.bin”。
- 非对称密钥：密钥材料为“EncryptedKeyMaterial.bin”临时密钥材料、“out_rsa_private_key.der/out_sm2_private_key”私钥密文。
- 方法一：使用下载的包装密钥在自己的HSM中加密密钥材料，详细信息请参考您的HSM操作指南。
- 方法二：使用OpenSSL生成密钥材料，并用下载的“包装密钥”对密钥材料进行加密。
如果用户需要使用openssl pkeyutl命令，OpenSSL需要是1.0.2及以上版本。
如果用户使用SM2公钥包装，需要支持gmssl命令。
- 在已安装OpenSSL工具的客户端上，执行以下命令，生成密钥材料（256位对称密钥），并将生成的密钥材料以“PlaintextKeyMaterial.bin”命名保存。
- 使用下载的“包装密钥”加密密钥材料，并将加密后的密钥材料按“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生成密钥材料，并用下载的“包装密钥”对密钥材料进行加密。
如果用户需要使用openssl pkeyutl命令，OpenSSL需要是1.0.2及以上版本。
如果用户使用SM2公钥包装，需要支持gmssl命令。
- 在已安装OpenSSL工具的客户端上，执行以下命令，生成密钥材料（256位对称密钥），并将生成的密钥材料以“PlaintextKeyMaterial.bin”命名保存。
- RSA、ECC非对称密钥
- SM2非对称密钥
- 使用下载的“包装密钥”加密密钥材料，并将加密后的密钥材料按“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
- 导入非对称密钥时，需要生成非对称私钥，并使用临时密钥材料（“ EncryptedKeyMaterial.bin”）对私钥进行加密，加密后的文件作为“私钥密文”。
- 以配套算法为“RSA4096算法”为例：
- 生成私钥
- 格式转换成pkcs8格式
openssl pkcs8 -topk8 -inform PEM -in pkcs1_rsa_private_key.pem -outform pem -nocrypt -out rsa_private_key.pem
- pkcs8格式转换成der格式
openssl pkcs8 -topk8 -inform PEM -outform DER -in rsa_private_key.pem -out rsa_private_key.der -nocrypt
- 使用临时密钥材料对私钥进行加密
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为例）的场景，参考如下步骤：
- 生成私钥
- 格式转换成pkcs8格式
openssl pkcs8 -topk8 -inform PEM -in pkcs1_sm2_private_key.pem -outform pem -nocrypt -out sm2_private_key.pem
- 转换成der格式
gmssl pkcs8 -topk8 -inform PEM -outform DER -in sm2_private_key.pem -out sm2_private_key.der -nocrypt
- 使用临时密钥材料对私钥进行加密
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，然后对其进行修补，以完成导入非对称密钥所需的信封包装。修补方式可以参考常见问题。
- 以配套算法为“RSA4096算法”为例：
- 在已安装OpenSSL工具的客户端上，执行以下命令，生成密钥材料（256位对称密钥），并将生成的密钥材料以“PlaintextKeyMaterial.bin”命名保存。
- 登录管理控制台。
- 单击管理控制台左上角，选择区域或项目。
- 单击页面左侧，选择，默认进入“密钥管理”界面。
- 在“自定义密钥”页签，定位到步骤一：创建密钥材料来源为外部的密钥创建的密钥，单击“操作”列的“导入密钥材料”。
- 在“获取包装密钥和导入令牌”配置项，根据表 密钥包装算法说明，选择密钥包装算法。
图3 获取包装密钥和导入令牌
- 单击“已有密钥材料”，在“导入密钥材料”配置项，填写“密钥材料”内容。
图4 导入密钥材料
表5 密钥材料说明 场景
说明
对称密钥
使用包装密钥加密后的密钥材料。
例如：步骤三：使用包装密钥加密密钥材料中的“EncryptedKeyMaterial.bin”文件。
非对称密钥
使用包装密钥加密后的临时密钥材料、私钥密文。
例如：步骤三：使用包装密钥加密密钥材料中的临时密钥材料“EncryptedKeyMaterial.bin”、私钥密文“out_rsa_private_key.der/out_sm2_private_key”。
- 单击“下一步”，在“密钥导入令牌”配置项，根据表6设置参数。
图5 导入密钥令牌
- 单击“确定”，页面右上角弹出“密钥导入成功”，则说明导入密钥成功。
密钥ID、导入的密钥材料和导入的令牌需要全部匹配，密钥材料才能导入成功，否则会导入失败。
用户可在密钥列表中查看到导入的密钥信息，导入密钥的默认状态为“启用”。
- 返回控制台“导入密钥材料”对话框（6），在“导入密钥材料”配置项，添加“密钥材料”文件。
图6 导入密钥材料
表7 密钥材料说明 场景
说明
对称密钥
使用包装密钥加密后的密钥材料。
例如：步骤三：使用包装密钥加密密钥材料中的“EncryptedKeyMaterial.bin”文件。
非对称密钥
使用包装密钥加密后的临时密钥材料、私钥密文。
例如：步骤三：使用包装密钥加密密钥材料中的临时密钥材料“EncryptedKeyMaterial.bin”、私钥密文“out_rsa_private_key.der/out_sm2_private_key”。
- 单击“下一步”，进入“密钥导入令牌”页面。根据表8设置参数。
图7 导入密钥令牌
- 单击“确定”，页面右上角弹出“密钥导入成功”，则说明导入密钥成功。
密钥ID、导入的密钥材料需要全部匹配，密钥材料才能导入成功，否则会导入失败。
用户可在密钥列表中查看到导入的密钥信息，导入密钥的默认状态为“启用”。
