From 5fc5d37330d3535a0f421632694d1e7918fc22d7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Parm=C3=A9nides=20GV?= Date: Tue, 8 Apr 2014 11:38:09 +0200 Subject: Compiles correctly: app/build-native + gradle. --- app/openvpn/doc/doxygen/doc_key_generation.h | 153 +++++++++++++++++++++++++++ 1 file changed, 153 insertions(+) create mode 100644 app/openvpn/doc/doxygen/doc_key_generation.h (limited to 'app/openvpn/doc/doxygen/doc_key_generation.h') diff --git a/app/openvpn/doc/doxygen/doc_key_generation.h b/app/openvpn/doc/doxygen/doc_key_generation.h new file mode 100644 index 00000000..903a4652 --- /dev/null +++ b/app/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 From 3c3421afd8f74a3aa8d1011de07a8c18f9549210 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Parm=C3=A9nides=20GV?= Date: Tue, 8 Apr 2014 12:04:17 +0200 Subject: Rename app->bitmask_android This way, gradle commands generate apks correctly named. --- app/openvpn/doc/doxygen/doc_key_generation.h | 153 --------------------------- 1 file changed, 153 deletions(-) delete mode 100644 app/openvpn/doc/doxygen/doc_key_generation.h (limited to 'app/openvpn/doc/doxygen/doc_key_generation.h') diff --git a/app/openvpn/doc/doxygen/doc_key_generation.h b/app/openvpn/doc/doxygen/doc_key_generation.h deleted file mode 100644 index 903a4652..00000000 --- a/app/openvpn/doc/doxygen/doc_key_generation.h +++ /dev/null @@ -1,153 +0,0 @@ -/* - * 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 From 1684c8f398922065a97e7da4dac4ac6a33cc5218 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Parm=C3=A9nides=20GV?= Date: Wed, 9 Apr 2014 16:03:55 +0200 Subject: Back to the standard "app" module. This return to "app" instead of "bitmask_android" is due to this reading: https://developer.android.com/sdk/installing/studio-build.html#projectStructure I'll have to tweak the final apk name in build.gradle. --- app/openvpn/doc/doxygen/doc_key_generation.h | 153 +++++++++++++++++++++++++++ 1 file changed, 153 insertions(+) create mode 100644 app/openvpn/doc/doxygen/doc_key_generation.h (limited to 'app/openvpn/doc/doxygen/doc_key_generation.h') diff --git a/app/openvpn/doc/doxygen/doc_key_generation.h b/app/openvpn/doc/doxygen/doc_key_generation.h new file mode 100644 index 00000000..903a4652 --- /dev/null +++ b/app/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