summaryrefslogtreecommitdiff
path: root/openvpn/doc/doxygen/doc_compression.h
diff options
context:
space:
mode:
authorArne Schwabe <arne@rfc2549.org>2012-04-16 19:21:14 +0200
committerArne Schwabe <arne@rfc2549.org>2012-04-16 19:21:14 +0200
commit3e4d8f433239c40311037616b1b8833a06651ae0 (patch)
tree98ab7fce0d011d34677b0beb762d389cb5c39199 /openvpn/doc/doxygen/doc_compression.h
Initial import
Diffstat (limited to 'openvpn/doc/doxygen/doc_compression.h')
-rw-r--r--openvpn/doc/doxygen/doc_compression.h92
1 files changed, 92 insertions, 0 deletions
diff --git a/openvpn/doc/doxygen/doc_compression.h b/openvpn/doc/doxygen/doc_compression.h
new file mode 100644
index 00000000..bdc4a7ed
--- /dev/null
+++ b/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/
+ */