From 3e4d8f433239c40311037616b1b8833a06651ae0 Mon Sep 17 00:00:00 2001 From: Arne Schwabe Date: Mon, 16 Apr 2012 19:21:14 +0200 Subject: Initial import --- openvpn/doc/doxygen/doc_key_generation.h | 153 +++++++++++++++++++++++++++++++ 1 file changed, 153 insertions(+) create mode 100644 openvpn/doc/doxygen/doc_key_generation.h (limited to 'openvpn/doc/doxygen/doc_key_generation.h') diff --git a/openvpn/doc/doxygen/doc_key_generation.h b/openvpn/doc/doxygen/doc_key_generation.h new file mode 100644 index 00000000..903a4652 --- /dev/null +++ b/openvpn/doc/doxygen/doc_key_generation.h @@ -0,0 +1,153 @@ +/* + * 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. + * + * + * 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 + * Key generation documentation file. + */ + +/** + * @page key_generation Data channel %key generation + * + * This section describes how OpenVPN peers generate and exchange %key + * material necessary for the security operations performed on data + * channel packets. + * + * The %key generation and exchange process between OpenVPN client and + * server occurs every time data channel security parameters are + * negotiated, for example during the initial setup of a VPN tunnel or + * when the active security parameters expire. In source code terms, this + * is when a new key_state structure is initialized. + * + * @section key_generation_method Key methods + * + * OpenVPN supports two different ways of generating and exchanging %key + * material between client and server. These are known as %key method 1 + * and %key method 2. %Key method 2 is the recommended method. Both are + * explained below. + * + * @subsection key_generation_method_1 Key method 1 + * + * -# Each host generates its own random material. + * -# Each host uses its locally generated random material as %key data + * for encrypting and signing packets sent to the remote peer. + * -# Each host then sends its random material to the remote peer, so that + * the remote peer can use that %key data for authenticating and + * decrypting received packets. + * + * @subsection key_generation_method_2 Key method 2 + * + * -# The client generates random material in the following amounts: + * - Pre-master secret: 48 bytes + * - Client's PRF seed for master secret: 32 bytes + * - Client's PRF seed for %key expansion: 32 bytes + * -# The client sends its share of random material to the server. + * -# The server generates random material in the following amounts: + * - Server's PRF seed for master secret: 32 bytes + * - Server's PRF seed for %key expansion: 32 bytes + * -# The server computes the %key expansion using its own and the + * client's random material. + * -# The server sends its share of random material to the client. + * -# The client computes the %key expansion using its own and the + * server's random material. + * + * %Key method 2 %key expansion is performed by the \c + * generate_key_expansion() function. Please refer to its source code for + * details of the %key expansion process. + * + * @subsection key_generation_random Source of random material + * + * OpenVPN uses the either the OpenSSL library or the PolarSSL library as its + * source of random material. + * + * In OpenSSL, the \c RAND_bytes() function is called + * to supply cryptographically strong pseudo-random data. The following links + * contain more information on this subject: + * - For OpenSSL's \c RAND_bytes() function: + * http://www.openssl.org/docs/crypto/RAND_bytes.html + * - For OpenSSL's pseudo-random number generating system: + * http://www.openssl.org/docs/crypto/rand.html + * - For OpenSSL's support for external crypto modules: + * http://www.openssl.org/docs/crypto/engine.html + * + * In PolarSSL, the Havege random number generator is used. For details, see + * the PolarSSL documentation. + * + * @section key_generation_exchange Key exchange: + * + * The %key exchange process is initiated by the OpenVPN process running + * in client mode. After the initial three-way handshake has successfully + * completed, the client sends its share of random material to the server, + * after which the server responds with its part. This process is + * depicted below: + * +@verbatim + Client Client Server Server + State Action Action State +---------- -------------------- -------------------- ---------- + + ... waiting until three-way handshake complete ... +S_START S_START + key_method_?_write() + send to server --> --> --> --> receive from client +S_SENT_KEY key_method_?_read() + S_GOT_KEY + key_method_?_write() + receive from server <-- <-- <-- <-- send to client + key_method_?_read() S_SENT_KEY +S_GOT_KEY + ... waiting until control channel fully synchronized ... +S_ACTIVE S_ACTIVE +@endverbatim + * + * For more information about the client and server state values, see the + * \link control_processor Control Channel Processor module\endlink. + * + * Depending on which %key method is used, the \c ? in the function names + * of the diagram above is a \c 1 or a \c 2. For example, if %key method + * 2 is used, that %key exchange would be started by the client calling \c + * key_method_2_write(). These functions are called from the \link + * control_processor Control Channel Processor module's\endlink \c + * tls_process() function and control the %key generation and exchange + * process as follows: + * - %Key method 1: + * - \c key_method_1_write(): generate random material locally, and load + * as "sending" keys. + * - \c key_method_1_read(): read random material received from remote + * peer, and load as "receiving" keys. + * - %Key method 2: + * - \c key_method_2_write(): generate random material locally, and if + * in server mode generate %key expansion. + * - \c key_method_2_read(): read random material received from remote + * peer, and if in client mode generate %key expansion. + * + * @subsection key_generation_encapsulation Transmission of key material + * + * The OpenVPN client and server communicate with each other through their + * control channel. This means that all of the data transmitted over the + * network, such as random material for %key generation, is encapsulated + * in a TLS layer. For more details, see the \link control_tls Control + * Channel TLS module\endlink documentation. + */ -- cgit v1.2.3