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