summaryrefslogtreecommitdiff
path: root/openvpn/doc/doxygen/doc_control_tls.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_control_tls.h
Initial import
Diffstat (limited to 'openvpn/doc/doxygen/doc_control_tls.h')
-rw-r--r--openvpn/doc/doxygen/doc_control_tls.h105
1 files changed, 105 insertions, 0 deletions
diff --git a/openvpn/doc/doxygen/doc_control_tls.h b/openvpn/doc/doxygen/doc_control_tls.h
new file mode 100644
index 00000000..aba55f77
--- /dev/null
+++ b/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
+ */