updated INSTALL to conform with autotools
[strongswan.git] / INSTALL
1                  ---------------------------
2                   strongSwan - Installation
3                  ---------------------------
4
5
6 Contents
7 --------
8
9    1.   Overview
10    2.   Required packages
11    3.   Optional packages
12    3.1   libcurl
13    3.2   OpenLDAP
14    3.3   PKCS#11 smartcard library modules
15    4.   Kernel configuration
16
17 1.  Overview
18     --------
19
20     The strongSwan 4.x branch introduces a new build environment featuring
21     GNU autotools. This should simplify the build process and package 
22     maintenance.
23     First check for the availability of required packages on your system
24     (section 2.). You may want to include support for additional features, which
25     require other packages to be installed (section 3.).
26     To compile an extracted tarball, run the ./configure script first:
27
28       ./configure
29
30     You may want to specify some arguments listed in section 3., or see the
31     available options of the script using "./configure --help".
32
33     After a successful run of the script, run
34
35       make
36
37     followed by
38
39       make install
40
41     in the usual manner.
42
43     To check if your kernel fullfills the requirements, see section 4.
44
45     Next add your connections to "/etc/ipsec.conf" and your secrets to 
46     "/etc/ipsec.secrets". Connections that are to be negotiated by the new
47     IKEv2 charon keying daemon should be designated by "keyexchange=ikev2" and 
48     those by the IKEv1 pluto keying daemon either by "keyexchange=ikev1" or
49     the default "keyexchange=ike".
50
51     At last start strongSwan with
52
53       ipsec start
54
55
56 2.  Required packages
57     -----------------
58
59     In order to be able to build strongSwan you'll need the GNU Multiprecision
60     Arithmetic Library (GMP) available from http://www.swox.com/gmp/. At least
61     version 4.1.5 of libgmp is required.
62
63     The libgmp library and the corresponding header file gmp.h are usually
64     included in the form of one or two packages in the major Linux
65     distributions (SuSE: gmp; Debian unstable:  libgmp3, libgmp3-dev).
66
67
68 3.  Optional packages
69     -----------------
70
71 3.1 libcurl
72     -------
73
74     If you intend to dynamically fetch Certificate Revocation Lists (CRLs)
75     from an HTTP server or as an alternative want to use the Online
76     Certificate Status Protocol (OCSP) then you will need the  libcurl library
77     available from http://curl.haxx.se/.
78
79     In order to keep the library as compact as possible for use with strongSwan
80     you can build libcurl from the sources with the optimized options
81
82        ./configure --prefix=<dir> --without-ssl \
83                    --disable-ldap --disable-telnet \
84                    --disable-dict --disable-gopher \
85                    --disable-debug \
86                    --enable-nonblocking --enable-thread
87
88     As an alternative you can use the ready-made packages included with your
89     favorite Linux distribution (SuSE: curl, curl-devel).
90
91     In order to activate the use of the libcurl library in strongSwan you must
92     enable the ./configure switch:
93
94        ./configure [...] --enable-http
95
96
97 3.2 OpenLDAP
98     --------
99
100     If you intend to dynamically fetch Certificate Revocation Lists (CRLs)
101     from an LDAP server then you will need the libldap library available
102     from http://www.openldap.org/.
103
104     OpenLDAP is usually included  with your Linux distribution. You will need
105     both the run-time and development environments (SuSE: openldap2,
106     openldap2-devel).
107
108     In order to activate the use of the libldap library in strongSwan you must
109     enable the ./configure switch:
110
111        ./configure [...] --enable-ldap
112
113     LDAP Protocl version 2 is not supported anymore, --enable-ldap uses always
114     version 3 of the LDAP protocol
115
116
117 3.3 PKCS#11 smartcard library modules
118     ---------------------------------
119
120     If you want to securely store your X.509 certificates and private RSA keys
121     on a smart card or a USB crypto token then you will need a PKCS #11 library 
122     for the smart card of your choice. The OpenSC PKCS#11 library (use
123     versions >= 0.9.4) available from http://www.opensc.org/ supports quite a
124     selection of cards and tokens (e.g. Aladdin eToken Pro32k, Schlumberger
125     Cryptoflex e-gate, Oberthur AuthentIC,  etc.) but requires that a PKCS#15
126     directory structure be present on the smart card. But in principle
127     any other PKCS#11 library could be used since the PKCS#11 API hides the
128     internal data representation on the card.
129
130     For USB crypto token support you must add the OpenCT driver library
131     (version >= 0.6.2) from the OpenSC site, whereas for serial smartcard
132     readers you'll need the pcsc-lite library and the matching driver from the
133     M.U.S.C.L.E project http://www.linuxnet.com/ .
134
135     In order to activate the PKCS#11-based smartcard support in strongSwan
136     you must enable the smartcard ./configure switch:
137
138        ./configure [...] --enable-smartcard
139
140     During compilation no externel smart card libraries must be present.
141     strongSwan directly references a copy of the standard RSAREF pkcs11.h
142     header files stored in the pluto/rsaref sub directory. During compile
143     time a pathname to a default PKCS#11 dynamical library can be specified
144     with a ./configure flag:
145
146       ./configure --enable-smartcard --with-default-pkcs11=/path/to/lib.so
147
148     This default path to the easily-obtainable OpenSC library module can be
149     simply overridden during run-time by specifying an alternative path in
150     ipsec.conf pointing to any dynamic PKCS#11 library of your choice.
151
152     config setup
153           pkcs11module="/usr/lib/xyz-pkcs11.so"
154
155
156 4.  Kernel configuration
157     --------------------
158
159     The strongSwan 4.x series currently support only 2.6 kernels and its
160     nativ IPsec stack. Please make sure that the the following IPsec kernel
161     modules are available:
162
163       o af_key
164       o ah4
165       o esp4
166       o ipcomp
167       o xfrm_user
168       o xfrm4_tunnel
169
170     These may be build into the kernel or as modules. Modules get loaded
171     automatically at strongSwan startup.
172
173     Also the built-in kernel Cryptoapi modules with selected encryption and
174     hash algorithms should be available.
175