summaryrefslogtreecommitdiff
path: root/openvpn/doc/doxygen/doc_protocol_overview.h
diff options
context:
space:
mode:
authorArne Schwabe <arne@rfc2549.org>2012-04-16 19:21:14 +0200
committerArne Schwabe <arne@rfc2549.org>2012-04-16 19:21:14 +0200
commit3e4d8f433239c40311037616b1b8833a06651ae0 (patch)
tree98ab7fce0d011d34677b0beb762d389cb5c39199 /openvpn/doc/doxygen/doc_protocol_overview.h
Initial import
Diffstat (limited to 'openvpn/doc/doxygen/doc_protocol_overview.h')
-rw-r--r--openvpn/doc/doxygen/doc_protocol_overview.h199
1 files changed, 199 insertions, 0 deletions
diff --git a/openvpn/doc/doxygen/doc_protocol_overview.h b/openvpn/doc/doxygen/doc_protocol_overview.h
new file mode 100644
index 00000000..26fed331
--- /dev/null
+++ b/openvpn/doc/doxygen/doc_protocol_overview.h
@@ -0,0 +1,199 @@
+/*
+ * 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. <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 (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 Network protocol overview documentation file.
+ */
+
+/**
+ * @page network_protocol OpenVPN's network protocol
+ *
+ * Description of packet structure in OpenVPN's network protocol.
+ *
+ * This document describes the structure of packets exchanged between
+ * OpenVPN peers. It is based on the protocol description in the \c ssl.h
+ * file.
+ *
+ * @section network_protocol_external Outer structure of packets exchanged between OpenVPN peers
+ *
+ * VPN tunnel packets are transported between OpenVPN peers using the UDP
+ * or TCP protocols. Their structure is described below.
+ *
+ * @subsection network_protocol_external_structure External packet structure
+ *
+ * - packet length (16 bits, unsigned) [TCP-mode only]: always sent as
+ * plain text. Since TCP is a stream protocol, this packet length
+ * defines the packetization of the stream.
+ * - packet opcode and key_id (8 bits) [TLS-mode only]:
+ * - package message type (high 5 bits)
+ * - key_id (low 3 bits): the key_id refers to an already negotiated
+ * TLS session. OpenVPN seamlessly renegotiates the TLS session by
+ * using a new key_id for the new session. Overlap (controlled by
+ * user definable parameters) between old and new TLS sessions is
+ * allowed, providing a seamless transition during tunnel operation.
+ * - payload (n bytes)
+ *
+ * @subsection network_protocol_external_types Message types
+ *
+ * The type of a VPN tunnel packet is indicated by its opcode. The
+ * following describes the various opcodes available.
+ *
+ * - Control channel messages:
+ * - \c P_CONTROL_HARD_RESET_CLIENT_V1 -- %Key method 1, initial %key
+ * from client, forget previous state.
+ * - \c P_CONTROL_HARD_RESET_SERVER_V1 -- %Key method 1, initial %key
+ * from server, forget previous state.
+ * - \c P_CONTROL_HARD_RESET_CLIENT_V2 -- %Key method 2, initial %key
+ * from client, forget previous state.
+ * - \c P_CONTROL_HARD_RESET_SERVER_V2 -- %Key method 2, initial %key
+ * from server, forget previous state.
+ * - \c P_CONTROL_SOFT_RESET_V1 -- New %key, with a graceful
+ * transition from old to new %key in the sense that a transition
+ * window exists where both the old or new key_id can be used.
+ * - \c P_CONTROL_V1 -- Control channel packet (usually TLS
+ * ciphertext).
+ * - \c P_ACK_V1 -- Acknowledgement for control channel packets
+ * received.
+ * - Data channel messages:
+ * - \c P_DATA_V1 -- Data channel packet containing data channel
+ * ciphertext.
+ *
+ * @subsection network_protocol_external_key_id Session IDs and Key IDs
+ *
+ * OpenVPN uses two different forms of packet identifiers:
+ * - The first form is 64 bits and is used for all control channel
+ * messages. This form is referred to as a \c session_id.
+ * - Data channel messages on the other hand use a shortened form of 3
+ * bits for efficiency reasons since the vast majority of OpenVPN
+ * packets in an active tunnel will be data channel messages. This
+ * form is referred to as a \c key_id.
+ *
+ * The control and data channels use independent packet-id sequences,
+ * because the data channel is an unreliable channel while the control
+ * channel is a %reliable channel. Each use their own independent HMAC
+ * keys.
+ *
+ * @subsection network_protocol_external_reliable Control channel reliability layer
+ *
+ * Control channel messages (\c P_CONTROL_* and \c P_ACK_* message types)
+ * are TLS ciphertext packets which have been encapsulated inside of a
+ * reliability layer. The reliability layer is implemented as a
+ * straightforward acknowledge and retransmit model.
+ *
+ * Acknowledgments of received messages can be encoded in either the
+ * dedicated \c P_ACK_* record or they can be prepended to a \c
+ * P_CONTROL_* message.
+ *
+ * See the \link reliable Reliability Layer\endlink module for a detailed
+ * description.
+ *
+ * @section network_protocol_control Structure of control channel messages
+ *
+ * @subsection network_protocol_control_ciphertext Structure of ciphertext control channel messages
+ *
+ * Control channel packets in ciphertext form consist of the following
+ * parts:
+ *
+ * - local \c session_id (random 64 bit value to identify TLS session).
+ * - HMAC signature of entire encapsulation header for HMAC firewall
+ * [only if \c --tls-auth is specified] (usually 16 or 20 bytes).
+ * - packet-id for replay protection (4 or 8 bytes, includes sequence
+ * number and optional \c time_t timestamp).
+ * - acknowledgment packet-id array length (1 byte).
+ * - acknowledgment packet-id array (if length > 0).
+ * - acknowledgment remote session-id (if length > 0).
+ * - packet-id of this message (4 bytes).
+ * - TLS payload ciphertext (n bytes) (only for \c P_CONTROL_V1).
+ *
+ * Note that when \c --tls-auth is used, all message types are protected
+ * with an HMAC signature, even the initial packets of the TLS handshake.
+ * This makes it easy for OpenVPN to throw away bogus packets quickly,
+ * without wasting resources on attempting a TLS handshake which will
+ * ultimately fail.
+ *
+ * @subsection network_protocol_control_key_methods Control channel key methods and
+ *
+ * Once the TLS session has been initialized and authenticated, the TLS
+ * channel is used to exchange random %key material for bidirectional
+ * cipher and HMAC keys which will be used to secure data channel packets.
+ * OpenVPN currently implements two %key methods. %Key method 1 directly
+ * derives keys using random bits obtained from the \c RAND_bytes()
+ * OpenSSL function. %Key method 2 mixes random %key material from both
+ * sides of the connection using the TLS PRF mixing function. %Key method
+ * 2 is the preferred method and is the default for OpenVPN 2.0.
+ *
+ * The @ref key_generation "Data channel key generation" related page
+ * describes the %key methods in more detail.
+ *
+ * @subsection network_protocol_control_plaintext Structure of plaintext control channel messages
+ *
+ * - %Key method 1:
+ * - Cipher %key length in bytes (1 byte).
+ * - Cipher %key (n bytes).
+ * - HMAC %key length in bytes (1 byte).
+ * - HMAC %key (n bytes).
+ * - %Options string (n bytes, null terminated, client/server %options
+ * string should match).
+ * - %Key method 2:
+ * - Literal 0 (4 bytes).
+ * - %Key method (1 byte).
+ * - \c key_source structure (\c key_source.pre_master only defined
+ * for client -> server).
+ * - %Options string length, including null (2 bytes).
+ * - %Options string (n bytes, null terminated, client/server %options
+ * string must match).
+ * - [The username/password data below is optional, record can end at
+ * this point.]
+ * - Username string length, including null (2 bytes).
+ * - Username string (n bytes, null terminated).
+ * - Password string length, including null (2 bytes).
+ * - Password string (n bytes, null terminated).
+ *
+ * @section network_protocol_data Structure of data channel messages
+ *
+ * @subsection network_protocol_data_ciphertext Structure of ciphertext data channel messages
+ *
+ * The P_DATA_* payload represents encrypted, encapsulated tunnel packets
+ * which tend to be either IP packets or Ethernet frames. This is
+ * essentially the "payload" of the VPN.
+ *
+ * Data channel packets in ciphertext form consist of the following parts:
+ * - HMAC of ciphertext IV + ciphertext (if not disabled by \c --auth
+ * none).
+ * - Ciphertext IV (size is cipher-dependent, if not disabled by \c
+ * --no-iv).
+ * - Tunnel packet ciphertext.
+ *
+ * @subsection network_protocol_data_plaintext Structure of plaintext data channel messages
+ *
+ * Data channel packets in plaintext form consist of the following parts:
+ * - packet-id (4 or 8 bytes, if not disabled by --no-replay).
+ * - In TLS mode, 4 bytes are used because the implementation can
+ * force a TLS renegotation before \c 2^32 packets are sent.
+ * - In pre-shared %key mode, 8 bytes are used (sequence number and \c
+ * time_t value) to allow long-term %key usage without packet-id
+ * collisions.
+ * - User plaintext (n bytes).
+ */