amt630hv160-sdk-release/amt630hv160-mcu/amt630hv160-mcu-iram/src/lib/hsm/libhsm.h

/*******************************************************************************
* File Name          : libhsm.h
* Author             : Sim
* Date First Issued  : 10/05/2024
* Description        : This file contains all the functions prototypes for the
*                      HSM library.
********************************************************************************
* History:
* 10/05/2024: V0.1
*******************************************************************************/

/* Define to prevent recursive inclusion -------------------------------------*/
#ifndef _LIBHSM_H
#define _LIBHSM_H
#include "amt630hv160_lib.h"

/* Includes ------------------------------------------------------------------*/


/* Exported macro ------------------------------------------------------------*/
#define HSM_OK                      (   0)
#define HSM_FAILED                  (  -1)
#define HSM_INPROGRESS              (  -2)
#define HSM_INVALID_HANDLE          (  -3)
#define HSM_INVALID_CONTEXT         (  -4)
#define HSM_INVALID_SIZE            (  -5)
#define HSM_NOT_INITIALIZED         (  -6)
#define HSM_NO_MEM                  (  -7)
#define HSM_INVALID_ALG             (  -8)
#define HSM_INVALID_KEY_SIZE        (  -9)
#define HSM_INVALID_ARGUMENT        ( -10)
#define HSM_MODULE_DISABLED         ( -11)
#define HSM_NOT_IMPLEMENTED         ( -12)
#define HSM_INVALID_BLOCK_ALIGNMENT ( -13)
#define HSM_INVALID_MODE            ( -14)
#define HSM_INVALID_KEY             ( -15)
#define HSM_AUTHENTICATION_FAILED   ( -16)
#define HSM_INVALID_IV_SIZE         ( -17)
#define HSM_MEMORY_ERROR            ( -18)
#define HSM_COMMON_ERROR_MAX        (-100)
#define HSM_FIFO_FULL               (-101)
#define HSM_CMD_FIFO_INACTIVE       (-102)

/* Hash Types */
#define HSM_MODE_HASH_MD5           0
#define HSM_MODE_HMAC_MD5           1
#define HSM_MODE_HASH_SHA1          2
#define HSM_MODE_HMAC_SHA1          3
#define HSM_MODE_HASH_SHA224        4
#define HSM_MODE_HMAC_SHA224        5
#define HSM_MODE_HASH_SHA512_224    6
#define HSM_MODE_HMAC_SHA512_224    7
#define HSM_MODE_HASH_SHA3_224      8
#define HSM_MODE_HASH_SHA256        9
#define HSM_MODE_HMAC_SHA256        10
#define HSM_MODE_HASH_SHA512_256    11
#define HSM_MODE_HMAC_SHA512_256    12
#define HSM_MODE_HASH_SHA3_256      13
#define HSM_MODE_HASH_SHA384        14
#define HSM_MODE_HMAC_SHA384        15
#define HSM_MODE_HASH_SHA3_384      16
#define HSM_MODE_HASH_SHA512        17
#define HSM_MODE_HMAC_SHA512        18
#define HSM_MODE_HASH_SHA3_512      19
#define HSM_MODE_HASH_CRC32         20
#define HSM_MODE_HASH_SM3           21
#define HSM_MODE_HMAC_SM3           22

/* Cipher Types */
#define HSM_MODE_AES_ECB            23
#define HSM_MODE_AES_CBC            24
#define HSM_MODE_AES_CTR            25
#define HSM_MODE_AES_CCM            26
#define HSM_MODE_AES_GCM            27
#define HSM_MODE_AES_F8             28
#define HSM_MODE_AES_XTS            29
#define HSM_MODE_AES_CFB            30
#define HSM_MODE_AES_OFB            31
#define HSM_MODE_AES_CS1            32
#define HSM_MODE_AES_CS2            33
#define HSM_MODE_AES_CS3            34
#define HSM_MODE_MULTI2_ECB         35
#define HSM_MODE_MULTI2_CBC         36
#define HSM_MODE_MULTI2_OFB         37
#define HSM_MODE_MULTI2_CFB         38
#define HSM_MODE_3DES_CBC           39
#define HSM_MODE_3DES_ECB           40
#define HSM_MODE_DES_CBC            41
#define HSM_MODE_DES_ECB            42
#define HSM_MODE_KASUMI_ECB         43
#define HSM_MODE_CHACHA20_STREAM    44
#define HSM_MODE_SM4_ECB            45
#define HSM_MODE_SM4_CBC            46
#define HSM_MODE_SM4_CFB            47
#define HSM_MODE_SM4_OFB            48
#define HSM_MODE_SM4_CTR            49
#define HSM_MODE_SM4_CCM            50
#define HSM_MODE_SM4_GCM            51
#define HSM_MODE_SM4_F8             52
#define HSM_MODE_SM4_XTS            53
#define HSM_MODE_SM4_CS1            54
#define HSM_MODE_SM4_CS2            55
#define HSM_MODE_SM4_CS3            56
#define HSM_MODE_CHACHA20_POLY1305  57
#define HSM_MODE_HASH_SHAKE128      58
#define HSM_MODE_HASH_SHAKE256      59
#define HSM_MODE_KASUMI_F8          60
#define HSM_MODE_MAC_CMAC           61
#define HSM_MODE_MAC_KASUMI_F9      62
#define HSM_MODE_MAC_KMAC128        63
#define HSM_MODE_MAC_KMAC256        64
#define HSM_MODE_MAC_KMACXOF128     65
#define HSM_MODE_MAC_KMACXOF256     66
#define HSM_MODE_MAC_POLY1305       67
#define HSM_MODE_MAC_SM4_CMAC       68
#define HSM_MODE_MAC_SM4_XCBC       69
#define HSM_MODE_MAC_SNOW3G_UIA2    70
#define HSM_MODE_MAC_XCBC           71
#define HSM_MODE_MAC_ZUC_UIA3       72
#define HSM_MODE_SNOW3G_UEA2        73
#define HSM_MODE_ZUC_UEA3           74
#define HSM_MODE_HMAC_SHA3_224      75
#define HSM_MODE_HMAC_SHA3_256      76
#define HSM_MODE_HMAC_SHA3_384      77
#define HSM_MODE_HMAC_SHA3_512      78


/* Exported types ------------------------------------------------------------*/
struct pka_rsa_mod {
   uint8_t *m;		//modulus
   uint8_t *r_sqr;  //Montgomery r2 mod m Precalculation
   uint8_t *mp;		//Montgomery m' Precalculation
};

struct pka_rsa_key {
   uint16_t mod_size;	//modulus bits
   struct pka_rsa_mod n;
   uint8_t *exp;	//Exponentiation
};

struct ecc_point {
   uint8_t *x;
   uint8_t *y;
};

/* Exported enums ------------------------------------------------------------*/
enum hashType{
   PKA_HASH_SHA224 = 0,
   PKA_HASH_SHA256,
   PKA_HASH_SHA384,
   PKA_HASH_SHA512
};

/* Exported functions ------------------------------------------------------- */
/* HSM --------------------------------------------------------------------- */
/*
 * HSM打开/关闭调试输出
 * param [in] debug_on 1:打开调试 0:关闭调试
 * return
 *   - none
 */
void HSM_Logout(int debug_on);

/* Exported functions ------------------------------------------------------- */
/* EHSE --------------------------------------------------------------------- */
/*
 * EHSE模块初始化
 * return 出错返回HSM_FAILED，成功返回HSM_OK
 */
int EHSE_Init(void);

/*
 * EHSE模块DDT初始化
 * param [in] pddt DDT表地址，要求8字节对齐
 * param [in] size DDT表大小，整个pddt内存不能跨越512K地址
 * return
 *   - HSM_XXX
 */
int EHSE_DDT_Init(void *pddt, uint32_t size);

/*
 * HASH计算
 * param [in] in 输入数据
 * param [in] inlen 输入数据长度
 * param [out] out 输出数据
 * param [inout] outlen 输出数据长度
 * param [in] hash_type hash类型，比如HSM_MODE_HASH_SHA256
 * return
 *   - HSM_XXX
 */
int EHSE_Hash(uint8_t *in, uint32_t inlen, uint8_t *out, uint32_t *outlen, int hash_type);

/*
 * HMAC计算
 * param [in] in 输入数据
 * param [in] inlen 输入数据长度
 * param [in] key 密钥
 * param [in] keysz 密钥长度
 * param [out] out 输出数据
 * param [inout] outlen 输出数据长度
 * param [in] hmac_type hmac类型，比如HSM_MODE_HMAC_SHA256
 * return
 *   - HSM_XXX
 */
int EHSE_Hmac(uint8_t *in, uint32_t inlen, void *key, uint32_t keysz,
		uint8_t *out, uint32_t *outlen, int hmac_type);

/*
 * 对称加密
 * param [in] in 原始数据
 * param [out] out 加密后的数据
 * param [in] len 数据长度
 * param [in] key 密钥
 * param [in] keysz 密钥长度
 * param [in] iv 初始化向量
 * param [in] ivsz 初始化向量长度
 * param [in] ciper_type 加密类型，比如HSM_MODE_AES_CTR
 * return
 *   - HSM_XXX
 */
int EHSE_CiperEncrypt(uint8_t *in, uint8_t *out, uint32_t len,
                 uint8_t *key, uint32_t keysz,
				 uint8_t *iv, uint32_t ivsz,
				 int ciper_type);

/*
 * 对称解密
 * param [in] in 加密后的数据
 * param [out] out 原始数据
 * param [in] len 数据长度
 * param [in] key 密钥
 * param [in] keysz 密钥长度
 * param [in] iv 初始化向量
 * param [in] ivsz 初始化向量长度
 * param [in] ciper_type 加密类型，比如HSM_MODE_AES_CTR
 * return
 *   - HSM_XXX
 */
int EHSE_CiperDecrypt(uint8_t *in, uint8_t *out, uint32_t len,
                 uint8_t *key, uint32_t keysz,
				 uint8_t *iv, uint32_t ivsz,
				 int ciper_type);

/*
 * 对称认证加密
 * param [in] in 原始数据
 * param [out] out 加密后的数据
 * param [in] len 数据长度
 * param [in] aad 填充数据
 * param [in] aadlen 填充数据长度
 * param [out] tag 生成的标签数据
 * param [in] taglen 接收标签数据缓存大小
 * param [in] key 密钥
 * param [in] keysz 密钥长度
 * param [in] iv 初始化向量
 * param [in] ivsz 初始化向量长度
 * param [in] ciper_type 加密类型，比如HSM_MODE_AES_GCM
 * return
 *   - HSM_XXX
 */
int EHSE_CiperAuthEncrypt(uint8_t *in, uint8_t *out, uint32_t len,
                 uint8_t *aad, uint32_t aadlen,
                 uint8_t *tag, uint8_t taglen,
                 uint8_t *key, uint32_t keysz,
				 uint8_t *iv, uint32_t ivsz,
				 int ciper_type);

/*
 * 对称认证解密
 * param [in] in 加密后的数据
 * param [out] out 原始数据
 * param [in] len 数据长度
 * param [in] aad 填充数据
 * param [in] aadlen 填充数据长度
 * param [in] tag 标签数据
 * param [in] taglen 标签数据大小
 * param [in] key 密钥
 * param [in] keysz 密钥长度
 * param [in] iv 初始化向量
 * param [in] ivsz 初始化向量长度
 * param [in] ciper_type 加密类型，比如HSM_MODE_AES_GCM
 * return
 *   - HSM_XXX
 */
int EHSE_CiperAuthDecrypt(uint8_t *in, uint8_t *out, uint32_t len,
                 uint8_t *aad, uint32_t aadlen,
                 uint8_t *tag, uint8_t taglen,
                 uint8_t *key, uint32_t keysz,
				 uint8_t *iv, uint32_t ivsz,
				 int ciper_type);


/* PKA  --------------------------------------------------------------------- */
/*
 * PKA模块初始化
 * return 出错返回HSM_FAILED，成功返回HSM_OK
 */
int PKA_Init(void);

/*
 * RSA预计算
 * param [inout] mod 根据输入的模数m计算r_sqr和mp
 * param [in] modlen 模数m的bit数
 * return
 *   - HSM_XXX
 */
int PKA_RsaPrecomp(struct pka_rsa_mod *mod, uint16_t  modlen);

/*
 * RSA PKCS1-v1_5 签名
 * param [in] key 私钥,exp指向私钥数据
 * param [in] hash 要签名的hash数据
 * param [in] htype hash数据类型
 * param [out] signature 签名后的数据
 * return
 *   - HSM_XXX
 */
int PKA_RsaSign(struct pka_rsa_key *key, uint8_t *hash, enum hashType htype, uint8_t *signature);

/*
 * RSA PKCS1-v1_5 认证
 * param [in] key 公钥,exp指向公钥数据
 * param [in] hash 要签名的hash数据
 * param [in] htype hash数据类型
 * param [out] signature 签名后的数据
 * return
 *   - HSM_XXX
 */
int PKA_RsaVerify(struct pka_rsa_key *key, uint8_t *hash,
						enum hashType htype, uint8_t *signature);

/*
 * RSA PKCS1-v1_5 加密
 * param [in] key 私钥,exp指向私钥数据
 * param [in] m 要加密的消息
 * param [in] mlen 消息长度
 * param [in] rng 填充数据
 * param [in] rnglen 填充数据长度
 * param [out] ct 加密后的数据
 * return
 *   - HSM_XXX
 */
int PKA_RsaEncrypt(struct pka_rsa_key *key , uint8_t *m, uint32_t mlen,
						uint8_t *rng, uint16_t rnglen, uint8_t *ct);

/*
 * RSA PKCS1-v1_5 解密
 * param [in] key 公钥,exp指向公钥数据
 * param [in] ct 加密后的数据
 * param [out] msg 被加密的消息
 * param [in] msglen 被加密的消息长度
 * return
 *   - HSM_XXX
 */
int PKA_RsaDecrypt(struct pka_rsa_key *key, uint8_t *ct, uint8_t *msg, uint32_t msglen);

/*
 * PKA 生成伪随机数
 * param [out] data 生成伪随机数
 * param [in] size 需要生成的随机数长度
 * return
 *   - HSM_XXX
 */
int PKA_Random(uint8_t *data, uint32_t size);

/*
 * PKA 根据私钥计算公钥
 * param [in] keypriv 私钥
 * param [out] keypub 生成的公钥
 * return
 *   - HSM_XXX
 */
int PKA_Sm2KeyGenerate(uint8_t *keypriv, struct ecc_point keypub);

/*
 * PKA SM2 签名
 * param [in] keypriv 私钥
 * param [in] k 随机数k
 * param [in] hash 要签名的数据e = SM3_HASH(ZA || M)
 * param [in] hlen 要签名的数据长度
 * param [out] r 生成的签名数据r
 * param [out] s 生成的签名数据s
 * return
 *   - HSM_XXX
 */
int PKA_Sm2Sign(uint8_t *keypriv, uint8_t *k, uint8_t *hash, uint32_t hlen,
					uint8_t *r, uint8_t *s);

/*
 * PKA SM2 认证
 * param [in] keypub 公钥
 * param [in] hash 要签名的数据e = SM3_HASH(ZA || M)
 * param [in] hlen 要签名的数据长度
 * param [in] r 生成的签名数据r
 * param [in] s 生成的签名数据s
 * return
 *   - HSM_XXX
 */
int PKA_Sm2Verify(struct ecc_point keypub, uint8_t *hash, uint32_t hlen,
					uint8_t *r, uint8_t *s);

/*
 * SM2 计算Za(SHA256, 不支持SM3)
 * Za = SHA256_HASH(ENTLa || IDa || a || b || xg || yg || xa || Ya )
 * param [in] keypub 公钥
 * param [in] ida 用户IDa标识符
 * param [in] idalen ida数据长度
 * param [out] za 生成的Za数据
 * return
 *   - HSM_XXX
 */
int SM2_ComputeZa(struct ecc_point keypub, uint8_t *ida, uint32_t idalen, uint8_t *za);


/* TRNG --------------------------------------------------------------------- */

/*
 * TRNG模块初始化
 * return 出错返回HSM_FAILED，成功返回HSM_OK
 */
int TRNG_Init(void);

/*
 * 产生一个随机数
 * return
 *   - HSM_OK
 *   - HSM_FAILED
 */
int TRNG_GenRandom(void);

/*
 * 获取随机数
 * param [out] out 接收随机数的缓存，最少16个字节
 * return
 *   - 写到out缓存的字节数，16个字节
 */
int TRNG_GetRandom(uint8_t *out);

/*
 * 重设种子
 * param [in] nonce 种子数据，空指针使用随机种子，否则指向32个字节的缓存
 * return
 *   - HSM_XXX
 */
int TRNG_Reseed(const uint8_t *nonce);

/*
 * 设置请求随机数多少次后提醒重设种子,如果同时设置了Age，只会触发更快触发的提醒
 * param [in] val 请求随机数16*val次后提醒重设种子
 * return
 *   - HSM_XXX
 */
int TRNG_SetReqReminder(uint32_t val);

/*
 * 设置多长时间后提醒重设种子，如果同时设置了Req，只会触发更快触发的提醒
 * param [in] sec 每隔sec秒提醒重设种子
 * return
 *   - HSM_XXX
 */
int TRNG_SetAgeReminder(uint32_t sec);

/*
 * 注册随机数请求超次数重设种子提醒回调函数，该回调函数执行在中断上下文，
 * 函数内不能调用TRNG_GenRandom, TRNG_Reseed这些会阻塞的函数
 */
void TRNG_RegisterReqCallback(void (*func)(void));

/*
 * 注销随机数请求超次数重设种子提醒回调函数
 */
void TRNG_UnregisterReqCallback();

/*
 * 注册超时重设种子提醒回调函数，该回调函数执行在中断上下文，
 * 函数内不能调用TRNG_GenRandom, TRNG_Reseed这些会阻塞的函数
 */
void TRNG_RegisterAgeCallback(void (*func)(void));

/*
 * 注销超时重设种子提醒回调函数
 */
void TRNG_UnregisterAgeCallback();

#endif /* _LIBHSM_H */