旗舰版Python3接口文档

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

错误码

初始化 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(b'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 算法进行加密。 输入参数：

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

• 当接口返回的整数信息为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 = b'1234567890abcdef'
iv = b'1234567890abcdef'
aad = b'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.encode())
if ret == 0:
       print('Sm2PemChangeToPubkey ok')
else:
       print('Sm2PemChangeToPubkey error')

priKey = base64.b16decode("B8F66F0097488D8FA91FE857DFC9886356BA26A48C23F44271DD702F374174F0")

ret,digest = HashForSM3WithSM2(b'hello',pubKey,b'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(b'hello',key)
if ret == 0:
       print ('Sm3Hmac is ok:',hmac)
else:
       print ('Sm3Hmac is error',ret)

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

ret,en_data = Sm4CbcEncrypt(b'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(b'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(b'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(b'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)