开源小满EasyXMen
KeyM¶
文档信息 Document Information¶
版本历史 Version History¶
日期(Date) |
作者(Author) |
版本(Version) |
状态(Status) |
说明(Description) |
|---|---|---|---|---|
2025/02/22 |
jie.gu |
V0.1 |
发布(Release) |
首次发布(First release) |
2025/04/04 |
jie.gu |
V1.0 |
发布(Release) |
正式发布(Official release) |
参考文档 References¶
编号(Number) |
分类(Classification) |
标题(Title) |
版本(Version) |
|---|---|---|---|
1 |
Autosar |
AUTOSAR_CP_SRS_CryptoStack.pdf |
R23-11 |
2 |
Autosar |
AUTOSAR_CP_SWS_KeyManager.pdf |
R23-11 |
术语与简写 Terms and Abbreviations¶
术语 Terms¶
术语(Terms) |
解释(Explanation) |
|---|---|
Callback |
在本文档中，术语 “callback” 用于API services，其旨在向其他BSW modules发送通知。(For the purpose of this file, the term “callback” is used for API services, which are intended for sending notifications to other BSW modules.) |
Callout |
Callouts是函数存根（function stubs），可在配置阶段填充内容，其用途是为提供callout的模块增加功能。(Callouts are function stubs that can be filled in during configuration phase, in order to add functions to modules that provide callouts.) |
Class |
Class代表一组具有相似电气特性的信号。(Class represents a group of signals with similar electrical characteristics.) |
Client / Server communication |
本定义摘录自[9]：客户端 - 服务器（Client-server）通信涉及两个实体，即作为service 请求方（或使用者）的client，以及提供service的server。client发起通信，请求server执行某项service，必要时会传输一个参数集（parameter set）。以RTE形式存在的server，会等待来自client的传入通信请求，执行所请求的service，并将响应（response）发送至client的请求。因此，通过通信的发起方向，可对AUTOSAR软件组件（AUTOSAR Software Component）是client还是server进行分类。(This definition is excerpted from [9]: Client-server communication involves two entities, i.e., the client as the service requester (or user), and the server providing services.) The client initiates communication to request the server to execute some service, and also, where necessary, transmits a parameter set. The server in the form of RTE waits for the inward transmission communication requests from client, executes the requested service, and sends response to the client’s request. Therefore, classify whether the AUTOSAR Software Component is a client or a server by the initiation direction of communication. |
简写 Abbreviations¶
简写(Abbreviation) |
全称(Full name) |
解释(Explanation) |
|---|---|---|
KeyM |
Key Manager |
密钥管理器 |
PKI |
Public Key Infrastructure |
公钥基础设施 |
CSR |
Certificate Signing Request |
证书签名请求 |
CSM |
Crypto Service Manager |
加密服务管理器 |
CRL |
Certificate Revocation List |
证书吊销列表 |
CA |
Certificate Authority |
证书认证 |
OID |
Object Identifier |
一个字节长度的数组用于识别一个或者一组证书元素.(An array of byte length is used for identifying one or a set of certificate elements) |
简介 Introduction¶
在一个加密功能中，密钥和证书的功能占比重很大。首先，密钥是一种参数，它是在明文转换为密文或将密文转换为明文的算法中输入的参数。许多加密算法需要使用到密钥，因此，就需要 keyM 模块来管理密钥，而 keyM 对于密钥的管理主要体现在对密钥的更新和生成密钥方面。而证书对网络用户在网络交流中的信息和数据等以加密或解密的形式保证了信息和数据的完整性和安全性。KeyM 模块可以实现证书的链的配置保存与验证，这使得网络中的信息和数据的安全性更高。
The functions of keys and certificates account for a large proportion in encryption function. Firstly, key is a kind of parameter that is input into algorithm converting plaintext to ciphertext or vice versa. Key is required in many encryption algorithms; therefore, a keyM module is required to manage keys. The management of keyM for key is mainly reflected in key updating and generating. Certificate can ensure the integrity and security of information and data exchanged by network users by either encryption or decryption. The KeyM module can save and verify the configuration of certificate chains, which enhances the security of information and data in the network.
功能描述 Functional Description¶
特性 Features¶
1.KeyM功能介绍
1.Introduction to KeyM function
Key Management 分为两部分：秘钥子模块和证书子模块
Key Management includes two parts: Key submodule and certificate submodule
2.Key子模块
2.Key submodule
秘钥子模块可以根据配置的需求，利用 HSM 的功能派生出新的秘钥，可以通过会话模式更新秘钥及秘钥元素，当会话开启后，可以对秘钥进行更新，结束会话后，更新的秘钥将被置成可用状态。
By leveraging the functions of HSM, the key submodule can derive new keys according to the configuration requirements. The keys and key elements can be updated through session mode. When a session is opened, the keys can be updated. The updated keys will be available upon the ending of session.
3.证书子模块
3.Certificate submodule
证书子模块允许配置证书链，在配置中将证书的属性和关系设置好，上层应用通过 API 将证书数据传给 keyM 后，证书子模块将根据配置内容及 HSM 按照标准结构解析的证书存储进配置的位置（NVM、CSM 或 RAM）。在存储之前将对证书进行解析与验证操作，以确定该证书的可靠性
The certificate submodule supports the configuration of certificate chains by setting the attributes and relationships of certificates in the configuration. After the upper layer application transfers the certificate data to keyM via API, the certificate submodule will be stored in the position configured (NVM, CSM, or RAM) based on the configuration content and the certificate parsed by HSM according to the standard structure. Before storage, the certificate will be parsed and validated to confirm its reliability
偏差 Deviation¶
1.证书链
1.Certificate chain
目前未实现证书链的验证功能
The verification function of certificate chain has not been implemented yet
扩展 Extension¶
None
集成 Integration¶
文件列表 File List¶
KeyM组件文件组织结构描述. (Descriptions of KeyM component file organization structure)¶
如图 KeyM组件文件组织结构描述. (Descriptions of KeyM component file organization structure) 所示，KeyM模块的文件引用关系如下：
As shown in the figure KeyM组件文件组织结构描述. (Descriptions of KeyM component file organization structure) , the file reference relationship of the KeyM module is shown as follows:
静态文件 Static Files¶
None
动态文件 Dynamic Files¶
文件(File) |
描述(Description) |
|---|---|
KeyM.c |
KeyM 模块源文件，包含了 API 函数的实现。(The KeyM module source file, which contains the realization of API functions.) |
KeyM.h |
KeyM 模块头文件，包含了 API 函数的扩展声明并定义了配置的数据结构。(The KeyM module header file contains extension declarations for API functions and defines the structure of configured data.) |
KeyM_Cfg.h |
定义 KeyM 模块预编译时用到的配置参数。(Defines the configuration parameters for pre-compiling KeyM modules.) |
KeyM_Cfg.c |
KeyM 模块配置生成文件。(Files generated by KeyM module configuration.) |
SchM_KeyM.h |
声明 KeyM 模块需要循环调用的 API。(Declares the API that the KeyM module needs to call in a loop.) |
Rte_KeyM_Type.h |
定义其它模块可能使用的 KeyM 模块的数据结构。(Defines the data structure of KeyM modules that other modules may use.) |
KeyM_Externals.c |
KeyM 模块源文件，包含 KeyM 模块外部实现的接口。(The KeyM module source file, which contains the interfaces realized externally for the KeyM module.) |
KeyM_Externals.h |
KeyM 模块头文件，定义 KeyM 模块外部实现的接口。(-The KeyM module header file, which defines the interfaces realized externally for the KeyM module.) |
KeyM_Internal.h |
KeyM 内部变量 (KeyM internal variables) |
KeyM_MemMap.h |
KeyM 模块的内存映射 (Memory mapping of KeyM module) |
KeyM_Type.h |
KeyM 的配置类型结构 (Configuration type structure of KeyM) |
错误处理 Error Handling¶
开发错误 Development Errors¶
Error code |
Value[hex] |
Description |
|---|---|---|
KEYM_E_PARAM_POINTER |
0x01 |
API service called with invalid parameter (Null Pointer) |
KEYM_E_SMALL_BUFFER |
0x02 |
Buffer is too small for operation |
KEYM_E_UNINIT |
0x03 |
API called before module has been initialized |
KEYM_E_INIT_FAILED |
0x04 |
KeyM module initialization failed |
KEYM_E_CONFIG_FAILURE |
0x05 |
KeyM configuration failure |
产品错误 Product Errors¶
None
运行时错误 Runtime Errors¶
None
应用程序集成 Application Integration¶
1.依赖模块
1.Dependency module
配置KeyM模块需要保证工程中存在STBM提供时间基准，CSM模块即下层模块提供加密服务
The configuration of KeyM module requires time reference provided by STBM in the project as well as encryption services provided by the CSM module, which is the lower level module
类型定义 Type Definitions¶
Type Name |
Type |
Description |
|---|---|---|
KeyM_Asn1DesType |
struct KeyM_Asn1Type |
Structure to hold ASN.1 data. |
KeyM_CryptoKeyIdType |
uint16 |
Type definition for a crypto key identifier. |
KeyM_CertDataPointerType |
uint8 * |
Type definition for a certificate data pointer. |
KeyM_KH_UpdateOperationType |
enum |
Enumeration of key handler update operations. |
提供的服务 Services¶
KeyM_Init¶
void KeyM_Init(const KeyM_ConfigType *ConfigPtr)
Initializes the Key Management module.
- Sync/Async
TRUE
- Reentrancy
Not reentrant.
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
ConfigPtr |
Pointer to the Key Management configuration structure. |
- Return type
void
KeyM_Deinit¶
void KeyM_Deinit(void)
Deinitializes the Key Management module.
- Sync/Async
TRUE
- Reentrancy
Not reentrant.
- Return type
void
KeyM_GetVersionInfo¶
void KeyM_GetVersionInfo(Std_VersionInfoType *VersionInfo)
Retrieves version information for the Key Management module.
- Sync/Async
TRUE
- Reentrancy
Not reentrant.
Parameters
Dir |
Name |
Description |
|---|---|---|
[out] |
VersionInfo |
Pointer to the structure to store version information. |
- Return type
void
KeyM_Start¶
Std_ReturnType KeyM_Start(KeyM_StartType StartType, const uint8 *RequestData, uint16 RequestDataLength, uint8 *ResponseData, uint16 *ResponseDataLength)
Starts the Key Management module.
- Sync/Async
TRUE
- Reentrancy
Not reentrant.
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
StartType |
Type of start operation. |
[in] |
RequestData |
Pointer to the request data. |
[in] |
RequestDataLength |
Length of the request data. |
[out] |
ResponseData |
Pointer to the response data. |
[out] |
ResponseDataLength |
Pointer to the length of the response data. |
- Return type
Std_ReturnType
Return values
Name |
Description |
|---|---|
E_OK |
The start operation was successful. |
E_NOT_OK |
The start operation failed. |
KeyM_Finalize¶
Std_ReturnType KeyM_Finalize(const uint8 *RequestDataPtr, uint16 RequestDataLength, uint8 *ResponseDataPtr, uint16 ResponseMaxDataLength)
Finalizes the Key Management module.
- Sync/Async
TRUE
- Reentrancy
Not reentrant.
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
RequestDataPtr |
Pointer to the request data. |
[in] |
RequestDataLength |
Length of the request data. |
[out] |
ResponseDataPtr |
Pointer to the response data. |
[in] |
ResponseMaxDataLength |
Maximum length of the response data. |
- Return type
Std_ReturnType
Return values
Name |
Description |
|---|---|
E_OK |
The finalize operation was successful. |
E_NOT_OK |
The finalize operation failed. |
KeyM_Prepare¶
Std_ReturnType KeyM_Prepare(const uint8 *RequestData, uint16 RequestDataLength, uint8 *ResponseData, uint16 *ResponseDataLength)
Prepares the Key Management module for a cryptographic operation.
- Sync/Async
TRUE
- Reentrancy
Not reentrant.
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
RequestData |
Pointer to the request data. |
[in] |
RequestDataLength |
Length of the request data. |
[out] |
ResponseData |
Pointer to the response data. |
[inout] |
ResponseDataLength |
Pointer to the length of the response data. |
- Return type
Std_ReturnType
Return values
Name |
Description |
|---|---|
E_OK |
The preparation was successful. |
E_NOT_OK |
The preparation failed. |
KeyM_Update¶
Std_ReturnType KeyM_Update(const uint8 *KeyNamePtr, uint16 KeyNameLength, const uint8 *RequestDataPtr, uint16 RequestDataLength, uint8 *ResultDataPtr, uint16 ResultDataMaxLength)
Updates a key in the Key Management module.
- Sync/Async
TRUE
- Reentrancy
Not reentrant.
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
KeyNamePtr |
Pointer to the key name. |
[in] |
KeyNameLength |
Length of the key name. |
[in] |
RequestDataPtr |
Pointer to the request data. |
[in] |
RequestDataLength |
Length of the request data. |
[out] |
ResultDataPtr |
Pointer to the result data. |
[in] |
ResultDataMaxLength |
Maximum length of the result data. |
- Return type
Std_ReturnType
Return values
Name |
Description |
|---|---|
E_OK |
The update operation was successful. |
E_NOT_OK |
The update operation failed. |
KeyM_Verify¶
Std_ReturnType KeyM_Verify(const uint8 *KeyNamePtr, uint16 KeyNameLength, const uint8 *RequestData, uint16 RequestDataLength, uint8 *ResponseData, uint16 *ResponseDataLength)
Verifies a key in the Key Management module.
- Sync/Async
TRUE
- Reentrancy
Not reentrant.
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
KeyNamePtr |
Pointer to the key name. |
[in] |
KeyNameLength |
Length of the key name. |
[in] |
RequestData |
Pointer to the request data. |
[in] |
RequestDataLength |
Length of the request data. |
[out] |
ResponseData |
Pointer to the response data. |
[inout] |
ResponseDataLength |
Pointer to the length of the response data. |
- Return type
Std_ReturnType
Return values
Name |
Description |
|---|---|
E_OK |
The verify operation was successful. |
E_NOT_OK |
The verify operation failed. |
KEYM_E_PENDING |
The verify operation is pending. |
KeyM_ServiceCertificate¶
Std_ReturnType KeyM_ServiceCertificate(KeyM_ServiceCertificateType Service, const uint8 *CertNamePtr, uint32 CertNameLength, const uint8 *RequestData, uint32 RequestDataLength, uint8 *ResponseData, uint32 *ResponseDataLength)
Performs a certificate service operation in the Key Management module.
- Sync/Async
TRUE
- Reentrancy
Not reentrant.
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
Service |
Type of certificate service operation. |
[in] |
CertNamePtr |
Pointer to the certificate name. |
[in] |
CertNameLength |
Length of the certificate name. |
[in] |
RequestData |
Pointer to the request data. |
[in] |
RequestDataLength |
Length of the request data. |
[out] |
ResponseData |
Pointer to the response data. |
[in] |
ResponseDataLength |
Length of the response data. |
- Return type
Std_ReturnType
Return values
Name |
Description |
|---|---|
E_OK |
The certificate service operation was successful. |
E_NOT_OK |
The certificate service operation failed. |
KeyM_ServiceCertificateByCertId¶
Std_ReturnType KeyM_ServiceCertificateByCertId(KeyM_CertificateIdType CertId, KeyM_ServiceCertificateType Service, const uint8 *RequestData, uint32 RequestDataLength, uint8 *ResponseData, uint32 *ResponseDataLength)
Performs a certificate service operation in the Key Management module.
- Sync/Async
TRUE
- Reentrancy
Not reentrant.
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
CertId |
the certificate ID. |
[in] |
Service |
Type of certificate service operation. |
[in] |
RequestData |
Pointer to the request data. |
[in] |
RequestDataLength |
Length of the request data. |
[out] |
ResponseData |
Pointer to the response data. |
[in] |
ResponseDataLength |
Length of the response data. |
- Return type
Std_ReturnType
Return values
Name |
Description |
|---|---|
E_OK |
The certificate service operation was successful. |
E_NOT_OK |
The certificate service operation failed. |
KeyM_SetCertificate¶
Std_ReturnType KeyM_SetCertificate(KeyM_CertificateIdType CertId, const KeyM_CertDataType *CertificateDataPtr)
Sets a certificate in the Key Management module.
- Sync/Async
TRUE
- Reentrancy
Not reentrant.
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
CertId |
ID of the certificate to set. |
[in] |
CertificateDataPtr |
Pointer to the certificate data. |
- Return type
Std_ReturnType
Return values
Name |
Description |
|---|---|
E_OK |
The certificate was set successfully. |
E_NOT_OK |
The certificate could not be set. |
KeyM_GetCertificate¶
Std_ReturnType KeyM_GetCertificate(KeyM_CertificateIdType CertId, KeyM_CertDataType *CertificateDataPtr)
Retrieves a certificate from the Key Management module.
- Sync/Async
TRUE
- Reentrancy
Not reentrant.
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
CertId |
ID of the certificate to retrieve. |
[out] |
CertificateDataPtr |
Pointer to the buffer to store the certificate data. |
- Return type
Std_ReturnType
Return values
Name |
Description |
|---|---|
E_OK |
The certificate was retrieved successfully. |
E_NOT_OK |
The certificate could not be retrieved. |
KEYM_E_KEY_CERT_SIZE_MISMATCH |
The provided buffer is too small to hold the certificate. |
KEYM_E_KEY_CERT_EMPTY |
The certificate is empty. |
KeyM_VerifyCertificates¶
Std_ReturnType KeyM_VerifyCertificates(KeyM_CertificateIdType CertId, KeyM_CertificateIdType CertUpperId)
Verifies a certificate chain in the Key Management module.
- Sync/Async
TRUE
- Reentrancy
Not reentrant.
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
CertId |
ID of the certificate to verify. |
[in] |
CertUpperId |
ID of the upper-level certificate in the chain. |
- Return type
Std_ReturnType
Return values
Name |
Description |
|---|---|
E_OK |
The certificate chain was verified successfully. |
E_NOT_OK |
The certificate chain could not be verified. |
KEYM_E_PARAMETER_MISMATCH |
The certificate IDs are invalid. |
KEYM_E_CERT_INVALID_CHAIN_OF_TRUST |
The certificate chain is invalid. |
KeyM_VerifyCertificate¶
Std_ReturnType KeyM_VerifyCertificate(KeyM_CertificateIdType CertId)
Verifies a certificate in the Key Management module.
- Sync/Async
TRUE
- Reentrancy
Not reentrant.
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
CertId |
ID of the certificate to verify. |
- Return type
Std_ReturnType
Return values
Name |
Description |
|---|---|
E_OK |
The certificate was verified successfully. |
E_NOT_OK |
The certificate could not be verified. |
KEYM_E_PARAMETER_MISMATCH |
The certificate ID is invalid. |
KEYM_E_CERT_INVALID_CHAIN_OF_TRUST |
The certificate chain is invalid. |
KeyM_VerifyCertificateChain¶
Std_ReturnType KeyM_VerifyCertificateChain(KeyM_CertificateIdType CertId, const KeyM_CertDataType certChainData[], uint8 NumberOfCertificates)
Verifies a certificate chain in the Key Management module.
- Sync/Async
TRUE
- Reentrancy
Not reentrant.
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
CertId |
ID of the starting certificate in the chain. |
[in] |
certChainData |
Array of certificate data for the chain. |
[in] |
NumberOfCertificates |
Number of certificates in the chain. |
- Return type
Std_ReturnType
Return values
Name |
Description |
|---|---|
E_OK |
The certificate chain was verified successfully. |
E_NOT_OK |
The certificate chain could not be verified. |
KeyM_CertElementGet¶
Std_ReturnType KeyM_CertElementGet(KeyM_CertificateIdType CertId, KeyM_CertElementIdType CertElementId, uint8 *CertElementData, uint32 *CertElementDataLength)
Retrieves a certificate element from the Key Management module.
- Sync/Async
TRUE
- Reentrancy
Not reentrant.
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
CertId |
ID of the certificate. |
[in] |
CertElementId |
ID of the certificate element to retrieve. |
[out] |
CertElementData |
Pointer to the buffer to store the certificate element data. |
[inout] |
CertElementDataLength |
Pointer to the length of the certificate element data. |
- Return type
Std_ReturnType
Return values
Name |
Description |
|---|---|
E_OK |
The certificate element was retrieved successfully. |
E_NOT_OK |
The certificate element could not be retrieved. |
KeyM_CertificateElementGetByIndex¶
Std_ReturnType KeyM_CertificateElementGetByIndex(KeyM_CertificateIdType CertId, KeyM_CertElementIdType CertElementId, uint32 Index, uint8 *CertElementDataPtr, uint32 *CertElementDataLengthPtr)
Retrieves a certificate element by index from the Key Management module.
- Sync/Async
TRUE
- Reentrancy
Not reentrant.
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
CertId |
ID of the certificate. |
[in] |
CertElementId |
ID of the certificate element to retrieve. |
[in] |
Index |
Index of the certificate element to retrieve. |
[out] |
CertElementDataPtr |
Pointer to the buffer to store the certificate element data. |
[inout] |
CertElementDataLengthPtr |
Pointer to the length of the certificate element data. |
- Return type
Std_ReturnType
Return values
Name |
Description |
|---|---|
E_OK |
The certificate element was retrieved successfully. |
E_NOT_OK |
The certificate element could not be retrieved. |
KeyM_CertificateElementGetCount¶
Std_ReturnType KeyM_CertificateElementGetCount(KeyM_CertificateIdType CertId, KeyM_CertElementIdType CertElementId, uint16 *CountPtr)
Retrieves the count of a specific certificate element in the Key Management module.
- Sync/Async
TRUE
- Reentrancy
Not reentrant.
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
CertId |
ID of the certificate. |
[in] |
CertElementId |
ID of the certificate element. |
[out] |
CountPtr |
Pointer to store the count of the certificate element. |
- Return type
Std_ReturnType
Return values
Name |
Description |
|---|---|
E_OK |
The count was retrieved successfully. |
E_NOT_OK |
The count could not be retrieved. |
KeyM_CertElementGetFirst¶
Std_ReturnType KeyM_CertElementGetFirst(KeyM_CertificateIdType CertId, KeyM_CertElementIdType CertElementId, KeyM_CertElementIteratorType *CertElementIterator, uint8 *CertElementData, uint32 *CertElementDataLength)
Retrieves the first occurrence of a certificate element and initializes an iterator.
- Sync/Async
TRUE
- Reentrancy
Not reentrant.
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
CertId |
ID of the certificate. |
[in] |
CertElementId |
ID of the certificate element to retrieve. |
[out] |
CertElementIterator |
Pointer to the iterator to be initialized. |
[out] |
CertElementData |
Pointer to the buffer to store the certificate element data. |
[inout] |
CertElementDataLength |
Pointer to the length of the certificate element data. |
- Return type
Std_ReturnType
Return values
Name |
Description |
|---|---|
E_OK |
The first certificate element was retrieved successfully and the iterator was initialized. |
E_NOT_OK |
The first certificate element could not be retrieved or the iterator could not be initialized. |
KeyM_CertElementGetNext¶
Std_ReturnType KeyM_CertElementGetNext(KeyM_CertElementIteratorType *CertElementIterator, uint8 *CertElementData, uint32 *CertElementDataLength)
Retrieves the next occurrence of a certificate element using an iterator.
- Sync/Async
TRUE
- Reentrancy
Not reentrant.
Parameters
Dir |
Name |
Description |
|---|---|---|
[inout] |
CertElementIterator |
Pointer to the iterator initialized by KeyM_CertElementGetFirst. |
[out] |
CertElementData |
Pointer to the buffer to store the certificate element data. |
[inout] |
CertElementDataLength |
Pointer to the length of the certificate element data. |
- Return type
Std_ReturnType
Return values
Name |
Description |
|---|---|
E_OK |
The next certificate element was retrieved successfully. |
E_NOT_OK |
The next certificate element could not be retrieved. |
KeyM_CertGetStatus¶
Std_ReturnType KeyM_CertGetStatus(KeyM_CertificateIdType CertId, KeyM_CertificateStatusType *Status)
Retrieves the status of a certificate in the Key Management module.
- Sync/Async
TRUE
- Reentrancy
Not reentrant.
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
CertId |
ID of the certificate. |
[out] |
Status |
Pointer to store the status of the certificate. |
- Return type
Std_ReturnType
Return values
Name |
Description |
|---|---|
E_OK |
The status was retrieved successfully. |
E_NOT_OK |
The status could not be retrieved. |
类型定义 Type Definitions¶
Type Name |
Type |
Description |
|---|---|---|
KeyM_CertPCfgType |
struct KeyM_CertType |
Structure to hold certificate configuration data. |
KeyM_CryptoCsmVerifyJobType |
enum |
Enumeration of crypto CSM verify job types. |
KeyM_CryptoKeyGenerationType |
enum |
Enumeration of crypto key generation types. |
KeyM_StorageType |
enum |
Enumeration of storage types for keys. |
KeyM_CertAlgorithmType |
enum |
Enumeration of certificate algorithms. |
KeyM_CertFormatType |
enum |
Enumeration of certificate formats. |
KeyM_CertEleStructType |
enum |
Enumeration of certificate element structures. |
提供的服务 Services¶
KEYM_DET_REPORT¶
static void KEYM_DET_REPORT(uint8 ApiId, uint8 ErrorId)
Reports an error to the DET (Diagnostic Error Trap) module.
- Sync/Async
TRUE
- Reentrancy
Reentrant
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
ApiId |
API identifier of the function that detected the error. |
[in] |
ErrorId |
Error identifier specifying the type of error. |
- Return type
void
CONST¶
CONST(KeyM_NvmBlockPCfgType, KEYM_CONST) KeyM_NvmBlockPCfg[KEYM_NVM_BLOCK_NUM]
Sync/Async
Reentrancy
Return type
CONST¶
CONST(KeyM_CertPCfgType, KEYM_CONST) KeyM_CertPCfg[KEYM_CERT_NUM]
Sync/Async
Reentrancy
Return type
KeyM_CopyData¶
void KeyM_CopyData(void *dest, const void *src, uint32 size)
Copies data from the source buffer to the destination buffer.This function performs a byte-wise copy of the specified number of bytes from the source buffer to the destination buffer.
- Sync/Async
TRUE
- Reentrancy
Reentrant
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
dest |
Pointer to the destination buffer. |
[in] |
src |
Pointer to the source buffer. |
[in] |
size |
Number of bytes to copy. |
- Return type
void
KeyM_strcmp¶
Std_ReturnType KeyM_strcmp(const uint8 *str1, const uint8 *str2, uint16 size)
Compares two strings of a specified length.This function compares the specified number of bytes from two strings.If the strings are identical up to the specified length, it returns E_OK.Otherwise, it returns E_NOT_OK.
- Sync/Async
TRUE
- Reentrancy
Reentrant
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
str1 |
Pointer to the first string. |
[in] |
str2 |
Pointer to the second string. |
[in] |
size |
Number of bytes to compare. |
- Return type
Std_ReturnType
Return values
Name |
Description |
|---|---|
E_OK:The |
strings are identical up to the specified length. |
E_NOT_OK:The |
strings are not identical up to the specified length. |
KeyM_HandleUpdate¶
Std_ReturnType KeyM_HandleUpdate(const uint8 *ResultDataPtr, uint16 ResultDataLength, uint16 KeyIdx, boolean sheKey)
Handles the update of a cryptographic key.This function updates a cryptographic key based on the provided result data.It can store or derive the key according to the configuration.If the key is stored in CSM or RAM, it updates the key directly.If the key is stored in NVM, it writes the key to the specified NVM block.If the key is derived, it performs key derivation using the provided result data and key generation information.
- Sync/Async
TRUE
- Reentrancy
Reentrant
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
ResultDataPtr |
Pointer to the result data used for key update or derivation. |
[in] |
ResultDataLength |
Length of the result data. |
[in] |
KeyIdx |
Index of the cryptographic key configuration. |
[in] |
sheKey |
Flag indicating whether the key is an SHE key. |
- Return type
Std_ReturnType
Return values
Name |
Description |
|---|---|
E_OK:The |
key update or derivation was successful. |
E_NOT_OK:The |
key update or derivation failed. |
KEYM_E_PARAMETER_MISMATCH:Invalid |
parameters were provided. |
KeyM_GetSHEKey_M4M5¶
Std_ReturnType KeyM_GetSHEKey_M4M5(uint32 keyId, uint8 *ResponseDataPtr, uint16 *ResponseMaxDataLength)
Retrieves the SHE key for M4 and M5 operations.This function retrieves the key element for the specified key ID, which is used for generating M4 and M5 data in the key update process.M4 is generated by encrypting the CID with K3, and M5 is generated by computing the CMAC of M4 using K4, where K4 is derived from the new key.
- Sync/Async
TRUE
- Reentrancy
Reentrant
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
keyId |
ID of the key to retrieve. |
[out] |
ResponseDataPtr |
Pointer to the buffer where the key element will be stored. |
[inout] |
ResponseMaxDataLength |
Pointer to the maximum length of the response data buffer. On return, it contains the actual length of the key element. |
- Return type
Std_ReturnType
Return values
Name |
Description |
|---|---|
E_OK:The |
key element was successfully retrieved. |
E_NOT_OK:The |
key element retrieval failed. |
KeyM_HandleParseCert¶
Std_ReturnType KeyM_HandleParseCert(KeyM_CertificateIdType CertId, const uint8 *certDataPtr, uint32 certDataLength)
Parses a certificate and extracts relevant information.This function processes a certificate according to the X.509 standard.It extracts the TBS (To Be Signed) certificate, version, serial number, signature algorithm, issuer and subject names, validity period, subject public key info, and extensions (if present).It also validates the structure of the certificate and stores the parsed data.
- Sync/Async
TRUE
- Reentrancy
Reentrant
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
CertId |
ID of the certificate to parse. |
[in] |
certDataPtr |
Pointer to the certificate data. |
[in] |
certDataLength |
Length of the certificate data. |
- Return type
Std_ReturnType
Return values
Name |
Description |
|---|---|
E_OK:The |
certificate was successfully parsed. |
E_NOT_OK:The |
certificate parsing failed. |
KEYM_E_KEY_CERT_INVALID:The |
certificate is invalid. |
KEYM_E_CERTIFICATE_INVALID_FORMAT:The |
certificate has an invalid format. |
KeyM_HandleCsmKeyStorage¶
void KeyM_HandleCsmKeyStorage(uint32 keyId, uint16 certId, boolean keySet)
Handles the storage of certificate elements in the CSM.This function processes each certificate element defined in the certificate configuration and either sets or gets the corresponding key element in the CSM.The operation (set or get) is determined by the
- Sync/Async
TRUE
- Reentrancy
Reentrant
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
keyId |
ID of the key in the CSM where the certificate elements will be stored or retrieved. |
[in] |
certId |
ID of the certificate configuration. |
[in] |
keySet |
Flag indicating whether to set (TRUE) or get (FALSE) the key elements. |
- Return type
void
KeyM_HandleCertcVerify¶
Std_ReturnType KeyM_HandleCertcVerify(const KeyM_CertPCfgType *certCfgPtr, const KeyM_CertPCfgType *certUpperHierRef)
Verifies a certificate against a higher-level certificate in the chain.This function performs a series of checks to validate a certificate
- Sync/Async
TRUE
- Reentrancy
Reentrant
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
certCfgPtr |
Pointer to the certificate configuration of the certificate to verify. |
[in] |
certUpperHierRef |
Pointer to the certificate configuration of the higher-level certificate. |
- Return type
Std_ReturnType
Return values
Name |
Description |
|---|---|
E_OK:The |
certificate is valid. |
E_NOT_OK:The |
certificate verification failed. |
KEYM_E_CERT_INVALID_CHAIN_OF_TRUST:The |
certificate chain of trust is invalid. |
KEYM_E_CERTIFICATE_VALIDITY_PERIOD_FAIL:The |
certificate is outside its validity period. |
KEYM_E_CERTIFICATE_INVALID_CONTENT:The |
certificate content is invalid. |
KEYM_E_CERTIFICATE_SIGNATURE_FAIL:The |
certificate signature is invalid. |
KeyM_CertSetStatus¶
Std_ReturnType KeyM_CertSetStatus(KeyM_CertificateIdType CertId, KeyM_CertificateStatusType Status)
Sets the status of a certificate.This function updates the status of a certificate in the certificate status array.It checks if the provided certificate ID is valid before updating the status.
- Sync/Async
TRUE
- Reentrancy
Reentrant
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
CertId |
ID of the certificate to update the status for. |
[in] |
Status |
New status of the certificate. |
- Return type
Std_ReturnType
Return values
Name |
Description |
|---|---|
E_OK:The |
status was successfully updated. |
KEYM_E_PARAMETER_MISMATCH:The |
provided certificate ID is invalid. |
KeyM_CertStoreNvmHandle¶
void KeyM_CertStoreNvmHandle(void)
Handles the storage of certificates in NVM with delayed write.This function iterates through the NVM blocks and checks if any block has a delayed write pending.If a block has a delayed write pending, it decrements the delay counter.When the delay counter reaches zero, it writes the certificate data to the NVM block and resets the delay.This ensures that the certificate data is written to NVM after a specified delay, which can be useful for optimizing write operations and reducing wear on the NVM.
- Sync/Async
TRUE
- Reentrancy
Reentrant
- Return type
void
配置 Configuration¶
KeyMGeneral通用配置 General Configuration of KeyMGeneral¶
提供一些基本功能的开关，如证书功能，秘钥功能，和handler函数功能，第一步应该按项目需要配置这里。
Provide some basic functions, such as certificate function, key function and handler function. In the first step, make configuration based on project needs.
fig_KeyM_General¶
KeyMCertificate配置 Configuration of KeyMCertificate¶
提供对证书的基本配置，可以配置证书的长度和字段，以及对证书的一些验证操作所使用的算法和秘钥类型。
Provide some basic configuration for certificates, including certificate length and fields, as well as the algorithms and key types used for some verification operations on the certificate.
fig_KeyMCertificate¶
KeyMCertificateElement配置 Configuration of KeyMCertificateElement¶
对证书中的每个字段进行详细配置，确保是符合证书规范的。
Configure each field in the certificate in detail to ensure its compliance with the certificate specification.
fig_KeyMCertificateElement¶
KeyMCertificateElementRule配置 Configuration of KeyMCertificateElementRule¶
对于证书里面的元素可以配置一些规则，通常这些规则是用不上的可以不配置，可以根据实际需要进行设计。
Configure some rules for the elements in the certificate. In general, these rules are not necessary and can be designed based on actual needs.
fig_KeyMCertificateElementRule¶
KeyMCertificateElementCondition配置 Configuration of KeyMCertificateElementCondition¶
对于证书里面的元素可以配置一些规则，通常这些规则是用不上的可以不配置，可以根据实际需要进行设计。
Configure some rules for the elements in the certificate. In general, these rules are not necessary and can be designed based on actual needs.
fig_KeyMCertificateElementCondition¶
KeyMCertificateElementConditionArrayElement配置 Configuration of KeyMCertificateElementConditionArrayElement¶
对于证书里面的元素可以配置一些规则，通常这些规则是用不上的可以不配置，可以根据实际需要进行设计。
Configure some rules for the elements in the certificate. In general, these rules are not necessary and can be designed based on actual needs.
fig_KeyMCertificateElementConditionArrayElement¶
KeyMCertificateElementConditionArray配置 Configuration of KeyMCertificateElementConditionArray¶
对于证书里面的元素可以配置一些规则，通常这些规则是用不上的可以不配置，可以根据实际需要进行设计。
Configure some rules for the elements in the certificate. In general, these rules are not necessary and can be designed based on actual needs.
fig_KeyMCertificateElementConditionArray¶
KeyMCertificateElementConditionPrimitive配置 Configuration of KeyMCertificateElementConditionPrimitive¶
对于证书里面的元素可以配置一些规则，通常这些规则是用不上的可以不配置，可以根据实际需要进行设计。
Configure some rules for the elements in the certificate. In general, these rules are not necessary and can be designed based on actual needs.
fig_KeyMCertificateElementConditionPrimitive¶
KeyMCertificateElementConditionSenderReceiver配置 Configuration of KeyMCertificateElementConditionSenderReceiver¶
对于证书里面的元素可以配置一些规则，通常这些规则是用不上的可以不配置，可以根据实际需要进行设计。
Configure some rules for the elements in the certificate. In general, these rules are not necessary and can be designed based on actual needs.
fig_KeyMCertificateElementConditionSenderReceiver¶
KeyMCryptoKey配置 Configuration of KeyMCryptoKey¶
配置需要使用的秘钥的配置，配置存储类型或者关联下层的配置等。
Configuration requiring key, type of configuration storage or configuration of linked lower level, etc.
fig_KeyMCryptoKey¶
KeyMNvmBlock配置 Configuration of KeyMNvmBlock¶
证书可以保存在NVM中，也可以保存在RAM中。但是下次上电前会丢失，可以根据配置决定是否需要NVM支持。
The certificate can be saved in NVM or RAM. However, it will be lost before the next power-on. Decide whether NVM support is needed based on the configuration.
fig_KeyMNvmBlock¶