/*
 *  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
 * 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
 */