LoRaMAC  4.4.6
Documentation of the API
Secure Element API Definition

Data Structures

struct  SecureElementNvmData_t
 

Macros

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

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 (SecureElementNvmData_t *nvm)
 
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


Data Structure Documentation

◆ SecureElementNvmData_t

struct SecureElementNvmData_t
Data Fields
uint8_t DevEui[SE_EUI_SIZE]

DevEUI storage

uint8_t JoinEui[SE_EUI_SIZE]

Join EUI storage

uint8_t Pin[SE_PIN_SIZE]

Pin storage

uint32_t Crc32

CRC32 value of the SecureElement data structure.

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

Enumeration Type Documentation

◆ 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 ( SecureElementNvmData_t nvm)

Initialization of Secure Element driver

Parameters
[IN]nvm - Pointer to the non-volatile memory data structure.
Return values
-Status of the operation

◆ 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