Merge branch 'debian/experimental-2.5'

1 files changed, 161 insertions, 0 deletions

diff --git a/doc/doxygen/doc_mainpage.h b/doc/doxygen/doc_mainpage.h
new file mode 100644
index 0000000..6016d07
--- /dev/null
+++ b/doc/doxygen/doc_mainpage.h
@@ -0,0 +1,161 @@
+/*
+ *  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-2018 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; if not, write to the Free Software Foundation, Inc.,
+ *  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+ */
+
+/**
+ * @file
+ * Main page documentation file.
+ */
+
+/**
+ * @mainpage OpenVPN 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.
+ */