旗舰版Python2接口文档

Python2 语言 SDK，底层使用 C 语言实现，上层通过 ctypes 封装后，提供接口供 Python2 语言调用。

错误码

初始化 SDK 接口

InitSdk

功能描述：检验用户是否开通 KMS 旗舰版服务。

输入参数：

返回值：接口返回一个整数。

• 当接口返回值为0，表示初始化成功。
• 当接口返回值为非0，代表初始化失败。

注意：

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

KMS 加密方式的接口说明

NewMasterKey

功能描述：将用户首个主密钥加入主密钥信息列表。

参数说明：

返回值：接口返回整数、主密钥信息列表。

• 当接口返回整数值为0，表示添加成功。
• 当接口返回整数值为非0，代表添加失败。

注意：

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

AddMasterKey

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

参数说明：

返回值：接口返回整数、主密钥信息列表。

• 当接口返回值为0，表示添加成功。
• 当接口返回值为非0，代表添加失败。

InitKeyManager

功能描述：初始化用户的主密钥，包含主密钥信息、密钥加密次数、密钥生效时间等，具体看后续参数。

参数说明：

返回值：接口返回 KeyManager 对象。

• 当接口返回值不为 None，表示初始化成功。
• 当接口返回值为 None，代表初始化失败。

Encrypt

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

输入参数：

返回值：接口返回三个内容，一个整数、一个 MsgHead 对象、一个字符串类型的加密后的密文。

• 当接口返回的整数信息为0，代表加密成功。
• 当接口返回的整数信息为非0，代表加密失败。

注意：

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

Decrypt

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

输入参数：

返回值：接口返回三个内容，一个整数、一个 MsgHead 结构体、一个字符串类型的解密后的明文。

• 当接口返回的整数信息为0，代表解密成功。
• 当接口返回的整数信息为非0，代表解密失败。

Algorithm 支持的加密算法列表

KMS 加密方式接口调用示例

#coding=utf-8
import sys
import os
import time

from kms_enc_sdk import *

region1 = 'replace-with-real-region1'
keyId1 = 'replace-with-realkeyid1'
region2 = 'replace-with-real-region2'
keyId2 = 'replace-with-realkeyid2'
secretId = 'replace-with-real-secretId'
secretKey = 'replace-with-real-secretKey'
domainName = 'replace-with-real-domainName'

def ECBEnAndDeWithSignTest():
       ret,masterKey = NewMasterKey(region1,keyId1)
       if ret != 0:
           print('NewMasterKey error:',ret)
           return
       ret,masterKey = AddMasterKey(masterKey,region2,keyId2)
       if ret != 0:
           print('AddMasterKey error:',ret)
           return

       keymanager = InitKeyManager(masterKey,0,0,0,secretId,secretKey)
       if keymanager == None:
           print('KeyManager error')
           return

       ret,enheader,endata = Encrypt('hello',keymanager,masterKey,Algorithm.SM4_ECB_128_WITH_SIGNATURE,'{}',0)
       if ret == 0:
           print('Encrypt ok')
       else:
           print('Encrypt error:',ret)
           return

       ret,deheader,dedata = Decrypt(endata,keymanager)
       if ret == 0:
           print 'dedata:',
           print dedata
       else:
           print('Decrypt error:',ret)



ret = InitSdk(region1,secretId,secretKey,domainName)
if ret != 0:
       print('InitSdk error:',ret)
       sys.exit(1)

ECBEnAndDeWithSignTest()

原生加密方式的接口说明

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

说明：

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

Sm2GetKey

功能描述：使用 SM2 算法生成密钥对。

输入参数：无需填充输入参数。

返回值：接口返回三个内容，一个整数和两个字符串（分别是生成的公钥值及私钥值）。

• 当接口返回的整数信息为0，表示获取密钥对成功；
• 当接口返回的整数信息为非0，代表获取失败。

Sm2Sign

功能描述：使用 SM2 算法进行签名。

输入参数：

返回值：接口返回两个内容，一个整数和一个包含签名内容的字符串。

• 当接口返回的整数信息为0，代表签名成功。
• 当接口返回的整数信息为非0，代表签名失败。

注意：

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

Sm2Verify

功能描述：使用 SM2 算法进行验签。

输入参数：

• 返回值：接口返回一个整数。
• 当接口返回的整数信息为0，表示验签成功。
• 当接口返回的整数信息为非0，代表验签失败。

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

Sm2Encrypt

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

  参数名称	必选	类型	描述
  pubkey	是	str	公钥内容，数据长度为64字节
  source	是	str	源数据

返回值：接口返回两个内容，一个整数和一个包含加密后的密文内容的字符串。

• 当接口返回的整数信息为0，代表加密成功。
• 当接口返回的整数信息为非0，代表加密失败。

注意：

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

Sm2Decrypt

功能描述：使用SM2算法进行解密

输入参数：

返回值：接口返回两个内容，一个整数和一个包含解密后的明文内容的字符串。

• 当接口返回的整数信息为0，代表解密成功。
• 当接口返回的整数信息为非0，代表解密失败。

Sm2PemChangeToPubkey

功能描述：对 pem 格式的公钥内容进行转换。

输入参数：

返回值：接口返回两个内容，一个整数和一个包含转换后的公钥内容的字符串。

• 当接口返回的整数信息为0，代表转换成功。
• 当接口返回的整数信息为非0，代表转换失败。

HashForSM3WithSM2

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

输入参数：

返回值：接口返回两个内容，一个整数和一个包含生成的摘要内容的字符串。

• 当接口返回的整数信息为0，代表摘要生成成功。
• 当接口返回的整数信息为非0，代表摘要生成失败。

Sm2SignWithDigest

功能描述：使用本地生成的消息摘要生成签名

输入参数：

返回值：接口返回两个内容，一个整数和一个包含生成签名内容的字符串。

• 当接口返回的整数信息为0，代表签名成功。
• 当接口返回的整数信息为非0，代表摘要签名失败。

Sm2VerifyWithDigest

功能描述：通过生成的摘要内容进行验签。

输入参数：

返回值：接口返回一个整数。

• 当接口返回的整数信息为0，代表验签成功。
• 当接口返回的整数信息为非0，代表摘要验签失败。

Sm3Hmac

功能描述：使用 SM3 哈希运算 Hmac 计算。

输入参数：

返回值：接口返回两个内容，一个整数和一个包含 Hmac 内容的字符串。

• 当接口返回的整数信息为0，代表 Hmac 计算成功。
• 当接口返回的整数信息为非0，代表 Hmac 计算失败。

Sm3Digest

功能描述：使用 SM3 生成摘要。

输入参数：

返回值：接口返回两个内容，一个整数和一个包含摘要内容的字符串。

• 当接口返回的整数信息为0，代表生成摘要成功。
• 当接口返回的整数信息为非0，代表生成摘要失败。

Sm4CbcEncrypt/Sm4CtrEncrypt

功能描述：方法是用于 SM4 加密算法 CBC、CTR 模式下的加密。

输入参数：

返回值：接口返回两个内容，一个整数和一个包含加密后的密文内容的字符串。

• 当接口返回的整数信息为0，代表加密成功。
• 当接口返回的整数信息为非0，代表加密失败。

Sm4CbcDecrypt/Sm4CtrDecrypt

功能描述：方法是用于 SM4 加密算法 CBC、CTR 模式下的解密。

输入参数：

返回值：接口返回两个内容，一个整数和一个包含解密后的明文内容的字符串。

• 当接口返回的整数信息为0，代表解密成功。
• 当接口返回的整数信息为非0，代表解密失败。

Sm4EcbEncrypt

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

输入参数：

返回值：接口返回两个内容，一个整数和一个包含加密后的密文内容的字符串。

• 当接口返回的整数信息为0，代表加密成功。
• 当接口返回的整数信息为非0，代表加密失败。

Sm4EcbDecrypt

功能描述：方法是用于 SM4 加密算法 ECB 模式下的解密。

输入参数：

返回值：接口返回两个内容，一个整数和一个包含解密后的明文内容的字符串。

• 当接口返回的整数信息为0，代表解密成功。
• 当接口返回的整数信息为非0，代表解密失败。

Sm4GcmEncrypt

功能描述：方法是用于 SM4 加密算法 GCM 模式下的加密。

输入参数：

返回值：接口返回三个内容，一个整数、一个包含加密后的密文内容的字符串、一个包含加密后的 tag 内容的字符串。

• 当接口返回的整数信息为0，代表加密成功。
• 当接口返回的整数信息为非0，代表加密失败。

Sm4GcmDecrypt

功能描述：方法是用于 SM4 加密算法 GCM 模式下的解密。

输入参数：

返回值：接口返回两个内容，一个整数和一个包含解密后的明文内容的字符串。

• 当接口返回的整数信息为0，代表解密成功。
• 当接口返回的整数信息为非0，代表解密失败。

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

#coding=utf-8
import sys
import os
import time

from kms_enc_sdk import *

key = "1234567890abcdef"
iv = "1234567890abcdef"
aad = "1234567890abcdef"

region = 'replace-with-real-region'
secretId = 'replace-with-real-secretId'
secretKey = 'replace-with-real-secretKey'
domainName = 'replace-with-real-domainName'

ret = InitSdk(region,secretId,secretKey,domainName)
if ret != 0:
         print('InitSdk error:',ret)
         sys.exit(1)

ret,pubKey,priKey = Sm2GetKey()
if ret == 0:
         print ("Sm2GetKey ok")

         ret,sm2endata = Sm2Encrypt(pubKey,b'this Sm2Test')
         if ret == 0:
             print ("Sm2Encrypt:",sm2endata)
             ret,sm2dedata = Sm2Decrypt(priKey,sm2endata)
             if ret == 0:
                 print ("Sm2Decrypt:",sm2dedata)
             else:
                 print ("Sm2Decrypt is error",ret)
         else:
             print ("Sm2Encrypt is error",ret)


         ret,sign = Sm2Sign(pubKey,priKey,b'hello world')
         if ret == 0:
             print ("Sm2Sign is ok",sign)
             ret = Sm2Verify(pubKey,sign,b'hello world')
             if ret == 0:
                 print ("Sm2Verify is ok")
             else:
                 print ("Sm2Verify is error",ret)
         else:
             print ("Sm2Sign is error",ret)
else:
         print ("Sm2GetKey is error",ret)


pemInfo = "-----BEGIN PUBLIC KEY-----\n"
pemInfo += "MFkwEwYHKoZIzj0CAQYIKoEcz1UBgi0DQgAE5rwEIw9e5fX87uSN7C/vy6lyEZ2R\n"
pemInfo += "gzLqWLnY8EPN1C+nJP2v4rLgaQCbHV38+vBVLimbLmdccLM69R83JxpxuQ==\n"
pemInfo += "-----END PUBLIC KEY-----\n"

ret,pubKey = Sm2PemChangeToPubkey(pemInfo)
if ret == 0:
         print('Sm2PemChangeToPubkey ok')
else:
         print('Sm2PemChangeToPubkey error')

priKey = "B8F66F0097488D8FA91FE857DFC9886356BA26A48C23F44271DD702F374174F0".decode('hex')

ret,digest = HashForSM3WithSM2('hello',pubKey,'1234567812345678')
if ret == 0:
         print('HashForSM3WithSM2 ok')
else:
         print('HashForSM3WithSM2 error')

ret,sign = Sm2SignWithDigest(pubKey,priKey,digest)
if ret == 0:
         print('Sm2SignWithDigest ok')
else:
         print('Sm2SignWithDigest error')

ret = Sm2VerifyWithDigest(pubKey,sign,digest)
if ret == 0:
         print('Sm2VerifyWithDigest ok')
else:
         print('Sm2VerifyWithDigest error')


ret,hmac = Sm3Hmac("hello",key)
if ret == 0:
         print ("Sm3Hmac is ok:",hmac)
else:
         print ("Sm3Hmac is error",ret)

ret,digest = Sm3Digest('hello')
if ret == 0:
         print ('Sm3Digest is ok:',digest)
else:
         print ('Sm3Digest is error',ret)

ret,en_data = Sm4CbcEncrypt("this Sm4CbcTest",key,iv)
if ret == 0:
         ret,de_data = Sm4CbcDecrypt(en_data,key,iv)
         if ret == 0:
             print (de_data)
         else:
             print ("Sm4CbcDecrypt is error",ret)
else:
         print ("Sm4CbcEncrypt is error",ret)



ret,en_data = Sm4CtrEncrypt("this Sm4CtrTest",key,iv)
if ret == 0:
         ret,de_data = Sm4CtrDecrypt(en_data,key,iv)
         if ret == 0:
             print (de_data)
         else:
             print ("Sm4CtrDecrypt is error",ret)
else:
         print ("Sm4CtrEncrypt is error",ret)



ret,en_data = Sm4EcbEncrypt("this Sm4EcbTest",key)
if ret == 0:
         ret,de_data = Sm4EcbDecrypt(en_data,key)
         if ret == 0:
             print (de_data)
         else:
             print ("Sm4EcbDecrypt is error",ret)
else:
         print ("Sm4EcbEncrypt is error",ret)

ret,en_data,tag = Sm4GcmEncrypt("this Sm4GcmTest",key,iv,aad)
if ret == 0:
         ret,de_data = Sm4GcmDecrypt(en_data,key,iv,aad,tag)
         if ret == 0:
          print (de_data)
         else:
             print ("Sm4GcmDecrypt is error",ret)
else:
         print ("Sm4GcmEncrypt is error",ret)