APIs for secure-element drivers

Linkage to secure element implementations. More...

Collaboration diagram for APIs for secure-element drivers:

Macros
#define	LMIC_SecureElement_DECLARE_DRIVER_FNS(a_driver)
	Declare secure element functions for a given driver.

Typedefs
typedef LMIC_SecureElement_Error_t LMIC_ABI_STD	LMIC_SecureElement_aes128Encrypt_t(const uint8_t *pKey, const uint8_t *pInput, uint8_t *pOutput)
	Perform an AES128 encryption.
typedef LMIC_SecureElement_Error_t LMIC_ABI_STD	LMIC_SecureElement_createJoinRequest_t(uint8_t *pJoinRequestBytes, LMIC_SecureElement_JoinFormat_t joinFormat)
	Create a join request.
typedef LMIC_SecureElement_Error_t LMIC_ABI_STD	LMIC_SecureElement_decodeJoinAccept_t(const uint8_t *pJoinAcceptBytes, uint8_t nJoinAcceptBytes, uint8_t *pJoinAcceptClearText, LMIC_SecureElement_JoinFormat_t joinFormat)
	Decode a join accept message; capture keys.
typedef LMIC_SecureElement_Error_t LMIC_ABI_STD	LMIC_SecureElement_decodeMessage_t(const uint8_t *pPhyPayload, uint8_t nPhyPayload, uint32_t devAddr, uint32_t FCntDown, LMIC_SecureElement_KeySelector_t iKey, uint8_t *pClearTextBuffer)
	Decode an application message.
typedef LMIC_SecureElement_Error_t LMIC_ABI_STD	LMIC_SecureElement_encodeMessage_t(const uint8_t *pMessage, uint8_t nMessage, uint8_t iPayload, uint8_t *pCipherTextBuffer, LMIC_SecureElement_KeySelector_t iKey)
	Encode an application uplink message.
typedef LMIC_SecureElement_Error_t LMIC_ABI_STD	LMIC_SecureElement_fillRandomBuffer_t(uint8_t *buffer, uint8_t nBuffer)
	Fill buffer with random independently distributed integers, each in [0..255].
typedef LMIC_SecureElement_Error_t LMIC_ABI_STD	LMIC_SecureElement_getAppEUI_t(LMIC_SecureElement_EUI_t *pAppEUI)
	Get application EUI.
typedef LMIC_SecureElement_Error_t LMIC_ABI_STD	LMIC_SecureElement_getAppKey_t(LMIC_SecureElement_Aes128Key_t *pAppKey)
	Get application key.
typedef LMIC_SecureElement_Error_t LMIC_ABI_STD	LMIC_SecureElement_getAppSKey_t(LMIC_SecureElement_Aes128Key_t *pAppSKey, LMIC_SecureElement_KeySelector_t iKey)
	Get application session key.
typedef LMIC_SecureElement_Error_t LMIC_ABI_STD	LMIC_SecureElement_getDevEUI_t(LMIC_SecureElement_EUI_t *pDevEUI)
	Get device EUI.
typedef LMIC_SecureElement_Error_t LMIC_ABI_STD	LMIC_SecureElement_getNwkSKey_t(LMIC_SecureElement_Aes128Key_t *pNwkSKey, LMIC_SecureElement_KeySelector_t iKey)
	Get network session key.
typedef uint8_t LMIC_ABI_STD	LMIC_SecureElement_getRandomU1_t(void)
	Return a random integer uniformly distributed in [0..255].
typedef uint16_t LMIC_ABI_STD	LMIC_SecureElement_getRandomU2_t(void)
	Return a random integer uniformly distributed in [0..65535].
typedef LMIC_SecureElement_Error_t LMIC_ABI_STD	LMIC_SecureElement_initialize_t(void)
	Initialize the Secure Element.
typedef LMIC_SecureElement_Error_t LMIC_ABI_STD	LMIC_SecureElement_setAppEUI_t(const LMIC_SecureElement_EUI_t *pAppEUI)
	Set application EUI.
typedef LMIC_SecureElement_Error_t LMIC_ABI_STD	LMIC_SecureElement_setAppKey_t(const LMIC_SecureElement_Aes128Key_t *pAppKey)
	Set application key.
typedef LMIC_SecureElement_Error_t LMIC_ABI_STD	LMIC_SecureElement_setAppSKey_t(const LMIC_SecureElement_Aes128Key_t *pAppSKey, LMIC_SecureElement_KeySelector_t iKey)
	Set application session key.
typedef LMIC_SecureElement_Error_t LMIC_ABI_STD	LMIC_SecureElement_setDevEUI_t(const LMIC_SecureElement_EUI_t *pDevEUI)
	Set device EUI.
typedef LMIC_SecureElement_Error_t LMIC_ABI_STD	LMIC_SecureElement_setNwkSKey_t(const LMIC_SecureElement_Aes128Key_t *pNwkSKey, LMIC_SecureElement_KeySelector_t iKey)
	Set network session key.
typedef LMIC_SecureElement_Error_t LMIC_ABI_STD	LMIC_SecureElement_verifyMIC_t(const uint8_t *pPhyPayload, uint8_t nPhyPayload, uint32_t devAddr, uint32_t FCntDown, LMIC_SecureElement_KeySelector_t iKey)
	Verify the MIC of a downlink message.

Detailed Description

Linkage to secure element implementations.

Function types are used to enforce consistency between the API wrappers and driver implementations. We follow MCCI's convention of declaring function types rather than pointer-to-function types; this lets one type name be used both for declaring pointers to functions and for declaring that a given function implements a given API.

Given that consistency, we further define macros that will generate all prototypes for a given driver's methods using consistent names (LMIC_SecureElement_DECLARE_DRIVER_FNS).

The framework implementation currently requires that the secure element driver be selected at compile time. However, the architecture allows an alternate implementation using pointers and dynamic linkage.

Macro Definition Documentation

LMIC_SecureElement_DECLARE_DRIVER_FNS

#define LMIC_SecureElement_DECLARE_DRIVER_FNS

(

a_driver

)

Declare secure element functions for a given driver.

Parameters

a_driver

Fragment of driver name to insert in function names, e.g Default.

The parameter is macro-expanded and then substituted to declare each of the interface functions for the specified driver.

Example

LMIC_SecureElement_DECLARE_DRIVER_DNS(MyDriver);

This expands to a series of function declarations:

LMIC_SecureElement_initialize_t LMIC_SecureElement_MyDriver_initialize;
LMIC_SecureElement_getRandomU1_t LMIC_SecureElement_MyDriver_getRandomU1;
/* ... */
LMIC_SecureElement_aes128Encrypt_t LMIC_SecureElement_MyDriver_aes128Encrypt;

Typedef Documentation

LMIC_SecureElement_aes128Encrypt_t

typedef LMIC_SecureElement_Error_t LMIC_ABI_STD LMIC_SecureElement_aes128Encrypt_t(const uint8_t *pKey, const uint8_t *pInput, uint8_t *pOutput)

Perform an AES128 encryption.

Parameters

pKey	[in] Encryption key (16 bytes).
pInput	[in] Clear text (16 bytes).
pOutput	[out] Cipher text (16 bytes).

This API is used for beacon calculations and other pseudo-random operations. Key, input buffer, output buffer are all 16 bytes long. pOutput and pInput may be the same buffer; otherwise they must point to non-overlapping regions of memory. pKey must not overlap pOutput. None of pKey, pInput, pOutput may be NULL.

Return values

LMIC_SecureElement_Error_OK	if the encryption was performed
LMIC_SecureElement_Error_InvalidParameter	if any of the parameters is invalid.

LMIC_SecureElement_createJoinRequest_t

typedef LMIC_SecureElement_Error_t LMIC_ABI_STD LMIC_SecureElement_createJoinRequest_t(uint8_t *pJoinRequestBytes, LMIC_SecureElement_JoinFormat_t joinFormat)

Create a join request.

Parameters

pJoinRequestBytes	[out] Buffer to be filled with the join request.
joinFormat	[in] Join type selector.

The buffer at * pJoinRequestBytes must be at least sizeof(LMIC_SecureElement_JoinRequest_t::bytes) long; it is filled with a JoinRequest message, encrypted with the keys suitable to the specified context. joinFormat is provided for future use in LoRaWAN 1.1 systems; it selects the keys to be used and the format of the message. It shall be set to LMIC_SecureElement_JoinFormat_JoinRequest10.

Returns

The result is LMIC_SecureElement_Error_OK for success, some other value for failure.

Return values

LMIC_SecureElement_Error_InvalidParameter

indicates that iKey was not valid.

LMIC_SecureElement_decodeJoinAccept_t

typedef LMIC_SecureElement_Error_t LMIC_ABI_STD LMIC_SecureElement_decodeJoinAccept_t(const uint8_t *pJoinAcceptBytes, uint8_t nJoinAcceptBytes, uint8_t *pJoinAcceptClearText, LMIC_SecureElement_JoinFormat_t joinFormat)

Decode a join accept message; capture keys.

Parameters

pJoinAcceptBytes	[in] Buffer with raw join accept message
nJoinAcceptBytes	[in] Number of bytes
pJoinAcceptClearText	[out] Buffer to be filled with decrypted message; same size as pJoinAcceptBytes.
joinFormat	[in] Type used on message that triggered this join accept.

The Join-Accept message is decoded using the keys designated by the joinFormat, and the clear text is placed in pJoinAcceptClearText.

The LMIC presently only supports LoRaWAN 1.0.3, so joinFormat must be LMIC_SecureElement_JoinFormat_JoinRequest10.

Returns

The result is LMIC_SecureElement_Error_OK for success, some other value for failure. If successful, the appropriate session keys are generated and stored in the secure element.

LMIC_SecureElement_decodeMessage_t

typedef LMIC_SecureElement_Error_t LMIC_ABI_STD LMIC_SecureElement_decodeMessage_t(const uint8_t *pPhyPayload, uint8_t nPhyPayload, uint32_t devAddr, uint32_t FCntDown, LMIC_SecureElement_KeySelector_t iKey, uint8_t *pClearTextBuffer)

Decode an application message.

Parameters

pPhyPayload	[in] Pointer to MHDR byte of received PHY message.
nPhyPayload	[in] Number of bytes, including the MIC.
devAddr	[in] Device address
FCntDown	[in] The downlink frame counter to be used with this message
iKey	[in] Key discriminator.
pClearTextBuffer	[out] Buffer to be used for the output data. Must be nPhyPayload - 4 bytes long.

The payload is decrypted and placed in pClearTextBuffer. The MIC is assumed to be valid. The output buffer must be nBuffer - 4 bytes long (the MIC is not appended). ClearTextdBuffer may be the same as pPhyPayload, in which case the update is done in-place if possible. Otherwise the input and output blocks shall be strictly non-overlapping.

Returns

Returns LMIC_SecureElement_Error_OK for success, some other value for failure.

LMIC_SecureElement_encodeMessage_t

typedef LMIC_SecureElement_Error_t LMIC_ABI_STD LMIC_SecureElement_encodeMessage_t(const uint8_t *pMessage, uint8_t nMessage, uint8_t iPayload, uint8_t *pCipherTextBuffer, LMIC_SecureElement_KeySelector_t iKey)

Encode an application uplink message.

Parameters

pMessage	[in] Pointer to MHDR byte of message to encode.
nMessage	[in] Number of bytes, not including the MIC.
iPayload	[in] Index of payload field in the message.
pCipherTextBuffer	[in] Pointer to buffer to receive phy message.
iKey	[in] Key discriminator.

The output buffer must be nBuffer + 4 bytes long. FCntUp in the message may be ignored by the Secure Element and replaced by SE's idea of the uplink frame count. SE will increment its internal FCntUp. To implement NbTrans > 1, caller shall cache the encoded message and retransmit it, rather than re-encoding it. pCipherTextBuffer may be the same as pMessage; in this case the update is done in-place if possible. Otherwise the blocks shall be strictly non-overlapping.

Returns

The result is LMIC_SecureElement_Error_OK for success, some other value for failure.

LMIC_SecureElement_fillRandomBuffer_t

typedef LMIC_SecureElement_Error_t LMIC_ABI_STD LMIC_SecureElement_fillRandomBuffer_t(uint8_t *buffer, uint8_t nBuffer)

Fill buffer with random independently distributed integers, each in [0..255].

Parameters

buffer	[out] Pointer to buffer to be filled.
nBuffer	[in] Number of bytes to be filled.

nBuffer is limited to 255, for maximum implementation flexibility.

Returns

LMIC_SecureElement_Error_OK for success, some other code for failure.

LMIC_SecureElement_getAppEUI_t

typedef LMIC_SecureElement_Error_t LMIC_ABI_STD LMIC_SecureElement_getAppEUI_t(LMIC_SecureElement_EUI_t *pAppEUI)

Get application EUI.

Parameters

pAppEUI

[out] application EUI for this secure element.

Returns

LMIC_SecureElement_Error_OK for success, some other code for failure. Many secure elements will fail this request, because their purpose in life is guarding keys and preventing tampering.

LMIC_SecureElement_getAppKey_t

typedef LMIC_SecureElement_Error_t LMIC_ABI_STD LMIC_SecureElement_getAppKey_t(LMIC_SecureElement_Aes128Key_t *pAppKey)

Get application key.

Parameters

pAppKey

[out] Points to buffer to be filled with application key.

Returns

LMIC_SecureElement_Error_OK for success, some other code for failure. Many secure elements will fail this request, because their purpose in life is guarding the application key and preventing tampering.

LMIC_SecureElement_getAppSKey_t

typedef LMIC_SecureElement_Error_t LMIC_ABI_STD LMIC_SecureElement_getAppSKey_t(LMIC_SecureElement_Aes128Key_t *pAppSKey, LMIC_SecureElement_KeySelector_t iKey)

Get application session key.

Parameters

pAppSKey	[out] set to the value of the application session key.
iKey	[in] key discriminator.

Returns

LMIC_SecureElement_Error_OK for success, some other code for failure. Many secure elements will fail this request, because their purpose in life is guarding keys and preventing tampering.

LMIC_SecureElement_getDevEUI_t

typedef LMIC_SecureElement_Error_t LMIC_ABI_STD LMIC_SecureElement_getDevEUI_t(LMIC_SecureElement_EUI_t *pDevEUI)

Get device EUI.

Parameters

pDevEUI

[out] device EUI.

Returns

LMIC_SecureElement_Error_OK for success, some other code for failure. Many secure elements will fail this request, because their purpose in life is guarding keys and preventing tampering.

LMIC_SecureElement_getNwkSKey_t

typedef LMIC_SecureElement_Error_t LMIC_ABI_STD LMIC_SecureElement_getNwkSKey_t(LMIC_SecureElement_Aes128Key_t *pNwkSKey, LMIC_SecureElement_KeySelector_t iKey)

Get network session key.

Parameters

pNwkSKey	[in] provides the value of the network session key.
iKey	[in] key discriminator.

Returns

LMIC_SecureElement_Error_OK for success, some other code for failure. Many secure elements will fail this request, because their purpose in life is guarding keys and preventing tampering.

LMIC_SecureElement_initialize_t

typedef LMIC_SecureElement_Error_t LMIC_ABI_STD LMIC_SecureElement_initialize_t(void)

Initialize the Secure Element.

Returns

LMIC_SecureElement_Error_OK for success, some other code for failure.

LMIC_SecureElement_setAppEUI_t

typedef LMIC_SecureElement_Error_t LMIC_ABI_STD LMIC_SecureElement_setAppEUI_t(const LMIC_SecureElement_EUI_t *pAppEUI)

Set application EUI.

Parameters

pAppEUI

[in] application EUI for this secure element.

Returns

LMIC_SecureElement_Error_OK for success, some other code for failure.

LMIC_SecureElement_setAppKey_t

typedef LMIC_SecureElement_Error_t LMIC_ABI_STD LMIC_SecureElement_setAppKey_t(const LMIC_SecureElement_Aes128Key_t *pAppKey)

Set application key.

Parameters

pAppKey

[in] Points to 16-byte application key.

Returns

LMIC_SecureElement_Error_OK for success, some other code for failure.

LMIC_SecureElement_setAppSKey_t

typedef LMIC_SecureElement_Error_t LMIC_ABI_STD LMIC_SecureElement_setAppSKey_t(const LMIC_SecureElement_Aes128Key_t *pAppSKey, LMIC_SecureElement_KeySelector_t iKey)

Set application session key.

Parameters

pAppSKey	[in] session key to be associated with iKey.
iKey	[in] key discriminator.

Returns

LMIC_SecureElement_Error_OK for success, some other code for failure.

LMIC_SecureElement_setDevEUI_t

typedef LMIC_SecureElement_Error_t LMIC_ABI_STD LMIC_SecureElement_setDevEUI_t(const LMIC_SecureElement_EUI_t *pDevEUI)

Set device EUI.

Parameters

pDevEUI

[in] Device key for this secure element.

Returns

LMIC_SecureElement_Error_OK for success, some other code for failure.

LMIC_SecureElement_setNwkSKey_t

typedef LMIC_SecureElement_Error_t LMIC_ABI_STD LMIC_SecureElement_setNwkSKey_t(const LMIC_SecureElement_Aes128Key_t *pNwkSKey, LMIC_SecureElement_KeySelector_t iKey)

Set network session key.

Parameters

pNwkSKey	[in] session key to be associated with iKey.
iKey	[in] key discriminator.

Returns

LMIC_SecureElement_Error_OK for success, some other code for failure.

LMIC_SecureElement_verifyMIC_t

typedef LMIC_SecureElement_Error_t LMIC_ABI_STD LMIC_SecureElement_verifyMIC_t(const uint8_t *pPhyPayload, uint8_t nPhyPayload, uint32_t devAddr, uint32_t FCntDown, LMIC_SecureElement_KeySelector_t iKey)

Verify the MIC of a downlink message.

Parameters

pPhyPayload	[in] Pointer to MHDR byte of received PHY message.
nPhyPayload	[in] Number of bytes, including the MIC.
devAddr	[in] Device address
FCntDown	[in] The downlink frame counter to be used with this message
iKey	[in] Key discriminator.

The MIC code for the message is calculated using the appropriate key and algorithm.

Returns

Returns LMIC_SecureElement_Error_OK if the MIC matched, or an error code related to the failure. Secure Element drivers are not rigorously tested to return the same error codes in all situations, so any result other than LMIC_SecureElement_Error_OK must be treated as an error.