- applied patch from andreas
[strongswan.git] / 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 and running strongSwan with a Linux 2.6 kernel
15
16
17 1. Required packages
18    -----------------
19
20    In order to be able to build strongSwan you'll need the GNU Multiprecision
21    Arithmetic Library (GMP) available from http://www.swox.com/gmp/.
22
23    The libgmp library and the corresponding header file gmp.h are usually
24    included in the form of one or two packages in the major Linux
25    distributions (SuSE: gmp; Debian unstable:  libgmp3, libgmp3-dev).
26
27
28 2. Optional packages
29    -----------------
30
31 2.1 libcurl
32     -------
33
34    If you intend to dynamically fetch Certificate Revocation Lists (CRLs)
35    from an HTTP server or as an alternative want to use the Online
36    Certificate Status Protocol (OCSP) then you will need the  libcurl library
37    available from http://curl.haxx.se/.
38
39    In order to keep the library as compact as possible for use with strongSwan
40    you can build libcurl from the sources with the optimized options
41
42        ./configure --prefix=<dir> --without-ssl \
43                    --disable-ldap --disable-telnet \
44                    --disable-dict --disable-gopher \
45                    --disable-debug \
46                    --enable-nonblocking --enable-thread
47
48    As an alternative you can use the ready-made packages included with your
49    favorite Linux distribution (SuSE: curl, curl-devel).
50
51    In order to activate the use of the libcurl library in strongSwan you must
52    set the USE_LIBCURL option in "Makefile.inc":
53
54        # include libcurl support (CRL fetching, OCSP and SCEP)
55        USE_LIBCURL?=true
56
57    Under Gentoo emerge strongSwan with
58
59        USE="curl -ssl" emerge strongswan
60
61
62 2.2 OpenLDAP
63     --------
64
65    If you intend to dynamically fetch Certificate Revocation Lists (CRLs)
66    from an LDAP server  then you will need the libldap library available
67    from http://www.openldap.org/.
68
69     OpenLDAP is usually included  with your Linux distribution. You will need
70    both the run-time and development environments (SuSE: openldap2,
71    openldap2-devel).
72
73    In order to activate the use of the libldap library in strongSwan you must
74    set the USE_LDAP option in "Makefile.inc":
75
76        # include LDAP support (CRL fetching)
77        USE_LDAP?=true
78
79    Depending upon whether your LDAP server understands the V3 (preferred) or
80    V2 LDAP protocol, uncomment one ot the two following lines:
81
82        # Uncomment to enable dynamic CRL fetching using LDAP V3
83        LDAP_VERSION=3
84        # Uncomment to enable dynamic CRL fetching using LDAP V2
85        #LDAP_VERSION=2
86
87    The latest OpenLDAP releases use the LDAP V3 protocol, whereas older
88    versions require LDAP V2.
89
90    Under Gentoo emerge strongSwan with
91
92        USE="ldap -ssl" emerge strongswan
93
94
95 2.3 PKCS#11 smartcard library modules
96     ---------------------------------
97
98    If you want to securely store your X.509 certificates and private RSA keys
99    on a smart card or a USB crypto token then you will need a PKCS #11 library 
100    for the smart card of your choice. The OpenSC PKCS#11 library (use
101    versions >= 0.9.4) available from http://www.opensc.org/ supports quite a
102    selection of cards and tokens (e.g. Aladdin eToken Pro32k, Schlumberger
103    Cryptoflex e-gate, Oberthur AuthentIC,  etc.) but requires that a PKCS#15
104    directory structure be present on the smart card. But in principle
105    any other PKCS#11 library could be used since the PKCS#11 API hides the
106    internal data representation on the card.
107
108    For USB crypto token support you must add the OpenCT driver library
109    (version >= 0.6.2) from the OpenSC site, whereas for serial smartcard
110    readers you'll need the pcsc-lite library and the matching driver from the
111    M.U.S.C.L.E project http://www.linuxnet.com/ .
112
113    In order to activate the PKCS#11-based smartcard support in strongSwan
114    you must set the USE_SMARTCARD option in "Makefile.inc":
115
116        #include PKCS11-based smartcard support
117        USE_SMARTCARD?=true
118
119    During compilation no externel smart card libraries must be present.
120    strongSwan directly references a copy of the standard RSAREF pkcs11.h
121    header files stored in the pluto/rsaref sub directory. During compile
122    time a pathname to a default PKCS#11 dynamical library can be specified
123    in "Makefile.inc" 
124
125       # Uncomment this line if using OpenSC <= 0.9.6
126       # PKCS11_DEFAULT_LIB=\"/usr/lib/pkcs11/opensc-pkcs11.so\"
127       # Uncomment tis line if using OpenSC >= 0.10.0
128         PKCS11_DEFAULT_LIB=\"usr/lib/opensc-pkcs11.so\"
129
130    This default path to the easily-obtainable OpenSC library module can be
131    simply overridden during run-time by specifying an alternative path in
132    ipsec.conf pointing to any dynamic PKCS#11 library of your choice.
133
134    config setup
135           pkcs11module="/usr/lib/xyz-pkcs11.so"
136
137    Under Gentoo emerge strongSwan with
138
139        USE="smartcard usb -pam -X" emerge strongswan
140
141
142
143 3. Building and running strongSwan with a Linux 2.6 kernel
144    -------------------------------------------------------
145
146    * Because the Linux 2.6 kernel comes with a built-in native IPsec stack,
147      you won't need to build the strongSwan kernel modules. Please make sure 
148      that the the following Linux 2.6 IPsec kernel modules are available:
149
150          o af_key
151          o ah4
152          o esp4
153          o ipcomp
154          o xfrm_user
155          o xfrm_tunnel
156
157      Also the built-in kernel Cryptoapi modules with selected encryption and 
158      hash algorithms should be available.
159
160    * First select any desired compile options in "Makefile.inc" (see section 2.
161      Optional packages). Then in the  strongwan-4.x.x  top directory type
162
163          make
164
165      followed by
166
167          make install
168
169    * Next add your connections to "/etc/ipsec.conf" and your secrets to 
170      "/etc/ipsec.secrets". Connections that are to be negotiated by the new
171      IKEv2 charon keying daemon should be designated by "keyexchange=ikev2" and 
172      those by the IKEv1 pluto keying daemon either by "keyexchange=ikev1" or
173      the default "keyexchange=ike".
174
175    * At last start strongSwan with
176
177          ipsec start
178
179 -----------------------------------------------------------------------------
180
181 This file is RCSID $Id: INSTALL,v 1.9 2006/05/01 16:02:37 as Exp $