/*
  *  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
  * 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 mbed TLS 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 mbed TLS, the Havege random number generator is used. For details, see
  * the mbed TLS 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.
  */