# OpenConnect

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

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.

## Getting started

Before you get dismayed by the badly laid out information below, here's a simple intro to using OpenConnect.

1. Install OpenConnect.
   Some distributions like Fedora have packages; otherwise you can download it and type '`make`' to build it. To build it, you'll want development packages for `libxml2`, `zlib` and obviously `OpenSSL` to be installed.
2. Install a `vpnc-script`.
   This script is what sets up all the addresses and routes for you; it's the same as `vpnc`'s. You can get one from here if you don't have one — or if you need IPv6 or Solaris support, which the `vpnc` version lacks. (Note that the script needs to be executable, and stored somewhere where SELinux or similar security setups won't prevent the root user from accessing it.)
3. Connect to your server, running as root:
   `openconnect --script /etc/vpnc/vpnc-script https://vpn.mycompany.com/`

That should be it, if you have a password-based login. If you use certificates, you'll need to tell OpenConnect where to find the certificate with the `-c` option. You might need to steal the certificate from your Windows certificate store using a tool like Jailbreak.

You can ignore anything you see below about needing to patch OpenSSL so that DTLS works — you don't really need it, although it will make your connections much faster if you're experiencing packet loss between you and the VPN server. But you can worry about that later.

## Supported Platforms

OpenConnect is known to work on Linux, OpenBSD, FreeBSD, NetBSD, DragonFly BSD, OpenSolaris and Mac OS X platforms, and should be trivially portable to any other platform supporting TUN/TAP devices and on which OpenSSL runs. IPv6 support is tested on Linux, FreeBSD and OpenSolaris.

For Solaris support, and for IPv6 on any platform, the `vpnc-script` shipped with vpnc itself (as of v0.5.3) is not sufficient. It is necessary to use the script from my vpnc-scripts repository instead.

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.

Note that 'Cisco Secure Desktop' support may require the ability to run Linux/i386 binaries; see below.

## Features

- Connection through HTTP proxy, including libproxy support for automatic proxy configuration.
- Connection through SOCKS5 proxy.
- Automatic detection of IPv4 and IPv6 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.
- "Cisco Secure Desktop" support (see below).

### Running as non-root

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.

### Cisco Secure Desktop

The 'Cisco Secure Desktop' is a bit of a misnomer — it works by downloading a trojan binary from the server and running it on your client machine to perform some kind of 'verification' and post its approval back to the server. This seems anything but secure to me, especially given their history of trivially-exploitable bugs.

It's also fairly easy to subvert, by running your own modified binary instead of the one you download from the server. Or by running their binary but poking at it with gdb.

We support this idiocy, but because of the security concerns the trojan will be executed only if a userid is specified on the command line using the `--csd-user=` option.

This support currently only works when the server has a Linux binary installed, and only when that Linux binary runs on the client machine.

## Mailing list

There is a mailing list at `openconnect-devel@lists.infradead.org`. To subscribe, visit the Mailman admin page.

## TODO

- Testing IPv6 on more platforms (only Linux, FreeBSD, Solaris are tested so far).
- Better support for running or emulating the 'Cisco Secure Desktop' trojan.
- More platform support: Windows, Symbian, etc.
- GUI for OS X, perhaps based on Tunnelblick.

Platform support for new UNIX systems is relatively simple to add — most of the difference is in the TUN/TAP device handling, and the major variants of that are already supported.

A port to Windows should be fairly simple, since a TUN/TAP driver exists for Windows and Cygwin should make the basic port work OK.

A port to Symbian, to provide VPN connectivity on phone handsets, would be very useful. Any volunteers?

## 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 HEAD
  - No changelog entries yet
- OpenConnect v2.24 — 2010-05-07
  - Forget preconfigured password after a single attempt; don't retry infinitely if it's failing.
  - Set `$CISCO_BANNER` environment variable when running script.
  - Better handling of passphrase failure on certificate files.
  - Fix NetBSD build (thanks to Pouya D. Tafti).
  - Fix DragonFly BSD build.
- OpenConnect v2.23 — 2010-04-09
  - Support "Cisco Secure Desktop" trojan in NetworkManager auth-dialog.
  - Support proxy in NetworkManager auth-dialog.
  - Add `--no-http-keepalive` option to work around Cisco's incompetence.
  - Fix build on Debian/kFreeBSD.
  - Fix crash on receiving HTTP 404 error.
  - Improve workaround for server certificates lacking SSL_SERVER purpose, so that it also works with OpenSSL older than 0.9.8k.
- OpenConnect v2.22 — 2010-03-07
  - Fix bug handling port numbers above 9999.
  - Ignore "`Connection: Keep-Alive`" in HTTP/1.0 to work around server bug with certificate authentication.
  - Handle non-standard port (and full URLs) when used with NetworkManager.
  - Cope with relative redirect and form URLs.
  - Allocate HTTP receive buffer dynamically, to cope with arbitrary size of content.
  - Fix server cert SHA1 comparison to be case-insensitive.
  - Fix build on Solaris and OSX (`strndup()`, `AI_NUMERICSERV`).
  - Fix exit code with `--background` option.
- OpenConnect v2.21 — 2010-01-10
  - Fix handling of HTTP 1.0 responses with keepalive (RH#553817).
  - Fix case sensitivity in HTTP headers and hostname comparison on redirect.
- OpenConnect v2.20 — 2010-01-04
  - Fix use-after-free bug in NetworkManager authentication dialog (RH#551665).
  - Allow server to be specified with `https://` URL, including port and pathname (which Cisco calls 'UserGroup')
  - Support connection through HTTP and SOCKS proxies.
  - Handle HTTP redirection with port numbers.
  - Handle HTTP redirection with IPv6 literal addresses.
- OpenConnect v2.12 — 2009-12-07
  - Fix buffer overflow when generating useragent string.
  - Cope with idiotic schizoDNS configurations by not repeating DNS lookup for VPN server on reconnects.
  - Support DragonFlyBSD. Probably.
- OpenConnect v2.11 — 2009-11-17
  - Add IPv6 support for FreeBSD.
  - Support "split tunnel" mode for IPv6 routing.
  - Fix bug where client certificate's MD5 was only given to the CSD trojan if a PKCS#12 certificate was used.
- OpenConnect v2.10 — 2009-11-04
  - OpenSolaris support.
  - Preliminary support for IPv6 connectivity.
  - Fix session shutdown on exit.
  - Fix reconnection when TCP connection is closed.
  - Support for "Cisco Secure Desktop" idiocy.
  - Allow `User-Agent:` to be specified on command line.
  - Fix session termination on disconnect.
  - Fix recognition of certificates from OpenSSL 1.0.0.
- OpenConnect v2.01 — 2009-06-24
  - Fix bug causing loss of DTLS (and lots of syslog spam about it) after a CSTP reconnection.
  - Don't apply OpenSSL certificate chain workaround if we already have "extra" certificates loaded (e.g. from a PKCS#12 file).
  - Load "extra" certificates from `.pem` files too.
  - Fix SEGV caused by freeing certificates after processing cert chain.
- OpenConnect v2.00 — 2009-06-03
  - Add OpenBSD and FreeBSD support.
  - Build with OpenSSL-0.9.7 (Mac OS X, OpenBSD, etc.)
  - Support PKCS#12 certificates.
  - Automatic detection of certificate type (PKCS#12, PEM, TPM).
  - Work around OpenSSL trust chain issues (RT#1942).
  - Allow PEM passphrase to be specified on command line.
  - Allow PEM passphrase automatically generated from the `fsid` of the file system on which the certificate is stored.
  - Fix certificate comparisons (in NM auth-dialog and `--servercert` option) to use SHA1 fingerprint, not signature.
  - Fix segfault in NM auth-dialog when changing hosts.
- 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 from 0.9.7 onwards will work for basic connectivity, but see note on DTLS compatibility below.
- libxml2
- zlib
- libproxy

Mac OS X users will also need to install the Mac OS X tun/tap driver, and Solaris users will need the Solaris one. Note that for IPv6 support, the Solaris tun/tap driver from 16th Nov 2009 or newer is required.

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

Note: DTLS is optional and not required for basic connectivity, as explained above.

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 is in the 0.9.8m and later releases of OpenSSL (and 1.0.0-beta2 and later).

If you are using an older version of OpenSSL, DTLS will only work if you 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 OpenSSL packages include all required patches for DTLS compatibility.

### Debian

The `openconnect` and `network-manager-openconnect` packages are available in unstable and testing.
Debian bug #524982 has been filed, requesting that the required patches be included in Debian's OpenSSL package.

### Ubuntu

Reasonably current versions of the required packages are finally included in Ubuntu 10.04 "Lucid". Older releases still have out of date OpenSSL and out of date OpenConnect which doesn't work around the latest Cisco bugs.

### Gentoo

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

### NetBSD, DragonFly BSD, etc. (pkgsrc)

Pouya D. Tafti has created a pkgsrc package for openconnect and is working on getting it into the standard repositories.

### FreeBSD

An `openconnect` port is available for FreeBSD. FreeBSD does not yet ship a version of OpenSSL which supports Cisco's "speshul" version of DTLS.

Last modified: Fri May 7 20:11:44 BST 2010