Vehicle-2-X Management (V2xM)

Initializes the V2x M module.

Provides the version information of this module.

Provides the instantaneous position information. Availab le via V2x M.h

This function is called by the V2x Gn to sign and/ or encrypt a message. An asynchronous V2x Gn_ V2x M_ Encap Confirmation call will be used to notify V2x G n of the result.

This function is called by the V2x Gn to decrypt and verify a message. An asynchronous V2x Gn_ V2x M_ Decap Confirmation call will be used to notify V2x Gn of the result.

This function is called by the V2x Fac, V2x Gn or another entity to change the Pseudonym used by the V2X - Stack, e.g. due to a Geo Networking address conflict.

This function is called by V2x Gn or from the Application Service Interface to lock the pseudonym change.

This function is called by V2x Gn or from the Application Service Interface to unlock the pseudonym change.

This function is called by V2x Gn to set the current channel busy percentage for the specified channel Available vi a V2x M_ V2x Gn.h

This function is called by V2x Gn to get the current channel busy percentage for the specified channel

Provides a pointer to the time reference of the V2X - Stack.

Scheduled Main Function of V2x M

Calculates the distance between two geographical points on earth with the assumption that they are on elevation 0.

Calculates if difference of heading values are within a tolerance value

Set available tolling z one information. This is done from V2x Fac that receives this information via CAM messages.

Service to get the certificate expiration date of the long term certificate that expires in the nearest future.

Service to get the certificate expiration date of the pseudonym certificate that expires in the nearest future.

Service for setting positional and time information relevant for the V2X-Stack

Service for getting the ITS time as estimated by the V2X-Stack

Specifies the packet transport type for Geo Networking packages. This is passed e.g. via V2x Fac and V2x Btp for the transmit path.

The Geo Networking address.

Definition of the Geo Networking destination area

Used to desc ribe the security service invoked by V2x M

Specifies the maximum tolerable time (in seconds) a Geo Networking packet can be buffered.

Requirements on packet transport coming from ITS Facilities layer

Specifies the channel type to use. Channels from ITS - G5A and ITS - G5B are used. Values matching IEEE 802.11 - 2012 channel numbers.

Specifies the Geo Networking payload.

Position - related information as defined within [25] chapter 9.5.2.

Position and time related information as defined within [25] chapter 8.2. Variation --

Pseudonym, derived from Pseudonym Certificates. The pseudonym is distributed to different modules to support privacy within the V2X System to the outside world.

Configuration data structure of the V2x M module.

Specifies the destination type for Geo Networking packages. This is passed e.g. via V2x Fac and V2x Btp for the transmit path.

Specifies the shape type for Geo Networking Areas.

The result code used to specify if a V2x Gn_ Transmit has been proce ssed successfully.

Used for return values of security related functions

Used to describe the security report after invocation of security services for Decapsulation (verify or decrypt) Variation --

The V2xM module shall implement the identity management, also known as the pseudonym. Specific V2X modules shall be notified with the current identity to e nsure a consistent value is used in each layer of the V2X Stack.

The V2xM module shall provide a mechanism to permit V2X modules to inhibit the identity change for a duration of maximum 15 minutes (e.g. during DENM event) via an API call to V2xM_LockPseudonymChange .

The V2xM module shall provide the Encap and Decap services required by V2xGn and Verification On Demand (VOD) by utilizing CSM.

Type of error Related error code Error value API service called with wrong parameter V2XM_ E_ PARAM 0x01 API service called with invalid pointer V2XM_ E_ PARAM_ POINTER 0x02 V2x M initialization failed V2XM_ E_ INIT_ FAILED 0x03 API function called before the V2x M module has been fully initialized V2XM_ E_ UNINIT 0x04

Module Header File Imported Type Csm Rte_ Csm_ Type.h Crypto _ Operation Mode Type Rte_ Csm_ Type.h Crypto _ Verify Result Type Gpt Gpt.h Gpt _ Channel Type Gpt.h Gpt _ Predef Timer Type Gpt.h Gpt _ Value Type Nv M Rte_ Nv M_ Type.h Nv M _ Block Id Type Rte_ Nv M_ Type.h Nv M _ Request Result Type Stb M Rte_ Stb M_ Type.h Stb M _ Synchronized Time Base Type Rte_ Stb M_ Type.h Stb M _ Time Base Status Type Rte_ Stb M_ Type.h Stb M _ Time Stamp Extended Type Rte_ Stb M_ Type.h Stb M _ Time Stamp Type Rte_ Stb M_ Type.h Stb M _ User Data Type Std Std_ Types.h Std _ Return Type Std_ Types.h Std _ Version Info Type V2x_ General Types Rte_ V2x M_ Type.h V2x M _ Position And Time Type Rte_ V2x M_ Type.h V2x M _ Sec Report Type V2x_ General Types.h V2x _ Chan Type V2x_ General Types.h V2x _ Pseudonym Type V2x_ General Types.h V2x _ Sec Profile Type V2x_ General Types.h V2x _ Sec Return Type WEth Trcv WEth_ General Types.h W Eth Trcv _ Get Chan Rx Param Id Type WEth_ General Types.h W Eth Trcv _ Set Chan Rx Param Id Type WEth_ General Types.h W Eth Trcv _ Set Chan Tx Param Id Type WEth_ General Types.h W Eth Trcv _ Set Radio Param Id Type

Csm _ Hash Csm.h Uses the given data to perform the hash calculation and stores the hash. Csm _ Key Element Get Csm.h Retrieves th e key element bytes from a specific key element of the key identified by the key Id and stores the key element in the memory location pointed by the key pointer. Csm _ Key Element Set Csm.h Sets the given key element bytes to the key identified by key Id. Csm _ Random - Generate Csm.h Generate a random number and stores it in the memory location pointed by the result pointer. Csm _ Signature - Generate Csm.h Uses the given data to perform the signature calculation and stores the signature in the memory locat ion pointed by the result pointer. Csm _ Signature Verify Csm.h Verifies the given MAC by comparing if the signature is generated with the given data. Eth If _ Get Chan Rx - Params Eth If.h Read values related to the receive direction of the transceiver. F or example, this could be a Channel Busy Ratio (CBR) or the average Channel Idle Time (CIT). Eth If _ Set Chan Rx - Params Eth If.h Set values related to the receive direction of a transceiver's wireless channel. For example, this could be a channel paramet er like the frequency. Eth If _ Set Chan Tx - Params Eth If.h Set values related to the transmit direction of a transceiver's wireless channel. For example, this could be the bitrate of a channel. Eth If _ Set Phys Addr Eth If.h Sets the physical source address used by the indexed controller. Eth If _ Set Radio - Params Eth If.h Set values related to a transceiver's wireless radio. For example, this could be the selection of the radio settings (channel, ...). Nv M _ Get Error Stat us Nv M.h Service to read the block dependent error/ status information. Nv M _ Read Block Nv M.h Service to copy the data of the NV block to its corresponding RAM block. Nv M _ Write Block Nv M.h Service to copy the data of the RAM block to its correspo nding NV block. V2x Fac _ V2x M _ Abort - Pseudonym Change V2x Fac_ V2x M.h This function is called by the V2x M when not all modules are OK with the pseudonym change and the change is to be rolled back. V2x Fac _ V2x M _ - Commit Pseudonym - Change V2x Fac_ V 2x M.h This function is called by the V2x M when all modules are OK with the pseudonym change and the change is to be committed. V2x Fac _ V2x M _ - Prepare Pseudonym - Change V2x Fac_ V2x M.h By this API primitive the V2x Fac module gets an indication that the given Pseudonym and hereby the Station Id is about to be changed V2x Fac _ V2x M _ Set - Ca Bs Operation V2x Fac_ V2x M.h By this API primitive the V2x Fac module gets an indication of the current operation state of the CA Basic Service. V2x Fac _ V2x M _ Set T - Gen Cam Dcc V2x Fac_ V2x M.h By this API primitive the V2x Fac module gets an indication of the current TGen Cam Dcc value. V2x Gn _ V2x M _ Abort - Pseudonym Change V2x Gn_ V2x M.h This function is called by the V2x M when not all modules are OK with the pseudonym change and the change is to be rolled back. V2x Gn _ V2x M _ - Commit Pseudonym - Change V2x Gn_ V2x M.h This function is called by the V2x M when all modules are OK with the pseudonym change and the change is to be committed. V2x Gn _ V2x M _ Decap - Confirmation V2x Gn_ V2x M.h This function is called by the V2x M when a decapsulation has been finished. V2x Gn _ V2x M _ Encap - Confirmation V2x Gn_ V2x M.h This function is called by the V2x M when an encapsulation has been finished. V2x Gn _ V2x M _ - Prepare Pseudonym - Change V2x Gn_ V2x M.h This function is called by the V2x M when a Pseudonym Change occurs to prepare the change in every module using it.

Det _ Report Error Det.h Service to report development errors. Efx _ Arc Cos _s32 - _u32 Efx.h This service computes the inverse cosine of a value. Efx _ Arc Sin _s32 - _s32 Efx.h This service computes the inverse sine of a value. Efx _ Cos _s32 - _s32 Efx.h This service computes the cosine of an angle. Efx _ Sin _s32 _s32 Efx.h This service computes the sine of an angle. Efx _ Sqrt _u32 - _u32 Efx.h This service computes the s quare root of a value Gpt _ Get Predef - Timer Value Gpt.h Delivers the current value of the desired GPT Predef Timer. Gpt _ Start Timer Gpt.h Starts a timer channel. Mfl _ Arc Cos _f32 Mfl.h Returns the arc cosine of an angle, in the range of 0.0 through pi. Mfl _ Arc Sin _f32 Mfl.h Returns the arc sine of an angle, in the range of - pi/ 2 through pi/ 2. Mfl _ Cos _f32 Mfl.h Calculates the cosine of the argument. Mfl _ Sin _f32 Mfl.h Calcula tes the sine of the argument. Mfl _ Sqrt _f32 Mfl.h Returns the square root of the operand (Val Sqrt), determined according to the following equation Stb M _ Get - Current Time Stb M.h Returns a time value (Local Time Base derived from Global Time Base) in standard format. Note: This API shall be called with locked interrupts / within an Exclusive Area to prevent interruption (i.e., the risk that the time stamp is outdated on return of the function call). Stb M _ Get - Current Time - Extended Stb M.h Returns a time value (Local Time Base derived from Global Time Base) in extended format. Note: This API shall be called with locked interrupts / within an Exclusive Area to prevent interruption (i.e., the risk that the time stamp is outdated on return of t he function call).

Name V2x M_ Vdp Comment Interfaces for Vehicle Data Provider (VDP) to get and set V2X related vehicle information in the BSW V2X - Stack Is Service true Variation -- Possible Errors 0 E_ OK Operation successful 1 E_ NOT_ OK Operation failed Operation Get Next Long Term Certificate Expiration Date Comment Service to get the certificate expiration date of the long term certificates that expires in the nearest future. Variation -- Parameters Expiration Date Type uint32 Direction OUT Comment Date is based on format Time32 that is specified in IEEE 1609.2 as mentioned in [19]. Variation -- Possible Errors E _ O K E _ N O T _ O K Operation Get Next Pseudonym Certificate Expiration Date Comment Service to get the certificate expiration date of the pseudonym certificates that expires in the nearest future. Variation -- Parameters Expiration Date Type uint32 Direction OUT Comment Date is based on format Time32 that is specified in IEEE 1609.2 as mentioned in [19] Variation -- Possible Errors E _ O K E _ N O T _ O K Operation Get Time32 Comment Service to get the current reference time. Variation -- Parameters Time32 Type uint32 Direction OUT Comment Time is based on TAI mod 2^32, where TAI is the number of elapsed TAI milliseconds since 2004 - 01 - 01 00:00:00.000. Variation -- Possible Errors E _ O K E _ N O T _ O K Operation Set Position And Time Comment Service for setting positional and time information relevant for the V2X - Stack Variation -- Parameters position And Time Type V2x M _ Position And Time Type Direction IN Comment -- Variation -- Possible Errors E _ O K E _ N O T _ O K

[SWS_V2xM_00116] ⌈The function shall store the access to the configuration structure for subsequent API calls.⌋

[SWS_V2xM_00118] Upstream requirements: SRS_BSW_00414 ⌈The Configuration pointer CfgPtr shall always have a NULL_PTR value⌋

[SWS_V2xM_00122] ⌈If development error detection is enabled: the function shall check that the service V2xM_Init() was previously called. If the check fails, the function shall raise the development error V2XM_E_UNINIT.⌋

[SWS_V2xM_00123] ⌈If development error detection is enabled: the function shall check the parameter Poti for being valid. If the check fails, the function shall raise the development error V2XM_E_PARAM_POINTER.⌋

[SWS_V2xM_00127] ⌈If development error detection is enabled: the function shall check that the service V2xM_Init() was previously called. If the check fails, the function shall raise the development error V2XM_E_UNINIT.⌋

[SWS_V2xM_00128] ⌈If development error detection is enabled: the function shall check the parameter RefTimePtr for being valid. If the check fails, the function shall raise the development error V2XM_E_PARAM_POINTER.⌋

[SWS_V2xM_00130] ⌈The function V2xM_V2xGn_ReqDecap() shall invoke CSM APIs for the verification of the data given by SecuredDataPtr.⌋(SRS_V2X_00163)

[SWS_V2xM_00135] ⌈The function V2xM_V2xGn_ReqEncap() shall encapsulate the payload of the GeoNetworking packet to be sent as defined in [19] and [17].⌋(SRS_- V2X_00406, SRS_V2X_00407)

[SWS_V2xM_00136] ⌈The function V2xM_V2xGn_ReqDecap() shall decapsulate the payload of a received GeoNetworking packet as defined in [19] and [17].⌋()

[SWS_V2xM_00142] ⌈The function V2xM_TriggerPseudonymChange() shall trig- ger the pseudonym change and update the identity of the V2X-Stack to the adjacent modules.⌋

[SWS_V2xM_00143] ⌈If development error detection is enabled: the function shall check that the service V2xM_Init() was previously called. If the check fails, the function shall raise the development error V2XM_E_UNINIT.⌋

If the pseudonym change is locked E_NOT_OK shall be returned

[SWS_V2xM_00145] ⌈The function V2xM_LockPseudonymChange() shall prevent the module from changing the pseudonym. The requirements from [23] shall apply.⌋

[SWS_V2xM_00146] ⌈If development error detection is enabled: the function shall check that the service V2xM_Init() was previously called. If the check fails, the function shall raise the development error V2XM_E_UNINIT.⌋

[SWS_V2xM_00147] ⌈If development error detection is enabled: the function shall check the parameter HandleId for being valid. If the check fails, the function shall raise the development error V2XM_E_PARAM_POINTER.⌋

[SWS_V2xM_00149] ⌈The function V2xM_UnlockPseudonymChange() shall allow the module to change the pseudonym again.⌋

[SWS_V2xM_00150] ⌈If development error detection is enabled: the function shall check that the service V2xM_Init() was previously called. If the check fails, the function shall raise the development error V2XM_E_UNINIT.⌋

[SWS_V2xM_00151] ⌈If development error detection is enabled: the function shall check the parameter HandleId for being valid. If the check fails, the function shall raise the development error V2XM_E_PARAM.⌋

Used for handling of tolling zone power reduction. If the distance to a Tolling Zone position given by V2xM_SetTollingZoneInformation is less than the distance given in protectedZoneRadius, the module shall p ush that to the WEthTrcv via the API EthIf_SetRadioParams so that WEthTrcv is able to reduce output power of specific packets. If the position drops out of the range, tolling zone power reduction shall be switched off.

Name V2x M_ Pseudonym Change Comment Interfaces for Applications to lock and unlock pseudonym changes within the V2X - BSW - Stack. Is Service true Variation -- Possible Errors 0 E_ OK Operation successful 1 E_ NOT_ OK Operation failed Operation Lock Comment Service for locking the pseudonym change. See SWS_V2xM_00078 for more information about locking the pseudonym change. Variation -- Parameters Duration Type uint16 Direction IN Comment Duration to lock. Variation -- Handle Id Type uint64 Direction OUT Comment Handle Id for manual Unlock Variation -- Possible Errors E _ O K E _ N O T _ O K Operation Unlock Comment Service for unlocking the pseudonym change. See SWS_V2xM_00079 for more information about locking the pseudonym change. Variation -- Parameters Handle Id Type uint64 Direction IN Comment Handle Id to unlock Variation -- Possible Errors E _ O K E _ N O T _ O K

Name V2x M_ Sec Comment Security related interfaces for applications Is Service true Variation -- Possible Errors 0 E_ OK Operation successful 1 E_ NOT_ OK Operation failed Operation Verify Comment Interfaces for Applications to verify messages on demand instead of verify all incoming messages, to reduce ECU load. Variation -- Parameters Transaction Id32 Type uint32 Direction IN Comment Transaction Id of the packet to be verified Variation -- Sec Report Type V2x M _ Sec Report Type Direction OUT Comment -- Variation -- Possible Errors E _ O K E _ N O T _ O K

[SWS_V2xM_00175] ⌈The V2xM shall disable CAM generation in case of unusable position (e.g. due to no position available, degenerated dead reckoning, time jitter/drift). This is done via a call to V2xFac_V2xM_SetCaBsOperation().⌋()

Name V2x M_ Geo Math Comment Interfaces for Applications to math functions Is Service true Variation -- Possible Errors 0 E_ OK Operation successful 1 E_ NOT_ OK Operation failed Operation Distance Comment Service for Calculating the distance between two geographical points Variation -- Parameters latitude A Type sint32 Direction IN Comment Latitude of geographical point A Variation -- longitude A Type sint32 Direction IN Comment Longitude of geographical point A Variation -- latitude B Type sint32 Direction IN Comment Latitude of geographical point B Variation -- longitude B Type sint32 Direction IN Comment Longitude of geographical point B Variation -- distance Type float32 Direction OUT Comment Distance between geographical points A and B in [m]. Variation -- Possible Errors E _ O K E _ N O T _ O K Operation Heading In Tolerance Comment Service for Calculating if difference of heading values are within a tolerance value Variation -- Parameters heading1 Type float32 Direction IN Comment First heading value Variation -- heading2 Type float32 Direction IN Comment Next heading value Variation -- tolerance Value Type float32 Direction IN Comment Tolerated difference between heading1 and heading2 Variation -- tolerated Type boolean Direction OUT Comment Return value Variation -- Possible Errors E _ O K E _ N O T _ O K

[SWS_V2xM_00181] ⌈If development error detection is enabled: the function shall check the parameter Distance for being valid. If the check fails, the function shall raise the development error V2XM_E_PARAM_POINTER.⌋

[SWS_V2xM_00190] ⌈The V2xM Module shall check the provided positional informa- tion. In case of a distance less than given in protectedZoneRadius, tolling zone power reduction shall be enabled.⌋()

Service port for geographical calculation requests. Variation --

Service port for pseudonym lock and unlock requests. Variation --

Service port for security operations of V2X messages. Variation --

Service port for exchange of vehicle related data. This port is used by the Vehicle Data Provider SW - C. Variation --

[SWS_V2xM_00199] ⌈The V2xM module shall support key origin authentication via the creation of a signature over internally generated public key(s), where public keys for Enrolment Certificates shall be signed with the module private key and public keys for Pseudonym Certificates shall be signed with a previously registered Enrolment Cer- tificates private key.⌋(SRS_V2X_00163, SRS_V2X_00174) Note: The "module private key" is a vehicle specific unique private key that could be generated randomly inside the HSM when the ECU is initialized in the first place

[SWS_V2xM_00202] ⌈The function V2xM_Vdp_GetNextLongTermCertificate- ExpirationDate shall check for the currently used long-term certificate (aka. Enrol- ment Credentials (EC)). If none was found, the function shall return E_NOT_OK. If a long-term certificate is in use, the expiration date of this certificate shall be provided through the parameter ExpirationDate and the function shall return E_OK.⌋

[SWS_V2xM_00203] ⌈The function V2xM_Vdp_GetNextPseudonymCertifica- teExpirationDate shall check for the currently used pseudonym certificate (aka. Authorization Tickets (AT)). If none was found, the function shall return E_NOT_OK. If a pseudonym certificate is in use, the expiration date of this certificate shall be provided through the parameter expirationDate and the function shall return E_OK.⌋

[SWS_V2xM_00204] ⌈The current position and time of the vehicle shall be set through the function V2xM_Vdp_SetPositionAndTime. If the values are accepted by the function, E_OK shall be returned, otherwise the value E_NOT_OK shall be returned.⌋

[SWS_V2xM_00205] ⌈The current ITS time of the vehicle shall be retrieved through the function V2xM_GetTime. If ITS time was successfully retrieved by the function, E_OK shall be returned, otherwise the value E_NOT_OK shall be returned.⌋()

[SWS_V2xM_20170] ⌈The V2xM module shall use for sending messages digital signa- tures and certificates based on ECDSA that is specified in IEEE 1609.2 as mentioned in [17].⌋(SRS_V2X_00163) Note: Additionally, [18] requires implementation of the elliptic curve brainpool P256r1 to sign messages.

(MAC Source Address, StationId in CAM/DENM, GN Source Address) shall be derive d from the "Certificate digest" / "hashedId8". The required number of least significant bytes of the "Certificate digest" / "hashedId8" shall be used as respective identifier. ⌋ ( SRS_V2X_00010 ) [SWS_V2xM_00005] The V2xM module shall provide a mechanism to permit V2X modules to inhibit the identity change for a duration of maximum 15 minutes (e.g. during DENM event) via an API call to V2xM_LockPseudonymChange .

[SWS_V2xM_20460] ⌈The V2X Management module shall implement a protected zone center position list. The minimum is to build in the official list provided by the ASECAP (not supposed to be updated except by a firmware update). Protected Zones with identical protectedZone ID may be seen as a single station. In case the ASECAP database and the CEN-DSRC mitigation CAMs contains a valid protection zone with the identical protectedZone ID mitigation shall be done only based on the CEN-DSRC mitigation CAM content.⌋()