Contiki-NG
tsch-security.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2014, SICS Swedish ICT.
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  * 1. Redistributions of source code must retain the above copyright
9  * notice, this list of conditions and the following disclaimer.
10  * 2. Redistributions in binary form must reproduce the above copyright
11  * notice, this list of conditions and the following disclaimer in the
12  * documentation and/or other materials provided with the distribution.
13  * 3. Neither the name of the Institute nor the names of its contributors
14  * may be used to endorse or promote products derived from this software
15  * without specific prior written permission.
16  *
17  * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
18  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20  * ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
21  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
23  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
24  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
25  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
26  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27  * SUCH DAMAGE.
28  *
29  * This file is part of the Contiki operating system.
30  *
31  */
32 
33 /**
34  * \addtogroup tsch
35  * @{
36  * \file
37  * TSCH security
38 */
39 
40 #ifndef __TSCH_SECURITY_H__
41 #define __TSCH_SECURITY_H__
42 
43 /********** Includes **********/
44 
45 #include "contiki.h"
48 #include "net/mac/llsec802154.h"
49 
50 /********** Configurarion *********/
51 
52 /* To enable TSCH security:
53 * - set LLSEC802154_CONF_ENABLED
54 * - set LLSEC802154_CONF_USES_EXPLICIT_KEYS
55 * */
56 
57 /* K1, defined in 6TiSCH minimal, is well-known (offers no security) and used for EBs only */
58 #ifdef TSCH_SECURITY_CONF_K1
59 #define TSCH_SECURITY_K1 TSCH_SECURITY_CONF_K1
60 #else /* TSCH_SECURITY_CONF_K1 */
61 #define TSCH_SECURITY_K1 { 0x36, 0x54, 0x69, 0x53, 0x43, 0x48, 0x20, 0x6D, 0x69, 0x6E, 0x69, 0x6D, 0x61, 0x6C, 0x31, 0x35 }
62 #endif /* TSCH_SECURITY_CONF_K1 */
63 
64 /* K2, defined in 6TiSCH minimal, is used for all but EB traffic */
65 #ifdef TSCH_SECURITY_CONF_K2
66 #define TSCH_SECURITY_K2 TSCH_SECURITY_CONF_K2
67 #else /* TSCH_SECURITY_CONF_K2 */
68 #define TSCH_SECURITY_K2 { 0xde, 0xad, 0xbe, 0xef, 0xfa, 0xce, 0xca, 0xfe, 0xde, 0xad, 0xbe, 0xef, 0xfa, 0xce, 0xca, 0xfe }
69 #endif /* TSCH_SECURITY_CONF_K2 */
70 
71 /* Key used for EBs */
72 #ifdef TSCH_SECURITY_CONF_KEY_INDEX_EB
73 #define TSCH_SECURITY_KEY_INDEX_EB TSCH_SECURITY_CONF_KEY_INDEX_EB
74 #else
75 #define TSCH_SECURITY_KEY_INDEX_EB 1 /* Use K1 as per 6TiSCH minimal */
76 #endif
77 
78 /* Security level for EBs */
79 #ifdef TSCH_SECURITY_CONF_SEC_LEVEL_EB
80 #define TSCH_SECURITY_KEY_SEC_LEVEL_EB TSCH_SECURITY_CONF_SEC_LEVEL_EB
81 #else
82 #define TSCH_SECURITY_KEY_SEC_LEVEL_EB 1 /* MIC-32, as per 6TiSCH minimal */
83 #endif
84 
85 /* Key used for ACK */
86 #ifdef TSCH_SECURITY_CONF_KEY_INDEX_ACK
87 #define TSCH_SECURITY_KEY_INDEX_ACK TSCH_SECURITY_CONF_KEY_INDEX_ACK
88 #else
89 #define TSCH_SECURITY_KEY_INDEX_ACK 2 /* Use K2 as per 6TiSCH minimal */
90 #endif
91 
92 /* Security level for ACKs */
93 #ifdef TSCH_SECURITY_CONF_SEC_LEVEL_ACK
94 #define TSCH_SECURITY_KEY_SEC_LEVEL_ACK TSCH_SECURITY_CONF_SEC_LEVEL_ACK
95 #else
96 #define TSCH_SECURITY_KEY_SEC_LEVEL_ACK 5 /* Encryption + MIC-32, as per 6TiSCH minimal */
97 #endif
98 
99 /* Key used for Other (Data, Cmd) */
100 #ifdef TSCH_SECURITY_CONF_KEY_INDEX_OTHER
101 #define TSCH_SECURITY_KEY_INDEX_OTHER TSCH_SECURITY_CONF_KEY_INDEX_OTHER
102 #else
103 #define TSCH_SECURITY_KEY_INDEX_OTHER 2 /* Use K2 as per 6TiSCH minimal */
104 #endif
105 
106 /* Security level for Other (Data, Cmd) */
107 #ifdef TSCH_SECURITY_CONF_SEC_LEVEL_OTHER
108 #define TSCH_SECURITY_KEY_SEC_LEVEL_OTHER TSCH_SECURITY_CONF_SEC_LEVEL_OTHER
109 #else
110 #define TSCH_SECURITY_KEY_SEC_LEVEL_OTHER 5 /* Encryption + MIC-32, as per 6TiSCH minimal */
111 #endif
112 
113 /********** Data types *********/
114 
115 /* AES-128 key */
116 typedef uint8_t aes_key[16];
117 
118 /********** Functions *********/
119 /**
120  * \brief Return MIC length
121  * \return The length of MIC (>= 0)
122  */
123 unsigned int tsch_security_mic_len(const frame802154_t *frame);
124 
125 /**
126  * \brief Protect a frame with encryption and/or MIC
127  * \return The length of a generated MIC (>= 0)
128  */
129 unsigned int tsch_security_secure_frame(uint8_t *hdr, uint8_t *outbuf,
130  int hdrlen, int datalen,
131  struct tsch_asn_t *asn);
132 
133 /**
134  * \brief Parse and check a frame protected with encryption and/or MIC
135  * \retval 0 On error or security check failure (insecure frame)
136  * \retval 1 On success or no need for security check (good frame)
137  */
138 unsigned int tsch_security_parse_frame(const uint8_t *hdr, int hdrlen,
139  int datalen, const frame802154_t *frame,
140  const linkaddr_t *sender,
141  struct tsch_asn_t *asn);
142 
143 /**
144  * \brief Set packetbuf (or eackbuf) attributes depending on a given frame type
145  * \param frame_type The frame type (FRAME802154_BEACONFRAME etc.)
146  */
147 void tsch_security_set_packetbuf_attr(uint8_t frame_type);
148 
149 #endif /* __TSCH_SECURITY_H__ */
150 /** @} */
IEEE 802.15.4e Information Element (IE) creation and parsing.
unsigned int tsch_security_parse_frame(const uint8_t *hdr, int hdrlen, int datalen, const frame802154_t *frame, const linkaddr_t *sender, struct tsch_asn_t *asn)
Parse and check a frame protected with encryption and/or MIC.
Common functionality of 802.15.4-compliant llsec_drivers.
unsigned int tsch_security_mic_len(const frame802154_t *frame)
Return MIC length.
802.15.4 frame creation and parsing functions
void tsch_security_set_packetbuf_attr(uint8_t frame_type)
Set packetbuf (or eackbuf) attributes depending on a given frame type.
Parameters used by the frame802154_create() function.
Definition: frame802154.h:198
unsigned int tsch_security_secure_frame(uint8_t *hdr, uint8_t *outbuf, int hdrlen, int datalen, struct tsch_asn_t *asn)
Protect a frame with encryption and/or MIC.
The ASN is an absolute slot number over 5 bytes.
Definition: tsch-asn.h:48