DolphinV4 API  1.6.1.0
Functions
Security functions
sec
Collaboration diagram for Security functions:

Functions

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

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,
uint32 *  pu32RLC 
)

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.
[in,out]pu32RLCPointer to the rolling-code. Rolling-code is automatically incremented
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. In this case, 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.
TEL_RADIO_TYPE rTel;
TEL_PARAM_TYPE pTel;
MESSAGE_TYPE pMsgSec, pMsgNonSec;
SECU_TYPE secuInfo;
uint8 u8MsgBuffer[32];
uint32 u32RLC;
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();
radio_enableRx(1);
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?
if(pMsgSec.u8Choice == RADIO_CHOICE_SEC_TI)
{
sec_parseTeachIn(&pMsgSec, &secuInfo, &u32RLC); // 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 ||
pMsgSec.u8Choice == RADIO_CHOICE_SEC )
{
// 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, &u32RLC);
}
}
}
See also:
sec_convertToSecure
SEC_RESULT sec_convertToSecure ( MESSAGE_TYPE *  mssgeNonsecure,
MESSAGE_TYPE *  mssgeSecure,
SECU_TYPE *  secuInfo,
uint32 *  pu32RLC 
)

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.
[in,out]pu32RLCPointer to the rolling-code. Rolling-code is automatically incremented
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 will be 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
secuInfo provides the information of what encryption method must be used by the function. It also indicates the presence and amount of CMAC bytes, as well as the presence of a rolling code and its size. 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. Before returning, the function increments the value of secuInfo->u32RLC in +1.
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.
uint32 u32RLC;
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;
u32RLC = 0x00000001;
sec_convertToSecure(&msgNonSec, &msgSec, &secuInfo, &u32RLC);
while(1)
{
CLR_WDT();
}
See also:
sec_convertToNonsecure
SEC_RESULT sec_createTeachIn ( SECU_TYPE *  secuInfo,
uint32 *  pu32RLC,
MESSAGE_TYPE *  teachInMsg,
uint8 *  u8PSK 
)

Creates a security teach-in message.

Parameters:
[in]secuInfoPointer to the security information structure.
[in]pu32RLCPointer to the rolling-code.
[out]teachInMsgPointer to the non-secure message.
[in]u8PSKPointer to the Pre-Shared Key. Pointer to 16 bytes array expected.
Returns:
SEC_OK Function exited correctly.
SEC_SIZE_WRONG Not enough space in the teachInMsg to place the information.
Note:
secuInfo contains all the information about the secure message to create 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_parseTeachIn
SEC_RESULT sec_parseTeachIn ( MESSAGE_TYPE *  teachInMsg,
SECU_TYPE *  secInfo,
uint32 *  pu32RLC,
uint8 *  u8PSK 
)

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

Parameters:
[in,out]teachInMsgPointer to the teach-in message. It is automatically decrypted when PSK was used.
[out]secInfoPointer to the security information structure.
[out]pu32RLCPointer to the rolling-code.
[in]u8PSKPointer to the Pre-Shared Key. Pointer to 16 bytes array expected.
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_PSK_WRONG
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