Control whether seed/key security is required for CCP calibration, data acquisition and/or reprogramming.
None (Main library). (See Section 2.3, “Licensed Features”.)
To prevent third parties recalibrating or reprogramming modules, manufacturers typically enable CCP seed/key security for production modules. This requires a valid seed/key exchange to take place with the calibration tool, where the module generates a seed (usually at random) and the calibration tool must respond with the correct key value corresponding to that seed, calculated by a secret algorithm known to the module and the calibration tool.
To ensure that CCP seed/key security is also used during reprogramming mode, the functions used to generate the seed (if required) and validate the key are copied to non-volatile storage by the application. The reprogramming mode software retrieves the functions from non-volatile storage, and copies them to RAM for execution.
There are three CCP privilege levels: calibration, data acquisition, and programming. These privilege levels can be individually enabled or disabled. For instance, it is possible to enable reprogramming access whilst calibration and data acquisition access remains disabled. The calibration tool may impose further restrictions on how levels can be accessed.
CCP seed/key security is a standard feature of the protocol; however configuring it on different calibration/programming tools requires some knowledge of that tool's operation. Support will currently only be given for CCP seed/key security on PiSnoop (see Section 2.2, “PiSnoop”), Vector CANape (see Section 2.5, “Vector CANape”), and ATI Vision (see Section 2.3, “ATI Vision”).
- Seed generator function
The seed generator function must be of the form:
void seed_generator(const U8 privilege_level, U8 *const seed)privilege_levelspecifies the privilege level for which a seed is being requested. Values are fixed by the CCP standard as:- 0x01 (1): Calibration
- 0x02 (2): Data acquisition
- 0x40 (64): Programming
seedis a four-byte array. This will initially contain values generated by a 32-bit random number algorithm within the OpenECU platform. The seed generator function may choose to leave these values intact, or may choose to set its own values in theseedarray.- Key validator function
The key validator function must be of the form:
BOOL key_validator(const U8 privilege_level, const U8 *const seed, const U8 *const key, const U8 key_size)privilege_levelspecifies the privilege level for which a seed is being requested.seedis a four-byte array containing the last seed value passed to the calibration tool.keyis an array of up to six bytes whose length is specified bykey_size. This contains the key passed back by the calibration tool.The CCP 2.1 specification for the CCP_UNLOCK command has a six-byte field for the key, although in practice most implementations only use four bytes. The contents of the remaining bytes are often undefined, so the key validator must take care to match the expected seed-key algorithm.
The function must return
TRUEif the key is valid for the seed, orFALSEif it is not.- Implementing seed/key functions
Because the seed generator and key validator functions will be relocated and run during reprogramming mode, it is ESSENTIAL that these functions do NOT access any global or static storage OR call any functions. If this is not the case, relocating and invoking the function in reprogramming mode will have unexpected consequences, because the function will read/write/execute memory at addresses which are not valid when in reprogramming mode. These consequences may include stuck outputs resulting in physical damage to hardware or electrical damage to the ECU, and/or complete permanent disablement of the ECU.
- Diab implementation considerations
If the application is built using the Diab compiler, then the file containing these functions should be specified for compilation as normal. It is frequently the case that seed/key functions are supplied only as object or library code for security reasons, in which case the file must have been compiled with PowerPC variable bit length (VLE) instructions.
- GCC implementation considerations
If the application is built using GCC, then the file containing these functions must also contain section attribute specifiers to place the code in sections that correspond to the names of the security functions. The attribute specifiers must be applied to the function prototypes in the form:
void seed_generator(const U8 privilege_level, U8 *const seed) __attribute__ ((section (".seed_generator")));It is frequently the case that seed/key functions are supplied only as object or library code for security reasons, in which case the file must have been compiled without PowerPC variable bit length (VLE) instructions.
The CAN bus for which CCP security will be implemented. A pcp_CCPConfiguration block must also exist in the design which configures CCP for this CAN bus. If this does not exist, an error will be reported.
Value type: List Calibratable: No Whether CCP seed/key security is required for this CCP privilege level.
Value type: Boolean Calibratable: No ECU seed generator function (optional)
If required, the name of the C function which generates the seed value. If this is not specified, a random 4-byte value will be generated by the OpenECU platform and used as a seed instead.
Value type: String Calibratable: No The name of the C function which validates the key value transmitted by the calibration tool. If this is not specified, an error will be reported.
Value type: String Calibratable: No If required, the name of the DLL supplying the key generation algorithm for the calibration tool. This will typically only be required if the RTW build is required to generate ASAP2 (A2L) files to configure the calibration tool. If this is not specified, security will not be configured in the A2L files, although typically the user will still be able to configure security manually from within the calibration tool.
Value type: String Calibratable: No ASAP security DLL function (optional)
If required, the name of the function within the DLL supplying the key generation algorithm. If unspecified, this will default to using the ASAP1A/ASAP2 standard function name
ASAP1A_CCP_ComputeKeyFromSeed. Note that some calibration tools do not permit the function name to be specified; see the relevant section for the calibration tool to be used for further details.Value type: String Calibratable: No Algorithm development mode (unsecure)
Whether the ECU should ignore security algorithms when reprogramming mode is entered as a result of the module powering up with FEPS applied.
This option allows a security algorithm to be tested without the risk of putting the ECU in a state where it cannot be reprogrammed. Otherwise, an error in the security algorithm will necessitate returning the ECU to Pi for servicing.
Value type: Boolean Calibratable: No
The file(s) containing seed generator and key validator functions must be referenced by the model. In Simulink, select the "Custom Code" option (found alongside other code generation/RTW model build options; the menu item depends on MATLAB version). If these functions are provided as uncompiled C, add the files to the list of "Include list of additional: Source files". If these functions are provided as precompiled object or library files (as is frequently done for security reasons), add them to the list of "Include list of additional: Libraries". RTW will then compile (if necessary) and link these files as part of the build.
Note that if incorrect function names are specified for seed generator or key validator functions, if the functions do not have the correct prototype, or if the relevant files are not compiled/linked in the model, then the build will fail at the link stage. If this occurs, check that function names and file names are specified correctly.