summaryrefslogtreecommitdiff
path: root/doc/doxygen/doc_mainpage.h
diff options
context:
space:
mode:
authorBernhard Schmidt <berni@debian.org>2020-09-01 16:52:17 +0200
committerBernhard Schmidt <berni@debian.org>2020-09-01 16:52:17 +0200
commit9fc3b98112217f2d92a67977dbde0987cc7a1803 (patch)
tree29fcc8654ee65d9dd89ade797bea2f3d9dfd9cfd /doc/doxygen/doc_mainpage.h
parenta8758c0e03eed188dcb9da0e4fd781a67c25bf1e (diff)
parent69b02b1f7fd609d84ace13ab04697158de2418a9 (diff)
Merge branch 'debian/experimental-2.5'
Diffstat (limited to 'doc/doxygen/doc_mainpage.h')
-rw-r--r--doc/doxygen/doc_mainpage.h161
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.
+ */