mac_security.h 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318
  1. /**
  2. * Copyright (c) 2016 - 2020 Nordic Semiconductor ASA and Luxoft Global Operations Gmbh.
  3. *
  4. * All Rights Reserved.
  5. *
  6. * Redistribution and use in source and binary forms, with or without modification,
  7. * are permitted provided that the following conditions are met:
  8. *
  9. *
  10. * 1. Redistributions of source code must retain the above copyright notice, this
  11. * list of conditions and the following disclaimer.
  12. *
  13. * 2. Redistributions in binary form, except as embedded into a Nordic
  14. * Semiconductor ASA integrated circuit in a product or a software update for
  15. * such product, must reproduce the above copyright notice, this list of
  16. * conditions and the following disclaimer in the documentation and/or other
  17. * materials provided with the distribution.
  18. *
  19. * 3. Neither the name of Nordic Semiconductor ASA nor the names of its
  20. * contributors may be used to endorse or promote products derived from this
  21. * software without specific prior written permission.
  22. *
  23. * 4. This software, with or without modification, must only be used with a
  24. * Nordic Semiconductor ASA integrated circuit.
  25. *
  26. * 5. Any software provided in binary form under this license must not be reverse
  27. * engineered, decompiled, modified and/or disassembled.
  28. *
  29. *
  30. * THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA "AS IS" AND ANY EXPRESS
  31. * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  32. * OF MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE
  33. * DISCLAIMED. IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA OR CONTRIBUTORS BE
  34. * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  35. * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
  36. * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  37. * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  38. * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  39. * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  40. *
  41. */
  42. #ifndef MAC_SECURITY_H_INCLUDED
  43. #define MAC_SECURITY_H_INCLUDED
  44. #include "sys_queue.h"
  45. #include "sec_aes_ccm.h"
  46. /** @file
  47. * The MAC MLME Security module declares the MAC Security types
  48. * according to the MAC specification.
  49. *
  50. * @defgroup mac_security MAC MLME Security API
  51. * @ingroup mac_15_4
  52. * @{
  53. * @brief Module to declare MAC MLME Security API.
  54. * @details The MAC Security module declares types/macros needed to implement and use the MAC security
  55. * engine according to the MAC specification. No routines or callbacks are declared here.
  56. */
  57. /**
  58. * @brief MAC sublayer security levels.
  59. *
  60. * In accordance with IEEE Std 802.15.4-2006, section 7.6.2.2.1
  61. */
  62. typedef enum
  63. {
  64. MAC_SEC_OFF = 0, /**< Security is OFF. */
  65. MAC_SEC_MIC32, /**< MIC32 security. */
  66. MAC_SEC_MIC64, /**< MIC64 security. */
  67. MAC_SEC_MIC128, /**< MIC128 security. */
  68. MAC_SEC_ENC, /**< ENC security. */
  69. MAC_SEC_ENC_MIC32, /**< ENC/MIC32 security. */
  70. MAC_SEC_ENC_MIC64, /**< ENC/MIC64 security. */
  71. MAC_SEC_ENC_MIC128 /**< ENC/MIC128 security. */
  72. } mac_security_level_t;
  73. /**
  74. * @brief MAC key identifier mode.
  75. *
  76. * In accordance with IEEE Std 802.15.4-2006, section 7.6.2.2.2
  77. */
  78. typedef enum
  79. {
  80. MAC_KEY_ID_IMPL = 0, /**< Impl. */
  81. MAC_KEY_ID_ONE_OCTET, /**< One octet. */
  82. MAC_KEY_ID_FOUR_OCTET, /**< 4 octets. */
  83. MAC_KEY_ID_EIGHT_OCTET /**< 8 octets. */
  84. } mac_key_id_mode_t;
  85. /**@brief Size (in bytes) of short security look up item. This size is
  86. * set when lookup size equals to 0.
  87. */
  88. #define MAC_LOOKUP_DATA_SIZE_SHORT 5
  89. /**@brief Size (in bytes) of long security Key look up item. This size is
  90. * set when lookup size equals to 1.
  91. */
  92. #define MAC_KEY_LOOKUP_DATA_SIZE_LONG 9
  93. /**@brief Size (in bytes) of long security Data look up item. This size is
  94. * set when lookup size equals to 1.
  95. */
  96. #define MAC_DATA_LOOKUP_DATA_SIZE_LONG 8
  97. /**@brief Length of \a mac_key_source_t. Equals to extended address length. */
  98. #define MAC_KEY_SOURCE_SIZE 8
  99. /**@brief This bit-mask is used to get UniqueDevice field value of
  100. * \a mac_key_device_descr_t.
  101. */
  102. #define MAC_KEY_DEVICE_FLAG_UNIQUE 0x01
  103. /**@brief This bit-mask is used to get BlackListed field value of
  104. * \a mac_key_device_descr_t.
  105. */
  106. #define MAC_KEY_DEVICE_FLAG_BLACKLISTED 0x02
  107. /**@brief Length of key. */
  108. #define MAC_SECURITY_KEY_SIZE 16
  109. /**@brief Length of nonce for aes-ccm algorithm .*/
  110. #define MAC_SECURITY_NONCE_SIZE 13
  111. /**@brief Maximum MIC size .*/
  112. #define MAX_MIC_SIZE 16
  113. /**@brief This type is used to store security key .*/
  114. typedef uint8_t mac_key_t[MAC_SECURITY_KEY_SIZE];
  115. /**@brief This type is used to store security key lookup data .*/
  116. typedef uint8_t mac_key_lookup_data_t[MAC_KEY_LOOKUP_DATA_SIZE_LONG];
  117. /**@brief This type is used to store security data lookup data .*/
  118. typedef uint8_t mac_data_lookup_data_t[MAC_DATA_LOOKUP_DATA_SIZE_LONG];
  119. /**@brief This type is used to store security key source address .*/
  120. typedef uint64_t mac_key_source_t;
  121. /**@brief This type represents key LookupDataSize according to Table 94 .*/
  122. typedef enum
  123. {
  124. KEY_LOOKUP_SIZE_FIVE = 0, /**< Size is 5. */
  125. KEY_LOOKUP_SIZE_NINE = 1 /**< Size is 9. */
  126. } mac_key_lookup_size_t;
  127. /**@brief This type represents real size of key LookupData .*/
  128. typedef enum
  129. {
  130. KEY_LOOKUP_SIZE_FIVE_VAL = 5, /**< Size is 5. */
  131. KEY_LOOKUP_SIZE_NINE_VAL = 9 /**< Size is 9. */
  132. } mac_key_lookup_size_val_t;
  133. /**@brief This type represents data LookupDataSize .*/
  134. typedef enum
  135. {
  136. DATA_LOOKUP_SIZE_FOUR_VAL = 4, /**< Size is 4. */
  137. DATA_LOOKUP_SIZE_EIGHT_VAL = 8 /**< Size is 8. */
  138. } mac_data_lookup_size_val_t;
  139. /**@brief Abstract type to work with growing tables such as some of MAC
  140. * security attributes.
  141. */
  142. typedef struct
  143. {
  144. sys_queue_t queue; /**< Service field .*/
  145. uint8_t size; /**< Number of currently allocated
  146. items inside the table .*/
  147. } mac_table_t;
  148. /**@brief Due to processing algorithm this field MUST be the first inside a
  149. * table or list.
  150. */
  151. typedef struct
  152. {
  153. sys_queue_item_t item; /**< Service field .*/
  154. uint8_t idx; /**< Index inside table .*/
  155. } mac_table_item_t;
  156. /**@brief KeyIdLookupDescriptor as described in Table 94 .*/
  157. typedef struct
  158. {
  159. mac_table_item_t table_service; /**< Service field .*/
  160. mac_key_lookup_data_t data; /**< Set of 5 or 9 bytes.
  161. Data used to identify the key .*/
  162. mac_key_lookup_size_t size; /**< A value of LOOKUP_SIZE_FIVE indicates a set
  163. of 5 bytes; a value of LOOKUP_SIZE_NINE
  164. indicates a set of 9 bytes .*/
  165. } mac_key_id_lookup_descr_t;
  166. /**@brief KeyIdLookupLis as described in Table 89 .*/
  167. typedef mac_table_t mac_key_id_lookup_list_t;
  168. /**@brief DeviceDescriptor as described in Table 93 .*/
  169. typedef struct
  170. {
  171. mac_table_item_t table_service; /**< Service field .*/
  172. uint16_t pan_id; /**< The 16-bit PAN identifier of the device in
  173. this DeviceDescriptor .*/
  174. uint16_t short_address; /**< The 16-bit short address of the device in
  175. this DeviceDescriptor. A value of
  176. #MAC_EXTENDED_ADDRESS_ONLY
  177. indicates that this device is using only its
  178. extended address. A value of
  179. #MAC_BROADCAST_SHORT_ADDRESS
  180. indicates that this value is unknown .*/
  181. uint64_t extended_address; /**< The 64-bit IEEE extended address of the
  182. device in this DeviceDescriptor. This
  183. element is also used in unsecuring
  184. operations on incoming frames .*/
  185. uint32_t frame_counter; /**< The incoming frame counter of the device
  186. in this DeviceDescriptor. This value is used
  187. to ensure sequential freshness of frames .*/
  188. bool exempt; /**< Indication of whether the device may
  189. override the minimum security level
  190. settings defined in \a mac_security_level_table_t .*/
  191. } mac_device_descr_t;
  192. /**@brief DeviceTable as described in Table 93 .*/
  193. typedef mac_table_t mac_device_table_t;
  194. /**@brief KeyDeviceDescriptor as described in Table 91 .*/
  195. typedef struct
  196. {
  197. mac_table_item_t table_service; /**< Service field .*/
  198. uint8_t device_handle; /**< Handle to the DeviceDescriptor
  199. corresponding to the device (see
  200. \a mac_device_descr_t).
  201. The value is an index of the device descriptor
  202. instance from device table .*/
  203. uint8_t unique_device : 1; /**< Indication of whether the device indicated
  204. by DeviceDescriptorHandle is uniquely
  205. associated with the KeyDescriptor, i.e., it
  206. is a link key as opposed to a group key .*/
  207. uint8_t blacklisted : 1; /**< Indication of whether the device indicated
  208. by DeviceDescriptorHandle previously
  209. communicated with this key prior to the
  210. exhaustion of the frame counter. If TRUE,
  211. this indicates that the device shall not use
  212. this key further because it exhausted its
  213. use of the frame counter used with this
  214. key .*/
  215. } mac_key_device_descr_t;
  216. /**@brief KeyDeviceList as described in Table 89 .*/
  217. typedef mac_table_t mac_key_device_list_t;
  218. /**@brief KeyUsageDescriptor as described in Table 90 .*/
  219. typedef struct
  220. {
  221. mac_table_item_t table_service; /**< Service field .*/
  222. uint8_t frame_type : 3; /**< See \a mac_frame_type_t .*/
  223. uint8_t cmd_frame_id : 4; /**< See \a mac_command_id_t .*/
  224. } mac_key_usage_descr_t;
  225. /**@brief KeyUsageList as described in Table 89 .*/
  226. typedef mac_table_t mac_key_usage_list_t;
  227. /**@brief KeyDescriptor as described in Table 89 .*/
  228. typedef struct
  229. {
  230. mac_table_item_t table_service; /**< Service field .*/
  231. mac_key_id_lookup_list_t id_lookup_list; /**< A list of KeyIdLookupDescriptor entries
  232. used to identify this KeyDescriptor .*/
  233. mac_key_device_list_t key_device_list; /**< A list of KeyDeviceDescriptor entries
  234. indicating which devices are currently
  235. using this key, including their blacklist
  236. status .*/
  237. mac_key_usage_list_t key_usage_list; /**< A list of KeyUsageDescriptor entries
  238. indicating which frame types this key may
  239. be used with .*/
  240. mac_key_t key; /**< The actual value of the key .*/
  241. } mac_key_descr_t;
  242. /**@brief KeyTable as described in Table 88 .*/
  243. typedef mac_table_t mac_key_table_t;
  244. /**@brief SecurityLevelDescriptor as described in Table 93 .*/
  245. typedef struct
  246. {
  247. mac_table_item_t table_service; /**< Service field. */
  248. uint16_t frame_type : 3; /**< See \a mac_frame_type_t .*/
  249. uint16_t cmd_frame_id : 4; /**< See \a mac_command_id_t .*/
  250. uint16_t security_min : 3; /**< The minimal required/expected security
  251. level for incoming MAC frames with the
  252. indicated frame type and, if present,
  253. command frame type (see
  254. \a mac_security_level_t) .*/
  255. uint16_t override_min : 1; /**< Indication of whether originating devices
  256. for which the Exempt flag is set may
  257. override the minimum security level
  258. indicated by the SecurityMinimum
  259. element. If TRUE, this indicates that for
  260. originating devices with Exempt status,
  261. the incoming security level zero is
  262. acceptable, in addition to the incoming
  263. security levels meeting the minimum
  264. expected security level indicated by the
  265. SecurityMinimum element .*/
  266. } mac_security_level_descr_t;
  267. typedef mac_table_t mac_security_level_table_t;
  268. /** @} */
  269. #endif // MAC_SECURITY_H_INCLUDED