]> git.ipfire.org Git - thirdparty/openssl.git/blame - INSTALL
add documentation
[thirdparty/openssl.git] / INSTALL
CommitLineData
79e259e3 1
4109b97c
RE
2 INSTALLATION ON THE UNIX PLATFORM
3 ---------------------------------
79e259e3 4
4d8743f4
RL
5 [Installation on DOS (with djgpp), Windows, OpenVMS, MacOS (before MacOS X)
6 and NetWare is described in INSTALL.DJGPP, INSTALL.W32, INSTALL.VMS,
7 INSTALL.MacOS and INSTALL.NW.
8
d5492d9b
RL
9 This document describes installation on operating systems in the Unix
10 family.]
4109b97c
RE
11
12 To install OpenSSL, you will need:
79e259e3 13
d57d85ff 14 * make
abb3e53f 15 * Perl 5
73bfb9ad 16 * an ANSI C compiler
d57d85ff
RL
17 * a development environment in form of development libraries and C
18 header files
80611577 19 * a supported Unix operating system
79e259e3 20
4109b97c
RE
21 Quick Start
22 -----------
79e259e3 23
4109b97c 24 If you want to just get on with it, do:
79e259e3 25
b1fe6b43 26 $ ./config
4109b97c 27 $ make
4109b97c
RE
28 $ make test
29 $ make install
79e259e3 30
d872c55c 31 [If any of these steps fails, see section Installation in Detail below.]
b1fe6b43 32
4109b97c
RE
33 This will build and install OpenSSL in the default location, which is (for
34 historical reasons) /usr/local/ssl. If you want to install it anywhere else,
462ba4f6 35 run config like this:
79e259e3 36
462ba4f6 37 $ ./config --prefix=/usr/local --openssldir=/usr/local/openssl
79e259e3 38
b1fe6b43
UM
39
40 Configuration Options
41 ---------------------
42
2d99cee7
BM
43 There are several options to ./config (or ./Configure) to customize
44 the build:
2613c1fa 45
b1fe6b43
UM
46 --prefix=DIR Install in DIR/bin, DIR/lib, DIR/include/openssl.
47 Configuration files used by OpenSSL will be in DIR/ssl
48 or the directory specified by --openssldir.
462ba4f6
UM
49
50 --openssldir=DIR Directory for OpenSSL files. If no prefix is specified,
51 the library files and binaries are also installed there.
52
5f8d5c96
BM
53 no-threads Don't try to build with support for multi-threaded
54 applications.
55
56 threads Build with support for multi-threaded applications.
57 This will usually require additional system-dependent options!
58 See "Note on multi-threading" below.
59
e452de9d
RL
60 no-zlib Don't try to build with support for zlib compression and
61 decompression.
62
63 zlib Build with support for zlib compression/decompression.
64
65 zlib-dynamic Like "zlib", but has OpenSSL load the zlib library dynamically
66 when needed. This is only supported on systems where loading
f1ca5f5b 67 of shared libraries is supported. This is the default choice.
e452de9d 68
fcc6a1c4
RL
69 no-shared Don't try to create shared libraries.
70
71 shared In addition to the usual static libraries, create shared
72 libraries on platforms where it's supported. See "Note on
73 shared libraries" below.
74
b1fe6b43 75 no-asm Do not use assembler code.
462ba4f6
UM
76
77 386 Use the 80386 instruction set only (the default x86 code is
a84c9d1e
UM
78 more efficient, but requires at least a 486). Note: Use
79 compiler flags for any other CPU specific configuration,
c58d983e 80 e.g. "-m32" to build x86 code on an x64 system.
2613c1fa 81
216ddfaf
AP
82 no-sse2 Exclude SSE2 code pathes. Normally SSE2 extention is
83 detected at run-time, but the decision whether or not the
84 machine code will be executed is taken solely on CPU
85 capability vector. This means that if you happen to run OS
86 kernel which does not support SSE2 extension on Intel P4
87 processor, then your application might be exposed to
88 "illegal instruction" exception. There might be a way
89 to enable support in kernel, e.g. FreeBSD kernel can be
90 compiled with CPU_ENABLE_SSE, and there is a way to
91 disengage SSE2 code pathes upon application start-up,
92 but if you aim for wider "audience" running such kernel,
93 consider no-sse2. Both 386 and no-asm options above imply
94 no-sse2.
95
b1fe6b43
UM
96 no-<cipher> Build without the specified cipher (bf, cast, des, dh, dsa,
97 hmac, md2, md5, mdc2, rc2, rc4, rc5, rsa, sha).
92afda6c
UM
98 The crypto/<cipher> directory can be removed after running
99 "make depend".
b1fe6b43 100
a84c9d1e 101 -Dxxx, -lxxx, -Lxxx, -fxxx, -mXXX, -Kxxx These system specific options will
b1fe6b43
UM
102 be passed through to the compiler to allow you to
103 define preprocessor symbols, specify additional libraries,
104 library directories or other compiler options.
105
e105098b
DSH
106 -DHAVE_CRYPTODEV Enable the BSD cryptodev engine even if we are not using
107 BSD. Useful if you are running ocf-linux or something
108 similar. Once enabled you can also enable the use of
109 cryptodev digests, which is usually slower unless you have
110 large amounts data. Use -DUSE_CRYPTODEV_DIGESTS to force
111 it.
79e259e3 112
4109b97c
RE
113 Installation in Detail
114 ----------------------
c9f06e7f 115
4109b97c 116 1a. Configure OpenSSL for your operation system automatically:
c9f06e7f 117
b1fe6b43 118 $ ./config [options]
c9f06e7f 119
4109b97c 120 This guesses at your operating system (and compiler, if necessary) and
b1fe6b43 121 configures OpenSSL based on this guess. Run ./config -t to see
db209ec2
UM
122 if it guessed correctly. If you want to use a different compiler, you
123 are cross-compiling for another platform, or the ./config guess was
124 wrong for other reasons, go to step 1b. Otherwise go to step 2.
c9f06e7f 125
b1fe6b43
UM
126 On some systems, you can include debugging information as follows:
127
128 $ ./config -d [options]
129
c9f06e7f 130 1b. Configure OpenSSL for your operating system manually
79e259e3 131
4109b97c
RE
132 OpenSSL knows about a range of different operating system, hardware and
133 compiler combinations. To see the ones it knows about, run
79e259e3 134
4109b97c 135 $ ./Configure
79e259e3 136
4109b97c
RE
137 Pick a suitable name from the list that matches your system. For most
138 operating systems there is a choice between using "cc" or "gcc". When
139 you have identified your system (and if necessary compiler) use this name
140 as the argument to ./Configure. For example, a "linux-elf" user would
141 run:
79e259e3 142
b1fe6b43 143 $ ./Configure linux-elf [options]
79e259e3
PS
144
145 If your system is not available, you will have to edit the Configure
73bfb9ad 146 program and add the correct configuration for your system. The
db209ec2
UM
147 generic configurations "cc" or "gcc" should usually work on 32 bit
148 systems.
79e259e3 149
b1fe6b43
UM
150 Configure creates the file Makefile.ssl from Makefile.org and
151 defines various macros in crypto/opensslconf.h (generated from
80611577 152 crypto/opensslconf.h.in).
79e259e3 153
462ba4f6 154 2. Build OpenSSL by running:
79e259e3 155
4109b97c 156 $ make
79e259e3 157
4109b97c
RE
158 This will build the OpenSSL libraries (libcrypto.a and libssl.a) and the
159 OpenSSL binary ("openssl"). The libraries will be built in the top-level
160 directory, and the binary will be in the "apps" directory.
79e259e3 161
a652ffc4 162 If "make" fails, look at the output. There may be reasons for
9020b862 163 the failure that aren't problems in OpenSSL itself (like missing
a652ffc4
RL
164 standard headers). If it is a problem with OpenSSL itself, please
165 report the problem to <openssl-bugs@openssl.org> (note that your
7650934f 166 message will be recorded in the request tracker publicly readable
b5dbbebb
RS
167 at https://www.openssl.org/community/index.html#bugs and will be
168 forwarded to a public mailing list). Include the output of "make
169 report" in your message. Please check out the request tracker. Maybe
170 the bug was already reported or has already been fixed.
b1fe6b43 171
436a376b 172 [If you encounter assembler error messages, try the "no-asm"
b82ccbb7 173 configuration option as an immediate fix.]
436a376b 174
91174a91
UM
175 Compiling parts of OpenSSL with gcc and others with the system
176 compiler will result in unresolved symbols on some systems.
177
462ba4f6 178 3. After a successful build, the libraries should be tested. Run:
79e259e3 179
4109b97c 180 $ make test
79e259e3 181
a652ffc4
RL
182 If a test fails, look at the output. There may be reasons for
183 the failure that isn't a problem in OpenSSL itself (like a missing
184 or malfunctioning bc). If it is a problem with OpenSSL itself,
c0ac3233 185 try removing any compiler optimization flags from the CFLAG line
a652ffc4
RL
186 in Makefile.ssl and run "make clean; make". Please send a bug
187 report to <openssl-bugs@openssl.org>, including the output of
7650934f 188 "make report" in order to be added to the request tracker at
b4be3808 189 http://www.openssl.org/support/rt.html.
b1fe6b43 190
462ba4f6 191 4. If everything tests ok, install OpenSSL with
79e259e3 192
4109b97c 193 $ make install
79e259e3 194
4109b97c 195 This will create the installation directory (if it does not exist) and
33d50ef6 196 then the following subdirectories:
79e259e3 197
462ba4f6
UM
198 certs Initially empty, this is the default location
199 for certificate files.
435b72dd
BM
200 man/man1 Manual pages for the 'openssl' command line tool
201 man/man3 Manual pages for the libraries (very incomplete)
7e05db95 202 misc Various scripts.
b1fe6b43
UM
203 private Initially empty, this is the default location
204 for private key files.
462ba4f6 205
f4e723f3 206 If you didn't choose a different installation prefix, the
33d50ef6 207 following additional subdirectories will be created:
79e259e3 208
462ba4f6
UM
209 bin Contains the openssl binary and a few other
210 utility programs.
211 include/openssl Contains the header files needed if you want to
212 compile programs with libcrypto or libssl.
33d50ef6 213 lib Contains the OpenSSL library files themselves.
79e259e3 214
60cdb821
UM
215 Use "make install_sw" to install the software without documentation,
216 and "install_docs_html" to install HTML renditions of the manual
217 pages.
218
e5f3045f
BM
219 Package builders who want to configure the library for standard
220 locations, but have the package installed somewhere else so that
221 it can easily be packaged, can use
222
223 $ make INSTALL_PREFIX=/tmp/package-root install
224
7e05db95 225 (or specify "--install_prefix=/tmp/package-root" as a configure
e5f3045f
BM
226 option). The specified prefix will be prepended to all
227 installation target filenames.
228
229
4fd53220
BM
230 NOTE: The header files used to reside directly in the include
231 directory, but have now been moved to include/openssl so that
232 OpenSSL can co-exist with other libraries which use some of the
233 same filenames. This means that applications that use OpenSSL
234 should now use C preprocessor directives of the form
235
236 #include <openssl/ssl.h>
237
238 instead of "#include <ssl.h>", which was used with library versions
239 up to OpenSSL 0.9.2b.
240
241 If you install a new version of OpenSSL over an old library version,
242 you should delete the old header files in the include directory.
243
244 Compatibility issues:
245
246 * COMPILING existing applications
247
248 To compile an application that uses old filenames -- e.g.
249 "#include <ssl.h>" --, it will usually be enough to find
250 the CFLAGS definition in the application's Makefile and
251 add a C option such as
252
253 -I/usr/local/ssl/include/openssl
254
255 to it.
256
257 But don't delete the existing -I option that points to
258 the ..../include directory! Otherwise, OpenSSL header files
259 could not #include each other.
260
261 * WRITING applications
262
263 To write an application that is able to handle both the new
264 and the old directory layout, so that it can still be compiled
265 with library versions up to OpenSSL 0.9.2b without bothering
266 the user, you can proceed as follows:
267
268 - Always use the new filename of OpenSSL header files,
269 e.g. #include <openssl/ssl.h>.
270
271 - Create a directory "incl" that contains only a symbolic
272 link named "openssl", which points to the "include" directory
273 of OpenSSL.
274 For example, your application's Makefile might contain the
275 following rule, if OPENSSLDIR is a pathname (absolute or
276 relative) of the directory where OpenSSL resides:
277
278 incl/openssl:
279 -mkdir incl
280 cd $(OPENSSLDIR) # Check whether the directory really exists
281 -ln -s `cd $(OPENSSLDIR); pwd`/include incl/openssl
282
283 You will have to add "incl/openssl" to the dependencies
284 of those C files that include some OpenSSL header file.
285
286 - Add "-Iincl" to your CFLAGS.
287
288 With these additions, the OpenSSL header files will be available
289 under both name variants if an old library version is used:
290 Your application can reach them under names like <openssl/foo.h>,
291 while the header files still are able to #include each other
292 with names of the form <foo.h>.
293
294
5f8d5c96
BM
295 Note on multi-threading
296 -----------------------
297
298 For some systems, the OpenSSL Configure script knows what compiler options
299 are needed to generate a library that is suitable for multi-threaded
300 applications. On these systems, support for multi-threading is enabled
301 by default; use the "no-threads" option to disable (this should never be
302 necessary).
303
304 On other systems, to enable support for multi-threading, you will have
33d50ef6 305 to specify at least two options: "threads", and a system-dependent option.
5f8d5c96
BM
306 (The latter is "-D_REENTRANT" on various systems.) The default in this
307 case, obviously, is not to include support for multi-threading (but
308 you can still use "no-threads" to suppress an annoying warning message
309 from the Configure script.)
310
fcc6a1c4
RL
311
312 Note on shared libraries
313 ------------------------
314
d9907c97
UM
315 Shared libraries have certain caveats. Binary backward compatibility
316 can't be guaranteed before OpenSSL version 1.0. The only reason to
317 use them would be to conserve memory on systems where several programs
318 are using OpenSSL.
c1c97165 319
fcc6a1c4
RL
320 For some systems, the OpenSSL Configure script knows what is needed to
321 build shared libraries for libcrypto and libssl. On these systems,
322 the shared libraries are currently not created by default, but giving
323 the option "shared" will get them created. This method supports Makefile
324 targets for shared library creation, like linux-shared. Those targets
325 can currently be used on their own just as well, but this is expected
326 to change in future versions of OpenSSL.
96c930dd
LJ
327
328 Note on random number generation
329 --------------------------------
330
331 Availability of cryptographically secure random numbers is required for
332 secret key generation. OpenSSL provides several options to seed the
333 internal PRNG. If not properly seeded, the internal PRNG will refuse
334 to deliver random bytes and a "PRNG not seeded error" will occur.
335 On systems without /dev/urandom (or similar) device, it may be necessary
336 to install additional support software to obtain random seed.
337 Please check out the manual pages for RAND_add(), RAND_bytes(), RAND_egd(),
338 and the FAQ for more information.
4a9476dd
RL
339
340 Note on support for multiple builds
341 -----------------------------------
342
a84c9d1e 343 OpenSSL is usually built in its source tree. Unfortunately, this doesn't
4a9476dd
RL
344 support building for multiple platforms from the same source tree very well.
345 It is however possible to build in a separate tree through the use of lots
346 of symbolic links, which should be prepared like this:
347
348 mkdir -p objtree/"`uname -s`-`uname -r`-`uname -m`"
349 cd objtree/"`uname -s`-`uname -r`-`uname -m`"
350 (cd $OPENSSL_SOURCE; find . -type f) | while read F; do
351 mkdir -p `dirname $F`
4e59cd3b
RL
352 rm -f $F; ln -s $OPENSSL_SOURCE/$F $F
353 echo $F '->' $OPENSSL_SOURCE/$F
4a9476dd 354 done
a0cd3ca6 355 make -f Makefile.org clean
4a9476dd
RL
356
357 OPENSSL_SOURCE is an environment variable that contains the absolute (this
358 is important!) path to the OpenSSL source tree.
359
360 Also, operations like 'make update' should still be made in the source tree.