使用EVSM实现应用层敏感数据加解密

资源准备

步骤一：配置密码机客户端

在加密服务试用阶段，您无须配置密码机客户端。如果您的业务需要正式上线，在购买加密服务实例后，您需要配置密码机客户端。

1. 登录加密服务管理控制台，在顶部菜单栏，选择目标地域。
2. 下载并安装密码机实例管理工具。
   说明 如果您的密码机是通用密码机GVSM且您没有使用UKEY的需求，您可以跳过本步骤，在控制台一键初始化密码机。
   1. 在实例列表页面，找到目标密码机实例。
   2. 单击密码机实例的规格列信息，然后单击下载密码机实例管理工具。
      
   3. 解压获取到的密码机软件包，选择以下任一方式安装密码机实例管理工具。
      • 在本地终端安装密码机客户端管理工具，然后通过VPN或物理专线使本地终端连接到密码机实例所属的VPC网络。
      • 在ECS实例上安装密码机客户端管理工具，然后通过本地终端远程登录ECS实例，在ECS实例上操作密码机实例管理工具。购买ECS实例的具体操作，请参见使用向导创建实例。
3. 使用密码机实例管理工具初始化密码机实例。
   1. 登录密码机实例管理工具。具体操作，请参见密码机实例管理工具用户使用手册的《登录》章节。
   2. 初始化密码机实例。具体操作，请参见密码机实例管理工具用户使用手册的《快速初始化》或《原始初始化》章节。

步骤二：初始化SDK

hsm=hsmGeneralFinance.getInstance("./cacipher.ini");

步骤三：调用Java接口生成密钥

hsm.genWorkKey(keyType,algFlag,keyIndex,keyLable);

public String[] genWorkKey(String keyType,
                                    char keyFlag,
                                    int storeKeyIndex,
                                    String storeKeyLabel)
                              throws cn.tass.exceptions.TAException

keyType：00A
algFlag：R
keyIndex：1
KeyLabel：test

cn.tass.exceptions.TAException //接口自定义异常。

步骤四：配置Java接口

步骤五：调用Java接口进行数据加解密

主要介绍了通过调用Java接口生成工作密钥和进行通用数据加解密的操作方法。

数据加密

hsm.generalDataEnc(algType,keyType,sm4SymmKey,disperFactor,sessionType,sessionFactor,padFlag,inData,IV);

public byte[] generalDataEnc(int algType,
                             String keyType,
                             Object key,
                             String disperFactor,
                             Int sessionType,
                             String sessionFactor,
                             Int padFlag,
                             byte[] inData,
                             String IV)
                      throws cn.tass.exceptions.TAException

algType：1
keyType："00A"
key:symmKey[0] //加密的对称密钥密文，使用EVSM内部的索引密钥，使用内部密钥时为int类型。
disperFactor：null
sessionType：0
sessionFactor：null
padFlag：1
inData：根据用户业务自行输入数据内容。
IV："00000000000000000000000000000000"

返回值

加密之后的密文数据。

cn.tass.exceptions.TAException //接口自定义异常。 

数据解密

hsm.generalDataDec(algType,keyType,sm4SymmKey,disperFactor,sessionType,sessionFactor,padFlag,symmEnc,IV);

public byte[] generalDataDec(int algType,
                            String keyType,
                             Object key,
                            String disperFactor,
                            int sessionType,
                            String sessionFactor,
                             int padFlag,
                            byte[] inData,
                             String IV)
                      throws cn.tass.exceptions.TAException

algType：1
keyType："00A"
key:symmKey[0] //加密的对称密钥密文，使用EVSM内部的索引密钥，使用内部密钥时为int类型。
disperFactor：null
sessionType：0
sessionFactor：null
padFlag：1
inData：自行输入加密后的数据。
IV："00000000000000000000000000000000"

返回值

解密后的数据。

cn.tass.exceptions.TAException //程序运行异常。   

示例

public class SensitiveDataEnc {

    public static void main(String[] args) throws TAException {
        // 接口初始化，采用配置文件的方式。
        hsmGeneralFinance hsm = hsmGeneralFinance.getInstance("./cacipher.ini");
        // 接口初始化2，采用配置内容的方式。
//        String config =
//                "{"
//                        + "[LOGGER];"
//                        + "logsw=error;logPath=./;"
//                        + "[HOST1];"
//                        + "hsmModel=SJJ1310;"
//                        + "host=192.168.19.19;"
//                        + "port=8018;"
//                        + "connTimeout=5;"
//                        + "}";
//
//        hsmGeneralFinance hsm = hsmGeneralFinance.getInstance(config);

        // 测试1产生随机密钥keyIndex为可变参数。
        // 当该密钥索引值取值为0时，表示不需要加密机保存生成的该条随机对称密钥。
        // 当keyIndex取值为1~2048时，表示将对称密钥储存在加密机中，且执行覆盖操作（相同索引执行覆盖操作）。
        int keyIndex = 0;

        switch (keyIndex) {
            case 0:
                // 产生随机SM4算法对称密钥。
                String keyType = "00A";
                char algFlag = 'R';
                String keyLable = "sm4Key";
                // 调用产生随机密钥接口。
                String[] symmKey = hsm.genWorkKey(keyType, algFlag, keyIndex, keyLable);
                System.out.println("对称密钥lmk下的密文值：" + symmKey[0]);
                System.out.println("对称密钥校验值：" + symmKey[1]);

                // 测试2。
                String str = "要加密的数据";
                // CBC模式。
                int algType = 1;
                // 密钥类型固定。
                keyType = "00A";
                // 执行加密的对称密钥密文。
                String sm4SymmKey = symmKey[0];
                // 也可以使用加密机内部的索引密钥，使用内部密钥时为int类型。
                String disperFactor = null;
                int sessionType = 0;
                String sessionFactor = null;
                // 遵循强制80填充。
                int padFlag = 1;
                byte[] inData = str.getBytes();
                String IV = "00000000000000000000000000000000";
                // 调用数据加密接口。
                byte[] symmEnc = hsm.generalDataEnc(algType, keyType, sm4SymmKey, disperFactor, sessionType, sessionFactor,
                        padFlag, inData, IV);
                System.out.println("16进制字符串输出对称加密结果：" + Forms.byteToHexString(symmEnc)
                        + ",如果进行解密，可使用接口功能函数'Forms.hexStringToByte()'将16进制字符串转换为byte[]参与解密。");
                // 调用数据解密接口。
                byte[] symmDec = hsm.generalDataDec(algType, keyType, sm4SymmKey, disperFactor, sessionType, sessionFactor,
                        padFlag, symmEnc, IV);
                System.out.println("解密结果与加密数据比较结果：" + Arrays.equals(symmDec, inData));
                System.out.println("还原解密结果，通过字符集还原原文：" + new String(symmDec));
                break;
            // 此时生成对称密钥到1号索引位置，若已经存在，会执行覆盖操作。
            case 1:
                str = "要加密的数据";
                // CBC模式。
                algType = 1;
                // 密钥类型固定。
                keyType = "00A";
                // 执行加密的对称密钥密文。
                int sm4SymmKeyIndex = 1;
                // 也可以使用加密机内部的索引密钥，使用内部密钥时为int类型。
                disperFactor = null;
                sessionType = 0;
                sessionFactor = null;
                // 遵循强制80填充。
                padFlag = 1;
                inData = str.getBytes();
                IV = "00000000000000000000000000000000";
                // 调用数据加密接口。
                symmEnc = hsm.generalDataEnc(algType, keyType, sm4SymmKeyIndex, disperFactor, sessionType, sessionFactor,
                        padFlag, inData, IV);
                System.out.println("16进制字符串输出对称加密结果：" + Forms.byteToHexString(symmEnc)
                        + ",如果进行解密，可使用接口功能函数'Forms.hexStringToByte()'将16进制字符串转换为byte[]参与解密。");
                // 调用数据解密接口。
                symmDec = hsm.generalDataDec(algType, keyType, sm4SymmKeyIndex, disperFactor, sessionType, sessionFactor,
                        padFlag, symmEnc, IV);
                System.out.println("解密结果与加密数据比较结果：" + Arrays.equals(symmDec, inData));
                System.out.println("还原解密结果，通过字符集还原原文：" + new String(symmDec));
                break;
            default:
                break;
        }

    }

}

步骤六：同步应用系统密钥

在部署密码机实例时，您需要同步应用系统的密钥和配置Java接口。应用密钥存储在密码机实例内部和外部系统的同步方式不同。

密钥存储在密码机实例内部系统

您需要根据密钥索引将应用密钥备份导出，然后通过密钥恢复导入功能将备份密钥导入到其他密码机实例中，完成密钥同步操作。以下内容以从A密码机实例导出应用密钥，并导入到B密码机实例为例。

1. 备份导出A密码机实例的应用密钥。
   1. 打开密码机实例管理工具，通过A密码机实例的IP地址登录VSM管理系统。
      具体操作，请参见密码机实例管理工具用户使用手册的《登录》章节。
   2. 在顶部菜单栏，单击密钥管理页签，然后单击备份导出。
   3. 在选择导出密钥类型和索引对话框，根据实际需要选择密钥类型并输入密钥索引，然后单击确认。
      您可以选择将密钥备份保存到文件或保存到UKEY内。本文以将密钥备份保存到文件为例进行描述。
   4. 按照系统提示依次插入3个空UKEY并输入口令，单击下一步。
      说明 密码机实例将依次制作出3个密钥备份密钥KBK UKEY。建议3个KBK UKEY由3个密钥管理员分别保管。
   5. 选择要保存密钥密文的文件，单击下一步。
      EVSM将导出全部应用密钥并保存到您选择的文件中。

      说明 密钥备份完成后，请您妥善保管3个KBK UKEY和密钥备份文件，待密钥恢复时使用。
2. 将导出的应用密钥导入到B密码机实例进行恢复。
   1. 打开密码机实例管理工具，通过B密码机实例的IP地址登录VSM管理系统。
      具体操作，请参见密码机实例管理工具用户使用手册的《登录》章节。
   2. 在顶部菜单栏，单击密钥管理页签，然后选择恢复导入 > 从文件中恢复密钥。
      说明 恢复密钥时使用任意2个密钥备份UKEY即可还原出原始的KBK文件，然后将密钥恢复到其他密码机实例内部或者同步到热备份的其他密码机实例内部。
   3. 按照系统提示依次插入任意2个KBK UKEY并输入口令，单击下一步。
   4. 选择要读取的密钥备份文件，等待系统完成应用密钥的恢复，单击完成。

密钥存储在密码机实例外部系统

当应用密钥经过本地主密钥LMK（Local Master Key）分组加密保护后存储在外部系统，如果需要同步应用系统密钥，您还需要同步密码机实例的域名主密钥DMK（Domain Master Key）。您可以通过密码机实例的原始初始化，来产生DMK成分的UKEY。

当多个密码机实例进行密钥备份时，只需要在第一个密码机实例上完成原始初始化后，对其他密码机实例恢复初始化，即可完成多个密码机实例的密钥同步。以下内容以在A密码机实例进行原始初始化，并在B密码机实例恢复初始化为例。

1. 在A密码机实例上进行原始初始化。
   警告 原始初始化将清空密码机实例内的所有密钥，如果您希望保存密码机中的数据，请使用UKEY备份。备份的具体操作请参见密码机实例管理工具的用户使用手册。
   1. 打开密码机实例管理工具，通过A密码机实例的IP地址登录VSM管理系统。
      具体操作，请参见密码机实例管理工具用户使用手册的《登录》章节。
   2. 在顶部菜单栏，单击密钥管理页签，然后单击原始初始化。
   3. 在弹出的警示提示框，单击下一步。
   4. 根据系统提示，制作至少2个域名主密钥DMK成份的UKEY。
      建议您采用3选2授权控制机制并制作3个授权UKEY。

      说明 具体操作，请参见密码机实例管理工具用户管理手册的《原始初始化》章节。
2. 对B密码机实例进行恢复初始化（即导入DMK）。
   警告 恢复初始化将清空密码机实例内的所有密钥，如果您希望保存密码机中的数据，请使用UKEY备份。备份的具体操作请参见密码机实例管理工具的用户使用手册。
   1. 打开密码机实例管理工具，通过B密码机实例的IP地址登录VSM管理系统。
      具体操作，请参见密码机实例管理工具用户使用手册的《登录》章节。
   2. 在顶部菜单栏，单击密钥管理页签，然后单击恢复初始化。
   3. 在弹出的警示提示框，单击下一步。
   4. 在恢复初始化-第一步对话框，输入DMK成份UKEY数目，单击下一步。
   5. 在恢复初始化-第二步对话框，依次插入n个成份UKEY并输入UKEY口令，单击导入成份UKEY，密码机实例将读取UKEY内的DMK成份数据。
   6. DMK成份导入完成后，单击合成DMK。
   7. DMK合成成功后，确定授权机制。
      • 如果您的其他密码机实例共用一套授权UKEY，请选择同步授权信息。您只需插入有效授权的UKEY并输入口令，单击完成，完成恢复初始化。
      • 如果您的每个密码机实例都需要使用独立的授权UKEY，选中制作新的授权UKEY，并从选择授权机制列表中选择请选择1选1授权控制机制，制作授权UKEY完成恢复初始化。
3. 在顶部菜单栏，单击密钥管理页签，然后单击获取DMK校验值。
   当DMK同步到多个密码机实例时，可以通过比对多个密码机实例的DMK校验值来确定同步后的DMK是否一致。
4. 在密钥管理页签，单击导出DMK成份。
   您可以将DMK成份导出到多个UKEY中，在原有密码机实例的成份UKEY丢失或损坏的情况下，能够重新合成出与原有密码机实例同样的DMK成份。

   重要 导出DMK成份时，不能保证DMK成份UKEY中的密钥备份与原有密码机实例的成份UKEY中的密钥备份完全相同。