IEEE 802.15.4 security

IEEE 802.15.4 security header. More...

Detailed Description

IEEE 802.15.4 security header.

Warning

This module is exposing raw 802.15.4 encryption without an underlying key management framework. This is intended for experimentation with the security modes of 802.15.4, and not for use cases where its security is depended on.

Files
file	ieee802154_security.h
	IEEE 802.15.4 security interface.

Data Structures
struct	ieee802154_radio_cipher_ops
	Struct of security operations. More...
struct	ieee802154_sec_dev
	IEEE 802.15.4 security device descriptor. More...
struct	ieee802154_sec_context
	Struct to hold IEEE 802.15.4 security information. More...
struct	ieee802154_sec_aux_t
	IEEE 802.15.4 auxiliary security header. More...
struct	ieee802154_sec_aux_key_identifier_1_t
	Content of key_source if key mode is IEEE802154_SEC_SCF_KEYMODE_INDEX. More...
struct	ieee802154_sec_aux_key_identifier_5_t
	Content of key_source if key mode is IEEE802154_SEC_SCF_KEYMODE_SHORT_INDEX. More...
struct	ieee802154_sec_aux_key_identifier_9_t
	Content of key_source if key mode is IEEE802154_SEC_SCF_KEYMODE_HW_INDEX. More...
struct	ieee802154_sec_ccm_nonce_t
	Format of 13 byte nonce. More...
struct	ieee802154_sec_ccm_block_t
	Format of 16 byte input block of CCM. More...

Macros
#define	CONFIG_IEEE802154_SEC_DEFAULT_KEY   "pizza_margherita"
	AES default key.
#define	IEEE802154_SEC_KEY_LENGTH   (16U)
	Length of an AES key in bytes.
#define	IEEE802154_SEC_BLOCK_SIZE   (16U)
	Block size of an encryption block.
#define	IEEE802154_SEC_MAX_AUX_HDR_LEN   (14U)
	Maximum length of the security auxiliary header in bytes.
#define	IEEE802154_SEC_MAX_MAC_SIZE   (16U)
	Maximum Size of IEEE 802.15.4 MAC.
#define	IEEE802154_SEC_SCF_SECLEVEL_MASK   (0x07)
	Mask to get security level bits.
#define	IEEE802154_SEC_SCF_SECLEVEL_SHIFT   (0)
	Number of shifts to set/get security level bits.
#define	IEEE802154_SEC_SCF_KEYMODE_MASK   (0x18)
	Mask to get key mode bits.
#define	IEEE802154_SEC_SCF_KEYMODE_SHIFT   (3)
	Number of shifts to set/get key mode bits.

Typedefs
typedef struct ieee802154_sec_dev	ieee802154_sec_dev_t
	Forward declaration of an IEEE 802.15.4 abstract security device.
typedef struct ieee802154_radio_cipher_ops	ieee802154_radio_cipher_ops_t
	Struct of security operations.
typedef struct ieee802154_sec_context	ieee802154_sec_context_t
	Struct to hold IEEE 802.15.4 security information.

Enumerations
enum	ieee802154_sec_scf_seclevel_t {   IEEE802154_SEC_SCF_SECLEVEL_NONE = 0x00 , IEEE802154_SEC_SCF_SECLEVEL_MIC32 = 0x01 , IEEE802154_SEC_SCF_SECLEVEL_MIC64 = 0x02 , IEEE802154_SEC_SCF_SECLEVEL_MIC128 = 0x03 ,   IEEE802154_SEC_SCF_SECLEVEL_ENC = 0x04 , IEEE802154_SEC_SCF_SECLEVEL_ENC_MIC32 = 0x05 , IEEE802154_SEC_SCF_SECLEVEL_ENC_MIC64 = 0x06 , IEEE802154_SEC_SCF_SECLEVEL_ENC_MIC128 = 0x07 }
	Security levels. More...
enum	ieee802154_sec_scf_keymode_t { IEEE802154_SEC_SCF_KEYMODE_IMPLICIT = 0x00 , IEEE802154_SEC_SCF_KEYMODE_INDEX = 0x01 , IEEE802154_SEC_SCF_KEYMODE_SHORT_INDEX = 0x02 , IEEE802154_SEC_SCF_KEYMODE_HW_INDEX = 0x03 }
	Key identifier modes. More...
enum	ieee802154_sec_error_t {   IEEE802154_SEC_OK , IEEE802154_SEC_FRAME_COUNTER_OVERFLOW , IEEE802154_SEC_NO_KEY , IEEE802154_SEC_MAC_CHECK_FAILURE ,   IEEE802154_SEC_UNSUPORTED }
	IEEE 802.15.4 security error codes. More...

Functions
void	ieee802154_sec_init (ieee802154_sec_context_t *ctx)
	Initialize IEEE 802.15.4 security context with default values.
int	ieee802154_sec_encrypt_frame (ieee802154_sec_context_t *ctx, const uint8_t *header, uint8_t *header_size, uint8_t *payload, uint16_t payload_size, uint8_t *mic, uint8_t *mic_size, const uint8_t *src_address)
	Encrypt IEEE 802.15.4 frame according to ctx.
int	ieee802154_sec_decrypt_frame (ieee802154_sec_context_t *ctx, uint16_t frame_size, uint8_t *header, uint8_t *header_size, uint8_t **payload, uint16_t *payload_size, uint8_t **mic, uint8_t *mic_size, const uint8_t *src_address)
	Decrypt IEEE 802.15.4 frame according to ctx.

Variables
const ieee802154_radio_cipher_ops_t	ieee802154_radio_cipher_ops
	Default descriptor that will fallback to default implementations.

Macro Definition Documentation

CONFIG_IEEE802154_SEC_DEFAULT_KEY

#define CONFIG_IEEE802154_SEC_DEFAULT_KEY   "pizza_margherita"

AES default key.

Note

Predefine it yourself, if you want another key to be set up on initialization

Definition at line 116 of file ieee802154_security.h.

IEEE802154_SEC_BLOCK_SIZE

#define IEEE802154_SEC_BLOCK_SIZE   (16U)

Block size of an encryption block.

Definition at line 127 of file ieee802154_security.h.

IEEE802154_SEC_KEY_LENGTH

#define IEEE802154_SEC_KEY_LENGTH   (16U)

Length of an AES key in bytes.

Definition at line 122 of file ieee802154_security.h.

IEEE802154_SEC_MAX_AUX_HDR_LEN

#define IEEE802154_SEC_MAX_AUX_HDR_LEN   (14U)

Maximum length of the security auxiliary header in bytes.

Definition at line 132 of file ieee802154_security.h.

IEEE802154_SEC_MAX_MAC_SIZE

#define IEEE802154_SEC_MAX_MAC_SIZE   (16U)

Maximum Size of IEEE 802.15.4 MAC.

Definition at line 137 of file ieee802154_security.h.

IEEE802154_SEC_SCF_KEYMODE_MASK

#define IEEE802154_SEC_SCF_KEYMODE_MASK   (0x18)

Mask to get key mode bits.

Definition at line 152 of file ieee802154_security.h.

IEEE802154_SEC_SCF_KEYMODE_SHIFT

#define IEEE802154_SEC_SCF_KEYMODE_SHIFT   (3)

Number of shifts to set/get key mode bits.

Definition at line 157 of file ieee802154_security.h.

IEEE802154_SEC_SCF_SECLEVEL_MASK

#define IEEE802154_SEC_SCF_SECLEVEL_MASK   (0x07)

Mask to get security level bits.

Definition at line 142 of file ieee802154_security.h.

IEEE802154_SEC_SCF_SECLEVEL_SHIFT

#define IEEE802154_SEC_SCF_SECLEVEL_SHIFT   (0)

Number of shifts to set/get security level bits.

Definition at line 147 of file ieee802154_security.h.

Typedef Documentation

ieee802154_radio_cipher_ops_t

typedef struct ieee802154_radio_cipher_ops ieee802154_radio_cipher_ops_t

Struct of security operations.

Note

A device can indicate that the fallback implementations should be used by setting the corresponding member to NULL, or pointing to ieee802154_radio_cipher_ops, which does the same. Note that ieee802154_radio_cipher_ops is the default security operations driver assigned when ieee802154_sec_init is called.

ieee802154_sec_dev_t

typedef struct ieee802154_sec_dev ieee802154_sec_dev_t

Forward declaration of an IEEE 802.15.4 abstract security device.

Definition at line 44 of file ieee802154_security.h.

Enumeration Type Documentation

ieee802154_sec_error_t

enum ieee802154_sec_error_t

IEEE 802.15.4 security error codes.

Enumerator
IEEE802154_SEC_OK	Everything went fine.
IEEE802154_SEC_FRAME_COUNTER_OVERFLOW	The requested operation would let the frame counter overflow.
IEEE802154_SEC_NO_KEY	Could not find the key to perform a requested cipher operation.
IEEE802154_SEC_MAC_CHECK_FAILURE	The computet MAC did not match.
IEEE802154_SEC_UNSUPORTED	Unsupported operation.

Definition at line 227 of file ieee802154_security.h.

ieee802154_sec_scf_keymode_t

enum ieee802154_sec_scf_keymode_t

Key identifier modes.

The key identifier field in the auxiliary header consists of the key source and the key index fields and is only present if the key identifier mode is not IEEE802154_SEC_SCF_KEYMODE_IMPLICIT. (see 9.4.3 in the spec.)

+-------------—+----------—+---------------—+---------------------------------—+ | mode | key source | key index | description | +-------------—+----------—+---------------—+---------------------------------—+ | IMPLICIT | 0 bytes | 0 bytes | The key is implicitly | | | | | known to the receiver. | +-------------—+----------—+---------------—+---------------------------------—+ | INDEX | 0 bytes | 1 byte | The key can be determined | | | | | from the key index. | +-------------—+----------—+---------------—+---------------------------------—+ | SHORT_INDEX | 4 bytes | 1 byte | The key is a group key and can be | | | | | determined from the key index and | | | | | the source PAN ID and the | | | | | short source address | | | | | of the originator of the frame. | +-------------—+----------—+---------------—+---------------------------------—+ | HW_INDEX | 8 bytes | 1 byte | The key can be determined | | | | | from the key index and | | | | | the long address of the originator | | | | | of the frame. | +-------------—+----------—+---------------—+---------------------------------—+

Enumerator
IEEE802154_SEC_SCF_KEYMODE_IMPLICIT	Key is determined implicitly.
IEEE802154_SEC_SCF_KEYMODE_INDEX	Key is determined from key index.
IEEE802154_SEC_SCF_KEYMODE_SHORT_INDEX	Key is determined from 4 byte key source and key index.
IEEE802154_SEC_SCF_KEYMODE_HW_INDEX	Key is determined from 8 byte key source and key index.

Definition at line 217 of file ieee802154_security.h.

ieee802154_sec_scf_seclevel_t

enum ieee802154_sec_scf_seclevel_t

Security levels.

IEEE802154_SEC_SCF_SECLEVEL_MIC*: A message integrity code (MIC), also known as MAC, is used to prove authentication. The MIC covers the whole frame i.e. header, auxiliary header, and frame payload. The MIC is always encrypted, thus it must be decrypted by the receiver, to be checked.

IEEE802154_SEC_SCF_SECLEVEL_ENC*: AES-128 in ECB mode is used to encrypt the payload of a frame to provide confidentiality.

IEEE802154_SEC_SCF_SECLEVEL_ENC_MIC*: A combination of the two modes above is used to ensure authentication and confidentiality.

Enumerator
IEEE802154_SEC_SCF_SECLEVEL_NONE	no security
IEEE802154_SEC_SCF_SECLEVEL_MIC32	32 bit MIC
IEEE802154_SEC_SCF_SECLEVEL_MIC64	64 bit MIC
IEEE802154_SEC_SCF_SECLEVEL_MIC128	128 bit MIC
IEEE802154_SEC_SCF_SECLEVEL_ENC	encryption
IEEE802154_SEC_SCF_SECLEVEL_ENC_MIC32	enc. 32 bit MIC
IEEE802154_SEC_SCF_SECLEVEL_ENC_MIC64	enc. 64 bit MIC (mandatory)
IEEE802154_SEC_SCF_SECLEVEL_ENC_MIC128	enc. 128 bit MIC

Definition at line 177 of file ieee802154_security.h.

Function Documentation

ieee802154_sec_decrypt_frame()

int ieee802154_sec_decrypt_frame	(	ieee802154_sec_context_t *	ctx,
		uint16_t	frame_size,
		uint8_t *	header,
		uint8_t *	header_size,
		uint8_t **	payload,
		uint16_t *	payload_size,
		uint8_t **	mic,
		uint8_t *	mic_size,
		const uint8_t *	src_address
	)

Decrypt IEEE 802.15.4 frame according to ctx.

Parameters

[in]	ctx	IEEE 802.15.4 security context
[in]	frame_size	Size of received frame
[in]	header	Pointer to header, which is also the frame
[in,out]	header_size	in: Header size; out: Size of header and auxiliary header
[out]	payload	Will point to the beginning of the payload
[out]	payload_size	Pointer to store the payload size
[out]	mic	Will point to the beginning of the MIC
[out]	mic_size	Pointer to store the size of the MIC
[in]	src_address	Pointer to remote long source address

Precondition

After header follows the auxiliary header

Returns

0 Success

negative integer on error

ieee802154_sec_encrypt_frame()

int ieee802154_sec_encrypt_frame	(	ieee802154_sec_context_t *	ctx,
		const uint8_t *	header,
		uint8_t *	header_size,
		uint8_t *	payload,
		uint16_t	payload_size,
		uint8_t *	mic,
		uint8_t *	mic_size,
		const uint8_t *	src_address
	)

Encrypt IEEE 802.15.4 frame according to ctx.

Parameters

[in]	ctx	IEEE 802.15.4 security context
[in]	header	Pointer to frame header
[in,out]	header_size	in: Header size; out: Size of header and auxiliary header
[in,out]	payload	in: Plain payload; out: Encrypted payload
[in]	payload_size	Size of payload
[out]	mic	Buffer to store computed MIC
[out]	mic_size	Size of MIC
[in]	src_address	Source address

Precondition

header should be large enough to also store the auxiliary header

Returns

0 Success

negative integer on error

ieee802154_sec_init()

void ieee802154_sec_init

(

ieee802154_sec_context_t *

ctx

)

Initialize IEEE 802.15.4 security context with default values.

Parameters

[out]

ctx

IEEE 802.15.4 security context