OpenVPN source code documentation

This documentation describes the internal structure of OpenVPN. It was automatically generated from specially formatted comment blocks in OpenVPN's source code using Doxygen. (See http://www.stack.nl/~dimitri/doxygen/ for more information on Doxygen)

The Modules section below gives an introduction into the high-level module concepts used throughout this documentation. The Related Pages section below describes various special subjects related to OpenVPN's implementation which are discussed in the related pages section.

Modules

For the purpose of describing the internal structure of OpenVPN, this documentation and the underlying source code has been broken up into a number of conceptually well-defined parts, known as modules. Each module plays a specific role within the OpenVPN process, and in most cases each module has a clear interfacing strategy for interacting with other modules.

The following modules have been defined:

• Driver module:
  • The Main Event Loop: this module drives the event handling of OpenVPN. It implements various types of select-loop which wait until an event happens, and then delegate the handling of that event to the appropriate module.
• Network interface modules:
  • The External Multiplexer: this module sends and receives packets to and from remote OpenVPN peers over the external network interface. It also takes care of demultiplexing received packets to their appropriate VPN tunnel and splitting control channel and data channel packets.
  • The Internal Multiplexer: this module sends and receives packets to and from locally reachable posts over the virtual tun/tap network interface. It also takes care of determining through which VPN tunnel a received packet must be sent to reach its destination.
• Control channel modules:
  • The Reliability Layer: this module offers a reliable and sequential transport layer for control channel messages.
  • The Control Channel TLS module: this module offers a secure encapsulation of control channel messages using the TLS protocol.
  • The Control Channel Processor: his module manages the setup, maintenance, and shut down of VPN tunnels.
• Data channel modules:
  • The Data Channel Control module: this module controls the processing of data channel packets and, depending on the settings of the packet's VPN tunnel, passes the packet to the three modules below for handling.
  • The Data Channel Crypto module: this module performs security operations on data channel packets.
  • The Data Channel Fragmentation module: this module offers fragmentation of data channel packets larger than the VPN tunnel's MTU.
  • The Data Channel Compression module: this module offers compression of data channel packets.

Example event: receiving a packet

OpenVPN handles many types of events during operation. These include external events, such as network traffic being received, and internal events, such as a key session timing out causing renegotiation. An example event, receiving a packet over the network, is described here together with which modules play what roles:

1. The Main Event Loop detects that a packet can be read from the external or the virtual tun/tap network interface.
2. The Main Event Loop calls the External Multiplexer or Internal Multiplexer to read and process the packet.
3. The multiplexer module determines the type of packet and its destination, and passes the packet on to the appropriate handling module:
   • A control channel packet received by the External Multiplexer is passed on through the Reliability Layer and the Control Channel TLS module to the Control Channel Processor.
   • A data channel packet received by either multiplexer module is passed on to the Data Channel Control module.
4. The packet is processed by the appropriate control channel or data channel modules.
5. If, after processing the packet, a resulting packet is generated that needs to be sent to a local or remote destination, it is given to the External Multiplexer or Internal Multiplexer for sending.
6. If a packet is waiting to be sent by either multiplexer module and the Main Event Loop detects that data can be written to the associated network interface, it calls the multiplexer module to send the packet.

Related pages

This documentation includes a number of descriptions of various aspects of OpenVPN and its implementation. These are not directly related to one module, function, or data structure, and are therefore listed separately under "Related Pages".

Data channel key generation

The Data channel key generation related page describes how, during VPN tunnel setup and renegotiation, OpenVPN peers generate and exchange the key material required for the symmetric encryption/decryption and HMAC signing/verifying security operations performed on data channel packets.

VPN tunnel state

The Structure of VPN tunnel state storage related page describes how an OpenVPN process manages the state information associated with its active VPN tunnels.

Network protocol

The Network protocol related page describes the format and content of VPN tunnel packets exchanged between OpenVPN peers.

Memory management

The Memory management strategies related page gives a brief introduction into OpenVPN's memory buffer library and garbage collection facilities.