密钥管理系统
有奖捉虫：行业应用 & 管理与支持文档专题 HOT
文档中心 > 密钥管理系统 > 最佳实践 > 白盒密钥管理 > 操作指南

操作指南

最近更新时间：2023-09-26 10:36:37

我的收藏

本页目录：

操作流程

API Key 是常用的一类用于客户端应用与后台服务器建立可信连接和数据通信的密钥。下面就以 API Key 为例，介绍腾讯云提供的白盒密钥保护解决方案。
用户使用白盒密钥加密的流程如下图所示：

从上述流程可以看出，API Key 并没有暴露在开放环境中，在实际的用户业务的服务器上只保存了 API Key 的密文，以及需要的白盒解密密钥，白盒解密算法和密钥混淆后无需额外的明文密钥进行解密，这就确保了整个链路的安全性。针对 GitHub 上源代码的 API Key 泄露事件，如果采用白盒密钥管理的解决方案，就可以彻底杜绝 API Key 的明文暴露在源代码中，从而防止 API Key 被恶意利用。

操作步骤

步骤1：创建白盒密钥

注意
白盒密钥为收费项，详情请参见 计费概述 和 购买方式。
创建白盒密钥对是通过调用白盒服务来实现的，支持控制台方式和 API 方式。
本文示例使用腾讯云 命令行工具 TCCLI ，后续您可以使用任何受支持的编程语言调用。 请求命令：
tccli kms CreateWhiteBoxKey --region ap-guangzhou --Alias test-gz01 --Description 'this is test for gz key' --Algorithm 'SM4'
返回结果示例：
{
    "Response": {
        "RequestId": "55f7ca05-17af-4bfb-87a5-80a80a4b0761",
        "EncryptKey": "BA4AADZhzTBr7vmCDyHwQRCKTSCXm8pnGs38mJfA1Pw+VaP8/MW+lSCTYIi/0AUsido39JWw2XkvrnmauXsU3cemHQ+bcpofelLB2nS2ShCINi9MTSS/KgAKhvQPD5jXtbbmUSiBcKLTMXxH6MZXcPyGvEmqe3SrhvqflQk4bL/uUxAW1IC4p7E07pn6RQr2zMZAdkK0IciuwV23+cp25x2G/fEGtZi46YZR48tb2ZciGQ5kzS8se/CJM+lTqdBwAHV6yvPVQaXS16NFp4UhAtGCRZVfMQCp56hkhEryGjtxvIz4qfgCZ4bEo3Xp2DnNtzwBmtRBnCXl2PbLABRfGZ9ZX7uN3IMv3rJ1mRJWJh2eBHR1N+ujO7bGTqYHIb9VxxafQ/D9PHhGO3LeQRrNi1LS31XClvVNqNR8p/gc4GQCs987q0vdXC2PfinEV0fkyAKzis6096Jo7gfK+QvjYgVNRPr0nVuKKMI60zDKHG5jnN5kRKuTYfhl2tppFQO2WpvCLPHQH3DcX2FZGAgmvV1yjMSp79dOgS3tnbHn8fPNIEYdziQgYV0+ce4r****",
        "DecryptKey": "CA4AAEFLh2SUfMm1UIuxgTiD7g/rBKlxShZ/5jxRByvOqgtNyx42vDGACEtPYZwOXIhCn5wnpnisA+ZlDd3oYnmbqO9cG9KzczsHy3x6ymlpsIfw46PB2ostz755947ykzbi71G0osTvqo9rJFrVjQpcfu7/P8iKbJhI5Y/W2CIMuhJdbrQhXl6xyYILnhAV+o4D+c3MgzpkzB/zovcWr7EoDCDcLn4730e96ubN/+BbA9opz11jMymCJsx6PHsrfd6jzis4ZzDV+Uq+jYd5IJHGhmXaaQoeX2Shi+b9lOHuLi/MFqwjoskNMZ17xhc1e7l3lHpQQMIk3dYfnK3UI+6t2D3QoRCz8ytRCfI2uRHtKGZUPYl2586iJ+48lJ7/cWLlRwsypYUv73Oas0KnuRqGCilG2dwpIW7P/0CAqO09hN7ti+IMbiVK4dHF8aJB24A9SAHpN1ZejZbduHACPBDfb5jyMdBegswiip9qdtRzHfP9CU1ozVRXt/8jt0iJdib6nEuvjHuFDauVuZk1ahd9MUqhdK3zKBBHdH9uP+EyiYu8w88+N0XOEMWv****",
        "KeyId": "1c820b96-73bd-11ea-a490-5254006d0810"
    }
}
注意
目前支持的加密算法有两种：SM4，AES_256。
返回的 EncryptKey，DecryptKey 分别是加密密钥和解密密钥，且都做了 base64 编码。

步骤2：绑定设备指纹（可选操作）

1. 登录需要采集设备指纹的机器，运行指纹采集工具（getDeviceFingerprint），得到长度70位的字符串，即为设备指纹。
2. 通过 密钥管理系统控制台 或 API 的方式，将收集到的设备指纹列表上传并绑定到指定的白盒密钥上。详细说明和操作步骤请参见 设备绑定指南。
说明
指纹采集工具（getDeviceFingerprint）请直接从 密钥管理系统控制台 上下载。
请求命令：
tccli kms OverwriteWhiteboxDeviceFingerprints --region ap-guangzhou --KeyId 1c820b96-73bd-11ea-a490-5254006d****  --DeviceFingerprints '[{"Identity":"c19c024c-2ba1-11b2-a85c-96f970f4****","Description":"10.0.0.1 密钥管理系统设备"}]'
返回结果示例：
{
    "Response": {
        "RequestId": "55f7ca05-17af-4bfb-87a5-80a80a4b0761",
     }
}
注意
DeviceFingerprints 会完全替换现有指定密钥的指纹。如果 DeviceFingerprints 为空，则表示删除该密钥所关联的所有的设备指纹。

步骤3：对明文进行 base64 编码

准备需要使用白盒密钥管理的明文，并对该明文进行 base64 编码。 例如，假设要加密的明文是：1234567890，使用 openssl 命令生成 base64 编码后的结果为：MTIzNDU2Nzg5MAo=。
echo 1234567890 | openssl base64

步骤4：使用白盒密钥加密 API Key

请求命令：
tccli kms EncryptByWhiteBox --region ap-guangzhou --KeyId a1a9376a-7261-11ea-a490-5254006d**** --PlainText MTIzNDU2Nzg5MAo=
返回结果：
{
    "Response": {
        "RequestId": "1bf315d1-3b20-4089-b458-51c367967b4b",
        "InitializationVector": "EUi3Vv7DiCf73D6XbVzMYg==",
        "CipherText": "HKyXV1Xoodi1P/sdf/cYLw=="
    }
}
注意
返回的字段主要有两个：
InitializationVector：随机生成的初始化向量（简称 Iv），用于增加密文被破解的难度。
CipherText：加密后的密文，并进行了 base64 编码。

步骤5：白盒解密密钥和 API Key 密文分发

管理员将上述步骤中生成的 DecryptKey，InitializationVector，CipherText 分发给各业务系统的开发或运维人员。其中，DecryptKey 会被部署到相应业务系统的文件中，而 InitializationVector 和 CipherText 会作为 SDK 的传参。
其中：
1. 解密密钥（DecryptKey）需要以二进制文件的形式保存，供系统启动的时候读取。操作命令如下：
1.1 将 DecryptKey 保存到文件中。
echo "CA4AAEFLh2SUfMm1UIuxgTiD7g/rBKlxShZ/5jxRByvOqgtNyx42vDGACEtPYZwOXIhCn5wnpnisA+ZlDd3oYnmbqO9cG9KzczsHy3x6ymlpsIfw46PB2ostz755947ykzbi71G0osTvqo9rJFrVjQpcfu7/P8iKbJhI5Y/W2CIMuhJdbrQhXl6xyYILnhAV+o4D+c3MgzpkzB/zovcWr7EoDCDcLn4730e96ubN/+BbA9opz11jMymCJsx6PHsrfd6jzis4ZzDV+Uq+jYd5IJHGhmXaaQoeX2Shi+b9lOHuLi/MFqwjoskNMZ17xhc1e7l3lHpQQMIk3dYfnK3UI+6t2D3QoRCz8ytRCfI2uRHtKGZUPYl2586iJ+48lJ7/cWLlRwsypYUv73Oas0KnuRqGCilG2dwpIW7P/0CAqO09hN7ti+IMbiVK4dHF8aJB24A9SAHpN1ZejZbduHACPBDfb5jyMdBegswiip9qdtRzHfP9CU1ozVRXt/8jt0iJdib6nEuvjHuFDauVuZk1ahd9MUqhdK3zKBBHdH9uP+EyiYu8w88+N0XOEMWv****" > decrypt_key.base64
1.2 base64 解码获取公钥实际内容：
openssl enc -d -base64 -A -in decrypt_key.base64 -out decrypt_key.bin
1.3 将生成的二进制文件 decrypt_key.bin 放在和业务系统（已经集成了解密 SDK）相同的服务器上的指定的目录decrypt_key_bin_dir中。
2. 将 InitializationVector，CipherText，decrypt_key_bin_dir，decrypt_key.bin 以字符串的形式，作为 SDK 中的 whitebox_decrypt 方法的传入参数。

步骤6：部署白盒解密密钥

各业务系统根据自身的编程语言，选择下载相应编程语言的解密 SDK，将 SDK 集成到业务系统中。

步骤7：使用 API Key 密文

在业务逻辑中调用 SDK 的解密函数（whitebox_decrypt），传入参数：decrypt_key_bin_dir，decrypt_key.bin，InitializationVector，CipherText，algorithmType 从而获得解密后的明文。其中 algorithmType 是生成密钥时使用的算法类型。取值为0或1。0表示 AES_256，1表示 SM4。 关于白盒密钥如何进行解密，请参考 白盒密钥解密代码示例，各语言 SDK 均有详细的代码示例。
中国站