ocserv/README

=== About ===

This program is openconnect VPN server (ocserv), a server compatible with the
openconnect VPN client [0]. It is believed to be compatible with the protocol
used by CISCO's AnyConnect SSL VPN. 

[0]. http://www.infradead.org/openconnect/


=== Build instructions ===

To build from a distributed release use:

$ ./configure && make

When cross compiling it may be useful to add the --with-local-libopts
option to configure.


To build from the git repository use:

$ autoreconf -fvi
$ ./configure && make


=== Installation instructions ===

Now you need to generate a certificate. E.g.
$ certtool --generate-privkey > ./test-key.pem
$ certtool --generate-self-signed --load-privkey test-key.pem --outfile test-cert.pem
(make sure you enable encryption or signing)

To run the server on the foreground edit the doc/sample.config and then run:
# src/ocserv -f -c src/sample.config


=== How the VPN works ===

The openconnect VPN server is an Internet-layer VPN server. That is, it provides 
the client with an IP address and a list of routes that this IP may access. 
Since this is not a Link-layer VPN a separate subnet must be allocated for the 
VPN addresses.

The subnet addresses are specified by the 'ipv4-network' and 'ipv4-netmask'
configuration options (and the corresponding ipv6 options). The routes that
are pushed to the client are specified by the 'route' option. For each client
two IPv4 addresses are assigned, its VPN address and its local image (remember
this is a point-to-point connection). The image isn't known to the client 
(the anyconnect protocol doesn't forward it). 

Note that in order to allow high-speed transfers ocserv doesn't do any packet 
forwarding or filtering between the networks. It is expected that the server 
has any required routes or firewall rules set up. You may conditionally 
enable firewall rules, or even enable routing rules through the client 
using the 'connect-script' and 'disconnect-script' scripts based on the 
user who connected. You can find some examples in the doc/scripts/ directory.


=== Authentication ===

Authentication in openconnect VPN server occurs in the initial TLS session.
That is an HTTPS session over which the client is provided with an XML authentication
page. The server is authenticated using its certificate and the client, either by
its certificate, or via username and password pairs, either via PAM or a
custom password file. Various combinations can be used, e.g., certificates
and passwords. Since PAM supports various authentication types, two factor
authentication methods are also supported. After the user is authenticated he 
is provided with a cookie that can be used for future connections. The lifetime 
of the cookie is configurable using the 'cookie-validity' option.

After the user is authenticated, directly, or via the cookie, he issues an HTTP
CONNECT command which results to a direct connection with the VPN. Additionally
the user could connect using UDP and Datagram TLS on a port that is provided
by the server. That connection is authenticated using TLS session resumption and 
a master key provided by the server, i.e., it is not really a DTLS 1.0 compliant 
connection.