 |
CANopen Slave Protocol Stack
Version 7.04.00
|
|
CANopen Slave Protocol Stack
Version 7.04.00
|
This module implements the variables and callback functions for the add-on CANopen Secure Configuration. The module adds the following objects to the object dictionary:
| Index | Description | Function / Variable | Configuration Symbol |
|---|---|---|---|
| 2D10h | Secure Object Dictionary | CosSecureConfig_Idx2D10() | - |
| 2D11h | Secure DCF Configuration | CosSecureConfig_Idx2D11() | - |
| 2D12h | Secure Configuration Checksum | CosSecureConfig_Idx2D12() | - |
| 2D14h | Secure Configuration Status | CosSecureConfig_Idx2D14() | - |
| 2D16h | Secure Configuration Error History | CosSecureConfig_Idx2D16() | - |
| 2D18h | Secure Authentication Seed | CosSecureConfig_Idx2D18() | - |
The symbol COS_SECURE_CONFIG_SUPPORT must be configured (file cos_conf.h) to enable this add-on.
The CANopen device has to ensure that the CANopen manager is entitled to perform changes in a secured object dictionary. For that reason, a seed/nonce procedure is implemented which allows to identify the CANopen manager.
The server generates a random seed (see function CosSecureConfigGetSeed()) which is used to create a nonce (see function CosSecureConfigBuildNonce()) by the server and the manager. The nonce is valid for a maximum duration of 1 second. The nonce can be used only once to gain write access to objects 2D10h and 2D11h. Access to other objects by the CANopen manager will destroy the nonce.
A full configuration of the CANopen device shall be issued by the CANopen manager for the very first configuration process. A full configuration is marked by bit 0 inside the flags field of the secure DCF header. The Secure Concise DCF can be stored by writing the value save to object 1010h. Please note that this operation must be the last entry inside the Secure Concise DCF. The contents of the Secure Concise DCF is not written by means of McNvmWrite() to a non-volatile memory. Instead, a specific API is provided, as shown in the following picture.
The functions CosSecureConfigFileLoad() and CosSecureConfigFileSave() are used for that purpose, an example is provided in the file cos_user.c .
Operations executed by the Secure Configuration module can be monitored by the CosSecureConfigEvent() function.
Macros | |
| #define | COS_SECURE_CONFIG_VERSION_MAJOR 1 |
| #define | COS_SECURE_CONFIG_VERSION_MINOR 4 |
Enumerations | |
| enum | CosSecureConfigEvent_e { eCOS_SECURE_CONFIG_EVENT_START_FULL = 1 , eCOS_SECURE_CONFIG_EVENT_START_PART = 2 , eCOS_SECURE_CONFIG_EVENT_DESTROY_NONCE = 3 , eCOS_SECURE_CONFIG_EVENT_ALLOW_ACCESS = 4 , eCOS_SECURE_CONFIG_EVENT_BLOCK_ACCESS = 5 , eCOS_SECURE_CONFIG_EVENT_DCF_APPLIED = 6 , eCOS_SECURE_CONFIG_EVENT_DCF_FAILED = 7 } |
Functions | |
| bool_t | CosSecureConfigAccessAllowed (uint16_t uwIndexV, uint8_t ubSubIndexV) |
| uint8_t * | CosSecureConfigBufferAllocate (uint32_t ulSizeV) |
| void | CosSecureConfigBufferRelease (void) |
| uint64_t | CosSecureConfigBuildNonce (uint64_t uqSeedV) |
| void | CosSecureConfigEvent (uint8_t ubSecureConfigEventV) |
| uint8_t | CosSecureConfigFileLoad (void) |
| uint8_t | CosSecureConfigFileSave (uint8_t *pubSecureConfigV, uint32_t ulSizeV) |
| uint8_t * | CosSecureConfigGetDcfBuffer (uint32_t ulSizeV) |
| uint64_t | CosSecureConfigGetSeed (void) |
The possible values for Secure Configuration events are listed in this enumeration. The function CosSecureConfigEvent() is called to inform the application about possible events.
| bool_t CosSecureConfigAccessAllowed | ( | uint16_t | uwIndexV, |
| uint8_t | ubSubIndexV ) |
| [in] | uwIndexV | Index of data element |
| [in] | ubSubIndexV | Sub-Index of data element |
true if write access is allowed, otherwise false cos_user.c provides an example and has to be adopted to the application.This function is called by the protocol stack during upon SDO / USDO access. In case the write access to the data element defined by uwIndexV and ubSubIndexV is allowed the function shall return true. By means of this function an application can allow exceptions to blocking any write access.
| uint8_t * CosSecureConfigBufferAllocate | ( | uint32_t | ulSizeV | ) |
| [in] | ulSizeV | Allocation size in number of bytes |
cos_user.c provides an example and has to be adopted to the application.This function shall allocate at least ulSizeV number of bytes as intermediate buffer when a DCF is written to object 2D11h (Secure DCF Configuration). The buffer can be release after the Secure DCF Configuration has been processed (refer to CosSecureConfigBufferRelease()).
| void CosSecureConfigBufferRelease | ( | void | ) |
cos_user.c provides an example and has to be adopted to the application.This function releases memory which has been allocated by CosSecureConfigBufferAllocate().
| uint64_t CosSecureConfigBuildNonce | ( | uint64_t | uqSeedV | ) |
| [in] | uqSeedV | Seed value |
cos_user.c provides an example and has to be adopted to the application.This function shall calculate a nonce (i.e. an arbitrary number used only once in a cryptographic communication) based on the parameter uqSeedV. This function is called by the protocol stack upon read access to object 2D18h (Secure Authentication Seed). The value of parameter uqSeedV is identical to the return value of CosSecureConfigGetSeed().
| void CosSecureConfigEvent | ( | uint8_t | ubSecureConfigEventV | ) |
| [in] | ubSecureConfigEventV | Configuration event |
cos_user.c provides an example and has to be adopted to the application.This function is called by the protocol stack in case of the following events:
Possible values for parameter ubSecureConfigEventV are defined by the enumeration CosSecureConfigEvent_e.
| uint8_t CosSecureConfigFileLoad | ( | void | ) |
cos_user.c provides an example and has to be adopted to the application.This function is used to load a concise DCF file. The function is called by the protocol stack. The function does not load the secure DCF from a non-volatile memory via the McNvmRead() call. Instead, the application must care how to load the data.
| uint8_t CosSecureConfigFileSave | ( | uint8_t * | pubSecureConfigV, |
| uint32_t | ulSizeV ) |
| [in] | pubSecureConfigV | Pointer to Secure Concise DCF file structure |
| [in] | ulSizeV | Size if Secure Concise DCF file structure |
cos_user.c provides an example and has to be adopted to the application.This function is used to store a Secure Concise DCF file. The function is called by the protocol stack upon save command to object 1010h (save all or save manufacturer-specific objects).
| uint8_t * CosSecureConfigGetDcfBuffer | ( | uint32_t | ulSizeV | ) |
| [in] | ulSizeV | Allocation size in number of bytes |
cos_user.c provides an example and has to be adopted to the application.This function shall allocate at least ulSizeV number of bytes as process buffer when a DCF is written to object 2D11h (Secure DCF Configuration). The function is only called when a full configuration is done. The allocated buffer and size is required when the secure DCF file shall be stored by means of CosSecureConfigFileSave().
| uint64_t CosSecureConfigGetSeed | ( | void | ) |
cos_user.c provides an example and has to be adopted to the application.This function returns a random seed for calculation of a nonce which is required for the Secure Configuration process. This function is called by the protocol stack upon read access to object 2D18h (Secure Authentication Seed).