服务热线:
181 2393 7129
新闻中心
当前位置:首页 > 新闻中心
国民技术N32S003/ N32S032_SM2国密算法API接口说明
浏览次数:644 

1. 概述

本文主要适用于已下载国民技术N32S003 芯片SM2国密算法的介绍,主要说明该类芯片中国密SM2算法接口和使用方法。

1.1. 支持的算法

N32S003 芯片提供的算法如下:
 SM4: ECB/CBC 加密/解密
 SM3: 获取摘要
 SM2: 加密/解密/签名/验证/密钥协商/密钥生成
 RNG: 随机数生成

1.2. 基本数据类型

typedef unsigned                char uint8_t;
typedef unsigned   short        int uint16_t;
typedef unsigned                int uint32_t;
typedef unsigned                   INT64 uint64_t;
typedef     signed               char int8_t;
typedef     signed  short       int int16_t;
typedef     signed               int int32_t;
typedef     signed                 INT64 int64  t;

2. SM2算法API说明

2.1. 算法库使用方法

算法库使用方法如下:
1. 将 SM2.h、HASH.h、RNG.h、Common.h 加入头文件夹中,将 RNG.lib 、Common.lib、
HASH.lib、SM2.lib 添加到工程中;
2. 按 3.3 节函数说明调用函数,例程见附录二提供的 demo。

2.2. 数据类型定义

enum{
          SM2_OK = 0x5a5a5a5a, // operation success 
          SM2_PointIsOnCrv_YES = 0x6a6a5a5a,             //point is on elliptic curve
          SM2_PointIsOnCrv_NOT = 0x5a5a6a6a,                   //point is not on elliptic curve
           SM2_PRIKEY_ERR,//prikey error
           SM2_PUBKEY_ERR,//pubkey error
            SM2_CONVERTION_ERR,//data type transfer error
           SM2_Verify_FAIL,//SM2 verify fail
           SM2_LengthErr, //length error
          SM2_AddrErr, //address error
           SM2_ROLE_ERR,//Role in key exchange is error 
           SM2_ATTACKED, //SM2 subject to attack
};

2.3. 函数接口说明

SM2 算法库包含的函数列表如下:

                                                   表 2-1 SM2 算法库函数表

函数

描述

uint32_t SM2_Init(void)

始化 SM2 模块

uint32_t SM2_GetKey(uint8_t priKey[32], uint8_t pubKey[65])

 SM2 密钥对函数

uint32_t SM2_GetPubKey(uint8_t priKey[32], uint8_t pubKey[65])

钥获取公钥

uint32_t SM2_PointisOnCurve(uint8_t Point[64])

断点是否在曲线上

uint32_t SM2_Sign(uint8_t E[32], uint8_t priKey[32], uint8_t r[32],

uint8_t s[32])

 

签名函数

uint32_t SM2_Verify(uint8_t E[32], uint8_t pubKey[65], uint8_t

r[32], uint8_t s[32])

验证函

uint32_t SM2_ExchangeKey(uint8_t role, uint8_t *IDA, uint32_t   IDAByteLen, uint8_t *IDB, uint32_t IDBByteLen, uint8_t dA[32], uint8_t PA[65],uint8_t PB[65], uint8_t rA[32], uint8_t RA[65],      uint8_t RB[65], uint32_t kByteLen, uint8_t *KA, uint8_t S1[32],

uint8_t SA[32])

 

 

 

 

密钥交换

uint32_t SM2_GetZ(uint8_t* ID, uint16_t IDByteLen, uint8_t

pubKey[65], uint8_t Z[32])

身份标识杂凑值计算函数

uint32_t SM2_GetE(uint8_t* M, uint32_t MByteLen, uint8_t Z[32],

uint8_t E[32])

息的 HUSH

uint32_t SM2_EncryptInit(uint8_t pubKey[65], uint8_t C1[65])

SM2 分步加密初始化函数

uint32_t SM2_EncryptUpdate(uint8_t* M, uint32_t MByteLen,

uint8_t* C2)

SM2 分步加密更新函数

uint32_t SM2_EncryptDone(uint8_t C3[32])

SM2 分步加密完成函数

uint32_t SM2_Encrypt(uint8_t *M, uint32_t MByteLen, uint8_t

pubKey[65], uint8_t *C, uint32_t *CByteLen)

 

单次加密函数

uint32_t SM2_DecryptInit(uint8_t priKey[32], uint8_t C1[65])

SM2 分步解密初始化函数

uint32_t SM2_DecryptUpdate(uint8_t* C2, uint32_t C2ByteLen,

uint8_t* M)

 

SM2 分步解密更新函数

uint32_t SM2_DecryptDone(uint8_t C3[32])

SM2 分步解密完成函数

uint32_t SM2_Decrypt(uint8_t * C, uint32_t CByteLen, uint8_t

priKey[32], uint8_t * M, uint32_t *MByteLen)

 单次解密函数

void SM2_Close(void)

SM2 函数

void SM2_Version(uint8_t *type, uint8_t *customer, uint8_t date[3],

uint8_t *version)

 获取 SM2 算法库版本

2.3.1.初始化SM2模块

SM2_Init 

初始化SM2模块                                                                                                         

函数原型

void SM2_Init(void)

参数说明

 

返回值

SM2_OK:初始化成功;其他值:初始化失败,详见枚举类型定义

注意事项

1. 进行SM2运算时,若还未初始化或已切换到其他算法,必须先调用此函数来

开启SM2模块。

2.3.2.密钥对生成

SM2_GetKey 

随机密钥对生成                                                                                                          

函数原型

uint32_t SM2_GetKey(uint8_t priKey[32], uint8_t pubKey[65])

参数说明

priKey 输出,私钥,字节大端输出,即高位在前低位在后

pubKey 输出,公钥,字节大端输出,首字节是 0x04,然后分别是 x|y 坐标

返回值

SM2_OK:运算正确;其他值:计算错误,详见枚举类型定义

注意事项

1. 调用本函数前,若还未初始化或已切换到其他算法,先调用 SM2_Init()启动SM2 模块;

2.私钥即一大数,要求必须在[1n-2]中,n SM2 曲线参数。


2.3.3.私钥生成公钥

SM2_GetPubKey 

私钥生成公钥                                                                                                          

函数原型

uint32_t SM2_GetPubKey(uint8_t priKey[32], uint8_t pubKey[65])

参数说明

priKey 输入,私钥,字节大端输入,即高位在前低位在后

pubKey 输出,公钥,字节大端输出,首字节是 0x04,然后分别是 x|y 坐标

返回值

SM2_OK:运算正确;其他值:计算错误,详见枚举类型定义

注意事项

1.调用本函数前,若还未初始化或已切换到其他算法,先调用 SM2_Init()启动SM2 模块

2. 私钥即一大数,要求必须在[1n-2]中,n SM2 曲线参数

2.3.4. 判断点是否在曲线上

SM2_PointisOnCurve 

判断点是否在曲线上                                                                                                      

函数原型

uint32_t SM2_PointisOnCurve(uint8_t Point[64])

参数说明

Point输入, 点坐标(x|y) x y 均为字节大端输入

返回值

SM2_PointIsOnCrv_YES :点在曲线上;其他值: 错误,详见枚举类型定义

注意事项

1.调用本函数前,若还未初始化或已切换到其他算法,先调用 SM2_Init()启动SM2 模块

2.3.5. 签名生成

SM2_Sign 

签名生成                                                                                                       

函数原型

uint32_t SM2_Sign(uint8_t E[32], uint8_t priKey[32], uint8_t r[32], uint8_t s[32])

参数说明

E       输入,待签名消息的 HASH

priKey 输入,签名者的私钥

r       输出,签名结果

s       输出,签名结果

 

返回值

SM2_OK:运算正确;其他值:计算错误,详见枚举类型定义

注意事项

1. 调用本函数前,若还未初始化或已切换到其他算法,先调用 SM2_Init()启动SM2 模块;

2. E prikey 存储介质可以为 RAM FLASH

3. E prikey RAM 存储,则签名结果 r s 可以复用此空间,但需保证空间足够;

4. prikey 要求必须在[1n-1]中。

2.3.6. 签名验证

SM2_Verify

签名验证                                                                                                       

函数原型

uint32_t SM2_Verify(uint8_t E[32], uint8_t pubKey[65], uint8_t r[32], uint8_t s[32])

参数说明

E      输入,待签名消息的 HASH

pubKey 输入,签名者的公钥

r       输入,签名结果

s      输入,签名结果

 

返回值

SM2_OK:运算正确;其他值:计算错误,详见枚举类型定义

注意事项

1.调用本函数前,若还未初始化或已切换到其他算法,先调用 SM2_Init()启动SM2 模块

2. E pubKey 存储介质可以为 RAM FLASH

2.3.7. 密钥协商(交换)

SSM2_ExchangeKey

密钥协商(交换)                                                                                                      

函数原型

uint32_t SM2_ExchangeKey(uint8_t role, uint8_t *IDA, uint32_t IDAByteLen,

uint8_t *IDB, uint32_t IDBByteLen, uint8_t dA[32], uint8_t PA[65],uint8_t

PB[65], uint8_t rA[32], uint8_t RA[65], uint8_t RB[65], uint32_t kByteLen,

uint8_t *KA, uint8_t S1[32], uint8_t SA[32])

参数说明

role        输入,角色,1-发起者,0-接受者

IDA       输入,发起方 ID

IDAByteLen      输入,IDB 的字节数

IDB        输入,接受方 ID

IDBByteLen     输入,IDB 的字节数

dA[32]       输入,己方私钥

PA[65]      输入,己方公钥

PB[65]        输入,对方公钥

rA[32]        输入,己方临时私钥

RA[65]         输入,己方临时公钥

RB[65]      输入,对方临时公钥

kByteLen       输入,协商密钥字节长度

KA [kByteLen] 输出,协商密钥

S1 [32]         输出,己方 S1

SA [32]       输出,己方 SA

返回值

SM2_OK:运算正确;其他值:计算错误,详见枚举类型值定义

注意事项

1. 调用本函数前,若还未初始化或已切换到其他算法,先调用 SM2_Init()启动 SM2 模块

2. 如果计算后的 S1=SB,S2=SA,则密钥交换成功,协商后的密钥为 KA

3. dAPBrARARBZAZB 存储介质可以为 RAM FLASH

4. 输出参数 KAS1SA 不能和输入参数 dAPBrARARBZAZB 使用同一 buffer。 

2.3.8. 用户杂凑值

SSM2_GetZy

用户身份标识杂凑值计算函数                                                                                                      

函数原型

uint32_t SM2_GetZ(uint8_t* ID, uint16_t IDByteLen, uint8_t pubKey[65], uint8_t Z[32])

 

参数说明

ID            输入,用户 A ID

IDByteLen     输入,用户 A ID 的字节数- 22 -

Pubkey        输入,用户 A 的公钥,65 字节

Z[32]             输出,用户 A 的杂凑值,32 字节

返回值

SM2_OK:计算成功,其他值:计算错误,详见枚举类型值定义

注意事项

1.符合 SM2 算法标准

2.调用本函数前,若还未初始化或已切换到其他算法,先调用 SM2_Init()启动 SM2 模块

3.运算结束后,本函数内部已再次调用 SM2_Init()启动 SM2 模块。

2.3.9. 消息杂凑值

SSM2_GetEy

消息的杂凑值计算函数                                                                                                      

函数原型

uint32_t SM2_GetE(uint8_t* M, uint32_t MByteLen, uint8_t Z[32], uint8_t E[32])

 

参数说明

M            输入,待签名验证消息

MByteLen      输入,待签名验证消息的字节数

Z              输入,签名者的 ID 杂凑值

E             输出,输入值 M Z 的杂凑值,32 字节

 

返回值

SM2_OK:计算成功, 其他值:计算错误,详见枚举类型值定义

注意事项

1.符合 SM2 算法标准;

2. 运算结束后,本函数内部已再次调用 SM2_Init()启动 SM2 模块。

2.3.10.  分步加密初始化函数

SM2_EncryptInity 

SM2 分步加密初始化函数                                                                                                       

函数原型

uint32_t SM2_EncryptInit(uint8_t pubKey[65], uint8_t C1[65])

参数说明

Pubkey      输入,公钥

C1     输出,密文的第一组成部分

 

 

返回值

SM2_OK:计算成功, 其他值:计算错误,详见枚举类型值定义

注意事项

1. 调用本函数前,若还未初始化或已切换到其他算法,先调用 SM2_Init()启动SM2 模块;

2. pubkey 存储介质可以为 RAM FLASH

3. pubkey C1 也不能是同一 buffer

4.按照新的国密规范,密文顺序从 C1||C2||C3 修正为 C1||C3||C2

2.3.11.  分步加密更新函数

SM2_EncryptUpdate 

SM2 分步加密更新函数                                                                                                       

函数原型

uint32_t SM2_EncryptUpdate(uint8_t* M, uint32_t MByteLen, uint8_t* C2)

 

参数说明

M                    输入,待加密消息

MByteLen       输入,消息的字节数

C2                   输出,密文的第二组成部分,长度与 MByteLen 相同

 

返回值

SM2_OK运算正确 其他值:计算错误,详见枚举类型值定义

注意事项

1. 调用本函数前,若还未初始化或已切换到其他算法,先调用 SM2_Init()启动 SM2 模块,且需与 SM2_EncryptInit 配合使用;

2. M 存储介质可以为 RAM FLASH

3. M C2 可以是同一 buffer

4.按照新的国密规范,密文顺序从 C1||C2||C3 修正为 C1||C3||C2 

2.3.12.  分步加密完成函数

SM2_EncryptDone  

SM2 分步加密完成函数                                                                                                       

函数原型

uint32_t SM2_EncryptDone(uint8_t C3[32] 

 

参数说明

C3 输出,密文的第三组成部分

返回值

SM2_OK:加密正确; 其他值:计算错误,详见枚举类型值定义

 

注意事项

1. 调用本函数前,若还未初始化或已切换到其他算法,先调用 SM2_Init()启动 SM2 模块,且需与 SM2_EncryptInitSM2_EncryptUpdate 配合使用;

2.按照新的国密规范,密文顺序从 C1||C2||C3 修正为 C1||C3||C2

2.3.13.  单次加密

SM2_Encrypt

SM2 单次加密函数                                                                                                     

函数原型

uint32_t SM2_Encrypt(uint8_t *M, uint32_t MByteLen, uint8_t pubKey[65],

uint8_t *C, uint32_t *CByteLen)

参数说明

M                      输入,明文

MByteLen         输入,明文的字节长度,0< MByteLen < (232 -97)

Pubkey               输入,公钥

C                        输出,密文

CByteLen          输出,密文的字节长度,应为(MByteLen +97)

 

返回值

SM2_OK运算正确 其他值:计算错误,详见枚举类型值定义

 

注意事项

1. 调用本函数前,若还未初始化或已切换到其他算法,先调用 SM2_Init()启动 SM2 模块;

2. M pubkey 存储介质可以为 RAM FLASH

3. M C 不能是同一 bufferpubkey C 也不能是同一 buffer

4.按照新的国密规范,密文顺序从 C1||C2||C3 修正为 C1||C3||C2

2.3.14.  分步解密初始化函数

SSM2_DecryptInit

SM2 分步解密初始化函数                                                                                                     

函数原型

uint32_t SM2_DecryptInit(uint8_t priKey[32], uint8_t C1[65])

参数说明

priKey      输入,私钥

C1             输入,密文的第一组成部分

 

返回值

SM2_OK:运算正确; 其他值:计算错误,详见枚举类型值定义

 

注意事项

1. 调用本函数前,若还未初始化或已切换到其他算法,先调用 SM2_Init()启动 SM2 模块;

2. priKey 存储介质可以为 RAM FLASH

3.按照新的国密规范,密文顺序从 C1||C2||C3 修正为 C1||C3||C2

2.3.15.  分步解密更新函数

SM2_DecrypUpdate  

SM2 分步解密更新函数                                                                                                     

函数原型

uint32_t SM2_DecryptUpdate(uint8_t* C2, uint32_t C2ByteLen, uint8_t* M)

参数说明

C2              输入,密文的第二组成部分

C2ByteLen    输入,C2 的字节数

M                 输出,消息,长度与 C2ByteLen 相同

 

返回值

SM2_OK:运算正确; 其他值:计算错误,详见枚举类型值定义

 

注意事项

1. 调用本函数前,若还未初始化或已切换到其他算法,先调用 SM2_Init()启动 SM2 模块,且需与 SM2_DecryptInit 配合使用;

2. C2 存储介质可以为 RAM FLASH

3. M C2 可以是同一 buffer

4.按照新的国密规范,密文顺序从 C1||C2||C3 修正为 C1||C3||C2

2.3.16.  分步解密完成函数

SSM2_DecrypDone  

SM2 分步解密完成函数                                                                                                     

函数原型

uint32_t SM2_DecryptDone(uint8_t C3[32])

参数说明

C3 输入,密文的第三组成部分

 

返回值

SM2_OK解密正确; 其他值:计算错误,详见枚举类型值定义

 

注意事项

1. 调用本函数前,若还未初始化或已切换到其他算法,先调用 SM2_Init()启动SM2 模块,且需与 SM2_DecryptInitSM2_DecryptUpdate 配合使用;

2.按照新的国密规范,密文顺序从 C1||C2||C3 修正为 C1||C3||C2 

2.3.17.  单次解密

SSM2_Decrypt  

SM2 单次解密                                                                                                      

函数原型

uint32_t SM2_DecryptDone(uint8_t C3[32])

参数说明

C3 输入,密文的第三组成部分

 

返回值

SM2_OK:解密正确; 其他值:计算错误,详见枚举类型值定义

 

注意事项

1. 调用本函数前,若还未初始化或已切换到其他算法,先调用 SM2_Init()启动SM2 模块,且需与 SM2_DecryptInitSM2_DecryptUpdate 配合使用;

2.按照新的国密规范,密文顺序从 C1||C2||C3 修正为 C1||C3||C2。  

2.3.18.  关闭SM2模块

SSM2_Close 

关闭 SM2 模块                                                                                                      

函数原型

 

参数说明

 

返回值

 

注意事项

1. SM2 运算完后,可调用本函数关闭 SM2 模块。

2.3.19.  获取SM2库版本信息

SSM2_Version 

获取 SM2 版本信息                                                                                                      

函数原型

void SM2_Version(uint8_t *type, uint8_t *customer, uint8_t date[3], uint8_t*version)

参数说明

type                   商业或安全版本

customer           标准或定制版本

date                  年,月,日

version             //版本 x.x

 

返回值

 

注意事项

*type = 0x03;                    // 商业和安全版

*customer = 0x00;             // 标准版本

date[0] = 18;                    //Year()

date[1] = 12;                    //Month()

date[2] = 28;                   //Day ()

*version = 0x10;             //表示版本 1.0








业务咨询1业务咨询2业务咨询3技术咨询Skype Me! 境外商务
QQ
0755-86583632
Tel