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