OpenVPN
packet_id.h
Go to the documentation of this file.
1 /*
2  * OpenVPN -- An application to securely tunnel IP networks
3  * over a single TCP/UDP port, with support for SSL/TLS-based
4  * session authentication and key exchange,
5  * packet encryption, packet authentication, and
6  * packet compression.
7  *
8  * Copyright (C) 2002-2017 OpenVPN Technologies, Inc. <sales@openvpn.net>
9  *
10  * This program is free software; you can redistribute it and/or modify
11  * it under the terms of the GNU General Public License version 2
12  * as published by the Free Software Foundation.
13  *
14  * This program is distributed in the hope that it will be useful,
15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17  * GNU General Public License for more details.
18  *
19  * You should have received a copy of the GNU General Public License along
20  * with this program; if not, write to the Free Software Foundation, Inc.,
21  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
22  */
23 
24 /*
25  * These routines are designed to catch replay attacks,
26  * where a man-in-the-middle captures packets and then
27  * attempts to replay them back later.
28  */
29 
30 #ifdef ENABLE_CRYPTO
31 
32 #ifndef PACKET_ID_H
33 #define PACKET_ID_H
34 
35 #include "circ_list.h"
36 #include "buffer.h"
37 #include "error.h"
38 #include "otime.h"
39 
40 /*
41  * Enables OpenVPN to be compiled in special packet_id test mode.
42  */
43 /*#define PID_TEST*/
44 
45 #if 1
46 /*
47  * These are the types that members of
48  * a struct packet_id_net are converted
49  * to for network transmission.
50  */
52 #define PACKET_ID_MAX UINT32_MAX
54 
55 /*
56  * In TLS mode, when a packet ID gets to this level,
57  * start thinking about triggering a new
58  * SSL/TLS handshake.
59  */
60 #define PACKET_ID_WRAP_TRIGGER 0xFF000000
61 
62 /* convert a packet_id_type from host to network order */
63 #define htonpid(x) htonl(x)
64 
65 /* convert a packet_id_type from network to host order */
66 #define ntohpid(x) ntohl(x)
67 
68 /* convert a time_t in host order to a net_time_t in network order */
69 #define htontime(x) htonl((net_time_t)x)
70 
71 /* convert a net_time_t in network order to a time_t in host order */
72 #define ntohtime(x) ((time_t)ntohl(x))
73 
74 #else /* if 1 */
75 
76 /*
77  * DEBUGGING ONLY.
78  * Make packet_id_type and net_time_t small
79  * to test wraparound logic and corner cases.
80  */
81 
82 typedef uint8_t packet_id_type;
83 typedef uint16_t net_time_t;
84 
85 #define PACKET_ID_WRAP_TRIGGER 0x80
86 
87 #define htonpid(x) (x)
88 #define ntohpid(x) (x)
89 #define htontime(x) htons((net_time_t)x)
90 #define ntohtime(x) ((time_t)ntohs(x))
91 
92 #endif /* if 1 */
93 
94 /*
95  * Printf formats for special types
96  */
97 #define packet_id_format "%u"
98 typedef unsigned int packet_id_print_type;
99 
100 /*
101  * Maximum allowed backtrack in
102  * sequence number due to packets arriving
103  * out of order.
104  */
105 #define MIN_SEQ_BACKTRACK 0
106 #define MAX_SEQ_BACKTRACK 65536
107 #define DEFAULT_SEQ_BACKTRACK 64
108 
109 /*
110  * Maximum allowed backtrack in
111  * seconds due to packets arriving
112  * out of order.
113  */
114 #define MIN_TIME_BACKTRACK 0
115 #define MAX_TIME_BACKTRACK 600
116 #define DEFAULT_TIME_BACKTRACK 15
117 
118 /*
119  * Do a reap pass through the sequence number
120  * array once every n seconds in order to
121  * expire sequence numbers which can no longer
122  * be accepted because they would violate
123  * TIME_BACKTRACK.
124  */
125 #define SEQ_REAP_INTERVAL 5
126 
127 CIRC_LIST(seq_list, time_t);
128 
129 /*
130  * This is the data structure we keep on the receiving side,
131  * to check that no packet-id (i.e. sequence number + optional timestamp)
132  * is accepted more than once.
133  */
135 {
136  time_t last_reap; /* last call of packet_id_reap */
137  time_t time; /* highest time stamp received */
138  packet_id_type id; /* highest sequence number received */
139  int seq_backtrack; /* set from --replay-window */
140  int time_backtrack; /* set from --replay-window */
141  int max_backtrack_stat; /* maximum backtrack seen so far */
142  bool initialized; /* true if packet_id_init was called */
143  struct seq_list *seq_list; /* packet-id "memory" */
144  const char *name;
145  int unit;
146 };
147 
148 /*
149  * file to facilitate cross-session persistence
150  * of time/id
151  */
152 struct packet_id_persist
153 {
154  const char *filename;
155  int fd;
156  time_t time; /* time stamp */
157  packet_id_type id; /* sequence number */
160 };
161 
163 {
164  time_t time; /* time stamp */
165  packet_id_type id; /* sequence number */
166 };
167 
168 /*
169  * Keep a record of our current packet-id state
170  * on the sending side.
171  */
173 {
175  time_t time;
176 };
177 
178 /*
179  * Communicate packet-id over the wire.
180  * A short packet-id is just a 32 bit
181  * sequence number. A long packet-id
182  * includes a timestamp as well.
183  *
184  * Long packet-ids are used as IVs for
185  * CFB/OFB ciphers.
186  *
187  * This data structure is always sent
188  * over the net in network byte order,
189  * by calling htonpid, ntohpid,
190  * htontime, and ntohtime on the
191  * data elements to change them
192  * to and from standard sizes.
193  *
194  * In addition, time is converted to
195  * a net_time_t before sending,
196  * since openvpn always
197  * uses a 32-bit time_t but some
198  * 64 bit platforms use a
199  * 64 bit time_t.
200  */
202 {
204  time_t time; /* converted to net_time_t before transmission */
205 };
206 
207 struct packet_id
208 {
209  struct packet_id_send send;
210  struct packet_id_rec rec;
211 };
212 
213 void packet_id_init(struct packet_id *p, int seq_backtrack, int time_backtrack, const char *name, int unit);
214 
215 void packet_id_free(struct packet_id *p);
216 
217 /* should we accept an incoming packet id ? */
218 bool packet_id_test(struct packet_id_rec *p,
219  const struct packet_id_net *pin);
220 
221 /* change our current state to reflect an accepted packet id */
222 void packet_id_add(struct packet_id_rec *p,
223  const struct packet_id_net *pin);
224 
225 /* expire TIME_BACKTRACK sequence numbers */
226 void packet_id_reap(struct packet_id_rec *p);
227 
228 /*
229  * packet ID persistence
230  */
231 
232 /* initialize the packet_id_persist structure in a disabled state */
234 
235 /* close the file descriptor if it is open, and switch to disabled state */
237 
238 /* load persisted rec packet_id (time and id) only once from file, and set state to enabled */
239 void packet_id_persist_load(struct packet_id_persist *p, const char *filename);
240 
241 /* save persisted rec packet_id (time and id) to file (only if enabled state) */
243 
244 /* transfer packet_id_persist -> packet_id */
245 void packet_id_persist_load_obj(const struct packet_id_persist *p, struct packet_id *pid);
246 
247 /* return an ascii string representing a packet_id_persist object */
248 const char *packet_id_persist_print(const struct packet_id_persist *p, struct gc_arena *gc);
249 
250 /*
251  * Read/write a packet ID to/from the buffer. Short form is sequence number
252  * only. Long form is sequence number and timestamp.
253  */
254 
255 bool packet_id_read(struct packet_id_net *pin, struct buffer *buf, bool long_form);
256 
267 bool packet_id_write(struct packet_id_send *p, struct buffer *buf,
268  bool long_form, bool prepend);
269 
270 /*
271  * Inline functions.
272  */
273 
275 static inline bool
277 {
278  return pid->rec.initialized;
279 }
280 
281 /* are we in enabled state? */
282 static inline bool
284 {
285  return p->fd >= 0;
286 }
287 
288 /* transfer packet_id -> packet_id_persist */
289 static inline void
291 {
292  if (packet_id_persist_enabled(p) && pid->rec.time)
293  {
294  p->time = pid->rec.time;
295  p->id = pid->rec.id;
296  }
297 }
298 
299 const char *packet_id_net_print(const struct packet_id_net *pin, bool print_timestamp, struct gc_arena *gc);
300 
301 #ifdef PID_TEST
302 void packet_id_interactive_test(void);
303 
304 #endif
305 
306 static inline int
307 packet_id_size(bool long_form)
308 {
309  return sizeof(packet_id_type) + (long_form ? sizeof(net_time_t) : 0);
310 }
311 
312 static inline bool
314 {
315  return p->id >= PACKET_ID_WRAP_TRIGGER;
316 }
317 
318 static inline bool
319 check_timestamp_delta(time_t remote, unsigned int max_delta)
320 {
321  unsigned int abs;
322  const time_t local_now = now;
323 
324  if (local_now >= remote)
325  {
326  abs = local_now - remote;
327  }
328  else
329  {
330  abs = remote - local_now;
331  }
332  return abs <= max_delta;
333 }
334 
335 static inline void
337 {
338  if (p->last_reap + SEQ_REAP_INTERVAL <= now)
339  {
340  packet_id_reap(p);
341  }
342 }
343 
344 #endif /* PACKET_ID_H */
345 #endif /* ENABLE_CRYPTO */
void packet_id_persist_load(struct packet_id_persist *p, const char *filename)
Definition: packet_id.c:435
bool packet_id_read(struct packet_id_net *pin, struct buffer *buf, bool long_form)
Definition: packet_id.c:303
int time_backtrack
Definition: packet_id.h:140
int max_backtrack_stat
Definition: packet_id.h:141
int seq_backtrack
Definition: packet_id.h:139
void packet_id_free(struct packet_id *p)
Definition: packet_id.c:103
void packet_id_persist_save(struct packet_id_persist *p)
Definition: packet_id.c:484
#define SEQ_REAP_INTERVAL
Definition: packet_id.h:125
packet_id_type id
Definition: packet_id.h:203
packet_id_type id_last_written
Definition: packet_id.h:159
time_t last_reap
Definition: packet_id.h:136
time_t time_last_written
Definition: packet_id.h:158
const char * name
Definition: packet_id.h:144
static bool check_timestamp_delta(time_t remote, unsigned int max_delta)
Definition: packet_id.h:319
time_t time
Definition: packet_id.h:137
static bool packet_id_initialized(const struct packet_id *pid)
Is this struct packet_id initialized?
Definition: packet_id.h:276
struct packet_id_rec rec
Definition: packet_id.h:210
uint32_t net_time_t
Definition: packet_id.h:53
packet_id_type id
Definition: packet_id.h:138
unsigned int packet_id_print_type
Definition: packet_id.h:98
static bool packet_id_close_to_wrapping(const struct packet_id_send *p)
Definition: packet_id.h:313
static void packet_id_reap_test(struct packet_id_rec *p)
Definition: packet_id.h:336
struct seq_list * seq_list
Definition: packet_id.h:143
time_t now
Definition: otime.c:36
time_t time
Definition: packet_id.h:204
unsigned __int32 uint32_t
Definition: config-msvc.h:121
CIRC_LIST(seq_list, time_t)
const char * filename
Definition: packet_id.h:154
void packet_id_add(struct packet_id_rec *p, const struct packet_id_net *pin)
Definition: packet_id.c:117
packet_id_type id
Definition: packet_id.h:157
void packet_id_persist_close(struct packet_id_persist *p)
Definition: packet_id.c:421
bool packet_id_test(struct packet_id_rec *p, const struct packet_id_net *pin)
Definition: packet_id.c:204
void packet_id_persist_init(struct packet_id_persist *p)
Definition: packet_id.c:411
unsigned __int8 uint8_t
Definition: config-msvc.h:123
void packet_id_reap(struct packet_id_rec *p)
Definition: packet_id.c:172
bool initialized
Definition: packet_id.h:142
Wrapper structure for dynamically allocated memory.
Definition: buffer.h:60
bool packet_id_write(struct packet_id_send *p, struct buffer *buf, bool long_form, bool prepend)
Write a packet ID to buf, and update the packet ID state.
Definition: packet_id.c:351
uint32_t packet_id_type
Definition: packet_id.h:51
const char * packet_id_persist_print(const struct packet_id_persist *p, struct gc_arena *gc)
Definition: packet_id.c:536
unsigned __int16 uint16_t
Definition: config-msvc.h:122
Garbage collection arena used to keep track of dynamically allocated memory.
Definition: buffer.h:116
static void packet_id_persist_save_obj(struct packet_id_persist *p, const struct packet_id *pid)
Definition: packet_id.h:290
static bool packet_id_persist_enabled(const struct packet_id_persist *p)
Definition: packet_id.h:283
void packet_id_persist_load_obj(const struct packet_id_persist *p, struct packet_id *pid)
Definition: packet_id.c:526
#define PACKET_ID_WRAP_TRIGGER
Definition: packet_id.h:60
const char * packet_id_net_print(const struct packet_id_net *pin, bool print_timestamp, struct gc_arena *gc)
Definition: packet_id.c:393
packet_id_type id
Definition: packet_id.h:174
static int packet_id_size(bool long_form)
Definition: packet_id.h:307
void packet_id_init(struct packet_id *p, int seq_backtrack, int time_backtrack, const char *name, int unit)
Definition: packet_id.c:80