OpenVPN IPv6 Tunnel Broker Guide

Acknowledgements go to people from the University of Erlangen for inspiring us with the idea to use OpenVPN for a tunnel broker service. Thank you, guys, it works like a charm!

Table of Contents:

1. Introduction
2. Definition of the term "tunnel broker"
3. Tunnel broker clients
4. Installation of tunnel broker components
   1. Installation of OpenSSL CA
      • Creating an openssl.cnf
      • Creating keys and certificates for your CA
   2. Installation of OpenVPN server
   3. Installation of user database
5. Functionality of tunnel broker and its components
   1. OpenSSL CA
   2. OpenVPN server
6. Routing configuration
7. Sample server configuration
8. Sample subnet client configuration
9. Management (and download of JOIN tunnel broker scripts)
10. Client user guide
11. Appendix

This document describes the process of setting up an OpenVPN based IPv6 tunnel broker to enable ISP-independent IPv6 connectivity that is authenticated, secure, stable, and IPv4 source-address independent. It provides an insight into necessary configurations, gives an overview over administrative tasks and possible caveats.

Important notice for Client users: This document deals with the construction of a whole tunnel broker. For instructions on how to install the client software, please read the paragraph Client user guide.

Back to top

Fig.: Schema of a typical tunnel broker

There are many different definitions of the term "tunnel broker". To clarify what this term means in the context of this document, it is necessary to summarise the tasks that an OpenVPN-based tunnel broker should fulfil:

• provide IPv6 connectivity to a subscribed client
• manage a set of X.509 certificates and keys and a certification authority (CA)
• check authorisation of a client
• assign a fixed IPv6 prefix to each client (either /64 or /128 for a single address)
• adjust routing according to prefix-/address-assignment
• on subscription of a new client, create client configuration for server and as archive file for client
• handle subscription information

To handle all of the above tasks, the tunnel broker needs to consist at least of the following components:

• OpenVPN server(s)
• OpenSSL certification authority (CA)
• client database
• dedicated router for clients (is identical to OpenVPN server)
• IPv6 infrastructure to route IPv6 traffic to and from clients

Fig.: Interaction of tunnel broker components

The components in detail may look like this:

• OpenVPN server: powerful Linux or *BSD PC with latest OpenVPN software (at the time of writing of this document, this is a version that is more recent than 1.6_rc2); JOIN utilise a Linux server for their installation
• OpenSSL CA: may be any kind of machine with an OpenSSL installation which provides the openssl-binary to create X.509 keys and certificates
• Client database: almost any form of database for holding information about clients ranging from simple text file to dedicated database systems
• Dedicated IPv6 router: normally the same Linux or *BSD machine that runs the OpenVPN server; routes need to be adjusted on that particular machine
• IPv6 infrastructure: your institution's IPv6 backbone

The above components form what we call a "tunnel broker" for the remainder of this document. It is clear that for the sake of scalability, many of the services (e.g. the OpenVPN server) may be spread across numerous different servers. This is not difficult to achieve and can easily be implemented.

"2. Definition of the term "tunnel broker""

Back to top

A very important part of a tunnel broker are -- obviously -- the tunnel broker clients. To understand what functionality a tunnel broker needs to implement, it is necessary to have a look at the different types of clients that need to be connected to the tunnel broker.

First of all, one needs to identify the network topology that a potential client will most likely reside in. It is assumed that any tunnel broker client only has native global IPv4 connectivity and no global IPv6 connectivity. From a practical viewpoint, having global IPv6 connectivity additionally to the tunnel broker IPv6 connectivity is possible. However, this scenario is not a standard scenario where an IPv6 tunnel broker would be employed. Additionally, effects that are imposed by having two types of global connectivity still need to be investigated. No serious problems are to be expected but tests have not yet been conducted to verify this.

One differentiates between two types of clients that reside in two different network topologies for this particular OpenVPN IPv6 tunnel broker:

• Hermit client: a lone client that will be assigned a /128 address
• Subnet client: a client that will be assigned a /64 prefix and that may act as a router for a subnet where it may announce this /64 prefix to other hosts that use the client as their default router

Fig.: Types of tunnel broker clients

Though the OpenVPN client runs on many different platforms and hence a tunnel broker that is based on OpenVPN should be able to accommodate quite a large number of different client OS', this document will only deal with Linux and Windows clients for now, since those are the client OS' that haven been tested as tunnel broker clients so far. However, extending the support to other client OS' should be trivial.

"3. Tunnel broker clients"

Back to top

The upcoming paragraphs deal with the software and hardware installation of all the necessary tunnel broker components. Please note that in most cases this document will not list the exact and detailed installation information of a software if the documentation that comes with the respective software packages is sufficient to explain the process. Since most of the software installation is trivial, this will not pose any problems.

To further facilitate the understanding of the concepts and the installation (especially if the scripts provided by JOIN are to be used for managing the tunnel broker), it is assumed that the CA, the OpenVPN server and the database are located on the same Linux server. The abstraction of the concept to spread these services across several servers and perhaps different operating systems is a trivial step.

To set up an OpenSSL certification authority it is sufficient to install the OpenSSL package on your Linux distribution (check that the openssl-binary is present and executable as root). The more difficult step is to create an appropriate configuration file and to create the necessary CA certificates and keys. This document will present a sample openssl.cnf configuration file that is self-explanatory and that may be edited to fit individual needs. It will also list the necessary steps to create all CA keys and certificates.

The following listing shows the openssl.cnf that JOIN uses for its OpenSSL CA:

#
# OpenSSL example configuration file.
#
HOME                    = .
RANDFILE                = $ENV::HOME/.rnd
oid_section             = new_oids
 
[ new_oids ]
 
[ ca ]
default_ca      = CA_default
 
[ CA_default ]
 
dir             = /usr/local/etc/openvpn/ssl    	# Adjust this!
certs           = $dir
crl_dir         = $dir
database        = $dir/index.txt
new_certs_dir   = $dir
 
certificate     = $dir/tmp-ca.crt       		# Adjust this!
serial          = $dir/serial
crl             = $dir/crl.pem
private_key     = $dir/tmp-ca.key       		# Adjust this!
RANDFILE        = $dir/.rand
 
x509_extensions = usr_cert
 
name_opt        = ca_default
cert_opt        = ca_default
default_days    = 365                   		# Adjust this!
default_crl_days= 30
default_md      = md5
preserve        = no
policy          = policy_match
 
[ policy_match ]
countryName             = match
stateOrProvinceName     = match
organizationName        = match
organizationalUnitName  = optional
commonName              = supplied
emailAddress            = optional
 
[ policy_anything ]
countryName             = optional
stateOrProvinceName     = optional
localityName            = optional
organizationName        = optional
organizationalUnitName  = optional
commonName              = supplied
emailAddress            = optional
 
[ req ]
default_bits            = 1024
default_keyfile         = privkey.pem
distinguished_name      = req_distinguished_name
attributes              = req_attributes
x509_extensions = v3_ca
string_mask = nombstr
 
[ req_distinguished_name ]
countryName                     = Country Name (2 letter code)
countryName_default             = DE    		# Adjust this!
countryName_min                 = 2
countryName_max                 = 2
 
stateOrProvinceName             = State or Province Name (full name)
stateOrProvinceName_default     = Nordrhein-Westfalen   # Adjust this!
 
localityName                    = Locality Name (eg, city)
localityName_default            = Muenster              # Adjust this!
 
0.organizationName              = Organization Name (eg, company)
0.organizationName_default      = ZIV, WWU Muenster     # Adjust this!
 
organizationalUnitName          = Organizational Unit Name (eg, section)
organizationalUnitName_default  = JOIN-Projekt          # Adjust this!
 
commonName                      = Common Name (eg, YOUR name)
commonName_max                  = 64
 
emailAddress                    = Email Address
emailAddress_max                = 64
 
[ req_attributes ]
challengePassword               = A challenge password
challengePassword_min           = 4
challengePassword_max           = 20
 
unstructuredName                = An optional company name
 
[ usr_cert ]
basicConstraints=CA:FALSE
nsComment                       = "OpenSSL Generated Certificate"
subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid,issuer:always
 
[ v3_req ]
basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment
 
[ v3_ca ]
subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid:always,issuer:always
basicConstraints = CA:true
 
[ crl_ext ]
authorityKeyIdentifier=keyid:always,issuer:always

Please note that you need to include "-config openssl.cnf" (where openssl.cnf is to be given with full path if not located in current directory) in every call of the openssl-binary. If you use the management scripts provided by JOIN, you need to adjust the variable pointing to your OpenSSL-installation.

Attention: You must initialise the files index.txt and serial when setting up the CA. You can create index.txt as an empty file and serial with the content "01". Additionally, you need a DH-hash that you can create with the command openssl dhparam -out /usr/local/etc/openvpn/ssl/dh1024.pem 1024. You can use the script setup-ca.sh from the JOIN configuration script package to do this task.

Important: This document shows a rather lax use of a CA. Ideally, you should take the process of running a CA rather seriously, especially if you want to hold people liable for the abuse of your tunnel broker. If you already have an established CA, please try to use it for creating client and server certificates. This will add to the security of your tunnel broker. Please use "your own private little CA" just for experimental purposes or if you think that you can afford to keep the security rather lax.

To create your own CA keys and certificates, run the following command:

openssl req -days 365 -new -x509 -keyout tmp-ca.key \
	-out tmp-ca.crt -config openssl.cnf

This command will create the secret key called "tmp-ca.key" and the certificate "tmp-ca.crt". Please note that the notation "tmp-ca.*" is intentional to make administrators aware that they are dealing with an experimental or temporary CA. Please make sure that the permissions for the secret key do not allow it to be read by any other user than the one who created it ("chmod 600 tmp-ca.key").

With these basic steps the setup of the OpenSSL CA is completed.

At the time this document was written, a very recent CVS-version of the OpenVPN software was needed to have all functionality that was necessary for running the OpenVPN based IPv6 tunnel broker. The OpenVPN software can be found at

Please follow the installation instructions for the CVS version on the OpenVPN site. The installation is not expected to pose any problems.

It is assumed that the OpenVPN sources are compiled with the given installation prefix /usr/local which means that the configuration files can be found in /usr/local/etc/openvpn. Naturally, any other prefix works just as well but for the sake of readability, the /usr/local prefix will be used for the remainder of the documentation.

The installation of a user database is completely up to you. The more users need to be accommodated by the tunnel broker, the more sophisticated the user database should be. For testing purposes, a simple text file may suffice.

If you plan to use the administration scripts provided by JOIN, please be aware that the user management is not yet implemented and you might want to integrate the user management part yourself.

Since there are significant differences between each local user database requirement, this document will not deal with the setup of the database in detail.

"4. Installation of tunnel broker components"

Back to top

All components of the tunnel broker serve a particular purpose. To explain the concept behind the tunnel broker, it is necessary to understand why a certain component is needed and what it actually does. This paragraph deals with each component separately and it will later explain how all the components work together and it will explain, what a typical connection by a client looks like from the client's and the server's point of view.

For many tunnel brokers, having some form of access control and authorisation is mandatory. It was one of the prerequisites for JOIN when working on the OpenVPN based tunnel broker. OpenVPN offers a very flexible and secure way of authorising access using X.509 certificates and keys. OpenVPN uses functionality provided by the OpenSSL library (e.g. TLS key exchange). The OpenSSL CA is needed to sign certificates for clients that would like to connect to the tunnel broker.

When a new client subscribes to the tunnel broker service, the following things have to be done:

1. Create an X.509 key and certificate for the client.
2. CA verifies the identity and authorisation of the client to actually use the tunnel broker and then signs the certificate of the client.
3. The CA's certificate is given to both the client and the server. It is used to verify the signature of the X.509 certificates of both client and server when they execute a TLS key exchange.

When a client starts an OpenVPN-connection to the server, the following steps are exercised by client and server:

1. TLS handshake and key exchange is started.
2. Both server and client verify the Common Names of each other's public certificates. Only on a positive verification of the CN the server or client continue the negotiations. (The CN verification can be seen as an initial sanity check.)
3. After the CN verification, the key exchange is started. Server and client verify each other's keys using the CA's certificate to find out if the signatures of the certificates are valid. If yes, both client and server proceed.
4. The server uses the client's certificate to cipher the stream that is sent to the client and it uses OpenSSL functionality to multiplex the tunnel into a UDP/IPv4 stream. The client uses his private key to decrypt the ciphered stream after de-multiplexing it. The client's use of the server's certificate is analogue.

Note: JOIN's OpenVPN based tunnel broker used encrypted tunnel streams in an initial version. However, now it uses the "null" cipher instead of the blowfish block stream cipher. This solves some performance and overhead issues.

The OpenVPN server is the actual heart of the tunnel broker. OpenSSL CA and user database are merely the framework or better say the helper applications that enable a controlled use of OpenVPN for a tunnel broker. This document will not go into deep technical detail. Rather, the most important functions of OpenVPN shall be described here.

The most important function of OpenVPN is obviously to provide some form of tunnel for IPv6 over UDP/IPv4. To understand what OpenVPN does to tunnel, one can have a look at what happens when client connects to an OpenVPN server:

1. Server verifies the identity of the client.
2. OpenVPN creates either a tun interface (P-t-P) or a tap interface (ethernet bridge) on both ends.
3. The tunnel interfaces are configured with IPv6 addresses.
4. The routing on the OpenVPN server is adjusted to route a pre-defined IPv6 prefix to the client via the tunnel interface. The client in turn adjusts its IPv6 default route to use the tunnel interface.

The OpenVPN server and client call external scripts upon establishing a new connection. These scripts are:

• a TLS verification script (used for checking CNs of X.509 certificates)
• an "up" script that calls external programs to configure interfaces and to set up routes or starting certain programs after setting up the tunnel
• a "down" script that may be used to cleanly dispose of the tunnel (end programs etc.)

"5. Functionality of tunnel broker and its components"

Back to top

An important task when setting up and maintaining a tunnel broker is the organisation of the routing. Not only does one have to set up routes to the OpenVPN server which itself has to act as a router, one also needs to dynamically add routes upon a client connection and remove them afterwards. The routing itself is not very complicated but there are a few things that need to be taken into account when planning the routing. Here are a few prerequisites that need to be met for JOIN's tunnel broker:

• A /56 prefix is at the tunnel broker's disposal to assign addresses for clients (either single IPv6 addresses or complete prefixes).
• Subnet clients must be able to freely assign addresses from the /64 prefix they get assigned.
• All clients must be identifiable by their respective addresses (hermit clients) or prefixes (subnet clients).

• The prefix used for JOIN's tunnel broker is 2001:638:500:f100::/56.
• All hermit hosts receive a /128 address coming from the prefix 2001:638:500:f1ff::/64.
• All subnet hosts receive /64 prefixes ranging from 2001:638:500:f101::/64 to 2001:638:500:f1fe::/64.
• The prefix 2001:638:500:f100::/64 is solely used for routing purposes for subnet hosts. Example: for a subnet client that is provided with the prefix 2001:638:500:f1ab::/64, the routing address 2001:638:500:f100::f1ab:1/112 is used for the P-t-P interface on the OpenVPN server's side, the address 2001:638:500:f100::f1ab:2/112 is used on the OpenVPN client's side. This way routes can be assigned uses those routing addresses as Next-Hop. No addresses from 2001:638:500:f1ab::/64 are used and hence the client can freely assign addresses from this prefix locally.
• All clients are assigned the same addresses or prefixes every time they connect. There is a 1:1 mapping between address/prefix and X.509 certificate. This helps to identify tunnel broker clients by they IPv6 addresses.

Fig.: Address assignment and routing configuration for a subnet client

To show how the routing is arranged for several subnet clients, please see the following figure.

Fig.: Routing for several subnet clients

The hermit client case is trivial: the server's local interface gets a fe80::1/64 IP address to have a next-hop address for the client on the other side. A route to the /128 IPv6 address of the client is added via the corresponding tunnel interface.

"6. Routing configuration"

Back to top

To give the reader an idea what a typical server configuration may look like, this chapter will present a number of sample configuration files.

The server needs three mandatory configuration files per client (note: each client has his own server instance with its own configuration; also, each server occupies exactly one UDP port):

• basic configuration file
• TLS verification script
• "up" script to initialise tunnel interface and routing

A sample configuration file looks like this:

daemon server-christian.strauf
dev tun
tun-ipv6
 
up /usr/local/etc/openvpn/server-conf/christian.strauf.up
tls-server
 
log-append /usr/local/etc/openvpn/server-logs/christian.strauf.log
 
dh /usr/local/etc/openvpn/ssl/dh1024.pem
ca /usr/local/etc/openvpn/ssl/tmp-ca.crt
cert /usr/local/etc/openvpn/ssl/servers/christian.strauf.crt
key /usr/local/etc/openvpn/ssl/servers/christian.strauf.key
tls-verify /usr/local/etc/openvpn/server-conf/christian.strauf.tls-verify
 
port 5000
 
persist-tun
ping 15
ping-restart 45
ping-timer-rem
persist-key
  
verb 3

The first part of the configuration file configures the OpenVPN server itself (act as a daemon, use a tun P-t-P interface and optimise multiplexing for IPv6 tunnelling). The second part tells the server where to find the "up" script and the server should authorise connection via TLS. The third part defines where to write log messages. The fourth part tells the server where to find the Diffie Hellmann hash, the CA certificates, the client's public key, the server's private key and the TLS verification script that check's the client certificate's Common Name. The fifth part tells the server which UDP port to use. The sixth part is very important to guarantee the OpenVPN tunnel's stability when used on dial-up links. It tells the tunnel to try to be as persistent as possible by checking the status of the tunnel with regular pings and other techniques. These options also suffice in many cases to help a client to traverse a NAT gateway because the gateway might be able to recognise that there is constant traffic coming in over the same port. The seventh and last part sets the verbosity level of the log messages.

Another important configuration file is the "up" script that is run by the OpenVPN software after the tunnel has been established. The "up" script configures the local tunnel interface and handles the route setup.

#!/bin/bash
 
INTERFACE=$1; shift;
TUN_MTU=$1;   shift;
UDP_MTU=$1;   shift;
LOCAL_IP=$1;  shift;
REMOTE_IP=$1; shift;
MODUS=$1;     shift;
 
ip link set ${INTERFACE} up
ip link set mtu ${TUN_MTU} dev ${INTERFACE}
 
ip -6 addr add 2001:638:500:f100::f101:1/112 dev ${INTERFACE}
ip -6 addr add fe80::f101:1/64 dev ${INTERFACE}
ip -6 route add 2001:638:500:f101::/64 dev ${INTERFACE}
exit 0

The content of the "up" script should be self-explanatory.

"7. Sample server configuration"

Back to top

This paragraph will present a sample subnet client configuration. Since a hermit client's configuration is almost the same, it is easy to deduct the configuration for it from this subnet client's sample configuration.

The basic configuration file of the client that corresponds to the server in the above paragraph looks like the following:

daemon client-christian.strauf
dev tun
tun-ipv6
 
remote corello.uni-muenster.de
 
up /etc/openvpn/christian.strauf.up
 
tls-client
ca /etc/openvpn/tmp-ca.crt
cert /etc/openvpn/christian.strauf.crt
key /etc/openvpn/christian.strauf.key
 
tls-verify /etc/openvpn/tls-verify
 
port 5000
 
persist-tun
ping 15
ping-restart 45
ping-timer-rem
persist-key
  
verb 3

The configuration is analog to the server configuration. The only differences are that a remote server is defined that the OpenVPN client tries to connect to and that no DH hash is used. If you use JOIN's management scripts, all configuration files have to be placed in /etc/openvpn.

The "up" script of a subnet client also sets up the tunnel interface and it creates a default route via the tunnel interface. Additionally, it enables IPv6 packet forwarding and it adds a route for the /64 prefix that is assigned to the client via an internal interface (in most cases eth0):

#!/bin/bash
 
INTERFACE=$1; shift;
TUN_MTU=$1;   shift;
UDP_MTU=$1;   shift;
LOCAL_IP=$1;  shift;
REMOTE_IP=$1; shift;
MODUS=$1;     shift;
 
 
ip link set ${INTERFACE} up
ip link set mtu ${TUN_MTU} dev ${INTERFACE}
 
ip -6 addr add 2001:638:500:f100::f101:2/112 dev ${INTERFACE}
ip -6 addr add fe80::f101:2/64 dev ${INTERFACE}
ip -6 route add default dev ${INTERFACE} metric 1
 
sysctl -w net.ipv6.conf.all.forwarding=1
ip -6 addr show dev eth0 | grep 2001:638:500:f101::1/64 \
	>/dev/null 2>&1 || ip -6 addr \
	add 2001:638:500:f101::1/64 dev eth0

"8. Sample subnet client configuration"

Back to top

The management of the tunnel broker is rather complicated to handle manually. Therefore, JOIN team members have written a very basic bash script that handles certificate creation, certificate signatures, server- & client-configurations and the creation of an archive file that may be given to users to set up the OpenVPN client on their machines. However, the script as of now can only be used to create client accounts, it cannot remove accounts and it does not handle the storage of client information in a user database. Therefore, the script should only be used as a reference for tunnel broker administrator how to set up local management. The script is released under the GNU GPL and may be modified to fit individual needs.

create-client-conf.sh is a script that is used to...

• ... create a client ID (e.g. christian.strauf),
• ... create an X.509 key and certificate for the client,
• ... sign the certificate using the CA's key,
• ... read routing relevant information from commandline (hermite or subnet client, Linux or Windows host, prefix to use),
• ... create the server's configuration files and scripts,
• ... put all client relevant configuration files into an archive that is given to the user.

To facilitate debugging of the tunnel on the client's side, join-openvpn-sanity-check.sh can be run on a Linux subnet client. The script collects a number of different information and tries to analyse if the information makes sense. It tests the setup for potential errors and reports these errors back to the user. The script does not modify the system, it is "read-only". It also does not send information somewhere, it merely displays information on the console that can be used by the user to identify the source of a problem.

Fig.: Output of join-openvpn-sanity-check.sh

Both scripts may be freely downloaded and distributed under the terms of the GNU GPL, however it is important to note that the scripts should only be used as a reference for a local installation rather than as a full featured "all-in-one" package.

Note: Please make sure to read the README and INSTALL files that are included in the tarball because they contain important setup information for the scripts.

• join-tunnel-broker-scripts-current.tar.gz (MD5-sum: 8d57bd67221d182e29b48a552c427c50)
• join-tunnel-broker-scripts-0.7.tar.gz (MD5-sum: 8d57bd67221d182e29b48a552c427c50)
• join-tunnel-broker-scripts-0.6.tar.gz (MD5-sum: f38bbda571b988af2dee231b71a238f8)
• join-tunnel-broker-scripts-0.5.tar.gz (MD5-sum: 4c81b3f49e1e2f49f2778ace3e86b170)
• join-tunnel-broker-scripts-0.4.tar.gz (MD5 sum: 6141a53de362d1ca230326b170678172)
• join-tunnel-broker-scripts-0.3.tar.gz (MD5 sum: dcbc4857d717407508e6f03693a2d156)

"9. Management"

Back to top

The installation of the OpenVPN based IPv6 tunnel broker client consists of three different steps:

1. Subscription to the service and receiving of configuration files from tunnel broker.
2. Installation of the OpenVPN client.
3. Installation of the OpenVPN configuration files provided by the tunnel broker.

The subscription part is the non-technical part. The technical part starts with the installation of the OpenVPN client. The client should be newer than version 1.6_rc3. It can be downloaded at http://openvpn.sourceforge.net/. Please install the package according to the documentation that can be found on the OpenVPN homepage (quick guide: under Windows, simply double-click the EXE file; under Linux, make sure that you have tun-driver- and IPv6-support in your kernel and that you have OpenSSL-devel and LZO-devel packages installed and do a "./configure ; make ; make install" -- for details, please refer to OpenVPN's documentation).

The configuration files that are provided by the tunnel broker must be copied to either /etc/openvpn (Linux) or to the config subdirectory of your OpenVPN installation (Windows). Starting the client is trivial:

• openvpn --config /etc/openvpn/<your.ID>.conf (Linux)
• run OpenVPN either as a service or from cmd.exe (Windows)

"10. Client user guide"

Back to top

Important links:

• OpenVPN homepage

"11. Appendix"

Back to top