LMIC Secure Element Interface

This abstract interface represents the Secure Element to the body of the LMIC. More...

Collaboration diagram for LMIC Secure Element Interface:

Topics
	APIs for secure-element drivers
	Linkage to secure element implementations.

Data Structures
struct	LMIC_SecureElement_Aes128Key_s
	an object to carry an AES128 (16-byte) key. More...
struct	LMIC_SecureElement_EUI_s
	an object to carry a 64-bit EUI. More...
struct	LMIC_SecureLElement_JoinRequest_s
	an object to carry a LoRaWAN Join Request message. More...

Macros
#define	LMIC_SecureElement_KeySelector_NAME_MULTISZ_INIT
	Names for values of LMIC_SecureElement_KeySelector_t.

Typedefs
typedef struct LMIC_SecureElement_Aes128Key_s	LMIC_SecureElement_Aes128Key_t
	an object to carry an AES128 (16-byte) key.
typedef enum LMIC_SecureElement_Error_e	LMIC_SecureElement_Error_t
	Controlled-width type for LMIC_SecureElement_Error_e.
typedef struct LMIC_SecureElement_EUI_s	LMIC_SecureElement_EUI_t
	an object to carry a 64-bit EUI.
typedef uint8_t	LMIC_SecureElement_JoinFormat_t
	Controlled-width type for LMIC_SecureElement_JoinFormat_e.
typedef struct LMIC_SecureLElement_JoinRequest_s	LMIC_SecureElement_JoinRequest_t
	an object to carry a LoRaWAN Join Request message.
typedef uint8_t	LMIC_SecureElement_KeySelector_t
	Controlled-width type for LMIC_SecureElement_KeySelector_e.

Enumerations
enum	LMIC_SecureElement_Error_e {   LMIC_SecureElement_Error_OK = 0 , LMIC_SecureElement_Error_InvalidParameter , LMIC_SecureElement_Error_Permission , LMIC_SecureElement_Error_NotProvisioned ,   LMIC_SecureElement_Error_InvalidMIC , LMIC_SecureElement_Error_Implementation }
	Values of type and LMIC_SecureElement_Error_t enumerate errors returned by the Secure Element APIs. More...
enum	LMIC_SecureElement_JoinFormat_e {   LMIC_SecureElement_JoinFormat_JoinRequest10 , LMIC_SecureElement_JoinFormat_JoinRequest11 , LMIC_SecureElement_JoinFormat_RejoinRequest0 , LMIC_SecureElement_JoinFormat_RejoinRequest1 ,   LMIC_SecureElement_JoinFormat_RejoinRequest2 , LMIC_SecureElement_JoinFormat_SIZE }
	Values of this type and LMIC_SecureElement_JoinFormat_t select specific formats of Join Request. More...
enum	LMIC_SecureElement_KeySelector_e {   LMIC_SecureElement_KeySelector_Unicast = 0 , LMIC_SecureElement_KeySelector_Mc0 , LMIC_SecureElement_KeySelector_Mc1 , LMIC_SecureElement_KeySelector_Mc2 ,   LMIC_SecureElement_KeySelector_Mc3 , LMIC_SecureElement_KeySelector_AppKey , LMIC_SecureElement_KeySelector_SIZE }
	Values of this type and LMIC_SecureElement_KeySelector_t select specific keys for encryption/decryption operations. More...
#define	LMIC_CFG_SecureElement_DRIVER
	Select the secure-element driver.
#define	LMIC_ENABLE_SecureElement_STATIC
	Select linkage style.
#define	LMIC_SecureElement_METHOD_(a_driver, a_fn)
	Generate a method function name without argument expansion.
#define	LMIC_SecureElement_METHOD(a_driver, a_fn)
	Generate a method function name.

Detailed Description

This abstract interface represents the Secure Element to the body of the LMIC.

The LMIC implementation attempts to separate the network protocol implementation from the low-level details of cryptography and key managements. The low-level details are modeled as being implemented by a Secure Element with the following functions.

• Storage for keys.
• Encryption primitives that can use the keys to secure, reveal, sign or check messages without requiring that the key values be available to the LMIC.
• Miscellaneous services to minimize duplication of function between the Secure Element and the LMIC.

In order to minimize the code footprint, and in order to minimize the number of conditional compiles required in the code, Secure Element APIs are called in two steps.

1. A static-inline wrapper function is called from the LMIC code.
2. The static in-line function directly calls the similarly-named concrete function from the configured secure element.

This structure allows the C compiler to optimize out the static-inline wrapper, and avoids adding conditional compiles or macros directly to the LMIC codebase.

The default Secure Element implementation is software-only and uses the code from the IBM LMIC.

Macro Definition Documentation

LMIC_CFG_SecureElement_DRIVER

#define LMIC_CFG_SecureElement_DRIVER

Select the secure-element driver.

This macro must be set to the name used by the secure element driver for its API functions. The default is Default.

LMIC_ENABLE_SecureElement_STATIC

#define LMIC_ENABLE_SecureElement_STATIC

Select linkage style.

If this macro is defined and non-zero, the secure element will be integrated with the LMIC at compile time. If defined and zero, the secure element driver will be accessed via external functions, allowing the integration to be deferred to link time or run time.

Note

At present, only compile-time integration is implemented.

LMIC_SecureElement_KeySelector_NAME_MULTISZ_INIT

#define LMIC_SecureElement_KeySelector_NAME_MULTISZ_INIT

Names for values of LMIC_SecureElement_KeySelector_t.

This is a single string initializer of type char [] (or const char []). It can be used to initialize a string containing names of each of the values of LMIC_SecureElement_KeySelector_t. It saves space by combining the values without requiring pointers to each value, at the cost of run-time indexing into the string in order to extract the value.

Example

const char KeyNames[] = LMIC_SecureElement_KeySelector_NAME_MULTISZ_INIT;

LMIC_SecureElement_METHOD

#define LMIC_SecureElement_METHOD	(		a_driver,
			a_fn )

Generate a method function name.

Parameters

a_driver	The name of the driver (will be macro-expanded)
a_fn	The function-name fragment (will be macro-expanded)

This macro returns a standard method function name. Standard method function names begin with LMIC_SecureElement_, followed by a_driver, followed by an underscore _, and ending with a_fn. For example, writing:

#define LMIC_CFG_SecureElement_DRIVER Foo
LMIC_SecureElement_METHOD(LMIC_CFG_SecureElement_DRIVER, initialize)();

is the same as writing:

LMIC_SecureElement_Foo_initialize();

This macro is primarily intended for internal use.

LMIC_SecureElement_METHOD_

#define LMIC_SecureElement_METHOD_	(		a_driver,
			a_fn )

Generate a method function name without argument expansion.

Parameters

a_driver	The name of the driver (will be macro-expanded)
a_fn	The function-name fragment (will be macro-expanded)

This macro is like LMIC_SecureElement_METHOD() except that macros in the arguments are not expanded prior performing string substitution.

For example, writing:

#define LMIC_CFG_SecureElement_DRIVER Foo
LMIC_SecureElement_METHOD(LMIC_CFG_SecureElement_DRIVER, initialize)();

is the same as writing:

LMIC_SecureElement_LMIC_CFG_SecureElement_DRIVER_initialize();

See also

LMIC_SecureElement_METHOD()

Enumeration Type Documentation

LMIC_SecureElement_Error_e

enum LMIC_SecureElement_Error_e

Values of type and LMIC_SecureElement_Error_t enumerate errors returned by the Secure Element APIs.

Enumerator
LMIC_SecureElement_Error_OK	The operation completed successfully.
LMIC_SecureElement_Error_InvalidParameter	Invalid parameter detected.
LMIC_SecureElement_Error_Permission	The application doesn't have permission to do this operation.
LMIC_SecureElement_Error_NotProvisioned	The security element is not provisioned.
LMIC_SecureElement_Error_InvalidMIC	The computed MIC was not valid.
LMIC_SecureElement_Error_Implementation	Implementation-defined error.

LMIC_SecureElement_JoinFormat_e

enum LMIC_SecureElement_JoinFormat_e

Values of this type and LMIC_SecureElement_JoinFormat_t select specific formats of Join Request.

LoRaWAN 1.1 defines 4 formats of (re)join request messages. Values of this type are used to select the appropriate message format. LoRaWAN 1.0.3 Devices only use LMIC_SecureElement_JoinFormat_JoinRequest.

Because C doesn't specify the underlying type used for a given enum, we normally use a separate type \ref LMIC_SecureElement_JoinFormat_t to carry numbers of this value, forcing it to uint8_t.

Enumerator
LMIC_SecureElement_JoinFormat_JoinRequest10	Basic Join Request (1.0.3).
LMIC_SecureElement_JoinFormat_JoinRequest11	Basic Join Request (1.1) – no difference on encode, enables 1.1 features on decode. See LMIC_SecureElement_decodeJoinAccept_t.
LMIC_SecureElement_JoinFormat_RejoinRequest0	Rejoin-request type 0.
LMIC_SecureElement_JoinFormat_RejoinRequest1	Rejoin-request type 1.
LMIC_SecureElement_JoinFormat_RejoinRequest2	Rejoin-request type 2.
LMIC_SecureElement_JoinFormat_SIZE	One greater than maximum value in this enum.

LMIC_SecureElement_KeySelector_e

enum LMIC_SecureElement_KeySelector_e

Values of this type and LMIC_SecureElement_KeySelector_t select specific keys for encryption/decryption operations.

LoRaWAN 1.0.3 crypto operations use network session keys and application session keys. These keys are always held by the secure element; they may be injected from the LMIC or from the application for device provisioning or dynamic joins to multicast groups.

Devices (after provisioning) always have unicast keys. After joining a multicast group, they'll have keys for that group.

Notes

LoRaWAN 1.1 has an even wider variety of encryption keys. We don't know whether the API is rich enough to support 1.1 operation.

Enumerator
LMIC_SecureElement_KeySelector_Unicast	The operation should use the unicast keys.
LMIC_SecureElement_KeySelector_Mc0	The operation should use the keys for multicast session Mc0.
LMIC_SecureElement_KeySelector_Mc1	The operation should use the keys for multicast session Mc1.
LMIC_SecureElement_KeySelector_Mc2	The operation should use the keys for multicast session Mc2.
LMIC_SecureElement_KeySelector_Mc3	The operation should use the keys for multicast session MC3.
LMIC_SecureElement_KeySelector_AppKey	The operation should use the (LoRaWAN 1.0.3) Application Key.
LMIC_SecureElement_KeySelector_SIZE	One greater than maximum value in this enum.