1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
|
/*
* 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
*/
|
