旗舰版 C 接口文档

国密 Encryption SDK 集成了 KMS，帮助用户解决密钥的生命周期管理问题，用户只需设置相关参数，调用加解密接口，便可实现本地、高效、稳定的国密加解密。

为了提供更好的服务，国密 Encryption SDK 支持基于 KMS 的密钥保护和原生加密的两种加密方式。

• 基于 KMS 的密钥保护方式：是指调用 KMS 平台生成加密密钥，由 KMS 提供密钥的全生命周期的管理，用户通过接口设置密钥的使用和替换策略，详情请参见 InitKeyManager 接口。
• 原生的加密方式：是指用户自行创建加密密钥，传入接口进行加解密，密钥的整个生命周期由用户管理，用户需要自己保证密钥的安全。

出于安全和合规考虑，建议用户使用基于 KMS 的密钥保护方式。

前提条件

• 国密 Encryption SDK 仅适用于密钥管理系统旗舰版，请升级为 KMS 旗舰版。
• 用户需要确保本机支持 CPU 支持 SDK 指令集优化，执行以下命令进行验证：

cat /proc/cpuinfo|grep aes
cat /proc/cpuinfo|grep avx

若可以查询到内容，则说明机器支持指令集加速。

初始化 SDK 接口

InitSdk

• 功能描述：检验用户是否已开通 KMS 旗舰版服务。
• 参数说明：

• 返回值：初始化成功返回0，否则返回相应的 错误码。

!

• 需注意 SecretId 和 SecretKey 的保密存储：腾讯云接口认证主要依靠 SecretID 和 SecretKey，SecretID 和 SecretKey 是用户的唯一认证凭证。业务系统需要该凭证调用腾讯云接口。
• 需注意 SecretId 和 SecretKey 的权限控制：建议使用子账号，根据业务需要进行接口授权的方式管控风险。
• 需注意 domainName 的设置：如果domainName入参为""，则从环境变量TENCENT_SDK_DOMAIN中读取值，反之，则以入参为准。

KMS 密钥保护方式接口说明

KMS 密钥保护方式基于 KMS 密钥管理平台实现，由 KMS 提供密钥的全生命周期管理，其中接口包括主密钥信息列表的新建添加、KeyManager 的初始化、加解密接口等。

NewMasterKey

• 功能描述：把用户首个主密钥加入主密钥信息列表。
• 参数说明：

• 返回值：加入主密钥调用成功返回0，否则返回相应的 错误码。

!用于加密的首个主密钥，在 KMS 平台中是处于生效的状态。

AddMasterKey

• 功能描述：加入备用的用户主密钥，目的是为了灾备，当首个主密钥无法使用时，将会使用的备用密钥，最多支持加入4个。
• 参数说明：

• 返回值：加入主密钥调用成功返回0，否则返回相应的 错误码。

!请保证 masterKeys 至少保留有512字节的空间，否则可能会产生内存错误。

InitKeyManager

• 功能描述：初始化 KeyManager 的结构体，KeyManager 用来保存密钥管理相关参数，包含主密钥信息、密钥加密次数、密钥生效时间等。
• 参数说明：

• 返回值：初始化成功返回0，否则返回相应的 错误码。

Encrypt

• 功能描述：使用 KMS 平台创建的 DataKey，进行本地数据加密。
• 参数说明：

• 返回值：加密成功返回0，否则返回相应的 错误码。

!加密后的数据，会加入DataKey相关信息，只能使用KMS密钥保护方式的接口进行解密。

支持的加密算法列表

EncryptedDataKey 结构体说明

MsgHead结构体说明

BlockType 结构体说明

Decrypt

• 功能描述：方法用于解密密文，得到明文数据。
• 参数说明：

• 返回值：解密成功则返回0，否则返回相应的 错误码。

KMS 加密方式接口调用示例

KMS 密钥保护方式接口调用示例如下：

#include<stdio.h>
#include "kms_enc_sdk.h"

int CBCEnAndDeTest(struct KeyManager *p,unsigned char plaintext[],char masterKeys[])
{
        int i_ret = 0;
        unsigned char ch_orig[128];
        unsigned char ch_enheader[128];
        unsigned char ch_cipher[1024];
        size_t i_cipherlen = 0;

        unsigned char ch_dedata[1024];
        size_t i_dedatalen = 0;
        size_t sourceLength = 0;

        struct KeyManager keymanager;
        struct MsgHead enheader,deheader;

        char masterKeys[1024];
        memset(masterKeys,0,sizeof(masterKeys));

        memset(&enheader,0,sizeof(enheader));
        memset(&deheader,0,sizeof(deheader));

        memset(ch_orig,0,sizeof(ch_orig));
        strcpy(ch_orig,plaintext);
        sourceLength = strlen(ch_orig);

        memset(ch_dedata,0,sizeof(ch_dedata));
        memset(ch_cipher,0,sizeof(ch_cipher));
        memset(ch_dedata,0,sizeof(ch_dedata));

        unsigned char encryptionContext[1024];
        memset(encryptionContext,0,sizeof(encryptionContext));
        i_cipherlen = 0;
        i_dedatalen = 0;

        /*分片大小*/
        size_t blockSize = 0;
        /*选择加解密算法*/
        enum Algorithm al_en = SM4_CBC_128;

        strcpy(encryptionContext,"{\"name\":\"test\",\"date\":\"20200228\"}");

        NewMasterKey(masterKeys,"ap-guangzhou","replace-with-realkeyid");
        AddMasterKey(masterKeys,"ap-beijing","replace-with-realkeyid");

        /*初始化        可加密的消息数量设置为0即缓存不过期*/
        i_ret = InitKeyManager(&keymanager,masterKeys,0,0,0,p->secretId,p->secretKey);

        if ( 0 != i_ret )
        {
                printf("InitKeyManager error\n");
                return ( 0 );
        }

        /*ch_cipher 是加密后的密文内容 */
        i_ret = Encrypt(ch_orig,sourceLength,&keymanager,masterKeys,al_en,encryptionContext,blockSize,&enheader,ch_cipher,&i_cipherlen);
        if (i_ret == 0)
        {
                i_ret = Decrypt(ch_cipher,i_cipherlen,&keymanager,&deheader,ch_dedata,&i_dedatalen);
                if ( 0 == i_ret )
                {
                        printf("ch_dedata[%s] i_dedatalen[%d]\n",ch_dedata,i_dedatalen);
                }
                else
                {
                        printf("Decrypt is err!!!!!!!![%d]\n\n",i_ret);
                }
        }
        else
        {
                printf("Encrypt is err!!!!!!!![%d]\n\n",i_ret);
        }
        return ( 0 );
}

int main()
{
        int i_ret = 0;
        unsigned char plaintext[128];
        char region[128];
        char masterKeys[1024];
        char domainName[128];

        memset(plaintext,0,sizeof(plaintext));
        memset(region,0,sizeof(region));
        memset(masterKeys,0,sizeof(masterKeys));
        memset(domainName,0,sizeof(domainName));

        struct KeyManager keymanager;

        /*domainName    请填入TCE的域名地址*/
        strcpy(domainName,"replace-with-real-domainName");
        strcpy(region,"ap-guangzhou");
        strcpy(keymanager.secretId,"replace-with-real-secretId");
        strcpy(keymanager.secretKey,"replace-with-real-secretKey");
        strcpy(plaintext,"abcdefg123456789abcdefg123456789abcdefg");

        i_ret = InitSdk(region,keymanager.secretId,keymanager.secretKey,domainName);
        if ( 0 != i_ret )
        {
                printf("InitSdk error\n");
                return ( -1 );
        }

        NewMasterKey(masterKeys,"ap-guangzhou","replace-with-realkeyid");
        AddMasterKey(masterKeys,"ap-beijing","replace-with-realkeyid");

        CBCEnAndDeTest(&keymanager,plaintext,masterKeys);

        return ( 0 );
}

原生加密方式的接口说明

原生加密方式对应的服务也需要升级为 KMS 旗舰版，与 KMS 密钥保护方式相比，原生加密方式需要用户本身生成加密密钥进行加解密，由用户保证密钥的安全性。出于安全与合规的考虑，建议用户使用 KMS 密钥保护方式。

?其中 CTR 模式加密没有填充，其他的模式加密采用 PKCS#7 标准进行填充。

Sm2GetKey

• 功能描述：使用SM2算法生成密钥对。
• 参数说明：

• 返回值：密钥对生成成功返回0，否则返回相应的错误码。

Sm2Sign

• 功能描述：使用 SM2 算法进行签名。
• 参数说明：

• 返回值：数据签名成功返回0，否则返回相应的 错误码。

!公钥和私钥的长度为固定长度，用户如果输入长度不一致的数据，可能导致内存访问异常。

Sm2Verify

• 功能描述：使用 SM2 算法进行验签。
• 参数说明：

• 返回值：验签成功返回0，否则返回相应的 错误码。

!公钥长度为固定长度64字节，用户如果输入长度不一致的数据，可能导致内存访问异常。

Sm2PemChangeToPubkey

• 功能描述：对pem格式的公钥内容进行转换。
• 参数说明：

• 返回值：转换成功返回0，否则返回相应的错误码。

HashForSM3WithSM2

• 功能描述：使用 Sm2GetKey 接口生成的公钥，并基于SM3算法生成信息摘要。
• 参数说明：

• 返回值：生成摘要成功返回0，否则返回相应的错误码。

注意：公钥的长度为固定长度，用户如果输入长度不一致的数据，可能导致内存访问异常。

Sm2SignWithDigest

• 功能描述：使用本地生成的消息摘要生成签名
• 参数说明：

• 返回值：生成签名成功返回0，否则返回相应的错误码。

注意：公钥和私钥的长度为固定长度，用户如果输入长度不一致的数据，可能导致内存访问异常。

Sm2VerifyWithDigest

• 功能描述：通过生成的摘要内容进行验签。
• 参数说明：

• 返回值：验签成功返回0，否则返回相应的错误码。

Sm2Encrypt

• 功能描述：使用 SM2 算法进行加密。
• 参数说明：

• 返回值：加密成功返回0，否则返回相应的 错误码。

!SM2 加密适用于小数据的场景，不建议加密超过256k的数据。

Sm2Decrypt

• 功能描述：使用SM2算法进行解密。
• 参数说明：

• 返回值：解密成功返回0，否则返回相应的 错误码。

Sm3Hmac

• 功能描述：使用 SM3 哈希运算 Hmac 计算。
• 参数说明：

• 返回值：接口调用成功返回0，否则返回相应的 错误码。

Sm3Digest

• 功能描述：使用SM3生成摘要。
• 参数说明：

Sm4CbcEncrypt/Sm4CtrEncrypt

• 功能描述：使用 SM4 加密算法 CBC、CTR 模式的加密。
• 参数说明：

• 返回值：加密成功返回0，否则返回相应的 错误码。

Sm4CbcDecrypt/Sm4CtrDecrypt

• 功能描述：用于 SM4 加密算法 CBC、CTR 模式下的解密。
• 参数说明：

• 返回值：解密成功返回0，否则返回相应的 错误码。

Sm4EcbEncrypt

• 功能描述：方法是用于 SM4 加密算法 ECB 模式下的加密。
• 参数说明：

• 返回值：加密成功返回0，否则返回相应的 错误码。

Sm4EcbDecrypt

• 功能描述：使用 SM4 加密算法 ECB 模式下的解密。
• 参数说明：

• 返回值：解密成功返回0，否则返回相应的 错误码。

Sm4GcmEncrypt

• 功能描述：用于 SM4 加密算法 GCM 模式下的加密。
• 参数说明：

• 返回值：加密成功返回0，否则返回相应的 错误码。

Sm4GcmDecrypt

• 功能描述：使用 SM4 加密算法 GCM 模式下的解密。
• 参数说明：

• 返回值：解密成功返回0，否则返回相应的 错误码。

原生加密方式的接口调用示例

原生加密方式的接口调用示例代码如下：

#include<stdio.h>
#include "kms_enc_sdk.h"

int Sm4CbcTest()
{
        int i_ret = 0;

        unsigned char ch_orig[1024];
        int i_orig = 0;
        unsigned char ch_en[1024];
        int i_en = 0;
        unsigned char ch_de[1024];
        int i_de = 0;

        memset(ch_orig,0,sizeof(ch_orig));
        memset(ch_en,0,sizeof(ch_en));
        memset(ch_de,0,sizeof(ch_de));

        unsigned char key[16] = {
                0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef,
                0xfe, 0xdc, 0xba, 0x98, 0x76, 0x54, 0x32, 0x10};

        unsigned char iv[16] = {
                0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef,
                0xfe, 0xdc, 0xba, 0x98, 0x76, 0x54, 0x32, 0x10};

        strcpy(ch_orig,"this Sm4CbcTest");
        i_orig = strlen(ch_orig);

        i_ret = Sm4CbcEncrypt(ch_orig,i_orig,ch_en,&i_en,key,iv);
        if ( 0 != i_ret )
        {
                printf("Sm4CbcEncrypt error\n");
                return ( -1 );
        }

        i_ret = Sm4CbcDecrypt(ch_en,i_en,ch_de,&i_de,key,iv);
        if ( 0 != i_ret )
        {
                printf("Sm4CbcDecrypt error\n");
                return ( -1 );
        }
        printf("Sm4CbcDecrypt data is [%s]\n",ch_de);

        return ( 0 );
}

int main()
{
        int i_ret = 0;

        char region[128];
        char secretId[128];
        char secretKey[128];

        memset(region,0,sizeof(region));
        memset(secretId,0,sizeof(secretId));
        memset(secretKey,0,sizeof(secretKey));
        memset(domainName,0,sizeof(domainName));

        /*domainName    请填入TCE的域名地址*/
        strcpy(domainName,"replace-with-real-domainName");
        strcpy(region,"ap-guangzhou");
        strcpy(secretId,"replace-with-real-secretId");
        strcpy(secretKey,"replace-with-real-secretKey");

        i_ret = InitSdk(region,secretId,secretKey,domainName);
        if ( i_ret != 0 )
        {
                printf("InitSdk error\n");
                return ( -1 );
        }

        Sm4CbcTest();

        return ( 0 );    
}

错误码