5 [Installation on DOS (with djgpp), MacOS (before MacOS X)
6 and NetWare is described in INSTALL.DJGPP, INSTALL.MacOS
9 This document describes installation on the main supported operating
10 systems, currently the Linux/Unix family, OpenVMS and Windows.]
12 To install OpenSSL, you will need:
15 * Perl 5 with core modules (please read README.PERL)
16 * The perl module Text::Template (please read README.PERL)
18 * a development environment in the form of development libraries and C
20 * a supported operating system
22 For more details regarding specific platforms, there are these notes
26 * NOTES.WIN (any Windows except for Windows CE)
31 If you want to just get on with it, do:
47 on Windows (only pick one of the targets for configuration):
49 $ perl Configure { VC-WIN32 | VC-WIN64A | VC-WIN64I | VC-CE }
53 [If any of these steps fails, see section Installation in Detail below.]
55 This will build and install OpenSSL in the default location, which is:
57 Unix: normal installation directories under /usr/local
58 OpenVMS: SYS$COMMON:[OPENSSL-'version'...], where 'version' is the
59 OpenSSL version number ('major'_'minor').
60 Windows: currently don't have an install function <TBA>
62 If you want to install it anywhere else, run config like this:
66 $ ./config --prefix=/opt/openssl --openssldir=/usr/local/ssl
70 $ @config --prefix=PROGRAM:[INSTALLS] --openssldir=SYS$MANAGER:[OPENSSL]
76 There are several options to ./config (or ./Configure) to customize
79 --prefix=DIR The top of the installation directory tree. Defaults are:
82 OpenVMS: SYS$COMMON:[OPENSSL-'version']
84 --openssldir=DIR Directory for OpenSSL configuration files, and also the
85 default certificate and key store. Defaults are:
87 Unix: PREFIX/ssl (PREFIX is given by --prefix)
88 OpenVMS: SYS$COMMON:[SSL]
90 --api=x.y.z Don't build with support for deprecated APIs below the
91 specified version number. For example "--api=1.1.0" will
92 remove support for all APIS that were deprecated in OpenSSL
93 version 1.1.0 or below.
95 no-deprecated Don't build with support for any deprecated APIs. This is the
96 same as using "--api" and supplying the latest version
99 no-autoalginit Don't automatically load all supported ciphers and digests.
100 Typically OpenSSL will make available all of its supported
101 ciphers and digests. For a statically linked application this
102 may be undesirable if small executable size is an objective.
103 This only affects libcrypto. Ciphers and digests will have to
104 be loaded manually using EVP_add_cipher() and
105 EVP_add_digest() if this option is used.
107 no-autoerrinit Don't automatically load all libcrypto/libssl error strings.
108 Typically OpenSSL will automatically load human readable
109 error strings. For a statically linked application this may
110 be undesirable if small executable size is an objective.
112 no-threads Don't try to build with support for multi-threaded
115 threads Build with support for multi-threaded applications.
116 This will usually require additional system-dependent
117 options! See "Note on multi-threading" below.
119 no-zlib Don't try to build with support for zlib compression and
122 zlib Build with support for zlib compression/decompression.
124 zlib-dynamic Like "zlib", but has OpenSSL load the zlib library
125 dynamically when needed. This is only supported on systems
126 where loading of shared libraries is supported. This is the
129 no-shared Don't try to create shared libraries.
131 shared In addition to the usual static libraries, create shared
132 libraries on platforms where it's supported. See "Note on
133 shared libraries" below.
135 no-asm Do not use assembler code.
137 386 On Intel hardware, use the 80386 instruction set only
138 (the default x86 code is more efficient, but requires at
139 least a 486). Note: Use compiler flags for any other CPU
140 specific configuration, e.g. "-m32" to build x86 code on
143 no-sse2 Exclude SSE2 code pathes. Normally SSE2 extension is
144 detected at run-time, but the decision whether or not the
145 machine code will be executed is taken solely on CPU
146 capability vector. This means that if you happen to run OS
147 kernel which does not support SSE2 extension on Intel P4
148 processor, then your application might be exposed to
149 "illegal instruction" exception. There might be a way
150 to enable support in kernel, e.g. FreeBSD kernel can be
151 compiled with CPU_ENABLE_SSE, and there is a way to
152 disengage SSE2 code pathes upon application start-up,
153 but if you aim for wider "audience" running such kernel,
154 consider no-sse2. Both 386 and no-asm options above imply
157 no-<alg> Build without the specified algorithm (bf, cast, des, dh,
158 dsa, hmac, md2, md5, mdc2, rc2, rc4, rc5, rsa, sha).
160 -Dxxx, -lxxx, These system specific options will be passed through to the
161 -Lxxx, -fxxx, compiler to allow you to define preprocessor symbols, specify
162 -mXXX, -Kxxx additional libraries, library directories or other compiler
166 Installation in Detail
167 ----------------------
169 1a. Configure OpenSSL for your operation system automatically:
171 NOTE: This is not available on Windows.
173 $ ./config [options] # Unix
177 $ @config [options] ! OpenVMS
179 For the remainder of this text, the Unix form will be used in all
180 examples, please use the appropriate form for your platform.
182 This guesses at your operating system (and compiler, if necessary) and
183 configures OpenSSL based on this guess. Run ./config -t to see
184 if it guessed correctly. If you want to use a different compiler, you
185 are cross-compiling for another platform, or the ./config guess was
186 wrong for other reasons, go to step 1b. Otherwise go to step 2.
188 On some systems, you can include debugging information as follows:
190 $ ./config -d [options]
192 1b. Configure OpenSSL for your operating system manually
194 OpenSSL knows about a range of different operating system, hardware and
195 compiler combinations. To see the ones it knows about, run
201 $ perl Configure # All other platforms
203 For the remainder of this text, the Unix form will be used in all
204 examples, please use the appropriate form for your platform.
206 Pick a suitable name from the list that matches your system. For most
207 operating systems there is a choice between using "cc" or "gcc". When
208 you have identified your system (and if necessary compiler) use this name
209 as the argument to Configure. For example, a "linux-elf" user would
212 $ ./Configure linux-elf [options]
214 If your system isn't listed, you will have to create a configuration
215 file named Configurations/{something}.conf and add the correct
216 configuration for your system. See the available configs as examples
217 and read Configurations/README and Configurations/README.design for
220 The generic configurations "cc" or "gcc" should usually work on 32 bit
223 Configure creates a build file ("Makefile" on Unix and "descrip.mms"
224 on OpenVMS) from a suitable template in Configurations, and
225 defines various macros in crypto/opensslconf.h (generated from
226 crypto/opensslconf.h.in).
228 1c. Configure OpenSSL for building outside of the source tree.
230 OpenSSL can be configured to build in a build directory separate from
231 the directory with the source code. It's done by placing yourself in
232 some other directory and invoking the configuration commands from
237 $ mkdir /var/tmp/openssl-build
238 $ cd /var/tmp/openssl-build
239 $ /PATH/TO/OPENSSL/SOURCE/config [options]
243 $ /PATH/TO/OPENSSL/SOURCE/Configure [target] [options]
247 $ set default sys$login:
248 $ create/dir [.tmp.openssl-build]
249 $ set default [.tmp.openssl-build]
250 $ @[PATH.TO.OPENSSL.SOURCE]config {options}
254 $ @[PATH.TO.OPENSSL.SOURCE]Configure {target} {options}
259 $ mkdir \temp-openssl
261 $ perl d:\PATH\TO\OPENSSL\SOURCE\Configure {target} {options}
263 Paths can be relative just as well as absolute. Configure will
264 do its best to translate them to relative paths whenever possible.
266 2. Build OpenSSL by running:
269 $ mms ! (or mmk) OpenVMS
272 This will build the OpenSSL libraries (libcrypto.a and libssl.a on
273 Unix, corresponding on other platforms) and the OpenSSL binary
274 ("openssl"). The libraries will be built in the top-level directory,
275 and the binary will be in the "apps" subdirectory.
277 If the build fails, look at the output. There may be reasons for
278 the failure that aren't problems in OpenSSL itself (like missing
279 standard headers). If it is a problem with OpenSSL itself, please
280 report the problem to <rt@openssl.org> (note that your message
281 will be recorded in the request tracker publicly readable at
282 https://www.openssl.org/community/index.html#bugs and will be
283 forwarded to a public mailing list). Please check out the request
284 tracker. Maybe the bug was already reported or has already been
287 [If you encounter assembler error messages, try the "no-asm"
288 configuration option as an immediate fix.]
290 Compiling parts of OpenSSL with gcc and others with the system
291 compiler will result in unresolved symbols on some systems.
293 3. After a successful build, the libraries should be tested. Run:
297 $ nmake test # Windows
299 If some tests fail, look at the output. There may be reasons for
300 the failure that isn't a problem in OpenSSL itself (like a
301 malfunction with Perl). You may want increased verbosity, that
302 can be accomplished like this:
304 $ HARNESS_VERBOSE=yes make test # Unix
306 $ DEFINE HARNESS_VERBOSE YES
309 $ set HARNESS_VERBOSE=yes
310 $ nmake test # Windows
312 If you want to run just one or a few specific tests, you can use
313 the make variable TESTS to specify them, like this:
315 $ make TESTS='test_rsa test_dsa' test # Unix
316 $ mms/macro="TESTS=test_rsa test_dsa" test ! OpenVMS
317 $ nmake TESTS='test_rsa test_dsa' test # Windows
319 And of course, you can combine (Unix example shown):
321 $ HARNESS_VERBOSE=yes make TESTS='test_rsa test_dsa' test
323 You can find the list of available tests like this:
325 $ make list-tests # Unix
326 $ mms list-tests ! OpenVMS
327 $ nmake list-tests # Windows
329 Have a look at the manual for the perl module Test::Harness to
330 see what other HARNESS_* variables there are.
332 If you find a problem with OpenSSL itself, try removing any
333 compiler optimization flags from the CFLAGS line in Makefile and
334 run "make clean; make" or corresponding.
336 Please send a bug reports to <rt@openssl.org>.
338 4. If everything tests ok, install OpenSSL with
340 $ make install # Unix
341 $ mms install ! OpenVMS
343 This will install all the software components in this directory
344 tree under PREFIX (the directory given with --prefix or its
349 bin/ Contains the openssl binary and a few other
352 Contains the header files needed if you want
353 to build your own programs that use libcrypto
355 lib Contains the OpenSSL library files.
356 lib/engines Contains the OpenSSL dynamically loadable engines.
357 share/man/{man1,man3,man5,man7}
358 Contains the OpenSSL man-pages.
359 share/doc/openssl/html/{man1,man3,man5,man7}
360 Contains the HTML rendition of the man-pages.
362 OpenVMS ('arch' is replaced with the architecture name, "Alpha"
365 [.EXE.'arch'] Contains the openssl binary and a few other
368 Contains the header files needed if you want
369 to build your own programs that use libcrypto
371 [.LIB.'arch'] Contains the OpenSSL library files.
373 Contains the OpenSSL dynamically loadable engines.
374 [.SYS$STARTUP] Contains startup, login and shutdown scripts.
375 These define appropriate logical names and
379 Additionally, install will add the following directories under
380 OPENSSLDIR (the directory given with --openssldir or its default)
383 certs Initially empty, this is the default location
384 for certificate files.
385 private Initially empty, this is the default location
386 for private key files.
387 misc Various scripts.
389 Package builders who want to configure the library for standard
390 locations, but have the package installed somewhere else so that
391 it can easily be packaged, can use
393 $ make DESTDIR=/tmp/package-root install # Unix
394 $ mms/macro="DESTDIR=TMP:[PACKAGE-ROOT]" install ! OpenVMS
396 The specified destination directory will be prepended to all
397 installation target paths.
399 Compatibility issues with previous OpenSSL versions:
401 * COMPILING existing applications
403 OpenSSL 1.1 hides a number of structures that were previously
404 open. This includes all internal libssl structures and a number
405 of EVP types. Accessor functions have been added to allow
406 controlled access to the structures' data.
408 This means that some software needs to be rewritten to adapt to
409 the new ways of doing things. This often amounts to allocating
410 an instance of a structure explicitly where you could previously
411 allocate them on the stack as automatic variables, and using the
412 provided accessor functions where you would previously access a
413 structure's field directly.
417 Some APIs have changed as well. However, older APIs have been
418 preserved when possible.
421 Note on multi-threading
422 -----------------------
424 For some systems, the OpenSSL Configure script knows what compiler options
425 are needed to generate a library that is suitable for multi-threaded
426 applications. On these systems, support for multi-threading is enabled
427 by default; use the "no-threads" option to disable (this should never be
430 On other systems, to enable support for multi-threading, you will have
431 to specify at least two options: "threads", and a system-dependent option.
432 (The latter is "-D_REENTRANT" on various systems.) The default in this
433 case, obviously, is not to include support for multi-threading (but
434 you can still use "no-threads" to suppress an annoying warning message
435 from the Configure script.)
437 OpenSSL provides built-in support for two threading models: pthreads (found on
438 most UNIX/Linux systems), and Windows threads. No other threading models are
439 supported. If your platform does not provide pthreads or Windows threads then
440 you should Configure with the "no-threads" option.
442 Note on shared libraries
443 ------------------------
445 Shared libraries have certain caveats. Binary backward compatibility
446 can't be guaranteed before OpenSSL version 1.0. The only reason to
447 use them would be to conserve memory on systems where several programs
450 For most systems, the OpenSSL Configure script knows what is needed to
451 build shared libraries for libcrypto and libssl. On these systems,
452 the shared libraries are currently not created by default, but giving
453 the option "shared" will get them created.
455 Note on random number generation
456 --------------------------------
458 Availability of cryptographically secure random numbers is required for
459 secret key generation. OpenSSL provides several options to seed the
460 internal PRNG. If not properly seeded, the internal PRNG will refuse
461 to deliver random bytes and a "PRNG not seeded error" will occur.
462 On systems without /dev/urandom (or similar) device, it may be necessary
463 to install additional support software to obtain random seed.
464 Please check out the manual pages for RAND_add(), RAND_bytes(), RAND_egd(),
465 and the FAQ for more information.