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
 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 IEEE802154_SEC_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_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. More...
 
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. 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...
 

Variables

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

Macro Definition Documentation

◆ IEEE802154_SEC_DEFAULT_KEY

#define IEEE802154_SEC_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 111 of file ieee802154_security.h.

Typedef Documentation

◆ 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.

Enumeration Type Documentation

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

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

◆ 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 175 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]ctxIEEE 802.15.4 security context
[in]frame_sizeSize of received frame
[in]headerPointer 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_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]ctxIEEE 802.15.4 security context