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