MICROSAR Classic KeyM

Technical Reference
Key Manager
Version 4.2.0

Authors visivg, vismwe

Status Released
 Technical Reference MICROSAR Classic KeyM

Document Information
History

Author Date Version Remarks

visivg; vismwe 2019-10-22 1.00.00 Initial creation of Technical Reference

visivg 2020-03-03 1.04.00 Updated supported features 2.1

Reworked chapter 2.3
Added chapter 2.4
Added chapter 2.6.7
Added chapter 2.6.8
Added chapter 2.6.9
Reworked chapter 3.3
visivg 2020-05-08 2.00.00 Updated supported features 2.1
Reworked chapter 2.4
Added chapter 2.6.10
Reworked chapter 2.7
Reworked chapter 4.1
Reworked chapter 4.2
visivg 2020-06-04 2.01.00 Updated supported features 2.1
Reworked chapter 2.6.10
Updated chapter 2.7
Reworked chapter 4.1
Reworked chapter 4.2.8
visivg 2020-06-08 2.02.00 Reworked chapter 2.7.1
Added chapter 3.3.3
Reworked chapter 3.3.6
visivg 2020-09-03 2.03.00 Reworked chapter 2.1.2
Added chapter 2.6.11
Added chapter 2.6.12
Added chapter 2.6.13
Updated chapter 2.7
Reworked chapter 4.1
Reworked chapter 4.2.8
Reworked chapter 6.2
visivg 2020-10-01 2.03.01 Reworked chapter 2.4
Added chapter 4.5.2.4
visivg 2020-10-16 3.00.00 Reworked chapter 4.2.8
Reworked chapter 3.3.4
Added chapter 2.6.14
Updated chapter 2.7
Reworked chapter 4.2.8
visivg 2020-11-24 3.01.00 Reworked chapter 4.2.8
Reworked chapter 2.6.1

© 2022 Vector Informatik GmbH Version 4.2.0 2

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

Reworked chapter 3.3.4

Added chapter 2.6.15
Added chapter 2.1.3.2
Added chapter 5.4
visivg 2021-05-19 3.02.00 Updated chapter 2.1.2
Added chapter 2.6.16
Updated chapter 2.7
Updated chapter 6.2
Updated chapter 1
viseag, visivg, vismhh 2021-09-21 4.00.00 Updated chapter 2.6.3.2
Updated chapter 2.6.9
Updated chapter 2.6.10
Updated chapter 2.6.11
Updated chapter 2.6.14
Updated chapter 2.7.1
Updated chapter 3.3
Updated chapter 3.3.2
Updated chapter 3.3.3
Updated chapter 3.3.4
Updated chapter 3.3.7
Updated chapter 4.1
Updated chapter 4.2.8.7
Updated chapter 4.2.8.10
Updated chapter 4.2.8.16
Updated chapter 4.3
Updated chapter 4.4.1
Added chapter 4.2.8.3
Added chapter 4.2.8.8
Added chapter 4.4.2
Added chapter 4.4.3
Added chapter 4.4.4
Added chapter 4.4.5
Added chapter 4.4.6
Added chapter 4.4.7
Added chapter 4.4.8
Added chapter 4.4.9
Added chapter 5.3
visivg 2021-12-09 4.01.00 Added chapter 2.6.17
Added chapter 4.5.1.3
Updated chapter 4.1
visivg 2022-02-16 4.02.00 Updated chapter 2.6.5
Added chapter 2.6.11.1
Added chapter 2.6.18
Updated chapter 2.7
Updated chapter 4.1

© 2022 Vector Informatik GmbH Version 4.2.0 3

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

Reference Documents

No. Source Title Version

[1] AUTOSAR AUTOSAR_SWS_KeyManager.pdf 4.4.0
[2] AUTOSAR AUTOSAR_SWS_DET.pdf 4.3.0
[3] AUTOSAR AUTOSAR_SWS_CryptoServiceManager.pdf 4.3.0
[4] AUTOSAR AUTOSAR_TR_BSWModuleList.pdf 4.4.0
[5] IETF Internet X.509 Public Key Infrastructure Certificate and -
RFC5280 Certificate Revocation List (CRL) Profile
[6] ITU-T X.690 ITU-T Recommendation X.690 (2002) | ISO/IEC 8825- Ed. 5
1:2002, Information technology - ASN.1 encoding rules: (08/2015)
Specification of Basic Encoding Rules (BER), Canonical
Encoding Rules (CER) and Distinguished Encoding Rules
(DER)
[7] IETF PKCS #10: Certification Request Syntax Specification -
RFC2986
[8] IETF X.509 Internet Public Key Infrastructure Online Certificate -
RFC6960 Status Protocol - OCSP
[9] IETF The Transport Layer Security (TLS) Multiple Certificate -
RFC6961 Status Request Extension
[10] BSI TR-03110 Advanced Security Mechanisms for Machine 2.21
Readable Travel Documents and eIDAS token

Caution
We have configured the programs in accordance with your specifications in the
questionnaire. Whereas the programs do support other configurations than the one
specified in your questionnaire, Vector´s release of the programs delivered to your
company is expressly restricted to the configuration you have specified in the
questionnaire.

© 2022 Vector Informatik GmbH Version 4.2.0 4

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

Contents

1 Introduction.......................................................................................................................... 11
1.1 Architecture Overview ............................................................................................... 12

2 Functional Description ........................................................................................................ 13

2.1 Features ................................................................................................................... 13
2.1.1 Deviations ................................................................................................. 13
2.1.1.1 Crypto Key Submodule ........................................................... 14
2.1.1.2 Key Generation for CSR ......................................................... 14
2.1.1.3 Configuration of element verification ....................................... 14
2.1.2 Additions/ Extensions ................................................................................ 14
2.1.3 Limitations ................................................................................................. 15
2.1.3.1 CSR ........................................................................................ 15
2.1.3.2 ECDSA certificates.................................................................. 15
2.2 Initialization ............................................................................................................... 15
2.3 States ....................................................................................................................... 15
2.4 Certificate Status....................................................................................................... 16
2.5 Main Functions ......................................................................................................... 17
2.6 Certificate Handling................................................................................................... 18
2.6.1 ASN.1 Parser ............................................................................................ 18
2.6.2 Element Verification .................................................................................. 18
2.6.3 Certificate Storage .................................................................................... 18
2.6.3.1 Permanent Storage in CSM .................................................... 18
2.6.3.2 Permanent Storage in NvM ..................................................... 19
2.6.4 Certificate Verification ............................................................................... 20
2.6.5 Retrieving Certificate Data ........................................................................ 21
2.6.6 Service and verification notification to application...................................... 21
2.6.7 Startup Handling ....................................................................................... 21
2.6.8 Certificate Update ..................................................................................... 21
2.6.9 Certificate Revocation List......................................................................... 22
2.6.10 Certificate Signing Request ....................................................................... 22
2.6.11 Dynamic issuer and certificate groups ....................................................... 24
2.6.11.1 Heterogeneous certificate groups ........................................... 27
2.6.12 Generic certificate revocation .................................................................... 27
2.6.13 Certificate structures ................................................................................. 27
2.6.14 Certificate hash ......................................................................................... 28
2.6.15 OCSP Stapling .......................................................................................... 28
2.6.16 Remote Handling ...................................................................................... 30
2.6.16.1 Dispatching Remote Service Requests ................................... 31
2.6.17 Callback Notifications ................................................................................ 32

© 2022 Vector Informatik GmbH Version 4.2.0 5

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

2.6.18 RAM Certificate Slot Sharing ..................................................................... 32

2.7 Error Handling ........................................................................................................... 33
2.7.1 Development Error Reporting .................................................................... 33

3 Integration ............................................................................................................................ 36
3.1 Embedded Implementation ....................................................................................... 36
3.2 Critical Sections ........................................................................................................ 36
3.3 Certificate Configuration............................................................................................ 37
3.3.1 Algorithm family ........................................................................................ 37
3.3.2 Verification Job and Key Dependencies .................................................... 37
3.3.3 Certificate Initial Value ............................................................................... 38
3.3.4 Element configuration ............................................................................... 39
3.3.5 Public key configuration ............................................................................ 40
3.3.6 Object Type ............................................................................................... 40
3.3.7 Configuration of CRLs ............................................................................... 41

4 API Description .................................................................................................................... 42

4.1 Type Definitions ........................................................................................................ 42
4.2 Services provided by KeyM ....................................................................................... 45
4.2.1 KeyM_InitMemory ..................................................................................... 45
4.2.2 KeyM_Init .................................................................................................. 46
4.2.3 KeyM_Deinit.............................................................................................. 46
4.2.4 KeyM_GetVersionInfo ............................................................................... 47
4.2.5 KeyM_MainFunction ................................................................................. 48
4.2.6 KeyM_MainBackgroundFunction ............................................................... 48
4.2.7 Key Sub-Module ....................................................................................... 49
4.2.7.1 KeyM_Prepare ........................................................................ 49
4.2.7.2 KeyM_Start ............................................................................. 49
4.2.7.3 KeyM_Update ......................................................................... 50
4.2.7.4 KeyM_Finalize ........................................................................ 51
4.2.7.5 KeyM_Verify............................................................................ 52
4.2.8 Certificate Sub-Module .............................................................................. 53
4.2.8.1 KeyM_ServiceCertificate ......................................................... 53
4.2.8.2 KeyM_SetCertificate ............................................................... 54
4.2.8.3 KeyM_SetCertificateWithConstPtr .......................................... 55
4.2.8.4 KeyM_GetCertificate ............................................................... 56
4.2.8.5 KeyM_VerifyCertificate............................................................ 56
4.2.8.6 KeyM_VerifyCertificates .......................................................... 57
4.2.8.7 KeyM_VerifyCertificateChain .................................................. 58
4.2.8.8 KeyM_VerifyCertificateChainWithConstPtr .............................. 59
4.2.8.9 KeyM_CertElementGet ........................................................... 60

© 2022 Vector Informatik GmbH Version 4.2.0 6

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

4.2.8.10 KeyM_CertElementGetFirst .................................................... 61

4.2.8.11 KeyM_CertElementGetNext .................................................... 62
4.2.8.12 KeyM_CertGetStatus .............................................................. 63
4.2.8.13 KeyM_Cert_SearchCert .......................................................... 63
4.2.8.14 KeyM_ CertificateElementGetByIndex .................................... 64
4.2.8.15 KeyM_CertificateElementGetCount ........................................ 65
4.2.8.16 KeyM_InitCSR ........................................................................ 66
4.2.8.17 KeyM_ServiceCertificateById .................................................. 66
4.2.8.18 KeyM_SetCertificateInGroup .................................................. 68
4.2.8.19 KeyM_GetGroupCertId ........................................................... 68
4.2.8.20 KeyM_VerifyGroup .................................................................. 69
4.2.8.21 KeyM_SetCRE........................................................................ 70
4.2.8.22 KeyM_CertStructureGet .......................................................... 70
4.2.8.23 KeyM_GetIssuerCertId ........................................................... 71
4.2.8.24 KeyM_GetCertHash ................................................................ 72
4.2.8.25 KeyM_CsrElementSet............................................................. 73
4.2.8.26 KeyM_DispatchRemoteJob..................................................... 73
4.2.8.27 KeyM_DispatchRemoteKeyElementSet .................................. 74
4.2.8.28 KeyM_DispatchRemoteKeyElementGet.................................. 75
4.2.8.29 KeyM_CertElementGetByStructureType ................................. 76
4.3 Services used by KeyM............................................................................................. 77
4.4 Callback Functions.................................................................................................... 77
4.4.1 KeyM_CallbackNotificationSignature......................................................... 77
4.4.2 KeyM_NvBlock_ReadFrom_KeyMCertificate_<NvBlock> ......................... 78
4.4.3 KeyM_NvBlock_WriteTo_KeyMCertificate_<NvBlock> .............................. 78
4.4.4 KeyM_NvBlock_Init_KeyMCertificate_<NvBlock> ..................................... 79
4.4.5 KeyM_NvBlock_Callback_KeyMCertificate_<NvBlock> ............................ 80
4.4.6 KeyM_NvBlock_ReadFrom_CRE.............................................................. 80
4.4.7 KeyM_NvBlock_WriteTo_CRE .................................................................. 81
4.4.8 KeyM_NvBlock_Init_CRE.......................................................................... 81
4.4.9 KeyM_NvBlock_Callback_CRE ................................................................. 82
4.5 Configurable Interfaces ............................................................................................. 83
4.5.1 Notifications .............................................................................................. 83
4.5.1.1 Appl_VerifyCallbackFunc ........................................................ 83
4.5.1.2 Appl_ServiceCallbackFunc ..................................................... 83
4.5.1.3 Appl_VerifyGroupCallbackFunc .............................................. 84
4.5.2 Callout Functions ...................................................................................... 85
4.5.2.1 Appl_CertificateElementVerificationCallout ............................. 85
4.5.2.2 Appl_SetKeyCallout ................................................................ 85
4.5.2.3 Appl_CertInitCallout ................................................................ 86
4.5.2.4 Appl_GetCurrentTimeCalloutFunc .......................................... 87

© 2022 Vector Informatik GmbH Version 4.2.0 7

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

5 Configuration ....................................................................................................................... 88
5.1 Configuration Variants ............................................................................................... 88
5.2 Certificate Elements .................................................................................................. 88
5.3 NvM Block Needs ..................................................................................................... 88
5.4 FAQ .......................................................................................................................... 89

6 Glossary and Abbreviations ............................................................................................... 91

6.1 Glossary ................................................................................................................... 91
6.2 Abbreviations ............................................................................................................ 91

7 Contact ................................................................................................................................. 92

© 2022 Vector Informatik GmbH Version 4.2.0 8

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

Illustrations
Figure 1-1 Interfaces to adjacent modules of the KeyM ...................................................... 12
Figure 2-1 Setting CA Certificate......................................................................................... 16
Figure 2-2 Certificate Status ............................................................................................... 17
Figure 2-3 Preset Issuer vs. Dynamic Issuer ....................................................................... 25
Figure 2-4 Group Certificates .............................................................................................. 26
Figure 3-1 Certificate Verification Job and Key References ................................................ 38

Tables
Table 2-1 Supported AUTOSAR standard conform features .............................................. 13
Table 2-2 Not supported AUTOSAR standard conform features ........................................ 14
Table 2-3 Features provided beyond the AUTOSAR standard ........................................... 14
Table 2-4 Failure State Transitions .................................................................................... 17
Table 2-5 Dispatching Remote Service Requests .............................................................. 32
Table 2-6 Service IDs ........................................................................................................ 35
Table 2-7 Errors reported to DET....................................................................................... 35
Table 3-1 Implementation files ........................................................................................... 36
Table 3-2 Supported universal ASN.1 tags ........................................................................ 41
Table 3-3 Supported CVC Tags ......................................................................................... 41
Table 4-1 KeyM_CertElementIteratorType ......................................................................... 42
Table 4-2 KeyM_CSRInfoType .......................................................................................... 43
Table 4-3 KeyM_ConstCertDataType ................................................................................ 44
Table 4-4 KeyM_ConstCertDataPointerType ..................................................................... 44
Table 4-5 KeyM_CertificateGroupIdType ........................................................................... 44
Table 4-6 KeyM_CertificateGroupStatusType .................................................................... 44
Table 4-7 KeyM_CertificateStructureType ......................................................................... 45
Table 4-8 KeyM_InitMemory .............................................................................................. 46
Table 4-9 KeyM_Init .......................................................................................................... 46
Table 4-10 KeyM_Deinit ...................................................................................................... 47
Table 4-11 KeyM_GetVersionInfo ........................................................................................ 47
Table 4-12 KeyM_MainFunction .......................................................................................... 48
Table 4-13 KeyM_MainBackgroundFunction ....................................................................... 48
Table 4-14 KeyM_Prepare................................................................................................... 49
Table 4-15 KeyM_Start ........................................................................................................ 50
Table 4-16 KeyM_Update .................................................................................................... 51
Table 4-17 KeyM_Finalize ................................................................................................... 52
Table 4-18 KeyM_Verify ...................................................................................................... 53
Table 4-19 KeyM_ServiceCertificate.................................................................................... 54
Table 4-20 KeyM_SetCertificate .......................................................................................... 55
Table 4-21 KeyM_SetCertificateWithConstPtr ..................................................................... 55
Table 4-22 KeyM_GetCertificate.......................................................................................... 56
Table 4-23 KeyM_VerifyCertificate ...................................................................................... 57
Table 4-24 KeyM_VerifyCertificates ..................................................................................... 58
Table 4-25 KeyM_VerifyCertificateChain ............................................................................. 59
Table 4-26 KeyM_VerifyCertificateChainWithConstPtr......................................................... 60
Table 4-27 KeyM_CertElementGet ...................................................................................... 61
Table 4-28 KeyM_CertElementGetFirst ............................................................................... 62
Table 4-29 KeyM_CertElementGetNext ............................................................................... 63
Table 4-30 KeyM_CertGetStatus ......................................................................................... 63
Table 4-31 KeyM_Cert_SearchCert ..................................................................................... 64
Table 4-32 KeyM_CertificateElementGetByIndex ................................................................ 65

© 2022 Vector Informatik GmbH Version 4.2.0 9

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

Table 4-33 KeyM_CertificateElementGetCount ................................................................... 65

Table 4-34 KeyM_InitCSR ................................................................................................... 66
Table 4-35 KeyM_ServiceCertificateById............................................................................. 67
Table 4-36 KeyM_SetCertificateInGroup ............................................................................. 68
Table 4-37 KeyM_GetGroupCertId ...................................................................................... 69
Table 4-38 KeyM_VerifyGroup............................................................................................. 70
Table 4-39 KeyM_SetCRE .................................................................................................. 70
Table 4-40 KeyM_CertStructureGet..................................................................................... 71
Table 4-41 KeyM_GetIssuerCertId ...................................................................................... 72
Table 4-42 KeyM_GetCertHash........................................................................................... 73
Table 4-43 KeyM_CsrElementSet ....................................................................................... 73
Table 4-44 KeyM_DispatchRemoteJob ............................................................................... 74
Table 4-45 KeyM_DispatchRemoteKeyElementSet ............................................................. 75
Table 4-46 KeyM_DispatchRemoteKeyElementGet ............................................................ 76
Table 4-47 KeyM_CertElementGetByStructureType ............................................................ 77
Table 4-48 Services used by the KeyM ............................................................................... 77
Table 4-49 KeyM_CallbackNotificationSignature ................................................................. 78
Table 4-50 KeyM_NvBlock_ReadFrom_KeyMCertificate_<NvBlock> .................................. 78
Table 4-51 KeyM_NvBlock_WriteToBlock_KeyMCertificate_<NvBlock> .............................. 79
Table 4-52 KeyM_NvBlock_Init_KeyMCertificate_<NvBlock> .............................................. 79
Table 4-53 KeyM_NvBlock_Callback_KeyMCertificate_<NvBlock> ..................................... 80
Table 4-54 KeyM_NvBlock_ReadFrom_CRE ...................................................................... 81
Table 4-55 KeyM_NvBlock_WriteTo_CRE ........................................................................... 81
Table 4-56 KeyM_NvBlock_Init_CRE .................................................................................. 82
Table 4-57 KeyM_NvBlock_Callback_CRE ......................................................................... 82
Table 4-58 Appl_VerifyCallbackFunc ................................................................................... 83
Table 4-59 Appl_ServiceCallbackFunc ................................................................................ 84
Table 4-60 Appl_VerifyGroupCallbackFunc ......................................................................... 84
Table 4-61 Appl_CertificateElementVerificationCallout ........................................................ 85
Table 4-62 Appl_SetKeyCallout ........................................................................................... 86
Table 4-63 Appl_CertInitCallout ........................................................................................... 87
Table 4-64 Appl_GetCurrentTimeCalloutFunc ..................................................................... 87
Table 5-1 NvM Block Needs .............................................................................................. 89
Table 6-1 Glossary ............................................................................................................ 91
Table 6-2 Abbreviations ..................................................................................................... 91

© 2022 Vector Informatik GmbH Version 4.2.0 10

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

1 Introduction

This document describes the functionality, API and configuration of the AUTOSAR BSW
module KeyM as specified in [1].

Supported Configuration Variants: pre-compile

Vendor ID: KeyM_VENDOR_ID 30 decimal
(= Vector-Informatik,
according to HIS)
Module ID: KeyM_MODULE_ID 109 decimal
(according to ref. [4])
* For the detailed functional specification please also refer to the corresponding AUTOSAR SWS.

The AUTOSAR KeyM module is separated into two sub modules, the crypto key submodule
and the certificate submodule.
The crypto key submodule provides services to introduce or update pre-defined
cryptographic key material.
The certificate submodule provides services for different operations on certificates. It allows
to define and configure certificates in a hierarchical PKI structure with root, intermediate and
target certificates. In this way, certificates can be stored and updated in permanent or
temporary storage. Furthermore, the submodule provides services to verify individual
certificates against already stored and provided certificates in a chain. Besides, the
submodule allows to access certificate data as well as specific certificate elements and to
verify their contents.

© 2022 Vector Informatik GmbH Version 4.2.0 11

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

1.1 Architecture Overview

The next figure shows the interfaces to adjacent modules of the KeyM. These interfaces are
described in chapter 4.
cmp Architecture

Application

«optional» «optional» KeyM_<CertificateHandling>CallbackNotification

«optional»

KeyM_<CertificateHandling> KeyM_<CryptoKeyOperations> «optional» KeyM_<CryptoKeyOperations>CallbackNotification

KeyM

SchM KeyM_MainFunction StbM_GetCurrentTime StbM

«optional»

BswM KeyM_Init Det_ReportError Det

«optional»

«optional» «optional» Csm_KeyElementSet Csm_AeadDecrypt KeyM_CallbackNotificationSignature

Read Write
Csm_SignatureVerify Csm_KeySetValid «optional»

NvM Csm

Figure 1-1 Interfaces to adjacent modules of the KeyM

© 2022 Vector Informatik GmbH Version 4.2.0 12

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

2 Functional Description

2.1 Features
The features listed in the following tables cover the functionality specified for the KeyM.
The AUTOSAR standard functionality is specified in [1], the corresponding features are listed
in the tables
> Table 2-1 Supported AUTOSAR standard conform features
> Table 2-2 Not supported AUTOSAR standard conform features
Vector Informatik provides further KeyM functionality beyond the AUTOSAR standard. The
corresponding features are listed in the table
> Table 2-3 Features provided beyond the AUTOSAR standard

The following features specified in [1] are supported:

Supported AUTOSAR Standard Conform Features
Set root and/or intermediate certificate
Update root and/or intermediate certificate
Set working certificate
Get certificate data from certificate slot in RAM or permanent key storage in CSM
Get certificate element
Get status of a certificate
Verify two certificates against each other
Verify certificate against certificate chain
Verify certificate against incomplete certificate chain
Retrieve iterated elements
Certificate validation period with StbM
Permanent certificate storage in NVM
Certificate Revocation List (CRL)
Asynchronous CSM job processing
Certificate Signing Request (CSR)
Table 2-1 Supported AUTOSAR standard conform features

2.1.1 Deviations
The following features specified in [1] are not supported:
Category Description ASR Version
Functional Crypto Key Submodule 4.4.0
Functional Key Generation for CSR 4.4.0

© 2022 Vector Informatik GmbH Version 4.2.0 13

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

Category Description ASR Version

Config KeyMCertificateElementVerification 4.4.0
Table 2-2 Not supported AUTOSAR standard conform features

2.1.1.1 Crypto Key Submodule

Only services of the certificate handling sub module are currently supported. The list of
services is described in chapter 4.2.8.

2.1.1.2 Key Generation for CSR

Currently there is no support for asymmetric key generation within the module, which is
required for the certificate signing request. In order to generate a CSR, the generated keys
need to be set as CSM key elements in a previous step.

2.1.1.3 Configuration of element verification

Currently there is no support for configuring conditions and rules for the element verification.
There is a workaround with an optional callout (see chapter 4.5.2.1).

2.1.2 Additions/ Extensions

The following features are provided beyond the AUTOSAR standard:
Features Provided Beyond The AUTOSAR Standard
Element Verification Callout
Public Key Setting Callout
Optional Certificate Elements
Retrieve certificate identifier by name (see Chapter 4.2.8.13)
Retrieve iterable certificate elements by index (see Chapter 4.2.8.14)
Dynamic issuer for certificates (see Chapter 2.6.11)
Dynamic certificate slot mapping (see Chapter 2.6.11)
Generic certificate revocation (see Chapter (2.6.12)
Provide service to access certificate structures (see Chapter 2.6.13)
Provide service to access issuer certificate identifier
OCSP Stapling (see Chapter 2.6.15)
Remote handling of service requests (see Chapter 2.6.16)
Table 2-3 Features provided beyond the AUTOSAR standard

© 2022 Vector Informatik GmbH Version 4.2.0 14

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

2.1.3 Limitations
2.1.3.1 CSR
The current implementation supports only synchronous CSM jobs for the signature
generation within the scope of a certificate signing request.
In addition, only certificate signing requests for X.509 certificates are supported so far.
2.1.3.2 ECDSA certificates
The signature of an ECDSA certificate contains two integers, an r- and an s-component. If
the lengths in bytes of these components are smaller than the maximum length according
to the ECC curve type of the certificate, the KeyM will format the components in such a way
that both are padded to the next larger multiple of 8 bytes with zero bytes. Thus, it must be
ensured that the underlying Crypto modules can handle signatures formatted in this way.

2.2 Initialization
Before any other functionality of the KeyM module can be called the initialization function
KeyM_Init() has to be called by the BswM.
For manual null initialization of RAM variables, the KeyM offers the function
KeyM_InitMemory() which can be called before the KeyM_Init().

2.3 States
The certificate handling is split into smaller computational units that form a state machine.
This way the main task of KeyM can perform asynchronously certificate operations as a
background task.
The main function can handle only one certificate operation at a time. This operation may
consist of multiple internal states. Internal states are:

> Idle: initial state before a service request

> Init: initialization of global RAM buffers for processing certificate
> Parse: parsing certificate data
> Verify Elements: verify parsed certificate elements
> Subject Check: compare issuer with subject of certificate in upper hierarchy
> Time Stamp Check: check certificate validation period
> Set Key: set public key in associated CSM key element
> Verify Signature: perform signature verification operation
> Store: store certificate data after successful verification
> Notify: notify application about end of service operation and verification result

The following sequence diagram depicts the states listed above using the example of setting
a CA certificate. Furthermore, it gives an overview of the services provided by other BSW
components used by the KeyM.

© 2022 Vector Informatik GmbH Version 4.2.0 15

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

DFSeq Functional

Application KeyM StbM NVM Csm

KeyM_ServiceCertificate()

Search for KeyMCertificate

Parsing

Verifying elements

Subject check
StbM_GetCurrentTime()

Time stamp check

Csm_KeyElementSet()

Csm_KeySetValid()

Csm_SignatureVerify()

opt
[Verification successful]
alt
[Nvm used for Key storage]
NvM_WriteBlock()

[Csm used for Key storage]

Csm_KeyElementSet()

Csm_KeySetValid()

Figure 2-1 Setting CA Certificate

2.4 Certificate Status

The following diagram displays the different status of a certificate during a certificate
verification operation. This status can be retrieved by calling the external API
KeyM_CertGetStatus(). The numbers indicated at the state transitions show possible
failure causes that can lead to this state transition.

© 2022 Vector Informatik GmbH Version 4.2.0 16

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

stm Certificate Status

Parse Validate
certificate certificate
Load certificate at startup
or
KeyM_SetCertificate(len>0) Parsing succeeded Validation succeeded

KEYM_CERTIFICATE
KEYM_CERTIFICATE KEYM_CERTIFICATE _PARSED_NOT_VALI KEYM_CERTIFICATE
_NOT_AVAILABLE _NOT_PARSED DATED _VALID
Power
Up

KeyM_Init
ST4 ST5
or
ST 1
KeyM_SetCertificate(len=0)
ST 8

KEYM_E_CERTIFICATE KEYM_CERTIFICATE KEYM_E_CERTIFICATE

_INVALID_FORMAT _INVALID _SIGNATURE_FAIL

ST2 ST 6
ST 9

KEYM_E_CERTIFICATE
KEYM_E_CERTIFICATE _VALIDITY KEYM_E_CERTIFICATE
_INVALID_TYPE _PERIOD_FAIL _REVOKED

ST 7

ST3
KEYM_E_CERTIFICATE
KEYM_E_CERTIFICATE _INVALID_CHAIN_OF
_INVALID_CONTENT _TRUST

Figure 2-2 Certificate Status

State Possible cause

Transition
Number
ST1 No valid ASN.1 format.
ST2 Certificate is not in a well-formatted form for X.509 or CVC.
ST3 Mismatch between the content of the certificate and the configured certificate
elements.
ST4 Unspecified failure during parsing
ST5 Unspecified failure during validation
ST6 Current time stamp is not within the validity period of the certificate.
ST7 One of the configured upper certificates is missing or is not in a valid state (and
could not brought to this state during the validation).
ST8 The signature verification of this certificate has failed or mismatched.
ST9 This certificate was identified on a revocation list that was maintained by the key
manager.
Table 2-4 Failure State Transitions

2.5 Main Functions

The KeyM module offers two main functions. The first one is called cyclically and handles
asynchronous jobs, whereas the second one can be used for background tasks. This is
useful when it is called from a pre-emptive operating system when no other task operation

© 2022 Vector Informatik GmbH Version 4.2.0 17

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

is needed. The background main function can be used for calling time consuming
synchronous functions.

2.6 Certificate Handling

This chapter gives an overview over the variety of general certificate operations which are
provided by the certificate handling submodule of the KeyM.

2.6.1 ASN.1 Parser

The KeyM ASN.1 parser supports X.509 and CRL certificates [5] as well as CVC certificates
[10]. Each certificate element is encoded in tag, length, and value (TLV-) syntax according
to DER rules [6].
To perform any operation on a certificate, the content needs to be parsed fully in a previous
step. Thereby after the parsing process one can retrieve a reference by accessing offset
and length of each pre-configured element. The parsed information is stored in a temporary
global RAM buffer. The parsing operation is performed whenever a certificate is set or
updated within the function call of KeyM_SetCertificate(),
KeyM_ServiceCertificate() or KeyM_SetCertificateInGroup(). Besides,
when a certificate is being verified, all issuing certificates that are currently unparsed are
parsed in the process. After parsing, a certificate’s individual elements can be accessed via
KeyM_CertElementGet(), KeyM_CertElementGetFirst() and
KeyM_CertElementGetNext() (see Chapter 4.2.8).

2.6.2 Element Verification

After a successful parsing, the data of each pre-configured certificate element is checked
against specified rules und conditions. The configuration container
KeyMCertificateElementVerification (see Chapter 2.1.1) specified by AUTOSAR
is currently not supported. However, verification of certificate elements can be achieved by
implementing the callout described in chapter 4.5.2.1.
The verification of certificate elements is performed whenever a certificate is set or updated
within the function call of KeyM_SetCertificate(), KeyM_ServiceCertificate()
or KeyM_SetCertificateInGroup().

2.6.3 Certificate Storage

The KeyM allows to configure certificates so that they can be stored at production time and
further be used for several purposes. For example, root and intermediate certificates of a
PKI system can be stored permanently in a specified certificate slot. If a certificate is
presented to the ECU, this certificate can be stored in a temporary place to perform further
verification.

2.6.3.1 Permanent Storage in CSM

The secure storage of certificates can be located in key storage locations of the CSM. To do
this, one has to configure a corresponding CSM key and reference it in

© 2022 Vector Informatik GmbH Version 4.2.0 18

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

KeyMCertificateCsmKeyTargetRef within the configuration of the KeyM. For more

detailed information on how to configure a CSM key, please refer to [3].

2.6.3.2 Permanent Storage in NvM

The KeyM allows optional usage of NvM in order to store certificate data in non-volatile
memory. To do so, the configuration container KeyMNvBlock needs to reference the
corresponding NvM blocks. Validations in the DaVinci Configurator 5 ensure that the blocks
in the NvM module are configured according to the KeyM’s requirements.
The KeyM provides an optional feature to notify the NvM that a referenced memory block
has changed (e.g. by calling NvM_SetRamBlockStatus). If the feature is disabled, the
KeyM module does not mark a block as modified (NvM_SetRamBlockStatus), it is up to
the NvM to detect the need of writing the block.
KeyM provides a callback for block initialization, reading from blocks and writing to blocks.
All blocks need to be mapped to the NvM_ReadAll operation.
The KeyM provides two modes for Block Processing:

> DEFERRED
The Block will only be marked as changed via NvM_SetRamBlockStatus.

> IMMEDIATE
The block is marked as changed via NvM_SetRamBlockStatus and the
NvM_WriteBlock is called. It is possible to overwrite the NvM write function and
configure it for NvM writing of KeyM. For this purpose, the name of the function
must be entered in the configuration
"/MICROSAR/KeyM/KeyMGeneral/KeyMNvWriteBlockFctName". Therefore, there is
a delay until the block is written to NvM.

© 2022 Vector Informatik GmbH Version 4.2.0 19

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

Caution
Depending on the Block Processing mode, the KeyM tries to trigger the write
operation. If the request to start the write operation fails (NvM_SetRamBlockStatus and
NvM_WriteBlock), the KeyM service function will not return with an error. The
KeyM will retry the operation in the next KeyM_MainFunction.

If the NvM operation fails and one of the configured callbacks reports an error, the
write operation will not be retried. The failure needs to be detected by the customer
using NvM. If an NVM write error occurs, the retry of the writing operation needs to be
handled by the customer, e.g. by calling NvM_WriteBlock for the effected block.

Information on the NvM block status need to be retrieved via NvM.

Note
It is recommended to ensure that KeyM data, which are stored in one or
more NvM blocks configured by
/MICROSAR/KeyM/KeyMCertificate/KeyMNvmBlock or
/MICROSAR/KeyM/KeyMCRE/KeyMCRENvmBlock,
are restored unchanged. The data integrity can be ensured e.g. by NvM using CRC.

The KeyM module does handle its configured NvM blocks. Therefore, the KeyM provides a
callback for block initialization, reading from blocks and writing to blocks. These callbacks
are specified in 4.4. All blocks need to be mapped to the NvM_ReadAll operation and it is
recommended to map DEFERRED blocks to the NvM_WriteAll operation.

Caution
The KeyM_NvBlock_Callback_KeyMCertificate _<NvBlock> and
KeyM_NvBlock_Callback_CRE must always be called for a write operation. This
includes NvM_WriteBlock and NvM_WriteAll. This can be either ensured by
configuration see 5.3 or by user code.

2.6.4 Certificate Verification

The KeyM allows the verification of two certificates that are stored and parsed internally
against each other. Thereby the KeyM references a pre-configured CSM job of the certificate

© 2022 Vector Informatik GmbH Version 4.2.0 20

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

in the upper hierarchy that is used to verify the signature of the lower certificate (see Chapter
4.2.8.6).
Furthermore, it is possible to verify a given certificate against all certificates in the associated
certificate chain (see Chapter 4.2.8.5). This chain can consist of certificates that are not
permanently available according to the configuration, so that the KeyM offers also an
additional service to pass the missing certificates to complete the chain for verification (see
Chapter 4.2.8.7).

2.6.5 Retrieving Certificate Data

The KeyM provides services to retrieve a complete certificate (see 4.2.8.4) as well as
specific certificate elements (see 4.2.8.9, 4.2.8.10, 4.2.8.11). Besides there is support for
getting the current status of a given certificate (see 4.2.8.12).

Additionally, KeyM provides the service KeyM_CertElementGetByStructureType (see

4.2.8.29) to retrieve certificate elements out of certificate data passed as input by referencing
a certificate structure type. The certificate structures that can be retrieved via this API are
listed in Table 4-7.
Due to ASN.1 formatting differences between different algorithms, the public key and the
signature are retrieved as an constructed BITSTRING ASN.1 element containing the ASN.1
tag identifier and tag length. The rest of the certificate elements are retrieves as the plain
tag value.

2.6.6 Service and verification notification to application

The KeyM invokes a callback notification to the application every time a requested service
is processed. In addition, in case of a verification service, the result of the verification
operation is conveyed. The provided interfaces are optional and have configurable function
names (see Chapter 4.5.1).

2.6.7 Startup Handling

The KeyM provides a startup handling for previously stored certificates in permanent
storage. Thereby after each startup, the stored certificates will be verified according to the
configured hierarchy. Since the parsing and verification operation at startup can slow down
the system, the startup handling for each certificate is optional. The custom enumeration
parameter KeyMCertStartUpHandling in the configuration can be used to specify the
startup behavior on a per-certificate basis. It allows parsing and verifying certain certificates
(PARSE_AND_VERIFY). Furthermore, if the permanent certificate storage is unaltered, it is
also possible to only parse and skip the verification operation (PARSE_AND_TRUST).
However, the startup handling for a given certificate is disabled per default (NONE).

2.6.8 Certificate Update

The KeyM provides services for updating CA certificates (root and intermediate) as well as
working certificates. When updating a CA certificate, the service first verifies the new

© 2022 Vector Informatik GmbH Version 4.2.0 21

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

certificate with the certificates in the upper hierarchies. In case of a new root certificate, the
root is verified with its own public key (self-signed). After a successful verification and
storage of the newly added certificate, the certificate status is set to valid, while all
certificates in the lower certificate are invalidated automatically and their status is reset to
parsed but not validated.

2.6.9 Certificate Revocation List

By adding a CRL, the KeyM allows to revoke certain certificates that are contained in the
list. The revocation is handled right before a certificate signature can be verified. Since the
CRL itself is verified by a CA certificate, it needs to be provided prior to any further verification
of another working certificate in order to ensure a possible revocation.
A new CRL is installed into KeyM by calling KeyM_ServiceCertificate with the service
KEYM_SERVICE_CERTUPDATE_CRL. During this installation, the certificate affected by
the CRL is first set to the state KEYM_CERTIFICATE_PARSED_NOT_VALIDATED. A
certificate is then set to state KEYM_E_CERTIFICATE_REVOKED during the next
validation. This behavior is defined by AUTOSAR.

Note
During the installation of a CRL the parameter revocationDate is not checked.

2.6.10 Certificate Signing Request

In order to handle a certificate signing request, an asymmetric key pair needs to be
generated. Both private and public key have to be set and validated as CSM key elements
in advance. The public key shall be set in the CSM key reference
KeyMCertCsmSignatureVerifyKeyRef of the corresponding certificate. Additionally,
the private key shall be set in the key referenced by the configured CSM job for the signature
generation in KeyMCertCsmSignatureGenerateJobRef. When setting the required key
pair, it is possible to set the public key either as plain value or according to ASN.1 encoding
rules including a leading zero byte as well as a format byte for ECDSA.

The necessary request data for a CSR, such as subject name and optional attributes, is
initialized in a first step by calling KeyM_InitCSR and passing the request data in
CsrInfo. For each array element in CsrInfo all configured subject names and as well
optional attributes have to be set by initializing a data pointer, a data length and an element
type before calling KeyM_InitCSR. All array elements need to be set in the exact order
as the corresponding certificate elements are configured. This parameter points to an array
of request data objects. The data returned by KeyM_InitCSR is then passed as request
data in KeyM_ServiceCertificate for the service

© 2022 Vector Informatik GmbH Version 4.2.0 22

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

KEYM_SERVICE_CERT_REQUEST_CSR, which eventually generates the final CSR

structure [7]. The advantage of this approach is that the complete set of CSR elements can
be set with one function call of KeyM_InitCSR. However, this method does not support
optional extensionRequest CSR elements.

Therefore, the KeyM supports a secondary iterative approach to set CSR element data. By
calling KeyM_CsrElementSet, each CSR element can be set separately. In this regard,
the certificate and element identifier as well as the encoding type need to be referenced.
While the element data for subject names and optional attributes has to be passed as plain
data (KEYM_CERT_ASN1_CSR_NO_ENCODING), extensions need to be encoded
(KEYM_CERT_ASN1_CSR_DER_ENCODING) before being passed in
KeyM_CsrElementSet. This input data includes the complete DER encoded data that
follows an object identifier in a certificate extension. After all CSR elements are set, calling
KeyM_ServiceCertificate with the service KEYM_SERVICE_CERT_REQUEST_CSR,
generates the final CSR structure [7]. Since no data is passed as input information for this
request, the parameter RequestDataLength needs to be zero. Note, however, that
RequestDataLength must still be a valid (i.e., not null) pointer.

The generated CSR structure is returned as response data of

KeyM_ServiceCertificate and a service callback notification, which can be configured
in KeyMServiceCertificateCallbackNotificationFunc.

After the Certificate Authority has signed the generated CSR, the resulting certificate can be
stored and validated by calling KeyM_ServiceCertificate with the service
KEYM_SERVICE_CERT_UPDATE_SIGNED_CSR.

© 2022 Vector Informatik GmbH Version 4.2.0 23

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

Note
The following distinguished name attributes are not supported for the CSR
initialization with the service KeyM_InitCSR:
KEYM_CERT_ASN1_CSR_ELEMENT_SUBJECT_SURNAME,
KEYM_CERT_ASN1_CSR_ELEMENT_SUBJECT_SERIALNUMBER,
KEYM_CERT_ASN1_CSR_ELEMENT_SUBJECT_STREETADDRESS,
KEYM_CERT_ASN1_CSR_ELEMENT_SUBJECT_TITLE,
KEYM_CERT_ASN1_CSR_ELEMENT_SUBJECT_GIVENNAME,
KEYM_CERT_ASN1_CSR_ELEMENT_SUBJECT_EMAIL,
KEYM_CERT_ASN1_CSR_ELEMENT_SUBJECT_USERID,
KEYM_CERT_ASN1_CSR_ELEMENT_SUBJECT_DOMAINCOMPONENT
Instead use KeyM_CsrElementSet to initialize a CSR with the upper
distinguished name attributes.

2.6.11 Dynamic issuer and certificate groups

According to AUTOSAR [1], the issuer for a given certificate must be configured statically
within the PKI. However, some use-cases may require to flexibly add and remove certificates
during the lifetime of an ECU. In order to meet this requirement, the MICROSAR Classic
KeyM does not only support preset, statically configured issuers, but also offers a feature to
determine certificates’ issuers dynamically at runtime.

The concept of dynamic certificate issuers mainly has the advantage of flexible PKI handling,
so that the user has to neither know the hierarchical relationships between certificates at
configuration time nor keep a specific order in which certificates have to be installed.
Furthermore, this approach saves resources, as the required memory for certificate data
storage can be reduced, since it eliminates the need to keep empty and unused certificate
slots for all possible configuration variants.

© 2022 Vector Informatik GmbH Version 4.2.0 24

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

R R

I1 I2 I1 I2

W1 ? ? W2 W1 ? W2

Figure 2-3 Preset Issuer vs. Dynamic Issuer

Figure 2-3 shows an example of a traditional preset-issuer scenario (left) and an example
of a dynamic issuer scenario (right). Both examples depict the use-case in which a working
certificate (named “?” in the figure) can be issued by one of two intermediary CA certificates.
In the traditional scenario, this use-case requires the user to create the working certificate
twice, once with every possible issuer. In scenario 2, the working certificate is configured so
that its issuer is determined dynamically at runtime. As shown in the figure, the configuration
can be flexibly extended to even include the root certificate. In this scenario, no additional
certificates are required and thus no additional memory resources are consumed.
If dynamic issuers are enabled for a certificate, its issuer is determined based on its issuer
common name.
In theory, this may enable an attack in which an attacker installs a certificate with a forged
subject common name, so that some certificates with dynamic issuers falsely identify it as
their issuer. The attacker has thus tampered with the legitimate issuer relations within the
PKI.
In order to thwart this kind of attack, the MICROSAR Classic KeyM introduces the concept
of Certificate Groups.
Certificate Groups reference two kinds of certificates:
> Members, which may act as issuer for each other. Every certificate with a dynamic
issuer must be a member of exactly one Certificate Group. All members of a
Certificate Group must have the exact same structure (for reasons explained in the
next paragraph), except for heterogeneous groups (see Chapter 2.6.11.1). Group
members can be configured via a group’s KeyMCertificateGroupCertRef parameter.

© 2022 Vector Informatik GmbH Version 4.2.0 25

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

> Additional Issuers, which are themselves not members of the group but may act as
issuer for group members. A certificate may act as an Additional Issuer for several
Certificate Groups. This is illustrated in Figure 2-4. Additional Issuers can be
configured via a group’s KeyMCertificateGroupIssuerRef parameter.

Besides defining which certificates may issue each other, Certificate Groups can also be
used to dynamically determine slots for certificates at runtime. For example, the user may
want to set a KeyM certificate at runtime, but does not know its ID. With Certificate Groups,
all the user needs to know about the certificate is its Group ID. The KeyM will determine the
certificate’s slot based on the certificate’s subject common name. If a certificate with the
same subject name is already present in the group, the KeyM will update that certificate. If
such a certificate is not yet present, it will select the next free slot within the group.

Shared additional
R dynamic issuer
reference

Group certificate
references

Group A Group B
Figure 2-4 Group Certificates

There are three options for the configuration of a dynamic issuer:

> DYNAMIC_MANDATORY_ISSUER means that if no issuer with the respective subject
common name is found, the certificate’s status is set to invalid.
> DYNAMIC_SELFSIGNED_OR_MANDATORY_ISSUER works like the previous option,
but also allows for the certificate to be self-signed.
> DYNAMIC_OPTIONAL_ISSUER means that the certificate is checked against its
issuer if an issuer can be determined. If not, the verification is skipped and the
certificate is deemed valid.

Members of a certificate group can be initially installed and updated using the service
KeyM_SetCertificateInGroup (see 4.2.8.18). When a certificate is initially set, the
parsing and the verification of certificate elements is processed synchronously within this
function. When a certificate is updated all certificates in the lower hierarchies are invalidated

© 2022 Vector Informatik GmbH Version 4.2.0 26

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

(Their certificate status is set to KEYM_CERTIFICATE_PARSED_NOT_VALIDATE) and a

asynchronous verification against the upper certificate and whole lower chain is initiated. A
certificate update requires the certificates to be installed in the chain order from top-to-
bottom, since an update can be only performed if there is a valid issuer.
After all certificates are installed initially, KeyM provides the possibility to verify all dynamic
group certificates with one single service call using KeyM_VerifyGroup (see 4.2.8.20).

2.6.11.1 Heterogeneous certificate groups

Group member certificates need to be configured mostly in the same way. Nevertheless, it
is possible to configure group member certificates with different algorithms within one
certificate group. Certificates with the same algorithm form a sub-group within the group and
need to be equally configured in-between. Note that the sub-groups are not visible in the
configuration process. The algorithm of a configured certificate is specified by the algorithm
family (KeyMCertAlgorithmFamily), algorithm type (KeyMCertAlgorithmType) and
the configured OIDs (KeyMCertificateElementObjectId) of the certificate element for
the public key algorithm info (structure type
CertificateSubjectPublicKeyInfo_PublicKeyAlgorithm).
When certificate data is installed in a heterogeneous group with different algorithms, KeyM
determines dynamically the certificate slot that matches the algorithm identifier specified in
the certificate data.

2.6.12 Generic certificate revocation

Besides CRLs according to X.509, the KeyM also offers an additional generic certificate
revocation concept. By setting so-called certificate revocation entries (CRE) which consist
of an issuer common name and a certificate serial number, the certificate that is to be
revoked can be uniquely identified. There is only a limited number of possible certificate
revocation entries. This number is defined during the configuration stage. Certificates that
have been revoked with CREs are revoked at runtime during the verification process. Every
installed CRE is persisted to NvM and is read after each startup. All CREs are stored in a
single NvM block.

For persisting the CREs in NvM, the same principles apply as for certificates. See 2.6.3.2
for further information.

2.6.13 Certificate structures

In addition to the KeyM_CertElementGet API (see 4.2.8.9) defined by the AUTOSAR
standard, the MICROSAR Classic KeyM offers an additional way to access certificate data
on a more basic level.
The KeyM_CertElementGet API can return only the primitive ASN.1 data (i.e., the individual
Integers, Bitstrings or UTFStrings, etc.) such as the contained elements in the certificate
subject or public key sequences. In some cases, it may, however, be required to return whole
ASN.1 structures, such as the whole certificate subject ASN.1 sequence with all its individual
fields. The MICROSAR Classic KeyM offers such an API (see 4.2.8.22), which returns the

© 2022 Vector Informatik GmbH Version 4.2.0 27

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

whole structure together with its structure header. The certificate structures that can be
retrieved via this API are listed in Table 4-7.
There are some certificate elements that do not consist of ASN.1 structures, such as the
Version or Serial Number fields. For these elements, the returned data consists only of the
primitive element data.

2.6.14 Certificate hash

The KeyM offers the option to compute a hash over given certificate data. Using the optional
configuration parameter KeyMCertCsmHashJobRef, one can specify a CSM hash job per
certificate. When configured, the corresponding hash is computed at startup for persisted
certificates or synchronously after the certificate data is initially installed.
By calling KeyM_GetCertHash() the computed hash can be retrieved (see 4.2.8.24).
If the hash calculation fails during start up, the start up is not blocked but when the hash is
retrieved, KeyM_GetCertHash() returns E_NOT_OK. If hash calculation fails during the
initial installation, the error E_NOT_OK is returned directly and the installation process
aborted.

Note
It must be secured that in the CSM hash primitive, which is referenced in the CSM
hash job, the result length is big enough to store the calculated hash

2.6.15 OCSP Stapling

The Online Certificate Status Protocol (OCSP) is used to determine the revocation status of
identified certificates [8]. By providing more timely revocation information, this method can
be used as alternative or in addition to checking against a periodic CRL. OCSP overcomes
the main limitation of CRLs: rather having to download and search through an entire CRL,
the client can check the status of a single certificate thus reducing overhead and burden of
the client. However, OCSP still requires the client to make requests to the CA which can
result in a huge number of requests on the OCSP responder.
The Transport Layer Security (TLS) Extension framework offers clients to request the
server's copy of the current status of certificates using a Certificate Status extension, which
is also referred as OCSP stapling [9]. This method shifts the burden from the client to the
server by reducing the number of roundtrips and network delays. The server makes the
OCSP request to the OCSP responder and staples the OCSP responses to the certificates
returned to the client. This allows the responses to be cached and then used multiple times
for many clients.

© 2022 Vector Informatik GmbH Version 4.2.0 28

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

Thus, a Certificate Status message is conveyed to the client, containing a list of all single
OCSP responses. The KeyM offers a service to parse and verify a Certificate Status
message and retrieve the revocation status for the corresponding certificates. For this
purpose, the common AUTOSAR API KeyM_ServiceCertificate() (see Chapter
4.2.8.1) can be used along with a custom service KEYM_SERVICE_CERT_STATUS_OCSP.
The Certificate Status message is passed as input data in the parameters RequestData
and RequestDataLenght. In case of an erroneous OCSP response within the Certificate
Status message, the OCSP response status will be returned in ResponseData and
ResponseDataLength. The remaining parameters are not used for the
KEYM_SERVICE_CERT_STATUS_OCSP service but still need to be valid. Ensure that the
parameter CertNamePtr is no null pointer. The parsing and verification of the passed
Certificate Status message is processed synchronously.
The KeyM supports both status types for Certificate Status messages containing single or
multiple OCSP responses. Besides, the KeyM is capable of processing OCSP responses of
the id-pkix-ocsp-basic response type. Within this context, a single OCSP response
can contain multiple certificates that are used to verify the OCSP signature. Furthermore,
the KeyM offers full support of hashing algorithms for the CertId element. The used OCSP
signature algorithm can be ECDSA or RSA.
After parsing of the Certificate Status message finished, the OCSP elements are verified
according to [8]. The KeyM verifies the following:
> OCSP response status
> Basic Response type
> Certificate identified in a received response
> Validity period of OCSP response (thisUpdate and nextUpdate)
> Version
> OCSP response signature
> Responder’s signature against certificate chain
> Certificate Status Value

Any other optional element within the OCSP response is parsed but not verified. If the OCSP
response is valid and the certificate shall be revoked according to the Certificate Status
Value, the KeyM will set the certificate status to KEYM_E_CERTIFICATE_REVOKED and a
revocation entry is added (see Chapter 2.6.12).
In order to enable the support of OCSP revocation for a given certificate, the optional sub
container KeyMOCSP needs to be configured per certificate. If the OCSP response contains
optional certificates for the OCSP signature verification, the optional parameter
KeyMOCSPDelegatedResponderRef needs to be configured. The dynamic group
referenced by this parameter is used to install the additional certificates. The hash algorithm
used for the CertId element in a OCSP response can be specified by configuring
KeyMOCSPResponseCertIdHashCsmJobRef. Furthermore, if the responder of the OCSP
response is identified by a public key hash, instead of its distinguished name, the CSM job
used for this hash operation can be configured in

© 2022 Vector Informatik GmbH Version 4.2.0 29

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

KeyMOCSPResponderPubKeyHashCsmJobRef. According to RFC6090, the used

algorithm for the responder's public key hash shall be SHA1.
The KeyM sets certificate revocations entries (CREs) for each revoked certificate, which is
why the CRE needs to be enabled in addition (see Chapter 2.6.12).
The CSM Jobs referenced in KeyMOCSPResponseCertIdHashCsmJobRef,
KeyMOCSPResponderPubKeyHashCsmJobRef and
KeyMCertCsmSignatureVerifyJobRef need to be configured as synchronous, since
the KeyM handles the service KEYM_SERVICE_CERT_STATUS_OCSP synchronously.

2.6.16 Remote Handling

Incoming service requests to KeyM can be processed either on application side or
alternatively on a remote instance (e.g. HSM). This is realized by transferring KeyM service
requests through CSM jobs and key management APIs to a custom Crypto driver. This way
the KeyM on application side acts solely as a proxy and any certificate operations are
processed completely on remote side. The KeyM APIs remain the same, independently if
the certificate is handled on application or remote side. In addition, the KeyM provides
remote service dispatching functions (see 2.6.16.1), that can be used on remote side. This
has the advantage that serialization and deserialization of passed data is handled only within
KeyM and the Crypto driver on remote side is independent from KeyM service requests.
In order to synchronize the application and remote side, a preconfiguration file is generated
based on the certificate configuration on remote side. The preconfiguration contains the
certificate configuration on application side. The preconfigured certificates require a CSM
job reference with an AEAD Decrypt primitive. This CSM job as well as the CSM key
referenced in the job are both used for the transfer of remote service requests. For this
purpose the configuration parameter KeyMCertCsmSignatureVerifyJobRef and
KeyMCertCsmSignatureVerifyKeyRef shall be used. Since the remote handling is
processed synchronously, the used CSM jobs need to be synchronous as well.
Please note that certificates that are handled on the remote side display a slightly different
callback behavior on the application side. Calls to
KeyM_ServiceCertificateCallbackNotification (if configured) only report return codes
KEYM_RT_OK and KEYM_RT_NOT_OK for remote certificates. Note that this is only a
subset of the return codes that are used for local application certificates (see chapter
4.5.1.2). Other, more detailed, return codes are simply reported as KEYM_RT_NOT_OK.

Caution
Please ensure that separate CSM jobs and CSM keys are configured for each certificate.
The crypto key identifier in the referenced CSM job corresponds to the certificate
identifier of the certificate on remote side. Therefore, the custom Crypto driver (e.g.
Crypto_30_KeyM) shall provide a mapping between crypto key identifier and certificate
identifier.
Also ensure that the used CSM job primitive is set to the AEAD Decrypt primitive
provided by the custom Crypto driver.

© 2022 Vector Informatik GmbH Version 4.2.0 30

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

Caution
Please consider that the startup handling for preconfigured certificates is processed on
remote side only.

Caution
Since the revocation of a single certificate can have an effect on the complete PKI, CRE
(see Chapter 2.6.12) and OCSP (see Chapter 2.6.15) are processed either fully on
application side or remote side. Mixed PKIs with application and remote certificates are
suppressed by generator validation. This applies for both certificates with preset issuer
as well as certificates with dynamic issuer (see Chapter 2.6.11).

2.6.16.1 Dispatching Remote Service Requests

The following table shows the provided dispatching functions and their corresponding
service requests.

Dispatching Function KeyM Service Request

KeyM_DispatchRemoteJob KeyM_ServiceCertificate

KeyM_ServiceCertificateById

KeyM_VerifyCertificates

KeyM_VerifyCertificate

KeyM_VerifyCertificateChain

KeyM_SetCertificateInGroup

KeyM_VerifyGroup

KeyM_DispatchRemoteKeyElementSet KeyM_SetCertificate

KeyM_SetCRE

KeyM_CsrElementSet

KeyM_DispatchRemoteKeyElementGet KeyM_GetCertificate

KeyM_CertElementGet

KeyM_CertGetStatus

KeyM_CertificateElementGetByIndex

© 2022 Vector Informatik GmbH Version 4.2.0 31

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

KeyM_CertificateElementGetCount

KeyM_CertStructureGet

KeyM_GetIssuerCertId

KeyM_GetCertHash
Table 2-5 Dispatching Remote Service Requests

Caution
Due to parameter limitations of CSM primitives and key management APIs, the following
KeyM services are not supported for remote service handling:
• KeyM_CertElementGetFirst
• KeyM_CertElementGetNext
• KeyM_InitCSR
• KeyM_GetGroupCertId

2.6.17 Callback Notifications

There exist three different configurable callback notifications to provide information to the
application about processing asynchronous service requests.
By configuring KeyMServiceCertificateCallbackNotificationFunc (see chapter
4.5.1.2) the application is notified if a certificate service operation was finished and provides
its status. A certificate service operation can be triggered by the APIs
KeyM_ServiceCertificate or KeyM_ServiceCertificateById. This callback
notification is called, if configured, only for the referenced certificate.
By configuring KeyMCertificateVerifyCallbackNotificationFunc (see chapter
4.5.1.1) the application is notified if a verification operation was finished and provides its
status. A verification operation can be triggered by the APIs KeyM_VerifyCertificate,
KeyM_VerifyCertificates, KeyM_VerifyCertificateChain. This callback
notification is called, if configured, for all certificates involved within the verification process.
By configuring KeyMCertificateGroupVerifyCallbackNotificationFunc (see
chapter 4.5.1.3) the application is notified if a certificate group verification operation was
finished and provides its status. A verification operation can be triggered by the API
KeyM_VerifyGroup. This callback notification is called, if configured, for the referenced
certificate group. The overall certificate group verification status is valid, only if all certificate
group members could be verified successfully.

2.6.18 RAM Certificate Slot Sharing

The KeyM provides the option to share a dedicated RAM certificate slot for certificate data
and certificate status in between several certificates. This has the advantage that a series
of certificate variants with different signature algorithms can be supported by only allocating
one RAM certificate slot. To achieve this, each certificate slot needs to be instantiated in

© 2022 Vector Informatik GmbH Version 4.2.0 32

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

KeyMCertificateSlot and can be referenced by the corresponding certificates in

KeyMCertificateSlotRef.
This feature is only supported for certificates with storage type RAM
(KEYM_STORAGE_IN_RAM). Furthermore, certificates with configured init values, can't be
used for slot sharing.

Note
If a CA certificate shares a RAM slot with another certificate and the CA certificate is
preempted from the RAM slot, all of its directly and indirectly issued certificates will
remain in their current respective certificate statuses (e.g.
KEYM_CERTIFICATE_VALID).
If a verification is not explicitly triggered on these certificates, they will remain in their
certificate status until ECU restart and will, for example, not react to a revocation of an
upper certificate.
If a verification is triggered on one of these certificates and the CA certificate is still
preempted from the RAM slot, the verification will fail and the orphaned certificate's
status will reflect this.

2.7 Error Handling

2.7.1 Development Error Reporting
By default, development errors are reported to the DET using the service
Det_ReportError() as specified in [2], if development error reporting is enabled (i.e. pre-
compile parameter KeyM_DEV_ERROR_REPORT==STD_ON).
If another module is used for development error reporting, the function prototype for
reporting the error can be configured with the parameter
DetReportRuntimeErrorCallout, but must have the same signature as the service
Det_ReportError().
The reported KeyM Module ID is 109.
The reported service IDs identify the services which are described in [1]. The following table
presents the service IDs and the related services:
Service ID Service
0x01 KeyM_Init()
0x02 KeyM_Deinit()
0x03 KeyM_GetVersionInfo()
0x04 KeyM_Start()
0x05 KeyM_Prepare()
0x06 KeyM_Update()
0x07 KeyM_Finalize()
0x08 KeyM_Verify()

© 2022 Vector Informatik GmbH Version 4.2.0 33

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

Service ID Service
0x09 KeyM_ServiceCertificate()
0x0A KeyM_SetCertificate()
0x0B KeyM_GetCertificate()
0x0C KeyM_VerifyCertificates()
0x0D KeyM_VerifyCertificate()
0x0E KeyM_VerifyCertificateChain()
0x0F KeyM_CertElementGet()
0x10 KeyM_CertElementGetFirst()
0x11 KeyM_CertElementGetNext()
0x12 KeyM_CertGetStatus()
0x19 KeyM_MainFunction()
0x1A KeyM_MainBackgroundFunction()
0x80 KeyM_NvBlock_ReadFromBlock()
0x81 KeyM_NvBlock_WriteToBlock()
0x82 KeyM_NvBlock_Init()
0x83 KeyM_NvBlock_Callback()
0x84 KeyM_NvBlock_ReadFromBlock_CRE()
0x85 KeyM_NvBlock_WriteToBlock_CRE()
0x86 KeyM_NvBlock_Init_CRE()
0x87 KeyM_NvBlock_Callback_CRE()
0x88 KeyM_CertificateElementGetByIndex()
0x89 KeyM_CertificateElementGetCount()
0x8A KeyM_InitCSR()
0x8B KeyM_ServiceCertificateById()
0x8C KeyM_SetCertificateInGroup()
0x8D KeyM_GetGroupCertId()
0x8E KeyM_VerifyGroup()
0x8F KeyM_SetCRE()
0x90 KeyM_CertStructureGet()
0x91 KeyM_GetIssuerCertId()
0x92 KeyM_GetCertHash()
0x93 KeyM_CsrElementSet()
0x94 KeyM_DispatchRemoteJob()
0x95 KeyM_DispatchRemoteKeyElementSet()
0x96 KeyM_DispatchRemoteKeyElementGet()
0x97 KeyM_SetCertificateWithConstPtr()
0x98 KeyM_VerifyCertificateChainWithConstPtr()
0x99 KeyM_Cert_SearchCert()

© 2022 Vector Informatik GmbH Version 4.2.0 34

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

Service ID Service
0x9A KeyM_Cert_IsBusy()
0x9B KeyM_CallbackNotificationSignature()
0x9C KeyM_CertElementGetByStructureType()
Table 2-6 Service IDs

The errors reported to DET are described in the following table:

Error Code Description
0x00 KEYM_E_NO_ERROR
0x01 KEYM_E_PARAM_POINTER
0x02 KEYM_E_SMALL_BUFFER
0x03 KEYM_E_UNINIT
0x04 KEYM_E_INIT_FAILED
0x80 KEYM_E_WRITE_ACCESS_FAILED
0x81 KEYM_E_CERTIFICATE_INIT_VALUE_INVALID_LENGTH
0x82 KEYM_E_INVALID_CONFIGURATION
Table 2-7 Errors reported to DET

© 2022 Vector Informatik GmbH Version 4.2.0 35

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

3 Integration

This chapter gives necessary information for the integration of the MICROSAR Classic
KeyM into an application environment of an ECU.

3.1 Embedded Implementation

The delivery of the KeyM contains these source code files:
File Name Description
KeyM.c This is the main source file of the KeyM.
KeyM.h This is the header file of the KeyM.
KeyM_Cert.c This is the source file of the certificate handling sub module.
KeyM_Cert.h This is the header file of the certificate handling sub module.
KeyM_Asn1.c This is the source file of the ASN.1 parser.
KeyM_Asn1.h This is the header file of the ASN.1 parser
KeyM_Cbk.h This is the header file, which contains the callback function declaration for the
CSM callback.
KeyM_Cfg.c This is configuration source file.
KeyM_Cfg.h This is configuration header file.
KeyM_Types.h This is a common header for data types used for service interfaces of the KeyM.
Table 3-1 Implementation files

3.2 Critical Sections

KeyM uses the following critical section:
> KEYM_EXLUSIVE_AREA_0
This critical section protects the main task busy state and ensures that the processing
of the current main task is not interrupted. Furthermore, it ensures the consistency of
the global RAM variables for the processing state, certificate Id, signature callback flag
and signature callback result.

> KEYM_EXLUSIVE_AREA_1
This critical section protects concurrent accesses to KeyM_CertStorage by KeyM and
NVM, e.g. copy operations, and accesses to KeyM_NvBlock_State used for NVM
handling. Furthermore, it ensures the consistency of global RAM variables for
certificate data.

© 2022 Vector Informatik GmbH Version 4.2.0 36

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

3.3 Certificate Configuration

A correct and complete certificate configuration is essential for the operation of the certificate
handling submodule. Each certificate, including all its corresponding certificate elements,
needs to be configured with respect to the plain certificate data as well as the hierarchical
PKI. Several aspects of this are clarified in this chapter.

Caution
The configuration of the KeyM has dependencies to the Crypto Stack and the NvM.
Therefore, it is necessary to always generate the KeyM in case the configuration of the
Crypto Stack or NvM was changed.

3.3.1 Algorithm family

The KeyMCertAlgorithmFamily is a custom parameter and shall specify the required
algorithm family for the signature verification operation of a given certificate. It is primarily
necessary for setting the public key in the required format as a CSM key. This parameter
needs to be set only for certificates with KeyMCertAlgorithmType set to ECC.

3.3.2 Verification Job and Key Dependencies

The configuration of the KeyMCertCsmSignatureVerifyJobRef and
KeyMCertCsmSignatureVerifyKeyRef must follow a strict pattern. While
KeyMCertCsmSignatureVerifyJobRef references the CSM job that is used to verify
the signature issued by the respective certificate,
KeyMCertCsmSignatureVerifyKeyRef references the CSM key that is used to store
the certificate’s own public key. Root certificates are the only certificates that reference the
same CSM job that is used for their verification as they are self-signed.

Caution
All signature verify jobs need to be configured either as synchronous or as
asynchronous jobs. A mixed configuration leads to undefined behavior.

© 2022 Vector Informatik GmbH Version 4.2.0 37

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

Mdl Certificate Configuration

Root «use for

verification»
Job 1

Signature Verify Job Ref Job Key Ref

Signature Verify Key Ref Key 1

«use for
verification»

Intermediate

Job 2
Signature Verify Job Ref
Job Key Ref

Signature Verify Key Ref Key 2

«use for
verification»

Working Certificate
Job 3

Signature Verify Job Ref Job Key Ref

Signature Verify Key Ref Key 3

Figure 3-1 Certificate Verification Job and Key References

3.3.3 Certificate Initial Value

The optional configuration of the choice container KeyMCertInit for each certificate
allows to define initial certificate data. By instantiating either a KeyMCertInitValue or
KeyMCertInitCallout sub container, one can choose how the initial certificate data is
provided.
The certificate initialization can be accomplished easily, by setting the corresponding
certificate data in hexadecimal format divided by comma in the KeyMCertInitValue
configuration parameter. Alternatively, one can configure a callout in
KeyMCertInitCallout which returns the certificate data and its data length.
Providing a certificate initial value is especially useful for CA (Certificate Authority)
certificates, that are fixed and known by the manufacturer. This way the setting of a
certificate during runtime is not necessary and can be achieved during the configuration
phase. Nevertheless it is also possible to overwrite a given initial value by calling one of the
set services, except for ROM certificates.
While for most certificate storage types (KEYM_STORAGE_IN_RAM,
KEYM_STORAGE_IN_CSM, KEYM_STORAGE_IN_NVM) the configuration of a certificate
initial value is optional, for read-only certificates (KEYM_STORAGE_IN_ROM) it is mandatory.
The configuration of a ROM certificate with an initial value has the advantage of reducing
the necessary RAM memory which is used for each certificate slot.

© 2022 Vector Informatik GmbH Version 4.2.0 38

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

Caution
Certificate information and the length of the certificate information provided via
KeyMCertInitCallout may not be changed during the lifetime of the data. If this
happens, the processing of the certificate information may return with errors.

3.3.4 Element configuration

Per default, it is required to configure only certificate elements that are either mandatory for
the certificate verification (issuer name, validity period, subject name, public key, signature)
or are of interest for the application and shall be retrievable after a certificate has been set.
By enabling the KeyMCertAllowUnconfiguredElements parameter per configured
certificate, not all contained certificate elements need to be configured. Thus, the ASN.1
parser will accept certificate elements that are part of the certificate data but were not set at
configuration stage. However, those certificate elements will just be skipped during the
parsing and will not be available for further retrieving. If
KeyMCertAllowUnconfiguredElements is disabled, all elements that are contained in
the certificate data need to be configured accordingly.
Besides, the order in which the certificate elements are configured is per default flexible, so
that the parsing is independent from any variations of the order within the distinguished
names or extension elements for example. By enabling the
KeyMCertAllowFlexibleOrder parameter per configured certificate, the order in which
the certificate elements are configured does not need to be equal to the actual certificate
data. If KeyMCertAllowFlexibleOrder is disabled, all certificate elements need to be
configured in the exact order as they appear in the certificate data.
By configuring a certificate element as optional, it is ensured that if the element is present in
the certificate data, it will be parsed and can be retrieved afterwards, but will not cause a
parsing error if it is not present. This feature is useful especially for the configuration of
optional elements within the extensions section of a certificate.

Furthermore, it is possible to replace configured certificate elements by enabling both the

KeyMCertAllowUnconfiguredElements parameter for the given certificate and the
KeyMCertificateElementOptional parameter for the given certificate element.
If there are several primitive ASN.1 sub-elements (e.g., Integer, Boolean) with the same tag
identifier within a certificate extension that shall be retrievable afterwards, it is required to
specify a certificate element path with the KeyMCertificateElementPath parameter.
The element path can only be configured certificate extension elements.
This is used to specify the position of the configured certificate sub-element within its basic
element structure. If no certificate element path is configured, the ASN.1 parser will match
the first configured certificate element of the same tag identifier.

© 2022 Vector Informatik GmbH Version 4.2.0 39

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

The path is based on the outer ASN.1 sequence element of the basic element structure. The
certificate element path is configured in chapters so that each chapter corresponds to a
nesting level within the ASN.1 sequence. Chapters are specified with decimal integers and
dots in between subchapters.

Exemplary configuration of the element path for the red INTEGER within the following ASN.1
SEQUENCE and path 1.2.1:
SEQUENCE {
OBJECT IDENTIFIER,
OCTET STRING {
INTEGER,
}
}

Caution
Mandatory certificate elements that are relevant for the verification (e.g. public key,
signature, validity period, issuer and subject common names) need to be configured in
order to ensure an accurate processing.

3.3.5 Public key configuration

Within the scope of the configuration of a public key, the
KeyMCertificateElementOfStructure parameter has to be set to
CertificateSubjectPublicKeyInfo_SubjectPublicKey for the plain data of the
public key element and
CertificateSubjectPublicKeyInfo_PublicKeyAlgorithm for the algorithm
object identifier.

3.3.6 Object Type

The KeyMCertificateElementObjectType parameter needs to be set according to the
ASN.1 format. Control elements like Sequence and Set are constructed elements and
therefore are not part of the configuration.
The following table shows the supported universal primitive ASN.1 tags by the parsing
submodule.
Element Description Object Type
Boolean 0x01
Integer 0x02
Bit String 0x03
Octet String 0x04
NULL 0x05

© 2022 Vector Informatik GmbH Version 4.2.0 40

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

Object Id 0x06
Enumerated 0x0A
UTF8 0x0C
Printable String 0x13
IA5 String 0x16
UTC Time 0x17
Generalized Time 0x18
BMPString 0x1E
Table 3-2 Supported universal ASN.1 tags

CVC certificates, in particular, include application elements with tags that are encoded in
one or two octets. Besides the element class and structure type, the remaining tag number
is an identifier for the element description type.
The table below shows the complete tag value for all supported element description types
and the corresponding object type which should be used for the corresponding element in
the configuration.
Element Description Tag Object Type
Certificate Profile Identifier 0x5F29 0x2
Certification Authority Reference 0x42 0xC
Public Key 0x7F49 0x81 / 0x86
Certificate Holder Reference 0x5F20 0xC
Certificate Holder Authorization 0x7F4C 0x4
Template
Certificate Effective Date 0x5F25 0x17
Certificate Expiration Date 0x5F24 0x17
Signature 0x5F37 0x4
Discretionary Data 0x53 0x4
Table 3-3 Supported CVC Tags

The element for elliptic curve public keys can include all curve parameters marked with
corresponding tags (0x81 – 0x87). In this case the object type for the public key element
has to be configured to 0x81.
It is also possible that only the public point is available as curve parameter in the plain data
of the public key, designated with the tag 0x86. In this case the object type has to be
configured to 0x86.

3.3.7 Configuration of CRLs

To configure a CRL in DaVinci configurator 5, a certificate with a special configuration needs
to be considered. This certificate requires a certificate element with the parameter
KeyMCertificateElementOfStructure set to the value "CertificateRevocationList"
and the parameter KeyMCertificateElementObjectType set to the value “0x10”.
Everything else can be configuration like other certificates.

© 2022 Vector Informatik GmbH Version 4.2.0 41

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

4 API Description

For an interfaces overview please see Figure 1-1.

4.1 Type Definitions

The types defined by the KeyM are described in this chapter.

KeyM_CertElementIteratorType
This structure is used to iterate through a number of elements of a certificate.
Struct Element C-Type Description Value Range
Name
certId uint16 Holds the identifier of the
certificate.
Holds the offset to the parsed
offset uint16
element in the RAM buffer.
Holds the length of the element
elementLength uint16
to be retrieved.
Holds the element index of the
rootElementIdx uint16
root element.
KEYM_CERT_ELEMENT_ITERATION
_NOT_INITIALIZED
KEYM_CERT_ELEMENT_ITERATION
Holds the current status of the _INITIALIZED
iterationStatus uint8
iteration process. KEYM_CERT_ELEMENT_ITERATION
_VALID
KEYM_CERT_ELEMENT_ITERATION
_INVALID
Table 4-1 KeyM_CertElementIteratorType

KeyM_CSRInfoType
This structure is used to initialize the request objects for a CSR.
Struct C-Type Description Value Range
Element
Name
dataPtr uint8* Points to an array that
holds request object
data.
Holds the length of the
dataLength uint16
request object data.

© 2022 Vector Informatik GmbH Version 4.2.0 42

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

Struct C-Type Description Value Range

Element
Name
KEYM_CERT_ASN1_CSR_ELEMENT_SUBJECT_
COUNTRYNAME
KEYM_CERT_ASN1_CSR_ELEMENT_SUBJECT_
STATEORPROVINCENAME
KEYM_CERT_ASN1_CSR_ELEMENT_SUBJECT_
LOCALITYNAME
KEYM_CERT_ASN1_CSR_ELEMENT_SUBJECT_
ORGANIZATIONNAME
KEYM_CERT_ASN1_CSR_ELEMENT_SUBJECT_
ORGANIZATIONUNITNAME
KEYM_CERT_ASN1_CSR_ELEMENT_SUBJECT_
COMMONNAME
KEYM_CERT_ASN1_CSR_ELEMENT_SUBJECT_
SURNAME
KEYM_CERT_ASN1_CSR_ELEMENT_SUBJECT_
SERIALNUMBER
Defines the type of the KEYM_CERT_ASN1_CSR_ELEMENT_SUBJECT_
elementType uint8 STREETADDRESS
request object.
KEYM_CERT_ASN1_CSR_ELEMENT_SUBJECT_
TITLE
KEYM_CERT_ASN1_CSR_ELEMENT_SUBJECT_
GIVENNAME
KEYM_CERT_ASN1_CSR_ELEMENT_SUBJECT_
EMAIL
KEYM_CERT_ASN1_CSR_ELEMENT_SUBJECT_
USERID
KEYM_CERT_ASN1_CSR_ELEMENT_SUBJECT_
DOMAINCOMPONENT
KEYM_CERT_ASN1_CSR_ELEMENT_ATTRIBUT
E_UNSTRUCTUREDNAME
KEYM_CERT_ASN1_CSR_ELEMENT_ATTRIBUT
E_CHALLENGEPASSWORD
KEYM_CERT_ASN1_CSR_ELEMENT_ATTRIBUT
E_EXTENSION
Table 4-2 KeyM_CSRInfoType

The buffer referenced by dataPtr must provide at least as many bytes as stored in
dataLength.

KeyM_ConstCertDataType
This structure is used to provide initial certificate data with an optional callout (see 4.5.2.3).

© 2022 Vector Informatik GmbH Version 4.2.0 43

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

Struct Element C-Type Description

Name
certData KeyM_ConstCertDataPointerType Points to an array that holds initial certificate
data.
certDataLength uint32 Holds the length of the initial certificate data.
Table 4-3 KeyM_ConstCertDataType

The buffer referenced by certData must provide at least as many bytes as stored in
certDataLength.

KeyM_ConstCertDataPointerType
This type is used in KeyM_ConstCertDataType.
Type Name C-Type Description
KeyM_ConstCertDataPointerType const uint8* Points to an array that holds initial certificate
data.

Table 4-4 KeyM_ConstCertDataPointerType

KeyM_CertificateGroupIdType
This type is used to identify a certificate group.
Type Name C-Type Description
KeyM_CertificateGroupIdType uint16 Holds the certificate group identifier.

Table 4-5 KeyM_CertificateGroupIdType

KeyM_CertificateGroupStatusType
This type is used for the overall status of a certificate group verification.
Type Name C- Description Value Range
Type
KeyM_CertificateGroupStatusType uint8 Holds the KEYM_CERT_VERIFY_GROUP_VALID
result of a All group member certificates were
certificate verified successfully.
group
verification. KEYM_CERT_VERIFY_GROUP_INVALID
One or more group member certificates
could not be verified successfully.
Table 4-6 KeyM_CertificateGroupStatusType

KeyM_CertificateStructureType
This uint32-based enumeration type is used by APIs that allow the configuration-
independent retrieval of certificate element data. There are multiple APIs like this and the
way in which they format the retrieved data may differ slightly (see chapters 2.6.5 and 2.6.13

© 2022 Vector Informatik GmbH Version 4.2.0 44

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

and for details). Note that not all APIs are compatible with all structures. The right columns
of the following table show which values are compatible with which API. Some values are
currently not used by any API, but may be supported in the future.

KeyM_CertStructureGet

KeyM_CertElementGet
ByStructureType
Value

KEYM_CERTIFICATE_EXTENSION X
KEYM_CERTIFICATE_ISSUER_NAME X
KEYM_CERTIFICATE_ISSUER_UNIQUE_IDENTIFIER
KEYM_CERTIFICATE_REVOCATION_LIST
KEYM_CERTIFICATE_SERIAL_NUMBER X X
KEYM_CERTIFICATE_SIGNATURE X X
KEYM_CERTIFICATE_SIGNATURE_ALGORITHM X X
KEYM_CERTIFICATE_SIGNATURE_ALGORITHM_ID X X
KEYM_CERTIFICATE_SUBJECT_NAME X
KEYM_CERTIFICATE_SUBJECT_PUBLIC_KEY_INFO_PUBLIC_KEY_ALGORITHM X
KEYM_CERTIFICATE_SUBJECT_PUBLIC_KEY_INFO_SUBJECT_PUBLIC_KEY
KEYM_CERTIFICATE_SUBJECT_UNIQUE_IDENTIFIER
KEYM_CERTIFICATE_VALIDITY_PERIOD_NOT_AFTER X
KEYM_CERTIFICATE_VALIDITY_PERIOD_NOT_BEFORE X
KEYM_CERTIFICATE_VERSION_NUMBER X X
KEYM_CERTIFICATE_SUBJECT_PUBLIC_KEY_INFO X
KEYM_CERTIFICATE_VALIDITY_PERIOD X
KEYM_CERTIFICATE_SUBJECT_PUBLIC_KEY_INFO_PUBLIC_KEY_ECC_CURVE X
Table 4-7 KeyM_CertificateStructureType

4.2 Services provided by KeyM

4.2.1 KeyM_InitMemory
Prototype
void KeyM_InitMemory (void)

© 2022 Vector Informatik GmbH Version 4.2.0 45

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

Parameter
void none
Return code
void none
Functional Description
The function initializes variables, which cannot be initialized with the startup code.
Initialize component variables at power up.
Particularities and Limitations
Module is uninitialized.
Call context
> TASK
> This function is Synchronous
> This function is Non-Reentrant
Table 4-8 KeyM_InitMemory

4.2.2 KeyM_Init
Prototype
void KeyM_Init (const KeyM_ConfigType *ConfigPtr)
Parameter
ConfigPtr [in] Pointer to the configuration set in VARIANT-POST-BUILD
Return code
void none
Functional Description
Initializes the Key Manager.
This function initializes the KeyM module. It initializes all variables and sets the module state to initialized.
Particularities and Limitations
Interrupts are disabled. Module is uninitialized.
Call context
> TASK
> This function is Synchronous
> This function is Non-Reentrant
Table 4-9 KeyM_Init

4.2.3 KeyM_Deinit
Prototype
void KeyM_Deinit (void)

© 2022 Vector Informatik GmbH Version 4.2.0 46

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

Parameter
void none
Return code
void none
Functional Description
Resets the Key Manager.
This function resets the KeyM module to the uninitialized state.
Particularities and Limitations
-
Call context
> TASK
> This function is Synchronous
> This function is Non-Reentrant
Table 4-10 KeyM_Deinit

4.2.4 KeyM_GetVersionInfo
Prototype
void KeyM_GetVersionInfo (Std_VersionInfoType *VersionInfo)
Parameter
VersionInfo [out] Pointer to where to store the version information. Parameter must not be
NULL.
Return code
void none
Functional Description
Returns the version information.
KeyM_GetVersionInfo() returns version information, vendor ID and AUTOSAR module ID of the component.
Particularities and Limitations
-
Configuration Variant(s): KEYM_VERSION_INFO_API == STD_ON
Call context
> TASK
> This function is Synchronous
> This function is Reentrant
Table 4-11 KeyM_GetVersionInfo

© 2022 Vector Informatik GmbH Version 4.2.0 47

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

4.2.5 KeyM_MainFunction
Prototype
void KeyM_MainFunction (void)
Parameter
void none
Return code
void none
Functional Description
Main function of the module. Is called cyclically and handles asynchronous jobs.
Particularities and Limitations
Declared and called by SchM.
-
Call context
> TASK
> This function is Synchronous
> This function is Non-Reentrant
Table 4-12 KeyM_MainFunction

4.2.6 KeyM_MainBackgroundFunction
Prototype
void KeyM_MainBackgroundFunction (void)
Parameter
void none
Return code
void none
Functional Description
Main function for background tasks.
Function is called from a pre-emptive operating system when no other task operation is needed. Can be
used for calling time consuming synchronous functions.
Particularities and Limitations
Declared and called by SchM.
-
Call context
> TASK
> This function is Synchronous
> This function is Non-Reentrant
Table 4-13 KeyM_MainBackgroundFunction

© 2022 Vector Informatik GmbH Version 4.2.0 48

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

4.2.7 Key Sub-Module

4.2.7.1 KeyM_Prepare
Prototype
Std_ReturnType KeyM_Prepare (const uint8 *RequestData, uint32
RequestDataLength, uint8 *ResponseData, uint32 *ResponseDataLength)
Parameter
RequestData [in] Information that comes along with the request.
RequestDataLength [in] Length of data in the RequestData array.
ResponseDataLength In: Max number of bytes available in ResponseData. Out: Actual number.
[in,out]
ResponseData [out] Data returned by the function.
Return code
Std_ReturnType E_OK Service has been accepted and will be processed
internally. Results will be provided through a callback.

E_NOT_OK Service not accepted due to an internal error.

KEYM_E_PARAMETER_MISMATCH Parameter does not match with
expected value.
KEYM_E_KEY_CERT_SIZE_MISMATCH Parameter size doesn't match.
Functional Description
Prepare key update.
This function is used to prepare a key update operation. The main intent is to provide information for the
key operation to the key server. Other operations may start the negotiation for a common secret that is
used further to derive key material. This function is only available if
KeyMCryptoKeyPrepareFunctionEnabled is set to TRUE.
Particularities and Limitations
-
Configuration Variant(s): KEYM_CRYPTO_KEY_PREPARE_FUNCTION_ENABLED == STD_ON
Call context
> TASK
> This function is Synchronous
> This function is Non-Reentrant
Table 4-14 KeyM_Prepare

4.2.7.2 KeyM_Start
Prototype
Std_ReturnType KeyM_Start (KeyMStartType StartType, const uint8 *RequestData,
uint32 RequestDataLength, uint8 *ResponseData, uint32 *ResponseDataLength)
Parameter
StartType [in] Defines in which mode the key operation shall be executed.

© 2022 Vector Informatik GmbH Version 4.2.0 49

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

RequestData [in] Information that comes along with the request, e.g. signature.
RequestDataLength [in] Length of data in the RequestData array.
ResponseDataLength In: Max number of bytes available in ResponseData. Out: Actual number.
[in,out]
ResponseData [out] Data returned by the function.
Return code
Std_ReturnType E_OK Start operation successfully performed. Key update operations are now
allowed.
E_NOT_OK Start operation not accepted.
KEYM_E_PARAMETER_MISMATCH Parameter does not match with
expected value.
KEYM_E_KEY_CERT_SIZE_MISMATCH Parameter size doesn't match.
Functional Description
Starts a session for key operations.
This function is optional and only used if the configuration item
KeyMCryptoKeyStartFinalizeFunctionEnabled is set to true. It intends to allow key update operation.
Particularities and Limitations
-
Configuration Variant(s): KEYM_CRYPTO_KEY_START_FINALIZE_FUNCTION_ENABLED == STD_ON
Call context
> TASK
> This function is Synchronous
> This function is Non-Reentrant
Table 4-15 KeyM_Start

4.2.7.3 KeyM_Update
Prototype
Std_ReturnType KeyM_Update (const uint8 *KeyNamePtr, uint32 KeyNameLength,
const uint8 *RequestDataPtr, uint32 RequestDataLength, uint8 *ResultDataPtr,
uint32 ResultDataMaxLength)
Parameter
KeyNamePtr [in] Pointer to an array that defines the name of the key to be updated.
KeyNameLength [in] Specifies the number of bytes in keyName. The value 0 indicates that no
keyName is provided within this function.
RequestDataPtr [in] Information that comes along with the request.
RequestDataLength [in] Length of data in the RequestData array.
ResultDataMaxLength [in] Max number of bytes available in ResultDataPtr.
ResultDataPtr [out] Pointer to a data buffer used by the function to store results.

© 2022 Vector Informatik GmbH Version 4.2.0 50

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

Return code
Std_ReturnType E_OK Service has been accepted and will be processed
internally. Results will be provided through a callback

E_NOT_OK Service not accepted due to an internal error.

E_BUSY Service could not be accepted because another
operation is already ongoing. Try next time.

KEYM_E_PARAMETER_MISMATCH Parameter does not match with

expected value.
KEYM_E_KEY_CERT_SIZE_MISMATCH Parameter size doesn't match.
Functional Description
Initiate key update.
This function is used to initiate the key generation or update process.
Particularities and Limitations
-
Call context
> TASK
> This function is not synchronous
> This function is Non-Reentrant
Table 4-16 KeyM_Update

4.2.7.4 KeyM_Finalize
Prototype
Std_ReturnType KeyM_Finalize (const uint8 *RequestDataPtr, uint32
RequestDataLength, uint8 *ResponseDataPtr, uint32 ResponseMaxDataLength)
Parameter
RequestDataPtr [in] Information that comes along with the request.
RequestDataLength [in] Length of data in the RequestData array.
ResponseMaxDataLength In: Max number of bytes available in ResponseData. Out: Actual number of
[in,out] bytes in ResponseData or left untouched if service runs in asynchronous
mode and function returns KEYM_E_OK.
ResponseDataPtr [out] Data returned by the function.
Return code
Std_ReturnType E_OK Service has been accepted and will be processed
internally. Results will be provided through a callback

E_NOT_OK Service not accepted due to an internal error.

KEYM_E_BUSY Validation cannot be performed yet. KeyM is currently
busy with other jobs.

© 2022 Vector Informatik GmbH Version 4.2.0 51

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

KEYM_E_PARAMETER_MISMATCH Parameter does not match with

expected value.
KEYM_E_KEY_CERT_SIZE_MISMATCH Parameter size doesn't match.
Functional Description
Finalize key update.
The function is used to finalize key update operations. It is typically used in conjunction with the
KeyM_Start operation and returns the key operation into the idle mode. Further key prepare or update
operations are not accepted until a new KeyM_Start operation has been initialized. This function is only
available if KeyMCryptoKeyStartFinalizeFunctionEnabled is set to TRUE. In addition, updated key material
will be persisted and set into valid state (calling Csm_KeySetValid).
Particularities and Limitations
-
Configuration Variant(s): KEYM_CRYPTO_KEY_START_FINALIZE_FUNCTION_ENABLED == STD_ON
Call context
> TASK
> This function is not synchronous
> This function is Non-Reentrant
Table 4-17 KeyM_Finalize

4.2.7.5 KeyM_Verify
Prototype
Std_ReturnType KeyM_Verify (const AUTOMATIC *KeyNamePtr, uint32 KeyNameLength,
const uint8 *RequestData, uint32 RequestDataLength, uint8 *ResponseData, uint32
*ResponseDataLength)
Parameter
KeyNamePtr [in] Points to an array that defines the name of the key to be updated.
KeyNameLength [in] Specifies the number of bytes in KeyNamePtr. The value 0 indicates that no
KeyNamePtr is provided within this function.
RequestData [in] Information that comes along with the request.
RequestDataLength [in] Length of data in the RequestData array
ResponseDataLength In: Max number of bytes available in ResponseData. Out: Actual number of
[in,out] bytes in ResponseData or left untouched if service runs in asynchronous
mode and function returns KEYM_E_PENDING.
ResponseData [out] Data returned by the function.
Return code
Std_ReturnType E_OK Operation was successfully performed. Result
information are available.

E_NOT_OK Operation not accepted due to an internal error.

KEYM_E_PENDING Operation runs in asynchronous mode, has been
accepted and will be processed internally. Results will be provided through
callback.

© 2022 Vector Informatik GmbH Version 4.2.0 52

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

KEYM_E_BUSY Validation cannot be performed yet. KeyM is currently

busy with other jobs (for asynchronous mode).
KEYM_E_PARAMETER_MISMATCH Parameter does not match with
expected value.
KEYM_E_KEY_CERT_SIZE_MISMATCH Parameter size doesn't match.
KEYM_E_KEY_CERT_INVALID Key operation cannot be performed because
the key name is invalid.
KEYM_E_KEY_CERT_EMPTY The key for this slot has not been set.
Functional Description
Verify key material.
The key server requests to verify the provided keys. The key manager performs operation on the assigned
job and returns the result to the key server who verifies if the results was provided with this key as
expected. This function is only available if KeyMCryptoKeyVerifyFunctionEnabled is set to TRUE.
Particularities and Limitations
-
Configuration Variant(s): KEYM_CRYPTO_KEY_VERIFY_FUNCTION_ENABLED == STD_ON
Call context
> TASK
> This function is not synchronous
> This function is Non-Reentrant
Table 4-18 KeyM_Verify

4.2.8 Certificate Sub-Module

4.2.8.1 KeyM_ServiceCertificate
Prototype
Std_ReturnType KeyM_ServiceCertificate (KeyM_ServiceCertificateType Service,
const uint8 *CertNamePtr, uint32 CertNameLength, const uint8 *RequestData,
uint32 RequestDataLength, uint8 *ResponseData, uint32 ResponseDataLength)
Parameter
Service [in] Provides the type of service the key manager has to perform.
CertNamePtr [in] Points to an array that defines the name of the certificate to be updated
CertNameLength [in] Specifies the number of bytes in CertNamePtr. The value 0 indicates that no
CertNamePtr is provided within this function.
RequestData [in] Information that comes along with the request.
RequestDataLength [in] Length of data in the RequestData array.
ResponseDataLength [in] Max number of bytes available in ResponseDataPtr.
ResponseData [out] Data returned by the function.
Return code
Std_ReturnType E_OK Service data operation successfully accepted.
E_NOT_OK Operation not accepted due to an internal error.

© 2022 Vector Informatik GmbH Version 4.2.0 53

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

KEYM_E_PARAMETER_MISMATCH Parameter does not match with

expected value.
KEYM_E_KEY_CERT_SIZE_MISMATCH Parameter size doesn't match.
KEYM_E_BUSY Service cannot be performed yet. KeyM is currently busy with
other jobs.
KEYM_E_KEY_CERT_EMPTY Certificate slot is empty.
KEYM_E_CERT_INVALID_CHAIN_OF_TRUST Invalid chain of trust.
Functional Description
Handle certificate operation requests.
The key server requests an operation from the key client. The type specified in the first parameter
KeyM_ServiceCertificateType. Certificate operation requests are operated through this function. This
function is only available if the configuration parameter KeyMServiceCertificateFunctionEnabled is set to
TRUE.
Particularities and Limitations
RequestData and ResponseData must be valid pointers to user-provided buffers. Their respective length
values must not exceed the actual buffer lengths.
The parsing of a certificate and the verifying of certificate elements is performed synchronously within this
function.
Configuration Variant(s): KEYM_SERVICE_CERTIFICATE_FUNCTION_ENABLED == STD_ON
Call context
> TASK
> This function is not synchronous
> This function is Non-Reentrant
Table 4-19 KeyM_ServiceCertificate

4.2.8.2 KeyM_SetCertificate
Prototype
Std_ReturnType KeyM_SetCertificate (KeyM_CertificateIdType CertId, const
KeyM_CertDataType *CertificateDataPtr)
Parameter
CertId [in] Holds the identifier of the certificate.
CertificateDataPtr [in] Pointer to a structure that provides the certificate data.
Return code
Std_ReturnType E_OK Certificate accepted.
E_NOT_OK Certificate could not be set.
KEYM_E_PARAMETER_MISMATCH Parameter does not match with
expected value.
KEYM_E_KEY_CERT_SIZE_MISMATCH Parameter size doesn't match.
Functional Description
Temporarily store certificate.

© 2022 Vector Informatik GmbH Version 4.2.0 54

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

This function provides the certificate data to the key management module to temporarily store the
certificate.
Particularities and Limitations
CertificateDataPtr->certData must be a valid, non-NULL pointer to a buffer of at least
CertificateDataPtr->certDataLength bytes.
The parsing of a certificate and the verifying of certificate elements is performed synchronously within this
function.
Call context
> TASK
> This function is Synchronous
> This function is Non-Reentrant
Table 4-20 KeyM_SetCertificate

4.2.8.3 KeyM_SetCertificateWithConstPtr
Prototype
Std_ReturnType KeyM_SetCertificateWithConstPtr (KeyM_CertificateIdType CertId,
const KeyM_ConstCertDataType *CertificateDataPtr)
Parameter
CertId [in] Holds the identifier of the certificate.
CertificateDataPtr [in] Pointer to a structure that provides the certificate data.
Return code
Std_ReturnType E_OK Certificate accepted.
E_NOT_OK Certificate could not be set.
KEYM_E_PARAMETER_MISMATCH Parameter does not match with
expected value.
KEYM_E_KEY_CERT_SIZE_MISMATCH Parameter size doesn't match.
Functional Description
Temporarily store certificate.
This function is identical to KeyM_SetCertificate, but it accepts a const pointer to certificate data.
Particularities and Limitations
CertificateDataPtr->certData must be a valid, non-NULL pointer to a buffer of at least
CertificateDataPtr->certDataLength bytes.
The parsing of a certificate and the verifying of certificate elements is performed synchronously within this
function.
Call context
> TASK
> This function is Synchronous
> This function is Non-Reentrant
Table 4-21 KeyM_SetCertificateWithConstPtr

© 2022 Vector Informatik GmbH Version 4.2.0 55

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

4.2.8.4 KeyM_GetCertificate
Prototype
Std_ReturnType KeyM_GetCertificate (KeyM_CertificateIdType CertId,
KeyM_CertDataType *CertificateDataPtr)
Parameter
CertId [in] Holds the identifier of the certificate.
CertificateDataPtr [in,out] Provides a pointer to a certificate data structure. The buffer located by the
pointer in the structure shall be provided by the caller of this function. The
length information indicates the maximum length of the buffer when the
function is called. If E_OK is returned, the length information indicates the
actual length of the certificate data in the buffer.
Return code
Std_ReturnType E_OK Certificate data available and provided.
E_NOT_OK Operation not accepted due to an internal error.
KEYM_E_PARAMETER_MISMATCH Certificate ID invalid.
KEYM_E_KEY_CERT_SIZE_MISMATCH Provided buffer for the certificate
too small.
KEYM_E_KEY_CERT_EMPTY No certificate data available, the certificate slot
is empty.
KEYM_E_KEY_CERT_READ_FAIL Certificate cannot be provided, access
denied.
Functional Description
Provide certificate.
This function provides the certificate data.
Particularities and Limitations
CertificateDataPtr->certData must be a valid, non-NULL pointer to a buffer of at least
CertificateDataPtr->certDataLength bytes.
Call context
> TASK
> This function is Synchronous
> This function is Non-Reentrant
Table 4-22 KeyM_GetCertificate

4.2.8.5 KeyM_VerifyCertificate
Prototype
Std_ReturnType KeyM_VerifyCertificate (KeyM_CertificateIdType CertId)
Parameter
CertId [in] Holds the identifier of the lower certificate in the chain.

© 2022 Vector Informatik GmbH Version 4.2.0 56

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

Return code
Std_ReturnType E_OK Certificate verification request accepted. Operation will be
performed in the background and response is given through a callback.
E_NOT_OK Operation not accepted due to an internal error.
KEYM_E_BUSY Validation cannot be performed yet. KeyM is
currently busy with other jobs.

KEYM_E_PARAMETER_MISMATCH Certificate ID invalid.

KEYM_E_KEY_CERT_EMPTY One of the certificate slots are empty.
KEYM_E_CERT_INVALID_CHAIN_OF_TRUST An upper certificate is not
valid.
Functional Description
Verify certificate.
This function verifies a certificate that was previously provided with KeyM_SetCertificate() against already
stored and provided certificates stored with other certificate IDs.
Particularities and Limitations
-
Call context
> TASK
> This function is not synchronous
> This function is Non-Reentrant
Table 4-23 KeyM_VerifyCertificate

4.2.8.6 KeyM_VerifyCertificates
Prototype
Std_ReturnType KeyM_VerifyCertificates (KeyM_CertificateIdType CertId,
KeyM_CertificateIdType CertUpperId)
Parameter
CertId [in] Holds the identifier of the lower certificate in the chain.
CertUpperId [in] Holds the identifier of the upper certificate in the chain.
Return code
Std_ReturnType E_OK Certificate verification request accepted. Operation will be
performed in the background and response is given through a callback.

E_NOT_OK Operation not accepted due to an internal error.

KEYM_E_BUSY Validation cannot be performed yet. KeyM is currently busy
with other jobs.

KEYM_E_PARAMETER_MISMATCH Certificate ID invalid.

KEYM_E_KEY_CERT_EMPTY One of the certificate slots are empty.

© 2022 Vector Informatik GmbH Version 4.2.0 57

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

KEYM_E_CERT_INVALID_CHAIN_OF_TRUST An upper certificate is not

valid.
Functional Description
Verify two certificates.
This function verifies two certificates that are stored and parsed internally against each other. The certificate
referenced with CertId was signed by the certificate referenced with certUpperId. Only these two certificates
are validated against each other.
Particularities and Limitations
-
Call context
> TASK
> This function is not synchronous
> This function is Non-Reentrant
Table 4-24 KeyM_VerifyCertificates

4.2.8.7 KeyM_VerifyCertificateChain
Prototype
Std_ReturnType KeyM_VerifyCertificateChain (KeyM_CertificateIdType CertId,
const KeyM_CertDataType certChainData[], uint8 NumberOfCertificates)
Parameter
CertId [in] Holds the identifier of the last certificate in the chain.
certChainData [in] This is a pointer to an array of certificates sorted according to the order in the
PKI.
NumberOfCertificates [in] Defines the number of certificates stored in the CertChainData array.
Return code
Std_ReturnType E_OK Certificate verification request accepted. Operation will be
performed in the background and response is given through a callback.

E_NOT_OK Operation not accepted due to an internal error.

KEYM_E_BUSY Validation cannot be performed yet. KeyM is
currently busy with other jobs.

KEYM_E_PARAMETER_MISMATCH Certificate ID invalid.

KEYM_E_KEY_CERT_EMPTY One of the certificate slots are empty.
KEYM_E_CERT_INVALID_CHAIN_OF_TRUST An upper certificate is not
valid.
Functional Description
Verify list of certificates.
This function performs a certificate verification against a list of certificates. It is a pre-requisite that the
certificate that shall be checked has already been written with KeyM_SetCertificate() and that the root
certificate is either in the list or is already assigned to one of the other certificates.

© 2022 Vector Informatik GmbH Version 4.2.0 58

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

Particularities and Limitations

NumberOfCertificates must be valid with respect to the configured certificate chain depth.
certChainData must reference at least NumberOfCertificates many elements.
For all its entries e, e->certData must be a valid, non-NULL pointer to a buffer of at least
e->certDataLength bytes.
Call context
> TASK
> This function is not synchronous
> This function is Non-Reentrant
Table 4-25 KeyM_VerifyCertificateChain

4.2.8.8 KeyM_VerifyCertificateChainWithConstPtr
Prototype
Std_ReturnType KeyM_VerifyCertificateChainWithConstPtr (KeyM_CertificateIdType
CertId, const KeyM_ConstCertDataType certChainData[], uint8
NumberOfCertificates)
Parameter
CertId [in] Holds the identifier of the last certificate in the chain.
certChainData [in] This is a pointer to an array of certificates sorted according to the order in the
PKI.
NumberOfCertificates [in] Defines the number of certificates stored in the CertChainData array.
Return code
Std_ReturnType E_OK Certificate verification request accepted. Operation will be
performed in the background and response is given through a callback.

E_NOT_OK Operation not accepted due to an internal error.

KEYM_E_BUSY Validation cannot be performed yet. KeyM is
currently busy with other jobs.

KEYM_E_PARAMETER_MISMATCH Certificate ID invalid.

KEYM_E_KEY_CERT_EMPTY One of the certificate slots are empty.
KEYM_E_CERT_INVALID_CHAIN_OF_TRUST An upper certificate is not
valid.
Functional Description
Verify list of certificates.
This function is identical to KeyM_VerifyCertificateChain, but it accepts a const pointers to certificate data.
Particularities and Limitations
NumberOfCertificates must be valid in respect to the configured certificate chain depth.
certChainData must reference at least NumberOfCertificates many elements.
For all its entries e, e->certData must be a valid, non-NULL pointer to a buffer of at least
e->certDataLength bytes.

© 2022 Vector Informatik GmbH Version 4.2.0 59

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

Call context
> TASK
> This function is not synchronous
> This function is Non-Reentrant
Table 4-26 KeyM_VerifyCertificateChainWithConstPtr

4.2.8.9 KeyM_CertElementGet
Prototype
Std_ReturnType KeyM_CertElementGet (KeyM_CertificateIdType CertId,
KeyM_CertElementIdType CertElementId, uint8 *CertElementData, uint32
*CertElementDataLength)
Parameter
CertId [in] Holds the identifier of the last certificate in the chain.
CertElementId [in] Specifies the ElementId where the data shall be read from.
CertElementDataLength In: Pointer to a value that contains the maximum data length of the
[in,out] CertElementData buffer. Out: The data length will be overwritten with the
actual length of data placed to the buffer if the function returns E_OK.
Otherwise, the it will be overwritten with the value zero.
CertElementData [out] Pointer to a data buffer allocated by the caller of this function. If available, the
function returns E_OK and copies the data into this buffer.
Return code
Std_ReturnType E_OK Element found and data provided in the buffer.
E_NOT_OK Element data not found.
KEYM_E_PARAMETER_MISMATCH Certificate ID or certificate element ID
invalid.
KEYM_E_KEY_CERT_SIZE_MISMATCH Provided buffer for the certificate
element too small.
KEYM_E_KEY_CERT_EMPTY No certificate data available, the certificate slot
is empty.
KEYM_E_KEY_CERT_INVALID The certificate is not valid or has not yet been
verified.
Functional Description
Provide certificate element.
Provides the content of a specific certificate element. The certificate configuration defines how the
certificate submodule can find the element, e.g. by providing the object identifier (OID). This function is
used to retrieve this information if only one element is assigned to the respective OID.
Particularities and Limitations
-
Call context
> TASK
> This function is Synchronous

© 2022 Vector Informatik GmbH Version 4.2.0 60

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

> This function is Non-Reentrant

Table 4-27 KeyM_CertElementGet

4.2.8.10 KeyM_CertElementGetFirst
Prototype
Std_ReturnType KeyM_CertElementGetFirst (KeyM_CertificateIdType CertId,
KeyM_CertElementIdType CertElementId, KeyM_CertElementIteratorType
*CertElementIterator, uint8 *CertElementData, uint32 *CertElementDataLength)
Parameter
CertId [in] Holds the identifier of the last certificate in the chain.
CertElementId [in] Specifies the ElementId where the data shall be read from.
CertElementIterator [in,out] Pointer to a structure that is allocated and maintained by the caller. It shall not
be destroyed or altered by the application until all elements have been
retrieved through KeyM_CertElementGetNext().
CertElementDataLength In: Pointer to a value that contains the maximum data length of the
[in,out] CertElementData buffer. Out: The data length will be overwritten with the
actual length of data placed to the buffer if the function returns E_OK.
CertElementData [out] Pointer to a data buffer allocated by the caller of this function. If available, the
function returns E_OK and copies the data into this buffer.
Return code
Std_ReturnType E_OK Element found and data provided in the buffer.
The certElementIterator has been initialized accordingly.

E_NOT_OK Element data not found.

KEYM_E_PARAMETER_MISMATCH Certificate ID or certificate element ID
invalid.
KEYM_E_KEY_CERT_SIZE_MISMATCH Provided buffer for the certificate
element too small.
KEYM_E_KEY_CERT_EMPTY No certificate data available, the certificate slot
is empty.
KEYM_E_KEY_CERT_INVALID Certificate is not valid or not verified
successfully or referenced certificate element is not iterable.
Functional Description
Provide first part of data from certificate element.
This function is used to initialize the interative extraction of a certificate data element. It always retrieves the
top element from the configured certificate element and initializes the structure KeyM_CertElementIterator
so that consecutive data from this element can be read with KeyM_CertElementGetNext().
Particularities and Limitations
-
Call context
> TASK
> This function is Synchronous

© 2022 Vector Informatik GmbH Version 4.2.0 61

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

> This function is Non-Reentrant

Table 4-28 KeyM_CertElementGetFirst

4.2.8.11 KeyM_CertElementGetNext
Prototype
Std_ReturnType KeyM_CertElementGetNext (KeyM_CertElementIteratorType
*CertElementIterator, uint8 *CertElementData, uint32 *CertElementDataLength)
Parameter
CertElementIterator [in,out] Pointer to a structure that is allocated by the caller and used by the function. It
shall not be destroyed or altered by the application until all elements have
been read from the list.
CertElementDataLength In: Pointer to a value that contains the maximum length of the
[in,out] CertElementData buffer. Out: The data length will be overwritten with the
actual length of data placed to the buffer if the function returns E_OK.
CertElementData [out] Pointer to a data buffer allocated by the caller of this function. If available, the
function returns E_OK and copies the data into this buffer.
Return code
Std_ReturnType E_OK Element found and data provided in the buffer.
The certElementIterator has been initialized accordingly.

E_NOT_OK Element data not found.

KEYM_E_PARAMETER_MISMATCH Certificate ID or certificate element ID
invalid.
KEYM_E_KEY_CERT_SIZE_MISMATCH Provided buffer for the certificate
element too small.
KEYM_E_KEY_CERT_EMPTY No certificate data available, the certificate slot
is empty.
KEYM_E_KEY_CERT_INVALID Certificate is not valid or not verified
successfully
Functional Description
Provide further data from certificate element.
This function provides further data from a certificate element, e.g. if a set of data is located in one certificate
element that shall be read one after another. This function can only be called if the function
KeyM_CertElementGetFirst() has been called once before. It has to be assured, that the installed certificate
data remains consistent between calls of KeyM_CertElementGetFirst() and KeyM_CertElementGetNext as
well as several calls of KeyM_CertElementGetNext().
Particularities and Limitations
The passed CertElementIterator must be an object that was previously retrieved via
KeyM_CertElementGetFirst().
Call context
> TASK
> This function is Synchronous
> This function is Non-Reentrant

© 2022 Vector Informatik GmbH Version 4.2.0 62

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

Table 4-29 KeyM_CertElementGetNext

4.2.8.12 KeyM_CertGetStatus
Prototype
Std_ReturnType KeyM_CertGetStatus (KeyM_CertificateIdType CertId,
KeyM_CertificateStatusType *Status)
Parameter
CertId [in] Holds the identifier of the certificate.
Status [out] Provides the status of the certificate.
Return code
Std_ReturnType E_OK Certificate status available and provided.
E_NOT_OK Status provisioning currently not possible.
KEYM_E_PARAMETER_MISMATCH Certificate ID invalid.
Functional Description
Provides certificate status.
This function provides the status of a certificate.
Particularities and Limitations
-
Call context
> TASK
> This function is Synchronous
> This function is Reentrant
Table 4-30 KeyM_CertGetStatus

4.2.8.13 KeyM_Cert_SearchCert
Prototype
boolean KeyM_Cert_SearchCert (const uint8 *certNamePtr, uint32 certNameLength,
KeyM_CertificateIdType *certId)
Parameter
certNamePtr [in] Pointer to a buffer that defines the name of the certificate.
certNameLength [in] Name buffer length.
certId [out] Holds the identifier of the certificate.
Return code
boolean TRUE Certificate with given name is available.
FALSE Certificate with given name is not available.

© 2022 Vector Informatik GmbH Version 4.2.0 63

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

Functional Description
Search name of referenced certificate in configuration.
Particularities and Limitations
-
Call context
> TASK
> This function is Synchronous
> This function is Non-Reentrant
Table 4-31 KeyM_Cert_SearchCert

4.2.8.14 KeyM_ CertificateElementGetByIndex

Prototype
Std_ReturnType KeyM_CertificateElementGetByIndex (KeyM_CertificateIdType
CertId, KeyM_CertElementIdType CertElementId, uint16 Index, uint8
*CertElementData, uint32 *CertDataLength)
Parameter
CertId [in] Holds the identifier of the certificate.
CertElementId [in] Holds the identifier of the iterable certificate element.
Index [in] This is the index to the respective element in the list of iterable elements.
CertElementData [out] Pointer to a data buffer for the iterable certificate element.
CertDataLength [in,out] In: Pointer to a value that contains the maximum data length of the
CertElementData buffer.
Out: The data length will be overwritten with the actual length of data placed to
the buffer if the function returns E_OK.
Return code
Std_ReturnType E_OK Element found and data provided in the buffer.
E_NOT_OK Element data not found.
KEYM_E_PARAMETER_MISMATCH Certificate ID or certificate element ID
invalid.
KEYM_E_KEY_CERT_SIZE_MISMATCH Provided buffer for the certificate
element too small.
KEYM_E_KEY_CERT_EMPTY No certificate data available, the certificate slot
is empty.
KEYM_E_KEY_CERT_INVALID Certificate is not valid or not verified
successfully
Functional Description
Provides data from an iterable certificate element.
-
Particularities and Limitations
-

© 2022 Vector Informatik GmbH Version 4.2.0 64

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

Call context
> TASK
> This function is Synchronous
> This function is Non-Reentrant
Table 4-32 KeyM_CertificateElementGetByIndex

4.2.8.15 KeyM_CertificateElementGetCount
Prototype
Std_ReturnType KeyM_CertificateElementGetCount (KeyM_CertificateIdType CertId,
KeyM_CertElementIdType CertElementId, uint16 *Count)
Parameter
CertId [in] Holds the identifier of the certificate.
CertElementId [in] Holds the identifier of the certificate element.
Count [out] Total number of iterable certificate elements.
Return code
Std_ReturnType E_OK Element found and number of element items provided.
E_NOT_OK Element data not found.
KEYM_E_PARAMETER_MISMATCH Certificate ID or certificate element ID
invalid.
KEYM_E_KEY_CERT_SIZE_MISMATCH Provided buffer for the certificate
element too small.
KEYM_E_KEY_CERT_EMPTY No certificate data available, the certificate slot
is empty.
KEYM_E_KEY_CERT_INVALID Certificate is not valid or not verified
successfully.
Functional Description
Provides the amount of iterable elements.
-
Particularities and Limitations
-
Call context
> TASK
> This function is Synchronous
> This function is Non-Reentrant
Table 4-33 KeyM_CertificateElementGetCount

© 2022 Vector Informatik GmbH Version 4.2.0 65

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

4.2.8.16 KeyM_InitCSR
Prototype
Std_ReturnType KeyM_InitCSR (const uint8 *CertNamePtr, uint32 CertNameLength,
const KeyM_CSRInfoType *CsrInfo, uint8 numOfReqObjects, uint8 *ResponseData,
uint32 *ResponseDataLength)
Parameter
CertNamePtr [in] Points to an array that defines the name of the certificate.
CertNameLength [in] Specifies the number of bytes in CertNamePtr.
CsrInfo [in] Points to an array of request data objects.
numOfReqObjects [in] Total number of available request objects.
ResponseData [out] Data returned by the function.
ResponseDataLength In: Max number of bytes available in ResponseData. Out: Actual number.
[in,out]
Return code
Std_ReturnType E_OK CertificationRequestInfo data structure was generated successfully.
E_NOT_OK Due to internal error, the CertificationRequestInfo data structure
could not be generated.
KEYM_E_PARAMETER_MISMATCH Parameter does not match with
expected value.
KEYM_E_KEY_CERT_SIZE_MISMATCH Parameter size doesn't match.
Functional Description
Initializes request data for certificate signing request.
-
Particularities and Limitations
CsrInfo must reference at least numOfReqObject many elements.
Call context
> TASK
> This function is Synchronous
> This function is Reentrant
Table 4-34 KeyM_InitCSR

4.2.8.17 KeyM_ServiceCertificateById
Prototype
Std_ReturnType KeyM_ServiceCertificateById (KeyM_ServiceCertificateType
Service, KeyM_CertificateIdType CertId, const uint8 *RequestData, uint32
RequestDataLength, uint8 *ResponseData, uint32 ResponseDataLength)
Parameter
Service [in] Provides the type of service the key manager has to perform.
CertId [in] Holds the identifier of the certificate.
RequestData [in] Information that comes along with the request.

© 2022 Vector Informatik GmbH Version 4.2.0 66

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

RequestDataLength [in] Length of data in the RequestData array.

ResponseDataLength [in] Max number of bytes available in ResponseDataPtr.
ResponseData [out] Data returned by the function.
Return code
Std_ReturnType E_OK Service data operation successfully accepted.
E_NOT_OK Operation not accepted due to an internal error.
KEYM_E_PARAMETER_MISMATCH Parameter does not match with
expected value.
KEYM_E_KEY_CERT_SIZE_MISMATCH Parameter size doesn't match.
KEYM_E_BUSY Service cannot be performed yet. KeyM is currently busy with
other jobs.
KEYM_E_KEY_CERT_EMPTY Certificate slot is empty.
KEYM_E_CERT_INVALID_CHAIN_OF_TRUST Invalid chain of trust.
Functional Description
Handle certificate operation requests.
The key server requests an operation from the key client. The type specified in the first parameter
KeyM_ServiceCertificateType. Certificate operation requests are operated through this function. This
function is only available if the configuration parameter KeyMServiceCertificateFunctionEnabled is set to
TRUE.
Particularities and Limitations
RequestData and ResponseData must be valid pointers to user-provided buffers. Their respective length
values must not exceed the actual buffer lengths.
Configuration Variant(s): KEYM_SERVICE_CERTIFICATE_FUNCTION_ENABLED == STD_ON
Call context
> TASK
> This function is not synchronous
> This function is Non-Reentrant
Table 4-35 KeyM_ServiceCertificateById

Note
The KeyM provides an API with the suffix
• RteAdpt in KeyM_ServiceCertificateByIdRteAdpt

This API is used only by RTE/SWCs. This API function wraps the existing API function
KeyM_ServiceCertificateById and does not add functionality.

© 2022 Vector Informatik GmbH Version 4.2.0 67

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

4.2.8.18 KeyM_SetCertificateInGroup
Prototype
Std_ReturnType KeyM_SetCertificateInGroup (KeyM_CertificateGroupIdType GroupId,
const uint8 *RequestData, uint32 RequestDataLength, KeyM_CertificateIdType
*CertId)
Parameter
GroupId [in] Holds the identifier of the certificate group.
RequestData [in] Pointer to the certificate data.
RequestDataLength [in] Holds the length of the certificate data.
CertId [out] Holds the certificate identifier of the slot where data has been installed.
Return code
Std_ReturnType E_OK Certificate accepted.
E_NOT_OK Certificate could not be set.
KEYM_E_PARAMETER_MISMATCH Parameter does not match with
expected value.
KEYM_E_KEY_CERT_SIZE_MISMATCH Parameter size doesn't match.
KEYM_E_BUSY Service cannot be performed yet. KeyM is currently busy with
other jobs.
KEYM_E_KEY_CERT_EMPTY Certificate slot is empty.
KEYM_E_CERT_INVALID_CHAIN_OF_TRUST Invalid chain of trust.
Functional Description
Set group certificate.
This function sets certificate data in a certicate group.
Particularities and Limitations
This function call can trigger a callback notification if an optional service certificate callback
<KeyM_ServiceCertificateCallbackNotification> is configured for the corresponding dynamic certificate slot.
The parsing of a certificate and the verifying of certificate elements is performed synchronously within this
function.
Call context
> TASK
> This function is Synchronous
> This function is Non-Reentrant
Table 4-36 KeyM_SetCertificateInGroup

4.2.8.19 KeyM_GetGroupCertId
Prototype
Std_ReturnType KeyM_GetGroupCertId (KeyM_CertificateGroupIdType GroupId, const
uint8 *SubjectCommonNameData, uint32 SubjectCommonNameDataLength,
KeyM_CertificateIdType *CertId)

© 2022 Vector Informatik GmbH Version 4.2.0 68

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

Parameter
GroupId [in] Holds the identifier of the certificate group.
SubjectCommonNameData [in] Pointer to the subject common name data.
SubjectCommonNameDataLength Holds the length of the subject common name data.
[in]
CertId [out] Holds the certificate identifier of the slot where data has been installed.
Return code
Std_ReturnType E_OK Certificate identifier was successfully retrieved.
E_NOT_OK Referenced subject common name was not found within
the group.
KEYM_E_PARAMETER_MISMATCH Parameter does not match with
expected value.
Functional Description
Get certificate identifier for previously set group certificates.
-
Particularities and Limitations
-
Call context
> TASK
> This function is Synchronous
> This function is Reentrant
Table 4-37 KeyM_GetGroupCertId

4.2.8.20 KeyM_VerifyGroup
Prototype
Std_ReturnType KeyM_VerifyGroup (KeyM_CertificateGroupIdType GroupId)
Parameter
GroupId [in] Holds the identifier of the certificate group.
Return code
Std_ReturnType E_OK The verification of the certificate group was triggered successfully.
E_NOT_OK Certificate data is unavailable and no verification could be
triggered.
Functional Description
Verify previously set group certificates.
-
Particularities and Limitations
-
Call context

© 2022 Vector Informatik GmbH Version 4.2.0 69

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

> TASK
> This function is Non-Reentrant
Table 4-38 KeyM_VerifyGroup

4.2.8.21 KeyM_SetCRE
Prototype
Std_ReturnType KeyM_SetCRE (const uint8 *IssuerNameData, uint16
IssuerNameDataLength, const uint8 *SerialNumberData, uint16
SerialNumberDataLength)
Parameter
IssuerNameData [in] Points to an array that defines the issuer common name of the revoked
certificate.
IssuerNameDataLength [in] Length of issuer common name data.
SerialNumberData [in] Points to an array that defines the serial number of the revoked certificate.
SerialNumberDataLength Length of serial number data.
[in]
Return code
Std_ReturnType E_OK Certificate revocation entry was appended successfully.
E_NOT_OK Due to internal error, the certificate revocation entry could not be
appended.
KEYM_E_KEY_CERT_SIZE_MISMATCH Parameter size doesn't match.
Functional Description
Set a certificate revocation entry.
Particularities and Limitations
Configuration Variant(s): KEYM_CRE == STD_ON
Call context
> TASK
> This function is Synchronous
> This function is Non-Reentrant
Table 4-39 KeyM_SetCRE

4.2.8.22 KeyM_CertStructureGet
Prototype
Std_ReturnType KeyM_CertStructureGet (KeyM_CertificateIdType CertId,
KeyM_CertificateStructureType CertStructure, uint8 *CertStructureData, uint32
*CertStructureDataLength)
Parameter
CertId [in] Holds the identifier of the certificate.

© 2022 Vector Informatik GmbH Version 4.2.0 70

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

CertStructure [in] Holds the certificate structure type.

CertStructureData [out] Pointer to a valid buffer which will hold the data returned by the function.
CertStructureDataLength In: Max number of bytes available in CertStructureData. Out: Actual number.
[in,out]
Return code
Std_ReturnType E_OK Certificate structure was retrieved successfully.
E_NOT_OK Due to internal error, the certificate structure could not be
retrieved.
KEYM_E_PARAMETER_MISMATCH Parameter does not match with
expected value.
KEYM_E_KEY_CERT_SIZE_MISMATCH Parameter size doesn't match.
KEYM_E_KEY_CERT_INVALID The certificate is not valid or has not yet been
verified.
Functional Description
Retrieve certificate structure.
-
Particularities and Limitations
-
Call context
> TASK
> This function is Synchronous
> This function is Reentrant
Table 4-40 KeyM_CertStructureGet

4.2.8.23 KeyM_GetIssuerCertId
Prototype
Std_ReturnType KeyM_GetIssuerCertId (KeyM_CertificateIdType CertId,
KeyM_CertificateIdType *IssuerCertId)
Parameter
CertId [in] Holds the certificate identifier.
IssuerCertId [out] Holds the certificate identifier of the issuer this function returns.
Return code
Std_ReturnType E_OK Issuer's certicate identifier was retrieved successfully.
E_NOT_OK Due to internal error, the issuer's certificate identifier could not be
retrieved.
Functional Description
Get certificate identifier of issuer in upper hierarchy.
-

© 2022 Vector Informatik GmbH Version 4.2.0 71

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

Particularities and Limitations

-
Call context
> ANY
> This function is Synchronous
> This function is Reentrant
Table 4-41 KeyM_GetIssuerCertId

4.2.8.24 KeyM_GetCertHash
Prototype
Std_ReturnType KeyM_GetCertHash (KeyM_CertificateIdType CertId, uint8
*HashData, uint32 *HashDataLength)
Parameter
CertId [in] Holds the identifier of the certificate.
HashData [out] Pointer to a valid buffer which will hold the data returned by the function.
HashDataLength [in,out] In: Max number of bytes available in HashData.
Out: Actual number.
Return code
Std_ReturnType E_OK Certificate hash was retrieved successfully.
E_NOT_OK Due to internal error, the certificate hash could not be retrieved.
KEYM_E_BUSY Service cannot be performed yet. Certificate is locked by
another service request.
KEYM_E_KEY_CERT_SIZE_MISMATCH Parameter size doesn't match.
KEYM_E_PARAMETER_MISMATCH Parameter size doesn't match.
KEYM_E_KEY_CERT_INVALID Certificate is not valid.
KEYM_E_KEY_CERT_EMPTY Certificate slot is empty.
Functional Description
Retrieve precomputed hash over certificate data.
-
Particularities and Limitations
The current implementation does not support a certificate locking mechanism. Therefore the
return code KEYM_E_BUSY is added only for future compliance. If a certificate update fails
and the persisted certificate data is re-loaded, the hash needs to be computed again. It is possible
that this function returns the hash of the invalid, updated certificate data if the hash computation
has not finished yet. To ensure the validity of the hash, check the status of the updated
certificate in advance. If after an update, the status is KEYM_CERTIFICATE_VALID, the hash retrieved
by this function is valid.
-
Call context

© 2022 Vector Informatik GmbH Version 4.2.0 72

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

> TASK
> This function is Synchronous
> This function is Reentrant
Table 4-42 KeyM_GetCertHash

4.2.8.25 KeyM_CsrElementSet
Prototype
Std_ReturnType KeyM_CsrElementSet (KeyM_CertificateIdType CertId,
KeyM_CertElementIdType CertElementId, KeyM_CsrEncodingType EncodingType, const
uint8 *ElementData, uint32 ElementDataLength)
Parameter
CertId [in] Holds the identifier of the certificate.
ElementId [in] Holds the identifier of the certificate element.
EncodingType [in] Holds the encoding type of the certificate element.
ElementData [in] Points to an array of element data.
ElementDataLength [in] Max number of bytes available in ElementData.
Return code
Std_ReturnType E_OK CSR element was set successfully.
E_NOT_OK Due to internal error, the CSR element could not be set.
KEYM_E_PARAMETER_MISMATCH Parameter does not match with
expected value.
KEYM_E_KEY_CERT_SIZE_MISMATCH Parameter size doesn't match.
Functional Description
Set certificate signing request element data.
Particularities and Limitations
-
Call context
> TASK
> This function is Synchronous
> This function is Reentrant
Table 4-43 KeyM_CsrElementSet

4.2.8.26 KeyM_DispatchRemoteJob
Prototype
Std_ReturnType KeyM_DispatchRemoteJob (const Crypto_JobType *job)

© 2022 Vector Informatik GmbH Version 4.2.0 73

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

Parameter
job [in] Pointer to the configuration of the job which is owned by the API user.
Contains structures with job and primitive relevant information but also
pointers to result buffers.
Return code
Std_ReturnType E_OK Remote service request was dispatched and processed successfully.
E_NOT_OK Due to an internal error, the remote service request could not be
dispatched or processed.
KEYM_E_PARAMETER_MISMATCH Parameter does not match with
expected value.
KEYM_E_KEY_CERT_SIZE_MISMATCH Parameter size doesn't match.
KEYM_E_BUSY Service cannot be performed yet. KeyM is currently busy with
other jobs.
KEYM_E_KEY_CERT_EMPTY Certificate slot is empty.
KEYM_E_CERT_INVALID_CHAIN_OF_TRUST Invalid chain of trust.
Functional Description
Dispatches remote Crypto job to KeyM service.
The dispatching functionality shall be only used by a custom Crypto driver on remote side to enable remote
service handling.
Particularities and Limitations
job->jobPrimitiveInputOutput->{input | secondaryInput | tertiaryInput | output}Ptr must be non-NULL, valid
pointers and their respective length fields must be valid.
Call context
> TASK
> This function is Synchronous
> This function is Reentrant
Table 4-44 KeyM_DispatchRemoteJob

4.2.8.27 KeyM_DispatchRemoteKeyElementSet
Prototype
Std_ReturnType KeyM_DispatchRemoteKeyElementSet (uint32 cryptoKeyId, uint32
keyElementId, const uint8 *keyPtr, uint32 keyLength)
Parameter
cryptoKeyId [in] Holds the identifier of the key whose key element shall be set.
keyElementId [in] Holds the identifier of the key element which shall be set.
keyPtr [in] Holds the pointer to the user-owned key data which shall be set as key
element.
keyLength [in] Contains the length of the key element in bytes.
Return code
Std_ReturnType E_OK Remote service request was dispatched and processed successfully.

© 2022 Vector Informatik GmbH Version 4.2.0 74

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

E_NOT_OK Due to an internal error, the remote service request could not be
dispatched or processed.
KEYM_E_PARAMETER_MISMATCH Parameter does not match with
expected value.
KEYM_E_KEY_CERT_SIZE_MISMATCH Parameter size doesn't match.
Functional Description
Dispatches remote set key element request to KeyM service.
The dispatching functionality shall be only used by a custom Crypto driver on remote side to enable remote
service handling.
Particularities and Limitations
The length of the buffer passed as keyPtr must be at least keyLength bytes.
Call context
> TASK
> This function is Synchronous
> This function is Reentrant
Table 4-45 KeyM_DispatchRemoteKeyElementSet

4.2.8.28 KeyM_DispatchRemoteKeyElementGet
Prototype
Std_ReturnType KeyM_DispatchRemoteKeyElementGet (uint32 cryptoKeyId, uint32
keyElementId, uint8 *keyPtr, uint32 *keyLengthPtr)
Parameter
cryptoKeyId [in] Holds the identifier of the key whose key element shall be set.
keyElementId [in] Holds the identifier of the key element which shall be set.
keyPtr [out] Holds the pointer to the user-owned memory location where the key shall be
copied to.
keyLengthPtr [in,out] Holds a pointer to the memory location in which the output buffer length in
bytes is stored. On calling this function, this parameter shall contain the buffer
length in bytes of the keyPtr. When the request has finished, the actual size of
the written input bytes shall be stored.
Return code
Std_ReturnType E_OK Remote service request was dispatched and processed successfully.
E_NOT_OK Due to an internal error, the remote service request could not be
dispatched or processed.
KEYM_E_PARAMETER_MISMATCH Certificate ID invalid.
KEYM_E_KEY_CERT_SIZE_MISMATCH Provided buffer for the certificate too
small.
KEYM_E_KEY_CERT_EMPTY No certificate data available, the certificate slot
is empty.
KEYM_E_KEY_CERT_READ_FAIL Certificate cannot be provided, access
denied.

© 2022 Vector Informatik GmbH Version 4.2.0 75

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

Functional Description
Dispatches remote get key element request to KeyM service.
The dispatching functionality shall be only used by a custom Crypto driver on remote side to enable remote
service handling.
Particularities and Limitations
The length of the buffer passed as keyPtr must be at least *keyLengthPtr bytes.
Call context
> TASK
> This function is Synchronous
> This function is Non-Reentrant
Table 4-46 KeyM_DispatchRemoteKeyElementGet

4.2.8.29 KeyM_CertElementGetByStructureType
Prototype
Std_ReturnType KeyM_CertElementGetByStructureType (const uint8 *CertData,
uint32 CertDataLength, KeyM_CertificateStructureType CertStructure, uint8
*CertElementData, uint32 *CertElementDataLength)
Parameter
CertData [in] Pointer to the certificate data.
CertDataLength [in] Holds the length of the certificate data.
CertStructure [in] Holds the certificate structure type.
CertElementData [out] Pointer to a valid buffer which will hold the data returned by the function.
CertElementDataLength In: Max number of bytes available in CertElementData. Out: Actual number.
[in,out]
Return code
Std_ReturnType E_OK Element found and data provided in the buffer.
E_NOT_OK Element data not found.
KEYM_E_PARAMETER_MISMATCH Certificate structure type is invalid.
KEYM_E_KEY_CERT_SIZE_MISMATCH Provided buffer for the certificate
element too small.
KEYM_E_KEY_CERT_EMPTY No certificate data available.
Functional Description
Provide certificate element by certificate structure type.
Particularities and Limitations
-

Call context
> TASK
> This function is Synchronous
> This function is Non-Reentrant

© 2022 Vector Informatik GmbH Version 4.2.0 76

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

Table 4-47 KeyM_CertElementGetByStructureType

4.3 Services used by KeyM

In the following table, services provided by other components which are used by the KeyM
are listed. For details about prototype and functionality refer to the documentation of the
providing component.
Component API
DET Det_ReportError
CSM Csm_SignatureVerify
Csm_KeyElementSet
Csm_KeySetValid
StbM StbM_GetCurrentTime
NvM NvM_ReadBlock
NvM_WriteBlock
Table 4-48 Services used by the KeyM

In order to ensure proper verification, the time reference provided by StbM using the service
StbM_GetCurrentTime must be trusted.

4.4 Callback Functions

This chapter describes the callback functions that are implemented by the KeyM and can be
invoked by other modules. The prototypes of the callback functions are provided in the
header file KeyM_Cbk.h by the KeyM.

4.4.1 KeyM_CallbackNotificationSignature
Prototype
void KeyM_CallbackNotificationSignature (Crypto_JobType *job, Std_ReturnType
result)
Parameter
job [in] Contains the CSM job.
result [in] Contains the result of the cryptographic operation.
Return code
void none
Functional Description
Callback Notification for finished signature verify CSM job.
Notifies the KeyM that the signature verify job has finished. This function is used by the CSM.

© 2022 Vector Informatik GmbH Version 4.2.0 77

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

Particularities and Limitations

job has to be a job object handle and a valid pointer.
Configuration Variant(s): KEYM_CSM_ASYNC_SIGNATURE_VERIFY == STD_ON
Call context
> TASK
> This function is Synchronous
> This function is Non-Reentrant
Table 4-49 KeyM_CallbackNotificationSignature

4.4.2 KeyM_NvBlock_ReadFrom_KeyMCertificate_<NvBlock>
Prototype
Std_ReturnType KeyM_NvBlock_ReadFrom_KeyMCertificate_<NvBlock> (const void
*NvMBuffer)
Parameter
NvMBuffer [in] RAM mirror where Ram block data can be read from.
Return code
E_OK Data was copied from buffer.
E_NOT_OK Data was not copied.
Functional Description
Read from Block callback routine.
Block specific callback routine which is called by NvM in order to let the KeyM copy data from NvM RAM
mirror to RAM block.
Particularities and Limitations
certIdx needs to be valid.
NvM storage needs to be preconfigured for referenced certificate.
Call context
> TASK
> This function is Synchronous
> This function is Non-Reentrant
Table 4-50 KeyM_NvBlock_ReadFrom_KeyMCertificate_<NvBlock>

4.4.3 KeyM_NvBlock_WriteTo_KeyMCertificate_<NvBlock>
Prototype
Std_ReturnType KeyM_NvBlock_ WriteToBlock_KeyMCertificate_<NvBlock> (const void
*NvMBuffer)
Parameter
NvMBuffer [in] RAM mirror where Ram block data can be read from.

© 2022 Vector Informatik GmbH Version 4.2.0 78

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

Return code
E_OK Data was copied from buffer.
E_NOT_OK Data was not copied.
Functional Description
Write to Block callback routine.
Block specific callback routine which is called by NvM in order to let the KeyM copy data from RAM block to
NvM RAM mirror.
Particularities and Limitations
certIdx needs to be valid.
NvM storage needs to be preconfigured for referenced certificate.
The buffer referenced by NvMBuffer must provide at least
KeyM_GetLengthOfNvmBlock(KeyM_GetNvmBlockIdxOfCertificate(certIdx)) byte.
Call context
> TASK
> This function is Synchronous
> This function is Non-Reentrant
Table 4-51 KeyM_NvBlock_WriteToBlock_KeyMCertificate_<NvBlock>

4.4.4 KeyM_NvBlock_Init_KeyMCertificate_<NvBlock>
Prototype
Std_ReturnType KeyM_NvBlock_Init_KeyMCertificate_<NvBlock>(void)
Parameter
void none
Return code
E_OK Data initialized.
E_NOT_OK Any error occurred.
Functional Description
Init Block callback routine.
Block specific callback routine which is called by NvM in order to let the KeyM copy default data to a RAM
block.
Particularities and Limitations
certIdx needs to be valid.
NvM storage needs to be preconfigured for referenced certificate.
Call context
> TASK
> This function is Synchronous
> This function is Non-Reentrant
Table 4-52 KeyM_NvBlock_Init_KeyMCertificate_<NvBlock>

© 2022 Vector Informatik GmbH Version 4.2.0 79

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

4.4.5 KeyM_NvBlock_Callback_KeyMCertificate_<NvBlock>
Prototype
Std_ReturnType KeyM_NvBlock_Callback_KeyMCertificate_<NvBlock> (const void
*NvMBuffer)
Parameter
NvM_ServiceIdType [in] The service identifier of the completed request.
JobResult[in] Result of the single block job.
Return code
E_OK Callback function has been processed successfully.
E_NOT_OK Callback function has not been processed successfully.
Functional Description
Request finished Block callback routine.
Block specific callback routine which is called by NvM in order to notify the KeyM that an asynchronous
single block request has been finished.
Particularities and Limitations
certIdx needs to be valid.
NvM storage needs to be preconfigured for referenced certificate.
Call context
> TASK
> This function is Synchronous
> This function is Non-Reentrant
Table 4-53 KeyM_NvBlock_Callback_KeyMCertificate_<NvBlock>

4.4.6 KeyM_NvBlock_ReadFrom_CRE
Prototype
Std_ReturnType KeyM_NvBlock_ReadFrom_CRE (const void *NvMBuffer)
Parameter
NvMBuffer [in] RAM mirror where Ram block data can be read from.
Return code
E_OK Data was copied from buffer.
E_NOT_OK Data was not copied.
Functional Description
Block specific callback routine which is called by NvM in order to let the KeyM copy data from NvM RAM
mirror to KeyM RAM block.

© 2022 Vector Informatik GmbH Version 4.2.0 80

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

Particularities and Limitations

-
Call context
> TASK
> This function is Synchronous
> This function is Non-Reentrant
Table 4-54 KeyM_NvBlock_ReadFrom_CRE

4.4.7 KeyM_NvBlock_WriteTo_CRE
Prototype
Std_ReturnType KeyM_NvBlock_WriteTo_CRE (const void *NvMBuffer)
Parameter
NvMBuffer [in] RAM mirror where Ram block data shall be written to.
Return code
E_OK Data was copied to buffer.
E_NOT_OK Data was not copied.
Functional Description
Block specific callback routine which is called by NvM in order to let the KeyM copy data from RAM block to
NvM RAM mirror.
Particularities and Limitations
-
Call context
> TASK
> This function is Synchronous
> This function is Non-Reentrant
Table 4-55 KeyM_NvBlock_WriteTo_CRE

4.4.8 KeyM_NvBlock_Init_CRE
Prototype
Std_ReturnType KeyM_NvBlock_Init_CRE (void)
Parameter
void none
Return code
E_OK Data initialized.
E_NOT_OK Any error occurred.

© 2022 Vector Informatik GmbH Version 4.2.0 81

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

Functional Description
Block specific callback routine which is called by NvM in order to let the KeyM copy default data to a RAM
block.
Particularities and Limitations
-
Call context
> TASK
> This function is Synchronous
> This function is Non-Reentrant
Table 4-56 KeyM_NvBlock_Init_CRE

4.4.9 KeyM_NvBlock_Callback_CRE
Prototype
Std_ReturnType KeyM_NvBlock_Callback_CRE (const void
*NvMBuffer)
Parameter
ServiceIdType [in] The service identifier of the completed request.
JobResult[in] Result of the single block job.
Return code
E_OK Callback function has been processed successfully.
E_NOT_OK Callback function has not been processed successfully.
Functional Description
Block specific callback routine which is called by NvM in order to notify the KeyM that an asynchronous
single block request has been finished.
Particularities and Limitations
-
Call context
> TASK
> This function is Synchronous
> This function is Non-Reentrant
Table 4-57 KeyM_NvBlock_Callback_CRE

© 2022 Vector Informatik GmbH Version 4.2.0 82

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

4.5 Configurable Interfaces

4.5.1 Notifications
At its configurable interfaces the KeyM defines notifications that can be mapped to callback
functions provided by other modules. The mapping is not statically defined by the KeyM but
can be performed at configuration time. The function prototypes that can be used for the
configuration have to match the appropriate function prototype signatures, which are
described in the following sub-chapters.
4.5.1.1 Appl_VerifyCallbackFunc
Prototype
Std_ReturnType <Appl_VerifyCallbackFunc> (KeyM_CertificateIdType CertId,
KeyM_CertificateStatusType Result)
Parameter
CertId [in] The certificate identifier that has been verified.
Result [in] Contains information about the result of the operation.
Return code
Std_ReturnType E_OK: Operation successful.
E_NOT_OK: Operation failed.
Functional Description
Indicate result of the verification operation.
Notifies the application that a certificate verification has been finished. The function name is configurable by
KeyMCertificateVerifyCallbackNotificationFunc.
Particularities and Limitations

Call context
> TASK
> This function is Synchronous
> This function is Reentrant
Table 4-58 Appl_VerifyCallbackFunc

4.5.1.2 Appl_ServiceCallbackFunc
Prototype
void <Appl_ServiceCallbackFunc> (KeyM_CertificateIdType CertId, KeyM_ResultType
Result, uint16 ResultDataLength, uint8 *ResultDataPtr)
Parameter
CertId [in] Certificate identifier.
Result [in] Contains information about the result of the operation.
ResultDataLength [in] Contains the length of the resulting data of this operation if any.
ResultDataPtr [in] Pointer to the data of the result. Is only guaranteed to be valid if
ResultDataLength > 0.

© 2022 Vector Informatik GmbH Version 4.2.0 83

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

Return code
void none
Functional Description
Indicate the end of a service operation.
Notifies the application that the certificate service operation has been finished. This function is used by the
certificate submodule. This callback is only provided if KeyMServiceCertificateFunctionEnabled is set to
TRUE. The function name is configurable by KeyMServiceCertificateCallbackNotificationFunc.
Particularities and Limitations

Call context
> TASK
> This function is Synchronous
> This function is Reentrant
Table 4-59 Appl_ServiceCallbackFunc

4.5.1.3 Appl_VerifyGroupCallbackFunc
Prototype
Std_ReturnType <Appl_VerifyGroupCallbackFunc> (KeyM_CertificateGroupIdType
GroupId, KeyM_CertificateGroupStatusType Result)
Parameter
GroupId [in] Holds the certificate group identifier.
Result [in] Contains information about the result of the operation.
Return code
Std_ReturnType E_OK: Operation successful.
E_NOT_OK: Operation failed.
Functional Description
Indicate result of the certificate group verification operation.
Notifies the application that a certificate group verification has been finished. The function name is
configurable by KeyMCertificateGroupVerifyCallbackNotificationFunc.
Particularities and Limitations

Call context
> TASK
> This function is Synchronous
> This function is Reentrant
Table 4-60 Appl_VerifyGroupCallbackFunc

© 2022 Vector Informatik GmbH Version 4.2.0 84

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

4.5.2 Callout Functions

At its configurable interfaces the KeyM defines callout functions. The declarations of the
callout functions are provided by the BSW module, i.e. the KeyM. It is the integrator's task
to provide the corresponding function definitions. The definitions of the callouts can be
adjusted to the system's needs. The KeyM callout function declarations are described in the
following tables:

4.5.2.1 Appl_CertificateElementVerificationCallout
Prototype
Std_ReturnType <Appl_CertificateElementVerificationCallout>
(KeyM_CertificateIdType CertId, KeyM_CertElementIdType CertElementId, const
uint8 *CertElementData, uint32 CertElementDataLength)
Parameter
CertId [in] Certificate identifier.
CertElementId [in] Certificate element identifier.
CertElementData [in] Pointer to certificate element data.
CertElementDataLength Length of certificate element data.
[in]
Return code
Std_ReturnType E_OK: Operation successful
E_NOT_OK: Operation failed
Functional Description
Verify certificate elements.
Callout to verify that a given certificate fulfills the specified rules and conditions
Particularities and Limitations

Call context
> TASK
> This function is Synchronous
> This function is Reentrant
Table 4-61 Appl_CertificateElementVerificationCallout

4.5.2.2 Appl_SetKeyCallout
Prototype
Std_ReturnType <Appl_SetKeyCallout> (KeyM_CertificateIdType CertId,
KeyM_CertElementIdType CertElementId, uint32 csmKeyId, const uint8
*CertElementData, uint32 CertElementDataLength)
Parameter
CertId [in] Certificate identifier.

© 2022 Vector Informatik GmbH Version 4.2.0 85

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

CertElementId [in] Certificate element identifier.

csmKeyId [in] CSM key identifier.
CertElementData [in] Pointer to certificate element data.
CertElementDataLength Length of certificate element data.
[in]
Return code
Std_ReturnType E_OK: Operation successful.
E_NOT_OK: Operation failed.
Functional Description
Set Key Callout.
Callout to set the certificate key if the format is not supported by the KeyM.
Particularities and Limitations

Call context
> TASK
> This function is Synchronous
> This function is Reentrant
Table 4-62 Appl_SetKeyCallout

4.5.2.3 Appl_CertInitCallout
Prototype
void <Appl_CertInitCallout> (KeyM_CertificateIdType CertId,
KeyM_ConstCertDataType *CertificateDataPtr)
Parameter
CertId [in] Certificate identifier.
CertificateDataPtr [in,out] Provides a pointer to a certificate data structure. The buffer located by the
pointer in the structure shall be provided by the caller of this function. The
length information indicates the maximum length of the buffer when the
function is called. When the function returns, the length information indicates
the actual length of the certificate data in the buffer.
Return code
void none
Functional Description
Provide the certificate data during initialization.
Particularities and Limitations

Call context
> TASK
> This function is Synchronous
> This function is Reentrant

© 2022 Vector Informatik GmbH Version 4.2.0 86

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

Table 4-63 Appl_CertInitCallout

4.5.2.4 Appl_GetCurrentTimeCalloutFunc
Prototype
Std_ReturnType <Appl_GetCurrentTimeCalloutFunc> (KeyM_CertificateIdType CertId,
uint64 *timeStamp)
Parameter
CertId [in] Certificate identifier.
timeStamp [out] Current time in Unix time format.
Return code
Std_ReturnType E_OK Operation successful.
E_NOT_OK Operation failed.
KEYM_E_NO_PERIOD_VALIDITY_CHECK Skip time stamp validation.
Functional Description
Provide current time to verify certificate time stamp.
Particularities and Limitations
-
Call context
> TASK
> This function is Synchronous
> This function is Reentrant
Table 4-64 Appl_GetCurrentTimeCalloutFunc

© 2022 Vector Informatik GmbH Version 4.2.0 87

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

5 Configuration

In the KeyM the attributes can be configured according to/ with the following methods/ tools:
> Configuration in DaVinci Configurator 5 Pro

5.1 Configuration Variants

The KeyM supports the configuration variants
> VARIANT-PRE-COMPILE
The configuration classes of the KeyM parameters depend on the supported configuration
variants. For their definitions please see the KeyM_bswmd.arxml file.

5.2 Certificate Elements

Please make sure that following configuration requirements for certificate elements are met:

Caution
The object type (KeyMCertificateElementObjectType) of a certificate element
needs to be configured. Please note that only the types listed in chapter 3.3.6 are
currently supported.

Caution
The structure type (KeyMCertificateElementOfStructure) of a certificate
element needs to be configured according to the contained element types depending
on the used certificate format. For more details, please refer to the standards of X.509,
CRL [5] and CVC [10].

Caution
If a certificate element is contained in a structure with a given object identifier, this OID
needs to be configured in KeyMCertificateElementObjectId.

5.3 NvM Block Needs

The following table includes the configuration constraint for the used NvM blocks.

Parameter Block Type Expected Value

NvMBlockUseSetRamBlockStatus - TRUE
NvMBlockUseSyncMechanism - TRUE

© 2022 Vector Informatik GmbH Version 4.2.0 88

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

NvMInitBlockCallback - Init Block Callback

NvMReadRamBlockFromNvCallback - Read from Block Callback
NvMSelectBlockForReadAll - TRUE
DEFERRED TRUE
NvMSelectBlockForWriteAll
IMMEDIATE FALSE
NvMSetRamBlockStatusApi - TRUE
NvMSingleBlockCallback - Block Callback
NvMWriteRamBlockToNvCallback - Write to Block Callback
MICROSAR/NvMInvokeCallbacksForWriteAll - TRUE
MICROSAR/NvMUseInitCallback - TRUE
MICROSAR/NvMUseJobendCallback - TRUE
Table 5-1 NvM Block Needs

5.4 FAQ

What are possible causes for the failure of certificate parsing?

• Parsing error is caused if the passed certificate data does not correspond to the
certificate configuration. Please check the certificate identifier.
• Parsing error is caused if the KeyMCertAllowUnconfiguredElements parameter
is disabled and not all certificate elements are configured.
• Parsing error is caused if the KeyMCertAllowFlexibleOrder parameter is
disabled and the certificate elements are not configured in the exact order as they
appear in the certificate data.
• Parsing error is caused if the configured object type for a certificate element is not
supported by the KeyM (KeyMCertificateElementObjectType) or is not a
primitive ASN.1 tag identifier.
• Parsing error is caused if the configured structure type for a certificate element does
not correspond to the specified data structures for X.509, CRL and CVC
(KeyMCertificateElementOfStructure).
• Parsing error is caused if the configured object identifier does not correspond to the
object identifier contained in the certificate data
(KeyMCertificateElementObjectId).
• Parsing error is caused if the configured element path for certificate sub-element is
not configured correctly (KeyMCertificateElement). Please refer to 3.3.4.

What are possible causes for the failure of certificate verification?

© 2022 Vector Informatik GmbH Version 4.2.0 89

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

• Verification error is caused if the CSM jobs for the signature verification and the
corresponding CSM keys for the public keys are not configured correctly. Please refer
to 3.3.2.
• Verification error is caused if the configured upper hierarchical reference for a
certificate (KeyMCertUpperHierarchicalCertRef) does not correspond to the
actual issuer of the certificate.
• Verification error is caused if no separate CSM jobs and CSM keys are used for each
individual certificate.
• Verification error is caused if the parsed validity period in the certificate data is not
valid.
• Verification error is caused if the CSM operation for setting the public key or verifying
the certificate signature fails due to internal error.

© 2022 Vector Informatik GmbH Version 4.2.0 90

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

6 Glossary and Abbreviations

6.1 Glossary
Term Description
BswM BSW Mode Manager
CSM Cryptographic Service Manager
NvM NVRAM Manager
SchM BSW Scheduler Module
StbM Synchronized Time-Base Manager
Table 6-1 Glossary

6.2 Abbreviations
Abbreviation Description
API Application Programming Interface
ASN Abstract Syntax Notation
AUTOSAR Automotive Open System Architecture
BSW Basis Software
CA Certificate Authority
CRE Certificate Revocation Entry
CRL Certificate Revocation List
CSR Certificate Signing Request
DER Distinguished Encoding Rules
DET Development Error Tracer
ECC Elliptic Curve Cryptography
ECU Electronic Control Unit
HSM Hardware security module
OCSP Online Certificate Status Protocol
PKI Public Key Infrastructure
SRS Software Requirement Specification
SWC Software Component
SWS Software Specification
Table 6-2 Abbreviations

© 2022 Vector Informatik GmbH Version 4.2.0 91

based on template version 6.3.0
 Technical Reference MICROSAR Classic KeyM

7 Contact

Visit our website for more information on

> News
> Products
> Demo software
> Support
> Training data
> Addresses

www.vector.com

© 2022 Vector Informatik GmbH Version 4.2.0 92

based on template version 6.3.0