1/* 2 * OpenVPN -- An application to securely tunnel IP networks 3 * over a single 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-2010 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 20 * along with this program (see the file COPYING included with this 21 * distribution); if not, write to the Free Software Foundation, Inc., 22 * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 23 */ 24 25#ifndef FRAGMENT_H 26#define FRAGMENT_H 27 28/** 29 * @file 30 * Data Channel Fragmentation module header file. 31 */ 32 33 34#ifdef ENABLE_FRAGMENT 35 36/** 37 * @addtogroup fragmentation 38 * @{ 39 */ 40 41 42#include "common.h" 43#include "buffer.h" 44#include "interval.h" 45#include "mtu.h" 46#include "shaper.h" 47#include "error.h" 48 49 50#define N_FRAG_BUF 25 51 /**< Number of packet buffers for 52 * reassembling incoming fragmented 53 * packets. */ 54 55#define FRAG_TTL_SEC 10 56 /**< Time-to-live in seconds for a %fragment. */ 57 58#define FRAG_WAKEUP_INTERVAL 5 59 /**< Interval in seconds between calls to 60 * wakeup code. */ 61 62/**************************************************************************/ 63/** 64 * Structure for reassembling one incoming fragmented packet. 65 */ 66struct fragment { 67 bool defined; /**< Whether reassembly is currently 68 * taking place in this structure. */ 69 70 int max_frag_size; /**< Maximum size of each %fragment. */ 71 72# define FRAG_MAP_MASK 0xFFFFFFFF 73 /**< Mask for reassembly map. */ 74# define MAX_FRAGS 32 /**< Maximum number of fragments per packet. */ 75 unsigned int map; 76 /**< Reassembly map for recording which 77 * fragments have been received. 78 * 79 * A bit array where each bit 80 * corresponds to a %fragment. A 1 bit 81 * in element n means that the %fragment 82 * n has been received. Needs to have 83 * at least \c MAX_FRAGS bits. */ 84 85 time_t timestamp; /**< Timestamp for time-to-live purposes. */ 86 87 struct buffer buf; /**< Buffer in which received datagrams 88 * are reassembled. */ 89}; 90 91 92/** 93 * List of fragment structures for reassembling multiple incoming packets 94 * concurrently. 95 */ 96struct fragment_list { 97 int seq_id; /**< Highest fragmentation sequence ID of 98 * the packets currently being 99 * reassembled. */ 100 int index; /**< Index of the packet being reassembled 101 * with the highest fragmentation 102 * sequence ID into the \c 103 * fragment_list.fragments array. */ 104 105/** Array of reassembly structures, each can contain one whole packet. 106 * 107 * The fragmentation sequence IDs of the packets being reassembled in 108 * this array are linearly increasing. \c 109 * fragment_list.fragments[fragment_list.index] has an ID of \c 110 * fragment_list.seq_id. This means that one of these \c fragment_list 111 * structures can at any one time contain at most packets with the 112 * fragmentation sequence IDs in the range \c fragment_list.seq_id \c - 113 * \c N_FRAG_BUF \c + \c 1 to \c fragment_list.seq_id, inclusive. 114 */ 115 struct fragment fragments[N_FRAG_BUF]; 116}; 117 118 119/** 120 * Fragmentation and reassembly state for one VPN tunnel instance. 121 * 122 * This structure contains all the state necessary for sending and 123 * receiving fragmented data channel packets associated with one VPN 124 * tunnel. 125 * 126 * The fragmented packet currently being sent to a remote OpenVPN peer is 127 * stored in \c fragment_master.outgoing. It is copied into that buffer 128 * by the \c fragment_outgoing() function and the remaining parts to be 129 * sent can be retrieved by successive calls to \c 130 * fragment_ready_to_send(). 131 * 132 * The received packets currently being reassembled are stored in the \c 133 * fragment_master.incoming array of \c fragment structures. The \c 134 * fragment_incoming() function adds newly received parts into this array 135 * and returns the whole packets once reassembly is complete. 136 */ 137struct fragment_master { 138 struct event_timeout wakeup; /**< Timeout structure used by the main 139 * event loop to know when to do 140 * fragmentation housekeeping. */ 141 bool received_os_mtu_hint; /**< Whether the operating system has 142 * explicitly recommended an MTU value. */ 143# define N_SEQ_ID 256 144 /**< One more than the maximum fragment 145 * sequence ID, above which the IDs wrap 146 * to zero. Should be a power of 2. */ 147 int outgoing_seq_id; /**< Fragment sequence ID of the current 148 * fragmented packet waiting to be sent. 149 * 150 * All parts of a fragmented packet 151 * share the same sequence ID, so that 152 * the remote OpenVPN peer can determine 153 * which parts belong to which original 154 * packet. */ 155# define MAX_FRAG_PKT_SIZE 65536 156 /**< (Not used) Maximum packet size before 157 * fragmenting. */ 158 int outgoing_frag_size; /**< Size in bytes of each part to be 159 * sent, except for the last part which 160 * may be smaller. 161 * 162 * This value is computed by the \c 163 * optimal_fragment_size() function. Its 164 * value is sent to the remote peer in 165 * the fragmentation header of the last 166 * part (i.e. with %fragment type \c 167 * FRAG_YES_LAST) using the \c 168 * FRAG_SIZE_MASK and \c FRAG_SIZE_SHIFT 169 * bits. */ 170 int outgoing_frag_id; /**< The fragment ID of the next part to 171 * be sent. Must have a value between 0 172 * and \c MAX_FRAGS-1. */ 173 struct buffer outgoing; /**< Buffer containing the remaining parts 174 * of the fragmented packet being sent. */ 175 struct buffer outgoing_return; 176 /**< Buffer used by \c 177 * fragment_ready_to_send() to return a 178 * part to send. */ 179 180 struct fragment_list incoming; 181 /**< List of structures for reassembling 182 * incoming packets. */ 183}; 184 185 186/**************************************************************************/ 187/** @name Fragment header 188 * @todo Add description of %fragment header format. 189 *//** @{ *//*************************************/ 190 191typedef uint32_t fragment_header_type; 192 /**< Fragmentation information is stored in 193 * a 32-bit packet header. */ 194 195#define hton_fragment_header_type(x) htonl(x) 196 /**< Convert a fragment_header_type from 197 * host to network order. */ 198 199#define ntoh_fragment_header_type(x) ntohl(x) 200 /**< Convert a \c fragment_header_type 201 * from network to host order. */ 202 203#define FRAG_TYPE_MASK 0x00000003 204 /**< Bit mask for %fragment type info. */ 205#define FRAG_TYPE_SHIFT 0 /**< Bit shift for %fragment type info. */ 206 207#define FRAG_WHOLE 0 /**< Fragment type indicating packet is 208 * whole. */ 209#define FRAG_YES_NOTLAST 1 /**< Fragment type indicating packet is 210 * part of a fragmented packet, but not 211 * the last part in the sequence. */ 212#define FRAG_YES_LAST 2 /**< Fragment type indicating packet is 213 * the last part in the sequence of 214 * parts. */ 215#define FRAG_TEST 3 /**< Fragment type not implemented yet. 216 * In the future might be used as a 217 * control packet for establishing MTU 218 * size. */ 219 220#define FRAG_SEQ_ID_MASK 0x000000ff 221 /**< Bit mask for %fragment sequence ID. */ 222#define FRAG_SEQ_ID_SHIFT 2 /**< Bit shift for %fragment sequence ID. */ 223 224#define FRAG_ID_MASK 0x0000001f 225 /**< Bit mask for %fragment ID. */ 226#define FRAG_ID_SHIFT 10 227 /**< Bit shift for %fragment ID. */ 228 229/* 230 * FRAG_SIZE 14 bits 231 * 232 * IF FRAG_YES_LAST (FRAG_SIZE): 233 * The max size of a %fragment. If a %fragment is not the last %fragment in the packet, 234 * then the %fragment size is guaranteed to be equal to the max %fragment size. Therefore, 235 * max_frag_size is only sent over the wire if FRAG_LAST is set. Otherwise it is assumed 236 * to be the actual %fragment size received. 237 */ 238#define FRAG_SIZE_MASK 0x00003fff 239 /**< Bit mask for %fragment size. */ 240#define FRAG_SIZE_SHIFT 15 241 /**< Bit shift for %fragment size. */ 242#define FRAG_SIZE_ROUND_SHIFT 2 /**< Bit shift for %fragment size rounding. */ 243#define FRAG_SIZE_ROUND_MASK ((1 << FRAG_SIZE_ROUND_SHIFT) - 1) 244 /**< Bit mask for %fragment size rounding. */ 245 246/* 247 * FRAG_EXTRA 16 bits 248 * 249 * IF FRAG_WHOLE or FRAG_YES_NOTLAST, these 16 bits are available (not currently used) 250 */ 251#define FRAG_EXTRA_MASK 0x0000ffff 252 /**< Bit mask for extra bits. */ 253#define FRAG_EXTRA_SHIFT 15 254 /**< Bit shift for extra bits. */ 255 256/** @} name Fragment header *//********************************************/ 257 258 259/**************************************************************************/ 260/** @name Functions for initialization and cleanup *//** @{ *//************/ 261 262/** 263 * Allocate and initialize a \c fragment_master structure. 264 * 265 * This function also modifies the \a frame packet geometry parameters to 266 * include space for the fragmentation header. 267 * 268 * @param frame - The packet geometry parameters for this VPN 269 * tunnel, modified by this function to include the 270 * fragmentation header. 271 * 272 * @return A pointer to the new \c fragment_master structure. 273 */ 274struct fragment_master *fragment_init (struct frame *frame); 275 276 277/** 278 * Allocate internal packet buffers for a \c fragment_master structure. 279 * 280 * @param f - The \c fragment_master structure for which to 281 * allocate the internal buffers. 282 * @param frame - The packet geometry parameters for this VPN 283 * tunnel, used to determine how much memory to 284 * allocate for each packet buffer. 285 */ 286void fragment_frame_init (struct fragment_master *f, const struct frame *frame); 287 288 289/** 290 * Free a \c fragment_master structure and its internal packet buffers. 291 * 292 * @param f - The \c fragment_master structure to free. 293 */ 294void fragment_free (struct fragment_master *f); 295 296/** @} name Functions for initialization and cleanup *//*******************/ 297 298 299/**************************************************************************/ 300/** @name Functions for processing packets received from a remote OpenVPN peer */ 301/** @{ */ 302 303/** 304 * Process an incoming packet, which may or may not be fragmented. 305 * 306 * This function inspects the fragmentation header of the incoming packet 307 * and processes the packet accordingly. Depending on the %fragment type 308 * bits (\c FRAG_TYPE_MASK and \c FRAG_TYPE_SHIFT) the packet is processed 309 * in the following ways: 310 * - \c FRAG_WHOLE: the packet is not fragmented, and this function does 311 * not modify its contents, except for removing the fragmentation 312 * header. 313 * - \c FRAG_YES_NOTLAST or \c FRAG_YES_LAST: the packet is part of a 314 * fragmented packet. This function copies the packet into an internal 315 * reassembly buffer. If the incoming part completes the packet being 316 * reassembled, the \a buf argument is modified to point to the fully 317 * reassembled packet. If, on the other hand, reassembly is not yet 318 * complete, then the the \a buf buffer is set to empty. 319 * - Any other value: error. 320 * 321 * If an error occurs during processing, an error message is logged and 322 * the length of \a buf is set to zero. 323 * 324 * @param f - The \c fragment_master structure for this VPN 325 * tunnel. 326 * @param buf - A pointer to the buffer structure containing the 327 * incoming packet. This pointer will have been 328 * modified on return either to point to a 329 * completely reassembled packet, or to have length 330 * set to zero if reassembly is not yet complete. 331 * @param frame - The packet geometry parameters for this VPN 332 * tunnel. 333 * 334 * @return Void.\n On return, the \a buf argument will point to a buffer. 335 * The buffer will have nonzero length if the incoming packet passed 336 * to this function was whole and unfragmented, or if it was the final 337 * part of a fragmented packet thereby completing reassembly. On the 338 * other hand, the buffer will have a length of zero if the incoming 339 * packet was part of a fragmented packet and reassembly is not yet 340 * complete. If an error occurs during processing, the buffer length 341 * is also set to zero. 342 */ 343void fragment_incoming (struct fragment_master *f, struct buffer *buf, 344 const struct frame* frame); 345 346/** @} name Functions for processing packets received from a VPN tunnel */ 347 348 349/**************************************************************************/ 350/** @name Functions for processing packets to be sent to a remote OpenVPN peer */ 351/** @{ */ 352 353/** 354 * Process an outgoing packet, which may or may not need to be fragmented. 355 * 356 * This function inspects the outgoing packet, determines whether it needs 357 * to be fragmented, and processes it accordingly. 358 * 359 * Depending on the size of the outgoing packet and the packet geometry 360 * parameters for the VPN tunnel, the packet will or will not be 361 * fragmented. 362 * @li Packet size is less than or equal to the maximum packet size for 363 * this VPN tunnel: fragmentation is not necessary. The \a buf 364 * argument points to a buffer containing the unmodified outgoing 365 * packet with a fragmentation header indicating the packet is whole 366 * (FRAG_WHOLE) prepended. 367 * @li Packet size is greater than the maximum packet size for this VPN 368 * tunnel: fragmentation is necessary. The original outgoing packet 369 * is copied into an internal buffer for fragmentation. The \a buf 370 * argument is modified to point to the first part of the fragmented 371 * packet. The remaining parts remain stored in the internal buffer, 372 * and can be retrieved using the \c fragment_ready_to_send() 373 * function. 374 * 375 * If an error occurs during processing, an error message is logged and 376 * the length of \a buf is set to zero. 377 * 378 * @param f - The \c fragment_master structure for this VPN 379 * tunnel. 380 * @param buf - A pointer to the buffer structure containing the 381 * outgoing packet. This pointer will be modified 382 * to point to a whole unfragmented packet or to the 383 * first part of a fragmented packet on return. 384 * @param frame - The packet geometry parameters for this VPN 385 * tunnel. 386 * 387 * @return Void.\n On return, the \a buf argument will point to a buffer. 388 * This buffer contains either the whole original outgoing packet if 389 * fragmentation was not necessary, or the first part of the 390 * fragmented outgoing packet if fragmentation was necessary. In both 391 * cases a fragmentation header will have been prepended to inform the 392 * remote peer how to handle the packet. 393 */ 394void fragment_outgoing (struct fragment_master *f, struct buffer *buf, 395 const struct frame* frame); 396 397/** 398 * Check whether outgoing fragments are ready to be send, and if so make 399 * one available. 400 * 401 * This function checks whether the internal buffer for fragmenting 402 * outgoing packets contains any unsent parts. If it does not, meaning 403 * there is nothing waiting to be sent, it returns false. Otherwise there 404 * are parts ready to be sent, and it returns true. In that case it also 405 * modifies the \a buf argument to point to a buffer containing the next 406 * part to be sent. 407 * 408 * @param f - The \a fragment_master structure for this VPN 409 * tunnel. 410 * @param buf - A pointer to a buffer structure which on return, 411 * if there are parts waiting to be sent, will point 412 * to the next part to be sent. 413 * @param frame - The packet geometry parameters for this VPN 414 * tunnel. 415 * 416 * @return 417 * @li True, if an outgoing packet has been fragmented and not all parts 418 * have been sent yet. In this case this function will modify the \a 419 * buf argument to point to a buffer containing the next part to be 420 * sent. 421 * @li False, if there are no outgoing fragmented parts waiting to be 422 * sent. 423 */ 424bool fragment_ready_to_send (struct fragment_master *f, struct buffer *buf, 425 const struct frame* frame); 426 427/** 428 * Check whether a \c fragment_master structure contains fragments ready 429 * to be sent. 430 * 431 * @param f - The \c fragment_master structure for this VPN 432 * tunnel. 433 * 434 * @return 435 * @li True, if there are one or more fragments ready to be sent. 436 * @li False, otherwise. 437 */ 438static inline bool 439fragment_outgoing_defined (struct fragment_master *f) 440{ 441 return f->outgoing.len > 0; 442} 443 444/** @} name Functions for processing packets going out through a VPN tunnel */ 445 446 447void fragment_wakeup (struct fragment_master *f, struct frame *frame); 448 449 450/**************************************************************************/ 451/** @name Functions for regular housekeeping *//** @{ *//******************/ 452 453/** 454 * Perform housekeeping of a \c fragment_master structure. 455 * 456 * Housekeeping includes scanning incoming packet reassembly buffers for 457 * packets which have not yet been reassembled completely but are already 458 * older than their time-to-live. 459 * 460 * @param f - The \c fragment_master structure for this VPN 461 * tunnel. 462 * @param frame - The packet geometry parameters for this VPN 463 * tunnel. 464 */ 465static inline void 466fragment_housekeeping (struct fragment_master *f, struct frame *frame, struct timeval *tv) 467{ 468 if (event_timeout_trigger (&f->wakeup, tv, ETT_DEFAULT)) 469 fragment_wakeup (f, frame); 470} 471 472/** @} name Functions for regular housekeeping *//*************************/ 473 474 475/** @} addtogroup fragmentation *//****************************************/ 476 477 478#endif 479#endif 480