OpenVPN Doxygen patches

index fcd4661..973677d 100644
@@ -22,6 +22,12 @@
  *  59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
 
+
+/**
+ * @file
+ */
+
+
 #ifndef CRYPTO_H
 #define CRYPTO_H
 #ifdef USE_CRYPTO

@@ -199,72 +205,118 @@ struct key_type
   const EVP_MD *digest;
 };
 
-/*
- * A random key.
+
+/**
+ * Container for unidirectional cipher and HMAC %key material.
+ * @ingroup control_processor
  */
 struct key
 {
   uint8_t cipher[MAX_CIPHER_KEY_LENGTH];
+                                /**< %Key material for cipher operations. */
   uint8_t hmac[MAX_HMAC_KEY_LENGTH];
+                                /**< %Key material for HMAC operations. */
 };
 
 #define KEY_DIRECTION_BIDIRECTIONAL 0 /* same keys for both directions */
 #define KEY_DIRECTION_NORMAL        1 /* encrypt with keys[0], decrypt with keys[1] */
 #define KEY_DIRECTION_INVERSE       2 /* encrypt with keys[1], decrypt with keys[0] */
 
-/*
- * Dual random keys (for encrypt/decrypt)
+/**
+ * Container for bidirectional cipher and HMAC %key material.
+ * @ingroup control_processor
  */
 struct key2
 {
-  int n;
-  struct key keys[2];
+  int n;                        /**< The number of \c key objects stored
+                                 *   in the \c key2.keys array. */
+  struct key keys[2];           /**< Two unidirectional sets of %key
+                                 *   material. */
 };
 
-/*
- * Used for controlling bidirectional keys
- * vs. a separate key for each direction.
+/**
+ * %Key ordering of the \c key2.keys array.
+ * @ingroup control_processor
+ * 
+ * This structure takes care of correct ordering when using unidirectional
+ * or bidirectional %key material, and allows the same shared secret %key
+ * file to be loaded in the same way by client and server by having one of
+ * the hosts use an reversed ordering.
  */
 struct key_direction_state
 {
-  int out_key;
-  int in_key;
-  int need_keys;
+  int out_key;                  /**< Index into the \c key2.keys array for
+                                 *   the sending direction. */
+  int in_key;                   /**< Index into the \c key2.keys array for
+                                 *   the receiving direction. */
+  int need_keys;                /**< The number of key objects necessary
+                                 *   to support both sending and
+                                 *   receiving.
+                                 *   
+                                 *   This will be 1 if the same keys are
+                                 *   used in both directions, or 2 if
+                                 *   there are two sets of unidirectional
+                                 *   keys. */
 };
 
-/*
- * A key context for cipher and/or HMAC.
+/**
+ * Container for one set of OpenSSL cipher and/or HMAC contexts.
+ * @ingroup control_processor
  */
 struct key_ctx
 {
-  EVP_CIPHER_CTX *cipher;
-  HMAC_CTX *hmac;
+  EVP_CIPHER_CTX *cipher;       /**< OpenSSL cipher %context. */
+  HMAC_CTX *hmac;               /**< OpenSSL HMAC %context. */
 };
 
-/*
- * Cipher/HMAC key context for both sending and receiving
- * directions.
+/**
+ * Container for two sets of OpenSSL cipher and/or HMAC contexts for both
+ * sending and receiving directions.
+ * @ingroup control_processor
  */
 struct key_ctx_bi
 {
-  struct key_ctx encrypt;
-  struct key_ctx decrypt;
+  struct key_ctx encrypt;       /**< OpenSSL cipher and/or HMAC contexts
+                                 *   for sending direction. */
+  struct key_ctx decrypt;       /**< OpenSSL cipher and/or HMAC contexts
+                                 *   for receiving direction. */
 };
 
-/*
- * Options for encrypt/decrypt.
+/**
+ * Security parameter state for processing data channel packets.
+ * @ingroup data_crypto
  */
 struct crypto_options
 {
   struct key_ctx_bi *key_ctx_bi;
-  struct packet_id *packet_id;
+                                /**< OpenSSL cipher and HMAC contexts for
+                                 *   both sending and receiving
+                                 *   directions. */
+  struct packet_id *packet_id;  /**< Current packet ID state for both
+                                 *   sending and receiving directions. */
   struct packet_id_persist *pid_persist;
+                                /**< Persistent packet ID state for
+                                 *   keeping state between successive
+                                 *   OpenVPN process startups. */
 
 # define CO_PACKET_ID_LONG_FORM  (1<<0)
+                                /**< Bit-flag indicating whether to use
+                                 *   OpenVPN's long packet ID format. */
 # define CO_USE_IV               (1<<1)
+                                /**< Bit-flag indicating whether to
+                                 *   generate a pseudo-random IV for each
+                                 *   packet being encrypted. */
 # define CO_IGNORE_PACKET_ID     (1<<2)
+                                /**< Bit-flag indicating whether to ignore
+                                 *   the packet ID of a received packet. 
+                                 *   This flag is used during processing
+                                 *   of the first packet received from a
+                                 *   client. */
 # define CO_MUTE_REPLAY_WARNINGS (1<<3)
-  unsigned int flags;
+                                /**< Bit-flag indicating not to display
+                                 *   replay warnings. */
+  unsigned int flags;           /**< Bit-flags determining behavior of
+                                 *   security operation functions. */
 };
 
 void init_key_type (struct key_type *kt, const char *ciphername,

@@ -313,14 +365,80 @@ void init_key_ctx (struct key_ctx *ctx, struct key *key,
 void free_key_ctx (struct key_ctx *ctx);
 void free_key_ctx_bi (struct key_ctx_bi *ctx);
 
+
+/**************************************************************************/
+/** @name Functions for performing security operations on data channel packets
+ *  @{ */
+
+/**
+ * Encrypt and HMAC sign a packet so that it can be sent as a data channel
+ * VPN tunnel packet to a remote OpenVPN peer.
+ * @ingroup data_crypto
+ * 
+ * This function handles encryption and HMAC signing of a data channel
+ * packet before it is sent to its remote OpenVPN peer.  It receives the
+ * necessary security parameters in the \a opt argument, which should have
+ * been set to the correct values by the \c tls_pre_encrypt() function.
+ * 
+ * This function calls the \c EVP_Cipher* and \c HMAC_* functions of the
+ * OpenSSL library to perform the actual security operations.
+ * 
+ * If an error occurs during processing, then the \a buf %buffer is set to
+ * empty.
+ * 
+ * @param buf          - The %buffer containing the packet on which to
+ *                       perform security operations.
+ * @param work         - A working %buffer.
+ * @param opt          - The security parameter state for this VPN tunnel.
+ * @param frame        - The packet geometry parameters for this VPN
+ *                       tunnel.
+ * @return This function returns void.\n On return, the \a buf argument
+ *     will point to the resulting %buffer.  This %buffer will either
+ *     contain the processed packet ready for sending, or be empty if an
+ *     error occurred.
+ */
 void openvpn_encrypt (struct buffer *buf, struct buffer work,
 		      const struct crypto_options *opt,
 		      const struct frame* frame);
 
+
+/**
+ * HMAC verify and decrypt a data channel packet received from a remote
+ * OpenVPN peer.
+ * @ingroup data_crypto
+ * 
+ * This function handles authenticating and decrypting a data channel
+ * packet received from a remote OpenVPN peer.  It receives the necessary
+ * security parameters in the \a opt argument, which should have been set
+ * to the correct values by the \c tls_pre_decrypt() function.
+ * 
+ * This function calls the \c EVP_Cipher* and \c HMAC_* functions of the
+ * OpenSSL library to perform the actual security operations.
+ * 
+ * If an error occurs during processing, then the \a buf %buffer is set to
+ * empty.
+ * 
+ * @param buf          - The %buffer containing the packet received from a
+ *                       remote OpenVPN peer on which to perform security
+ *                       operations.
+ * @param work         - A working %buffer.
+ * @param opt          - The security parameter state for this VPN tunnel.
+ * @param frame        - The packet geometry parameters for this VPN
+ *                       tunnel.
+ * 
+ * @return
+ * @li True, if the packet was authenticated and decrypted successfully.
+ * @li False, if an error occurred. \n On return, the \a buf argument will
+ *     point to the resulting %buffer.  This %buffer will either contain
+ *     the plaintext packet ready for further processing, or be empty if
+ *     an error occurred.
+ */
 bool openvpn_decrypt (struct buffer *buf, struct buffer work,
 		      const struct crypto_options *opt,
 		      const struct frame* frame);
 
+/** @} name Functions for performing security operations on data channel packets */
+
 
 void crypto_adjust_frame_parameters(struct frame *frame,
 				    const struct key_type* kt,

75 lines not on this page · raw message

new file mode 100644
index 0000000..dd3a41c
@@ -0,0 +1,105 @@
+/*
+ *  OpenVPN -- An application to securely tunnel IP networks
+ *             over a single TCP/UDP port, with support for SSL/TLS-based
+ *             session authentication and key exchange,
+ *             packet encryption, packet authentication, and
+ *             packet compression.
+ *
+ *  Copyright (C) 2010 Fox Crypto B.V. <[email protected]...>
+ *
+ *
+ *  This program is free software; you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License version 2
+ *  as published by the Free Software Foundation.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License
+ *  along with this program (see the file COPYING included with this
+ *  distribution); if not, write to the Free Software Foundation, Inc.,
+ *  59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ */
+
+/**
+ * @file
+ * Control Channel TLS module documentation file.
+ */
+
+/**
+ * @defgroup control_tls Control Channel TLS module
+ * 
+ * This module provides secure encapsulation of control channel messages
+ * exchanged between OpenVPN peers.
+ * 
+ * The Control Channel TLS module uses the Transport Layer Security (TLS)
+ * protocol to provide an encrypted communication channel between the
+ * local OpenVPN process and a remote peer.  This protocol simultaneously
+ * offers certificate-based authentication of the communicating parties.
+ * 
+ * @par This module's roles
+ * The Control Channel TLS module is essential for the security of any
+ * OpenVPN-based system.  On the one hand, it performs the security
+ * operations necessary to protect control channel messages exchanged
+ * between OpenVPN peers.  On the other hand, before the control and data
+ * channels are even setup, it controls the exchange of certificates and
+ * verification of the remote's identity during negotiation of VPN
+ * tunnels.
+ * 
+ * @par
+ * The former role is described below.  The latter is described in the
+ * documentation for the \c verify_callback() function.
+ * 
+ * @par
+ * In other words, this module takes care of the confidentiality and
+ * integrity of data channel communications, and the authentication of
+ * both the communicating parties and the control channel messages
+ * exchanged.
+ * 
+ * @par Initialization and cleanup
+ * Because of the one-to-one relationship between control channel TLS
+ * state and \c key_state structures, the initialization and cleanup of an
+ * instance of the Control Channel TLS module's state happens within the
+ * \c key_state_init() and \c key_state_free() functions.  In other words,
+ * each \c key_state object contains exactly one OpenSSL SSL-BIO object,
+ * which is initialized and cleaned up together with the rest of the \c
+ * key_state object.
+ * 
+ * @par Packet processing functions
+ * This object behaves somewhat like a black box with a ciphertext and a
+ * plaintext I/O port. Its interaction with OpenVPN's control channel
+ * during operation takes place within the \c tls_process() function of
+ * the \link control_processor Control Channel Processor\endlink.  The
+ * following functions are available for processing packets:
+ * - If ciphertext received from the remote peer is available in the \link
+ *   reliable Reliability Layer\endlink:
+ *   - Insert it into the ciphertext-side of the SSL-BIO.
+ *   - Use function: \c key_state_write_ciphertext()
+ * - If ciphertext can be extracted from the ciphertext-side of the
+ *   SSL-BIO:
+ *   - Pass it to the \link reliable Reliability Layer\endlink for sending
+ *     to the remote peer.
+ *   - Use function: \c key_state_read_ciphertext()
+ * - If plaintext can be extracted from the plaintext-side of the SSL-BIO:
+ *   - Pass it on to the \link control_processor Control Channel
+ *     Processor\endlink for local processing.
+ *   - Use function: \c key_state_read_plaintext()
+ * - If plaintext from the \link control_processor Control Channel
+ *   Processor\endlink is available to be sent to the remote peer:
+ *   - Insert it into the plaintext-side of the SSL-BIO.
+ *   - Use function: \c key_state_write_plaintext() or \c
+ *     key_state_write_plaintext_const()
+ * 
+ * @par Transport Layer Security protocol implementation
+ * This module uses the OpenSSL library's implementation of the TLS
+ * protocol in the form of an OpenSSL SSL-BIO object.
+ * 
+ * @par
+ * For more information on the OpenSSL library's BIO objects, please see:
+ *  - OpenSSL's generic BIO objects:
+ *    http://www.openssl.org/docs/crypto/bio.html
+ *  - OpenSSL's SSL-BIO object:
+ *    http://www.openssl.org/docs/crypto/BIO_f_ssl.html
+ */

148 lines not on this page · raw message

401 lines not on this page · raw message

619 lines not on this page · raw message

new file mode 100644
index 0000000..0296b27
@@ -0,0 +1,92 @@
+/*
+ *  OpenVPN -- An application to securely tunnel IP networks
+ *             over a single TCP/UDP port, with support for SSL/TLS-based
+ *             session authentication and key exchange,
+ *             packet encryption, packet authentication, and
+ *             packet compression.
+ *
+ *  Copyright (C) 2010 Fox Crypto B.V. <[email protected]...>
+ *
+ *
+ *  This program is free software; you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License version 2
+ *  as published by the Free Software Foundation.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License
+ *  along with this program (see the file COPYING included with this
+ *  distribution); if not, write to the Free Software Foundation, Inc.,
+ *  59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ */
+
+/**
+ * @file Data Channel Compression module documentation file.
+ */
+
+/**
+ * @defgroup compression Data Channel Compression module
+ * 
+ * This module offers compression of data channel packets.
+ * 
+ * @par State structures
+ * The Data Channel Compression module stores its internal state in a \c
+ * lzo_compress_workspace structure.  This state includes flags which
+ * control the module's behavior and preallocated working memory.  One
+ * such structure is present for each VPN tunnel, and is stored in the \c
+ * context.c2.lzo_compwork of the \c context associated with that VPN
+ * tunnel.
+ * 
+ * @par Initialization and cleanup
+ * Every time a new \c lzo_compress_workspace is needed, it must be
+ * initialized using the \c lzo_compress_init() function.  Similarly,
+ * every time a \c lzo_compress_workspace is no longer needed, it must be
+ * cleaned up using the \c lzo_compress_uninit() function.  These
+ * functions take care of the allocation and freeing of internal working
+ * memory, but not of the \c lzo_compress_workspace structures themselves.
+ * 
+ * @par
+ * Because of the one-to-one relationship between \c
+ * lzo_compress_workspace structures and VPN tunnels, the above-mentioned
+ * initialization and cleanup functions are called directly from the \c
+ * init_instance() and \c close_instance() functions, which control the
+ * initialization and cleanup of VPN tunnel instances and their associated
+ * \c context structures.
+ * 
+ * @par Packet processing functions
+ * This module receives data channel packets from the \link data_control
+ * Data Channel Control module\endlink and processes them according to the
+ * settings of the packet's VPN tunnel.  The \link data_control Data
+ * Channel Control module\endlink uses the following interface functions:
+ * - For packets which will be sent to a remote OpenVPN peer: \c
+ *   lzo_compress()
+ * - For packets which have been received from a remote OpenVPN peer: \c
+ *   lzo_decompress()
+ * 
+ * @par Settings that control this module's activity
+ * Whether or not the Data Channel Compression module is active depends on
+ * the compile-time \c USE_LZO preprocessor macro and the runtime flags
+ * stored in \c lzo_compress_workspace.flags of the associated VPN tunnel.
+ * The latter are initialized from \c options.lzo, which gets its value
+ * from the process's configuration sources, such as its configuration
+ * file or command line %options.
+ * 
+ * @par Adaptive compression
+ * The compression module supports adaptive compression.  If this feature
+ * is enabled, the compression routines monitor their own performance and
+ * turn compression on or off depending on whether it is leading to
+ * significantly reduced payload size.
+ * 
+ * @par Compression algorithms
+ * This module uses the Lempel-Ziv-Oberhumer (LZO) compression algorithms.
+ * These offer lossless compression and are designed for high-performance
+ * decompression.  This module uses the external \c lzo library's
+ * implementation of the algorithms.
+ * 
+ * @par
+ * For more information on the LZO library, see:\n
+ * http://www.oberhumer.com/opensource/lzo/
+ */

index 3d6aa5a..64945d0 100644
@@ -22,6 +22,10 @@
  *  59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
 
+/**
+ * @file Data Channel Compression module function definitions.
+ */
+
 #include "syshead.h"
 
 #ifdef USE_LZO

@@ -33,7 +37,13 @@
 #include "memdbg.h"
 
 #ifndef LZO_STUB
-
+/**
+ * Perform adaptive compression housekeeping.
+ * 
+ * @param ac the adaptive compression state structure.
+ * 
+ * @return 
+ */
 static bool
 lzo_adaptive_compress_test (struct lzo_adaptive_compress *ac)
 {

@@ -142,10 +152,6 @@ lzo_compression_enabled (struct lzo_compress_workspace *lzowork)
   return false;
 }
 
-/* Magic numbers to tell our peer if we compressed or not */
-#define YES_COMPRESS 0x66
-#define NO_COMPRESS  0xFA
-
 void
 lzo_compress (struct buffer *buf, struct buffer work,
 	      struct lzo_compress_workspace *lzowork,

@@ -281,9 +287,6 @@ lzo_modify_flags (struct lzo_compress_workspace *lzowork, unsigned int flags)
   lzowork->flags = flags;
 }
 
-/*
- * Print statistics
- */
 void lzo_print_stats (const struct lzo_compress_workspace *lzo_compwork, struct status_output *so)
 {
   ASSERT (lzo_compwork->defined);

338 lines not on this page · raw message

new file mode 100644
index 0000000..9877d8c
@@ -0,0 +1,49 @@
+/*
+ *  OpenVPN -- An application to securely tunnel IP networks
+ *             over a single TCP/UDP port, with support for SSL/TLS-based
+ *             session authentication and key exchange,
+ *             packet encryption, packet authentication, and
+ *             packet compression.
+ *
+ *  Copyright (C) 2010 Fox Crypto B.V. <[email protected]...>
+ *
+ *
+ *  This program is free software; you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License version 2
+ *  as published by the Free Software Foundation.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License
+ *  along with this program (see the file COPYING included with this
+ *  distribution); if not, write to the Free Software Foundation, Inc.,
+ *  59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ */
+
+/**
+ * @file
+ * Reliability Layer module documentation file.
+ */
+
+/**
+ * @defgroup reliable Reliability Layer module
+ * 
+ * The Reliability Layer is part of OpenVPN's control channel.  It
+ * provides a reliable and sequential transport mechanism for control
+ * channel messages between OpenVPN peers.  This module forms the
+ * interface between the \link external_multiplexer External
+ * Multiplexer\endlink and the \link control_tls Control Channel TLS
+ * module\endlink.
+ * 
+ * @par UDP or TCP as VPN tunnel transport
+ * 
+ * This is especially important when OpenVPN is configured to communicate
+ * over UDP, because UDP does not offer a reliable and sequential
+ * transport.  OpenVPN endpoints can also communicate over TCP which does
+ * provide a reliable and sequential transport.  In both cases, using UDP
+ * or TCP as an external transport, the internal Reliability Layer is
+ * active.
+ */

510 lines not on this page · raw message

index 1fe3c08..06d5e84 100644
@@ -42,14 +42,30 @@
 #define BUF_INIT_TRACKING
 #endif
 
-/* basic buffer class for OpenVPN */
-
+/**************************************************************************/
+/**
+ * Wrapper structure for dynamically allocated memory.
+ * 
+ * The actual content stored in a \c buffer structure starts at the memory
+ * location \c buffer.data \c + \c buffer.offset, and has a length of \c
+ * buffer.len bytes.  This, together with the space available before and
+ * after the content, is represented in the pseudocode below:
+@code
+uint8_t *content_start    = buffer.data + buffer.offset;
+uint8_t *content_end      = buffer.data + buffer.offset + buffer.len;
+int      prepend_capacity = buffer.offset;
+int      append_capacity  = buffer.capacity - (buffer.offset + buffer.len);
+@endcode
+ */
 struct buffer
 {
-  int capacity;	   /* size of buffer allocated by malloc */
-  int offset;	   /* data starts at data + offset, offset > 0 to allow for efficient prepending */
-  int len;	   /* length of data that starts at data + offset */
-  uint8_t *data;
+  int capacity;                 /**< Size in bytes of memory allocated by
+                                 *   \c malloc(). */
+  int offset;                   /**< Offset in bytes of the actual content
+                                 *   within the allocated memory. */
+  int len;                      /**< Length in bytes of the actual content
+                                 *   within the allocated memory. */
+  uint8_t *data;                /**< Pointer to the allocated memory. */
 
 #ifdef BUF_INIT_TRACKING
   const char *debug_file;

@@ -57,18 +73,41 @@ struct buffer
 #endif
 };
 
-/* for garbage collection */
 
+/**************************************************************************/
+/**
+ * Garbage collection entry for one dynamically allocated block of memory.
+ * 
+ * This structure represents one link in the linked list contained in a \c
+ * gc_arena structure.  Each time the \c gc_malloc() function is called,
+ * it allocates \c sizeof(gc_entry) + the requested number of bytes.  The
+ * \c gc_entry is then stored as a header in front of the memory address
+ * returned to the caller.
+ */
 struct gc_entry
 {
-  struct gc_entry *next;
+  struct gc_entry *next;        /**< Pointer to the next item in the
+                                 *   linked list. */
 };
 
+
+/**
+ * Garbage collection arena used to keep track of dynamically allocated
+ * memory.
+ * 
+ * This structure contains a linked list of \c gc_entry structures.  When
+ * a block of memory is allocated using the \c gc_malloc() function, the
+ * allocation is registered in the function's \c gc_arena argument.  All
+ * the dynamically allocated memory registered in a \c gc_arena can be
+ * freed using the \c gc_free() function.
+ */
 struct gc_arena
 {
-  struct gc_entry *list;
+  struct gc_entry *list;        /**< First element of the linked list of
+                                 *   \c gc_entry structures. */
 };
 
+
 #define BPTR(buf)  (buf_bptr(buf))
 #define BEND(buf)  (buf_bend(buf))
 #define BLAST(buf) (buf_blast(buf))

99 lines not on this page · raw message

new file mode 100644
index 0000000..e7e9c1e
@@ -0,0 +1,96 @@
+/*
+ *  OpenVPN -- An application to securely tunnel IP networks
+ *             over a single TCP/UDP port, with support for SSL/TLS-based
+ *             session authentication and key exchange,
+ *             packet encryption, packet authentication, and
+ *             packet compression.
+ *
+ *  Copyright (C) 2010 Fox Crypto B.V. <[email protected]...>
+ *
+ *
+ *  This program is free software; you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License version 2
+ *  as published by the Free Software Foundation.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License
+ *  along with this program (see the file COPYING included with this
+ *  distribution); if not, write to the Free Software Foundation, Inc.,
+ *  59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ */
+
+/**
+ * @file
+ * Data Channel Fragmentation module documentation file.
+ */
+
+/**
+ * @defgroup fragmentation Data Channel Fragmentation module
+ * 
+ * The Data Channel Fragmentation module offers fragmentation of data
+ * channel packets.
+ * 
+ * @par State structures
+ * The Data Channel Fragmentation module stores its internal state in a \c
+ * fragment_master structure.  One such structure is present for each VPN
+ * tunnel, and is stored in \c context.c2.fragment of the \c context
+ * associated with that VPN tunnel.
+ * 
+ * @par
+ * The \c fragment_master structure contains one \c fragment_list
+ * structure \c fragment_master.incoming.  This is a list of \c fragment
+ * structures, each of which can store the parts of one fragmented packet
+ * while it is being reassembled.  The \c fragment_master structure also
+ * contains one \c buffer called \c fragment_master.outgoing, in which a
+ * data channel large packet to be sent to a remote OpenVPN peer can be
+ * broken up into parts to be sent one by one.
+ * 
+ * @par Initialization and cleanup
+ * Every time a new \c fragment_master is needed, it must be allocated and
+ * initialized by the \c fragment_init() function.  Similarly, every time
+ * a \c fragment_master is no longer needed, it must be cleaned up using
+ * the \c fragment_free() function.  These functions take care of the
+ * allocation and freeing of the \c fragment_master structure itself and
+ * all internal memory required for the use of that structure.  Note that
+ * this behavior is different from that displayed by the \link compression
+ * Data Channel Compression module\endlink.
+ * 
+ * @par
+ * Because of the one-to-one relationship between \c fragment_master
+ * structures and VPN tunnels, the above-mentioned initialization and
+ * cleanup functions are called directly from the \c init_instance() and
+ * \c close_instance() functions, which control the initialization and
+ * cleanup of VPN tunnel instances and their associated \c context
+ * structures.
+ * 
+ * @par Packet processing functions
+ * This module receives data channel packets from the \link data_control
+ * Data Channel Control module\endlink and processes them according to the
+ * settings of the packet's VPN tunnel.  The \link data_control Data
+ * Channel Control module\endlink uses the following interface functions:
+ * - For packets which will be sent to a remote OpenVPN peer: \c
+ *   fragment_outgoing() \n This function inspects data channel packets as
+ *   they are being made ready to be sent as VPN tunnel packets to a
+ *   remote OpenVPN peer.  If a packet's size is larger than its
+ *   destination VPN tunnel's maximum transmission unit (MTU), then this
+ *   module breaks that packet up into smaller parts, each of which is
+ *   smaller than or equal to the VPN tunnel's MTU.  See \c
+ *   fragment_outgoing() for details.
+ * - For packets which have been received from a remote OpenVPN peer: \c
+ *   fragment_incoming() \n This function inspects data channel packets
+ *   that have been received from a remote OpenVPN peer through a VPN
+ *   tunnel.  It reads the fragmentation header of the packet, and
+ *   depending on its value performs the appropriate action.  See \c
+ *   fragment_incoming() for details.
+ * 
+ * @par Settings that control this module's activity
+ * Whether the Data Channel Fragmentation module is active or not depends
+ * on the compile-time \c ENABLE_FRAGMENT preprocessor macro and the
+ * runtime flag \c options.fragment, which gets its value from the
+ * process's configuration sources, such as the configuration file and
+ * commandline %options.
+ */

527 lines not on this page · raw message

new file mode 100644
index 0000000..506f8ab
@@ -0,0 +1,189 @@
+/*
+ *  OpenVPN -- An application to securely tunnel IP networks
+ *             over a single TCP/UDP port, with support for SSL/TLS-based
+ *             session authentication and key exchange,
+ *             packet encryption, packet authentication, and
+ *             packet compression.
+ *
+ *  Copyright (C) 2010 Fox Crypto B.V. <[email protected]...>
+ *
+ *
+ *  This program is free software; you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License version 2
+ *  as published by the Free Software Foundation.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License
+ *  along with this program (see the file COPYING included with this
+ *  distribution); if not, write to the Free Software Foundation, Inc.,
+ *  59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ */
+
+/**
+ * @file
+ * Control Channel Processor module documentation file.
+ */
+
+/**
+ * @defgroup control_processor Control Channel Processor module
+ * 
+ * This module controls the setup and maintenance of VPN tunnels and the
+ * associated security parameters.
+ * 
+ * @par This module's role
+ * The Control Channel Processor module lies at the core of OpenVPN's
+ * activities.  It handles the setup of new VPN tunnels, the negotiation
+ * of data channel security parameters, the managing of active VPN
+ * tunnels, and finally the cleanup of expired VPN tunnels.
+ * 
+ * @par State structures
+ * A large amount of VPN tunnel state information must be stored within an
+ * OpenVPN process.  A wide variety of container structures are used by
+ * this module for that purpose.  Several of these structures are listed
+ * below, and the function of the first three VPN tunnel state containers
+ * is described in more detail later.
+ *  - VPN tunnel state containers:
+ *     - \c tls_multi, security parameter state for a single VPN tunnel.
+ *       Contains three instances of the \c tls_session structure.
+ *     - \c tls_session, security parameter state of a single session
+ *       within a VPN tunnel.  Contains two instances of the \c key_state
+ *       structure.
+ *     - \c key_state, security parameter state of one TLS and data
+ *       channel %key set.
+ *  - Data channel security parameter containers:
+ *     - \c key_ctx_bi, container for two sets of OpenSSL cipher and/or
+ *       HMAC context (both directions).  Contains two instances of the \c
+ *       key_ctx structure.
+ *     - \c key_ctx, container for one set of OpenSSL cipher and/or HMAC
+ *       context (one directions.
+ *  - Key material containers:
+ *     - \c key2, container for two sets of cipher and/or HMAC %key
+ *       material (both directions).  Contains two instances of the \c key
+ *       structure.
+ *     - \c key, container for one set of cipher and/or HMAC %key material
+ *       (one direction).
+ *     - \c key_direction_state, ordering of %key material within the \c
+ *       key2.key array.
+ *  - Key method 2 random material containers:
+ *     - \c key_source2, container for both halves of random material used
+ *       for %key method 2.  Contains two instances of the \c key_source
+ *       structure.
+ *     - \c key_source, container for one half of random material used for
+ *       %key method 2.
+ * 
+ * @par The life of a \c tls_multi object
+ * A \c tls_multi structure contains all the security parameter state
+ * information related to the control and data channels of one VPN tunnel.
+ * Its life cycle can be summarized as follows:
+ *  -# Initialization: \c tls_multi_init() and \c
+ *     tls_multi_init_finalize(), which are called (indirectly) from \c
+ *     init_instance() when initializing a new \c context structure.
+ *     - Initializes a \c tls_multi structure.
+ *     - Allocates the three \c tls_session objects contained by the \c
+ *       tls_multi structure, and initializes as appropriate.
+ *  -# Management: \c tls_multi_process() and \c tls_pre_decrypt()
+ *     - If a new session is initiated by the remote peer, then \c
+ *       tls_pre_decrypt() starts the new session negotiation in the
+ *       un-trusted \c tls_session.
+ *     - If the, as yet, un-trusted \c tls_session authenticates
+ *       successfully, then \c tls_multi_process() moves it so as to be
+ *       the active \c tls_session.
+ *     - If an error occurs during processing of a \c key_state object,
+ *       then \c tls_multi_process() cleans up and initializes the
+ *       associated \c tls_session object.  If the error occurred in the
+ *       active \c key_state of the active \c tls_session and the
+ *       lame-duck \c key_state of that \c tls_session has not yet
+ *       expired, it is preserved as fallback.
+ *  -# Cleanup: \c tls_multi_free(), which is called (indirectly) from \c
+ *     close_instance() when cleaning up a \c context structure.
+ *     - Cleans up a \c tls_multi structure.
+ *     - Cleans up the three \c tls_session objects contained by the \c
+ *       tls_multi structure.
+ * 
+ * @par The life of a \c tls_session object
+ * A \c tls_session structure contains the state information related to an
+ * active and a lame-duck \c key_state.  Its life cycle can be summarized
+ * as follows:
+ *  -# Initialization: \c tls_session_init()
+ *     - Initializes a \c tls_session structure.
+ *     - Initializes the primary \c key_state by calling \c
+ *       key_state_init().
+ *  -# Renegotiation: \c key_state_soft_reset()
+ *     - Cleans up the old lame-duck \c key_state by calling \c
+ *       key_state_free().
+ *     - Moves the old primary \c key_state to be the new lame-duck \c
+ *       key_state.
+ *     - Initializes a new primary \c key_state by calling \c
+ *       key_state_init().
+ *  -# Cleanup: \c tls_session_free()
+ *     - Cleans up a \c tls_session structure.
+ *     - Cleans up all \c key_state objects associated with the session by
+ *       calling \c key_state_free() for each.
+ * 
+ * @par The life of a \c key_state object
+ * A \c key_state structure represents one control and data channel %key
+ * set.  It contains an OpenSSL TLS object that encapsulates the control
+ * channel, and the data channel security parameters needed by the \link
+ * data_crypto Data Channel Crypto module\endlink to perform cryptographic
+ * operations on data channel packets.  Its life cycle can be summarized
+ * as follows:
+ *  -# Initialization: \c key_state_init()
+ *     - Initializes a \c key_state structure.
+ *     - Creates a new OpenSSL TLS object to encapsulate this new control
+ *       channel session.
+ *     - Sets \c key_state.state to \c S_INITIAL.
+ *     - Allocates several internal buffers.
+ *     - Initializes new reliability layer structures for this key set.
+ *  -# Negotiation: \c tls_process()
+ *     - The OpenSSL TLS object negotiates a TLS session between itself
+ *       and the remote peer's TLS object.
+ *     - Key material is generated and exchanged through the TLS session
+ *       between OpenVPN peers.
+ *     - Both peers initialize their data channel cipher and HMAC key
+ *       contexts.
+ *     - On successful negotiation, the \c key_state.state will progress
+ *       from \c S_INITIAL to \c S_ACTIVE and \c S_NORMAL.
+ *  -# Active tunneling: \link data_crypto Data Channel Crypto
+ *     module\endlink
+ *     - Data channel packet to be sent to a remote OpenVPN peer:
+ *        - \c tls_pre_encrypt() loads the security parameters from the \c
+ *          key_state into a \c crypto_options structure.
+ *        - \c openvpn_encrypt() uses the \c crypto_options to an encrypt
+ *          and HMAC sign the data channel packet.
+ *     - Data channel packet received from a remote OpenVPN peer:
+ *        - \c tls_pre_decrypt() loads the security parameters from the \c
+ *          key_state into a \c crypto_options structure.
+ *        - \c openvpn_encrypt() uses the \c crypto_options to
+ *          authenticate and decrypt the data channel packet.
+ *  -# Cleanup: \c key_state_free()
+ *     - Cleans up a \c key_state structure together with its OpenSSL TLS
+ *       object, key material, internal buffers, and reliability layer
+ *       structures.
+ * 
+ * @par Control functions
+ * The following two functions drive the Control Channel Processor's
+ * activities.
+ *  - \c tls_multi_process(), iterates through the \c tls_session objects
+ *    within a given \c tls_multi of a VPN tunnel, and calls \c
+ *    tls_process() for each \c tls_session which is being set up, is
+ *    already active, or is busy expiring.
+ *  - \c tls_process(), performs the Control Channel Processor module's
+ *    core handling of received control channel messages, and generates
+ *    appropriate messages to be sent.
+ * 
+ * @par Functions which control data channel key generation
+ *  - Key method 1 key exchange functions:
+ *     - \c key_method_1_write(), generates and processes key material to
+ *       be sent to the remote OpenVPN peer.
+ *     - \c key_method_1_read(), processes key material received from the
+ *       remote OpenVPN peer.
+ *  - Key method 2 key exchange functions:
+ *     - \c key_method_2_write(), generates and processes key material to
+ *       be sent to the remote OpenVPN peer.
+ *     - \c key_method_2_read(), processes key material received from the
+ *       remote OpenVPN peer.
+ */

103 lines not on this page · raw message

67 lines not on this page · raw message

46 lines not on this page · raw message

44 lines not on this page · raw message

162 lines not on this page · raw message

199 lines not on this page · raw message

155 lines not on this page · raw message

187 lines not on this page · raw message

index 3585af4..0b5308d 100644
@@ -60,8 +60,17 @@ void multi_tcp_instance_specific_free (struct multi_instance *mi);
 
 void multi_tcp_link_out_deferred (struct multi_context *m, struct multi_instance *mi);
 
+
+/**************************************************************************/
+/**
+ * Main event loop for OpenVPN in TCP server mode.
+ * @ingroup eventloop
+ * 
+ * @param top - Top-level context structure.
+ */
 void tunnel_server_tcp (struct context *top);
 
+
 void multi_tcp_delete_event (struct multi_tcp *mtcp, event_t event);
 
 #endif

75 lines not on this page · raw message

index a478b29..1e17299 100644
@@ -199,9 +199,17 @@ p2mp_iow_flags (const struct multi_context *m)
   return flags;
 }
 
-/*
- * Top level event loop for single-threaded operation.
- * UDP mode.
+
+/**************************************************************************/
+/**
+ * Main event loop for OpenVPN in UDP server mode.
+ * @ingroup eventloop
+ * 
+ * This function implements OpenVPN's main event loop for UDP server mode.
+ *  At this time, OpenVPN does not yet support multithreading.  This
+ * function's name is therefore slightly misleading.
+ * 
+ * @param top - Top-level context structure.
  */
 static void
 tunnel_server_udp_single_threaded (struct context *top)

index dc9cfde..5d347fa 100644
@@ -34,8 +34,37 @@
 struct context;
 struct multi_context;
 
+
+/**************************************************************************/
+/**
+ * Main event loop wrapper function for OpenVPN in UDP server mode.
+ * @ingroup eventloop
+ * 
+ * This function simply calls \c tunnel_server_udp_single_threaded().
+ * 
+ * @param top          - Top-level context structure.
+ */
 void tunnel_server_udp (struct context *top);
 
+
+/**************************************************************************/
+/**
+ * Get, and if necessary create, the multi_instance associated with a
+ * packet's source address.
+ * @ingroup external_multiplexer
+ * 
+ * This function extracts the source address of a recently read packet
+ * from \c m->top.c2.from and uses that source address as a hash key for
+ * the hash table \c m->hash.  If an entry exists, this function returns
+ * it.  If no entry exists, this function handles its creation, and if
+ * successful, returns the newly created instance.
+ * 
+ * @param m            - The single multi_context structure.
+ * 
+ * @return A pointer to a multi_instance if one already existed for the
+ *     packet's source address or if one was a newly created successfully.
+ *      NULL if one did not yet exist and a new one was not created.
+ */
 struct multi_instance *multi_get_create_instance_udp (struct multi_context *m);
 
 #endif

233 lines not on this page · raw message

index 99b343b..faf2858 100644
@@ -42,6 +42,16 @@ process_signal_p2p (struct context *c)
   return process_signal (c);
 }
 
+
+
+/**************************************************************************/
+/**
+ * Main event loop for OpenVPN in client mode, where only one VPN tunnel
+ * is active.
+ * @ingroup eventloop
+ * 
+ * @param c - The context structure of the single active VPN tunnel.
+ */
 static void
 tunnel_point_to_point (struct context *c)
 {

@@ -90,6 +100,27 @@ tunnel_point_to_point (struct context *c)
 
 #undef PROCESS_SIGNAL_P2P
 
+
+/**************************************************************************/
+/**
+ * OpenVPN's main init-run-cleanup loop.
+ * @ingroup eventloop
+ * 
+ * This function contains the two outer OpenVPN loops.  Its structure is
+ * as follows:
+ *  - Once-per-process initialization.
+ *  - Outer loop, run at startup and then once per \c SIGHUP:
+ *    - Level 1 initialization
+ *    - Inner loop, run at startup and then once per \c SIGUSR1:
+ *      - Call event loop function depending on client or server mode:
+ *        - \c tunnel_point_to_point()
+ *        - \c tunnel_server()
+ *    - Level 1 cleanup
+ *  - Once-per-process cleanup.
+ * 
+ * @param argc - Commandline argument count.
+ * @param argv - Commandline argument values.
+ */
 int
 main (int argc, char *argv[])
 {

238 lines not on this page · raw message

deleted file mode 100644
index 0296b27..0000000
@@ -1,92 +0,0 @@
-/*
- *  OpenVPN -- An application to securely tunnel IP networks
- *             over a single TCP/UDP port, with support for SSL/TLS-based
- *             session authentication and key exchange,
- *             packet encryption, packet authentication, and
- *             packet compression.
- *
- *  Copyright (C) 2010 Fox Crypto B.V. <[email protected]...>
- *
- *
- *  This program is free software; you can redistribute it and/or modify
- *  it under the terms of the GNU General Public License version 2
- *  as published by the Free Software Foundation.
- *
- *  This program is distributed in the hope that it will be useful,
- *  but WITHOUT ANY WARRANTY; without even the implied warranty of
- *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- *  GNU General Public License for more details.
- *
- *  You should have received a copy of the GNU General Public License
- *  along with this program (see the file COPYING included with this
- *  distribution); if not, write to the Free Software Foundation, Inc.,
- *  59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
- */
-
-/**
- * @file Data Channel Compression module documentation file.
- */
-
-/**
- * @defgroup compression Data Channel Compression module
- * 
- * This module offers compression of data channel packets.
- * 
- * @par State structures
- * The Data Channel Compression module stores its internal state in a \c
- * lzo_compress_workspace structure.  This state includes flags which
- * control the module's behavior and preallocated working memory.  One
- * such structure is present for each VPN tunnel, and is stored in the \c
- * context.c2.lzo_compwork of the \c context associated with that VPN
- * tunnel.
- * 
- * @par Initialization and cleanup
- * Every time a new \c lzo_compress_workspace is needed, it must be
- * initialized using the \c lzo_compress_init() function.  Similarly,
- * every time a \c lzo_compress_workspace is no longer needed, it must be
- * cleaned up using the \c lzo_compress_uninit() function.  These
- * functions take care of the allocation and freeing of internal working
- * memory, but not of the \c lzo_compress_workspace structures themselves.
- * 
- * @par
- * Because of the one-to-one relationship between \c
- * lzo_compress_workspace structures and VPN tunnels, the above-mentioned
- * initialization and cleanup functions are called directly from the \c
- * init_instance() and \c close_instance() functions, which control the
- * initialization and cleanup of VPN tunnel instances and their associated
- * \c context structures.
- * 
- * @par Packet processing functions
- * This module receives data channel packets from the \link data_control
- * Data Channel Control module\endlink and processes them according to the
- * settings of the packet's VPN tunnel.  The \link data_control Data
- * Channel Control module\endlink uses the following interface functions:
- * - For packets which will be sent to a remote OpenVPN peer: \c
- *   lzo_compress()
- * - For packets which have been received from a remote OpenVPN peer: \c
- *   lzo_decompress()
- * 
- * @par Settings that control this module's activity
- * Whether or not the Data Channel Compression module is active depends on
- * the compile-time \c USE_LZO preprocessor macro and the runtime flags
- * stored in \c lzo_compress_workspace.flags of the associated VPN tunnel.
- * The latter are initialized from \c options.lzo, which gets its value
- * from the process's configuration sources, such as its configuration
- * file or command line %options.
- * 
- * @par Adaptive compression
- * The compression module supports adaptive compression.  If this feature
- * is enabled, the compression routines monitor their own performance and
- * turn compression on or off depending on whether it is leading to
- * significantly reduced payload size.
- * 
- * @par Compression algorithms
- * This module uses the Lempel-Ziv-Oberhumer (LZO) compression algorithms.
- * These offer lossless compression and are designed for high-performance
- * decompression.  This module uses the external \c lzo library's
- * implementation of the algorithms.
- * 
- * @par
- * For more information on the LZO library, see:\n
- * http://www.oberhumer.com/opensource/lzo/
- */

189 lines not on this page · raw message

105 lines not on this page · raw message

103 lines not on this page · raw message

75 lines not on this page · raw message

67 lines not on this page · raw message

46 lines not on this page · raw message

96 lines not on this page · raw message

44 lines not on this page · raw message

148 lines not on this page · raw message

162 lines not on this page · raw message

99 lines not on this page · raw message

199 lines not on this page · raw message

49 lines not on this page · raw message

155 lines not on this page · raw message

92 lines not on this page · raw message

189 lines not on this page · raw message

105 lines not on this page · raw message

103 lines not on this page · raw message

75 lines not on this page · raw message

67 lines not on this page · raw message

46 lines not on this page · raw message

96 lines not on this page · raw message

44 lines not on this page · raw message

148 lines not on this page · raw message

162 lines not on this page · raw message

99 lines not on this page · raw message

145 lines not on this page · raw message

49 lines not on this page · raw message

155 lines not on this page · raw message