Key Manager (KeyM)

The function KeyM_Init serves to initialize the key management module ([SWS_KeyM_00043]). The call is synchronous and defined as non-reentrant ([SWS_KeyM_00043]). As the only passed parameter, ConfigPtr is expected, which represents a pointer to the configuration data set for VARIANT-POST-BUILD; the function has no return value ([SWS_KeyM_00043]).

With regard to the interaction with other module functions, KeyM_Init represents a mandatory precondition: When development error detection is enabled, all further functions of the Key Manager check whether the module was previously initialized via KeyM_Init and not yet de-initialized by means of KeyM_Deinit ([SWS_KeyM_00144]). If a module function is called in the uninitialized state, the Key Manager reports the development error KEYM_E_UNINIT ([SWS_KeyM_00144]).

Since KeyM_Init is specified as non-reentrant ([SWS_KeyM_00043]), the function may be executed only once and to the exclusion of concurrent calls in the system initialization phase. After successful execution, the module is available via the header file KeyM.h ([SWS_KeyM_00043]).

The function KeyM_Deinit serves to reset the Key Manager module back to the uninitialized state ([SWS_KeyM_00047]).

Usage and Call Context

The call to KeyM_Deinit is synchronous and specified as non-reentrant (Non Reentrant). The function has service ID 0x02, accepts no parameters, and returns no return value ([SWS_KeyM_00047]).

Concurrency and Interaction

Due to non-reentrancy, KeyM_Deinit must not be called concurrently with itself or in contradiction to running operations. After executing this deinitialization, the module is in the uninitialized state. If development errors are enabled, the Key Manager checks on every subsequent function call whether the module was previously initialized via KeyM_Init() and not yet deinitialized via KeyM_Deinit(); otherwise, the development error KEYM_E_UNINIT is reported ([SWS_KeyM_00144]).

The synchronous function KeyM_Start serves to release key update operations in the Key Manager ([SWS_KeyM_00050]). It is optional and only available if the configuration parameter KeyMCryptoKeyStartFinalizeFunctionEnabled is configured to true (AUTOSAR_SWS_KeyManager p. 35). The function is provided via KeyM.h and expects via StartType the operation mode to be executed as well as via Request Data and Request Data Length additional request data such as a signature.

Response data is returned via the output buffer Response Data. The parameter Response Data Length functions as an input and output parameter: Prior to the call, it defines the maximum number of bytes available in the buffer; after execution, it contains the actually written data length ([SWS_KeyM_00050]).

Error handling and return values:

• E_OK: Start operation executed successfully; key updates are now permitted.
• E_NOT_OK: Start operation not accepted.
• KEYM_E_PARAMETER_MISMATCH: Passed parameters do not match the expected values.
• KEYM_E_KEY_CERT_SIZE_MISMATCH: A passed parameter size does not match the expected size.

The function is specified as non-reentrant ([SWS_KeyM_00050]). Since no module-internal locks are described, the caller is likely required to ensure coordinated, serialized execution. Question Q-82276b712a8dd170 (open)

The synchronous function KeyM_Prepare serves to prepare a key update operation and transmits the required information to the key server or triggers the negotiation of a shared secret for key derivation [SWS_KeyM_00051]. The function has the service ID 0x05, is declared via the header KeyM.h, and is available exclusively when the configuration parameter Key MCrypto Key Prepare Function Enabled is set to TRUE [SWS_KeyM_00051].

The following buffers and length specifications must be passed during the call [SWS_KeyM_00051]:

• Request Data and Request Data Length: Input data and its length for the request [SWS_KeyM_00051].
• Response Data: Pointer to the buffer for receiving the output data [SWS_KeyM_00051].
• Response Data Length: Input/output parameter that specifies the maximum available buffer size prior to the call and contains the actually written byte count upon return [SWS_KeyM_00051].

If the call is acknowledged with E_OK, the service was accepted and is processed internally; the final results are subsequently provided via a callback [SWS_KeyM_00051]. If acceptance fails, the function returns E_NOT_OK in case of internal errors, KEYM_E_PARAMETER_MISMATCH for deviating parameter values, or KEYM_E_KEY_CERT_SIZE_MISMATCH for unsuitable size specifications [SWS_KeyM_00051].

Since KeyM_Prepare is specified as non-reentrant (Non Reentrant), no simultaneous or nested calls may occur [SWS_KeyM_00051].

The function KeyM_Finalize finalizes key update operations and transitions the key operation back into the idle state (idle mode) [SWS_KeyM_00053]. It is typically used in conjunction with a preceding KeyM_Start operation. After the call, the module accepts no further preparation or update operations (prepare/update) until a new sequence is initiated via KeyM_Start [SWS_KeyM_00053]. In addition, the updated key material is persisted and transitioned into the valid state by calling Csm_KeySetValid [SWS_KeyM_00053].

Usage and concurrency: KeyM_Finalize is non-reentrant (Non Reentrant) and operates asynchronously [SWS_KeyM_00053]. Interpretation: Due to the lack of reentrancy, the call is typically expected to occur in task context. Question Q-895ebec2d0d2e635 (open) The interface is only available if the configuration parameter KeyMCryptoKeyStartFinalizeFunctionEnabled is set to TRUE, and is declared via KeyM.h [SWS_KeyM_00053].

Parameters and return values: Request-specific data is passed via RequestDataPtr and RequestDataLength. Response data is provided via ResponseDataPtr; ResponseMaxDataLength initially serves as buffer size and yields the actual byte count upon synchronous return [SWS_KeyM_00053]. If the operation is accepted and processed internally, the function returns E_OK (the results follow asynchronously via callback) and ResponseMaxDataLength remains untouched [SWS_KeyM_00053].

Error handling: In case of error, KeyM_Finalize signals failure via specific return values [SWS_KeyM_00053]:

• E_NOT_OK: Operation not accepted due to an internal error.
• KEYM_E_BUSY: KeyM is busy with other jobs; validation cannot be performed yet.
• KEYM_E_PARAMETER_MISMATCH: Parameters do not match the expected value.
• KEYM_E_KEY_CERT_SIZE_MISMATCH: Parameter size does not match.

use

The synchronous function KeyM_SetCertificate passes certificate data to the key management module to temporarily store a certificate [SWS_KeyM_00057]. It expects as input parameters the identifier of the certificate CertId (type KeyM_CertificateIdType) as well as the pointer CertificateDataPtr (type const KeyM_CertDataType*), which points to the certificate structure to be provided [SWS_KeyM_00057]. The interface is declared via the header KeyM.h and has the service ID 0x0a [SWS_KeyM_00057].

Return Values and Error Handling

The return value of type Std_ReturnType provides information about the acceptance of the data [SWS_KeyM_00057]:

• E_OK: The certificate was successfully accepted [SWS_KeyM_00057].
• E_NOT_OK: The certificate could not be set [SWS_KeyM_00057].
• KEYM_E_PARAMETER_MISMATCH: The passed parameters do not match the expected values [SWS_KeyM_00057].
• KEYM_E_KEY_CERT_SIZE_MISMATCH: The size of the passed certificate data deviates from the expected size [SWS_KeyM_00057].

Concurrency and Limitations

The function is classified as non-reentrant (Non Reentrant) [SWS_KeyM_00057]. Concurrent calls must therefore be synchronized or excluded on the caller side. Since the specification explicitly provides for temporary storage, the passed certificate data presumably remains initially in the module's volatile memory before permanent storage or verification takes place. Question Q-c35c4b02344d5bc9 (open)

use

The synchronous function KeyM_GetCertificate serves to provide the certificate data for a specified certificate identifier [SWS_KeyM_00058]. Via parameter CertId, the caller passes the identifier of the desired certificate, and via inout parameter CertificateDataPtr, a pointer to the certificate data structure. The caller is responsible for providing the buffer referenced by the pointer in the structure [SWS_KeyM_00058]. Prior to the call, the maximum length of this buffer must be specified in the structure; upon successful return (E_OK), the length field contains the actual length of the provided certificate data [SWS_KeyM_00058].

Error handling

The function indicates success or specific errors via the return value of type Std_ReturnType [SWS_KeyM_00058]:

• E_OK: Certificate data is available and was passed successfully.
• KEYM_E_PARAMETER_MISMATCH: The passed certificate ID (CertId) is invalid.
• KEYM_E_KEY_CERT_SIZE_MISMATCH: The provided buffer is too small for the certificate.
• KEYM_E_KEY_CERT_EMPTY: No certificate data is present because the certificate slot is empty.
• KEYM_E_KEY_CERT_READ_FAIL: The certificate cannot be provided because access was denied.
• E_NOT_OK: The operation was not accepted due to an internal error.

Concurrency and Limitations

The function is specified as non-reentrant (Non Reentrant) and is available via header file KeyM.h [SWS_KeyM_00058]. Callers must therefore ensure that concurrent calls to the function are synchronized against each other.

The function KeyM_VerifyCertificates serves for the asynchronous verification of two internally stored and parsed certificates against each other according to [SWS_KeyM_00059]. In doing so, it validates whether the subordinate certificate referenced via CertId was signed by the superordinate certificate referenced via CertUpperId.

Since the service is defined as non-reentrant (Non Reentrant), it must not be called concurrently for overlapping operations [SWS_KeyM_00059]. Execution takes place asynchronously in the background: A return value of E_OK merely signals the successful acceptance of the verification job. The actual verification result is communicated to the caller via the configured callback function KeyMCertificateVerifyCallbackNotificationFunc, provided that this function is validly configured [SWS_KeyM_00153].

If the request is not accepted, the function returns specific return values for error handling [SWS_KeyM_00059]:

• KEYM_E_BUSY: The Key Manager is busy with other tasks; the validation cannot be started at this point in time.
• KEYM_E_PARAMETER_MISMATCH: At least one passed certificate ID is invalid.
• KEYM_E_KEY_CERT_EMPTY: One of the referenced certificate slots is empty.
• KEYM_E_CERT_INVALID_CHAIN_OF_TRUST: The superordinate certificate (CertUpperId) is not valid.
• E_NOT_OK: The job was rejected due to an internal error.

The function KeyM_VerifyCertificate serves for the asynchronous verification of a certificate that was previously provided via KeyM_SetCertificate() [SWS_KeyM_00060]. The check is performed based on the passed certificate identifier CertId against certificates of other certificate IDs already stored in the Key Manager [SWS_KeyM_00060]. The declaration is available via header file KeyM.h [SWS_KeyM_00060].

Call semantics and return values

A return value of E_OK confirms that the verification request was successfully accepted and that the operation is executed in the background [SWS_KeyM_00060]. If the request cannot be accepted, feedback is provided synchronously via specific error codes [SWS_KeyM_00060]:

• E_NOT_OK: The operation was rejected due to an internal error [SWS_KeyM_00060].
• KEYM_E_BUSY: The KeyM module is currently busy with other tasks, so the validation cannot yet be executed [SWS_KeyM_00060].
• KEYM_E_PARAMETER_MISMATCH: The passed CertId is invalid [SWS_KeyM_00060].
• KEYM_E_KEY_CERT_EMPTY: At least one of the required certificate slots is empty [SWS_KeyM_00060].
• KEYM_E_CERT_INVALID_CHAIN_OF_TRUST: A superordinate certificate in the chain of trust is invalid [SWS_KeyM_00060].

Concurrency and asynchrony

Since KeyM_VerifyCertificate is specified as non-reentrant (Non Reentrant), the caller must ensure that no concurrent or interrupting calls occur [SWS_KeyM_00060]. After successful acceptance of the verification request (return value E_OK), the result of the background operation is transmitted to the configured callback function KeyMCertificateVerifyCallbackNotificationFunc, provided that it is configured with a valid function name [SWS_KeyM_00153].

The function KeyM_VerifyCertificateChain serves for the asynchronous verification of a certificate against a chain of passed certificates [SWS_KeyM_00061]. The identifier of the last certificate in the chain (CertId), a pointer to the certificate array sorted according to PKI order (certChainData), and the number of certificates (NumberOfCertificates) are passed as parameters [SWS_KeyM_00061]. Prior to the call, the certificate to be verified must have been registered via KeyM_SetCertificate(), and the root certificate must either be included in the list or already assigned to one of the other certificates [SWS_KeyM_00061].

The function is non-reentrant (Non Reentrant) and is provided via the header file KeyM.h [SWS_KeyM_00061]. The following synchronous return values indicate the job acceptance status [SWS_KeyM_00061]:

• E_OK: The verification job was accepted and is executed in the background [SWS_KeyM_00061].
• E_NOT_OK: The job was rejected due to an internal error [SWS_KeyM_00061].
• KEYM_E_BUSY: The module is busy with other jobs; the validation cannot be executed yet [SWS_KeyM_00061].
• KEYM_E_PARAMETER_MISMATCH: The passed certificate ID is invalid [SWS_KeyM_00061].
• KEYM_E_KEY_CERT_EMPTY: One of the required certificate slots is empty [SWS_KeyM_00061].
• KEYM_E_CERT_INVALID_CHAIN_OF_TRUST: A superordinate certificate in the chain of trust is invalid [SWS_KeyM_00061].

If the job was accepted with E_OK, the evaluation takes place in the background. Provided that KeyMCertificateVerifyCallbackNotificationFunc is configured with a valid function, KeyM reports the final result of the verification operation back to the calling application via this callback function [SWS_KeyM_00061] [SWS_KeyM_00153].

Usage and Call Context

The synchronous function KeyM_CertElementGet serves to read the data of a specific certificate element from a certificate slot into a buffer provided by the caller [SWS_KeyM_00063]. It is used when exactly one single element is assigned to the object identifier (OID) stored in the certificate configuration [SWS_KeyM_00063].

The caller passes certificate identifier CertId, element identifier CertElementId, and a pointer to destination buffer CertElementData [SWS_KeyM_00063]. Parameter CertElementDataLength serves as a combined input and output value: Prior to the call, it must contain the maximum buffer size. In case of success (E_OK), it is overwritten with the actual length of the written data; in case of an error, the function resets the referenced value to zero [SWS_KeyM_00063].

Error Handling and Return Values

The function reports the execution status via the following return values [SWS_KeyM_00063]:

• E_OK: The element was found and successfully copied into the buffer [SWS_KeyM_00063].
• E_NOT_OK: The element data was not found [SWS_KeyM_00063].
• KEYM_E_PARAMETER_MISMATCH: Invalid CertId or CertElementId [SWS_KeyM_00063].
• KEYM_E_KEY_CERT_SIZE_MISMATCH: The provided buffer is too small for the element's data [SWS_KeyM_00063].
• KEYM_E_KEY_CERT_EMPTY: No data exists for the specified slot; the slot is empty [SWS_KeyM_00063].
• KEYM_E_KEY_CERT_INVALID: The certificate is invalid or has not yet been verified [SWS_KeyM_00063].

Concurrency

The function is specified as non-reentrant (Non Reentrant) [SWS_KeyM_00063]. For concurrent calls from different tasks or contexts, caller-side synchronization is therefore likely required. Question Q-238a3e53ce0e3a45 (open)

The synchronous function KeyM_CertificateElementGetByIndex is used to selectively read data of a certificate element based on a zero-based index (0..N) when multiple entries exist for an element type [SWS_KeyM_91014]. It thus represents a direct-access alternative to sequential iteration.

Usage and Parameters

The caller passes the certificate identifier CertId, the element identifier CertElementId, and the desired Index [SWS_KeyM_91014]. In addition, the caller must allocate the memory for CertElementDataPtr and pass the maximum available buffer size via CertElementDataLengthPtr. Upon successful return, CertElementDataLengthPtr is overwritten with the actual length of the copied data [SWS_KeyM_91014].

Return Values and Error Handling

The function indicates the result via specific Std_ReturnType return values [SWS_KeyM_91014]:

• E_OK: The element was found and successfully copied into the target buffer.
• KEYM_E_PARAMETER_MISMATCH: Invalid CertId, invalid CertElementId, or the passed Index is outside the valid range.
• KEYM_E_KEY_CERT_SIZE_MISMATCH: The provided buffer is too small for the certificate element.
• KEYM_E_KEY_CERT_EMPTY: The specified certificate contains no data or is empty.
• KEYM_E_CERT_INVALID: The certificate is invalid or verification was unsuccessful.
• E_NOT_OK: Reading the element data failed.

Concurrency

According to the specification, the service is classified as non-reentrant (Non Reentrant) [SWS_KeyM_91014]. Calls must therefore not be executed concurrently without protection.

The synchronous interface KeyM_CertificateElementGetCount determines the total number of data elements stored for a specific certificate element and writes the result into the buffer CountPtr [SWS_KeyM_91015].

Usage and Parameters

The function is declared via the header KeyM.h and has the service ID 0x1c [SWS_KeyM_91015]. It processes the following parameters:

• CertId (IN): Unique identifier of the certificate to query ([SWS_KeyM_91015]).
• CertElementId (IN): Determines the concrete element within the certificate ([SWS_KeyM_91015]).
• CountPtr (OUT): Pointer to the buffer of type uint16 into which the number of available data elements is copied ([SWS_KeyM_91015]).

Error Handling and Return Values

The return value of type Std_ReturnType provides information about the result of the execution [SWS_KeyM_91015]:

• E_OK: The count value was successfully written into the buffer ([SWS_KeyM_91015]).
• E_NOT_OK: The count value could not be provided ([SWS_KeyM_91015]).
• KEYM_E_PARAMETER_MISMATCH: The certificate ID (CertId) or element ID (CertElementId) is invalid or out of range ([SWS_KeyM_91015]).

Concurrency and Interaction

Execution is synchronous but classified as non-reentrant (Non Reentrant), so that concurrent calls must be coordinated [SWS_KeyM_91015]. While certificate elements typically only have a single data element assigned, multiple consecutive data elements may be present in certain cases [SWS_KeyM_91015]. The determined total number serves as the basis for subsequently reading out individual elements in a targeted manner via KeyM_CertificateElementGetByIndex(), which functionally resembles the iterative approach using KeyM_CertElementGetFirst and KeyM_CertElementGetNext [SWS_KeyM_91015].

According to [SWS_KeyM_00064], the synchronous function KeyM_CertElementGetFirst serves to initiate the iterative extraction of certificate data. It reads the top element of the certificate element addressed via CertElementId from certificate CertId and initializes the iterator construction CertElementIterator for subsequent calls to KeyM_CertElementGetNext().

When calling, the following parameter and memory requirements according to [SWS_KeyM_00064] must be observed:

• CertElementIterator: Pointer to a structure allocated and managed by the caller; this structure must neither be destroyed nor modified by the application as long as not all data has been retrieved via KeyM_CertElementGetNext().
• CertElementData: Pointer to an output buffer provided by the caller into which the payload data is copied upon successful finding (E_OK).
• CertElementDataLength: Passes the maximum length of the data buffer as input and is overwritten with the actually written data length upon return of E_OK.

With regard to concurrency, according to [SWS_KeyM_00064], the service is reentrant, but with respect to exactly one iterator (“Reentrant for one iterator”).

In case of error, the function differentiates via specific return values according to [SWS_KeyM_00064]: E_NOT_OK indicates that no element data was found (the iterator must not be used for further calls thereafter). KEYM_E_PARAMETER_MISMATCH indicates an invalid certificate or element ID, KEYM_E_KEY_CERT_SIZE_MISMATCH a data buffer that is too small, KEYM_E_KEY_CERT_EMPTY an empty certificate without available data, and KEYM_E_CERT_INVALID an invalid or not successfully verified certificate.

The synchronous function KeyM_CertElementGetNext (Service ID 0x11, provided via KeyM.h) serves for the continuous reading of further data from a certificate element if multiple records are stored sequentially in it [SWS_KeyM_00065]. As a mandatory call precondition, the specification requires that function KeyM_CertElementGetFirst() was called at least once previously [SWS_KeyM_00065].

The memory areas for all parameters must be provided by the calling application [SWS_KeyM_00065]:

• CertElementIterator: Pointer to an allocated iterator structure, which must neither be modified nor destroyed by the application during traversal until all elements have been completely read out [SWS_KeyM_00065].
• CertElementData: Pointer to the output buffer into which the function copies the payload data upon successful execution [SWS_KeyM_00065].
• CertElementDataLength: Passes the maximum capacity of the data buffer upon the call and is overwritten with the actual length of the copied data upon successful return [SWS_KeyM_00065].

If the call returns E_OK, the next element was found, written into the buffer, and the iterator was advanced accordingly [SWS_KeyM_00065]. In the case of E_NOT_OK, no further element data could be found; in this case, the iterator may no longer be used for any further calls [SWS_KeyM_00065]. Error situations are reported via specific return values: KEYM_E_KEY_CERT_SIZE_MISMATCH indicates a data buffer that is dimensioned too small, KEYM_E_PARAMETER_MISMATCH an invalid certificate or element ID, KEYM_E_KEY_CERT_EMPTY an empty certificate, and KEYM_E_CERT_INVALID an invalid or not successfully verified certificate [SWS_KeyM_00065].

Regarding concurrency, the synchronous function is specified as reentrant for one iterator at a time [SWS_KeyM_00065].

The synchronous function KeyM_CertGetStatus serves to query the status of a certificate and provide it via an output parameter [SWS_KeyM_00066]. The declaration of the function is accessible via header file KeyM.h, and the hexadecimal Service ID 0x12 is assigned to the service [SWS_KeyM_00066].

The following parameters are used for the call [SWS_KeyM_00066]:

• CertId (IN): Contains the identifier of the certificate to be queried and is passed with data type KeyM_CertificateIdType [SWS_KeyM_00066].
• Status (OUT): Pointer to the memory area of type KeyM_CertificateStatusType into which the function writes the determined status of the certificate [SWS_KeyM_00066].

The return value of type Std_ReturnType provides information about the outcome of the status query [SWS_KeyM_00066]:

• E_OK: The certificate status was successfully determined and provided [SWS_KeyM_00066].
• E_NOT_OK: Providing the status is currently not possible [SWS_KeyM_00066]. This occurs, for example, if an invalid certificate ID is passed, documented with error code KEYM_E_PARAMETER_MISMATCH [SWS_KeyM_00066].

Regarding execution and concurrency, the interface behaves purely synchronously and is specified as non-reentrant (Non Reentrant) [SWS_KeyM_00066]. Concurrent calls across multiple execution contexts are therefore not permitted. Additional input and output parameters are not intended for this interface [SWS_KeyM_00066].

The function KeyM_MainFunction serves as the periodic main function for the Classic AUTOSAR module KeyM [SWS_KeyM_00074]. According to the specification, the function has service ID 0x19 in hexadecimal representation as well as the signature void KeyM_MainFunction (void) [SWS_KeyM_00074]. Calling entities thus pass no input parameters and receive no return value [SWS_KeyM_00074].

For schedule control, it is defined that the function is to be called periodically according to a defined time interval [SWS_KeyM_00074]. The header file SchM_KeyM.h is declared as the interface file [SWS_KeyM_00074]. This leads to the interpretation: By being provided via SchM_KeyM.h, the regular call of the function is likely to take place in the context of the basic software scheduler (SchM) [SWS_KeyM_00074]. Question Q-761ff71812bda3c2 (open) In addition, the cyclic triggering presumably serves for the internal processing of time-dependent procedures in the module KeyM.

Regarding error handling and error behavior, no return codes, error constants, or reports to DET or DEM are documented in the specification element for this service [SWS_KeyM_00074]. Since no input parameters exist, checking passed values during the call is also omitted [SWS_KeyM_00074].

Usage and Call Context

The function KeyM_MainBackgroundFunction has signature void KeyM_MainBackgroundFunction(void) and is specified under service ID 0x1a [SWS_KeyM_00075]. It takes no input parameters and returns no return value to the caller [SWS_KeyM_00075]. For integration, the interface is declared and provided via the header file SchM_KeyM.h [SWS_KeyM_00075].

The call is performed by a preemptive operating system in the background as soon as no other task operation is pending for execution [SWS_KeyM_00075]. The primary purpose of this function is to provide an uncritical background context for time-consuming, synchronous operations of the KeyM module, as described by way of example for the execution of KeyM_KH_Update() [SWS_KeyM_00075].

Concurrency and Error Handling

Since the function is executed in the background context of a preemptive operating system, it is likely interruptible at any time by any regular, higher-priority tasks. Question Q-a2394a51ba63467f (open) For this background service, the standard specifies neither specific error codes nor notifications to the DET or DEM [SWS_KeyM_00075]. Furthermore, no special reentrancy properties or fixed sequencing conditions with respect to other module functions are prescribed in the given data baseline [SWS_KeyM_00075].

The synchronous and non-reentrant function KeyM_KH_Start is declared via header KeyM_Externals.h [SWS_KeyM_00067]. When the configuration parameters KeyMCryptoKeyStartFinalizeFunctionEnabled and KeyMCryptoKeyHandlerStartFinalizeEnabled are set to TRUE, it is executed immediately upon a call to KeyM_Start [SWS_KeyM_00067].

Via parameter StartType, the execution mode of the key operation is defined. By means of RequestData and RequestDataLength, the function receives request-specific accompanying data, such as signatures. Via in/out parameter ResponseDataLength, the caller passes the maximum byte amount available in buffer ResponseData; in case of success, the function uses it to report back the number of response bytes actually written [SWS_KeyM_00067].

As return value, the function provides a status of type Std_ReturnType [SWS_KeyM_00067]:

• E_OK: The start operation was successful. Only through this return value does the Key Manager transition to the active state, so that subsequent key updates are permitted.
• E_NOT_OK: The start operation was not accepted.
• KEYM_E_PARAMETER_MISMATCH: A passed parameter does not match the expected value.
• KEYM_E_KEY_CERT_SIZE_MISMATCH: A specified parameter size does not match the expected size.

Since KeyM_KH_Start is defined as non-reentrant, calls for parallel key operations must not occur concurrently [SWS_KeyM_00067].

Usage and Call Context

The function KeyM_KH_Prepare is declared via header file KeyM_Externals.h and serves to prepare a key management operation [SWS_KeyM_00068]. It is triggered immediately upon calling KeyM_Prepare if the two configuration parameters KeyMCryptoKeyPrepareFunctionEnabled and KeyMCryptoKeyHandlerPrepareEnabled are each set to TRUE [SWS_KeyM_00068]. Execution is synchronous and specified as non-reentrant [SWS_KeyM_00068].

Data transfer takes place via four parameters [SWS_KeyM_00068]:

• RequestData: Input data passed together with the request [SWS_KeyM_00068].
• RequestDataLength: Length of the data in the array RequestData [SWS_KeyM_00068].
• ResponseDataPtr: Pointer to the buffer for the response data returned by the function, which is forwarded unchanged to the caller of Key_Prepare [SWS_KeyM_00068].
• ResponseDataLength: Input and output parameter; passes the maximum number of bytes available in the buffer upon the call and returns the amount of bytes actually written after return [SWS_KeyM_00068].

Return Values and Error Behavior

As a result, the function returns status value Std_ReturnType [SWS_KeyM_00068]:

• E_OK: The service was accepted and is processed further internally; results are transmitted via a callback [SWS_KeyM_00068].
• E_NOT_OK: The service was not accepted due to an internal error [SWS_KeyM_00068].
• KEYM_E_PARAMETER_MISMATCH: A parameter does not match the expected value [SWS_KeyM_00068].
• KEYM_E_KEY_CERT_SIZE_MISMATCH: The size of a parameter is not suitable [SWS_KeyM_00068].

Usage and delegation

The function KeyM_KH_Finalize is declared via header file KeyM_Externals.h and acts as a user-specific key handler [SWS_KeyM_00070]. If both KeyMCryptoKeyStartFinalizeFunctionEnabled and KeyMCryptoKeyHandlerStartFinalizeEnabled are set to TRUE in the configuration, KeyM_Finalize() does not execute an independent operation, but immediately delegates processing to this handler function [SWS_KeyM_00070].

Call Context and Parameters

The call to KeyM_KH_Finalize occurs synchronously, but is classified as non-reentrant (Non Reentrant) and requires a protected call context [SWS_KeyM_00070]. Data passing takes place via the following parameters:

• RequestData and RequestDataLength: Pointer to the input data passed with the request, as well as the length of the data array [SWS_KeyM_00070].
• ResponseData: Buffer for the output data provided by the function [SWS_KeyM_00070].
• ResponseDataLength: An in/out parameter that specifies the maximum byte amount available in the response buffer upon the call and contains the number of bytes actually written upon return [SWS_KeyM_00070].

Return Values and Error Handling

The operation result is returned via Std_ReturnType [SWS_KeyM_00070]:

• E_OK: The operation was accepted and is processed further internally; the results are provided via a callback [SWS_KeyM_00070]. Interpretation: Although the function interface is defined as synchronous, actual processing is likely continued in the background. Question Q-02c4aac040570c03 (open)
• E_NOT_OK: The operation was not accepted due to an internal error [SWS_KeyM_00070].
• KEYM_E_BUSY: The Key Manager is busy with other tasks, which is why the validation currently cannot be performed [SWS_KeyM_00070].
• KEYM_E_PARAMETER_MISMATCH: A parameter does not match the expected value [SWS_KeyM_00070].
• KEYM_E_KEY_CERT_SIZE_MISMATCH: The passed parameter size does not comply with the specifications [SWS_KeyM_00070].

The callback function KeyM_CryptoKeyUpdateCallbackNotification() notifies the application that an update of a cryptographic key has been completed ([SWS_KeyM_00077]). The function is provided via KeyM_Externals.h, is synchronous and reentrant, and has no return value ([SWS_KeyM_00077]).

Parameters

• Result: Transmits information about the result of the update operation via type KeyM_ResultType ([SWS_KeyM_00077], [SWS_KeyM_00156]).
• ResultDataLength: Specifies the length of the resulting data of this operation ([SWS_KeyM_00077], [SWS_KeyM_00156]).
• ResultDataPtr: Pointer to the data of the result ([SWS_KeyM_00077]).

Interaction and Buffer Management

The call to KeyM_CryptoKeyUpdateCallbackNotification() is performed by KeyM_Update() as soon as the key handler returns and provides operation type KEYM_KH_UPDATE_FINISH ([SWS_KeyM_00093]). Here, the result data is copied from KeyM_KH_Update::ResultDataPtr into the buffer that was passed upon calling KeyM_Update(), and the return value of the key handler is adopted ([SWS_KeyM_00093]).

Provided that KeyM_Update() has accepted the operation with E_OK, the calling function must under no circumstances modify buffer ResultDataPtr until callback notification KeyM_CryptoKeyUpdateCallbackNotification() has occurred ([SWS_KeyM_00156]). The same buffer pointer is passed in the callback as ResultDataPtr with the operation results copied into it ([SWS_KeyM_00156]).

The callback function KeyM_CryptoKeyFinalizeCallbackNotification notifies the application of the completion of a key finalization operation [SWS_KeyM_00079]. It is specified as synchronous and reentrant, has no return value, and is declared via header file KeyM_Externals.h [SWS_KeyM_00079].

Upon the call, the interface passes the following parameters to the application [SWS_KeyM_00079]:

• Result (type KeyM_ResultType): Transmits the result and status information of the completed operation [SWS_KeyM_00079].
• Result Data Length (type uint16): Indicates the length of the resulting data of this operation [SWS_KeyM_00079].
• Result Data Ptr (type const uint8*): Pointer to the buffer containing the result data that was previously provided to the service function [SWS_KeyM_00079].

With regard to configuration, the callback function is only called and required if configuration parameter KeyMCryptoKeyStartFinalizeFunctionEnabled is set to TRUE [SWS_KeyM_00079]. Specific DET or DEM error notifications are not defined for this callback function. Presumably, the application implements this callback in order to receive the asynchronous results of a previously initiated key finalization. Question Q-6d9e4e062b008832 (open)

Usage and Parameters

The callback function KeyM_CryptoKeyVerifyCallbackNotification informs the application of the completion of a verification operation for a cryptographic key by the KeyM module [SWS_KeyM_00081]. Interpretation: Since according to the specification the element is available via header KeyM_Externals.h and serves to notify the application, the implementation is likely done by the using software component, while the call is performed by the Key Manager [SWS_KeyM_00081]. Question Q-e88e332a7d2cac40 (open)

Four pure input parameters are defined for the call [SWS_KeyM_00081]:

• Result (KeyM_ResultType): Passes the result of the completed verification [SWS_KeyM_00081].
• KeyId (uint32): Identifies the key ID for which the verification was started [SWS_KeyM_00081].
• ResultDataLength (uint16): Contains the length of the resulting result data, if present [SWS_KeyM_00081].
• ResultDataPtr (const uint8*): Points to the data of the verification result [SWS_KeyM_00081].

Concurrency and Limitations

The function has no return value (void) and neither output nor input/output parameters [SWS_KeyM_00081]. The call is implemented synchronously and reentrantly [SWS_KeyM_00081]. Specific error codes as well as DET or DEM messages are not specified for this callback; status and error information are transmitted to the application exclusively via parameter Result [SWS_KeyM_00081].

Usage and Semantics

The callback function KeyM_ServiceCertificateCallbackNotification is called by the certificate submodule of the KeyM to notify the application of the completion of a certificate service operation [SWS_KeyM_00147]. The preceding certificate operation runs asynchronously and executes this callback upon its completion to transmit the results to the application [SWS_KeyM_00149].

All relevant result data is transmitted via the function parameters [SWS_KeyM_00147]:

• CertId: Identifier of the certificate for which the operation was initiated.
• Result: Type KeyM_ResultType with the status or result of the operation.
• ResultDataLength: Length of the result data, if present.
• ResultDataPtr: Pointer to the result data.

The function itself has no return value (void) and exhibits synchronous execution semantics [SWS_KeyM_00147].

Configuration and Restrictions

The callback is provided via the header KeyM_Externals.h, but is only available if the configuration parameter KeyMServiceCertificateFunctionEnabled is set to TRUE [SWS_KeyM_00147]. The actual name of the notification function can be customized via the configuration parameter KeyMServiceCertificateCallbackNotificationFunc [SWS_KeyM_00147].

Concurrency and Error Handling

According to the specification, the function is classified as reentrant [SWS_KeyM_00147]. Errors or success states of the preceding asynchronous operation are signaled via the passing parameter Result; specific DET or DEM messages are not defined in the payload for this callback interface [SWS_KeyM_00147].

use

The callback function KeyM_CertificateVerifyCallbackNotification serves to notify the application of the completion of a certificate verification [SWS_KeyM_00073]. The declaration is available via header KeyM_Externals.h, where the function name can be configured via configuration parameter KeyMCertificateVerifyCallbackNotificationFunc [SWS_KeyM_00073].

Upon the call, two input parameters are passed [SWS_KeyM_00073]:

• CertId (type KeyM_CertificateIdType): Identifier of the verified certificate [SWS_KeyM_00073].
• Result (type KeyM_CertificateStatusType): Contains information about the result of the verification operation [SWS_KeyM_00073].

The function returns the value E_OK as a status value of type Std_ReturnType [SWS_KeyM_00073].

Execution and error handling

The execution of the notification is defined as synchronous and reentrant [SWS_KeyM_00073]. Specific error codes, deviating return values, or reports to DET or DEM are not intended for this callback [SWS_KeyM_00073]. Interpretation: The application-side implementation will likely have to be designed thread-safe in order to process concurrent calls for different certificates without side effects. Question Q-6bf5313c425fe1a8 (open)

use

The data type KeyM_CertElementIteratorType is defined as a structure (Structure) according to [SWS_KeyM_00042] and is provided via the header file KeyM.h. According to the specification, this type serves to iterate over a series of elements of a certificate ([SWS_KeyM_00042]). Since the concrete content of the data structure is explicitly defined as implementation-specific ([SWS_KeyM_00042]), users are expected to treat the type as an opaque iteration state and not directly access internal structure fields. Question Q-81b5deb7dcdf2812 (open)

Handling and Limitations

The following practical conditions for use result from the specification:

• Implementation-specific structure: Since the fields of KeyM_CertElementIteratorType are implemented vendor-specifically ([SWS_KeyM_00042]), the internal memory layout depends on the respective BSW implementation.
• State management: Interpretation: An instance of the structure is likely allocated by the caller as an iterator context and passed to the corresponding functions for certificate element traversal in order to track progress during checking or extraction of certificate fields. Question Q-5ddb438001abe656 (open)
• Concurrency: Presumably, an iterator instance cannot be used concurrently across multiple tasks without external synchronization if parallel accesses to the same certificate occur. Question Q-6b4b8b1cdc35f021 (open)

The enumeration type KeyM_ServiceCertificateType is provided via the header Rte_KeyM_Type.h and specifies the certificate service operation requested by the key server as well as the kind of information passed with the function [SWS_KeyM_00039]. The declaration in the RTE header file is likely to indicate that the type is primarily used in data exchange between software components and the Key Manager module. Question Q-37ed693ea3eda646 (open)

The following standardized operation codes are defined for certificate management [SWS_KeyM_00039]:

• KEYM_SERVICE_CERT_REQUEST_CSR (0x01): The key server requests the key client to generate a certificate or a certificate signing request (CSR) [SWS_KeyM_00039].
• KEYM_SERVICE_CERT_UPDATE_SIGNED_CSR (0x02): The server returns a previously received certificate that has meanwhile been signed by the certification authority (CA) [SWS_KeyM_00039].
• KEYM_SERVICE_CERT_SET_ROOT (0x03) and KEYM_SERVICE_CERT_UPDATE_ROOT (0x04): Creating a new root certificate or updating an existing root certificate [SWS_KeyM_00039].
• KEYM_SERVICE_CERT_SET_INTERMEDIATE (0x05) and KEYM_SERVICE_CERT_UPDATE_INTERMEDIATE (0x06): Adding or updating an intermediate certificate (CA certificate) [SWS_KeyM_00039].
• KEYM_SERVICE_CERT_UPDATE_CRL (0x07): Providing or updating a certificate revocation list (CRL) [SWS_KeyM_00039].

As an essential precondition, KEYM_SERVICE_CERT_SET_INTERMEDIATE requires that the associated root certificate must already be stored prior to setting an intermediate certificate in order to ensure successful verification [SWS_KeyM_00039]. For project-specific extensions, the specification provides the reserved value range from 0x80 to 0x9F [SWS_KeyM_00039].

The enumeration type KeyM_CertificateStatusType represents the result of certificate checks and reflects the current verification and processing status of a certificate in the Key Manager [SWS_KeyM_91003]. The type is provided via the header Rte_KeyM_Type.h and serves callers to evaluate the status or specific error causes of a certificate verification in a differentiated manner [SWS_KeyM_91003].

The enumeration values cover regular intermediate and success states as well as precise error patterns [SWS_KeyM_91003]:

• KEYM_CERTIFICATE_VALID (0x00): The certificate was successfully parsed and verified [SWS_KeyM_91003].
• KEYM_CERTIFICATE_INVALID (0x01): The certificate is invalid due to an unspecified error [SWS_KeyM_91003].
• KEYM_CERTIFICATE_NOT_PARSED (0x02): The certificate has not yet been parsed so far [SWS_KeyM_91003].
• KEYM_CERTIFICATE_PARSED_NOT_VALIDATED (0x03): The certificate was parsed, but not yet validated [SWS_KeyM_91003].
• KEYM_CERTIFICATE_NOT_AVAILABLE (0x04): No certificate is set [SWS_KeyM_91003].
• Error-specific check results: Failed validity period (KEYM_E_CERTIFICATE_VALIDITY_PERIOD_FAIL, 0x05), incorrect signature (KEYM_E_CERTIFICATE_SIGNATURE_FAIL, 0x06), invalid chain of trust (KEYM_E_CERTIFICATE_INVALID_CHAIN_OF_TRUST, 0x07), invalid type (KEYM_E_CERTIFICATE_INVALID_TYPE, 0x08), incorrect format (KEYM_E_CERTIFICATE_INVALID_FORMAT, 0x09), invalid content (KEYM_E_CERTIFICATE_INVALID_CONTENT, 0x0A), and revocation or invalid scope (KEYM_E_CERTIFICATE_REVOKED, 0x0B) [SWS_KeyM_91003].

Callers should check the status before using cryptographic keys; operations may typically only build upon a certificate if the status explicitly signals KEYM_CERTIFICATE_VALID. Since the type is declared via Rte_KeyM_Type.h, it is likely to be used primarily in standardized service interfaces and ports for interaction between KeyM and application SWCs. Question Q-f3ca10ee673798df (open)

Usage and structure

The data type KeyM_CertificateElementType is specified as a byte array with the element type uint8 and, according to the specification, serves as a sufficiently large memory area for storing data of a certificate element [SWS_KeyM_91004]. The data type is provided and declared for the KeyM module via the header file Rte_KeyM_Type.h [SWS_KeyM_91004].

Configuration and Variation

The manifestation of the data type is subject to a configuration-dependent naming and size variation derived from the configured parameters of the module [SWS_KeyM_91004]:

• Naming pattern: The concrete type name is generated element-specifically according to the pattern KeyM_CertificateElementType_{KeyMCertificate}_{KeyMCertificateElement}, where the placeholders correspond to the configured short names SHORT-NAME of the respective certificate and certificate element instances [SWS_KeyM_91004].
• Array size: The number of uint8 elements is determined by the configuration parameter KeyMCertificateElementMaxLength so that the array provides sufficient storage space for the raw data of the respective element [SWS_KeyM_91004].

Limitations and Assumptions

Since the definition is provided in Rte_KeyM_Type.h, the type is presumably used primarily as a standardized buffer at the interfaces to software components for exchanging certificate content [SWS_KeyM_91004]. Question Q-994f8ac6772de3c1 (open) The maximum processable data length remains statically bound to the maximum length defined at configuration time [SWS_KeyM_91004].

Usage and Type Definition

The data type KeyM_CryptoKeyDataType is defined as a pointer type to uint8* and serves as a byte pointer for input or output data within the KeyM module [SWS_KeyM_91012]. The type definition is provided via the header file Rte_KeyM_Type.h [SWS_KeyM_91012].

Limitations and Memory Management

When using KeyM_CryptoKeyDataType as a pointer to byte buffers, specific constraints must be observed:

• Interpretation: Since the type is specified as a simple byte pointer (uint8*) [SWS_KeyM_91012], the allocation, sizing, and validity of the referenced memory are presumably the responsibility of the respective caller. Question Q-07c167f400cbfb9c (open)
• Interpretation: When passed as an output buffer, it should presumably be ensured that the referenced memory area is large enough for the key or crypto data to be accommodated, in order to prevent buffer overflows. Question (open)
• Interpretation: For concurrent access to the referenced buffer, additional synchronization measures by the calling software might be required, since the type itself does not provide any synchronization mechanism. Question (open)

Integration

Callers passing cryptographic key or certificate data to KeyM interfaces or receiving them from them include Rte_KeyM_Type.h to obtain access to the typed pointer definition of KeyM_CryptoKeyDataType [SWS_KeyM_91012].

The enumeration type KeyM_ResultType specifies the result of asynchronous functions of module KeyM for key and certificate management [SWS_KeyM_91008]. The type is provided via header file Rte_KeyM_Type.h and serves to report the outcome of a requested asynchronous work request [SWS_KeyM_91008].

The range of values comprises standardized status and error codes for differentiated evaluation by callers [SWS_KeyM_91008]:

• KEYM_RT_OK (0x00): The key management operation completed successfully [SWS_KeyM_91008].
• KEYM_RT_NOT_OK (0x01): A general error occurred during the key management operation [SWS_KeyM_91008].
• KEYM_RT_KEY_CERT_INVALID (0x02): The referenced key or certificate is invalid and cannot be used for the operation [SWS_KeyM_91008].
• KEYM_RT_KEY_CERT_WRITE_FAIL (0x03): Writing the key or certificate to the intended destination memory failed [SWS_KeyM_91008].
• KEYM_RT_KEY_CERT_UPDATE_FAIL (0x04): General error during key or certificate update that could not be specified by a more specific code [SWS_KeyM_91008].
• KEYM_RT_CERT_INVALID_CHAIN_OF_TRUST (0x05): Certificate verification failed due to an invalid chain of trust [SWS_KeyM_91008].

Callers of asynchronous KeyM functions must evaluate this return type in order to react specifically to invalid chains of trust, memory access errors, or incorrect key material in the event of an error [SWS_KeyM_91008].

The structure KeyM_CertDataType is used in the module KeyM for passing and exchanging certificate data via interface functions [SWS_KeyM_00041]. The type definition is available via the header file KeyM.h [SWS_KeyM_00041].

The structure bundles two essential elements [SWS_KeyM_00041]:

• certDataLength: Element of type uint32 that specifies the length of the certificate data [SWS_KeyM_00041].
• certData: Element of type VoidPtr that references as a pointer directly to the certificate data in a local data area of the caller [SWS_KeyM_00041].

Since certData points to memory areas in the caller's local context [SWS_KeyM_00041], buffer management is the responsibility of the calling instance. Interpretation: The caller is likely required to ensure that the referenced memory remains valid for the entire execution duration of the respective interface function and comprises at least the number of bytes specified in certDataLength. Question Q-7da9d5ed0975ddbd (open) In addition, it is assumed that for a length greater than zero, a valid pointer not equal to NULL must be passed to avoid erroneous memory accesses within the interface function.