mac_security.h

/**
 * Copyright (c) 2016 - 2017 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