IEEE 802.15.4 security

IEEE 802.15.4 security header. More...

Detailed Description

IEEE 802.15.4 security header.

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
 IEEE802.15.4 security device descriptor. More...
 
struct  ieee802154_sec_context
 Struct to hold IEEE 802.15.4 security information. More...
 
struct  ieee802154_aux_sec_t
 IEEE 802.15.4 auxiliary security header. More...
 
struct  ieee802154_aux_sec_key_identifier_1_t
 Content of key_source if key mode is IEEE802154_SCF_KEYMODE_INDEX. More...
 
struct  ieee802154_aux_sec_key_identifier_5_t
 Content of key_source if key mode is IEEE802154_SCF_KEYMODE_SHORT_INDEX. More...
 
struct  ieee802154_aux_sec_key_identifier_9_t
 Content of key_source if key mode is IEEE802154_SCF_KEYMODE_HW_INDEX. More...
 
struct  ieee802154_ccm_nonce_t
 Format of 13 byte nonce. More...
 
struct  ieee802154_ccm_block_t
 Format of 16 byte input block of CCM. More...
 

Macros

#define IEEE802154_DEFAULT_KEY
 AES key that is used in the test vectors from the specification. More...
 
#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_MAX_AUX_HDR_LEN   (14U)
 Maximum length of the security auxiliary header in bytes.
 
#define IEEE802154_MAC_SIZE   (16U)
 Maximum Size of IEEE 802.15.4 MAC.
 
#define IEEE802154_SCF_SECLEVEL_MASK   (0x07)
 Mask to get security level bits.
 
#define IEEE802154_SCF_SECLEVEL_SHIFT   (0)
 Number of shifts to set/get security level bits.
 
#define IEEE802154_SCF_KEYMODE_MASK   (0x18)
 Mask to get key mode bits.
 
#define IEEE802154_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 IEEE802.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_scf_seclevel_t {
  IEEE802154_SCF_SECLEVEL_NONE = 0x00, IEEE802154_SCF_SECLEVEL_MIC32 = 0x01, IEEE802154_SCF_SECLEVEL_MIC64 = 0x02, IEEE802154_SCF_SECLEVEL_MIC128 = 0x03,
  IEEE802154_SCF_SECLEVEL_ENC = 0x04, IEEE802154_SCF_SECLEVEL_ENC_MIC32 = 0x05, IEEE802154_SCF_SECLEVEL_ENC_MIC64 = 0x06, IEEE802154_SCF_SECLEVEL_ENC_MIC128 = 0x07
}
 Security levels. More...
 
enum  ieee802154_scr_keymode_t { IEEE802154_SCF_KEYMODE_IMPLICIT = 0x00, IEEE802154_SCF_KEYMODE_INDEX = 0x01, IEEE802154_SCF_KEYMODE_SHORT_INDEX = 0x02, IEEE802154_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. More...
 
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. More...
 
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. More...
 
void ieee802154_sec_set_key (ieee802154_sec_dev_t *dev, const uint8_t *key, uint8_t key_size)
 Set the encryption key to be used for the next cipher operation. More...
 
void ieee802154_sec_ecb (const ieee802154_sec_dev_t *dev, uint8_t *cipher, const uint8_t *plain, uint8_t nblocks)
 Perform ECB block cipher for IEEE802154 security layer. More...
 
void ieee802154_sec_cbc (const ieee802154_sec_dev_t *dev, uint8_t *cipher, uint8_t *iv, const uint8_t *plain, uint8_t nblocks)
 Perform CBC block cipher for IEEE802154 security layer MIC computation. More...
 

Variables

const ieee802154_radio_cipher_ops_t ieee802154_radio_cipher_ops
 Implements ieee802154_sec_set_key, ieee802154_sec_ecb, ieee802154_sec_cbc.
 

Macro Definition Documentation

◆ IEEE802154_DEFAULT_KEY

#define IEEE802154_DEFAULT_KEY
Value:
{ 0xc0, 0xc1, 0xc2, 0xc3, \
0xc4, 0xc5, 0xc6, 0xc7, \
0xc8, 0xc9, 0xca, 0xcb, \
0xcc, 0xcd, 0xce, 0xcf }

AES key that is used in the test vectors from the specification.

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

Definition at line 109 of file ieee802154_security.h.

Enumeration Type Documentation

◆ ieee802154_scf_seclevel_t

Security levels.

IEEE802154_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_SCF_SECLEVEL_ENC*: AES-128 in ECB mode is used to encrypt the payload of a frame to provide confidentiality.

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

Enumerator
IEEE802154_SCF_SECLEVEL_NONE 

no security

IEEE802154_SCF_SECLEVEL_MIC32 

32 bit MIC

IEEE802154_SCF_SECLEVEL_MIC64 

64 bit MIC

IEEE802154_SCF_SECLEVEL_MIC128 

128 bit MIC

IEEE802154_SCF_SECLEVEL_ENC 

encryption

IEEE802154_SCF_SECLEVEL_ENC_MIC32 

enc.

  • 32 bit MIC
IEEE802154_SCF_SECLEVEL_ENC_MIC64 

enc.

  • 64 bit MIC (mandatory)
IEEE802154_SCF_SECLEVEL_ENC_MIC128 

enc.

  • 128 bit MIC

Definition at line 173 of file ieee802154_security.h.

◆ ieee802154_scr_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_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. | +-------------—+----------—+---------------—+---------------------------------—+ | HX_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_SCF_KEYMODE_IMPLICIT 

Key is determined implicitly.

IEEE802154_SCF_KEYMODE_INDEX 

Key is determined from key index.

IEEE802154_SCF_KEYMODE_SHORT_INDEX 

Key is determined from 4 byte key source and key index.

IEEE802154_SCF_KEYMODE_HW_INDEX 

Key is determined from 8 byte key source and key index.

Definition at line 213 of file ieee802154_security.h.

◆ 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 223 of file ieee802154_security.h.

Function Documentation

◆ ieee802154_sec_cbc()

void ieee802154_sec_cbc ( const ieee802154_sec_dev_t dev,
uint8_t *  cipher,
uint8_t *  iv,
const uint8_t *  plain,
uint8_t  nblocks 
)

Perform CBC block cipher for IEEE802154 security layer MIC computation.

This function should be the default callback operation to perform CBC, if a radio does not provide special hardware security features.

Parameters
[in]devSecurity device
[out]cipherOutput cipher blocks
[in]ivInitial vector
[in]plainInput plain blocks
[in]nblocksNumber of blocks

◆ 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]ctxIEEE 802.15.4 security context
[in]frame_sizeSize of received frame
[in]headerPoinzter to header, which is also the frame
[in,out]header_sizein: Header size; out: Size of header and auxiliary header
[out]payloadWill point to the beginning of the payload
[out]payload_sizePointer to store the payload size
[out]micWill point to the beginning of the MIC
[out]mic_sizePointer to store the size of the MIC
[in]src_addressPointer to remote long source address
Precondition
After header follows the auxiliary header
Returns
0 Success
negative integer on error

◆ ieee802154_sec_ecb()

void ieee802154_sec_ecb ( const ieee802154_sec_dev_t dev,
uint8_t *  cipher,
const uint8_t *  plain,
uint8_t  nblocks 
)

Perform ECB block cipher for IEEE802154 security layer.

This function should be the default callback operation to perform ECB, if a radio does not provide special hardware security features.

Parameters
[in]devSecurity device
[out]cipherOutput cipher blocks
[in]plainInput plain blocks
[in]nblocksNumber of blocks

◆ 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]ctxIEEE 802.15.4 security context
[in]headerPointer to frame header
[in,out]header_sizein: Header size; out: Size of header and auxiliary header
[in,out]payloadin: Plain payload; out: Encrypted payload
[in]payload_sizeSize of payload
[out]micBuffer to store computed MIC
[out]mic_sizeSize of MIC
[in]src_addressSource 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]ctxsecurity context

◆ ieee802154_sec_set_key()

void ieee802154_sec_set_key ( ieee802154_sec_dev_t dev,
const uint8_t *  key,
uint8_t  key_size 
)

Set the encryption key to be used for the next cipher operation.

This function should be the default callback operation to set the encryption key, if a radio does not provide special hardware security features.

Parameters
[in]devSecurity device
[in]keyKey to be use for the next cipher operation
[in]key_sizeKey size