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) is described in INSTALL.DJGPP.]
9 To install OpenSSL, you will need:
12 * Perl 5 with core modules (please read README.PERL)
13 * The perl module Text::Template (please read README.PERL)
15 * a development environment in the form of development libraries and C
17 * a supported operating system
19 For additional platform specific requirements and other details,
20 please read one of these:
23 * NOTES.WIN (any supported Windows)
28 If you want to just get on with it, do:
44 on Windows (only pick one of the targets for configuration):
46 $ perl Configure { VC-WIN32 | VC-WIN64A | VC-WIN64I | VC-CE }
51 [If any of these steps fails, see section Installation in Detail below.]
53 This will build and install OpenSSL in the default location, which is:
55 Unix: normal installation directories under /usr/local
56 OpenVMS: SYS$COMMON:[OPENSSL-'version'...], where 'version' is the
57 OpenSSL version number with underscores instead of periods.
58 Windows: C:\Program Files\OpenSSL or C:\Program Files (x86)\OpenSSL
60 If you want to install it anywhere else, run config like this:
64 $ ./config --prefix=/opt/openssl --openssldir=/usr/local/ssl
68 $ @config --prefix=PROGRAM:[INSTALLS] --openssldir=SYS$MANAGER:[OPENSSL]
74 There are several options to ./config (or ./Configure) to customize
75 the build (note that for Windows, the defaults for --prefix and
76 --openssldir depend in what configuration is used and what Windows
77 implementation OpenSSL is built on. More notes on this in NOTES.WIN):
80 The top of the installation directory tree. Defaults are:
83 Windows: C:\Program Files\OpenSSL
84 or C:\Program Files (x86)\OpenSSL
85 OpenVMS: SYS$COMMON:[OPENSSL-'version']
88 Directory for OpenSSL configuration files, and also the
89 default certificate and key store. Defaults are:
92 Windows: C:\Program Files\Common Files\SSL
93 or C:\Program Files (x86)\Common Files\SSL
94 OpenVMS: SYS$COMMON:[OPENSSL-COMMON]
97 Don't build with support for deprecated APIs below the
98 specified version number. For example "--api=1.1.0" will
99 remove support for all APIS that were deprecated in OpenSSL
100 version 1.1.0 or below.
103 Don't build the AFALG engine. This option will be forced if
104 on a platform that does not support AFALG.
107 Do not use assembler code. On some platforms a small amount
108 of assembler code may still be used.
111 Do not build support for async operations.
114 Don't automatically load all supported ciphers and digests.
115 Typically OpenSSL will make available all of its supported
116 ciphers and digests. For a statically linked application this
117 may be undesirable if small executable size is an objective.
118 This only affects libcrypto. Ciphers and digests will have to
119 be loaded manually using EVP_add_cipher() and
120 EVP_add_digest() if this option is used. This option will
121 force a non-shared build.
124 Don't automatically load all libcrypto/libssl error strings.
125 Typically OpenSSL will automatically load human readable
126 error strings. For a statically linked application this may
127 be undesirable if small executable size is an objective.
131 Don't build the CAPI engine. This option will be forced if
132 on a platform that does not support CAPI.
135 Don't build support for CMS features
138 Don't build support for SSL/TLS compression. If this option
139 is left enabled (the default), then compression will only
140 work if the zlib or zlib-dynamic options are also chosen.
143 Build support for debugging memory allocated via
144 OPENSSL_malloc() or OPENSSL_zalloc().
146 enable-crypto-mdebug-backtrace
147 As for crypto-mdebug, but additionally provide backtrace
148 information for allocated memory.
151 Don't build support for Certificate Transparency.
154 Don't build with support for any deprecated APIs. This is the
155 same as using "--api" and supplying the latest version
159 Don't build support for datagram based BIOs. Selecting this
160 option will also force the disabling of DTLS.
163 Don't build support for loading Dynamic Shared Objects.
166 Don't build the dynamically loaded engines. This only has an
167 effect in a "shared" build
170 Don't build support for Elliptic Curves.
173 Don't build support for binary Elliptic Curves
175 enable-ec_nistp_64_gcc_128
176 Enable support for optimised implementations of some commonly
177 used NIST elliptic curves. This is only supported on some
181 Build support for gathering entropy from EGD (Entropy
185 Don't build support for loading engines.
188 Don't compile in any error strings.
191 Don't compile in filename and line number information (e.g.
192 for errors and memory allocation).
195 Don't build support for GOST based ciphersuites. Note that
196 if this feature is enabled then GOST ciphersuites are only
197 available if the GOST algorithms are also available through
198 loading an externally supplied engine.
201 Build support for DTLS heartbeats.
204 Don't build the padlock engine.
207 Don't generate dependencies.
210 Don't build support for writing multiple records in one
211 go in libssl (Note: this is a different capability to the
212 pipelining functionality).
215 Don't build support for the NPN TLS extension.
218 Don't build support for OCSP.
221 Don't build with support for Position Independent Code.
224 Don't use POSIX IO capabilities.
227 Don't build support for Pre-Shared Key based ciphersuites.
230 Don't use hardware RDRAND capabilities.
233 Don't build support for RFC3779 ("X.509 Extensions for IP
234 Addresses and AS Identifiers")
237 Build support for SCTP
240 Do not create shared libraries, only static ones. See "Note
241 on shared libraries" below.
244 Don't build support for socket BIOs
247 Don't build support for SRP or SRP based ciphersuites.
250 Don't build SRTP support
253 Exclude SSE2 code paths. Normally SSE2 extension is
254 detected at run-time, but the decision whether or not the
255 machine code will be executed is taken solely on CPU
256 capability vector. This means that if you happen to run OS
257 kernel which does not support SSE2 extension on Intel P4
258 processor, then your application might be exposed to
259 "illegal instruction" exception. There might be a way
260 to enable support in kernel, e.g. FreeBSD kernel can be
261 compiled with CPU_ENABLE_SSE, and there is a way to
262 disengage SSE2 code pathes upon application start-up,
263 but if you aim for wider "audience" running such kernel,
264 consider no-sse2. Both the 386 and no-asm options imply
268 Build with the SSL Trace capabilities (adds the "-trace"
269 option to s_client and s_server).
272 Don't build the statically linked engines. This only
273 has an impact when not built "shared".
276 Don't use any C "stdio" features. Only libcrypto and libssl
277 can be built in this way. Using this option will suppress
278 building the command line applications. Additionally since
279 the OpenSSL tests also use the command line applications the
280 tests will also be skipped.
283 Don't try to build with support for multi-threaded
287 Build with support for multi-threaded applications. Most
288 platforms will enable this by default. However if on a
289 platform where this is not the case then this will usually
290 require additional system-dependent options! See "Note on
291 multi-threading" below.
294 Don't build Time Stamping Authority support.
297 Don't build with the "UI" capability (i.e. the set of
298 features enabling text based prompts).
301 Enable additional unit test APIs. This should not typically
302 be used in production deployments.
304 enable-weak-ssl-ciphers
305 Build support for SSL/TLS ciphers that are considered "weak"
306 (e.g. RC4 based ciphersuites).
309 Build with support for zlib compression/decompression.
312 Like "zlib", but has OpenSSL load the zlib library
313 dynamically when needed. This is only supported on systems
314 where loading of shared libraries is supported.
317 On Intel hardware, use the 80386 instruction set only
318 (the default x86 code is more efficient, but requires at
319 least a 486). Note: Use compiler flags for any other CPU
320 specific configuration, e.g. "-m32" to build x86 code on
324 Don't build support for negotiating the specified SSL/TLS
325 protocol (one of ssl, ssl3, tls, tls1, tls1_1, tls1_2, dtls,
326 dtls1 or dtls1_2). If "no-tls" is selected then all of tls1,
327 tls1_1 and tls1_2 are disabled. Similarly "no-dtls" will
328 disable dtls1 and dtls1_2. The "no-ssl" option is synonymous
329 with "no-ssl3". Note this only affects version negotiation.
330 OpenSSL will still provide the methods for applications to
331 explicitly select the individual protocol versions.
334 As for no-<prot> but in addition do not build the methods for
335 applications to explicitly select individual protocol
339 Build with support for the specified algorithm, where <alg>
340 is one of: md2 or rc5.
343 Build without support for the specified algorithm, where
344 <alg> is one of: bf, blake2, camellia, cast, chacha, cmac,
345 des, dh, dsa, ecdh, ecdsa, idea, md4, md5, mdc2, ocb,
346 ploy1305, rc2, rc4, rmd160, scrypt, seed or whirlpool. The
347 "ripemd" algorithm is deprecated and if used is synonymous
350 -Dxxx, -lxxx, -Lxxx, -fxxx, -mXXX, -Kxxx
351 These system specific options will be passed through to the
352 compiler to allow you to define preprocessor symbols, specify
353 additional libraries, library directories or other compiler
357 Installation in Detail
358 ----------------------
360 1a. Configure OpenSSL for your operation system automatically:
362 NOTE: This is not available on Windows.
364 $ ./config [options] # Unix
368 $ @config [options] ! OpenVMS
370 For the remainder of this text, the Unix form will be used in all
371 examples, please use the appropriate form for your platform.
373 This guesses at your operating system (and compiler, if necessary) and
374 configures OpenSSL based on this guess. Run ./config -t to see
375 if it guessed correctly. If you want to use a different compiler, you
376 are cross-compiling for another platform, or the ./config guess was
377 wrong for other reasons, go to step 1b. Otherwise go to step 2.
379 On some systems, you can include debugging information as follows:
381 $ ./config -d [options]
383 1b. Configure OpenSSL for your operating system manually
385 OpenSSL knows about a range of different operating system, hardware and
386 compiler combinations. To see the ones it knows about, run
392 $ perl Configure # All other platforms
394 For the remainder of this text, the Unix form will be used in all
395 examples, please use the appropriate form for your platform.
397 Pick a suitable name from the list that matches your system. For most
398 operating systems there is a choice between using "cc" or "gcc". When
399 you have identified your system (and if necessary compiler) use this name
400 as the argument to Configure. For example, a "linux-elf" user would
403 $ ./Configure linux-elf [options]
405 If your system isn't listed, you will have to create a configuration
406 file named Configurations/{something}.conf and add the correct
407 configuration for your system. See the available configs as examples
408 and read Configurations/README and Configurations/README.design for
411 The generic configurations "cc" or "gcc" should usually work on 32 bit
414 Configure creates a build file ("Makefile" on Unix and "descrip.mms"
415 on OpenVMS) from a suitable template in Configurations, and
416 defines various macros in crypto/opensslconf.h (generated from
417 crypto/opensslconf.h.in).
419 1c. Configure OpenSSL for building outside of the source tree.
421 OpenSSL can be configured to build in a build directory separate from
422 the directory with the source code. It's done by placing yourself in
423 some other directory and invoking the configuration commands from
428 $ mkdir /var/tmp/openssl-build
429 $ cd /var/tmp/openssl-build
430 $ /PATH/TO/OPENSSL/SOURCE/config [options]
434 $ /PATH/TO/OPENSSL/SOURCE/Configure [target] [options]
438 $ set default sys$login:
439 $ create/dir [.tmp.openssl-build]
440 $ set default [.tmp.openssl-build]
441 $ @[PATH.TO.OPENSSL.SOURCE]config {options}
445 $ @[PATH.TO.OPENSSL.SOURCE]Configure {target} {options}
450 $ mkdir \temp-openssl
452 $ perl d:\PATH\TO\OPENSSL\SOURCE\Configure {target} {options}
454 Paths can be relative just as well as absolute. Configure will
455 do its best to translate them to relative paths whenever possible.
457 2. Build OpenSSL by running:
460 $ mms ! (or mmk) OpenVMS
463 This will build the OpenSSL libraries (libcrypto.a and libssl.a on
464 Unix, corresponding on other platforms) and the OpenSSL binary
465 ("openssl"). The libraries will be built in the top-level directory,
466 and the binary will be in the "apps" subdirectory.
468 If the build fails, look at the output. There may be reasons for
469 the failure that aren't problems in OpenSSL itself (like missing
470 standard headers). If it is a problem with OpenSSL itself, please
471 report the problem to <rt@openssl.org> (note that your message
472 will be recorded in the request tracker publicly readable at
473 https://www.openssl.org/community/index.html#bugs and will be
474 forwarded to a public mailing list). Please check out the request
475 tracker. Maybe the bug was already reported or has already been
478 [If you encounter assembler error messages, try the "no-asm"
479 configuration option as an immediate fix.]
481 Compiling parts of OpenSSL with gcc and others with the system
482 compiler will result in unresolved symbols on some systems.
484 3. After a successful build, the libraries should be tested. Run:
488 $ nmake test # Windows
490 If some tests fail, look at the output. There may be reasons for
491 the failure that isn't a problem in OpenSSL itself (like a
492 malfunction with Perl). You may want increased verbosity, that
493 can be accomplished like this:
495 $ make VERBOSE=1 test # Unix
497 $ mms /macro=(VERBOSE=1) test ! OpenVMS
499 $ nmake VERBOSE=1 test # Windows
501 If you want to run just one or a few specific tests, you can use
502 the make variable TESTS to specify them, like this:
504 $ make TESTS='test_rsa test_dsa' test # Unix
505 $ mms/macro="TESTS=test_rsa test_dsa" test ! OpenVMS
506 $ nmake TESTS='test_rsa test_dsa' test # Windows
508 And of course, you can combine (Unix example shown):
510 $ make VERBOSE=1 TESTS='test_rsa test_dsa' test
512 You can find the list of available tests like this:
514 $ make list-tests # Unix
515 $ mms list-tests ! OpenVMS
516 $ nmake list-tests # Windows
518 Have a look at the manual for the perl module Test::Harness to
519 see what other HARNESS_* variables there are.
521 If you find a problem with OpenSSL itself, try removing any
522 compiler optimization flags from the CFLAGS line in Makefile and
523 run "make clean; make" or corresponding.
525 Please send a bug reports to <rt@openssl.org>.
527 4. If everything tests ok, install OpenSSL with
529 $ make install # Unix
530 $ mms install ! OpenVMS
532 This will install all the software components in this directory
533 tree under PREFIX (the directory given with --prefix or its
538 bin/ Contains the openssl binary and a few other
541 Contains the header files needed if you want
542 to build your own programs that use libcrypto
544 lib Contains the OpenSSL library files.
545 lib/engines Contains the OpenSSL dynamically loadable engines.
546 share/man/{man1,man3,man5,man7}
547 Contains the OpenSSL man-pages.
548 share/doc/openssl/html/{man1,man3,man5,man7}
549 Contains the HTML rendition of the man-pages.
551 OpenVMS ('arch' is replaced with the architecture name, "Alpha"
554 [.EXE.'arch'] Contains the openssl binary and a few other
557 Contains the header files needed if you want
558 to build your own programs that use libcrypto
560 [.LIB.'arch'] Contains the OpenSSL library files.
562 Contains the OpenSSL dynamically loadable engines.
563 [.SYS$STARTUP] Contains startup, login and shutdown scripts.
564 These define appropriate logical names and
568 Additionally, install will add the following directories under
569 OPENSSLDIR (the directory given with --openssldir or its default)
572 certs Initially empty, this is the default location
573 for certificate files.
574 private Initially empty, this is the default location
575 for private key files.
576 misc Various scripts.
578 Package builders who want to configure the library for standard
579 locations, but have the package installed somewhere else so that
580 it can easily be packaged, can use
582 $ make DESTDIR=/tmp/package-root install # Unix
583 $ mms/macro="DESTDIR=TMP:[PACKAGE-ROOT]" install ! OpenVMS
585 The specified destination directory will be prepended to all
586 installation target paths.
588 Compatibility issues with previous OpenSSL versions:
590 * COMPILING existing applications
592 OpenSSL 1.1 hides a number of structures that were previously
593 open. This includes all internal libssl structures and a number
594 of EVP types. Accessor functions have been added to allow
595 controlled access to the structures' data.
597 This means that some software needs to be rewritten to adapt to
598 the new ways of doing things. This often amounts to allocating
599 an instance of a structure explicitly where you could previously
600 allocate them on the stack as automatic variables, and using the
601 provided accessor functions where you would previously access a
602 structure's field directly.
606 Some APIs have changed as well. However, older APIs have been
607 preserved when possible.
610 Note on multi-threading
611 -----------------------
613 For some systems, the OpenSSL Configure script knows what compiler options
614 are needed to generate a library that is suitable for multi-threaded
615 applications. On these systems, support for multi-threading is enabled
616 by default; use the "no-threads" option to disable (this should never be
619 On other systems, to enable support for multi-threading, you will have
620 to specify at least two options: "threads", and a system-dependent option.
621 (The latter is "-D_REENTRANT" on various systems.) The default in this
622 case, obviously, is not to include support for multi-threading (but
623 you can still use "no-threads" to suppress an annoying warning message
624 from the Configure script.)
626 OpenSSL provides built-in support for two threading models: pthreads (found on
627 most UNIX/Linux systems), and Windows threads. No other threading models are
628 supported. If your platform does not provide pthreads or Windows threads then
629 you should Configure with the "no-threads" option.
631 Note on shared libraries
632 ------------------------
634 For most systems the OpenSSL Configure script knows what is needed to
635 build shared libraries for libcrypto and libssl. On these systems
636 the shared libraries will be created by default. This can be suppressed and
637 only static libraries created by using the "no-shared" option. On systems
638 where OpenSSL does not know how to build shared libraries the "no-shared"
639 option will be forced and only static libraries will be created.
641 Note on random number generation
642 --------------------------------
644 Availability of cryptographically secure random numbers is required for
645 secret key generation. OpenSSL provides several options to seed the
646 internal PRNG. If not properly seeded, the internal PRNG will refuse
647 to deliver random bytes and a "PRNG not seeded error" will occur.
648 On systems without /dev/urandom (or similar) device, it may be necessary
649 to install additional support software to obtain random seed.
650 Please check out the manual pages for RAND_add(), RAND_bytes(), RAND_egd(),
651 and the FAQ for more information.