dtls_misc.h
Go to the documentation of this file.
1 /**
2  * @file dtls_misc.h
3  * @brief DTLS (Datagram Transport Layer Security)
4  *
5  * @section License
6  *
7  * Copyright (C) 2010-2018 Oryx Embedded SARL. All rights reserved.
8  *
9  * This file is part of CycloneSSL Open.
10  *
11  * This program is free software; you can redistribute it and/or
12  * modify it under the terms of the GNU General Public License
13  * as published by the Free Software Foundation; either version 2
14  * of the License, or (at your option) any later version.
15  *
16  * This program is distributed in the hope that it will be useful,
17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19  * GNU General Public License for more details.
20  *
21  * You should have received a copy of the GNU General Public License
22  * along with this program; if not, write to the Free Software Foundation,
23  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
24  *
25  * @author Oryx Embedded SARL (www.oryx-embedded.com)
26  * @version 1.9.0
27  **/
28 
29 #ifndef _DTLS_MISC_H
30 #define _DTLS_MISC_H
31 
32 //DTLS version numbers
33 #define DTLS_VERSION_1_0 0xFEFF
34 #define DTLS_VERSION_1_2 0xFEFD
35 
36 //DTLS support
37 #ifndef DTLS_SUPPORT
38  #define DTLS_SUPPORT DISABLED
39 #elif (DTLS_SUPPORT != ENABLED && DTLS_SUPPORT != DISABLED)
40  #error DTLS_SUPPORT parameter is not valid
41 #endif
42 
43 //Default PMTU value
44 #ifndef DTLS_DEFAULT_PMTU
45  #define DTLS_DEFAULT_PMTU 1452
46 #elif (DTLS_DEFAULT_PMTU < 64)
47  #error DTLS_DEFAULT_PMTU parameter is not valid
48 #endif
49 
50 //Minimum PMTU value
51 #ifndef DTLS_MIN_PMTU
52  #define DTLS_MIN_PMTU 528
53 #elif (DTLS_MIN_PMTU < 64)
54  #error DTLS_MIN_PMTU parameter is not valid
55 #endif
56 
57 //Replay protection
58 #ifndef DTLS_REPLAY_DETECTION_SUPPORT
59  #define DTLS_REPLAY_DETECTION_SUPPORT ENABLED
60 #elif (DTLS_REPLAY_DETECTION_SUPPORT != ENABLED && DTLS_REPLAY_DETECTION_SUPPORT != DISABLED)
61  #error DTLS_REPLAY_DETECTION_SUPPORT parameter is not valid
62 #endif
63 
64 //Size of the sliding window for replay protection
65 #ifndef DTLS_REPLAY_WINDOW_SIZE
66  #define DTLS_REPLAY_WINDOW_SIZE 64
67 #elif (DTLS_REPLAY_WINDOW_SIZE < 1)
68  #error DTLS_REPLAY_WINDOW_SIZE parameter is not valid
69 #endif
70 
71 //Maximum size for cookies
72 #ifndef DTLS_MAX_COOKIE_SIZE
73  #define DTLS_MAX_COOKIE_SIZE 32
74 #elif (DTLS_MAX_COOKIE_SIZE < 32)
75  #error DTLS_MAX_COOKIE_SIZE parameter is not valid
76 #endif
77 
78 //Maximum number of retransmissions
79 #ifndef DTLS_MAX_RETRIES
80  #define DTLS_MAX_RETRIES 5
81 #elif (DTLS_MAX_RETRIES < 1)
82  #error DTLS_MAX_RETRIES parameter is not valid
83 #endif
84 
85 //Initial retransmission timeout
86 #ifndef DTLS_INIT_TIMEOUT
87  #define DTLS_INIT_TIMEOUT 1000
88 #elif (DTLS_INIT_TIMEOUT < 100)
89  #error DTLS_INIT_TIMEOUT parameter is not valid
90 #endif
91 
92 //Maximum retransmission timeout
93 #ifndef DTLS_MAX_TIMEOUT
94  #define DTLS_MAX_TIMEOUT 60000
95 #elif (DTLS_MAX_TIMEOUT < 1000)
96  #error DTLS_MAX_TIMEOUT parameter is not valid
97 #endif
98 
99 //C++ guard
100 #ifdef __cplusplus
101  extern "C" {
102 #endif
103 
104 
105 /**
106  * @brief DTLS retransmission states
107  **/
108 
109 typedef enum
110 {
116 
117 
118 //CodeWarrior or Win32 compiler?
119 #if defined(__CWCC__) || defined(_WIN32)
120  #pragma pack(push, 1)
121 #endif
122 
123 
124 /**
125  * @brief Sequence number
126  **/
127 
128 typedef __start_packed struct
129 {
130  uint8_t b[6];
132 
133 
134 /**
135  * @brief Cookie
136  **/
137 
138 typedef __start_packed struct
139 {
140  uint8_t length; //0
141  uint8_t value[]; //1
143 
144 
145 /**
146  * @brief List of supported versions
147  **/
148 
149 typedef __start_packed struct
150 {
151  uint8_t length; //0
152  uint16_t value[]; //1
154 
155 
156 /**
157  * @brief DTLS record
158  **/
159 
160 typedef __start_packed struct
161 {
162  uint8_t type; //0
163  uint16_t version; //1-2
164  uint16_t epoch; //3-4
166  uint16_t length; //11-12
167  uint8_t data[]; //13
169 
170 
171 /**
172  * @brief DTLS handshake message
173  **/
174 
175 typedef __start_packed struct
176 {
177  uint8_t msgType; //0
178  uint8_t length[3]; //1-3
179  uint16_t msgSeq; //4-5
180  uint8_t fragOffset[3]; //6-8
181  uint8_t fragLength[3]; //9-11
182  uint8_t data[]; //12
184 
185 
186 /**
187  * @brief HelloVerifyRequest message
188  **/
189 
190 typedef __start_packed struct
191 {
192  uint16_t serverVersion; //0-1
193  uint8_t cookieLength; //2
194  uint8_t cookie[]; //3
196 
197 
198 //CodeWarrior or Win32 compiler?
199 #if defined(__CWCC__) || defined(_WIN32)
200  #pragma pack(pop)
201 #endif
202 
203 
204 /**
205  * @brief Client parameters
206  **/
207 
208 typedef struct
209 {
210  uint16_t version;
211  const uint8_t *random;
212  size_t randomLen;
213  const uint8_t *sessionId;
214  size_t sessionIdLen;
215  const uint8_t *cipherSuites;
217  const uint8_t *compressMethods;
220 
221 
222 /**
223  * @brief DTLS cookie generation callback function
224  **/
225 
227  const DtlsClientParameters *clientParams, uint8_t *cookie,
228  size_t *length, void *param);
229 
230 
231 /**
232  * @brief DTLS cookie verification callback function
233  **/
234 
236  const DtlsClientParameters *clientParams, const uint8_t *cookie,
237  size_t length, void *param);
238 
239 
240 //DTLS specific functions
241 error_t dtlsSelectVersion(TlsContext *context, uint16_t version);
242 uint16_t dtlsTranslateVersion(uint16_t version);
243 
244 error_t dtlsFormatCookie(TlsContext *context, uint8_t *p, size_t *written);
245 
247  const DtlsClientParameters *clientParams);
248 
250 
253 
255  const DtlsHelloVerifyRequest *message, size_t length);
256 
258  const DtlsSupportedVersionList *supportedVersionList);
259 
260 void dtlsInitReplayWindow(TlsContext *context);
263 
264 //C++ guard
265 #ifdef __cplusplus
266  }
267 #endif
268 
269 #endif
error_t dtlsParseHelloVerifyRequest(TlsContext *context, const DtlsHelloVerifyRequest *message, size_t length)
Parse HelloVerifyRequest message.
Definition: dtls_misc.c:321
uint16_t version
Definition: dtls_misc.h:163
const uint8_t * sessionId
Definition: dtls_misc.h:213
uint8_t p
Definition: ndp.h:295
uint8_t message[]
Definition: chap.h:150
uint16_t msgSeq
Definition: dtls_misc.h:179
error_t dtlsSelectVersion(TlsContext *context, uint16_t version)
Set the DTLS version to be used.
Definition: dtls_misc.c:52
error_t dtlsFormatCookie(TlsContext *context, uint8_t *p, size_t *written)
Format Cookie field.
Definition: dtls_misc.c:138
__start_packed struct @56 DtlsCookie
Cookie.
__start_packed struct @57 DtlsSupportedVersionList
List of supported versions.
__start_packed struct @59 DtlsHandshake
DTLS handshake message.
__start_packed struct @58 DtlsRecord
DTLS record.
error_t(* DtlsCookieGenerateCallback)(TlsContext *context, const DtlsClientParameters *clientParams, uint8_t *cookie, size_t *length, void *param)
DTLS cookie generation callback function.
Definition: dtls_misc.h:226
uint16_t dtlsTranslateVersion(uint16_t version)
Translate TLS version into DTLS version.
Definition: dtls_misc.c:111
Client parameters.
Definition: dtls_misc.h:208
uint8_t fragOffset[3]
Definition: dtls_misc.h:180
uint8_t type
Definition: dtls_misc.h:162
__start_packed struct @55 DtlsSequenceNumber
Sequence number.
size_t compressMethodsLen
Definition: dtls_misc.h:218
__start_packed struct @60 DtlsHelloVerifyRequest
HelloVerifyRequest message.
error_t dtlsVerifyCookie(TlsContext *context, const DtlsCookie *cookie, const DtlsClientParameters *clientParams)
Cookie verification.
Definition: dtls_misc.c:172
uint8_t fragLength[3]
Definition: dtls_misc.h:181
const uint8_t * compressMethods
Definition: dtls_misc.h:217
uint8_t cookie[]
Definition: dtls_misc.h:194
void dtlsUpdateReplayWindow(TlsContext *context, DtlsSequenceNumber *seqNum)
Update sliding window.
Definition: dtls_misc.c:543
uint16_t serverVersion
Definition: dtls_misc.h:192
__start_packed struct _Ipv4Header __end_packed
error_t dtlsParseClientSupportedVersionsExtension(TlsContext *context, const DtlsSupportedVersionList *supportedVersionList)
Parse SupportedVersions extension.
Definition: dtls_misc.c:393
error_t
Error codes.
Definition: error.h:40
DtlsSequenceNumber seqNum
Definition: dtls_misc.h:165
DtlsRetransmitState
DTLS retransmission states.
Definition: dtls_misc.h:109
error_t dtlsSendHelloVerifyRequest(TlsContext *context)
Send HelloVerifyRequest message.
Definition: dtls_misc.c:239
uint8_t data[]
Definition: dtls_misc.h:167
uint16_t epoch
Definition: dtls_misc.h:164
uint8_t value[]
Definition: dtls_misc.h:141
const uint8_t * cipherSuites
Definition: dtls_misc.h:215
error_t dtlsFormatHelloVerifyRequest(TlsContext *context, DtlsHelloVerifyRequest *message, size_t *length)
Format HelloVerifyRequest message.
Definition: dtls_misc.c:283
error_t(* DtlsCookieVerifyCallback)(TlsContext *context, const DtlsClientParameters *clientParams, const uint8_t *cookie, size_t length, void *param)
DTLS cookie verification callback function.
Definition: dtls_misc.h:235
error_t dtlsCheckReplayWindow(TlsContext *context, DtlsSequenceNumber *seqNum)
Perform replay detection.
Definition: dtls_misc.c:462
uint8_t length
Definition: dtls_misc.h:140
uint8_t msgType
Definition: dtls_misc.h:177
#define TlsContext
Definition: tls.h:34
uint8_t b[6]
Definition: dtls_misc.h:130
uint8_t cookieLength
Definition: dtls_misc.h:193
void dtlsInitReplayWindow(TlsContext *context)
Initialize sliding window.
Definition: dtls_misc.c:441
const uint8_t * random
Definition: dtls_misc.h:211