Security Module

Description

LDL depends on the interfaces in this group for performing cryptographic operations.

Function List
void	LDL_SM_init (struct ldl_sm *self, const void *appKey)
const struct ldl_sm_interface *	LDL_SM_getInterface (void)
void	LDL_SM_updateSessionKey (struct ldl_sm *self, enum ldl_sm_key keyDesc, enum ldl_sm_key rootDesc, const void *iv)
void	LDL_SM_beginUpdateSessionKey (struct ldl_sm *self)
void	LDL_SM_endUpdateSessionKey (struct ldl_sm *self)
uint32_t	LDL_SM_mic (struct ldl_sm *self, enum ldl_sm_key desc, const void *hdr, uint8_t hdrLen, const void *data, uint8_t dataLen)
void	LDL_SM_ecb (struct ldl_sm *self, enum ldl_sm_key desc, void *b)
void	LDL_SM_ctr (struct ldl_sm *self, enum ldl_sm_key desc, const void *iv, void *data, uint8_t len)

Functions

LDL_SM_init()

void LDL_SM_init	(	struct ldl_sm *	self,
		const void *	appKey
	)

Initialise Default Security Module with root key

Parameters

[in]	self	ldl_sm
[in]	appKey	pointer to 16 byte field

LDL_SM_getInterface()

const struct ldl_sm_interface* LDL_SM_getInterface

(

void

)

MAC can use this interface to talk to the default SM implementation

e.g.

struct ldl_mac_init_arg arg = {

     // ...

     .sm_interface = LDL_SM_getInterface()

     // ...
};

LDL_SM_updateSessionKey()

void LDL_SM_updateSessionKey	(	struct ldl_sm *	self,
		enum ldl_sm_key	keyDesc,
		enum ldl_sm_key	rootDesc,
		const void *	iv
	)

Update a session key and save the result in the key store

LoRaWAN session keys are derived from clear text encrypted with a root key.

Parameters

[in]	self
[in]	keyDesc	ldl_sm_key the key to update
[in]	rootDesc	ldl_sm_key the key to use as root key in derivation
[in]	iv	16B of text used to derive key

LDL_SM_beginUpdateSessionKey()

void LDL_SM_beginUpdateSessionKey

(

struct ldl_sm *

self

)

Signal the beginning of session key update transaction

SM implementations that perform batch updates can use this signal to initialise a cache prior to receiving multiple LDL_SM_updateSessionKey() calls.

Parameters

[in]

self

LDL_SM_endUpdateSessionKey()

void LDL_SM_endUpdateSessionKey

(

struct ldl_sm *

self

)

Signal the end session key update transaction

Always follows a previous call to LDL_SM_beginUpdateSessionKey().

SM implementations that perform batch updates can use this signal to perform the actual update operation on the cached key material.

Parameters

[in]

self

LDL_SM_mic()

uint32_t LDL_SM_mic	(	struct ldl_sm *	self,
		enum ldl_sm_key	desc,
		const void *	hdr,
		uint8_t	hdrLen,
		const void *	data,
		uint8_t	dataLen
	)

Lookup a key and use it to produce a MIC

The MIC is the four least-significant bytes of an AES-128 CMAC digest of (hdr|data), intepreted as a little-endian integer.

Note that sometimes hdr will be empty (hdr=NULL and hdrLen=0).

Parameters

[in]	self
[in]	desc	ldl_sm_key
[in]	hdr	may be NULL
[in]	hdrLen
[in]	data
[in]	dataLen

LDL_SM_ecb()

void LDL_SM_ecb	(	struct ldl_sm *	self,
		enum ldl_sm_key	desc,
		void *	b
	)

Lookup a key and use it to perform ECB AES-128 in-place

Parameters

[in]	self
[in]	desc	ldl_sm_key
[in]	b	16B block to encrypt in-place (arbitrary alignment)

LDL_SM_ctr()

void LDL_SM_ctr	(	struct ldl_sm *	self,
		enum ldl_sm_key	desc,
		const void *	iv,
		void *	data,
		uint8_t	len
	)

Lookup a key and use it to perform CTR AES-128 in-place

Parameters

[in]	self
[in]	desc	ldl_sm_key
[in]	iv	16B block to be used as a nonce/intial value (word aligned)
[in]	data
[in]	len

---

Data Structure Documentation

ldl_sm

struct ldl_sm

default in-memory security module state

Enumeration Type Documentation

ldl_sm_key

enum ldl_sm_key

SM key descriptor

Enumerator
LDL_SM_KEY_FNWKSINT	FNwkSInt forwarding/uplink (also used as NwkSKey)
LDL_SM_KEY_APPS	AppSKey
LDL_SM_KEY_SNWKSINT	SNwkSInt serving/downlink
LDL_SM_KEY_NWKSENC	NwkSEnc
LDL_SM_KEY_JSENC	JSEncKey
LDL_SM_KEY_JSINT	JSIntKey
LDL_SM_KEY_APP	application root key
LDL_SM_KEY_NWK	network root key