LoRa MAC layer cryptographic functionality implementation. More...

#include <stdlib.h>
#include <stdint.h>
#include <stdbool.h>
#include "utilities.h"
#include "LoRaMacTypes.h"
#include "LoRaMacMessageTypes.h"

#define	USE_LRWAN_1_1_X_CRYPTO 0

#define	USE_RANDOM_DEV_NONCE 1

#define	USE_JOIN_NONCE_COUNTER_CHECK 0

#define	FCNT_DOWN_INITAL_VALUE 0xFFFFFFFF

enum	LoRaMacCryptoStatus_t { LORAMAC_CRYPTO_SUCCESS = 0, LORAMAC_CRYPTO_FAIL_MIC, LORAMAC_CRYPTO_FAIL_ADDRESS, LORAMAC_CRYPTO_FAIL_JOIN_NONCE, LORAMAC_CRYPTO_FAIL_RJCOUNT0_OVERFLOW, LORAMAC_CRYPTO_FAIL_FCNT_ID, LORAMAC_CRYPTO_FAIL_FCNT_SMALLER, LORAMAC_CRYPTO_FAIL_FCNT_DUPLICATED, LORAMAC_CRYPTO_FAIL_MAX_GAP_FCNT, LORAMAC_CRYPTO_FAIL_PARAM, LORAMAC_CRYPTO_ERROR_NPE, LORAMAC_CRYPTO_ERROR_INVALID_KEY_ID, LORAMAC_CRYPTO_ERROR_INVALID_ADDR_ID, LORAMAC_CRYPTO_ERROR_INVALID_VERSION, LORAMAC_CRYPTO_ERROR_BUF_SIZE, LORAMAC_CRYPTO_ERROR_SECURE_ELEMENT_FUNC, LORAMAC_CRYPTO_ERROR_PARSER, LORAMAC_CRYPTO_ERROR_SERIALIZER, LORAMAC_CRYPTO_ERROR_RJCOUNT1_OVERFLOW, LORAMAC_CRYPTO_ERROR }

typedef void(*	LoRaMacCryptoNvmEvent) (void)

LoRaMacCryptoStatus_t	LoRaMacCryptoInit (LoRaMacCryptoNvmEvent cryptoNvmCtxChanged)

LoRaMacCryptoStatus_t	LoRaMacCryptoSetLrWanVersion (Version_t version)

LoRaMacCryptoStatus_t	LoRaMacCryptoRestoreNvmCtx (void *cryptoNvmCtx)

void *	LoRaMacCryptoGetNvmCtx (size_t *cryptoNvmCtxSize)

LoRaMacCryptoStatus_t	LoRaMacCryptoGetFCntDown (FCntIdentifier_t fCntID, uint16_t maxFCntGap, uint32_t frameFcnt, uint32_t *currentDown)

LoRaMacCryptoStatus_t	LoRaMacCryptoGetFCntUp (uint32_t *currentUp)

LoRaMacCryptoStatus_t	LoRaMacCryptoSetMulticastReference (MulticastCtx_t *multicastList)

LoRaMacCryptoStatus_t	LoRaMacCryptoSetKey (KeyIdentifier_t keyID, uint8_t *key)

LoRaMacCryptoStatus_t	LoRaMacCryptoPrepareJoinRequest (LoRaMacMessageJoinRequest_t *macMsg)

LoRaMacCryptoStatus_t	LoRaMacCryptoPrepareReJoinType1 (LoRaMacMessageReJoinType1_t *macMsg)

LoRaMacCryptoStatus_t	LoRaMacCryptoPrepareReJoinType0or2 (LoRaMacMessageReJoinType0or2_t *macMsg)

LoRaMacCryptoStatus_t	LoRaMacCryptoHandleJoinAccept (JoinReqIdentifier_t joinReqType, uint8_t joinEUI, LoRaMacMessageJoinAccept_t macMsg)

LoRaMacCryptoStatus_t	LoRaMacCryptoSecureMessage (uint32_t fCntUp, uint8_t txDr, uint8_t txCh, LoRaMacMessageData_t *macMsg)

LoRaMacCryptoStatus_t	LoRaMacCryptoUnsecureMessage (AddressIdentifier_t addrID, uint32_t address, FCntIdentifier_t fCntID, uint32_t fCntDown, LoRaMacMessageData_t *macMsg)

LoRaMacCryptoStatus_t	LoRaMacCryptoDeriveMcRootKey (uint8_t versionMinor, KeyIdentifier_t keyID)

LoRaMacCryptoStatus_t	LoRaMacCryptoDeriveMcKEKey (KeyIdentifier_t keyID)

LoRaMacCryptoStatus_t	LoRaMacCryptoDeriveMcSessionKeyPair (AddressIdentifier_t addrID, uint32_t mcAddr)

Detailed Description

LoRa MAC layer cryptographic functionality implementation.

Copyright: Revised BSD License, see section License.

  ______                              _
 / _____)             _              | |
( (____  _____ ____ _| |_ _____  ____| |__
 \____ \| ___ |    (_   _) ___ |/ ___)  _ \
 _____) ) ____| | | || |_| ____( (___| | | |
(______/|_____)_|_|_| \__)_____)\____)_| |_|
(C)2013-2017 Semtech
 
 ___ _____ _   ___ _  _____ ___  ___  ___ ___
/ __|_   _/_\ / __| |/ / __/ _ \| _ \/ __| __|
\__ \ | |/ _ \ (__| ' <| _| (_) |   / (__| _|
|___/ |_/_/ \_\___|_|\_\_| \___/|_|_\\___|___|
embedded.connectivity.solutions===============

Author: Miguel Luis ( Semtech ); Gregory Cristian ( Semtech ); Daniel Jaeckle ( STACKFORCE ); Johannes Bruder ( STACKFORCE )

addtogroup LORAMAC

Macro Definition Documentation

◆ USE_LRWAN_1_1_X_CRYPTO

#define USE_LRWAN_1_1_X_CRYPTO 0

Indicates if LoRaWAN 1.1.x crypto scheme is enabled

◆ USE_RANDOM_DEV_NONCE

#define USE_RANDOM_DEV_NONCE 1

Indicates if a random devnonce must be used or not

◆ USE_JOIN_NONCE_COUNTER_CHECK

#define USE_JOIN_NONCE_COUNTER_CHECK 0

Indicates if JoinNonce is counter based and requires to be checked

◆ FCNT_DOWN_INITAL_VALUE

#define FCNT_DOWN_INITAL_VALUE 0xFFFFFFFF

Initial value of the frame counters

Typedef Documentation

◆ LoRaMacCryptoNvmEvent

typedef void( * LoRaMacCryptoNvmEvent) (void)

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.

Enumeration Type Documentation

◆ LoRaMacCryptoStatus_t

enum LoRaMacCryptoStatus_t

LoRaMac Cryto Status

Enumerator
LORAMAC_CRYPTO_SUCCESS	No error occurred
LORAMAC_CRYPTO_FAIL_MIC	MIC does not match
LORAMAC_CRYPTO_FAIL_ADDRESS	Address does not match
LORAMAC_CRYPTO_FAIL_JOIN_NONCE	JoinNonce was not greater than previous one.
LORAMAC_CRYPTO_FAIL_RJCOUNT0_OVERFLOW	RJcount0 reached 2^16-1
LORAMAC_CRYPTO_FAIL_FCNT_ID	FCNT_ID is not supported
LORAMAC_CRYPTO_FAIL_FCNT_SMALLER	FCntUp/Down check failed (new FCnt is smaller than previous one)
LORAMAC_CRYPTO_FAIL_FCNT_DUPLICATED	FCntUp/Down check failed (duplicated)
LORAMAC_CRYPTO_FAIL_MAX_GAP_FCNT	MAX_GAP_FCNT check failed
LORAMAC_CRYPTO_FAIL_PARAM	Not allowed parameter value
LORAMAC_CRYPTO_ERROR_NPE	Null pointer exception
LORAMAC_CRYPTO_ERROR_INVALID_KEY_ID	Invalid key identifier exception
LORAMAC_CRYPTO_ERROR_INVALID_ADDR_ID	Invalid address identifier exception
LORAMAC_CRYPTO_ERROR_INVALID_VERSION	Invalid LoRaWAN specification version
LORAMAC_CRYPTO_ERROR_BUF_SIZE	Incompatible buffer size
LORAMAC_CRYPTO_ERROR_SECURE_ELEMENT_FUNC	The secure element reports an error
LORAMAC_CRYPTO_ERROR_PARSER	Error from parser reported
LORAMAC_CRYPTO_ERROR_SERIALIZER	Error from serializer reported
LORAMAC_CRYPTO_ERROR_RJCOUNT1_OVERFLOW	RJcount1 reached 2^16-1 which should never happen
LORAMAC_CRYPTO_ERROR	Undefined Error occurred

Function Documentation

◆ LoRaMacCryptoInit()

LoRaMacCryptoStatus_t LoRaMacCryptoInit ( LoRaMacCryptoNvmEvent cryptoNvmCtxChanged )

Initialization of LoRaMac Crypto module It sets initial values of volatile variables and assigns the non-volatile context.

Parameters

[IN]	cryptoNvmCtxChanged - Callback function which will be called when the non-volatile context have to be stored.

Return values

-	Status of the operation

◆ LoRaMacCryptoSetLrWanVersion()

LoRaMacCryptoStatus_t LoRaMacCryptoSetLrWanVersion ( Version_t version )

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.

Parameters

[IN]	version - LoRaWAN specification version to be used.

Return values

-	Status of the operation

◆ LoRaMacCryptoRestoreNvmCtx()

LoRaMacCryptoStatus_t LoRaMacCryptoRestoreNvmCtx ( void * cryptoNvmCtx )

Restores the internal nvm context from passed pointer.

Parameters

[IN]	cryptoNmvCtx - Pointer to non-volatile crypto module context to be restored.

Return values

-	Status of the operation

◆ LoRaMacCryptoGetNvmCtx()

void* LoRaMacCryptoGetNvmCtx ( size_t * cryptoNvmCtxSize )

Returns a pointer to the internal non-volatile context.

Parameters

[IN]	cryptoNvmCtxSize - Size of the module non-volatile context

Return values

-	Points to a structure where the module store its non-volatile context

◆ LoRaMacCryptoGetFCntDown()

LoRaMacCryptoStatus_t LoRaMacCryptoGetFCntDown	(	FCntIdentifier_t	fCntID,
		uint16_t	maxFCntGap,
		uint32_t	frameFcnt,
		uint32_t *	currentDown
	)

Returns updated fCntID downlink counter value.

Parameters

[IN]	fCntID - Frame counter identifier
[IN]	maxFcntGap - Maximum allowed frame counter difference (only necessary for L2 LW1.0.x)
[IN]	frameFcnt - Received frame counter (used to update current counter value)
[OUT]	currentDown - Current downlink counter value

Return values

-	Status of the operation

◆ LoRaMacCryptoGetFCntUp()

LoRaMacCryptoStatus_t LoRaMacCryptoGetFCntUp ( uint32_t * currentUp )

Returns updated fCntUp uplink counter value.

Parameters

[IN]	currentUp - Uplink counter value

Return values

-	Status of the operation

◆ LoRaMacCryptoSetMulticastReference()

LoRaMacCryptoStatus_t LoRaMacCryptoSetMulticastReference ( MulticastCtx_t * multicastList )

Provides multicast context.

Parameters

[IN]	multicastList - Pointer to the multicast context list

Return values

-	Status of the operation

◆ LoRaMacCryptoSetKey()

LoRaMacCryptoStatus_t LoRaMacCryptoSetKey	(	KeyIdentifier_t	keyID,
		uint8_t *	key
	)

Sets a key

Parameters

[IN]	keyID - Key identifier
[IN]	key - Key value (16 byte), if its a multicast key it must be encrypted with McKEKey

Return values

-	Status of the operation

◆ LoRaMacCryptoPrepareJoinRequest()

LoRaMacCryptoStatus_t LoRaMacCryptoPrepareJoinRequest ( LoRaMacMessageJoinRequest_t * macMsg )

Prepares the join-request message. It computes the mic and add it to the message.

Parameters

[IN/OUT] macMsg - Join-request message object

Return values

-	Status of the operation

◆ LoRaMacCryptoPrepareReJoinType1()

LoRaMacCryptoStatus_t LoRaMacCryptoPrepareReJoinType1 ( LoRaMacMessageReJoinType1_t * macMsg )

Prepares a rejoin-request type 1 message. It computes the mic and add it to the message.

Parameters

[IN/OUT] macMsg - Rejoin message object

Return values

-	Status of the operation

◆ LoRaMacCryptoPrepareReJoinType0or2()

LoRaMacCryptoStatus_t LoRaMacCryptoPrepareReJoinType0or2 ( LoRaMacMessageReJoinType0or2_t * macMsg )

Prepares a rejoin-request type 0 or 2 message. It computes the mic and add it to the message.

Parameters

[IN/OUT] macMsg - Rejoin message object

Return values

-	Status of the operation

◆ LoRaMacCryptoHandleJoinAccept()

LoRaMacCryptoStatus_t LoRaMacCryptoHandleJoinAccept	(	JoinReqIdentifier_t	joinReqType,
		uint8_t *	joinEUI,
		LoRaMacMessageJoinAccept_t *	macMsg
	)

Handles the join-accept message. It decrypts the message, verifies the MIC and if successful derives the session keys.

Parameters

[IN]	joinReqType - Type of last join-request or rejoin which triggered the join-accept response
[IN]	joinEUI - Join server EUI (8 byte)
[IN/OUT]	macMsg - Join-accept message object

Return values

-	Status of the operation

◆ LoRaMacCryptoSecureMessage()

LoRaMacCryptoStatus_t LoRaMacCryptoSecureMessage	(	uint32_t	fCntUp,
		uint8_t	txDr,
		uint8_t	txCh,
		LoRaMacMessageData_t *	macMsg
	)

Secures a message (encryption + integrity).

Parameters

[IN]	fCntUp - Uplink sequence counter
[IN]	txDr - Data rate used for the transmission
[IN]	txCh - Index of the channel used for the transmission
[IN/OUT]	macMsg - Data message object

Return values

-	Status of the operation

◆ LoRaMacCryptoUnsecureMessage()

LoRaMacCryptoStatus_t LoRaMacCryptoUnsecureMessage	(	AddressIdentifier_t	addrID,
		uint32_t	address,
		FCntIdentifier_t	fCntID,
		uint32_t	fCntDown,
		LoRaMacMessageData_t *	macMsg
	)

Unsecures a message (decryption + integrity verification).

Parameters

[IN]	addrID - Address identifier
[IN]	address - Address
[IN]	fCntID - Frame counter identifier
[IN]	fCntDown - Downlink sequence counter
[IN/OUT]	macMsg - Data message object

Return values

-	Status of the operation

◆ LoRaMacCryptoDeriveMcRootKey()

LoRaMacCryptoStatus_t LoRaMacCryptoDeriveMcRootKey	(	uint8_t	versionMinor,
		KeyIdentifier_t	keyID
	)

Derives the McRootKey from the AppKey.

1.0.x McRootKey = aes128_encrypt(AppKey, 0x00 | pad16)

1.1.x McRootKey = aes128_encrypt(AppKey, 0x20 | pad16)

Parameters

[IN]	versionMinor - LoRaWAN specification minor version to be used.
[IN]	keyID - Key identifier of the root key to use to perform the derivation ( AppKey )

Return values

-	Status of the operation

◆ LoRaMacCryptoDeriveMcKEKey()

LoRaMacCryptoStatus_t LoRaMacCryptoDeriveMcKEKey ( KeyIdentifier_t keyID )

Derives the McKEKey from the McRootKey.

McKEKey = aes128_encrypt(McRootKey , 0x00 | pad16)

Parameters

[IN]	keyID - Key identifier of the root key to use to perform the derivation ( McRootKey )

Return values

-	Status of the operation

◆ LoRaMacCryptoDeriveMcSessionKeyPair()

LoRaMacCryptoStatus_t LoRaMacCryptoDeriveMcSessionKeyPair	(	AddressIdentifier_t	addrID,
		uint32_t	mcAddr
	)

Derives a Multicast group key pair ( McAppSKey, McNwkSKey ) from McKey

McAppSKey = aes128_encrypt(McKey, 0x01 | McAddr | pad16) McNwkSKey = aes128_encrypt(McKey, 0x02 | McAddr | pad16)

Parameters

[IN]	addrID - Address identifier to select the multicast group
[IN]	mcAddr - Multicast group address (4 bytes)

Return values

-	Status of the operation