diff options
Diffstat (limited to 'thirdparty/nRF5_SDK_15.0.0_a53641a/components/802_15_4/api/MAC/mac_security.h')
| -rw-r--r-- | thirdparty/nRF5_SDK_15.0.0_a53641a/components/802_15_4/api/MAC/mac_security.h | 318 |
1 files changed, 318 insertions, 0 deletions
diff --git a/thirdparty/nRF5_SDK_15.0.0_a53641a/components/802_15_4/api/MAC/mac_security.h b/thirdparty/nRF5_SDK_15.0.0_a53641a/components/802_15_4/api/MAC/mac_security.h new file mode 100644 index 0000000..295d387 --- /dev/null +++ b/thirdparty/nRF5_SDK_15.0.0_a53641a/components/802_15_4/api/MAC/mac_security.h @@ -0,0 +1,318 @@ +/** + * Copyright (c) 2016 - 2018 Nordic Semiconductor ASA and Luxoft Global Operations Gmbh. + * + * All Rights Reserved. + * + * Redistribution and use in source and binary forms, with or without modification, + * are permitted provided that the following conditions are met: + * + * + * 1. Redistributions of source code must retain the above copyright notice, this + * list of conditions and the following disclaimer. + * + * 2. Redistributions in binary form, except as embedded into a Nordic + * Semiconductor ASA integrated circuit in a product or a software update for + * such product, must reproduce the above copyright notice, this list of + * conditions and the following disclaimer in the documentation and/or other + * materials provided with the distribution. + * + * 3. Neither the name of Nordic Semiconductor ASA nor the names of its + * contributors may be used to endorse or promote products derived from this + * software without specific prior written permission. + * + * 4. This software, with or without modification, must only be used with a + * Nordic Semiconductor ASA integrated circuit. + * + * 5. Any software provided in binary form under this license must not be reverse + * engineered, decompiled, modified and/or disassembled. + * + * + * THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA "AS IS" AND ANY EXPRESS + * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + * OF MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE + * DISCLAIMED. IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE + * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT + * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + * + */ +#ifndef MAC_SECURITY_H_INCLUDED +#define MAC_SECURITY_H_INCLUDED + +#include "sys_queue.h" +#include "sec_aes_ccm.h" + +/** @file + * The MAC MLME Security module declares the MAC Security types + * according to the MAC specification. + * + * @defgroup mac_security MAC MLME Security API + * @ingroup mac_15_4 + * @{ + * @brief Module to declare MAC MLME Security API. + * @details The MAC Security module declares types/macros needed to implement and use the MAC security + * engine according to the MAC specification. No routines or callbacks are declared here. + */ + +/** + * @brief MAC sublayer security levels. + * + * In accordance with IEEE Std 802.15.4-2006, section 7.6.2.2.1 + */ +typedef enum +{ + MAC_SEC_OFF = 0, /**< Security is OFF. */ + MAC_SEC_MIC32, /**< MIC32 security. */ + MAC_SEC_MIC64, /**< MIC64 security. */ + MAC_SEC_MIC128, /**< MIC128 security. */ + MAC_SEC_ENC, /**< ENC security. */ + MAC_SEC_ENC_MIC32, /**< ENC/MIC32 security. */ + MAC_SEC_ENC_MIC64, /**< ENC/MIC64 security. */ + MAC_SEC_ENC_MIC128 /**< ENC/MIC128 security. */ +} mac_security_level_t; + + +/** + * @brief MAC key identifier mode. + * + * In accordance with IEEE Std 802.15.4-2006, section 7.6.2.2.2 + */ +typedef enum +{ + MAC_KEY_ID_IMPL = 0, /**< Impl. */ + MAC_KEY_ID_ONE_OCTET, /**< One octet. */ + MAC_KEY_ID_FOUR_OCTET, /**< 4 octets. */ + MAC_KEY_ID_EIGHT_OCTET /**< 8 octets. */ +} mac_key_id_mode_t; + +/**@brief Size (in bytes) of short security look up item. This size is + * set when lookup size equals to 0. + */ +#define MAC_LOOKUP_DATA_SIZE_SHORT 5 + +/**@brief Size (in bytes) of long security Key look up item. This size is + * set when lookup size equals to 1. + */ +#define MAC_KEY_LOOKUP_DATA_SIZE_LONG 9 + +/**@brief Size (in bytes) of long security Data look up item. This size is + * set when lookup size equals to 1. + */ +#define MAC_DATA_LOOKUP_DATA_SIZE_LONG 8 + +/**@brief Length of \a mac_key_source_t. Equals to extended address length. */ +#define MAC_KEY_SOURCE_SIZE 8 + +/**@brief This bit-mask is used to get UniqueDevice field value of + * \a mac_key_device_descr_t. + */ +#define MAC_KEY_DEVICE_FLAG_UNIQUE 0x01 + +/**@brief This bit-mask is used to get BlackListed field value of + * \a mac_key_device_descr_t. + */ +#define MAC_KEY_DEVICE_FLAG_BLACKLISTED 0x02 + +/**@brief Length of key. */ +#define MAC_SECURITY_KEY_SIZE 16 + +/**@brief Length of nonce for aes-ccm algorithm .*/ +#define MAC_SECURITY_NONCE_SIZE 13 + +/**@brief Maximum MIC size .*/ +#define MAX_MIC_SIZE 16 + +/**@brief This type is used to store security key .*/ +typedef uint8_t mac_key_t[MAC_SECURITY_KEY_SIZE]; + +/**@brief This type is used to store security key lookup data .*/ +typedef uint8_t mac_key_lookup_data_t[MAC_KEY_LOOKUP_DATA_SIZE_LONG]; + +/**@brief This type is used to store security data lookup data .*/ +typedef uint8_t mac_data_lookup_data_t[MAC_DATA_LOOKUP_DATA_SIZE_LONG]; + +/**@brief This type is used to store security key source address .*/ +typedef uint64_t mac_key_source_t; + +/**@brief This type represents key LookupDataSize according to Table 94 .*/ +typedef enum +{ + KEY_LOOKUP_SIZE_FIVE = 0, /**< Size is 5. */ + KEY_LOOKUP_SIZE_NINE = 1 /**< Size is 9. */ +} mac_key_lookup_size_t; + +/**@brief This type represents real size of key LookupData .*/ +typedef enum +{ + KEY_LOOKUP_SIZE_FIVE_VAL = 5, /**< Size is 5. */ + KEY_LOOKUP_SIZE_NINE_VAL = 9 /**< Size is 9. */ +} mac_key_lookup_size_val_t; + +/**@brief This type represents data LookupDataSize .*/ +typedef enum +{ + DATA_LOOKUP_SIZE_FOUR_VAL = 4, /**< Size is 4. */ + DATA_LOOKUP_SIZE_EIGHT_VAL = 8 /**< Size is 8. */ +} mac_data_lookup_size_val_t; + +/**@brief Abstract type to work with growing tables such as some of MAC + * security attributes. + */ +typedef struct +{ + sys_queue_t queue; /**< Service field .*/ + uint8_t size; /**< Number of currently allocated + items inside the table .*/ +} mac_table_t; + +/**@brief Due to processing algorithm this field MUST be the first inside a + * table or list. + */ +typedef struct +{ + sys_queue_item_t item; /**< Service field .*/ + uint8_t idx; /**< Index inside table .*/ +} mac_table_item_t; + +/**@brief KeyIdLookupDescriptor as described in Table 94 .*/ +typedef struct +{ + mac_table_item_t table_service; /**< Service field .*/ + mac_key_lookup_data_t data; /**< Set of 5 or 9 bytes. + Data used to identify the key .*/ + mac_key_lookup_size_t size; /**< A value of LOOKUP_SIZE_FIVE indicates a set + of 5 bytes; a value of LOOKUP_SIZE_NINE + indicates a set of 9 bytes .*/ +} mac_key_id_lookup_descr_t; + + +/**@brief KeyIdLookupLis as described in Table 89 .*/ +typedef mac_table_t mac_key_id_lookup_list_t; + + +/**@brief DeviceDescriptor as described in Table 93 .*/ +typedef struct +{ + mac_table_item_t table_service; /**< Service field .*/ + uint16_t pan_id; /**< The 16-bit PAN identifier of the device in + this DeviceDescriptor .*/ + uint16_t short_address; /**< The 16-bit short address of the device in + this DeviceDescriptor. A value of + #MAC_EXTENDED_ADDRESS_ONLY + indicates that this device is using only its + extended address. A value of + #MAC_BROADCAST_SHORT_ADDRESS + indicates that this value is unknown .*/ + uint64_t extended_address; /**< The 64-bit IEEE extended address of the + device in this DeviceDescriptor. This + element is also used in unsecuring + operations on incoming frames .*/ + uint32_t frame_counter; /**< The incoming frame counter of the device + in this DeviceDescriptor. This value is used + to ensure sequential freshness of frames .*/ + bool exempt; /**< Indication of whether the device may + override the minimum security level + settings defined in \a mac_security_level_table_t .*/ +} mac_device_descr_t; + + +/**@brief DeviceTable as described in Table 93 .*/ +typedef mac_table_t mac_device_table_t; + + +/**@brief KeyDeviceDescriptor as described in Table 91 .*/ +typedef struct +{ + mac_table_item_t table_service; /**< Service field .*/ + uint8_t device_handle; /**< Handle to the DeviceDescriptor + corresponding to the device (see + \a mac_device_descr_t). + The value is an index of the device descriptor + instance from device table .*/ + uint8_t unique_device : 1; /**< Indication of whether the device indicated + by DeviceDescriptorHandle is uniquely + associated with the KeyDescriptor, i.e., it + is a link key as opposed to a group key .*/ + uint8_t blacklisted : 1; /**< Indication of whether the device indicated + by DeviceDescriptorHandle previously + communicated with this key prior to the + exhaustion of the frame counter. If TRUE, + this indicates that the device shall not use + this key further because it exhausted its + use of the frame counter used with this + key .*/ +} mac_key_device_descr_t; + + +/**@brief KeyDeviceList as described in Table 89 .*/ +typedef mac_table_t mac_key_device_list_t; + + +/**@brief KeyUsageDescriptor as described in Table 90 .*/ +typedef struct +{ + mac_table_item_t table_service; /**< Service field .*/ + + uint8_t frame_type : 3; /**< See \a mac_frame_type_t .*/ + uint8_t cmd_frame_id : 4; /**< See \a mac_command_id_t .*/ +} mac_key_usage_descr_t; + + +/**@brief KeyUsageList as described in Table 89 .*/ +typedef mac_table_t mac_key_usage_list_t; + + +/**@brief KeyDescriptor as described in Table 89 .*/ +typedef struct +{ + mac_table_item_t table_service; /**< Service field .*/ + mac_key_id_lookup_list_t id_lookup_list; /**< A list of KeyIdLookupDescriptor entries + used to identify this KeyDescriptor .*/ + mac_key_device_list_t key_device_list; /**< A list of KeyDeviceDescriptor entries + indicating which devices are currently + using this key, including their blacklist + status .*/ + mac_key_usage_list_t key_usage_list; /**< A list of KeyUsageDescriptor entries + indicating which frame types this key may + be used with .*/ + mac_key_t key; /**< The actual value of the key .*/ +} mac_key_descr_t; + + +/**@brief KeyTable as described in Table 88 .*/ +typedef mac_table_t mac_key_table_t; + + +/**@brief SecurityLevelDescriptor as described in Table 93 .*/ +typedef struct +{ + mac_table_item_t table_service; /**< Service field. */ + + uint16_t frame_type : 3; /**< See \a mac_frame_type_t .*/ + uint16_t cmd_frame_id : 4; /**< See \a mac_command_id_t .*/ + uint16_t security_min : 3; /**< The minimal required/expected security + level for incoming MAC frames with the + indicated frame type and, if present, + command frame type (see + \a mac_security_level_t) .*/ + uint16_t override_min : 1; /**< Indication of whether originating devices + for which the Exempt flag is set may + override the minimum security level + indicated by the SecurityMinimum + element. If TRUE, this indicates that for + originating devices with Exempt status, + the incoming security level zero is + acceptable, in addition to the incoming + security levels meeting the minimum + expected security level indicated by the + SecurityMinimum element .*/ +} mac_security_level_descr_t; + +typedef mac_table_t mac_security_level_table_t; + +/** @} */ + +#endif // MAC_SECURITY_H_INCLUDED |