]>
Commit | Line | Data |
---|---|---|
79e259e3 | 1 | |
4109b97c RE |
2 | INSTALLATION ON THE UNIX PLATFORM |
3 | --------------------------------- | |
79e259e3 | 4 | |
2acd8ec7 RL |
5 | [Installation on DOS (with djgpp), Windows, MacOS (before MacOS X) |
6 | and NetWare is described in INSTALL.DJGPP, INSTALL.WIN, INSTALL.MacOS | |
7 | and INSTALL.NW. | |
4d8743f4 | 8 | |
2acd8ec7 RL |
9 | This document describes installation on the main supported operating |
10 | systems, currently the Unix family and OpenVMS.] | |
4109b97c RE |
11 | |
12 | To install OpenSSL, you will need: | |
79e259e3 | 13 | |
d57d85ff | 14 | * make |
d36ab9ce RL |
15 | * Perl 5 with core modules (please read README.PERL) |
16 | * The perl module Text::Template (please read README.PERL) | |
73bfb9ad | 17 | * an ANSI C compiler |
d57d85ff RL |
18 | * a development environment in form of development libraries and C |
19 | header files | |
2acd8ec7 RL |
20 | * a supported operating system |
21 | ||
22 | For more details regarding specific platforms, there are these notes | |
23 | available: | |
24 | ||
25 | * NOTES.VMS | |
79e259e3 | 26 | |
4109b97c RE |
27 | Quick Start |
28 | ----------- | |
79e259e3 | 29 | |
4109b97c | 30 | If you want to just get on with it, do: |
79e259e3 | 31 | |
2acd8ec7 RL |
32 | on Unix: |
33 | ||
34 | $ ./config | |
35 | $ make | |
36 | $ make test | |
37 | $ make install | |
38 | ||
39 | on OpenVMS: | |
40 | ||
41 | $ @config | |
42 | $ mms | |
43 | $ mms test | |
44 | $ mms install | |
79e259e3 | 45 | |
d872c55c | 46 | [If any of these steps fails, see section Installation in Detail below.] |
b1fe6b43 | 47 | |
2acd8ec7 RL |
48 | This will build and install OpenSSL in the default location, which is: |
49 | ||
50 | Unix: normal installation directories under /usr/local | |
51 | OpenVMS: SYS$COMMON:[OPENSSL-'version'...], where 'version' is the | |
52 | OpenSSL version number ('major'_'minor'). | |
53 | ||
54 | If you want to install it anywhere else, run config like this: | |
79e259e3 | 55 | |
2acd8ec7 RL |
56 | On Unix: |
57 | ||
58 | $ ./config --prefix=/opt/openssl --openssldir=/usr/local/ssl | |
59 | ||
60 | On OpenVMS: | |
61 | ||
62 | $ @config --prefix=PROGRAM:[INSTALLS] --openssldir=SYS$MANAGER:[OPENSSL] | |
79e259e3 | 63 | |
b1fe6b43 UM |
64 | |
65 | Configuration Options | |
66 | --------------------- | |
67 | ||
2d99cee7 BM |
68 | There are several options to ./config (or ./Configure) to customize |
69 | the build: | |
2613c1fa | 70 | |
2acd8ec7 | 71 | --prefix=DIR The top of the installation directory tree. Defaults are: |
462ba4f6 | 72 | |
2acd8ec7 RL |
73 | Unix: /usr/local |
74 | OpenVMS: SYS$COMMON:[OPENSSL-'version'] | |
75 | ||
76 | --openssldir=DIR Directory for OpenSSL configuration files, and also the | |
77 | default certificate and key store. Defaults are: | |
78 | ||
79 | Unix: PREFIX/ssl (PREFIX is given by --prefix) | |
80 | OpenVMS: SYS$COMMON:[SSL] | |
462ba4f6 | 81 | |
8b75603c MC |
82 | no-autoalginit Don't automatically load all supported ciphers and digests. |
83 | Typically OpenSSL will make available all of its supported | |
84 | ciphers and digests. For a statically linked application this | |
85 | may be undesirable if small executable size is an objective. | |
86 | This only affects libcrypto. Ciphers and digests will have to be | |
87 | loaded manually using EVP_add_cipher() and EVP_add_digest() if | |
88 | this option is used. | |
89 | ||
90 | no-autoerrinit Don't automatically load all libcrypto/libssl error strings. | |
91 | Typically OpenSSL will automatically load human readable error | |
92 | strings. For a statically linked application this may be | |
93 | undesirable if small executable size is an objective. | |
94 | ||
5f8d5c96 BM |
95 | no-threads Don't try to build with support for multi-threaded |
96 | applications. | |
97 | ||
98 | threads Build with support for multi-threaded applications. | |
99 | This will usually require additional system-dependent options! | |
100 | See "Note on multi-threading" below. | |
101 | ||
e452de9d RL |
102 | no-zlib Don't try to build with support for zlib compression and |
103 | decompression. | |
104 | ||
105 | zlib Build with support for zlib compression/decompression. | |
106 | ||
107 | zlib-dynamic Like "zlib", but has OpenSSL load the zlib library dynamically | |
108 | when needed. This is only supported on systems where loading | |
f1ca5f5b | 109 | of shared libraries is supported. This is the default choice. |
e452de9d | 110 | |
fcc6a1c4 RL |
111 | no-shared Don't try to create shared libraries. |
112 | ||
113 | shared In addition to the usual static libraries, create shared | |
114 | libraries on platforms where it's supported. See "Note on | |
115 | shared libraries" below. | |
116 | ||
b1fe6b43 | 117 | no-asm Do not use assembler code. |
462ba4f6 | 118 | |
2acd8ec7 RL |
119 | 386 On Intel hardware, use the 80386 instruction set only |
120 | (the default x86 code is more efficient, but requires at | |
121 | least a 486). Note: Use compiler flags for any other CPU | |
122 | specific configuration, e.g. "-m32" to build x86 code on | |
123 | an x64 system. | |
2613c1fa | 124 | |
478b50cf | 125 | no-sse2 Exclude SSE2 code pathes. Normally SSE2 extension is |
216ddfaf AP |
126 | detected at run-time, but the decision whether or not the |
127 | machine code will be executed is taken solely on CPU | |
128 | capability vector. This means that if you happen to run OS | |
129 | kernel which does not support SSE2 extension on Intel P4 | |
130 | processor, then your application might be exposed to | |
131 | "illegal instruction" exception. There might be a way | |
132 | to enable support in kernel, e.g. FreeBSD kernel can be | |
133 | compiled with CPU_ENABLE_SSE, and there is a way to | |
134 | disengage SSE2 code pathes upon application start-up, | |
135 | but if you aim for wider "audience" running such kernel, | |
136 | consider no-sse2. Both 386 and no-asm options above imply | |
137 | no-sse2. | |
138 | ||
b1fe6b43 UM |
139 | no-<cipher> Build without the specified cipher (bf, cast, des, dh, dsa, |
140 | hmac, md2, md5, mdc2, rc2, rc4, rc5, rsa, sha). | |
92afda6c UM |
141 | The crypto/<cipher> directory can be removed after running |
142 | "make depend". | |
b1fe6b43 | 143 | |
a84c9d1e | 144 | -Dxxx, -lxxx, -Lxxx, -fxxx, -mXXX, -Kxxx These system specific options will |
b1fe6b43 UM |
145 | be passed through to the compiler to allow you to |
146 | define preprocessor symbols, specify additional libraries, | |
147 | library directories or other compiler options. | |
148 | ||
79e259e3 | 149 | |
4109b97c RE |
150 | Installation in Detail |
151 | ---------------------- | |
c9f06e7f | 152 | |
4109b97c | 153 | 1a. Configure OpenSSL for your operation system automatically: |
c9f06e7f | 154 | |
2acd8ec7 RL |
155 | $ ./config [options] # Unix |
156 | ||
157 | or | |
158 | ||
159 | $ @config [options] ! OpenVMS | |
160 | ||
161 | For the remainder of this text, the Unix form will be used in all | |
162 | examples, please use the appropriate form for your platform. | |
c9f06e7f | 163 | |
4109b97c | 164 | This guesses at your operating system (and compiler, if necessary) and |
b1fe6b43 | 165 | configures OpenSSL based on this guess. Run ./config -t to see |
db209ec2 UM |
166 | if it guessed correctly. If you want to use a different compiler, you |
167 | are cross-compiling for another platform, or the ./config guess was | |
168 | wrong for other reasons, go to step 1b. Otherwise go to step 2. | |
c9f06e7f | 169 | |
b1fe6b43 UM |
170 | On some systems, you can include debugging information as follows: |
171 | ||
172 | $ ./config -d [options] | |
173 | ||
c9f06e7f | 174 | 1b. Configure OpenSSL for your operating system manually |
79e259e3 | 175 | |
4109b97c RE |
176 | OpenSSL knows about a range of different operating system, hardware and |
177 | compiler combinations. To see the ones it knows about, run | |
79e259e3 | 178 | |
2acd8ec7 RL |
179 | $ ./Configure # Unix |
180 | ||
181 | or | |
182 | ||
183 | $ perl Configure # All other platforms | |
184 | ||
185 | For the remainder of this text, the Unix form will be used in all | |
186 | examples, please use the appropriate form for your platform. | |
79e259e3 | 187 | |
4109b97c RE |
188 | Pick a suitable name from the list that matches your system. For most |
189 | operating systems there is a choice between using "cc" or "gcc". When | |
190 | you have identified your system (and if necessary compiler) use this name | |
2acd8ec7 | 191 | as the argument to Configure. For example, a "linux-elf" user would |
4109b97c | 192 | run: |
79e259e3 | 193 | |
b1fe6b43 | 194 | $ ./Configure linux-elf [options] |
79e259e3 PS |
195 | |
196 | If your system is not available, you will have to edit the Configure | |
73bfb9ad | 197 | program and add the correct configuration for your system. The |
db209ec2 UM |
198 | generic configurations "cc" or "gcc" should usually work on 32 bit |
199 | systems. | |
79e259e3 | 200 | |
d10dac11 | 201 | Configure creates the file Makefile.ssl from Makefile.in and |
b1fe6b43 | 202 | defines various macros in crypto/opensslconf.h (generated from |
80611577 | 203 | crypto/opensslconf.h.in). |
79e259e3 | 204 | |
2acd8ec7 RL |
205 | 1c. Configure OpenSSL for building outside of the source tree. |
206 | ||
207 | OpenSSL can be configured to build in a build directory separate from | |
208 | the directory with the source code. It's done by placing yourself in | |
209 | some other directory and invoking the configuration commands from | |
210 | there. | |
211 | ||
212 | Unix example: | |
213 | ||
214 | $ mkdir /var/tmp/openssl-build | |
215 | $ cd /var/tmp/openssl-build | |
216 | $ /PATH/TO/OPENSSL/SOURCE/config [options] | |
217 | ||
218 | or | |
219 | ||
220 | $ /PATH/TO/OPENSSL/SOURCE/Configure [target] [options] | |
221 | ||
222 | OpenVMS example: | |
223 | ||
224 | $ set default sys$login: | |
225 | $ create/dir [.tmp.openssl-build] | |
226 | $ set default [.tmp.openssl-build] | |
227 | $ @[PATH.TO.OPENSSL.SOURCE]config {options} | |
228 | ||
229 | or | |
230 | ||
231 | $ @[PATH.TO.OPENSSL.SOURCE]Configure {target} {options} | |
232 | ||
233 | Paths can be relative just as well as absolute. Configure will | |
234 | do its best to translate them to relative paths whenever possible. | |
235 | ||
462ba4f6 | 236 | 2. Build OpenSSL by running: |
79e259e3 | 237 | |
2acd8ec7 RL |
238 | $ make # Unix |
239 | $ mms ! (or mmk) OpenVMS | |
79e259e3 | 240 | |
2acd8ec7 RL |
241 | This will build the OpenSSL libraries (libcrypto.a and libssl.a on |
242 | Unix, corresponding on other platforms) and the OpenSSL binary | |
243 | ("openssl"). The libraries will be built in the top-level directory, | |
244 | and the binary will be in the "apps" subdirectory. | |
79e259e3 | 245 | |
2acd8ec7 | 246 | If the build fails, look at the output. There may be reasons for |
9020b862 | 247 | the failure that aren't problems in OpenSSL itself (like missing |
a652ffc4 | 248 | standard headers). If it is a problem with OpenSSL itself, please |
2acd8ec7 RL |
249 | report the problem to <rt@openssl.org> (note that your message |
250 | will be recorded in the request tracker publicly readable at | |
251 | https://www.openssl.org/community/index.html#bugs and will be | |
41977c53 RS |
252 | forwarded to a public mailing list). Include the output of "make |
253 | report" in your message. Please check out the request tracker. Maybe | |
254 | the bug was already reported or has already been fixed. | |
b1fe6b43 | 255 | |
436a376b | 256 | [If you encounter assembler error messages, try the "no-asm" |
b82ccbb7 | 257 | configuration option as an immediate fix.] |
436a376b | 258 | |
91174a91 UM |
259 | Compiling parts of OpenSSL with gcc and others with the system |
260 | compiler will result in unresolved symbols on some systems. | |
261 | ||
462ba4f6 | 262 | 3. After a successful build, the libraries should be tested. Run: |
79e259e3 | 263 | |
2acd8ec7 RL |
264 | $ make test # Unix |
265 | $ mms test ! OpenVMS | |
79e259e3 | 266 | |
2e996acf RL |
267 | If some tests fail, look at the output. There may be reasons for |
268 | the failure that isn't a problem in OpenSSL itself (like a | |
269 | malfunction with Perl). You may want increased verbosity, that | |
270 | can be accomplished like this: | |
271 | ||
2acd8ec7 RL |
272 | $ HARNESS_VERBOSE=yes make test # Unix |
273 | ||
274 | $ DEFINE HARNESS_VERBOSE YES | |
275 | $ mms test ! OpenVMS | |
2e996acf | 276 | |
2e996acf RL |
277 | If you want to run just one or a few specific tests, you can use |
278 | the make variable TESTS to specify them, like this: | |
279 | ||
2acd8ec7 RL |
280 | $ make TESTS='test_rsa test_dsa' test # Unix |
281 | $ mms/macro="TESTS=test_rsa test_dsa" test ! OpenVMS | |
2e996acf | 282 | |
2acd8ec7 | 283 | And of course, you can combine (Unix example shown): |
2e996acf RL |
284 | |
285 | $ HARNESS_VERBOSE=yes make TESTS='test_rsa test_dsa' test | |
286 | ||
287 | You can find the list of available tests like this: | |
288 | ||
2acd8ec7 RL |
289 | $ make list-tests # Unix |
290 | $ make list-tests ! OpenVMS | |
2e996acf | 291 | |
d40b0622 RL |
292 | Have a look at the manual for the perl module Test::Harness to |
293 | see what other HARNESS_* variables there are. | |
294 | ||
2e996acf | 295 | If you find a problem with OpenSSL itself, try removing any |
2acd8ec7 RL |
296 | compiler optimization flags from the CFLAGS line in Makefile and |
297 | run "make clean; make" or corresponding. | |
2e996acf RL |
298 | |
299 | Please send a bug report to <openssl-bugs@openssl.org>, and when | |
300 | you do, please run the following and include the output in your | |
301 | report: | |
302 | ||
303 | $ make report | |
b1fe6b43 | 304 | |
462ba4f6 | 305 | 4. If everything tests ok, install OpenSSL with |
79e259e3 | 306 | |
2acd8ec7 RL |
307 | $ make install # Unix |
308 | $ mms install ! OpenVMS | |
309 | ||
310 | This will install all the software components in this directory | |
311 | tree under PREFIX (the directory given with --prefix or its | |
312 | default): | |
313 | ||
314 | Unix: | |
315 | ||
316 | bin/ Contains the openssl binary and a few other | |
317 | utility scripts. | |
318 | include/openssl | |
319 | Contains the header files needed if you want | |
320 | to build your own programs that use libcrypto | |
321 | or libssl. | |
322 | lib Contains the OpenSSL library files. | |
323 | lib/engines Contains the OpenSSL dynamically loadable engines. | |
324 | share/man/{man1,man3,man5,man7} | |
325 | Contains the OpenSSL man-pages. | |
326 | share/doc/openssl/html{man1,man3,man5,man7} | |
327 | Contains the HTML rendition of the man-pages. | |
328 | ||
329 | OpenVMS ('arch' is replaced with the architecture name, "Alpha" | |
330 | or "ia64"): | |
331 | ||
332 | [.EXE.'arch'] Contains the openssl binary and a few other | |
333 | utility scripts. | |
334 | [.include.openssl] | |
335 | Contains the header files needed if you want | |
336 | to build your own programs that use libcrypto | |
337 | or libssl. | |
338 | [.LIB.'arch'] Contains the OpenSSL library files. | |
339 | [.ENGINES.'arch'] | |
340 | Contains the OpenSSL dynamically loadable engines. | |
341 | [.SYS$STARTUP] Contains startup, login and shutdown scripts. | |
342 | These define appropriate logical names and | |
343 | command symbols. | |
344 | ||
345 | ||
346 | Additionally, install will add the following directories under | |
347 | OPENSSLDIR (the directory given with --openssldir or its default) | |
348 | for you convenience: | |
349 | ||
350 | certs Initially empty, this is the default location | |
351 | for certificate files. | |
352 | private Initially empty, this is the default location | |
353 | for private key files. | |
354 | misc Various scripts. | |
60cdb821 | 355 | |
e5f3045f BM |
356 | Package builders who want to configure the library for standard |
357 | locations, but have the package installed somewhere else so that | |
358 | it can easily be packaged, can use | |
359 | ||
2acd8ec7 RL |
360 | $ make DESTDIR=/tmp/package-root install # Unix |
361 | $ mms/macro="DESTDIR=TMP:[PACKAGE-ROOT]" install ! OpenVMS | |
e5f3045f | 362 | |
3c65577f | 363 | The specified destination directory will be prepended to all |
2acd8ec7 | 364 | installation target paths. |
4fd53220 | 365 | |
2acd8ec7 | 366 | Compatibility issues with previous OpenSSL versions: |
4fd53220 BM |
367 | |
368 | * COMPILING existing applications | |
369 | ||
2acd8ec7 RL |
370 | OpenSSL 1.1 hides a number of structures that were previously |
371 | open. This includes all internal libssl structures and a number | |
372 | of EVP types. Accessor functions have been added to allow | |
373 | controlled access to the structures' data. | |
4fd53220 | 374 | |
2acd8ec7 RL |
375 | This means that some software needs to be rewritten to adapt to |
376 | the new ways of doing things. This often amounts to allocating | |
377 | an instance of a structure explicitly where you could previously | |
378 | allocate them on the stack as automatic variables, and using the | |
379 | provided accessor functions where you would previously access a | |
380 | structure's field directly. | |
4fd53220 | 381 | |
2acd8ec7 | 382 | <TBA> |
4fd53220 | 383 | |
2acd8ec7 RL |
384 | Some APIs have changed as well. However, older APIs have been |
385 | preserved when possible. | |
4fd53220 BM |
386 | |
387 | ||
5f8d5c96 BM |
388 | Note on multi-threading |
389 | ----------------------- | |
390 | ||
391 | For some systems, the OpenSSL Configure script knows what compiler options | |
392 | are needed to generate a library that is suitable for multi-threaded | |
393 | applications. On these systems, support for multi-threading is enabled | |
394 | by default; use the "no-threads" option to disable (this should never be | |
395 | necessary). | |
396 | ||
397 | On other systems, to enable support for multi-threading, you will have | |
33d50ef6 | 398 | to specify at least two options: "threads", and a system-dependent option. |
5f8d5c96 BM |
399 | (The latter is "-D_REENTRANT" on various systems.) The default in this |
400 | case, obviously, is not to include support for multi-threading (but | |
401 | you can still use "no-threads" to suppress an annoying warning message | |
402 | from the Configure script.) | |
403 | ||
35d8fa56 | 404 | OpenSSL provides built-in support for two threading models: pthreads (found on |
8b75603c MC |
405 | most UNIX/Linux systems), and Windows threads. No other threading models are |
406 | supported. If your platform does not provide pthreads or Windows threads then | |
407 | you should Configure with the "no-threads" option. | |
fcc6a1c4 RL |
408 | |
409 | Note on shared libraries | |
410 | ------------------------ | |
411 | ||
d9907c97 UM |
412 | Shared libraries have certain caveats. Binary backward compatibility |
413 | can't be guaranteed before OpenSSL version 1.0. The only reason to | |
414 | use them would be to conserve memory on systems where several programs | |
415 | are using OpenSSL. | |
c1c97165 | 416 | |
fcc6a1c4 RL |
417 | For some systems, the OpenSSL Configure script knows what is needed to |
418 | build shared libraries for libcrypto and libssl. On these systems, | |
419 | the shared libraries are currently not created by default, but giving | |
420 | the option "shared" will get them created. This method supports Makefile | |
421 | targets for shared library creation, like linux-shared. Those targets | |
422 | can currently be used on their own just as well, but this is expected | |
423 | to change in future versions of OpenSSL. | |
96c930dd LJ |
424 | |
425 | Note on random number generation | |
426 | -------------------------------- | |
427 | ||
428 | Availability of cryptographically secure random numbers is required for | |
429 | secret key generation. OpenSSL provides several options to seed the | |
430 | internal PRNG. If not properly seeded, the internal PRNG will refuse | |
431 | to deliver random bytes and a "PRNG not seeded error" will occur. | |
432 | On systems without /dev/urandom (or similar) device, it may be necessary | |
433 | to install additional support software to obtain random seed. | |
434 | Please check out the manual pages for RAND_add(), RAND_bytes(), RAND_egd(), | |
435 | and the FAQ for more information. | |
4a9476dd | 436 |