================================================================================ ABOUT ================================================================================ This software distribution contains the Shrew Soft Inc Internet Key exchange daemon and IPsec VPN client front end applications. All included source code and supporting materials are covered under a liberal open source license. Please see the LICENSE.TXT file for more details. The source code is organized as several components that work together to facilitate IPsec communications. iked - Internet Key Exchange Daemon This component implements the IKE protocol version 1 for IPv4 networks and is very similar to the IPsec tools racoon daemon. It supports an extensive feature set that includes NAT-Traversal, Dead Peer Detection, Mode Config for centralized client configuration and management, dynamic security policy configuration and dynamic route management. The daemon supports two different modes of operation depending on how it is configured. This first mode of operation allows it to interact with Client Front end applications to facilitate Client to Gateway remote access. The other mode allows it to facilitate site to site IPsec key exchange provide advanced client gateway functionality. At this time, is recommended that the daemon only be used in client mode due to lack of adequate testing. If you need to install a VPN Client Gateway, please use the IPsec Tools racoon daemon. Version 0.7 or later is highly recommended. ikec - VPN Client Connect Application This component provides a console based user interface that represents a connection instance for a remote site. It allows a user to connect or disconnect, enter user login credentials and view the status of the remote access connection. qikea - VPN Access Manager Application ( optional ) This component provides a GUI user interface for managing remote site configurations. It is also used to launch a VPN Client Connect instance for a given remote site. qikec - VPN Client Connect Application ( optional ) This component provides a GUI user interface that represents a connection instance for a remote site. It allows a user to connect or disconnect, enter user login credentials and view the status of the remote access connection. ================================================================================ REQUIREMENTS ================================================================================ This section describes the basic requirements used to compile this software. In most cases, development versions of the dependencies will need to be installed. These could be available as pre-compiled packages or compiled directly from source. Minimum -------------------------------------------------------------------------------- c++ compiler stock c libs stock c includes pthread support lex or flex libedit bison >= 2.3 cmake >= 2.4 opsenssl >= 0.9.x This software requires Bison version 2.3 or higher as it uses the new c++ parser model. The c++ model was introduced in version 2.1 but appears to be incomplete. Optional -------------------------------------------------------------------------------- QT >= 5 openldap >= 2.0 The QT toolkit version 5.x or higher is also required if you plan to build the QT client front end applications. The openldap support is only useful if you plan to use iked to facilitate VPN client gateway connectivity and require xauth support via an external LDAP database. ================================================================================ PLATFORM SUPPORT ================================================================================ The FreeBSD, NetBSD and several Linux operating systems are supported and have been tested with this software. A free windows client is also available but requires custom kernel support and additional software that is not covered under an open source license. Please see the Shrew Soft Inc web site for more details. The only processor architectures that have been tested are i386 and amd64. It may be that this software works with more exotic architectures such as powerpc or sparc but no testing has been performed to confirm this. With the exception of the Windows client, this software utilizes the native IPsec kernel support which is bundled with all supported operating systems. Depending on your platform, a custom kernel may need to compiled or additional kernel modules may need to be loaded before it will operate correctly. Please see the specific platform notes for more details. FreeBSD -------------------------------------------------------------------------------- FreeBSD version 6.2 RELEASE was used to test this software. You will need to make sure your kernel has been built with IPsec support. Either the KAME IPsec stack or the Fast IPsec stack is supported. For example, to add support for Fast IPsec you could enable the following options in your custom kernel configuration file ... # IP Security device crypto options FAST_IPSEC As of FreeBSD 6.2, NATT kernel support has not yet been committed to the main line source. However, a high quality patch is available and has been tested with this software. It can be obtained from the following url ... http://ipsec-tools.sourceforge.net/freebsd6-natt.diff Before this software can be compiled with NATT support, the patch must be applied to your kernel. To apply the patch, you need to copy the file into your /usr/src/sys directory and apply it using the following command ... patch < freebsd6-natt.diff To enable this support, include the additional option in your custom kernel configuration file ... options IPSEC_NAT_T You will then need to build and install the custom kernel and perform a buildworld and installworld. Please see the FreeBSD handbook for more information on compiling and installing a custom kernel and userland. The following options are recommended when running the cmake configuration for FreeBSD. Please see the OPTIONS section for more details. cmake -DQTGUI=YES -DNATT=YES NetBSD -------------------------------------------------------------------------------- NetBSD version 3.1 was used to test this software. You will need to make sure your kernel has been built with IPsec support. For example, to include support for IPsec you could enable the following options in your custom kernel configuration file ... options INET options IPSEC options IPSEC_ESP options IPSEC_NAT_T Please see the NetBSD Documentation for more information on compiling and installing a custom kernel. The following options are recommended when running the cmake configuration for NetBSD. Please see the OPTIONS section for more details. cmake -DQTGUI=YES -DNATT=YES -DETCDIR=/etc NetBSD also appears to require several environment variables to be set when compiling and using the QT front end applications. For example, the following lines were added to the users ~/.profie script when testing this software for NetBSD ... QTDIR=/usr/pkg/qt5 QMAKESPEC=netbsd-g++ PATH=${PATH}:${QTDIR}/bin LD_LIBRARY_PATH=/usr/pkg/qt5/lib/:/usr/X11R6/lib export PATH QTDIR QMAKESPEC LD_LIBRARY_PATH Linux -------------------------------------------------------------------------------- Beginning with linux version 2.6, native kernel support has been added for the IPsec protocol suite. Both the Fedora Core 6 and Ubuntu 7.04 distributions were tested and came preinstalled with both ESP and NAT-T support by default. If you use another distribution, a custom kernel or additional modules may be be required. Please see your distribution documentation for more details. The following options are recommended when running the cmake configuration for linux platforms. Please see the OPTIONS section for more details. cmake -DCMAKE_INSTALL_PREFIX=/usr -DQTGUI=YES -DETCDIR=/etc -DNATT=YES For 64 bit Linux systems, most distributions store native 64bit library files in a unique path. The option for this is -LIBDIR=/usr/lib64 or the appropriate directory path. NOTE : It may also be necessary to add the KRNINC option to specify the kernel header file path on older versions of Linux. OSX -------------------------------------------------------------------------------- Apple OSX provides native kernel support for the IPsec protocol suite. This software was designed to support OSX version 10.8 and later. This software can also be linked against a private Qt library build when gui components are desired. When an install step is performed, a private copy of the Qt libs will also be installed. All references to that library will be modified to utilize the private library path. The following options are recommended when running the cmake configuration for OSX platforms. Please see the OPTIONS section for more details. cmake -DQTGUI=YES -DNATT=YES -DCMAKE_INSTALL_PREFIX=/usr \ -DQT_QMAKE_EXECUTABLE=[/qt/install/path]/bin/qmake NOTE : Qt will still attempt to load plugin libraries from the original private Qt install path. Since these libraries will have references to the original Qt library framework paths ( not the copy ), the dynamic link loader may load multiple versions of Qt libraries and cause the application to crash. It may be necessary to move the private qt install path to a different location before executing the compiled gui applications. For example: mv /qt/install/path /qt/install/path.bak ================================================================================ COMPILING ================================================================================ The cmake build system is used to generate platform specific make files. To configure the build, you simply run cmake in the base distribution directory using any optional parameters you may require. For example: enter the following to build and install the basic software ... cmake [OPTIONS] make make install ================================================================================ OPTIONS ================================================================================ In addition to the standard CMake options such as CMAKE_INSTALL_PREFIX, a few additional build parameters may be specified. Here is a brief list ... DEBUG Enable Debug Symbols TESTS Enable Library Tests Build QTGUI Enable Client QT GUI NATT Enable Nat Traversal Support LDAP Enable LDAP Authentication Support ETCDIR Custom etc configuration install path BINDIR Custim user bin install path SBINDIR Custim user sbin install path LIBDIR Custom user lirbrary install path MANDIR Custom man page install path KRNINC Kernel include path For example: enter the following to build and install the software with a few common options enabled ... cmake -DDEBUG=YES -DQTGUI=YES -DNATT=YES -DLDAP=YES make make install ================================================================================ USAGE ================================================================================ The main process that handles IKE negotiations is iked and must be run as root. By default, it will detach itself from the terminal and execute as a daemon. To force foreground operation, use the -F switch. A sample configuration file is included in this distribution and will be installed in the etc system configuration directory. The configuration should be suitable to allow for client operation but can also be modified to allow for site to site or client gateway operation as well. See the iked.conf man page for more details. Once the iked process has been launched, the VPN Access Manager application ( qikea ) is used to build remote access client configurations and initiate client connections. When the Access Manager GUI is used to initiate a client connection, a VPN Connect application ( qikec ) process is created. This process interacts with iked to initiate the connection. Alternately, a command line version of the VPN Connect application ( ikec ) can be used to initiate a connection. Please see the online documentation available at http://www.shrew.net for more details. ================================================================================ EXPORTED CONFIGURATION FILES ================================================================================ A site configuration contains all the data required to connect to a site using the VPN client tools. These configuration files can be exported or imported using the VPN Access Manager application. The file format used to describe the site configuration is a text ducument that contains one attribute per line with one or more attribute values. The attribute type is denoted by a single charachter field followed by the attribute name field and then by a value. The fields are separated using a colon charachter. For example, the following line describes a string attribute names network-host with a value of 10.1.1.1 s:network-host:10.1.1.1 Attributes are denoted as one of three types. s = String n = Number b = Binary ( bas64 encoded ) Multi valued strings are separated using a comma charachter and binary values are base64 encoded. Here is a list of attributes currently supported. s:network-host:<hostname>|<IP address> n:network-ike-port:<IKE UDP port> s:network-auto-mode:disable|pull|push|dhcp s:client-iface:virtual|direct n:client-addr-auto:0|1 s:client-ip-addr:<virtual IP address> s:client-ip-mask:<virtual IP netmask> n:network-mtu-size:<virtual MTU> n:client-wins-used:0|1 n:client-wins-auto:0|1 s:client-wins-addr:<WINS server IP address list> n:client-dns-used:0|1 n:client-dns-auto:0|1 s:client-dns-addr:<DNS server IP address list> s:client-dns-suffix:<DNS default suffix> n:client-splitdns-used:0|1 n:client-splitdns-auto:0|1 s:client-splitdns-list:<DNS split suffix list> s:network-natt-mode:disable|enable|force-draft|force-rfc s:network-frag-mode:disable|enable|force n:network-dpd-enable:0|1 n:network-notify-enable:0|1 n:client-banner-enable:0|1 s:auth-method:hybrid-rsa-xauth|mutual-rsa-xauth|mutual-psk-xauth|mutual-rsa|mutual-psk s:auth-server-cert:<path to server ca> s:auth-client-cert:<path to client public cert> s:auth-client-key:<path to client private key> b:auth-mutual-psk:<mutual pre-shared key> s:ident-client-type:asn1dn|keyid|fqdn|ufqdn|address s:ident-client-data:<type specific value> s:ident-server-type:asn1dn|keyid|fqdn|ufqdn|address s:ident-server-data:<type specific value> s:phase1-exchange:main|aggressive s:phase1-cipher:auto|aes|blowfish|3des|cast|des n:phase1-keylen:<key length> ( 0 = auto ) s:phase1-hash:auto|md5|sha1 n:phase1-dhgorup:1|2|5|14|15 n:phase1-life-secs:<life time> n:phase1-life-kbytes:<life KBytes> s:phase2-transform:auto|esp-aes|esp-blowfish|esp-3des|esp-cast|esp-des n:phase2-keylen:<key length> ( 0 = auto ) s:phase2-hmac:auto|md5|sha1 n:phase2-pfsgroup:-1|0|1|2|5|14|15 ( -1 = disabled, 0 = auto ) n:phase2-life-secs:<life time> n:phase2-life-kbytes:<life KBytes> s:policy-level:auto|required|unique|shared n:policy-nailed:0|1 ( persistent IPsec SAs ) n:policy-list-auto:0|1 s:policy-list-exclude:<address/netmask list> s:policy-list-include:<address/netmask list> NOTE : When a file is exported, the certificate and key file paths are modified to only contain the unqualified filename. The actual file data is encoded as a binary value. This allows the certificate information to be exported along with other site configuration data. Here are the related attributes after export. s:auth-server-cert:<server ca filename> b:auth-server-cert-data:<server ca file contents> s:auth-client-cert:<client public cert filename> b:auth-client-cert-data:<client public cert file contents> s:auth-client-key:<client private key filename> b:auth-client-key-data:<client private key file contents>