# OpenConnect

OpenConnect is a client for Cisco's AnyConnect SSL VPN, which is supported by IOS 12.4(9)T or later on Cisco SR500, 870, 880, 1800, 2800, 3800, 7200 Series and Cisco 7301 Routers.

OpenConnect is released under the GNU Lesser Public License, version 2.1.

Like vpnc, OpenConnect is not officially supported by, or associated in any way with, Cisco Systems. It just happens to interoperate with their equipment.

Development of OpenConnect was started after a trial of their "official" client under Linux found it to have many deficiencies:

- Inability to use SSL certificates from a TPM, or even use a passphrase.
- Lack of support for Linux platforms other than i386.
- Lack of integration with NetworkManager on the Linux desktop.
- Lack of proper (RPM/DEB) packaging for Linux distributions.
- "Stealth" use of libraries with `dlopen()`, even using the development-only symlinks such as `libz.so` — making it hard to properly discover the dependencies which proper packaging would have expressed
- Tempfile races allowing unprivileged users to trick it into overwriting arbitrary files, as root.
- Unable to run as an unprivileged user, which would have reduced the severity of the above bug.
- Inability to audit the source code for further such "Security 101" bugs.

Naturally, OpenConnect addresses all of the above issues, and more.

## Supported Platforms

OpenConnect is known to work on Linux and Mac OS X platforms, and should be trivially portable to any other platform supporting TUN/TAP devices and on which OpenSSL runs.

It is known to work on at least i386, x86_64, PowerPC and MIPS processors, and should not have issues with portability to other CPUs.

## Features

- Automatic detection of IPv4 address, routes.
- Authentication via HTTP forms.
- Authentication using SSL certificates, from local file or Trusted Platform Module.
- UserGroup support for selecting between multiple configurations on a single VPN server.
- Data transport over TCP (HTTPS) or UDP (DTLS).
- Keepalive and Dead Peer Detection on both HTTPS and DTLS.
- Automatic update of VPN server list / configuration.
- Roaming support, allowing reconnection when the local IP address changes.
- Run without root privileges.

There are two ways that OpenConnect can run without root privileges. The first is that it can use a tun device which is created in advance by the root user, and set to be owned by the user who runs OpenConnect.

The second is that it can avoid using the tun device altogether and instead spawn a user-supplied program, passing all data traffic through a UNIX socket to that program. This latter option can be used in conjunction with a userspace TCP stack such as lwip to provide SOCKS access to the VPN without giving full access to all untrusted users and processes on the computer, and without requiring root privileges at all.

## TODO

- IPv6 support
- Windows / BSD / etc. support

Neither of the above would be hard to implement. The first just requires someone with access to a suitably configured server; it should be fairly simple to see how IPv6 connectivity works. If someone has such a machine — or has a legitimate version of IOS which they could run in an emulator like Dynamips, it would be very much appreciated to have some time to experiment with it.

The second is just a case of someone testing it on new platforms and letting me have any patches that are required; it mostly ought to 'just work', with maybe a few system-specific modifications to the tun support.

## Download

Development of OpenConnect is in the git repository at `git://git.infradead.org/users/dwmw2/openconnect.git`, which can be viewed in gitweb at http://git.infradead.org/users/dwmw2/openconnect.git

Tarball releases can be downloaded from ftp://ftp.infradead.org/pub/openconnect/

## Release Notes / Changelog

For full changelog entries including the latest development, see gitweb.

- OpenConnect v1.40 — 2009-05-27
  - Fix validation of server's SSL certificate when NetworkManager runs openconnect as an unprivileged user (which can't read the real user's trust chain file).
  - Fix double-free of DTLS Cipher option on reconnect.
  - Reconnect on SSL write errors
  - Fix reporting of SSL errors through syslog/UI.
- OpenConnect v1.30 — 2009-05-13
  - NetworkManager auth-dialog will now cache authentication form options.
- OpenConnect v1.20 — 2009-05-08
  - DTLS cipher choice fixes.
  - Improve handling of authentication group selection.
  - Export more information to connection script.
  - Add `--background` option to dæmonize after connection.
  - Detect TCP connection closure.
- OpenConnect v1.10 — 2009-04-01
  - NetworkManager UI rewrite with many improvements.
  - Support for "UserGroups" where a single server offers multiple configurations according to the URL used to connect.
- OpenConnect v1.00 — 2009-03-18
  - First non-beta release.

## NetworkManager support

Support for OpenConnect in NetworkManager has been integrated into GNOME git and is released alongside NetworkManager's other VPN modules: http://ftp.gnome.org/pub/GNOME/sources/NetworkManager-openconnect/.

Unlike other VPN support in NetworkManager, the `auth-dialog` tool which handles GUI authentication is part of OpenConnect itself, rather than included in the `network-manager-openconnect` package. This is because it shares a lot of code with OpenConnect, but doesn't actually share any with NetworkManager or the other parts of the NetworkManager support.

## ConnMan support

Basic support for OpenConnect in ConnMan has been submitted, and is pending approval. It can be obtained from the git repository at `git://git.infradead.org/users/dwmw2/connman-openconnect.git`; browsable in gitweb.

## Requirements

The basic text-mode client uses the following libraries:

- OpenSSL — all versions will work for basic connectivity, but see note on DTLS compatibility below.
- libxml2

For building the NetworkManager support, you will also need:

- GTK
- GConf

Patches converting OpenConnect from libxml2 to something more compact like expat would be welcomed...

## How the VPN works

The VPN is extremely simple, based almost entirely on the standard HTTPS and DTLS protocols. You connect to the secure web server, authenticate using certificates and/or arbitrary web forms, and you are rewarded with a standard HTTP cookie.

You then use this cookie in an HTTP `CONNECT` request, and can then pass traffic over that connection. IP addresses and routing information are passed back and forth in the headers of that `CONNECT` request.

Since TCP over TCP is very suboptimal, the VPN also attempts to use UDP datagrams, and will only actually pass traffic over the HTTPS connection if that fails. The UDP connectivity is done using Datagram TLS, which is supported by OpenSSL.

## OpenSSL/DTLS compatibility

Unfortunately, Cisco used an old version of OpenSSL for their server, which predates the official RFC and has a few differences in the implementation of DTLS. Compatibility support for their "speshul" version of the protocol was introduced into OpenSSL after the 0.9.8k release.

If you are using a version of OpenSSL older than 0.9.8l, you will need to apply this patch from OpenSSL CVS:

- http://cvs.openssl.org/chngview?cn=18037 (OpenSSL RT#1751)

For versions older than 0.9.8j, some generic DTLS bug fixes are also required:

- http://cvs.openssl.org/chngview?cn=17500 (OpenSSL RT#1703)
- http://cvs.openssl.org/chngview?cn=17505 (OpenSSL RT#1752)

The username/password for OpenSSL RT is 'guest/guest'

## Distribution Status

Updates to the information below are welcomed, especially for distributions (including *BSD etc.) which aren't yet mentioned.

### Fedora

Both `openconnect` and `NetworkManager-openconnect` packages are included in Fedora. Fedora's latest OpenSSL package updates also include all required patches for DTLS compatibility, as of the `openssl-0.9.8g-13` package in Fedora 10 and the `openssl-0.9.8k-4` package in Fedora 11.

### Debian

The `openconnect` package is available in Debian unstable, but `NetworkManager-openconnect` is not yet available.
Debian bug #524982 has been filed, requesting that the required patches be included in Debian's OpenSSL package.

### Gentoo

Gentoo bug #263097 has been filed, asking for `openconnect` to be packaged.

Last modified: Wed May 27 13:53:47 BST 2009