- import of strongswan-2.7.0
[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 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 $