Intrusion Detection System Manager (IdsM)

The synchronous and non-reentrant interface IdsM_Init serves the fundamental initialization of the module IdsM according to [SWS_IdsM_91001]. When called, the service initializes all internal variables and transitions the IdsM to the initialized state ([SWS_IdsM_00202]). Via the input parameter configPtr, the function accepts a pointer to the module-specific configuration structure ([SWS_IdsM_91001]).

The execution of IdsM_Init represents an indispensable functional precondition for the operation of the module. If an API of the IdsM other than IdsM_Init or IdsM_GetVersionInfo is called in the still uninitialized state, the module reports the error IDSM_E_PARAM_UNINIT via Det_ReportError when development detection (IdsMDevErrorDetect) is enabled ([SWS_IdsM_00203], see also error code 0x0D under [SWS_IdsM_02003]).

Specific behavioral rules apply to error handling and the call context:

• If IdsM_Init is called while the module is already in the initialized state, reinitialization of the internal variables does not take place ([SWS_IdsM_00204]).
• Instead, with IdsMDevErrorDetect enabled, the module reports the development error IDSM_E_ALREADY_INITIALIZED with the numeric value 0x0E via Det_ReportError ([SWS_IdsM_00204], [SWS_IdsM_02003]).
• The function has no return value and is defined as non-reentrant ([SWS_IdsM_91001]). It must therefore not be called concurrently or multiple times simultaneously by preempting contexts in the system.

Usage and Call Context

The function IdsM_MainFunction is called periodically and is available via the header file IdsM.h [SWS_IdsM_91000]. It has the signature void IdsM_MainFunction(void), takes no parameters, and has no return value [SWS_IdsM_91000]. The call of the function itself is synchronous, but serves for the asynchronous processing of security events (SEv) that were previously queued during synchronous API calls [SWS_IdsM_91000]. The periodic triggering is typically expected to be performed by the BSW scheduler or a cyclic operating system task. Question Q-86e2e870c3496bad (open)

Concurrency and Limitations

According to the specification, IdsM_MainFunction is classified as non-reentrant (Non Reentrant) [SWS_IdsM_91000]. The calling system environment must therefore ensure that the function is executed in only a single instance at any time and that no overlapping calls take place.

Interaction during Event Processing

The main task within the cyclic processing comprises the following aspects:

• Event buffer: After receiving an SEv, the IdsM stores it in an event buffer; these buffers are managed and filtered asynchronously within IdsM_MainFunction [SWS_IdsM_00702].
• Context data buffer: If an SEv with context data is received, the IdsM uses suitable buffers from a context data buffer pool; these buffers are also handled and filtered asynchronously in IdsM_MainFunction [SWS_IdsM_00705].
• Qualification: The SEvs stored in the event buffers are processed asynchronously to identify them as qualified security events (QSEv) [SWS_IdsM_00901].

The callback function is called synchronously and reentrantly to retrieve transmit data for segments of an I-PDU (N-PDU) [SWS_IdsM_91010]. It is available via the header IdsM_Cbk.h and serves the service ID 0x43 [SWS_IdsM_91010].

The I-PDU to be transmitted is identified via id [SWS_IdsM_91010]. The parameter info passes the destination buffer (SduDataPtr) as well as the requested byte length (SduLength); a value of 0 for SduLength (where SduDataPtr may be a NULL_PTR) serves for state changes in the parameter retry or for querying remaining data [SWS_IdsM_91010]. Via availableDataPtr, the function reports back the data amount remaining in the Tx buffer, which allows transport protocols with dynamic payload lengths (e.g., FrIsoTp) to determine the size of subsequent consecutive frames [SWS_IdsM_91010].

If retry is a NULL_PTR, copied data may be released from the buffer immediately after the copying process [SWS_IdsM_91010]. Otherwise, RetryInfoType controls the error handling: With TP_CONFPENDING, previously copied data remains in the TP buffer, whereas TP_DATACONF acknowledges and releases all data copied prior to this call [SWS_IdsM_91010]. If TpDataState is set to TP_DATARETRY, the function copies previously transmitted data again starting from the byte offset specified by TxTpDataCnt [SWS_IdsM_91010].

The function returns BUFREQ_OK upon successful complete copying [SWS_IdsM_91010]. If insufficient transmit data is available, no data is copied and BUFREQ_E_BUSY is returned, whereupon the lower-layer module can retry the call [SWS_IdsM_91010]. If the request fails, BUFREQ_E_NOT_OK is returned without data adoption [SWS_IdsM_91010].

The function IdsM_SetSecurityEvent serves as an interface for applications to report security events to the IdsM (Intrusion Detection System Manager) module [SWS_IdsM_91002].

Usage and Call Context

The call is made synchronously via the header file IdsM.h with the Service ID 0x03 [SWS_IdsM_91002]. As the sole passed parameter, the identifier of the security event is passed:

• securityEventId (IN, IdsM_SecurityEventIdType): Unique identifier of the reported security event [SWS_IdsM_91002].

The function has no return value (void) [SWS_IdsM_91002].

Error handling

If the detection of development errors (IdsMDevErrorDetect) is enabled, the module checks the parameter securityEventId against the configured security events [SWS_IdsM_02101]. If an unknown event ID is passed that was not configured in IdsMEvent, the IdsM reports the development error IDSM_E_PARAM_INVALID [SWS_IdsM_02101].

Concurrency and Limitations

The function is specified as non-reentrant (Non Reentrant) [SWS_IdsM_91002]. Concurrent or preempting calls from different contexts must therefore be synchronized or avoided by the caller.

The function IdsM_SetSecurityEventWithContextData serves as an application interface for synchronously reporting security events along with optional context data to the Intrusion Detection System Manager ([SWS_IdsM_91003]). It has no return value.

Parameters and usage

• securityEventId: Unique identifier of the reported security event ([SWS_IdsM_91003]).
• contextData: Pointer to optional context data; if no context data is available, NULL_PTR must be passed ([SWS_IdsM_91003]).
• contextDataSize: Size of the provided context data in bytes ([SWS_IdsM_91003]).

Error handling

When development error detection (IdsMDevErrorDetect) is enabled, the IdsM module performs the following checks:

• If the passed securityEventId does not originate from the security events configured in IdsMEvent, the development error IDSM_E_PARAM_INVALID is reported ([SWS_IdsM_02102]).
• If contextDataSize exceeds the maximum configured buffer size for context data (defined via the largest parameterized value of IdsMContextDataBufferSize), the development error IDSM_E_PARAM_LENGTH is reported ([SWS_IdsM_02107]).

Concurrency and Integration

The interface is specified as non-reentrant (Non Reentrant) ([SWS_IdsM_91003]). Callers must therefore ensure that concurrent calls are avoided or appropriately synchronized. The declaration is available via the header IdsM.h ([SWS_IdsM_91003]).

The synchronous function IdsM_SetSecurityEventWithCount (Service ID 0x05) represents the application interface for Smart Sensors to transmit security events (SEvs) together with a count value to the IdsM [SWS_IdsM_91018], [SWS_IdsM_00401]. This allows the IdsM to receive events with a counter precomputed by the sensor [SWS_IdsM_00401]. The function declaration is provided via the header file IdsM.h [SWS_IdsM_91018].

Upon invocation, the function expects two input parameters:

• securityEventId: Identifier of the security event of type IdsM_SecurityEventIdType [SWS_IdsM_91018].
• count: Count value of type uint16, which originates from the sensor and serves as initial start value for the event [SWS_IdsM_91018], [SWS_IdsM_00401].

The function provides no return value and defines no output parameters [SWS_IdsM_91018]. With respect to concurrency and call context, the function is declared as non-reentrant (Non Reentrant) [SWS_IdsM_91018]; parallel calls must therefore be avoided on the software side.

For error handling, it is specified that the IdsM verifies the parameters securityEventId and count when development detection (IdsMDevErrorDetect) is enabled [SWS_IdsM_02103]. If an unknown event ID is passed or count has the value 0, the development error IDSM_E_PARAM_INVALID is reported [SWS_IdsM_02103].

The function IdsM_SetSecurityEventWithCountContextData serves as an application interface for smart sensors to synchronously report security events with count value and optional context data to the [SWS_IdsM_91019].

Usage and Parameters

The call is synchronous and specified as non-reentrant (Non Reentrant) [SWS_IdsM_91019]:

• securityEventId: Unique identifier of the security event [SWS_IdsM_91019].
• count: Count value used as start value for the security event [SWS_IdsM_91019].
• contextData: Pointer to a byte array containing the context data to be provided [SWS_IdsM_00502]. If no context data is present, NULL_PTR must be passed [SWS_IdsM_91019].
• contextDataSize: Size of the passed context data in bytes [SWS_IdsM_91019]. The function supports a maximum length of up to 1500 bytes [SWS_IdsM_00501].

Error handling

When development error detection (IdsMDevErrorDetect) is enabled, the module monitors the passed arguments for validity:

• The development error IDSM_E_PARAM_INVALID is reported if an unknown securityEventId is passed or count has the value 0 [SWS_IdsM_02104].
• If contextDataSize exceeds the maximum configured buffer size (determined by the largest configured IdsMContextDataBufferSize), the IdsM reports the development error IDSM_E_PARAM_LENGTH [SWS_IdsM_02108].

The function returns no return value [SWS_IdsM_91019]; an error response in case of error is likely based primarily on reporting via the DET. Question Q-135f4b865790f34d (open)

The synchronous interface IdsM_SetSecurityEventWithTimestampCount serves Smart Sensors to report security events with a timestamp and count value to the IdsM [SWS_IdsM_91020]. The function has no return value and is available via the header file IdsM.h [SWS_IdsM_91020].

The following input parameters are processed:

• securityEventId: Specific identifier of the reported security event [SWS_IdsM_91020].
• timestamp: Timestamp for the temporal referencing of the event [SWS_IdsM_91020]. If the timestamp feature is active and a timestamp is passed, the IdsM uses it for the storage or transmission of the qualified security event (QSEv) [SWS_IdsM_01108]. If, however, the event is reported without a timestamp when the feature is active, the IdsM sets the option bit for the timestamp in the protocol header to 0 prior to transmission or storage [SWS_IdsM_01112].
• count: Count value as start value for the security event [SWS_IdsM_91020]. If no precomputed counter is available beforehand, the function can be called with the value 1 [SWS_IdsM_00405].

When development detection (IdsMDevErrorDetect) is enabled, the IdsM validates the arguments securityEventId and count. If an unknown event ID is passed or count has the value 0, the module reports the development error IDSM_E_PARAM_INVALID [SWS_IdsM_02105].

Regarding concurrency, the function is specified as non-reentrant (Non Reentrant) [SWS_IdsM_91020].

The function IdsM_SetSecurityEventWithTimestampCountContextData with service ID 0x08 serves as a standardized application interface for smart sensors to report security events together with a timestamp, a start count value, and optional context data to the Intrusion Detection System Manager (IdsM) [SWS_IdsM_91021]. The declaration of this interface is provided via header IdsM.h [SWS_IdsM_91021].

The call is executed synchronously and uses input parameters exclusively, while neither input/output parameters nor output parameters exist [SWS_IdsM_91021]. The following parameters must be passed during the call [SWS_IdsM_91021]:

• securityEventId: Identifier of the specific security event to be transmitted to the IdsM [SWS_IdsM_91021].
• timestamp: Timestamp value acting as the temporal reference of the occurred security event [SWS_IdsM_91021].
• count: Count value used by the IdsM as the initial value for the respective security event [SWS_IdsM_91021].
• contextData: Pointer to optional context data for the event; if no data is available, NULL_PTR must be passed [SWS_IdsM_91021].
• contextDataSize: Numerical specification of the size of the passed context data [SWS_IdsM_91021].

Regarding execution behavior, the function is classified as non-reentrant (Non Reentrant) and has no return value (void) [SWS_IdsM_91021]. Calling smart sensors must therefore ensure that no concurrent or overlapping calls to the interface occur [SWS_IdsM_91021].

The callback function IdsM_BswM_StateChanged ([SWS_IdsM_91005]) is called by the BswM to signal changes in the current ECU state to the Intrusion Detection System Manager (IdsM) ([SWS_IdsM_91005]). It is declared in the header file IdsM_Cbk.h and has the Service ID 0x0F ([SWS_IdsM_91005]).

The interface has the signature void IdsM_BswM_StateChanged (IdsM_Filters_BlockStateType state) ([SWS_IdsM_91005]). The input parameter state of type IdsM_Filters_BlockStateType, which represents the current ECU state ([SWS_IdsM_91005]), serves as the sole passed value. Neither input/output parameters nor output parameters are provided, and the function returns no return value ([SWS_IdsM_91005]). The call is executed synchronously and is classified as reentrant ([SWS_IdsM_91005]).

In functional interaction, this notification service serves to continuously inform the IdsM about the current state via the BswM ([SWS_IdsM_01022]). The received state information is retained in the IdsM and evaluated during subsequent asynchronous processing of block state filters (block state filter) within the main function (main function) ([SWS_IdsM_01022]). No specific error codes, return values, or notifications to the Development Error Tracer (DET) or Diagnostic Event Manager (DEM) are defined for this call within the scope of the specification.

The callback function IdsM_TpTxConfirmation is declared as a synchronous and reentrant service via the header file IdsM_Cbk.h [SWS_IdsM_91011]. According to [SWS_IdsM_01502], the module IdsM receives the confirmation from the module PduR for the transmission of a segmented PDU via this service. The call occurs as soon as the respective I-PDU has been transmitted on the underlying network [SWS_IdsM_91011].

The interface has the service ID 0x48 and returns no value (void) [SWS_IdsM_91011]. Two input parameters are passed upon the call:

• id (type PduIdType): Unique identification of the transmitted I-PDU [SWS_IdsM_91011].
• result (type Std_ReturnType): Transmits the result of the I-PDU transmission and indicates whether the transmission was successful or failed [SWS_IdsM_91011].

Specific error codes as well as DET or DEM notifications are not defined for this call in the specification. Thanks to the specified reentrancy, the function can be called by the calling layer in parallel for different I-PDUs [SWS_IdsM_91011]. Interpretation: The module IdsM is likely to evaluate the status parameter result in order to update the internal transmission status of the segmented PDU and release occupied transmit buffers upon completion. Question Q-9179efcbf744346d (open)

use

The callback function IdsM_TxConfirmation ([SWS_IdsM_91009]) is called by an underlying communication interface module to confirm the successful sending of a PDU or the failure of the transmission. It is defined synchronously, declared in IdsM_Cbk.h, and has no return value. It accepts the following parameters:

• TxPduId: Identifier of the transmitted PDU ([SWS_IdsM_91009]).
• result: Transmission result with E_OK upon successful transmission or E_NOT_OK if an error occurred ([SWS_IdsM_91009]).

Concurrency and Limitations

The function is reentrant for different PDU IDs, but non-reentrant for the same TxPduId ([SWS_IdsM_91009]).

Interplay and Sequence Conditions

A strict sequence condition applies to the transmission sequence: According to [SWS_IdsM_01499], the IdsM may call the send function PduR_IdsMTransmit again only after IdsM_TxConfirmation or IdsM_TpTxConfirmation has been called beforehand. Interpretation: The arrival of the confirmation likely serves in the IdsM as a trigger to complete the transmission and enable subsequent calls. Question Q-dd4013520e85370c (open)

Error handling

A failure of the PDU transmission is reported directly via the parameter result = E_NOT_OK ([SWS_IdsM_91009]). Specific DET or DEM error codes are not designated in the interface specification.

Usage and Call Context

The synchronous function IdsM_Dcm_GetReportingMode_RequestResults (Service ID 0x0D, header IdsM_Cbk.h) is called by the Diagnostic Communication Manager (DCM) to query the routine results of a request previously initiated via IdsM_Dcm_GetReportingMode_Start() [SWS_IdsM_91007]. Via the input parameter OpStatus, the current operation status is transmitted [SWS_IdsM_91007]. Upon successful completion, the function returns E_OK and outputs the determined reporting mode of the requested security event via the output pointer Out_ReportingMode [SWS_IdsM_91007]. If processing is not yet completed, it signals this via the return value DCM_E_PENDING [SWS_IdsM_91007].

Error handling

If the query fails, the function returns E_NOT_OK [SWS_IdsM_91007]. In this case, a specific Negative Response Code (Dcm_NegativeResponseCodeType) must be set via the parameter ErrorCode; if this remains unset, the DCM sends the error code 0x22 [SWS_IdsM_91007]. Specific DET or DEM events are not designated for this service [SWS_IdsM_91007].

Concurrency and Interaction

The function is specified as reentrant [SWS_IdsM_91007]. With regard to the call sequence, it strictly requires that the routine was previously triggered via IdsM_Dcm_GetReportingMode_Start() [SWS_IdsM_91007]. Interpretation: Parameter OpStatus is likely used by the DCM during repeated queries after DCM_E_PENDING has been returned to coordinate the progress of the diagnostic operation. Question Q-c268fab018a1f5b3 (open)

The function IdsM_Dcm_GetReportingMode_Start is called by the diagnostic module (DCM) to start the execution of a routine in the Intrusion Detection System Manager (IdsM) to query the current reporting mode of a specific security event (SEv) [SWS_IdsM_91006], [SWS_IdsM_02001]. The interface is declared in the header IdsM_Cbk.h, has the service ID 0x0C, and is specified as synchronous as well as reentrant [SWS_IdsM_91006].

Upon invocation, the DCM passes the external ID of the security event (In_SecurityEventId), the instance ID of the sensor (In_SensorInstanceId), and the operation status (OpStatus) [SWS_IdsM_91006]. As a return value, the function provides Std_ReturnType:

• E_OK: The operation was completed successfully [SWS_IdsM_91006].
• DCM_E_PENDING: The operation is not yet completed [SWS_IdsM_91006]. This likely means that the internal processing of the routine continues over multiple cycles or asynchronously until the data is available. Question Q-395a30fc3ed42497 (open)
• E_NOT_OK: The operation failed [SWS_IdsM_91006].

In case of an error (E_NOT_OK), the IdsM is required to provide a specific Negative Response Code (NRC) via the output parameter ErrorCode; if this does not occur, the DCM sends the NRC 0x22 (Conditions Not Correct) by default [SWS_IdsM_91006].

The function merely initiates the routine; the actual reading of the determined results is subsequently performed via the function IdsM_Dcm_GetReportingMode_RequestResults [SWS_IdsM_91007].

The synchronous and reentrant function IdsM_Dcm_SetReportingMode_Start is called by the diagnostic module (DCM) to start the routine for changing the reporting mode (IdsMReportingModeFilter) for a specific security event in the Intrusion Detection System Manager [SWS_IdsM_91008], [SWS_IdsM_01901]. The declaration is provided via the header file IdsM_Cbk.h [SWS_IdsM_91008].

Upon invocation, the external event ID (In_SecurityEventId), the sensor instance ID (In_SensorInstanceId), the reporting mode to be set newly (In_ReportingMode), and the operation status (OpStatus) are passed [SWS_IdsM_91008], [SWS_IdsM_01901]. The function provides the following return values:

• E_OK: The execution of the operation was completed successfully [SWS_IdsM_91008].
• DCM_E_PENDING: The processing is not yet completed and is continued asynchronously [SWS_IdsM_91008].
• E_NOT_OK: The operation has failed; in this case, a concrete Negative Response Code (NRC) must be set via the output parameter ErrorCode, since the DCM will otherwise transmit the NRC 0x22 [SWS_IdsM_91008].

If the validation of the event ID fails because an invalid Security Event Definition ID was used, the function returns E_NOT_OK and strictly sets the error code ErrorCode to DCM_E_REQUESTOUTOFRANGE [SWS_IdsM_01903].

The data type IdsM_Filters_BlockStateType serves to define bitmasks for so-called “Block State” filters of the Intrusion Detection System Manager (IdsM) according to [SWS_IdsM_91017]. The type is derived from uint16, covers the integer value range from 0 to 65535, and is made available to software modules via the header IdsM_Filters_Types.h ([SWS_IdsM_91017]).

The primary usage occurs in interaction with the Basic Software Mode Manager (BswM). Upon changes to the system or ECU state, the BswM calls the callback function IdsM_BswM_StateChanged and passes the current ECU state via parameter state of this type ([SWS_IdsM_91005]). This callback interface is declared in IdsM_Cbk.h, has no return values, and is specified as synchronous and reentrant ([SWS_IdsM_91005]).

Interpretation: Since the type is designed as a bitmask for filters, the IdsM likely compares the passed ECU state value with configured filter states to filter the capturing or blocking of security events depending on the ECU state. Question Q-00b355cc5ec6383f (open) Independent error handling with specific error codes, DET, or DEM notifications does not exist for this data type.

The data type IdsM_Filters_ReportingModeType is based on the base type uint8 and is provided for software components via the header file IdsM_Types.h [SWS_IdsM_91013]. It describes the standardized reporting modes that are applied within the reporting mode filter in the Intrusion Detection System Manager (IdsM) for the targeted processing and forwarding of security events [SWS_IdsM_91013].

The defined enumeration values control precisely whether an event is reported and which level of detail is used in the process [SWS_IdsM_91013]:

• IDSM_REPORTING_MODE_OFF (0x00): The event is suppressed and not reported to higher-level entities [SWS_IdsM_91013].
• IDSM_REPORTING_MODE_BRIEF (0x01): The event is reported in compact form without additional context data [SWS_IdsM_91013].
• IDSM_REPORTING_MODE_DETAILED (0x02): The event is reported in detail, including all relevant context data [SWS_IdsM_91013].
• IDSM_REPORTING_MODE_BRIEF_BYPASSING_FILTERS (0x03): The event bypasses subsequent filter stages and is reported unfiltered without context data [SWS_IdsM_91013].
• IDSM_REPORTING_MODE_DETAILED_BYPASSING_FILTERS (0x04): The event bypasses subsequent filter stages and is reported unfiltered including all context data [SWS_IdsM_91013].
• IDSM_REPORTING_MODE_INVALID (0xFF): Designates an invalid reporting mode within the range of values [SWS_IdsM_91013].

The values thus combine two functional control dimensions: the level of detail via the context data, as well as the deliberate circumvention of regular filtering mechanisms through bypassing [SWS_IdsM_91013]. This enables the IdsM to handle security incidents in a differentiated manner depending on criticality and filter configuration [SWS_IdsM_91013].