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 #if LLSEC802154_ENABLED && !LLSEC802154_USES_EXPLICIT_KEYS
58 #error LLSEC802154_ENABLED set but LLSEC802154_USES_EXPLICIT_KEYS unset
59 #endif /* LLSEC802154_ENABLED */
60 
61 /* K1, defined in 6TiSCH minimal, is well-known (offers no security) and used for EBs only */
62 #ifdef TSCH_SECURITY_CONF_K1
63 #define TSCH_SECURITY_K1 TSCH_SECURITY_CONF_K1
64 #else /* TSCH_SECURITY_CONF_K1 */
65 #define TSCH_SECURITY_K1 { 0x36, 0x54, 0x69, 0x53, 0x43, 0x48, 0x20, 0x6D, 0x69, 0x6E, 0x69, 0x6D, 0x61, 0x6C, 0x31, 0x35 }
66 #endif /* TSCH_SECURITY_CONF_K1 */
67 
68 /* K2, defined in 6TiSCH minimal, is used for all but EB traffic */
69 #ifdef TSCH_SECURITY_CONF_K2
70 #define TSCH_SECURITY_K2 TSCH_SECURITY_CONF_K2
71 #else /* TSCH_SECURITY_CONF_K2 */
72 #define TSCH_SECURITY_K2 { 0xde, 0xad, 0xbe, 0xef, 0xfa, 0xce, 0xca, 0xfe, 0xde, 0xad, 0xbe, 0xef, 0xfa, 0xce, 0xca, 0xfe }
73 #endif /* TSCH_SECURITY_CONF_K2 */
74 
75 /* Key used for EBs */
76 #ifdef TSCH_SECURITY_CONF_KEY_INDEX_EB
77 #define TSCH_SECURITY_KEY_INDEX_EB TSCH_SECURITY_CONF_KEY_INDEX_EB
78 #else
79 #define TSCH_SECURITY_KEY_INDEX_EB 1 /* Use K1 as per 6TiSCH minimal */
80 #endif
81 
82 /* Security level for EBs */
83 #ifdef TSCH_SECURITY_CONF_SEC_LEVEL_EB
84 #define TSCH_SECURITY_KEY_SEC_LEVEL_EB TSCH_SECURITY_CONF_SEC_LEVEL_EB
85 #else
86 #define TSCH_SECURITY_KEY_SEC_LEVEL_EB 1 /* MIC-32, as per 6TiSCH minimal */
87 #endif
88 
89 /* Key used for ACK */
90 #ifdef TSCH_SECURITY_CONF_KEY_INDEX_ACK
91 #define TSCH_SECURITY_KEY_INDEX_ACK TSCH_SECURITY_CONF_KEY_INDEX_ACK
92 #else
93 #define TSCH_SECURITY_KEY_INDEX_ACK 2 /* Use K2 as per 6TiSCH minimal */
94 #endif
95 
96 /* Security level for ACKs */
97 #ifdef TSCH_SECURITY_CONF_SEC_LEVEL_ACK
98 #define TSCH_SECURITY_KEY_SEC_LEVEL_ACK TSCH_SECURITY_CONF_SEC_LEVEL_ACK
99 #else
100 #define TSCH_SECURITY_KEY_SEC_LEVEL_ACK 5 /* Encryption + MIC-32, as per 6TiSCH minimal */
101 #endif
102 
103 /* Key used for Other (Data, Cmd) */
104 #ifdef TSCH_SECURITY_CONF_KEY_INDEX_OTHER
105 #define TSCH_SECURITY_KEY_INDEX_OTHER TSCH_SECURITY_CONF_KEY_INDEX_OTHER
106 #else
107 #define TSCH_SECURITY_KEY_INDEX_OTHER 2 /* Use K2 as per 6TiSCH minimal */
108 #endif
109 
110 /* Security level for Other (Data, Cmd) */
111 #ifdef TSCH_SECURITY_CONF_SEC_LEVEL_OTHER
112 #define TSCH_SECURITY_KEY_SEC_LEVEL_OTHER TSCH_SECURITY_CONF_SEC_LEVEL_OTHER
113 #else
114 #define TSCH_SECURITY_KEY_SEC_LEVEL_OTHER 5 /* Encryption + MIC-32, as per 6TiSCH minimal */
115 #endif
116 
117 /********** Data types *********/
118 
119 /* AES-128 key */
120 typedef uint8_t aes_key[16];
121 
122 /********** Functions *********/
123 /**
124  * \brief Return MIC length
125  * \return The length of MIC (>= 0)
126  */
127 unsigned int tsch_security_mic_len(const frame802154_t *frame);
128 
129 /**
130  * \brief Protect a frame with encryption and/or MIC
131  * \return The length of a generated MIC (>= 0)
132  */
133 unsigned int tsch_security_secure_frame(uint8_t *hdr, uint8_t *outbuf,
134  int hdrlen, int datalen,
135  struct tsch_asn_t *asn);
136 
137 /**
138  * \brief Parse and check a frame protected with encryption and/or MIC
139  * \retval 0 On error or security check failure (insecure frame)
140  * \retval 1 On success or no need for security check (good frame)
141  */
142 unsigned int tsch_security_parse_frame(const uint8_t *hdr, int hdrlen,
143  int datalen, const frame802154_t *frame,
144  const linkaddr_t *sender,
145  struct tsch_asn_t *asn);
146 
147 #endif /* __TSCH_SECURITY_H__ */
148 /** @} */
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
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