INSTALL

   1                  ---------------------------
   2                   strongSwan - Installation
   3                  ---------------------------
   4
   5
   6 Contents
   7 --------
   8
   9    1. Required packages
  10    2. Optional packages
  11    2.1 libcurl
  12    2.2 OpenLDAP
  13    2.3 PKCS#11 smartcard library modules
  14    3. Building strongSwan with a Linux 2.4 kernel
  15    4. Updating strongSwan with a Linux 2.4 kernel
  16    5. Building strongSwan with a Linux 2.6 kernel
  17
  18
  19 1. Required packages
  20    -----------------
  21
  22    In order to be able to build strongSwan you'll need the GNU Multiprecision
  23    Arithmetic Library (GMP) available from http://www.swox.com/gmp/.
  24
  25    The libgmp library and the corresponding header file gmp.h are usually
  26    included in the form of one or two packages in the major Linux
  27    distributions (SuSE: gmp; Debian unstable:  libgmp3, libgmp3-dev).
  28
  29
  30 2. Optional packages
  31    -----------------
  32
  33 2.1 libcurl
  34     -------
  35
  36    If you intend to dynamically fetch Certificate Revocation Lists (CRLs)
  37    from an HTTP server or as an alternative want to use the Online
  38    Certificate Status Protocol (OCSP) then you will need the  libcurl library
  39    available from http://curl.haxx.se/.
  40
  41    In order to keep the library as compact as possible for use with strongSwan
  42    you can build libcurl from the sources with the optimized options
  43
  44        ./configure --prefix=<dir> --without-ssl \
  45                    --disable-ldap --disable-telnet \
  46                    --disable-dict --disable-gopher \
  47                    --disable-debug \
  48                    --enable-nonblocking --enable-thread
  49
  50    As an alternative you can use the ready-made packages included with your
  51    favorite Linux distribution (SuSE: curl, curl-devel).
  52
  53    In order to activate the use of the libcurl library in strongSwan you must
  54    set the USE_LIBCURL option in "Makefile.inc":
  55
  56        # include libcurl support (CRL fetching, OCSP and SCEP)
  57        USE_LIBCURL?=true
  58
  59    Under Gentoo emerge strongSwan with
  60
  61        USE="curl -ssl" emerge strongswan
  62
  63
  64 2.2 OpenLDAP
  65     --------
  66
  67    If you intend to dynamically fetch Certificate Revocation Lists (CRLs)
  68    from an LDAP server  then you will need the libldap library available
  69    from http://www.openldap.org/.
  70
  71     OpenLDAP is usually included  with your Linux distribution. You will need
  72    both the run-time and development environments (SuSE: openldap2,
  73    openldap2-devel).
  74
  75    In order to activate the use of the libldap library in strongSwan you must
  76    set the USE_LDAP option in "Makefile.inc":
  77
  78        # include LDAP support (CRL fetching)
  79        USE_LDAP?=true
  80
  81    Depending upon whether your LDAP server understands the V3 (preferred) or
  82    V2 LDAP protocol, uncomment one ot the two following lines:
  83
  84        # Uncomment to enable dynamic CRL fetching using LDAP V3
  85        LDAP_VERSION=3
  86        # Uncomment to enable dynamic CRL fetching using LDAP V2
  87        #LDAP_VERSION=2
  88
  89    The latest OpenLDAP releases use the LDAP V3 protocol, whereas older
  90    versions require LDAP V2.
  91
  92    Under Gentoo emerge strongSwan with
  93
  94        USE="ldap -ssl" emerge strongswan
  95
  96
  97 2.3 PKCS#11 smartcard library modules
  98     ---------------------------------
  99
 100    If you want to securely store your X.509 certificates and private RSA keys
 101    on a smart card or a USB crypto token then you will need a PKCS #11 library
 102    for the smart card of your choice. The OpenSC PKCS#11 library (use
 103    versions >= 0.9.4) available from http://www.opensc.org/ supports quite a
 104    selection of cards and tokens (e.g. Aladdin eToken Pro32k, Schlumberger
 105    Cryptoflex e-gate, Oberthur AuthentIC,  etc.) but requires that a PKCS#15
 106    directory structure be present on the smart card. But in principle
 107    any other PKCS#11 library could be used since the PKCS#11 API hides the
 108    internal data representation on the card.
 109
 110    For USB crypto token support you must add the OpenCT driver library
 111    (version >= 0.6.2) from the OpenSC site, whereas for serial smartcard
 112    readers you'll need the pcsc-lite library and the matching driver from the
 113    M.U.S.C.L.E project http://www.linuxnet.com/ .
 114
 115    In order to activate the PKCS#11-based smartcard support in strongSwan
 116    you must set the USE_SMARTCARD option in "Makefile.inc":
 117
 118        #include PKCS11-based smartcard support
 119        USE_SMARTCARD?=true
 120
 121    During compilation no externel smart card libraries must be present.
 122    strongSwan directly references a copy of the standard RSAREF pkcs11.h
 123    header files stored in the pluto/rsaref sub directory. During compile
 124    time a pathname to a default PKCS#11 dynamical library can be specified
 125    in "Makefile.inc"
 126
 127       # Uncomment this line if using OpenSC <= 0.9.6
 128       PKCS11_DEFAULT_LIB=\"/usr/lib/pkcs11/opensc-pkcs11.so\"
 129       # Uncomment tis line if using OpenSC >= 0.10.0
 130       #PKCS11_DEFAULT_LIB=\"usr/lib/opensc-pkcs11.so\"
 131
 132    This default path to the easily-obtainable OpenSC library module can be
 133    simply overridden during run-time by specifying an alternative path in
 134    ipsec.conf pointing to any dynamic PKCS#11 library of your choice.
 135
 136    config setup
 137           pkcs11module="/usr/lib/xyz-pkcs11.so"
 138
 139    Under Gentoo emerge strongSwan with
 140
 141        USE="smartcard usb -pam -X" emerge strongswan
 142
 143
 144 3. Building strongSwan with a Linux 2.4 kernel
 145    -------------------------------------------
 146
 147    * Building strongSwan with a Linux 2.4 kernel requires the presence of the
 148      matching kernel sources referenced via the symbolic link /usr/src/linux.
 149      The use of the vanilla kernel sources from ftp.kernel.org is strongly
 150      recommended.
 151
 152      Before building strongSwan you must have compiled the kernel sources at
 153      least once:
 154
 155          make menuconfig; make dep; make bzImage; make modules
 156
 157    * Now change into the  strongswan-2.x.x  source directory.
 158
 159      First uncomment any desired compile options in "programs/pluto/Makefile"
 160      (see section 2. Optional packages).
 161
 162      Then in the top source directory type
 163
 164          make menumod
 165
 166      This command applies an ESP_IN_UDP encapsulation patch which is required
 167      for NAT-Traversal to the kernel sources.
 168
 169      In the "Networking options" menu set
 170
 171          <M> IP Security Protocol (strongSwan IPsec)
 172
 173      in order to build KLIPS as a loadable kernel module "ipsec.o".  Do not
 174      forget to save the modified configuration file when leaving "menumod".
 175
 176      The strongSwan userland programs are now automatically built and
 177      installed, whereas the  ipsec.o  kernel module and the crypto modules
 178      are only built and must be installed with the command
 179
 180          make minstall
 181
 182    * If you intend to use the NAT-Traversal feature then you must compile the
 183      patched kernel sources again by executing
 184
 185          make bzImage
 186
 187      and then install and boot the modified kernel.
 188
 189    * Next add your connections to "/etc/ipsec.conf" and start strongSwan with
 190
 191          ipsec setup start
 192
 193
 194 4. Updating strongSwan with a Linux 2.4 kernel
 195    -------------------------------------------
 196
 197    * If you have already successfully installed  strongSwan and want to update
 198      to a newer version then the following shortcut can be taken:
 199
 200      First uncomment any desired compile options in "programs/pluto/Makefile"
 201      (see section 2. Optional packages).
 202
 203      Then in the  strongwan-2.x.x  top directory type
 204
 205          make programs; make install
 206
 207      followed by
 208
 209          make module; make minstall
 210
 211    * You can then start the updated strongSwan version with
 212
 213          ipsec setup restart
 214
 215
 216 5. Building strongSwan with a Linux 2.6 kernel
 217    -------------------------------------------
 218
 219    * Because the Linux 2.6 kernel comes with a built-in native IPsec stack,
 220      you won't need to build the strongSwan kernel modules. Please make sure
 221      that the the following Linux 2.6 IPsec kernel modules are available:
 222
 223          o af_key
 224          o ah4
 225          o esp4
 226          o ipcomp
 227          o xfrm_user
 228
 229      Also the built-in kernel Cryptoapi modules with selected encryption and
 230      hash algorithms should be available.
 231
 232    * First uncomment any desired compile options in "programs/pluto/Makefile"
 233      (see section 2. Optional packages).
 234
 235      Then in the  strongwan-2.x.x  top directory type
 236
 237          make programs
 238
 239      followed by
 240
 241          make install
 242
 243    * Next add your connections to "etc/ipsec.conf" and start strongSwan with
 244
 245          ipsec setup start
 246
 247 -----------------------------------------------------------------------------
 248
 249 This file is RCSID $Id: INSTALL,v 1.8 2006/01/22 16:22:23 as Exp $