EO3000I_API  2.6.1.0
 All Data Structures Functions Variables Enumerations Enumerator Groups Pages
Secutity functions
Collaboration diagram for Secutity functions:

Functions

void sec_init (uint8 *pReserved, uint32 RLCwindow)
SEC_RESULT sec_convertToNonsecure (MESSAGE_TYPE *mssgeSecure, MESSAGE_TYPE *mssgeNonsecure, SECU_TYPE *secuInfo)
SEC_RESULT sec_convertToSecure (MESSAGE_TYPE *mssgeNonsecure, MESSAGE_TYPE *mssgeSecure, SECU_TYPE *secuInfo)
SEC_RESULT sec_createTeachIn (SECU_TYPE *secuInfo, MESSAGE_TYPE *teachInMsg)
SEC_RESULT sec_parseTeachIn (MESSAGE_TYPE *teachInMsg, SECU_TYPE *secInfo)

Detailed Description

Functions used for secure communication


Function Documentation

void sec_init ( uint8 *  pReserved,
uint32  RLCwindow 
)

Sets all the security module parameters

Parameters:
[in]*pReservedReserved, can be NULL.
[in]RLCwindowIn the receiver module, it sets the maximal difference between the received message rolling code and the expected rolling code
Returns:
-
Note:
A small RLCwindow value increases the security by narrowing the amount of rolling codes that the receiver will test before invalidating a message. On the other hand it increases the risk of desynchronisation between sender and receiver in the event of sender activations without the receiver "listening" to these messages.
See also:
sec_convertToNonsecure, sec_convertToSecure
SEC_RESULT sec_convertToNonsecure ( MESSAGE_TYPE mssgeSecure,
MESSAGE_TYPE mssgeNonsecure,
SECU_TYPE secuInfo 
)

Transforms a secure message into a non-secure message, decrypting the information, checking the CMAC and the rolling codes if necesssary.

Parameters:
[in]mssgeSecurePointer to the secure message.
[out]mssgeNonsecurePointer to the non-secure message.
[in]secuInfoPointer to the security information structure.
Returns:
SEC_OK Function exited correctly.
SEC_SIZE_WRONG Some of the input information contains non-valid length
SEC_RLC_OUT_OF_RANGE The received rolling code and the expected rolling code differ in a value bigger than the rolling code window. See sec_init
SEC_CMAC_WRONG The received message contains a wrong CMAC
SEC_ENC_WRONG Wrong encryption method code in the SLF byte.
Note:
Under mssgeNonsecure->u8Data can be found the decrypted data. This data does include neither rolling code nor CMAC
mssgeSecure->u8Data* mssgeNonsecure->u8Data
|--------------|----------|----------| |----------|
| data_enc | rlc | CMAC | --> | data |
|--------------|----------|----------| |----------|
*The information rlc and CMAC under mssgeSecure->u8Data is optional.
The encryption of data, data_enc, is also optional.
The figure shows simply the most general case of securing information.
Note:
SECU_TYPE secuInfo input parameter provides information about the secure message, such as the encryption method, the presence and amount of CMAC bytes, as well as rolling code and amount of bytes. With this information the function checks and decrypts the secure message.
The function reports through the return value if the secure message contains a wrong authentication code (CMAC) or the received rolling code is out of range.
When the received mssgeSecure.u8Choice field is RADIO_CHOICE_SEC, mssgeSecure->u8Data does not contain the non-secure message choice. This allows saving energy when sending. The mssgeNonsecure->u8Choice returned by the function is a general RADIO_CHOICE_NON_SEC. When the received mssgeSecure.u8Choice field is RADIO_CHOICE_SEC_ENCAPS, the mssgeSecure->u8Data includes the Choice of the original plain message. The returned mssgeNonsecure->u8Choice contains the original non-secure choice. The returned mssgeNonsecure->u8Data does not include the non-secure choice. Therefore the length of data = data_enc - 1.
The function uses the CURRENT rolling code stored under secuInfo->u32RLC for the processing of the mssgeSecure. When the result of the function is OK, the rolling code value stored under secuInfo->u32RLC is +1 the rolling code in the received radio message.
The function handles the arithmetic overflow of the rolling code. The user does not have to implement additional code to set the rolling value to 0 after the rolling code reaches its maximal value.
In the case of variable AES encryption (VAES) the data_enc field can not be longer than 16 bytes.
MESSAGE_TYPE pMsgSec, pMsgNonSec;
SECU_TYPE secuInfo;
uint8 u8MsgBuffer[32];
pMsgSec.u8Data = u8MsgBuffer;
pMsgNonSec.u8Data = u8MsgBuffer; // The address where non-secure data will be stored can be the same as the array for the secure information...
pMsgSec.u16MaxLength = sizeof(u8MsgBuffer); // ...if RAM space is a concern
pMsgNonSec.u16MaxLength = sizeof(u8MsgBuffer);
mainInit();
while(1)
{
CLR_WDT();
memset(&rTel, 0x00, sizeof(rTel));
if ((radio_getTelegram(&rTel, &pTel) == OK) &&
(msg_receive(&pMsgSec, &pTel, &rTel, &pTel) == OK))
{
// Secure teach-in telegram received?
{
sec_parseTeachIn(&pMsgSec, &secuInfo); // The details of the encryption, authentication and rolling code are stored in secuInfo
}
// Secure telegram in operation mode?
else if(pMsgSec.u8Choice == RADIO_CHOICE_SEC_ENCAPS ||
{
// The non-encrypted information is stored in pMsgNonSec.u8Choice and pMsgNonSec.u8Data.
// You may check the return value of the function to be sure that the received mssgeSecure contains correct rolling code and correct authentication CMAC
sec_convertToNonsecure(&mssgeSecure, &pMsgNonSec, &secuInfo);
}
}
}
See also:
sec_convertToSecure
SEC_RESULT sec_convertToSecure ( MESSAGE_TYPE mssgeNonsecure,
MESSAGE_TYPE mssgeSecure,
SECU_TYPE secuInfo 
)

Transforms a non-secure message into a secure message, encrypting the information, adding a CMAC and a rolling codes if necesssary.

Parameters:
[in]mssgeNonsecurePointer to the non-secure message.
[out]mssgeSecurePointer to the secure message.
[in]secuInfoPointer to the security information structure.
Returns:
SEC_OK Function exited correctly.
SEC_CHOICE_WRONG Secure telegrams can not be encrypted again.
SEC_SIZE_WRONG Some of the input information contains non-valid length
SEC_ENC_WRONG Wrong encryption method code in the SLF byte.
Note:
Under mssgeSecure->u8Data can be found the encrypted data, rolling code and CMAC.
mssgeNonsecure->u8Data mssgeSecure->u8Data*
|----------| |--------------|----------|----------|
| data | --> | data_enc | rlc | CMAC |
|----------| |--------------|----------|----------|
*the information rlc and CMAC under mssgeSecure->u8Data are optional. The encryption of data, data_enc, is also optional.
The figure shows simply the most general case of securing information.
Note:
In the case the non-secure message choice field is equal to RADIO_CHOICE_NON_SEC the non-secure data is used as payload for the calculation of data_enc. In this case the mssgeSecure->u8Choice is RADIO_CHOICE_SEC In the case the non-secure message choice field is not RADIO_CHOICE_NON_SEC, the function concatenates the non-secure choice byte to the data field for the calculation of data_enc. Therefore, the length of data_enc = length of data + 1. Where 1 is the length of the mssgeNonsecure choice. The mssgeSecure->u8Choice returned by the function is RADIO_CHOICE_SEC_ENCAPS
The data_enc field length for VAES algorithm can not be bigger than 16 bytes.
secuInfo provides the information of what encryption method is to be used, the presence and amount of CMAC bytes, as well as rolling code presence and amount of bytes. According to this information the function creates the secure message.
The function uses the CURRENT rolling code stored under secuInfo->u32RLC for the processing of the mssgeSecure. Afterwards the function increments the rolling code. After the function returns, the rolling code value under secuInfo->u32RLC is +1 than the rolling code used for the message.
The function handles the arithmetic overflow of the rolling code. The user does not have to implement additional code to set the rolling value to 0 after the rolling code reaches its maximal value.
Secure PTM telegram can only be performed when the encryption method is set to VAES. Secure PTM message are 1 data byte long. The 4 most significant bits of the data byte will be cleared by the function.
MESSAGE_TYPE msgNonSec, msgSec;
SECU_TYPE secuInfo;
uint8 u8Buff[5] = {0x00, 0x01, 0x02, 0x03};
uint8 u8BuffSec[11] ; Choice(1) + Data(4) + RLC(3) + CMAC(3) bytes stored in this buffer.
mainInit();
secuInfo.u8SLF = SLF_RLC_TX_NO + SLF_RLC_24_BIT + SLF_MAC_3_AES128 + SLF_ENC_VAES128; // Defines protocol
msgNonSec.u8Data = u8Buff;
msgSec.u8Data = u8BuffSec;
msgNonSec.u8Choice = RADIO_CHOICE_4BS;
msgNonSec.u16Length = sizeof(u8Buff) ;
msgSec.u16MaxLength = sizeof(u8BuffSec);
secuInfo.u8SLF = SLF_RLC_TX_NO + SLF_RLC_24_BIT + SLF_MAC_3_AES128 + SLF_ENC_VAES128;
secuInfo.u32RLC = 0x00000001;
sec_convertToSecure(&msgNonSec, &msgSec, &secuInfo);
while(1)
{
CLR_WDT();
}
See also:
sec_convertToNonsecure
SEC_RESULT sec_createTeachIn ( SECU_TYPE secuInfo,
MESSAGE_TYPE teachInMsg 
)

Creates a security teach-in message.

Parameters:
[in]secuInfoPointer to the security information structure.
[out]teachInMsgPointer to the non-secure message.
Returns:
SEC_OK Function exited correctly.
SEC_SIZE_WRONG Not enough space in the teachInMsg to place the information.
Note:
The function reads the information in the SLF byte
secuInfo contains all the information about the secure message such as the encryption method, the presence and amount of CMAC bytes, as well as rolling code presence and amount of bytes, and key. With this information the function creates the secure teach-in message. See within msg_send, the teach-in message example, for a description of the teach-in message structure.
The current rolling code stored under the SECU_TYPE structure is sent. The rolling code stored in SECU_TYPE is not incremented.
The function assigns the choice code RADIO_CHOICE_SEC_TI to the teachInMssge->u8Choice field.
See also:
sec_createCMAC, sec_AES128enc
SEC_RESULT sec_parseTeachIn ( MESSAGE_TYPE teachInMsg,
SECU_TYPE secInfo 
)

From a received secure teach-in message the function generates the information for the SECU_TYPE structure.

Parameters:
[in]teachInMsgPointer to the non-secure message.
[out]secInfoPointer to the security information structure.
Returns:
SEC_CHOICE_WRONG Message choice value not RADIO_CHOICE_SEC_TI
SEC_SIZE_WRONG Some of the message fields contain wrong size information
SEC_OK Message correctly parse. Security information is now in secInfo.
Note:
This function is typically implemented by the receiver. The structure of type SECU_TYPE contains the necessary information (such as the key, encryption method, etc) for the decoding of received secure telegrams. See within the msg_send function the teach-in message example for a description of the teach-in message structure.
The rolling code stored under the SECU_TYPE structure is the expected rolling code to be received from the sender.
See also:
sec_createTeachIn, sec_AES128enc