secure element
The idea is to introduce a new LoRaMac Crypto module which is doing everything to secure/unsecure messages. This enables to use a Secure Element (SE) which provides specific LoRaWAN cryptographic functionalities, a secure memory or only basic aes/cmac functionalities. Through this security tasks can be completely or partly performed in soft- or hardware.
The new structure defines two layers of abstraction. The lower layer (secure-element) defines the minimum range of functionality to full fill requirements of the LoRaWAN-Secure element specification. That means it defines the basic secure element. In most application scenarios this part is performed on a secure element device which is connected via SPI , UART or any other inter processor communication. Anyway the LoRaMac Stack includes a software implementation of it. The second layer is called LoRaMacCrypto Module and defines a API to perform all security tasks required by the LoRaMac. It separates the security task from the core stack tasks. Since the task of securing a message is closely linked with the tasks of serializing and parsing messages, the LoRaMacCrypto is calling also the Serializer and Parser API. Those functionalities are still part of the LoRaMac stack.
The following figure shows how the layers work with each other. The architecture on the left side shows the case of a pure software implementation. On the right side it shows a combination with a secure element device.
The new architecture also allows to integrate a more advanced Secure Element which undertake other tasks such as the preparation of messages. The following figure shows greatest considered scope of functionality.
The file-directory tree of the stack repository shows where you can find the related files.
├── apps
├── boards
├── mac
│ ├── LoRaMacCrypto.c
│ ├── LoRaMacCrypto.h ← LoRaMac Crypto Module API
│ ├── LoRaMacHeaderTypes.h
│ ├── LoRaMacMessageTypes.h
│ ├── LoRaMacParser.c
│ ├── LoRaMacParser.h ← LoRaMac Parser API
│ ├── LoRaMacSerializer.c
│ ├── LoRaMacSerializer.h ← LoRaMac Serializer API
│ ├── secure-element.h ← Secure Element API
│ ├── ...
│ └── region
├── peripherals
│ ├── atecc608a-tnglora-se ← ATECC608A-TNGLORA Secure Element Implementation
│ | |── cryptoauthlib
| | | └── ...
│ │ ├── atca_config.h
│ │ ├── atecc608a-tnglora-se.c
│ │ ├── atecc608a-tnglora-se-hal.c
│ │ ├── atecc608a-tnglora-se-hal.h
│ │ └── se-identity.h
│ ├── lr1110-se ← LR1110 radio Secure Element Implementation
│ │ ├── lr1110-se.c
│ │ ├── lr1110-se-hal.c
│ │ ├── lr1110-se-hal.h
│ │ └── se-identity.h
│ ├── soft-se ← Software Secure Element Implementation
│ │ ├── aes.c
│ │ ├── aes.h
│ │ ├── cmac.c
│ │ ├── cmac.h
│ │ ├── se-identity.h
│ │ ├── soft-se.c
│ │ ├── soft-se-hal.c
│ │ └── soft-se-hal.h
│ └── ...
├── radio
└── system
/*!
* \file LoRaMacCrypto.h
*
* \brief LoRa MAC layer cryptographic functionality implementation
*
* \copyright Revised BSD License, see section \ref LICENSE.
*
* \code
* ______ _
* / _____) _ | |
* ( (____ _____ ____ _| |_ _____ ____| |__
* \____ \| ___ | (_ _) ___ |/ ___) _ \
* _____) ) ____| | | || |_| ____( (___| | | |
* (______/|_____)_|_|_| \__)_____)\____)_| |_|
* (C)2013-2017 Semtech
*
* ___ _____ _ ___ _ _____ ___ ___ ___ ___
* / __|_ _/_\ / __| |/ / __/ _ \| _ \/ __| __|
* \__ \ | |/ _ \ (__| ' <| _| (_) | / (__| _|
* |___/ |_/_/ \_\___|_|\_\_| \___/|_|_\\___|___|
* embedded.connectivity.solutions===============
*
* \endcode
*
* \author Miguel Luis ( Semtech )
*
* \author Gregory Cristian ( Semtech )
*
* \author Daniel Jaeckle ( STACKFORCE )
*
* \author Johannes Bruder ( STACKFORCE )
*
* addtogroup LORAMAC
* \{
*
*/
#ifndef __LORAMAC_CRYPTO_H__
#define __LORAMAC_CRYPTO_H__
#ifdef __cplusplus
extern "C"
{
#endif
#include <stdlib.h>
#include <stdint.h>
#include <stdbool.h>
#include "utilities.h"
#include "LoRaMacTypes.h"
#include "LoRaMacMessageTypes.h"
/*!
* Indicates if LoRaWAN 1.1.x crypto scheme is enabled
*/
#define USE_LRWAN_1_1_X_CRYPTO 0
/*!
* Indicates if a random devnonce must be used or not
*/
#define USE_RANDOM_DEV_NONCE 1
/*!
* Indicates if JoinNonce is counter based and requires to be checked
*/
#define USE_JOIN_NONCE_COUNTER_CHECK 0
/*!
* Initial value of the frame counters
*/
#define FCNT_DOWN_INITAL_VALUE 0xFFFFFFFF
/*!
* LoRaMac Cryto Status
*/
typedef enum eLoRaMacCryptoStatus
{
/*!
* No error occurred
*/
LORAMAC_CRYPTO_SUCCESS = 0,
/*!
* MIC does not match
*/
LORAMAC_CRYPTO_FAIL_MIC,
/*!
* Address does not match
*/
LORAMAC_CRYPTO_FAIL_ADDRESS,
/*!
* JoinNonce was not greater than previous one.
*/
LORAMAC_CRYPTO_FAIL_JOIN_NONCE,
/*!
* RJcount0 reached 2^16-1
*/
LORAMAC_CRYPTO_FAIL_RJCOUNT0_OVERFLOW,
/*!
* FCNT_ID is not supported
*/
LORAMAC_CRYPTO_FAIL_FCNT_ID,
/*!
* FCntUp/Down check failed (new FCnt is smaller than previous one)
*/
LORAMAC_CRYPTO_FAIL_FCNT_SMALLER,
/*!
* FCntUp/Down check failed (duplicated)
*/
LORAMAC_CRYPTO_FAIL_FCNT_DUPLICATED,
/*!
* MAX_GAP_FCNT check failed
*/
LORAMAC_CRYPTO_FAIL_MAX_GAP_FCNT,
/*!
* Not allowed parameter value
*/
LORAMAC_CRYPTO_FAIL_PARAM,
/*!
* Null pointer exception
*/
LORAMAC_CRYPTO_ERROR_NPE,
/*!
* Invalid key identifier exception
*/
LORAMAC_CRYPTO_ERROR_INVALID_KEY_ID,
/*!
* Invalid address identifier exception
*/
LORAMAC_CRYPTO_ERROR_INVALID_ADDR_ID,
/*!
* Invalid LoRaWAN specification version
*/
LORAMAC_CRYPTO_ERROR_INVALID_VERSION,
/*!
* Incompatible buffer size
*/
LORAMAC_CRYPTO_ERROR_BUF_SIZE,
/*!
* The secure element reports an error
*/
LORAMAC_CRYPTO_ERROR_SECURE_ELEMENT_FUNC,
/*!
* Error from parser reported
*/
LORAMAC_CRYPTO_ERROR_PARSER,
/*!
* Error from serializer reported
*/
LORAMAC_CRYPTO_ERROR_SERIALIZER,
/*!
* RJcount1 reached 2^16-1 which should never happen
*/
LORAMAC_CRYPTO_ERROR_RJCOUNT1_OVERFLOW,
/*!
* Undefined Error occurred
*/
LORAMAC_CRYPTO_ERROR,
}LoRaMacCryptoStatus_t;
/*!
* Signature of callback function to be called by the LoRaMac Crypto module when the
* non-volatile context have to be stored. It is also possible to save the entire
* crypto module context.
*
*/
typedef void ( *LoRaMacCryptoNvmEvent )( void );
/*!
* Initialization of LoRaMac Crypto module
* It sets initial values of volatile variables and assigns the non-volatile context.
*
* \param[IN] cryptoNvmCtxChanged - Callback function which will be called when the
* non-volatile context have to be stored.
* \retval - Status of the operation
*/
LoRaMacCryptoStatus_t LoRaMacCryptoInit( LoRaMacCryptoNvmEvent cryptoNvmCtxChanged );
/*!
* Sets the LoRaWAN specification version to be used.
*
* \warning This function should be used for ABP only. In case of OTA the version will be set automatically.
*
* \param[IN] version - LoRaWAN specification version to be used.
*
* \retval - Status of the operation
*/
LoRaMacCryptoStatus_t LoRaMacCryptoSetLrWanVersion( Version_t version );
/*!
* Restores the internal nvm context from passed pointer.
*
* \param[IN] cryptoNmvCtx - Pointer to non-volatile crypto module context to be restored.
* \retval - Status of the operation
*/
LoRaMacCryptoStatus_t LoRaMacCryptoRestoreNvmCtx( void* cryptoNvmCtx );
/*!
* Returns a pointer to the internal non-volatile context.
*
* \param[IN] cryptoNvmCtxSize - Size of the module non-volatile context
* \retval - Points to a structure where the module store its non-volatile context
*/
void* LoRaMacCryptoGetNvmCtx( size_t* cryptoNvmCtxSize );
/*!
* Returns updated fCntID downlink counter value.
*
* \param[IN] fCntID - Frame counter identifier
* \param[IN] maxFcntGap - Maximum allowed frame counter difference (only necessary for L2 LW1.0.x)
* \param[IN] frameFcnt - Received frame counter (used to update current counter value)
* \param[OUT] currentDown - Current downlink counter value
* \retval - Status of the operation
*/
LoRaMacCryptoStatus_t LoRaMacCryptoGetFCntDown( FCntIdentifier_t fCntID, uint16_t maxFCntGap, uint32_t frameFcnt, uint32_t* currentDown );
/*!
* Returns updated fCntUp uplink counter value.
*
* \param[IN] currentUp - Uplink counter value
* \retval - Status of the operation
*/
LoRaMacCryptoStatus_t LoRaMacCryptoGetFCntUp( uint32_t* currentUp );
/*!
* Provides multicast context.
*
* \param[IN] multicastList - Pointer to the multicast context list
*
* \retval - Status of the operation
*/
LoRaMacCryptoStatus_t LoRaMacCryptoSetMulticastReference( MulticastCtx_t* multicastList );
/*!
* Sets a key
*
* \param[IN] keyID - Key identifier
* \param[IN] key - Key value (16 byte), if its a multicast key it must be encrypted with McKEKey
* \retval - Status of the operation
*/
LoRaMacCryptoStatus_t LoRaMacCryptoSetKey( KeyIdentifier_t keyID, uint8_t* key );
/*!
* Prepares the join-request message.
* It computes the mic and add it to the message.
*
* \param[IN/OUT] macMsg - Join-request message object
* \retval - Status of the operation
*/
LoRaMacCryptoStatus_t LoRaMacCryptoPrepareJoinRequest( LoRaMacMessageJoinRequest_t* macMsg );
/*!
* Prepares a rejoin-request type 1 message.
* It computes the mic and add it to the message.
*
* \param[IN/OUT] macMsg - Rejoin message object
* \retval - Status of the operation
*/
LoRaMacCryptoStatus_t LoRaMacCryptoPrepareReJoinType1( LoRaMacMessageReJoinType1_t* macMsg );
/*!
* Prepares a rejoin-request type 0 or 2 message.
* It computes the mic and add it to the message.
*
* \param[IN/OUT] macMsg - Rejoin message object
* \retval - Status of the operation
*/
LoRaMacCryptoStatus_t LoRaMacCryptoPrepareReJoinType0or2( LoRaMacMessageReJoinType0or2_t* macMsg );
/*!
* Handles the join-accept message.
* It decrypts the message, verifies the MIC and if successful derives the session keys.
*
* \param[IN] joinReqType - Type of last join-request or rejoin which triggered the join-accept response
* \param[IN] joinEUI - Join server EUI (8 byte)
* \param[IN/OUT] macMsg - Join-accept message object
* \retval - Status of the operation
*/
LoRaMacCryptoStatus_t LoRaMacCryptoHandleJoinAccept( JoinReqIdentifier_t joinReqType, uint8_t* joinEUI, LoRaMacMessageJoinAccept_t* macMsg );
/*!
* Secures a message (encryption + integrity).
*
* \param[IN] fCntUp - Uplink sequence counter
* \param[IN] txDr - Data rate used for the transmission
* \param[IN] txCh - Index of the channel used for the transmission
* \param[IN/OUT] macMsg - Data message object
* \retval - Status of the operation
*/
LoRaMacCryptoStatus_t LoRaMacCryptoSecureMessage( uint32_t fCntUp, uint8_t txDr, uint8_t txCh, LoRaMacMessageData_t* macMsg );
/*!
* Unsecures a message (decryption + integrity verification).
*
* \param[IN] addrID - Address identifier
* \param[IN] address - Address
* \param[IN] fCntID - Frame counter identifier
* \param[IN] fCntDown - Downlink sequence counter
* \param[IN/OUT] macMsg - Data message object
* \retval - Status of the operation
*/
LoRaMacCryptoStatus_t LoRaMacCryptoUnsecureMessage( AddressIdentifier_t addrID, uint32_t address, FCntIdentifier_t fCntID, uint32_t fCntDown, LoRaMacMessageData_t* macMsg );
/*!
* Derives the McRootKey from the AppKey.
*
* 1.0.x
* McRootKey = aes128_encrypt(AppKey, 0x00 | pad16)
*
* 1.1.x
* McRootKey = aes128_encrypt(AppKey, 0x20 | pad16)
*
* \param[IN] keyID - Key identifier of the root key to use to perform the derivation ( AppKey )
* \retval - Status of the operation
*/
LoRaMacCryptoStatus_t LoRaMacCryptoDeriveMcRootKey( KeyIdentifier_t keyID );
/*!
* Derives the McKEKey from the McRootKey.
*
* McKEKey = aes128_encrypt(McRootKey , 0x00 | pad16)
*
* \param[IN] keyID - Key identifier of the root key to use to perform the derivation ( McRootKey )
* \retval - Status of the operation
*/
LoRaMacCryptoStatus_t LoRaMacCryptoDeriveMcKEKey( KeyIdentifier_t keyID );
/*!
* Derives a Multicast group key pair ( McAppSKey, McNwkSKey ) from McKey
*
* McAppSKey = aes128_encrypt(McKey, 0x01 | McAddr | pad16)
* McNwkSKey = aes128_encrypt(McKey, 0x02 | McAddr | pad16)
*
* \param[IN] addrID - Address identifier to select the multicast group
* \param[IN] mcAddr - Multicast group address (4 bytes)
* \retval - Status of the operation
*/
LoRaMacCryptoStatus_t LoRaMacCryptoDeriveMcSessionKeyPair( AddressIdentifier_t addrID, uint32_t mcAddr );
/*! \} addtogroup LORAMAC */
#ifdef __cplusplus
}
#endif
#endif // __LORAMAC_CRYPTO_H__/*!
* \file secure-element.h
*
* \brief Secure Element driver API
*
* \copyright Revised BSD License, see section \ref LICENSE.
*
* \code
* ______ _
* / _____) _ | |
* ( (____ _____ ____ _| |_ _____ ____| |__
* \____ \| ___ | (_ _) ___ |/ ___) _ \
* _____) ) ____| | | || |_| ____( (___| | | |
* (______/|_____)_|_|_| \__)_____)\____)_| |_|
* (C)2013 Semtech
*
* ___ _____ _ ___ _ _____ ___ ___ ___ ___
* / __|_ _/_\ / __| |/ / __/ _ \| _ \/ __| __|
* \__ \ | |/ _ \ (__| ' <| _| (_) | / (__| _|
* |___/ |_/_/ \_\___|_|\_\_| \___/|_|_\\___|___|
* embedded.connectivity.solutions===============
*
* \endcode
*
* \author Miguel Luis ( Semtech )
*
* \author Gregory Cristian ( Semtech )
*
* \author Daniel Jaeckle ( STACKFORCE )
*
* \author Johannes Bruder ( STACKFORCE )
*
* \defgroup SECUREELEMENT Secure Element API Definition
*
* \{
*
*/
#ifndef __SECURE_ELEMENT_H__
#define __SECURE_ELEMENT_H__
#ifdef __cplusplus
extern "C"
{
#endif
#include <stdint.h>
#include "LoRaMacCrypto.h"
/*!
* Secure-element keys size in bytes
*/
#define SE_KEY_SIZE 16
/*!
* Secure-element EUI size in bytes
*/
#define SE_EUI_SIZE 8
/*!
* Secure-element pin size in bytes
*/
#define SE_PIN_SIZE 4
/*!
* Return values.
*/
typedef enum eSecureElementStatus
{
/*!
* No error occurred
*/
SECURE_ELEMENT_SUCCESS = 0,
/*!
* CMAC does not match
*/
SECURE_ELEMENT_FAIL_CMAC,
/*!
* Null pointer exception
*/
SECURE_ELEMENT_ERROR_NPE,
/*!
* Invalid key identifier exception
*/
SECURE_ELEMENT_ERROR_INVALID_KEY_ID,
/*!
* Invalid LoRaWAN specification version
*/
SECURE_ELEMENT_ERROR_INVALID_LORAWAM_SPEC_VERSION,
/*!
* Incompatible buffer size
*/
SECURE_ELEMENT_ERROR_BUF_SIZE,
/*!
* Undefined Error occurred
*/
SECURE_ELEMENT_ERROR,
/*!
* Failed to encrypt
*/
SECURE_ELEMENT_FAIL_ENCRYPT,
}SecureElementStatus_t;
/*!
* Signature of callback function to be called by the Secure Element driver when the
* non volatile context have to be stored.
*
*/
typedef void ( *SecureElementNvmEvent )( void );
/*!
* Initialization of Secure Element driver
*
* \param[IN] seNvmCtxChanged - Callback function which will be called when the
* non-volatile context have to be stored.
* \retval - Status of the operation
*/
SecureElementStatus_t SecureElementInit( SecureElementNvmEvent seNvmCtxChanged );
/*!
* Restores the internal nvm context from passed pointer.
*
* \param[IN] seNvmCtx - Pointer to non-volatile module context to be restored.
* \retval - Status of the operation
*/
SecureElementStatus_t SecureElementRestoreNvmCtx( void* seNvmCtx );
/*!
* Returns a pointer to the internal non-volatile context.
*
* \param[IN] seNvmCtxSize - Size of the module non volatile context
* \retval - Points to a structure where the module store its non volatile context
*/
void* SecureElementGetNvmCtx( size_t* seNvmCtxSize );
/*!
* Sets a key
*
* \param[IN] keyID - Key identifier
* \param[IN] key - Key value
* \retval - Status of the operation
*/
SecureElementStatus_t SecureElementSetKey( KeyIdentifier_t keyID, uint8_t* key );
/*!
* Computes a CMAC of a message using provided initial Bx block
*
* \param[IN] micBxBuffer - Buffer containing the initial Bx block
* \param[IN] buffer - Data buffer
* \param[IN] size - Data buffer size
* \param[IN] keyID - Key identifier to determine the AES key to be used
* \param[OUT] cmac - Computed cmac
* \retval - Status of the operation
*/
SecureElementStatus_t SecureElementComputeAesCmac( uint8_t* micBxBuffer, uint8_t* buffer, uint16_t size, KeyIdentifier_t keyID, uint32_t* cmac );
/*!
* Verifies a CMAC (computes and compare with expected cmac)
*
* \param[IN] buffer - Data buffer
* \param[IN] size - Data buffer size
* \param[in] expectedCmac - Expected cmac
* \param[IN] keyID - Key identifier to determine the AES key to be used
* \retval - Status of the operation
*/
SecureElementStatus_t SecureElementVerifyAesCmac( uint8_t* buffer, uint16_t size, uint32_t expectedCmac, KeyIdentifier_t keyID );
/*!
* Encrypt a buffer
*
* \param[IN] buffer - Data buffer
* \param[IN] size - Data buffer size
* \param[IN] keyID - Key identifier to determine the AES key to be used
* \param[OUT] encBuffer - Encrypted buffer
* \retval - Status of the operation
*/
SecureElementStatus_t SecureElementAesEncrypt( uint8_t* buffer, uint16_t size, KeyIdentifier_t keyID, uint8_t* encBuffer );
/*!
* Derives and store a key
*
* \param[IN] version - LoRaWAN specification version currently in use.
* \param[IN] input - Input data from which the key is derived ( 16 byte )
* \param[IN] rootKeyID - Key identifier of the root key to use to perform the derivation
* \param[IN] targetKeyID - Key identifier of the key which will be derived
* \retval - Status of the operation
*/
SecureElementStatus_t SecureElementDeriveAndStoreKey( Version_t version, uint8_t* input, KeyIdentifier_t rootKeyID, KeyIdentifier_t targetKeyID );
/*!
* Process JoinAccept message.
*
* \param[IN] encJoinAccept - Received encrypted JoinAccept message
* \param[IN] encJoinAcceptSize - Received encrypted JoinAccept message Size
* \param[OUT] decJoinAccept - Decrypted and validated JoinAccept message
* \param[OUT] versionMinor - Detected LoRaWAN specification version minor field.
* - 0 -> LoRaWAN 1.0.x
* - 1 -> LoRaWAN 1.1.x
* \retval - Status of the operation
*/
SecureElementStatus_t SecureElementProcessJoinAccept( JoinReqIdentifier_t joinReqType, uint8_t* joinEui,
uint16_t devNonce, uint8_t* encJoinAccept,
uint8_t encJoinAcceptSize, uint8_t* decJoinAccept,
uint8_t* versionMinor );
/*!
* Generates a random number
*
* \param[OUT] randomNum - 32 bit random number
* \retval - Status of the operation
*/
SecureElementStatus_t SecureElementRandomNumber( uint32_t* randomNum );
/*!
* Sets the DevEUI
*
* \param[IN] devEui - Pointer to the 8-byte devEUI
* \retval - Status of the operation
*/
SecureElementStatus_t SecureElementSetDevEui( uint8_t* devEui );
/*!
* Gets the DevEUI
*
* \retval - Pointer to the 8-byte devEUI
*/
uint8_t* SecureElementGetDevEui( void );
/*!
* Sets the JoinEUI
*
* \param[IN] joinEui - Pointer to the 8-byte joinEui
* \retval - Status of the operation
*/
SecureElementStatus_t SecureElementSetJoinEui( uint8_t* joinEui );
/*!
* Gets the DevEUI
*
* \retval - Pointer to the 8-byte joinEui
*/
uint8_t* SecureElementGetJoinEui( void );
/*!
* Sets the pin
*
* \param[IN] pin - Pointer to the 4-byte pin
* \retval - Status of the operation
*/
SecureElementStatus_t SecureElementSetPin( uint8_t* pin );
/*!
* Gets the Pin
*
* \retval - Pointer to the 4-byte pin
*/
uint8_t* SecureElementGetPin( void );
/*! \} defgroup SECUREELEMENT */
#ifdef __cplusplus
}
#endif
#endif // __SECURE_ELEMENT_H__