Secure Element API Definition

Macros
#define	SE_KEY_SIZE   16
#define	SE_EUI_SIZE   8
#define	SE_PIN_SIZE   4

Typedefs
typedef void(*	SecureElementNvmEvent) (void)

Enumerations
enum	SecureElementStatus_t {   SECURE_ELEMENT_SUCCESS = 0, SECURE_ELEMENT_FAIL_CMAC, SECURE_ELEMENT_ERROR_NPE, SECURE_ELEMENT_ERROR_INVALID_KEY_ID,   SECURE_ELEMENT_ERROR_INVALID_LORAWAM_SPEC_VERSION, SECURE_ELEMENT_ERROR_BUF_SIZE, SECURE_ELEMENT_ERROR, SECURE_ELEMENT_FAIL_ENCRYPT }

Functions
SecureElementStatus_t	SecureElementInit (SecureElementNvmEvent seNvmCtxChanged)
SecureElementStatus_t	SecureElementRestoreNvmCtx (void *seNvmCtx)
void *	SecureElementGetNvmCtx (size_t *seNvmCtxSize)
SecureElementStatus_t	SecureElementSetKey (KeyIdentifier_t keyID, uint8_t *key)
SecureElementStatus_t	SecureElementComputeAesCmac (uint8_t *micBxBuffer, uint8_t *buffer, uint16_t size, KeyIdentifier_t keyID, uint32_t *cmac)
SecureElementStatus_t	SecureElementVerifyAesCmac (uint8_t *buffer, uint16_t size, uint32_t expectedCmac, KeyIdentifier_t keyID)
SecureElementStatus_t	SecureElementAesEncrypt (uint8_t *buffer, uint16_t size, KeyIdentifier_t keyID, uint8_t *encBuffer)
SecureElementStatus_t	SecureElementDeriveAndStoreKey (uint8_t *input, KeyIdentifier_t rootKeyID, KeyIdentifier_t targetKeyID)
SecureElementStatus_t	SecureElementProcessJoinAccept (JoinReqIdentifier_t joinReqType, uint8_t *joinEui, uint16_t devNonce, uint8_t *encJoinAccept, uint8_t encJoinAcceptSize, uint8_t *decJoinAccept, uint8_t *versionMinor)
SecureElementStatus_t	SecureElementRandomNumber (uint32_t *randomNum)
SecureElementStatus_t	SecureElementSetDevEui (uint8_t *devEui)
uint8_t *	SecureElementGetDevEui (void)
SecureElementStatus_t	SecureElementSetJoinEui (uint8_t *joinEui)
uint8_t *	SecureElementGetJoinEui (void)
SecureElementStatus_t	SecureElementSetPin (uint8_t *pin)
uint8_t *	SecureElementGetPin (void)

Detailed Description

Macro Definition Documentation

SE_KEY_SIZE

#define SE_KEY_SIZE   16

Secure-element keys size in bytes

SE_EUI_SIZE

#define SE_EUI_SIZE   8

Secure-element EUI size in bytes

SE_PIN_SIZE

#define SE_PIN_SIZE   4

Secure-element pin size in bytes

Typedef Documentation

SecureElementNvmEvent

typedef void( * SecureElementNvmEvent) (void)

Signature of callback function to be called by the Secure Element driver when the non volatile context have to be stored.

Enumeration Type Documentation

SecureElementStatus_t

enum SecureElementStatus_t

Return values.

Enumerator
SECURE_ELEMENT_SUCCESS	No error occurred
SECURE_ELEMENT_FAIL_CMAC	CMAC does not match
SECURE_ELEMENT_ERROR_NPE	Null pointer exception
SECURE_ELEMENT_ERROR_INVALID_KEY_ID	Invalid key identifier exception
SECURE_ELEMENT_ERROR_INVALID_LORAWAM_SPEC_VERSION	Invalid LoRaWAN specification version
SECURE_ELEMENT_ERROR_BUF_SIZE	Incompatible buffer size
SECURE_ELEMENT_ERROR	Undefined Error occurred
SECURE_ELEMENT_FAIL_ENCRYPT	Failed to encrypt

Function Documentation

SecureElementInit()

SecureElementStatus_t SecureElementInit

(

SecureElementNvmEvent

seNvmCtxChanged

)

Initialization of Secure Element driver

Parameters

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

Return values

-	Status of the operation

SecureElementRestoreNvmCtx()

SecureElementStatus_t SecureElementRestoreNvmCtx

(

void *

seNvmCtx

)

Restores the internal nvm context from passed pointer.

Parameters

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

Return values

-	Status of the operation

SecureElementGetNvmCtx()

void* SecureElementGetNvmCtx

(

size_t *

seNvmCtxSize

)

Returns a pointer to the internal non-volatile context.

Parameters

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

Return values

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

SecureElementSetKey()

SecureElementStatus_t SecureElementSetKey	(	KeyIdentifier_t	keyID,
		uint8_t *	key
	)

Sets a key

Parameters

[IN]	keyID - Key identifier
[IN]	key - Key value

Return values

-	Status of the operation

SecureElementComputeAesCmac()

SecureElementStatus_t SecureElementComputeAesCmac	(	uint8_t *	micBxBuffer,
		uint8_t *	buffer,
		uint16_t	size,
		KeyIdentifier_t	keyID,
		uint32_t *	cmac
	)

Computes a CMAC of a message using provided initial Bx block

Parameters

[IN]	micBxBuffer - Buffer containing the initial Bx block
[IN]	buffer - Data buffer
[IN]	size - Data buffer size
[IN]	keyID - Key identifier to determine the AES key to be used
[OUT]	cmac - Computed cmac

Return values

-	Status of the operation

SecureElementVerifyAesCmac()

SecureElementStatus_t SecureElementVerifyAesCmac	(	uint8_t *	buffer,
		uint16_t	size,
		uint32_t	expectedCmac,
		KeyIdentifier_t	keyID
	)

Verifies a CMAC (computes and compare with expected cmac)

Parameters

	[IN]	buffer - Data buffer
	[IN]	size - Data buffer size
[in]	expectedCmac	- Expected cmac
	[IN]	keyID - Key identifier to determine the AES key to be used

Return values

-	Status of the operation

SecureElementAesEncrypt()

SecureElementStatus_t SecureElementAesEncrypt	(	uint8_t *	buffer,
		uint16_t	size,
		KeyIdentifier_t	keyID,
		uint8_t *	encBuffer
	)

Encrypt a buffer

Parameters

[IN]	buffer - Data buffer
[IN]	size - Data buffer size
[IN]	keyID - Key identifier to determine the AES key to be used
[OUT]	encBuffer - Encrypted buffer

Return values

-	Status of the operation

SecureElementDeriveAndStoreKey()

SecureElementStatus_t SecureElementDeriveAndStoreKey	(	uint8_t *	input,
		KeyIdentifier_t	rootKeyID,
		KeyIdentifier_t	targetKeyID
	)

Derives and store a key

Parameters

[IN]	input - Input data from which the key is derived ( 16 byte )
[IN]	rootKeyID - Key identifier of the root key to use to perform the derivation
[IN]	targetKeyID - Key identifier of the key which will be derived

Return values

-	Status of the operation

SecureElementProcessJoinAccept()

SecureElementStatus_t SecureElementProcessJoinAccept	(	JoinReqIdentifier_t	joinReqType,
		uint8_t *	joinEui,
		uint16_t	devNonce,
		uint8_t *	encJoinAccept,
		uint8_t	encJoinAcceptSize,
		uint8_t *	decJoinAccept,
		uint8_t *	versionMinor
	)

Process JoinAccept message.

Parameters

[IN]	encJoinAccept - Received encrypted JoinAccept message
[IN]	encJoinAcceptSize - Received encrypted JoinAccept message Size
[OUT]	decJoinAccept - Decrypted and validated JoinAccept message
[OUT]	versionMinor - Detected LoRaWAN specification version minor field. 0 -> LoRaWAN 1.0.x 1 -> LoRaWAN 1.1.x

Return values

-	Status of the operation

SecureElementRandomNumber()

SecureElementStatus_t SecureElementRandomNumber

(

uint32_t *

randomNum

)

Generates a random number

Parameters

[OUT]

randomNum - 32 bit random number

Return values

-	Status of the operation

SecureElementSetDevEui()

SecureElementStatus_t SecureElementSetDevEui

(

uint8_t *

devEui

)

Sets the DevEUI

Parameters

[IN]	devEui - Pointer to the 8-byte devEUI

Return values

-	Status of the operation

SecureElementGetDevEui()

uint8_t* SecureElementGetDevEui

(

void

)

Gets the DevEUI

Return values

-	Pointer to the 8-byte devEUI

SecureElementSetJoinEui()

SecureElementStatus_t SecureElementSetJoinEui

(

uint8_t *

joinEui

)

Sets the JoinEUI

Parameters

[IN]	joinEui - Pointer to the 8-byte joinEui

Return values

-	Status of the operation

SecureElementGetJoinEui()

uint8_t* SecureElementGetJoinEui

(

void

)

Gets the DevEUI

Return values

-	Pointer to the 8-byte joinEui

SecureElementSetPin()

SecureElementStatus_t SecureElementSetPin

(

uint8_t *

pin

)

Sets the pin

Parameters

[IN]	pin - Pointer to the 4-byte pin

Return values

-	Status of the operation

SecureElementGetPin()

uint8_t* SecureElementGetPin

(

void

)

Gets the Pin

Return values

-	Pointer to the 4-byte pin