summaryrefslogtreecommitdiff
path: root/app/openvpn/doc/doxygen
diff options
context:
space:
mode:
authorParménides GV <parmegv@sdf.org>2014-04-09 17:07:48 +0200
committerParménides GV <parmegv@sdf.org>2014-04-09 17:15:17 +0200
commit51ff5a18f1f074e27e97d822745551a7e8fa068d (patch)
tree402e7dd42778a218635bb29a4c2dff93ea7f6525 /app/openvpn/doc/doxygen
parent910b0e1746ab3f63e63808b198ad51fec5b635e5 (diff)
parentb5ba0abc1610dd4bf573ebcabc5e8f6ab0c9528f (diff)
Merge branch 'feature/implement-gradle-build-system-#4676' into develop
Diffstat (limited to 'app/openvpn/doc/doxygen')
-rw-r--r--app/openvpn/doc/doxygen/doc_compression.h92
-rw-r--r--app/openvpn/doc/doxygen/doc_control_processor.h189
-rw-r--r--app/openvpn/doc/doxygen/doc_control_tls.h105
-rw-r--r--app/openvpn/doc/doxygen/doc_data_control.h103
-rw-r--r--app/openvpn/doc/doxygen/doc_data_crypto.h75
-rw-r--r--app/openvpn/doc/doxygen/doc_eventloop.h67
-rw-r--r--app/openvpn/doc/doxygen/doc_external_multiplexer.h46
-rw-r--r--app/openvpn/doc/doxygen/doc_fragmentation.h96
-rw-r--r--app/openvpn/doc/doxygen/doc_internal_multiplexer.h44
-rw-r--r--app/openvpn/doc/doxygen/doc_key_generation.h153
-rw-r--r--app/openvpn/doc/doxygen/doc_mainpage.h162
-rw-r--r--app/openvpn/doc/doxygen/doc_memory_management.h99
-rw-r--r--app/openvpn/doc/doxygen/doc_protocol_overview.h199
-rw-r--r--app/openvpn/doc/doxygen/doc_reliable.h49
-rw-r--r--app/openvpn/doc/doxygen/doc_tunnel_state.h155
-rw-r--r--app/openvpn/doc/doxygen/openvpn.doxyfile279
16 files changed, 1913 insertions, 0 deletions
diff --git a/app/openvpn/doc/doxygen/doc_compression.h b/app/openvpn/doc/doxygen/doc_compression.h
new file mode 100644
index 00000000..bdc4a7ed
--- /dev/null
+++ b/app/openvpn/doc/doxygen/doc_compression.h
@@ -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. <openvpn@fox-it.com>
+ *
+ *
+ * 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 ENABLE_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/
+ */
diff --git a/app/openvpn/doc/doxygen/doc_control_processor.h b/app/openvpn/doc/doxygen/doc_control_processor.h
new file mode 100644
index 00000000..072dc372
--- /dev/null
+++ b/app/openvpn/doc/doxygen/doc_control_processor.h
@@ -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. <openvpn@fox-it.com>
+ *
+ *
+ * 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.
+ */
diff --git a/app/openvpn/doc/doxygen/doc_control_tls.h b/app/openvpn/doc/doxygen/doc_control_tls.h
new file mode 100644
index 00000000..aba55f77
--- /dev/null
+++ b/app/openvpn/doc/doxygen/doc_control_tls.h
@@ -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. <openvpn@fox-it.com>
+ *
+ *
+ * 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
+ */
diff --git a/app/openvpn/doc/doxygen/doc_data_control.h b/app/openvpn/doc/doxygen/doc_data_control.h
new file mode 100644
index 00000000..d0f65ba3
--- /dev/null
+++ b/app/openvpn/doc/doxygen/doc_data_control.h
@@ -0,0 +1,103 @@
+/*
+ * 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. <openvpn@fox-it.com>
+ *
+ *
+ * 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 Control module documentation file.
+ */
+
+/**
+ * @defgroup data_control Data Channel Control module
+ *
+ * This module controls the processing of packets as they pass through the
+ * data channel.
+ *
+ * The Data Channel Control module controls the processing of packets as
+ * they pass through the data channel. The processing includes packet
+ * compression, fragmentation, and the performing of security operations
+ * on the packets. This module does not do the processing itself, but
+ * passes the packet to other data channel modules to perform the
+ * appropriate actions.
+ *
+ * Packets can travel in two directions through the data channel. They
+ * can be going to a remote destination which is reachable through a VPN
+ * tunnel, in which case this module prepares them to be sent out through
+ * a VPN tunnel. On the other hand, they can have been received through a
+ * VPN tunnel from a remote OpenVPN peer, in which case this module
+ * retrieves the packet in its original form as it was before entering the
+ * VPN tunnel on the remote OpenVPN peer. How this module processes
+ * packets traveling in the two directions is discussed in more detail
+ * below.
+ *
+ * @par Packets to be sent to a remote OpenVPN peer
+ * This module's main function for processing packets traveling in this
+ * direction is \c encrypt_sign(), which performs the following processing
+ * steps:
+ * - Call the \link compression Data Channel Compression module\endlink to
+ * perform packet compression if necessary.
+ * - Call the \link fragmentation Data Channel Fragmentation
+ * module\endlink to perform packet fragmentation if necessary.
+ * - Call the \link data_crypto Data Channel Crypto module\endlink to
+ * perform the required security operations.
+ *
+ * @par
+ * See the \c encrypt_sign() documentation for details of these
+ * interactions.
+ *
+ * @par
+ * After the above processing is complete, the packet is ready to be sent
+ * to a remote OpenVPN peer as a VPN tunnel packet. The actual sending of
+ * the packet is handled by the \link external_multiplexer External
+ * Multiplexer\endlink.
+ *
+ * @par Packets received from a remote OpenVPN peer
+ * The function that controls how packets traveling in this direction are
+ * processed is \c process_incoming_link(). That function, however, also
+ * performs some of the tasks required for the \link external_multiplexer
+ * External Multiplexer\endlink and is therefore listed as part of that
+ * module, instead of here.
+ *
+ * @par
+ * After the \c process_incoming_link() function has determined that a
+ * received packet is a data channel packet, it performs the following
+ * processing steps:
+ * - Call the \link data_crypto Data Channel Crypto module\endlink to
+ * perform the required security operations.
+ * - Call the \link fragmentation Data Channel Fragmentation
+ * module\endlink to perform packet reassembly if necessary.
+ * - Call the \link compression Data Channel Compression module\endlink to
+ * perform packet decompression if necessary.
+ *
+ * @par
+ * See the \c process_incoming_link() documentation for details of these
+ * interactions.
+ *
+ * @par
+ * After the above processing is complete, the packet is in its original
+ * form again as it was received by the remote OpenVPN peer. It can now
+ * be routed further to its final destination. If that destination is a
+ * locally reachable host, then the \link internal_multiplexer Internal
+ * Multiplexer\endlink will send it there.
+ */
diff --git a/app/openvpn/doc/doxygen/doc_data_crypto.h b/app/openvpn/doc/doxygen/doc_data_crypto.h
new file mode 100644
index 00000000..ee72b8cd
--- /dev/null
+++ b/app/openvpn/doc/doxygen/doc_data_crypto.h
@@ -0,0 +1,75 @@
+/*
+ * 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. <openvpn@fox-it.com>
+ *
+ *
+ * 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 Crypto module documentation file.
+ */
+
+/**
+ * @addtogroup data_crypto Data Channel Crypto module
+ *
+ * The Data Channel Crypto Module performs cryptographic operations on
+ * data channel packets.
+ *
+ * @par Security parameters
+ * This module is merely the user of a VPN tunnel's security parameters.
+ * It does not perform the negotiation and setup of the security
+ * parameters, nor the %key generation involved. These actions are done
+ * by the \link control_processor Control Channel Processor\endlink. This
+ * module receives the appropriate security parameters from that module in
+ * the form of a \c crypto_options structure when they are necessary for
+ * processing a packet.
+ *
+ * @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
+ * security parameters 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 tls_pre_encrypt()
+ * - \c openvpn_encrypt()
+ * - \c tls_post_encrypt()
+ * - For packets which have been received from a remote OpenVPN peer:
+ * - \c tls_pre_decrypt() (documented as part of the \link
+ * external_multiplexer External Multiplexer\endlink)
+ * - \c openvpn_decrypt()
+ *
+ * @par Settings that control this module's activity
+ * Whether or not the Data Channel Crypto module is active depends on the
+ * compile-time \c ENABLE_CRYPTO and \c ENABLE_SSL preprocessor macros. How it
+ * processes packets received from the \link data_control Data Channel
+ * Control module\endlink at runtime depends on the associated \c
+ * crypto_options structure. To perform cryptographic operations, the \c
+ * crypto_options.key_ctx_bi must contain the correct cipher and HMAC
+ * security parameters for the direction the packet is traveling in.
+ *
+ * @par Crypto algorithms
+ * This module uses the crypto algorithm implementations of the external
+ * OpenSSL library. More precisely, it uses the OpenSSL library's \c
+ * EVP_Cipher* and \c HMAC_* set of functions to perform cryptographic
+ * operations on data channel packets.
+ */
diff --git a/app/openvpn/doc/doxygen/doc_eventloop.h b/app/openvpn/doc/doxygen/doc_eventloop.h
new file mode 100644
index 00000000..a860db68
--- /dev/null
+++ b/app/openvpn/doc/doxygen/doc_eventloop.h
@@ -0,0 +1,67 @@
+/*
+ * 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. <openvpn@fox-it.com>
+ *
+ *
+ * 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
+ * Main Event Loop module documentation file.
+ */
+
+/**
+ * @defgroup eventloop Main Event Loop module
+ *
+ * This main event loop module drives the packet processing of OpenVPN.
+ *
+ * OpenVPN is an event driven system. Its activities are driven by a main
+ * event loop, which repeatedly waits for one of several predefined events
+ * to occur, and then calls the appropriate module to handle the event.
+ * The major types of network events that OpenVPN processes are:
+ * - A packet can be read from the external network interface.
+ * - The main event loop activates the \link external_multiplexer
+ * External Multiplexer\endlink to read and process the packet.
+ * - A packet can be read from the virtual tun/tap network interface.
+ * - The main event loop activates the \link internal_multiplexer
+ * Internal Multiplexer\endlink to read and process the packet.
+ * - If a packet is ready to be sent out as a VPN tunnel packet: the
+ * external network interface can be written to.
+ * - The main event loop activates the \link external_multiplexer
+ * External Multiplexer\endlink to send the packet.
+ * - If a packet is ready to be sent to a locally reachable destination:
+ * the virtual tun/tap network interface can be written to.
+ * - The main event loop activates the \link internal_multiplexer
+ * Internal Multiplexer\endlink to send the packet.
+ *
+ * Beside these external events, OpenVPN also processes other types of
+ * internal events. These include scheduled events, such as resending of
+ * non-acknowledged control channel messages.
+ *
+ * @par Main event loop implementations
+ *
+ * Depending on the mode in which OpenVPN is running, a different main
+ * event loop function is called to drive the event processing. The
+ * following implementations are available:
+ * - Client mode using UDP or TCP: \c tunnel_point_to_point()
+ * - Server mode using UDP: \c tunnel_server_udp_single_threaded()
+ * - Server mode using TCP: \c tunnel_server_tcp()
+ */
diff --git a/app/openvpn/doc/doxygen/doc_external_multiplexer.h b/app/openvpn/doc/doxygen/doc_external_multiplexer.h
new file mode 100644
index 00000000..76532557
--- /dev/null
+++ b/app/openvpn/doc/doxygen/doc_external_multiplexer.h
@@ -0,0 +1,46 @@
+/*
+ * 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. <openvpn@fox-it.com>
+ *
+ *
+ * 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
+ * External Multiplexer module documentation file.
+ */
+
+/**
+ * @addtogroup external_multiplexer External Multiplexer module
+ *
+ * The External Multiplexer is the link between the external network
+ * interface and the other OpenVPN modules. It reads packets from the
+ * external network interface, determines which remote OpenVPN peer and
+ * VPN tunnel they are associated with, and whether they are data channel
+ * or control channel packets. It then passes the packets on to the
+ * appropriate processing module.
+ *
+ * This module also handles packets traveling in the reverse direction,
+ * which have been generated by the local control channel or which have
+ * already been processed by the \link data_control Data Channel Control
+ * module\endlink and are destined for a remote host reachable through a
+ * VPN tunnel.
+ */
diff --git a/app/openvpn/doc/doxygen/doc_fragmentation.h b/app/openvpn/doc/doxygen/doc_fragmentation.h
new file mode 100644
index 00000000..ef34cdb2
--- /dev/null
+++ b/app/openvpn/doc/doxygen/doc_fragmentation.h
@@ -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. <openvpn@fox-it.com>
+ *
+ *
+ * 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.
+ */
diff --git a/app/openvpn/doc/doxygen/doc_internal_multiplexer.h b/app/openvpn/doc/doxygen/doc_internal_multiplexer.h
new file mode 100644
index 00000000..5142dd0d
--- /dev/null
+++ b/app/openvpn/doc/doxygen/doc_internal_multiplexer.h
@@ -0,0 +1,44 @@
+/*
+ * 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. <openvpn@fox-it.com>
+ *
+ *
+ * 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
+ * Internal Multiplexer module documentation file.
+ */
+
+/**
+ * @addtogroup internal_multiplexer Internal Multiplexer module
+ *
+ * The Internal Multiplexer is the link between the virtual tun/tap
+ * network interface and the \link data_control Data Channel Control
+ * module\endlink. It reads packets from the virtual network interface,
+ * determines for which remote OpenVPN peer they are destined, and then
+ * passes the packets on to the Data Channel Control module together with
+ * information about their destination VPN tunnel instance.
+ *
+ * This module also handles packets traveling in the reverse direction,
+ * which have already been processed by the Data Channel Control module
+ * and are destined for a locally reachable host.
+ */
diff --git a/app/openvpn/doc/doxygen/doc_key_generation.h b/app/openvpn/doc/doxygen/doc_key_generation.h
new file mode 100644
index 00000000..903a4652
--- /dev/null
+++ b/app/openvpn/doc/doxygen/doc_key_generation.h
@@ -0,0 +1,153 @@
+/*
+ * 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. <openvpn@fox-it.com>
+ *
+ *
+ * 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
+ * Key generation documentation file.
+ */
+
+/**
+ * @page key_generation Data channel %key generation
+ *
+ * This section describes how OpenVPN peers generate and exchange %key
+ * material necessary for the security operations performed on data
+ * channel packets.
+ *
+ * The %key generation and exchange process between OpenVPN client and
+ * server occurs every time data channel security parameters are
+ * negotiated, for example during the initial setup of a VPN tunnel or
+ * when the active security parameters expire. In source code terms, this
+ * is when a new key_state structure is initialized.
+ *
+ * @section key_generation_method Key methods
+ *
+ * OpenVPN supports two different ways of generating and exchanging %key
+ * material between client and server. These are known as %key method 1
+ * and %key method 2. %Key method 2 is the recommended method. Both are
+ * explained below.
+ *
+ * @subsection key_generation_method_1 Key method 1
+ *
+ * -# Each host generates its own random material.
+ * -# Each host uses its locally generated random material as %key data
+ * for encrypting and signing packets sent to the remote peer.
+ * -# Each host then sends its random material to the remote peer, so that
+ * the remote peer can use that %key data for authenticating and
+ * decrypting received packets.
+ *
+ * @subsection key_generation_method_2 Key method 2
+ *
+ * -# The client generates random material in the following amounts:
+ * - Pre-master secret: 48 bytes
+ * - Client's PRF seed for master secret: 32 bytes
+ * - Client's PRF seed for %key expansion: 32 bytes
+ * -# The client sends its share of random material to the server.
+ * -# The server generates random material in the following amounts:
+ * - Server's PRF seed for master secret: 32 bytes
+ * - Server's PRF seed for %key expansion: 32 bytes
+ * -# The server computes the %key expansion using its own and the
+ * client's random material.
+ * -# The server sends its share of random material to the client.
+ * -# The client computes the %key expansion using its own and the
+ * server's random material.
+ *
+ * %Key method 2 %key expansion is performed by the \c
+ * generate_key_expansion() function. Please refer to its source code for
+ * details of the %key expansion process.
+ *
+ * @subsection key_generation_random Source of random material
+ *
+ * OpenVPN uses the either the OpenSSL library or the PolarSSL library as its
+ * source of random material.
+ *
+ * In OpenSSL, the \c RAND_bytes() function is called
+ * to supply cryptographically strong pseudo-random data. The following links
+ * contain more information on this subject:
+ * - For OpenSSL's \c RAND_bytes() function:
+ * http://www.openssl.org/docs/crypto/RAND_bytes.html
+ * - For OpenSSL's pseudo-random number generating system:
+ * http://www.openssl.org/docs/crypto/rand.html
+ * - For OpenSSL's support for external crypto modules:
+ * http://www.openssl.org/docs/crypto/engine.html
+ *
+ * In PolarSSL, the Havege random number generator is used. For details, see
+ * the PolarSSL documentation.
+ *
+ * @section key_generation_exchange Key exchange:
+ *
+ * The %key exchange process is initiated by the OpenVPN process running
+ * in client mode. After the initial three-way handshake has successfully
+ * completed, the client sends its share of random material to the server,
+ * after which the server responds with its part. This process is
+ * depicted below:
+ *
+@verbatim
+ Client Client Server Server
+ State Action Action State
+---------- -------------------- -------------------- ----------
+
+ ... waiting until three-way handshake complete ...
+S_START S_START
+ key_method_?_write()
+ send to server --> --> --> --> receive from client
+S_SENT_KEY key_method_?_read()
+ S_GOT_KEY
+ key_method_?_write()
+ receive from server <-- <-- <-- <-- send to client
+ key_method_?_read() S_SENT_KEY
+S_GOT_KEY
+ ... waiting until control channel fully synchronized ...
+S_ACTIVE S_ACTIVE
+@endverbatim
+ *
+ * For more information about the client and server state values, see the
+ * \link control_processor Control Channel Processor module\endlink.
+ *
+ * Depending on which %key method is used, the \c ? in the function names
+ * of the diagram above is a \c 1 or a \c 2. For example, if %key method
+ * 2 is used, that %key exchange would be started by the client calling \c
+ * key_method_2_write(). These functions are called from the \link
+ * control_processor Control Channel Processor module's\endlink \c
+ * tls_process() function and control the %key generation and exchange
+ * process as follows:
+ * - %Key method 1:
+ * - \c key_method_1_write(): generate random material locally, and load
+ * as "sending" keys.
+ * - \c key_method_1_read(): read random material received from remote
+ * peer, and load as "receiving" keys.
+ * - %Key method 2:
+ * - \c key_method_2_write(): generate random material locally, and if
+ * in server mode generate %key expansion.
+ * - \c key_method_2_read(): read random material received from remote
+ * peer, and if in client mode generate %key expansion.
+ *
+ * @subsection key_generation_encapsulation Transmission of key material
+ *
+ * The OpenVPN client and server communicate with each other through their
+ * control channel. This means that all of the data transmitted over the
+ * network, such as random material for %key generation, is encapsulated
+ * in a TLS layer. For more details, see the \link control_tls Control
+ * Channel TLS module\endlink documentation.
+ */
diff --git a/app/openvpn/doc/doxygen/doc_mainpage.h b/app/openvpn/doc/doxygen/doc_mainpage.h
new file mode 100644
index 00000000..821b2e87
--- /dev/null
+++ b/app/openvpn/doc/doxygen/doc_mainpage.h
@@ -0,0 +1,162 @@
+/*
+ * 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. <openvpn@fox-it.com>
+ *
+ *
+ * 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
+ * Main page documentation file.
+ */
+
+/**
+ * @mainpage OpenVPN v2.1 source code documentation
+ *
+ * This documentation describes the internal structure of OpenVPN. It was
+ * automatically generated from specially formatted comment blocks in
+ * OpenVPN's source code using Doxygen. (See
+ * http://www.stack.nl/~dimitri/doxygen/ for more information on Doxygen)
+ *
+ * The \ref mainpage_modules "Modules section" below gives an introduction
+ * into the high-level module concepts used throughout this documentation.
+ * The \ref mainpage_relatedpages "Related Pages section" below describes
+ * various special subjects related to OpenVPN's implementation which are
+ * discussed in the related pages section.
+ *
+ * @section mainpage_modules Modules
+ *
+ * For the purpose of describing the internal structure of OpenVPN, this
+ * documentation and the underlying source code has been broken up into a
+ * number of conceptually well-defined parts, known as modules. Each
+ * module plays a specific role within the OpenVPN process, and in most
+ * cases each module has a clear interfacing strategy for interacting with
+ * other modules.
+ *
+ * The following modules have been defined:
+ * - Driver module:
+ * - The \link eventloop Main Event Loop\endlink: this module drives the
+ * event handling of OpenVPN. It implements various types of
+ * select-loop which wait until an event happens, and then delegate
+ * the handling of that event to the appropriate module.
+ * - Network interface modules:
+ * - The \link external_multiplexer External Multiplexer\endlink: this
+ * module sends and receives packets to and from remote OpenVPN peers
+ * over the external network interface. It also takes care of
+ * demultiplexing received packets to their appropriate VPN tunnel and
+ * splitting control channel and data channel packets.
+ * - The \link internal_multiplexer Internal Multiplexer\endlink: this
+ * module sends and receives packets to and from locally reachable
+ * posts over the virtual tun/tap network interface. It also takes
+ * care of determining through which VPN tunnel a received packet must
+ * be sent to reach its destination.
+ * - Control channel modules:
+ * - The \link reliable Reliability Layer\endlink: this module offers a
+ * %reliable and sequential transport layer for control channel
+ * messages.
+ * - The \link control_tls Control Channel TLS module\endlink: this
+ * module offers a secure encapsulation of control channel messages
+ * using the TLS protocol.
+ * - The \link control_processor Control Channel Processor\endlink: his
+ * module manages the setup, maintenance, and shut down of VPN
+ * tunnels.
+ * - Data channel modules:
+ * - The \link data_control Data Channel Control module\endlink: this
+ * module controls the processing of data channel packets and,
+ * depending on the settings of the packet's VPN tunnel, passes the
+ * packet to the three modules below for handling.
+ * - The \link data_crypto Data Channel Crypto module\endlink: this
+ * module performs security operations on data channel packets.
+ * - The \link fragmentation Data Channel Fragmentation module\endlink:
+ * this module offers fragmentation of data channel packets larger
+ * than the VPN tunnel's MTU.
+ * - The \link compression Data Channel Compression module\endlink: this
+ * module offers compression of data channel packets.
+ *
+ * @subsection mainpage_modules_example Example event: receiving a packet
+ *
+ * OpenVPN handles many types of events during operation. These include
+ * external events, such as network traffic being received, and internal
+ * events, such as a %key session timing out causing renegotiation. An
+ * example event, receiving a packet over the network, is described here
+ * together with which modules play what roles:
+ * -# The \link eventloop Main Event Loop\endlink detects that a packet
+ * can be read from the external or the virtual tun/tap network
+ * interface.
+ * -# The \link eventloop Main Event Loop\endlink calls the \link
+ * external_multiplexer External Multiplexer\endlink or \link
+ * internal_multiplexer Internal Multiplexer\endlink to read and
+ * process the packet.
+ * -# The multiplexer module determines the type of packet and its
+ * destination, and passes the packet on to the appropriate handling
+ * module:
+ * - A control channel packet received by the \link
+ * external_multiplexer External Multiplexer\endlink is passed on
+ * through the \link reliable Reliability Layer\endlink and the \link
+ * control_tls Control Channel TLS module\endlink to the \link
+ * control_processor Control Channel Processor\endlink.
+ * - A data channel packet received by either multiplexer module is
+ * passed on to the \link data_control Data Channel Control
+ * module\endlink.
+ * -# The packet is processed by the appropriate control channel or data
+ * channel modules.
+ * -# If, after processing the packet, a resulting packet is generated
+ * that needs to be sent to a local or remote destination, it is given
+ * to the \link external_multiplexer External Multiplexer\endlink or
+ * \link internal_multiplexer Internal Multiplexer\endlink for sending.
+ * -# If a packet is waiting to be sent by either multiplexer module and
+ * the \link eventloop Main Event Loop\endlink detects that data can be
+ * written to the associated network interface, it calls the
+ * multiplexer module to send the packet.
+ *
+ * @section mainpage_relatedpages Related pages
+ *
+ * This documentation includes a number of descriptions of various aspects
+ * of OpenVPN and its implementation. These are not directly related to
+ * one module, function, or data structure, and are therefore listed
+ * separately under "Related Pages".
+ *
+ * @subsection mainpage_relatedpages_key_generation Data channel key generation
+ *
+ * The @ref key_generation "Data channel key generation" related page
+ * describes how, during VPN tunnel setup and renegotiation, OpenVPN peers
+ * generate and exchange the %key material required for the symmetric
+ * encryption/decryption and HMAC signing/verifying security operations
+ * performed on data channel packets.
+ *
+ * @subsection mainpage_relatedpages_tunnel_state VPN tunnel state
+ *
+ * The @ref tunnel_state "Structure of VPN tunnel state storage" related
+ * page describes how an OpenVPN process manages the state information
+ * associated with its active VPN tunnels.
+ *
+ * @subsection mainpage_relatedpages_network_protocol Network protocol
+ *
+ * The @ref network_protocol "Network protocol" related page describes the
+ * format and content of VPN tunnel packets exchanged between OpenVPN
+ * peers.
+ *
+ * @subsection mainpage_relatedpages_memory_management Memory management
+ *
+ * The @ref memory_management "Memory management strategies" related page
+ * gives a brief introduction into OpenVPN's memory %buffer library and
+ * garbage collection facilities.
+ */
diff --git a/app/openvpn/doc/doxygen/doc_memory_management.h b/app/openvpn/doc/doxygen/doc_memory_management.h
new file mode 100644
index 00000000..f948783e
--- /dev/null
+++ b/app/openvpn/doc/doxygen/doc_memory_management.h
@@ -0,0 +1,99 @@
+/*
+ * 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. <openvpn@fox-it.com>
+ *
+ *
+ * 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
+ * Memory management strategies documentation file.
+ */
+
+/**
+ * @page memory_management OpenVPN's memory management strategies
+ *
+ * This section describes several implementation details relating to
+ * OpenVPN's memory management strategies.
+ *
+ * During operation, the OpenVPN process performs all kinds of operations
+ * on blocks of data. Receiving packets, encrypting content, prepending
+ * headers, etc. To make the programmer's job easier and to decrease the
+ * likelihood of memory-related bugs, OpenVPN uses its own memory %buffer
+ * library and garbage collection facilities. These are described in
+ * brief here.
+ *
+ * @section memory_management_buffer The buffer structure
+ *
+ * The \c buffer structure is a wrapper around a block of dynamically
+ * allocated memory which keeps track of the block's capacity \c
+ * buffer.capacity and location in memory \c buffer.data. This structure
+ * supports efficient prepending and appending within the allocated memory
+ * through the use of offset \c buffer.offset and length \c buffer.len
+ * fields. See the \c buffer documentation for more details on the
+ * structure itself.
+ *
+ * OpenVPN's %buffer library, implemented in the \c buffer.h and \c
+ * buffer.c files, contains many utility functions for working with \c
+ * buffer structures. These functions facilitate common operations, such
+ * as allocating, freeing, reading and writing to \c buffer structures,
+ * and even offer several more advanced operations, such as string
+ * matching and creating sub-buffers.
+ *
+ * Not only do these utility functions make working with \c buffer
+ * structures easy, they also perform extensive error checking. Each
+ * function, where necessary, checks whether enough space is available
+ * before performing its actions. This minimizes the chance of bugs
+ * leading to %buffer overflows and other vulnerabilities.
+ *
+ * @section memory_management_frame The frame structure
+ *
+ * The \c frame structure keeps track of the maximum allowed packet
+ * geometries of a network connection.
+ *
+ * It is used, for example, to determine the size of \c buffer structures
+ * in which to store data channel packets. This is done by having each
+ * data channel processing module register the maximum amount of extra
+ * space it will need for header prepending and content expansion in the
+ * \c frame structure. Once these parameters are known, \c buffer
+ * structures can be allocated, based on the \c frame parameters, so that
+ * they are large enough to allow efficient prepending of headers and
+ * processing of content.
+ *
+ * @section memory_management_garbage Garbage collection
+ *
+ * OpenVPN has many sizable functions which perform various actions
+ * depending on their %context. This makes it difficult to know in advance
+ * exactly how much memory must be allocated. The garbage collection
+ * facilities are used to keep track of dynamic allocations, thereby
+ * allowing easy collective freeing of the allocated memory.
+ *
+ * The garbage collection system is implemented by the \c gc_arena and \c
+ * gc_entry structures. The arena represents a garbage collecting unit,
+ * and contains a linked list of entries. Each entry represents one block
+ * of dynamically allocated memory.
+ *
+ * The garbage collection system also contains various utility functions
+ * for working with the garbage collection structures. These include
+ * functions for initializing new arenas, allocating memory of a given
+ * size and registering the allocation in an arena, and freeing all the
+ * allocated memory associated with an arena.
+ */
diff --git a/app/openvpn/doc/doxygen/doc_protocol_overview.h b/app/openvpn/doc/doxygen/doc_protocol_overview.h
new file mode 100644
index 00000000..26fed331
--- /dev/null
+++ b/app/openvpn/doc/doxygen/doc_protocol_overview.h
@@ -0,0 +1,199 @@
+/*
+ * 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. <openvpn@fox-it.com>
+ *
+ *
+ * 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 Network protocol overview documentation file.
+ */
+
+/**
+ * @page network_protocol OpenVPN's network protocol
+ *
+ * Description of packet structure in OpenVPN's network protocol.
+ *
+ * This document describes the structure of packets exchanged between
+ * OpenVPN peers. It is based on the protocol description in the \c ssl.h
+ * file.
+ *
+ * @section network_protocol_external Outer structure of packets exchanged between OpenVPN peers
+ *
+ * VPN tunnel packets are transported between OpenVPN peers using the UDP
+ * or TCP protocols. Their structure is described below.
+ *
+ * @subsection network_protocol_external_structure External packet structure
+ *
+ * - packet length (16 bits, unsigned) [TCP-mode only]: always sent as
+ * plain text. Since TCP is a stream protocol, this packet length
+ * defines the packetization of the stream.
+ * - packet opcode and key_id (8 bits) [TLS-mode only]:
+ * - package message type (high 5 bits)
+ * - key_id (low 3 bits): the key_id refers to an already negotiated
+ * TLS session. OpenVPN seamlessly renegotiates the TLS session by
+ * using a new key_id for the new session. Overlap (controlled by
+ * user definable parameters) between old and new TLS sessions is
+ * allowed, providing a seamless transition during tunnel operation.
+ * - payload (n bytes)
+ *
+ * @subsection network_protocol_external_types Message types
+ *
+ * The type of a VPN tunnel packet is indicated by its opcode. The
+ * following describes the various opcodes available.
+ *
+ * - Control channel messages:
+ * - \c P_CONTROL_HARD_RESET_CLIENT_V1 -- %Key method 1, initial %key
+ * from client, forget previous state.
+ * - \c P_CONTROL_HARD_RESET_SERVER_V1 -- %Key method 1, initial %key
+ * from server, forget previous state.
+ * - \c P_CONTROL_HARD_RESET_CLIENT_V2 -- %Key method 2, initial %key
+ * from client, forget previous state.
+ * - \c P_CONTROL_HARD_RESET_SERVER_V2 -- %Key method 2, initial %key
+ * from server, forget previous state.
+ * - \c P_CONTROL_SOFT_RESET_V1 -- New %key, with a graceful
+ * transition from old to new %key in the sense that a transition
+ * window exists where both the old or new key_id can be used.
+ * - \c P_CONTROL_V1 -- Control channel packet (usually TLS
+ * ciphertext).
+ * - \c P_ACK_V1 -- Acknowledgement for control channel packets
+ * received.
+ * - Data channel messages:
+ * - \c P_DATA_V1 -- Data channel packet containing data channel
+ * ciphertext.
+ *
+ * @subsection network_protocol_external_key_id Session IDs and Key IDs
+ *
+ * OpenVPN uses two different forms of packet identifiers:
+ * - The first form is 64 bits and is used for all control channel
+ * messages. This form is referred to as a \c session_id.
+ * - Data channel messages on the other hand use a shortened form of 3
+ * bits for efficiency reasons since the vast majority of OpenVPN
+ * packets in an active tunnel will be data channel messages. This
+ * form is referred to as a \c key_id.
+ *
+ * The control and data channels use independent packet-id sequences,
+ * because the data channel is an unreliable channel while the control
+ * channel is a %reliable channel. Each use their own independent HMAC
+ * keys.
+ *
+ * @subsection network_protocol_external_reliable Control channel reliability layer
+ *
+ * Control channel messages (\c P_CONTROL_* and \c P_ACK_* message types)
+ * are TLS ciphertext packets which have been encapsulated inside of a
+ * reliability layer. The reliability layer is implemented as a
+ * straightforward acknowledge and retransmit model.
+ *
+ * Acknowledgments of received messages can be encoded in either the
+ * dedicated \c P_ACK_* record or they can be prepended to a \c
+ * P_CONTROL_* message.
+ *
+ * See the \link reliable Reliability Layer\endlink module for a detailed
+ * description.
+ *
+ * @section network_protocol_control Structure of control channel messages
+ *
+ * @subsection network_protocol_control_ciphertext Structure of ciphertext control channel messages
+ *
+ * Control channel packets in ciphertext form consist of the following
+ * parts:
+ *
+ * - local \c session_id (random 64 bit value to identify TLS session).
+ * - HMAC signature of entire encapsulation header for HMAC firewall
+ * [only if \c --tls-auth is specified] (usually 16 or 20 bytes).
+ * - packet-id for replay protection (4 or 8 bytes, includes sequence
+ * number and optional \c time_t timestamp).
+ * - acknowledgment packet-id array length (1 byte).
+ * - acknowledgment packet-id array (if length > 0).
+ * - acknowledgment remote session-id (if length > 0).
+ * - packet-id of this message (4 bytes).
+ * - TLS payload ciphertext (n bytes) (only for \c P_CONTROL_V1).
+ *
+ * Note that when \c --tls-auth is used, all message types are protected
+ * with an HMAC signature, even the initial packets of the TLS handshake.
+ * This makes it easy for OpenVPN to throw away bogus packets quickly,
+ * without wasting resources on attempting a TLS handshake which will
+ * ultimately fail.
+ *
+ * @subsection network_protocol_control_key_methods Control channel key methods and
+ *
+ * Once the TLS session has been initialized and authenticated, the TLS
+ * channel is used to exchange random %key material for bidirectional
+ * cipher and HMAC keys which will be used to secure data channel packets.
+ * OpenVPN currently implements two %key methods. %Key method 1 directly
+ * derives keys using random bits obtained from the \c RAND_bytes()
+ * OpenSSL function. %Key method 2 mixes random %key material from both
+ * sides of the connection using the TLS PRF mixing function. %Key method
+ * 2 is the preferred method and is the default for OpenVPN 2.0.
+ *
+ * The @ref key_generation "Data channel key generation" related page
+ * describes the %key methods in more detail.
+ *
+ * @subsection network_protocol_control_plaintext Structure of plaintext control channel messages
+ *
+ * - %Key method 1:
+ * - Cipher %key length in bytes (1 byte).
+ * - Cipher %key (n bytes).
+ * - HMAC %key length in bytes (1 byte).
+ * - HMAC %key (n bytes).
+ * - %Options string (n bytes, null terminated, client/server %options
+ * string should match).
+ * - %Key method 2:
+ * - Literal 0 (4 bytes).
+ * - %Key method (1 byte).
+ * - \c key_source structure (\c key_source.pre_master only defined
+ * for client -> server).
+ * - %Options string length, including null (2 bytes).
+ * - %Options string (n bytes, null terminated, client/server %options
+ * string must match).
+ * - [The username/password data below is optional, record can end at
+ * this point.]
+ * - Username string length, including null (2 bytes).
+ * - Username string (n bytes, null terminated).
+ * - Password string length, including null (2 bytes).
+ * - Password string (n bytes, null terminated).
+ *
+ * @section network_protocol_data Structure of data channel messages
+ *
+ * @subsection network_protocol_data_ciphertext Structure of ciphertext data channel messages
+ *
+ * The P_DATA_* payload represents encrypted, encapsulated tunnel packets
+ * which tend to be either IP packets or Ethernet frames. This is
+ * essentially the "payload" of the VPN.
+ *
+ * Data channel packets in ciphertext form consist of the following parts:
+ * - HMAC of ciphertext IV + ciphertext (if not disabled by \c --auth
+ * none).
+ * - Ciphertext IV (size is cipher-dependent, if not disabled by \c
+ * --no-iv).
+ * - Tunnel packet ciphertext.
+ *
+ * @subsection network_protocol_data_plaintext Structure of plaintext data channel messages
+ *
+ * Data channel packets in plaintext form consist of the following parts:
+ * - packet-id (4 or 8 bytes, if not disabled by --no-replay).
+ * - In TLS mode, 4 bytes are used because the implementation can
+ * force a TLS renegotation before \c 2^32 packets are sent.
+ * - In pre-shared %key mode, 8 bytes are used (sequence number and \c
+ * time_t value) to allow long-term %key usage without packet-id
+ * collisions.
+ * - User plaintext (n bytes).
+ */
diff --git a/app/openvpn/doc/doxygen/doc_reliable.h b/app/openvpn/doc/doxygen/doc_reliable.h
new file mode 100644
index 00000000..5264906a
--- /dev/null
+++ b/app/openvpn/doc/doxygen/doc_reliable.h
@@ -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. <openvpn@fox-it.com>
+ *
+ *
+ * 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.
+ */
diff --git a/app/openvpn/doc/doxygen/doc_tunnel_state.h b/app/openvpn/doc/doxygen/doc_tunnel_state.h
new file mode 100644
index 00000000..6c93e71b
--- /dev/null
+++ b/app/openvpn/doc/doxygen/doc_tunnel_state.h
@@ -0,0 +1,155 @@
+/*
+ * 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. <openvpn@fox-it.com>
+ *
+ *
+ * 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
+ * VPN tunnel state documentation file.
+ */
+
+/**
+ * @page tunnel_state Structure of the VPN tunnel state storage
+ *
+ * This section describes how OpenVPN stores its VPN tunnel state during
+ * operation.
+ *
+ * OpenVPN uses several data structures as storage containers for state
+ * information of active VPN tunnels. These are described in this
+ * section, together with a little bit of history to help understand the
+ * origin of the current architecture.
+ *
+ * Whether an OpenVPN process is running in client-mode or server-mode
+ * determines whether it can support only one or multiple simultaneously
+ * active VPN tunnels. This consequently also determines how the
+ * associated state information is wrapped up internally. This section
+ * gives an overview of the differences.
+ *
+ * @section tunnel_state_history Historic developments
+ *
+ * In the old v1.x series, an OpenVPN process managed only one single VPN
+ * tunnel. This allowed the VPN tunnel state to be stored together with
+ * process-global information in one single \c context structure.
+ *
+ * This changed, however, in the v2.x series, as new OpenVPN versions
+ * running in server-mode can support multiple simultaneously active VPN
+ * tunnels. This necessitated a redesign of the VPN tunnel state
+ * container structures, and modification of the \link
+ * external_multiplexer External Multiplexer\endlink and \link
+ * internal_multiplexer Internal Multiplexer\endlink systems. The
+ * majority of these changes are only relevant for OpenVPN processes
+ * running in server-mode, and the client-mode structure has remained very
+ * similar to the v1.x single-tunnel form.
+ *
+ * @section tunnel_state_client Client-mode state
+ *
+ * An OpenVPN process running in client-mode can manage at most one single
+ * VPN tunnel at any one time. The state information for a client's VPN
+ * tunnel is stored in a \c context structure.
+ *
+ * The \c context structure is created in the \c main() function. That is
+ * also where process-wide initialization takes place, such as parsing
+ * command line %options and reading configuration files. The \c context
+ * is then passed to \c tunnel_point_to_point() which drives OpenVPN's
+ * main event processing loop. These functions are both part of the \link
+ * eventloop Main Event Loop\endlink module.
+ *
+ * @subsection tunnel_state_client_init Initialization and cleanup
+ *
+ * Because there is only one \c context structure present, it can be
+ * initialized and cleaned up from the client's main event processing
+ * function. Before the \c tunnel_point_to_point() function enters its
+ * event loop, it calls \c init_instance_handle_signals() which calls \c
+ * init_instance() to initialize the single \c context structure. After
+ * the event loop stops, it calls \c close_instance() to clean up the \c
+ * context.
+ *
+ * @subsection tunnel_state_client_event Event processing
+ *
+ * When the main event processing loop activates the external or internal
+ * multiplexer to handle a network event, it is not necessary to determine
+ * which VPN tunnel the event is associated with, because there is only
+ * one VPN tunnel active.
+ *
+ * @section tunnel_state_server Server-mode state
+ *
+ * An OpenVPN process running in server-mode can manage multiple
+ * simultaneously active VPN tunnels. For every VPN tunnel active, in
+ * other words for every OpenVPN client which is connected to a server,
+ * the OpenVPN server has one \c context structure in which it stores that
+ * particular VPN tunnel's state information.
+ *
+ * @subsection tunnel_state_server_multi Multi_context and multi_instance structures
+ *
+ * To support multiple \c context structures, each is wrapped in a \c
+ * multi_instance structure, and all the \c multi_instance structures are
+ * registered in one single \c multi_context structure. The \link
+ * external_multiplexer External Multiplexer\endlink and \link
+ * internal_multiplexer Internal Multiplexer\endlink then use the \c
+ * multi_context to retrieve the correct \c multi_instance and \c context
+ * associated with a given network address.
+ *
+ * @subsection tunnel_state_server_init Startup and initialization
+ *
+ * An OpenVPN process running in server-mode starts in the same \c main()
+ * function as it would in client-mode. The same process-wide
+ * initialization is performed, and the resulting state and configuration
+ * is stored in a \c context structure. The server-mode and client-mode
+ * processes diverge when the \c main() function calls one of \c
+ * tunnel_point_to_point() or \c tunnel_server().
+ *
+ * In server-mode, \c main() calls the \c tunnel_server() function, which
+ * transfers control to \c tunnel_server_udp_single_threaded() or \c
+ * tunnel_server_tcp() depending on the external transport protocol.
+ *
+ * These functions receive the \c context created in \c main(). This
+ * object has a special status in server-mode, as it does not represent an
+ * active VPN tunnel, but does contain process-wide configuration
+ * parameters. In the source code, it is often stored in "top" variables.
+ * To distinguish this object from other instances of the same type, its
+ * \c context.mode value is set to \c CM_TOP. Other \c context objects,
+ * which do represent active VPN tunnels, have a \c context.mode set to \c
+ * CM_CHILD_UDP or \c CM_CHILD_TCP, depending on the external transport
+ * protocol.
+ *
+ * Both \c tunnel_server_udp_single_threaded() and \c tunnel_server_tcp()
+ * perform similar initialization. In either case, a \c multi_context
+ * structure is created, and it is initialized according to the
+ * configuration stored in the top \c context by the \c multi_init() and
+ * \c multi_top_init() functions.
+ *
+ * @subsection tunnel_state_server_tunnels Creating and destroying VPN tunnels
+ *
+ * When an OpenVPN client makes a new connection to a server, the server
+ * creates a new \c context and \c multi_instance. The latter is
+ * registered in the \c multi_context, which makes it possible for the
+ * external and internal multiplexers to retrieve the correct \c
+ * multi_instance and \c context when a network event occurs.
+ *
+ * @subsection tunnel_state_server_cleanup Final cleanup
+ *
+ * After the main event loop exits, both \c
+ * tunnel_server_udp_single_threaded() and \c tunnel_server_tcp() perform
+ * similar cleanup. They call \c multi_uninit() followed by \c
+ * multi_top_free() to clean up the \c multi_context structure.
+ */
diff --git a/app/openvpn/doc/doxygen/openvpn.doxyfile b/app/openvpn/doc/doxygen/openvpn.doxyfile
new file mode 100644
index 00000000..5d87172c
--- /dev/null
+++ b/app/openvpn/doc/doxygen/openvpn.doxyfile
@@ -0,0 +1,279 @@
+# Doxyfile 1.5.5
+
+#---------------------------------------------------------------------------
+# Project related configuration options
+#---------------------------------------------------------------------------
+DOXYFILE_ENCODING = UTF-8
+PROJECT_NAME = "OpenVPN"
+PROJECT_NUMBER =
+OUTPUT_DIRECTORY = doxygen
+CREATE_SUBDIRS = NO
+OUTPUT_LANGUAGE = English
+BRIEF_MEMBER_DESC = YES
+REPEAT_BRIEF = YES
+ABBREVIATE_BRIEF = "The $name class" \
+ "The $name widget" \
+ "The $name file" \
+ is \
+ provides \
+ specifies \
+ contains \
+ represents \
+ a \
+ an \
+ the
+ALWAYS_DETAILED_SEC = NO
+INLINE_INHERITED_MEMB = NO
+FULL_PATH_NAMES = YES
+STRIP_FROM_PATH = ""
+STRIP_FROM_INC_PATH =
+SHORT_NAMES = NO
+JAVADOC_AUTOBRIEF = YES # NO
+QT_AUTOBRIEF = NO
+MULTILINE_CPP_IS_BRIEF = NO
+DETAILS_AT_TOP = NO
+INHERIT_DOCS = YES
+SEPARATE_MEMBER_PAGES = NO
+TAB_SIZE = 8
+ALIASES =
+OPTIMIZE_OUTPUT_FOR_C = YES
+OPTIMIZE_OUTPUT_JAVA = NO
+OPTIMIZE_FOR_FORTRAN = NO
+OPTIMIZE_OUTPUT_VHDL = NO
+BUILTIN_STL_SUPPORT = NO
+CPP_CLI_SUPPORT = NO
+SIP_SUPPORT = NO
+DISTRIBUTE_GROUP_DOC = NO
+SUBGROUPING = YES
+TYPEDEF_HIDES_STRUCT = NO
+#---------------------------------------------------------------------------
+# Build related configuration options
+#---------------------------------------------------------------------------
+EXTRACT_ALL = YES
+EXTRACT_PRIVATE = YES
+EXTRACT_STATIC = YES
+EXTRACT_LOCAL_CLASSES = YES
+EXTRACT_LOCAL_METHODS = YES
+EXTRACT_ANON_NSPACES = YES
+HIDE_UNDOC_MEMBERS = NO
+HIDE_UNDOC_CLASSES = NO
+HIDE_FRIEND_COMPOUNDS = NO
+HIDE_IN_BODY_DOCS = NO
+INTERNAL_DOCS = NO
+CASE_SENSE_NAMES = NO
+HIDE_SCOPE_NAMES = NO
+SHOW_INCLUDE_FILES = YES
+INLINE_INFO = YES
+SORT_MEMBER_DOCS = YES
+SORT_BRIEF_DOCS = NO
+SORT_GROUP_NAMES = NO
+SORT_BY_SCOPE_NAME = NO
+GENERATE_TODOLIST = YES
+GENERATE_TESTLIST = YES
+GENERATE_BUGLIST = YES
+GENERATE_DEPRECATEDLIST= YES
+ENABLED_SECTIONS =
+MAX_INITIALIZER_LINES = 30
+SHOW_USED_FILES = YES
+SHOW_DIRECTORIES = NO
+FILE_VERSION_FILTER =
+#---------------------------------------------------------------------------
+# configuration options related to warning and progress messages
+#---------------------------------------------------------------------------
+QUIET = NO
+WARNINGS = YES
+WARN_IF_UNDOCUMENTED = YES
+WARN_IF_DOC_ERROR = YES
+WARN_NO_PARAMDOC = NO
+WARN_FORMAT = "$file:$line: $text"
+WARN_LOGFILE =
+#---------------------------------------------------------------------------
+# configuration options related to the input files
+#---------------------------------------------------------------------------
+INPUT = .
+INPUT_ENCODING = UTF-8
+FILE_PATTERNS = *.c \
+ *.cc \
+ *.cxx \
+ *.cpp \
+ *.c++ \
+ *.d \
+ *.java \
+ *.ii \
+ *.ixx \
+ *.ipp \
+ *.i++ \
+ *.inl \
+ *.h \
+ *.hh \
+ *.hxx \
+ *.hpp \
+ *.h++ \
+ *.idl \
+ *.odl \
+ *.cs \
+ *.php \
+ *.php3 \
+ *.inc \
+ *.m \
+ *.mm \
+ *.dox \
+ *.py \
+ *.f90 \
+ *.f \
+ *.vhd \
+ *.vhdl
+RECURSIVE = YES
+EXCLUDE =
+EXCLUDE_SYMLINKS = NO
+EXCLUDE_PATTERNS =
+EXCLUDE_SYMBOLS =
+EXAMPLE_PATH =
+EXAMPLE_PATTERNS = *
+EXAMPLE_RECURSIVE = NO
+IMAGE_PATH =
+INPUT_FILTER =
+FILTER_PATTERNS =
+FILTER_SOURCE_FILES = NO
+#---------------------------------------------------------------------------
+# configuration options related to source browsing
+#---------------------------------------------------------------------------
+SOURCE_BROWSER = YES
+INLINE_SOURCES = NO
+STRIP_CODE_COMMENTS = YES
+REFERENCED_BY_RELATION = YES
+REFERENCES_RELATION = YES
+REFERENCES_LINK_SOURCE = YES
+USE_HTAGS = NO
+VERBATIM_HEADERS = YES
+#---------------------------------------------------------------------------
+# configuration options related to the alphabetical class index
+#---------------------------------------------------------------------------
+ALPHABETICAL_INDEX = NO
+COLS_IN_ALPHA_INDEX = 5
+IGNORE_PREFIX =
+#---------------------------------------------------------------------------
+# configuration options related to the HTML output
+#---------------------------------------------------------------------------
+GENERATE_HTML = YES
+HTML_OUTPUT = html
+HTML_FILE_EXTENSION = .html
+HTML_HEADER =
+HTML_FOOTER =
+HTML_STYLESHEET =
+HTML_ALIGN_MEMBERS = YES
+GENERATE_HTMLHELP = NO
+GENERATE_DOCSET = NO
+DOCSET_FEEDNAME = "Doxygen generated docs"
+DOCSET_BUNDLE_ID = org.doxygen.Project
+HTML_DYNAMIC_SECTIONS = NO
+CHM_FILE =
+HHC_LOCATION =
+GENERATE_CHI = NO
+BINARY_TOC = NO
+TOC_EXPAND = NO
+DISABLE_INDEX = NO
+ENUM_VALUES_PER_LINE = 4
+GENERATE_TREEVIEW = NO
+TREEVIEW_WIDTH = 250
+#---------------------------------------------------------------------------
+# configuration options related to the LaTeX output
+#---------------------------------------------------------------------------
+GENERATE_LATEX = YES
+LATEX_OUTPUT = latex
+LATEX_CMD_NAME = latex
+MAKEINDEX_CMD_NAME = makeindex
+COMPACT_LATEX = YES # NO
+PAPER_TYPE = a4wide
+EXTRA_PACKAGES =
+LATEX_HEADER =
+PDF_HYPERLINKS = YES
+USE_PDFLATEX = YES
+LATEX_BATCHMODE = NO
+LATEX_HIDE_INDICES = NO
+#---------------------------------------------------------------------------
+# configuration options related to the RTF output
+#---------------------------------------------------------------------------
+GENERATE_RTF = NO
+RTF_OUTPUT = rtf
+COMPACT_RTF = NO
+RTF_HYPERLINKS = NO
+RTF_STYLESHEET_FILE =
+RTF_EXTENSIONS_FILE =
+#---------------------------------------------------------------------------
+# configuration options related to the man page output
+#---------------------------------------------------------------------------
+GENERATE_MAN = NO
+MAN_OUTPUT = man
+MAN_EXTENSION = .3
+MAN_LINKS = NO
+#---------------------------------------------------------------------------
+# configuration options related to the XML output
+#---------------------------------------------------------------------------
+GENERATE_XML = NO
+XML_OUTPUT = xml
+XML_SCHEMA =
+XML_DTD =
+XML_PROGRAMLISTING = YES
+#---------------------------------------------------------------------------
+# configuration options for the AutoGen Definitions output
+#---------------------------------------------------------------------------
+GENERATE_AUTOGEN_DEF = NO
+#---------------------------------------------------------------------------
+# configuration options related to the Perl module output
+#---------------------------------------------------------------------------
+GENERATE_PERLMOD = NO
+PERLMOD_LATEX = NO
+PERLMOD_PRETTY = YES
+PERLMOD_MAKEVAR_PREFIX =
+#---------------------------------------------------------------------------
+# Configuration options related to the preprocessor
+#---------------------------------------------------------------------------
+ENABLE_PREPROCESSING = YES
+MACRO_EXPANSION = NO
+EXPAND_ONLY_PREDEF = NO
+SEARCH_INCLUDES = YES
+INCLUDE_PATH =
+INCLUDE_FILE_PATTERNS =
+PREDEFINED = WIN32 NTLM USE_LZO ENABLE_FRAGMENT P2MP P2MP_SERVER USE_CRYPTO USE_SSL ENABLE_PLUGIN ENABLE_MANAGEMENT ENABLE_OCC HAVE_GETTIMEOFDAY
+EXPAND_AS_DEFINED =
+SKIP_FUNCTION_MACROS = YES
+#---------------------------------------------------------------------------
+# Configuration::additions related to external references
+#---------------------------------------------------------------------------
+TAGFILES =
+GENERATE_TAGFILE =
+ALLEXTERNALS = NO
+EXTERNAL_GROUPS = YES
+PERL_PATH = /usr/bin/perl
+#---------------------------------------------------------------------------
+# Configuration options related to the dot tool
+#---------------------------------------------------------------------------
+CLASS_DIAGRAMS = NO
+MSCGEN_PATH =
+HIDE_UNDOC_RELATIONS = YES
+HAVE_DOT = YES
+CLASS_GRAPH = YES
+COLLABORATION_GRAPH = YES
+GROUP_GRAPHS = YES
+UML_LOOK = NO
+TEMPLATE_RELATIONS = NO
+INCLUDE_GRAPH = YES
+INCLUDED_BY_GRAPH = YES
+CALL_GRAPH = NO # YES
+CALLER_GRAPH = NO # YES
+GRAPHICAL_HIERARCHY = YES
+DIRECTORY_GRAPH = YES
+DOT_IMAGE_FORMAT = png
+DOT_PATH = "/usr/bin/dot"
+DOTFILE_DIRS =
+DOT_GRAPH_MAX_NODES = 50
+MAX_DOT_GRAPH_DEPTH = 1000
+DOT_TRANSPARENT = YES
+DOT_MULTI_TARGETS = NO
+GENERATE_LEGEND = YES
+DOT_CLEANUP = YES
+#---------------------------------------------------------------------------
+# Configuration::additions related to the search engine
+#---------------------------------------------------------------------------
+SEARCHENGINE = NO