1 /*
2 * Copyright (c) 2016 Intel Corporation.
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6
7 /**
8 * @file
9 * @brief IEEE 802.15.4 MAC frame related functions
10 *
11 * @details This is not to be included by the application.
12 *
13 * @note All references to the standard in this file cite IEEE 802.15.4-2020.
14 *
15 * @note All structs and attributes (e.g. PAN id, ext address and short address)
16 * in this file that directly represent parts of IEEE 802.15.4 frames are in
17 * LITTLE ENDIAN, see section 4, especially section 4.3.
18 */
19
20 #ifndef __IEEE802154_FRAME_H__
21 #define __IEEE802154_FRAME_H__
22
23 #include <zephyr/kernel.h>
24 #include <zephyr/net/ieee802154.h>
25 #include <zephyr/net/net_pkt.h>
26 #include <zephyr/toolchain.h>
27
28 #define IEEE802154_ACK_PKT_LENGTH 3 /* Imm-Ack length, see section 7.3.3 */
29 #define IEEE802154_MIN_LENGTH IEEE802154_ACK_PKT_LENGTH
30
31 #define IEEE802154_FCF_SEQ_LENGTH 3
32 #define IEEE802154_PAN_ID_LENGTH 2
33
34 #define IEEE802154_BEACON_MIN_SIZE 4
35 #define IEEE802154_BEACON_SF_SIZE 2
36 #define IEEE802154_BEACON_GTS_SPEC_SIZE 1
37 #define IEEE802154_BEACON_GTS_IF_MIN_SIZE IEEE802154_BEACON_GTS_SPEC_SIZE
38 #define IEEE802154_BEACON_PAS_SPEC_SIZE 1
39 #define IEEE802154_BEACON_PAS_IF_MIN_SIZE IEEE802154_BEACON_PAS_SPEC_SIZE
40 #define IEEE802154_BEACON_GTS_DIR_SIZE 1
41 #define IEEE802154_BEACON_GTS_SIZE 3
42 #define IEEE802154_BEACON_GTS_RX 1
43 #define IEEE802154_BEACON_GTS_TX 0
44
45 /** see section 7.2.2.2 */
46 enum ieee802154_frame_type {
47 IEEE802154_FRAME_TYPE_BEACON = 0x0,
48 IEEE802154_FRAME_TYPE_DATA = 0x1,
49 IEEE802154_FRAME_TYPE_ACK = 0x2,
50 IEEE802154_FRAME_TYPE_MAC_COMMAND = 0x3,
51 IEEE802154_FRAME_TYPE_RESERVED = 0x4,
52 IEEE802154_FRAME_TYPE_MULTIPURPOSE = 0x5,
53 IEEE802154_FRAME_TYPE_FRAK = 0x6,
54 IEEE802154_FRAME_TYPE_EXTENDED = 0x7,
55 };
56
57 /** see section 7.2.2.9, table 7-3 */
58 enum ieee802154_addressing_mode {
59 IEEE802154_ADDR_MODE_NONE = 0x0,
60 IEEE802154_ADDR_MODE_RESERVED = 0x1,
61 IEEE802154_ADDR_MODE_SHORT = 0x2,
62 IEEE802154_ADDR_MODE_EXTENDED = 0x3,
63 };
64
65 /** see section 7.2.2.10 */
66 enum ieee802154_version {
67 IEEE802154_VERSION_802154_2003 = 0x0,
68 IEEE802154_VERSION_802154_2006 = 0x1,
69 IEEE802154_VERSION_802154 = 0x2,
70 IEEE802154_VERSION_RESERVED = 0x3,
71 };
72
73 /** Frame Control Field, see section 7.2.2 */
74 struct ieee802154_fcf_seq {
75 struct {
76 #ifdef CONFIG_LITTLE_ENDIAN
77 uint16_t frame_type : 3;
78 uint16_t security_enabled : 1;
79 uint16_t frame_pending : 1;
80 uint16_t ar : 1;
81 uint16_t pan_id_comp : 1;
82 uint16_t reserved : 1;
83 uint16_t seq_num_suppr : 1;
84 uint16_t ie_list : 1;
85 uint16_t dst_addr_mode : 2;
86 uint16_t frame_version : 2;
87 uint16_t src_addr_mode : 2;
88 #else
89 uint16_t reserved : 1;
90 uint16_t pan_id_comp : 1;
91 uint16_t ar : 1;
92 uint16_t frame_pending : 1;
93 uint16_t security_enabled : 1;
94 uint16_t frame_type : 3;
95 uint16_t src_addr_mode : 2;
96 uint16_t frame_version : 2;
97 uint16_t dst_addr_mode : 2;
98 uint16_t ie_list : 1;
99 uint16_t seq_num_suppr : 1;
100 #endif
101 } fc __packed;
102
103 uint8_t sequence;
104 } __packed;
105
106 struct ieee802154_address {
107 union {
108 uint16_t short_addr;
109 uint8_t ext_addr[0];
110 };
111 } __packed;
112
113 struct ieee802154_address_field_comp {
114 struct ieee802154_address addr;
115 } __packed;
116
117 struct ieee802154_address_field_plain {
118 uint16_t pan_id;
119 struct ieee802154_address addr;
120 } __packed;
121
122 struct ieee802154_address_field {
123 union {
124 struct ieee802154_address_field_plain plain;
125 struct ieee802154_address_field_comp comp;
126 };
127 } __packed;
128
129 /** see section 9.4.2.2, table 9-6 */
130 enum ieee802154_security_level {
131 IEEE802154_SECURITY_LEVEL_NONE = 0x0,
132 IEEE802154_SECURITY_LEVEL_MIC_32 = 0x1,
133 IEEE802154_SECURITY_LEVEL_MIC_64 = 0x2,
134 IEEE802154_SECURITY_LEVEL_MIC_128 = 0x3,
135 IEEE802154_SECURITY_LEVEL_RESERVED = 0x4,
136 IEEE802154_SECURITY_LEVEL_ENC_MIC_32 = 0x5,
137 IEEE802154_SECURITY_LEVEL_ENC_MIC_64 = 0x6,
138 IEEE802154_SECURITY_LEVEL_ENC_MIC_128 = 0x7,
139 };
140
141 /** Levels above this level will be encrypted. */
142 #define IEEE802154_SECURITY_LEVEL_ENC IEEE802154_SECURITY_LEVEL_RESERVED
143
144 /** This will match above *_MIC_<32/64/128> */
145 #define IEEE802154_AUTH_TAG_LENGTH_32 4
146 #define IEEE802154_AUTH_TAG_LENGTH_64 8
147 #define IEEE802154_AUTH_TAG_LENGTH_128 16
148
149 /** see section 9.4.2.3, table 9-7 */
150 enum ieee802154_key_id_mode {
151 IEEE802154_KEY_ID_MODE_IMPLICIT = 0x0,
152 IEEE802154_KEY_ID_MODE_INDEX = 0x1,
153 IEEE802154_KEY_ID_MODE_SRC_4_INDEX = 0x2,
154 IEEE802154_KEY_ID_MODE_SRC_8_INDEX = 0x3,
155 };
156
157 #define IEEE802154_KEY_ID_FIELD_INDEX_LENGTH 1
158 #define IEEE802154_KEY_ID_FIELD_SRC_4_INDEX_LENGTH 5
159 #define IEEE802154_KEY_ID_FIELD_SRC_8_INDEX_LENGTH 9
160
161 #define IEEE802154_KEY_MAX_LEN 16
162
163 /** see section 9.4.2 */
164 struct ieee802154_security_control_field {
165 #ifdef CONFIG_LITTLE_ENDIAN
166 uint8_t security_level : 3;
167 uint8_t key_id_mode : 2;
168 uint8_t reserved : 3;
169 #else
170 uint8_t reserved : 3;
171 uint8_t key_id_mode : 2;
172 uint8_t security_level : 3;
173 #endif
174 } __packed;
175
176 #define IEEE802154_SECURITY_CF_LENGTH 1
177
178 /**
179 * @brief see section 9.4.4
180 *
181 * @note Currently only mode 0 is supported, so this structure holds no info,
182 * yet.
183 */
184 struct ieee802154_key_identifier_field {
185 union {
186 struct {
187 uint8_t key_index;
188 } mode_1;
189
190 struct {
191 uint8_t key_src[4];
192 uint8_t key_index;
193 } mode_2;
194
195 struct {
196 uint8_t key_src[8];
197 uint8_t key_index;
198 } mode_3;
199 };
200 } __packed;
201
202 /** Auxiliary Security Header, see section 9.4 */
203 struct ieee802154_aux_security_hdr {
204 struct ieee802154_security_control_field control;
205 uint32_t frame_counter;
206 struct ieee802154_key_identifier_field kif;
207 } __packed;
208
209 #define IEEE802154_SECURITY_FRAME_COUNTER_LENGTH 4
210
211 /** MAC header and footer, see section 7.2.1 */
212 struct ieee802154_mhr {
213 struct ieee802154_fcf_seq *fs;
214 struct ieee802154_address_field *dst_addr;
215 struct ieee802154_address_field *src_addr;
216 #ifdef CONFIG_NET_L2_IEEE802154_SECURITY
217 struct ieee802154_aux_security_hdr *aux_sec;
218 #endif
219 };
220
221 /** see section 7.3.1.5, figure 7-10 */
222 struct ieee802154_gts_dir {
223 #ifdef CONFIG_LITTLE_ENDIAN
224 uint8_t mask : 7;
225 uint8_t reserved : 1;
226 #else
227 uint8_t reserved : 1;
228 uint8_t mask : 7;
229 #endif
230 } __packed;
231
232 /** see section 7.3.1.5, figure 7-11 */
233 struct ieee802154_gts {
234 uint16_t short_address;
235 #ifdef CONFIG_LITTLE_ENDIAN
236 uint8_t starting_slot : 4;
237 uint8_t length : 4;
238 #else
239 uint8_t length : 4;
240 uint8_t starting_slot : 4;
241 #endif
242 } __packed;
243
244 /** see section 7.3.1.5, figure 7-9 */
245 struct ieee802154_gts_spec {
246 #ifdef CONFIG_LITTLE_ENDIAN
247 /* Descriptor Count */
248 uint8_t desc_count : 3;
249 uint8_t reserved : 4;
250 /* GTS Permit */
251 uint8_t permit : 1;
252 #else
253 /* GTS Permit */
254 uint8_t permit : 1;
255 uint8_t reserved : 4;
256 /* Descriptor Count */
257 uint8_t desc_count : 3;
258 #endif
259 } __packed;
260
261 /** see section 7.3.1.6, figure 7-13 */
262 struct ieee802154_pas_spec {
263 #ifdef CONFIG_LITTLE_ENDIAN
264 /* Number of Short Addresses Pending */
265 uint8_t nb_sap : 3;
266 uint8_t reserved_1 : 1;
267 /* Number of Extended Addresses Pending */
268 uint8_t nb_eap : 3;
269 uint8_t reserved_2 : 1;
270 #else
271 uint8_t reserved_1 : 1;
272 /* Number of Extended Addresses Pending */
273 uint8_t nb_eap : 3;
274 uint8_t reserved_2 : 1;
275 /* Number of Short Addresses Pending */
276 uint8_t nb_sap : 3;
277 #endif
278 } __packed;
279
280 /** see section 7.3.1.4, figure 7-7 */
281 struct ieee802154_beacon_sf {
282 #ifdef CONFIG_LITTLE_ENDIAN
283 /* Beacon Order*/
284 uint16_t bc_order : 4;
285 /* Superframe Order*/
286 uint16_t sf_order : 4;
287 /* Final CAP Slot */
288 uint16_t cap_slot : 4;
289 /* Battery Life Extension */
290 uint16_t ble : 1;
291 uint16_t reserved : 1;
292 /* PAN Coordinator */
293 uint16_t coordinator : 1;
294 /* Association Permit */
295 uint16_t association : 1;
296 #else
297 /* Superframe Order*/
298 uint16_t sf_order : 4;
299 /* Beacon Order*/
300 uint16_t bc_order : 4;
301 /* Association Permit */
302 uint16_t association : 1;
303 /* PAN Coordinator */
304 uint16_t coordinator : 1;
305 uint16_t reserved : 1;
306 /* Battery Life Extension */
307 uint16_t ble : 1;
308 /* Final CAP Slot */
309 uint16_t cap_slot : 4;
310 #endif
311 } __packed;
312
313 /** see section 7.3.1.1, figure 7-5 */
314 struct ieee802154_beacon {
315 struct ieee802154_beacon_sf sf;
316
317 /* GTS Fields - Spec is always there */
318 struct ieee802154_gts_spec gts;
319 } __packed;
320
321 /** See section 7.5.2 */
322 struct ieee802154_cmd_assoc_req {
323 struct {
324 #ifdef CONFIG_LITTLE_ENDIAN
325 uint8_t reserved_1 : 1;
326 uint8_t dev_type : 1;
327 uint8_t power_src : 1;
328 uint8_t rx_on : 1;
329 uint8_t association_type : 1;
330 uint8_t reserved_2 : 1;
331 uint8_t sec_capability : 1;
332 uint8_t alloc_addr : 1;
333 #else
334 uint8_t alloc_addr : 1;
335 uint8_t sec_capability : 1;
336 uint8_t reserved_2 : 1;
337 uint8_t association_type : 1;
338 uint8_t rx_on : 1;
339 uint8_t power_src : 1;
340 uint8_t dev_type : 1;
341 uint8_t reserved_1 : 1;
342 #endif
343 } ci;
344 } __packed;
345
346 #define IEEE802154_CMD_ASSOC_REQ_LENGTH 1
347
348 /** see section 7.5.3 */
349 enum ieee802154_association_status_field {
350 IEEE802154_ASF_SUCCESSFUL = 0x00,
351 IEEE802154_ASF_PAN_AT_CAPACITY = 0x01,
352 IEEE802154_ASF_PAN_ACCESS_DENIED = 0x02,
353 IEEE802154_ASF_RESERVED = 0x03,
354 IEEE802154_ASF_RESERVED_PRIMITIVES = 0x80,
355 };
356
357 struct ieee802154_cmd_assoc_res {
358 uint16_t short_addr;
359 uint8_t status;
360 } __packed;
361
362 #define IEEE802154_CMD_ASSOC_RES_LENGTH 3
363
364 /** see section 7.5.4 */
365 enum ieee802154_disassociation_reason_field {
366 IEEE802154_DRF_RESERVED_1 = 0x00,
367 IEEE802154_DRF_COORDINATOR_WISH = 0x01,
368 IEEE802154_DRF_DEVICE_WISH = 0x02,
369 IEEE802154_DRF_RESERVED_2 = 0x03,
370 IEEE802154_DRF_RESERVED_PRIMITIVES = 0x80,
371 };
372
373 struct ieee802154_cmd_disassoc_note {
374 uint8_t reason;
375 } __packed;
376
377 #define IEEE802154_CMD_DISASSOC_NOTE_LENGTH 1
378
379 /** Coordinator realignment, see section 7.5.10 */
380 struct ieee802154_cmd_coord_realign {
381 uint16_t pan_id;
382 uint16_t coordinator_short_addr;
383 uint8_t channel;
384 uint16_t short_addr;
385 uint8_t channel_page; /* optional */
386 } __packed;
387
388 #define IEEE802154_CMD_COORD_REALIGN_LENGTH 3
389
390 /** GTS request, see section 7.5.11 */
391 struct ieee802154_gts_request {
392 struct {
393 #ifdef CONFIG_LITTLE_ENDIAN
394 uint8_t length : 4;
395 uint8_t direction : 1;
396 uint8_t type : 1;
397 uint8_t reserved : 2;
398 #else
399 uint8_t reserved : 2;
400 uint8_t type : 1;
401 uint8_t direction : 1;
402 uint8_t length : 4;
403 #endif
404 } gts;
405 } __packed;
406
407 #define IEEE802154_GTS_REQUEST_LENGTH 1
408
409 /** Command Frame Identifiers (CFI), see section 7.5.1 */
410 enum ieee802154_cfi {
411 IEEE802154_CFI_UNKNOWN = 0x00,
412 IEEE802154_CFI_ASSOCIATION_REQUEST = 0x01,
413 IEEE802154_CFI_ASSOCIATION_RESPONSE = 0x02,
414 IEEE802154_CFI_DISASSOCIATION_NOTIFICATION = 0x03,
415 IEEE802154_CFI_DATA_REQUEST = 0x04,
416 IEEE802154_CFI_PAN_ID_CONFLICT_NOTIFICATION = 0x05,
417 IEEE802154_CFI_ORPHAN_NOTIFICATION = 0x06,
418 IEEE802154_CFI_BEACON_REQUEST = 0x07,
419 IEEE802154_CFI_COORDINATOR_REALIGNEMENT = 0x08,
420 IEEE802154_CFI_GTS_REQUEST = 0x09,
421 IEEE802154_CFI_RESERVED = 0x0a,
422 };
423
424 struct ieee802154_command {
425 uint8_t cfi;
426 union {
427 struct ieee802154_cmd_assoc_req assoc_req;
428 struct ieee802154_cmd_assoc_res assoc_res;
429 struct ieee802154_cmd_disassoc_note disassoc_note;
430 struct ieee802154_cmd_coord_realign coord_realign;
431 struct ieee802154_gts_request gts_request;
432 /* Data request, PAN ID conflict, orphan notification
433 * or beacon request just provide the CFI.
434 */
435 };
436 } __packed;
437
438 #define IEEE802154_CMD_CFI_LENGTH 1
439
440 /** Frame */
441 struct ieee802154_mpdu {
442 struct ieee802154_mhr mhr;
443 union {
444 void *payload;
445 struct ieee802154_beacon *beacon;
446 struct ieee802154_command *command;
447 };
448 uint16_t payload_length;
449 };
450
451 /** Frame build parameters */
452 struct ieee802154_frame_params {
453 struct {
454 union {
455 uint8_t ext_addr[IEEE802154_EXT_ADDR_LENGTH]; /* in big endian */
456 uint16_t short_addr; /* in CPU byte order */
457 };
458
459 uint16_t len;
460 uint16_t pan_id; /* in CPU byte order */
461 } dst;
462
463 uint16_t short_addr; /* in CPU byte order */
464 uint16_t pan_id; /* in CPU byte order */
465 } __packed;
466
467 #ifdef CONFIG_NET_L2_IEEE802154_SECURITY
468 struct ieee802154_aux_security_hdr *
469 ieee802154_validate_aux_security_hdr(uint8_t *buf, uint8_t **p_buf, uint8_t *length);
470 #endif
471
472 struct ieee802154_fcf_seq *ieee802154_validate_fc_seq(uint8_t *buf, uint8_t **p_buf,
473 uint8_t *length);
474
475 /**
476 * @brief Calculate the beacon header length.
477 *
478 * @details Returns the length of the MAC payload without the beacon payload,
479 * see section 7.3.1.1, figure 7-5.
480 *
481 * @param buf pointer to the MAC payload
482 * @param length buffer length
483 *
484 * @retval -EINVAL The header is invalid.
485 * @return the length of the beacon header
486 */
487 int ieee802514_beacon_header_length(uint8_t *buf, uint8_t length);
488
489 bool ieee802154_validate_frame(uint8_t *buf, uint8_t length, struct ieee802154_mpdu *mpdu);
490
491 void ieee802154_compute_header_and_authtag_len(struct net_if *iface, struct net_linkaddr *dst,
492 struct net_linkaddr *src, uint8_t *ll_hdr_len,
493 uint8_t *authtag_len);
494
495 bool ieee802154_create_data_frame(struct ieee802154_context *ctx, struct net_linkaddr *dst,
496 struct net_linkaddr *src, struct net_buf *buf,
497 uint8_t ll_hdr_len);
498
499 struct net_pkt *ieee802154_create_mac_cmd_frame(struct net_if *iface, enum ieee802154_cfi type,
500 struct ieee802154_frame_params *params);
501
502 void ieee802154_mac_cmd_finalize(struct net_pkt *pkt, enum ieee802154_cfi type);
503
ieee802154_get_mac_command(struct net_pkt * pkt)504 static inline struct ieee802154_command *ieee802154_get_mac_command(struct net_pkt *pkt)
505 {
506 return (struct ieee802154_command *)(pkt->frags->data + pkt->frags->len);
507 }
508
509 bool ieee802154_create_ack_frame(struct net_if *iface, struct net_pkt *pkt, uint8_t seq);
510
511 #ifdef CONFIG_NET_L2_IEEE802154_SECURITY
512 bool ieee802154_decipher_data_frame(struct net_if *iface, struct net_pkt *pkt,
513 struct ieee802154_mpdu *mpdu);
514 #else
515 #define ieee802154_decipher_data_frame(...) true
516 #endif /* CONFIG_NET_L2_IEEE802154_SECURITY */
517
518 #endif /* __IEEE802154_FRAME_H__ */
519
