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-2022 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 2.2.0
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 #define DTLS_VERSION_1_3 0xFEFC
38 
39 //DTLS support
40 #ifndef DTLS_SUPPORT
41  #define DTLS_SUPPORT DISABLED
42 #elif (DTLS_SUPPORT != ENABLED && DTLS_SUPPORT != DISABLED)
43  #error DTLS_SUPPORT parameter is not valid
44 #endif
45 
46 //Default PMTU value
47 #ifndef DTLS_DEFAULT_PMTU
48  #define DTLS_DEFAULT_PMTU 1452
49 #elif (DTLS_DEFAULT_PMTU < 64)
50  #error DTLS_DEFAULT_PMTU parameter is not valid
51 #endif
52 
53 //Minimum PMTU value
54 #ifndef DTLS_MIN_PMTU
55  #define DTLS_MIN_PMTU 528
56 #elif (DTLS_MIN_PMTU < 64)
57  #error DTLS_MIN_PMTU parameter is not valid
58 #endif
59 
60 //Replay protection
61 #ifndef DTLS_REPLAY_DETECTION_SUPPORT
62  #define DTLS_REPLAY_DETECTION_SUPPORT ENABLED
63 #elif (DTLS_REPLAY_DETECTION_SUPPORT != ENABLED && DTLS_REPLAY_DETECTION_SUPPORT != DISABLED)
64  #error DTLS_REPLAY_DETECTION_SUPPORT parameter is not valid
65 #endif
66 
67 //Size of the sliding window for replay protection
68 #ifndef DTLS_REPLAY_WINDOW_SIZE
69  #define DTLS_REPLAY_WINDOW_SIZE 64
70 #elif (DTLS_REPLAY_WINDOW_SIZE < 1)
71  #error DTLS_REPLAY_WINDOW_SIZE parameter is not valid
72 #endif
73 
74 //Maximum size for cookies
75 #ifndef DTLS_MAX_COOKIE_SIZE
76  #define DTLS_MAX_COOKIE_SIZE 32
77 #elif (DTLS_MAX_COOKIE_SIZE < 32)
78  #error DTLS_MAX_COOKIE_SIZE parameter is not valid
79 #endif
80 
81 //Maximum number of retransmissions
82 #ifndef DTLS_MAX_RETRIES
83  #define DTLS_MAX_RETRIES 5
84 #elif (DTLS_MAX_RETRIES < 1)
85  #error DTLS_MAX_RETRIES parameter is not valid
86 #endif
87 
88 //Initial retransmission timeout
89 #ifndef DTLS_INIT_TIMEOUT
90  #define DTLS_INIT_TIMEOUT 1000
91 #elif (DTLS_INIT_TIMEOUT < 100)
92  #error DTLS_INIT_TIMEOUT parameter is not valid
93 #endif
94 
95 //Minimum retransmission timeout
96 #ifndef DTLS_MIN_TIMEOUT
97  #define DTLS_MIN_TIMEOUT 500
98 #elif (DTLS_MIN_TIMEOUT < 100)
99  #error DTLS_MIN_TIMEOUT parameter is not valid
100 #endif
101 
102 //Maximum retransmission timeout
103 #ifndef DTLS_MAX_TIMEOUT
104  #define DTLS_MAX_TIMEOUT 60000
105 #elif (DTLS_MAX_TIMEOUT < 1000)
106  #error DTLS_MAX_TIMEOUT parameter is not valid
107 #endif
108 
109 //C++ guard
110 #ifdef __cplusplus
111 extern "C" {
112 #endif
113 
114 
115 /**
116  * @brief DTLS retransmission states
117  **/
118 
119 typedef enum
120 {
126 
127 
128 //CodeWarrior or Win32 compiler?
129 #if defined(__CWCC__) || defined(_WIN32)
130  #pragma pack(push, 1)
131 #endif
132 
133 
134 /**
135  * @brief Sequence number
136  **/
137 
138 typedef __start_packed struct
139 {
140  uint8_t b[6];
142 
143 
144 /**
145  * @brief Cookie
146  **/
147 
148 typedef __start_packed struct
149 {
150  uint8_t length; //0
151  uint8_t value[]; //1
153 
154 
155 /**
156  * @brief List of supported versions
157  **/
158 
159 typedef __start_packed struct
160 {
161  uint8_t length; //0
162  uint16_t value[]; //1
164 
165 
166 /**
167  * @brief DTLS record
168  **/
169 
170 typedef __start_packed struct
171 {
172  uint8_t type; //0
173  uint16_t version; //1-2
174  uint16_t epoch; //3-4
176  uint16_t length; //11-12
177  uint8_t data[]; //13
179 
180 
181 /**
182  * @brief DTLS handshake message
183  **/
184 
185 typedef __start_packed struct
186 {
187  uint8_t msgType; //0
188  uint8_t length[3]; //1-3
189  uint16_t msgSeq; //4-5
190  uint8_t fragOffset[3]; //6-8
191  uint8_t fragLength[3]; //9-11
192  uint8_t data[]; //12
194 
195 
196 /**
197  * @brief HelloVerifyRequest message
198  **/
199 
200 typedef __start_packed struct
201 {
202  uint16_t serverVersion; //0-1
203  uint8_t cookieLength; //2
204  uint8_t cookie[]; //3
206 
207 
208 //CodeWarrior or Win32 compiler?
209 #if defined(__CWCC__) || defined(_WIN32)
210  #pragma pack(pop)
211 #endif
212 
213 
214 /**
215  * @brief Client parameters
216  **/
217 
218 typedef struct
219 {
220  uint16_t version;
221  const uint8_t *random;
222  size_t randomLen;
223  const uint8_t *sessionId;
224  size_t sessionIdLen;
225  const uint8_t *cipherSuites;
227  const uint8_t *compressMethods;
230 
231 
232 /**
233  * @brief DTLS cookie generation callback function
234  **/
235 
237  const DtlsClientParameters *clientParams, uint8_t *cookie,
238  size_t *length, void *param);
239 
240 
241 /**
242  * @brief DTLS cookie verification callback function
243  **/
244 
246  const DtlsClientParameters *clientParams, const uint8_t *cookie,
247  size_t length, void *param);
248 
249 
250 //DTLS specific functions
251 error_t dtlsSelectVersion(TlsContext *context, uint16_t version);
252 uint16_t dtlsTranslateVersion(uint16_t version);
253 
254 error_t dtlsFormatCookie(TlsContext *context, uint8_t *p, size_t *written);
255 
257  const DtlsClientParameters *clientParams);
258 
260 
263 
265  const DtlsHelloVerifyRequest *message, size_t length);
266 
268  const DtlsSupportedVersionList *supportedVersionList);
269 
270 void dtlsInitReplayWindow(TlsContext *context);
273 
274 //C++ guard
275 #ifdef __cplusplus
276 }
277 #endif
278 
279 #endif
@ DTLS_RETRANSMIT_STATE_WAITING
Definition: dtls_misc.h:123
const uint8_t * random
Definition: dtls_misc.h:221
uint8_t length
Definition: dtls_misc.h:150
error_t dtlsFormatCookie(TlsContext *context, uint8_t *p, size_t *written)
Format Cookie field.
Definition: dtls_misc.c:145
uint8_t b[6]
Definition: dtls_misc.h:140
uint8_t p
Definition: ndp.h:298
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:236
uint16_t version
Definition: dtls_misc.h:173
@ DTLS_RETRANSMIT_STATE_FINISHED
Definition: dtls_misc.h:124
error_t dtlsSelectVersion(TlsContext *context, uint16_t version)
Set the DTLS version to be used.
Definition: dtls_misc.c:54
__start_packed struct @1 DtlsCookie
Cookie.
#define TlsContext
Definition: tls.h:36
error_t
Error codes.
Definition: error.h:43
__start_packed struct @5 DtlsHelloVerifyRequest
HelloVerifyRequest message.
uint8_t type
Definition: dtls_misc.h:172
Client parameters.
Definition: dtls_misc.h:219
const uint8_t * cipherSuites
Definition: dtls_misc.h:225
@ DTLS_RETRANSMIT_STATE_SENDING
Definition: dtls_misc.h:122
uint8_t fragLength[3]
Definition: dtls_misc.h:191
__start_packed struct _Ipv4Header __end_packed
error_t dtlsParseClientSupportedVersionsExtension(TlsContext *context, const DtlsSupportedVersionList *supportedVersionList)
Parse SupportedVersions extension.
Definition: dtls_misc.c:402
uint16_t epoch
Definition: dtls_misc.h:174
uint8_t fragOffset[3]
Definition: dtls_misc.h:190
uint16_t dtlsTranslateVersion(uint16_t version)
Translate TLS version into DTLS version.
Definition: dtls_misc.c:113
error_t dtlsVerifyCookie(TlsContext *context, const DtlsCookie *cookie, const DtlsClientParameters *clientParams)
Cookie verification.
Definition: dtls_misc.c:179
__start_packed struct @0 DtlsSequenceNumber
Sequence number.
uint16_t serverVersion
Definition: dtls_misc.h:202
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:245
const uint8_t * sessionId
Definition: dtls_misc.h:223
error_t dtlsSendHelloVerifyRequest(TlsContext *context)
Send HelloVerifyRequest message.
Definition: dtls_misc.c:248
void dtlsUpdateReplayWindow(TlsContext *context, DtlsSequenceNumber *seqNum)
Update sliding window.
Definition: dtls_misc.c:551
uint8_t msgType
Definition: dtls_misc.h:187
__start_packed struct @2 DtlsSupportedVersionList
List of supported versions.
error_t dtlsCheckReplayWindow(TlsContext *context, DtlsSequenceNumber *seqNum)
Perform replay detection.
Definition: dtls_misc.c:470
uint8_t message[]
Definition: chap.h:152
const uint8_t * compressMethods
Definition: dtls_misc.h:227
uint8_t cookie[]
Definition: dtls_misc.h:204
__start_packed struct @4 DtlsHandshake
DTLS handshake message.
void dtlsInitReplayWindow(TlsContext *context)
Initialize sliding window.
Definition: dtls_misc.c:449
error_t dtlsFormatHelloVerifyRequest(TlsContext *context, DtlsHelloVerifyRequest *message, size_t *length)
Format HelloVerifyRequest message.
Definition: dtls_misc.c:292
__start_packed struct @3 DtlsRecord
DTLS record.
DtlsSequenceNumber seqNum
Definition: dtls_misc.h:175
size_t compressMethodsLen
Definition: dtls_misc.h:228
DtlsRetransmitState
DTLS retransmission states.
Definition: dtls_misc.h:120
uint8_t value[]
Definition: dtls_misc.h:151
error_t dtlsParseHelloVerifyRequest(TlsContext *context, const DtlsHelloVerifyRequest *message, size_t length)
Parse HelloVerifyRequest message.
Definition: dtls_misc.c:330
uint8_t data[]
Definition: dtls_misc.h:177
@ DTLS_RETRANSMIT_STATE_PREPARING
Definition: dtls_misc.h:121
uint16_t msgSeq
Definition: dtls_misc.h:189
uint8_t cookieLength
Definition: dtls_misc.h:203