英飞凌HSM内核开发-CSM模块

CSM模块接口

初始化

• Csm_Init()：在使用CSM模块的其他功能之前，必须由BSWM调用初始化函数 Csm_Init()。这个函数负责设置CSM模块所需的初始状态和配置。
• Csm_InitMemory()：CSM还提供了一个用于手动将RAM变量初始化为null的函数 Csm_InitMemory()。这个函数可以在调用 Csm_Init() 之前调用，以确保所有RAM变量在模块启动前都被正确初始化。

主要功能

• 主函数：CSM模块实现提供了一个主函数，当启用异步作业处理时，这个主函数需要在任务级别循环调用。这个主函数负责将新作业分派到底层的CRYIF或CRYPTO驱动程序。

错误处理

• 开发错误报告：
  • 默认行为：默认情况下，如果启用了开发错误报告（即预编译参数 CSM_DEV_ERROR_DETECT==STD_ON），则使用服务 Det_ReportError() 向DET报告开发错误，如[2]中指定。
  • 自定义错误报告：如果使用另一个模块进行开发错误报告，集成商可以配置报告错误的函数原型，但该函数必须具有与服务 Det_ReportError() 相同的签名。

数据类型

Crypto_OperationModeType

• 类型：uint8
• 描述：指示要执行的模式/操作。
• 枚举值：
  • CRYPTO_OPERATIONMODE_START：执行开始操作。
  • CRYPTO_OPERATIONMODE_UPDATE：执行更新操作。
  • CRYPTO_OPERATIONMODE_FINISH：执行完成操作。
  • CRYPTO_OPERATIONMODE_STREAMSTART：执行开始和更新操作。
  • CRYPTO_OPERATIONMODE_SINGLECALL：执行开始、更新和完成操作。
  • CRYPTO_OPERATIONMODE_SAVE_CONTEXT：执行保存工作空间上下文。
  • CRYPTO_OPERATIONMODE_RESTORE_CONTEXT：执行恢复工作空间上下文。

Crypto_VerifyResultType

• 类型：uint8
• 描述：枚举验证操作的结果类型。
• 枚举值：
  • CRYPTO_E_VER_OK：验证结果为“true”，即两个比较的元素是相同的。这个返回码应作为值“0”给出。
  • CRYPTO_E_VER_NOT_OK：验证结果为“false”，即两个比较的元素不相同。这个返回码应作为值“1”给出。

Services provided by CSM

名称	功能简单介绍
Csm_Init	初始化CSM模块。
Csm_InitMemory	执行电源上电内存初始化。
Csm_MainFunction	模块的主函数，循环调用以处理异步作业。
Csm_GetVersionInfo	获取CSM模块的版本信息。
Csm_CancelJob	取消给定作业。
Csm_KeyElementSet	设置指定密钥ID的密钥元素字节。
Csm_KeySetValid	将指定密钥ID的密钥状态设置为有效。
Csm_KeyElementGet	检索指定密钥ID的特定密钥元素中的密钥元素字节。
Csm_KeyElementCopy	从一个密钥复制密钥元素到目标密钥。
Csm_KeyElementCopyPartial	部分复制一个密钥的元素到目标密钥。
Csm_KeyCopy	复制所有密钥元素从源密钥到目标密钥。
Csm_RandomSeed	为指定密钥ID的密钥元素提供随机种子。
Csm_KeyGenerate	生成新密钥材料并存储在指定的密钥ID中。
Csm_KeyDerive	通过使用给定密钥ID的密钥元素派生新密钥。
Csm_KeyExchangeCalcPubVal	计算密钥交换的公钥值。
Csm_KeyExchangeCalcSecret	计算密钥交换的共享秘密密钥。
Csm_CertificateParse	解析证书。
Csm_CertificateVerify	验证证书。
Csm_Hash	计算给定数据的哈希值。
Csm_MacGenerate	生成消息认证码（MAC）。
Csm_MacVerify	验证消息认证码（MAC）。
Csm_Encrypt	加密给定数据。
Csm_Decrypt	解密给定数据。
Csm_AEADEncrypt	执行AEAD加密。
Csm_AEADDecrypt	执行AEAD解密。
Csm_SignatureGenerate	生成签名。
Csm_SignatureVerify	验证签名。
Csm_RandomGenerate	生成随机数。
Csm_JobKeySetValid	设置作业密钥为有效。
Csm_JobRandomSeed	为作业设置随机种子。
Csm_JobKeyGenerate	为作业生成新密钥材料。
Csm_JobKeyDerive	为作业派生新密钥。
Csm_JobKeyExchangeCalcPubVal	计算作业密钥交换的公钥值。
Csm_JobKeyExchangeCalcSecret	计算作业密钥交换的共享秘密密钥。
Csm_SaveContextJob	保存作业上下文。
Csm_RestoreContextJob	恢复作业上下文。

Services used by CSM

Det_ReportError

Callback Functions Provided by CSM

CSM实现的回调函数

名称	功能简单介绍
Csm_CallbackNotification	当加密操作完成时，通知CSM模块操作的结果。

由CSM调用的其他模块实现的回调函数

名称	功能简单介绍
void CallbackFunc ASR 4.3 (Crypto_JobType *job, Std_ReturnType result)	ASR 4.3版本，当加密操作完成时，使用 Crypto_JobType *job, Std_ReturnType result 参数通知CSM模块操作的结果。
void CallbackFunc ASR 4.4 (const uint32 jobID, Csm_ResultType result)	ASR 4.4版本，当加密操作完成时，使用 const uint32 jobID, Csm_ResultType result 参数通知CSM模块操作的结果。
void CallbackFunc ASR R19-11 (const Crypto_JobType *job, Crypto_ResultType result)	ASR R19-11版本，当加密操作完成时，使用 const Crypto_JobType *job, Crypto_ResultType result 参数通知CSM模块操作的结果。

Configuration

加密栈的基本工作流程：

1. 服务请求：软件组件（Swc）请求CSM提供加密服务，并提供必要的数据以及将执行操作的CsmJob的ID。
2. CsmJob：包含所有执行加密操作所需的计算参数。
3. 队列分配：在配置时，每个CsmJob被分配到一个CsmQueue，无论作业的处理类型（同步或异步）。
4. 映射关系：每个CsmQueue映射到CryIfQueue，CryIfQueue映射到加密驱动对象（CryptoDriverObject）。
5. 加密驱动：在加密层，可以共存多个加密驱动，它们之间不会相互干扰。
6. 工作空间：CryptoDriverObject必须分配所需的工作空间并支持加密操作。Job在计算过程中占用加密服务的工作空间，因此在同一加密驱动对象中运行的Job以序列化方式处理，而在不同加密驱动对象中运行的Job或不同类型的加密Job可以并行运行。

支持的加密服务

服务类型	描述
MacGenerate	生成消息认证码（MAC）。
MacVerify	验证消息认证码（MAC）。
SignatureGenerate	生成数字签名。
SignatureVerify	验证数字签名。
Encrypt	对数据进行加密。
Decrypt	对加密数据进行解密。
Hash	计算数据的哈希值。
Random Generate	生成随机数。
AEADEncrypt	执行认证加密算法（AEAD）进行加密。
AEADDecrypt	执行认证加密算法（AEAD）进行解密。
KeySetValid	设置密钥状态为有效。
RandomSeed	设置随机种子以用于密钥生成等。
KeyGenerate	生成新的密钥材料。
KeyDerive	从现有密钥派生新的密钥。
KeyExchangeCalcPubVal	在密钥交换协议中计算公钥值。
KeyExchangeCalcSecret	在密钥交换协议中计算共享秘密值。