Always wait for both threads to finish
[openssl.git] / INSTALL.md
1 Build and Install
2 =================
3
4 This document describes installation on all supported operating
5 systems (the Unix/Linux family, including macOS), OpenVMS,
6 and Windows).
7
8 Table of Contents
9 =================
10
11  - [Prerequisites](#prerequisites)
12  - [Notational Conventions](#notational-conventions)
13  - [Quick Installation Guide](#quick-installation-guide)
14    - [Building OpenSSL](#building-openssl)
15    - [Installing OpenSSL](#installing-openssl)
16  - [Configuration Options](#configuration-options)
17    - [API Level](#api-level)
18    - [Cross Compile Prefix](#cross-compile-prefix)
19    - [Build Type](#build-type)
20    - [Directories](#directories)
21    - [Compiler Warnings](#compiler-warnings)
22    - [ZLib Flags](#zlib-flags)
23    - [Seeding the Random Generator](#seeding-the-random-generator)
24    - [Setting the FIPS HMAC key](#setting-the-FIPS-HMAC-key)
25    - [Enable and Disable Features](#enable-and-disable-features)
26    - [Displaying configuration data](#displaying-configuration-data)
27  - [Installation Steps in Detail](#installation-steps-in-detail)
28    - [Configure](#configure-openssl)
29    - [Build](#build-openssl)
30    - [Test](#test-openssl)
31    - [Install](#install-openssl)
32  - [Advanced Build Options](#advanced-build-options)
33    - [Environment Variables](#environment-variables)
34    - [Makefile Targets](#makefile-targets)
35    - [Running Selected Tests](#running-selected-tests)
36  - [Troubleshooting](#troubleshooting)
37    - [Configuration Problems](#configuration-problems)
38    - [Build Failures](#build-failures)
39    - [Test Failures](#test-failures)
40  - [Notes](#notes)
41    - [Notes on multi-threading](#notes-on-multi-threading)
42    - [Notes on shared libraries](#notes-on-shared-libraries)
43    - [Notes on random number generation](#notes-on-random-number-generation)
44    - [Notes on assembler modules compilation](#notes-on-assembler-modules-compilation)
45
46 Prerequisites
47 =============
48
49 To install OpenSSL, you will need:
50
51  * A "make" implementation
52  * Perl 5 with core modules (please read [NOTES-PERL.md](NOTES-PERL.md))
53  * The Perl module `Text::Template` (please read [NOTES-PERL.md](NOTES-PERL.md))
54  * an ANSI C compiler
55  * a development environment in the form of development libraries and C
56    header files
57  * a supported operating system
58
59 For additional platform specific requirements, solutions to specific
60 issues and other details, please read one of these:
61
62  * [Notes for UNIX-like platforms](NOTES-UNIX.md)
63  * [Notes for Android platforms](NOTES-ANDROID.md)
64  * [Notes for Windows platforms](NOTES-WINDOWS.md)
65  * [Notes for the DOS platform with DJGPP](NOTES-DJGPP.md)
66  * [Notes for the OpenVMS platform](NOTES-VMS.md)
67  * [Notes on Perl](NOTES-PERL.md)
68  * [Notes on Valgrind](NOTES-VALGRIND.md)
69
70 Notational conventions
71 ======================
72
73 Throughout this document, we use the following conventions.
74
75 Commands
76 --------
77
78 Any line starting with a dollar sign is a command line.
79
80     $ command
81
82 The dollar sign indicates the shell prompt and is not to be entered as
83 part of the command.
84
85 Choices
86 -------
87
88 Several words in curly braces separated by pipe characters indicate a
89 **mandatory choice**, to be replaced with one of the given words.
90 For example, the line
91
92     $ echo { WORD1 | WORD2 | WORD3 }
93
94 represents one of the following three commands
95
96     $ echo WORD1
97     - or -
98     $ echo WORD2
99     - or -
100     $ echo WORD3
101
102 One or several words in square brackets separated by pipe characters
103 denote an **optional choice**.  It is similar to the mandatory choice,
104 but it can also be omitted entirely.
105
106 So the line
107
108     $ echo [ WORD1 | WORD2 | WORD3 ]
109
110 represents one of the four commands
111
112     $ echo WORD1
113     - or -
114     $ echo WORD2
115     - or -
116     $ echo WORD3
117     - or -
118     $ echo
119
120 Arguments
121 ---------
122
123 **Mandatory arguments** are enclosed in double curly braces.
124 A simple example would be
125
126     $ type {{ filename }}
127
128 which is to be understood to use the command `type` on some file name
129 determined by the user.
130
131 **Optional Arguments** are enclosed in double square brackets.
132
133     [[ options ]]
134
135 Note that the notation assumes spaces around `{`, `}`, `[`, `]`, `{{`, `}}` and
136 `[[`, `]]`.  This is to differentiate from OpenVMS directory
137 specifications, which also use [ and ], but without spaces.
138
139 Quick Installation Guide
140 ========================
141
142 If you just want to get OpenSSL installed without bothering too much
143 about the details, here is the short version of how to build and install
144 OpenSSL.  If any of the following steps fails, please consult the
145 [Installation in Detail](#installation-steps-in-detail) section below.
146
147 Building OpenSSL
148 ----------------
149
150 Use the following commands to configure, build and test OpenSSL.
151 The testing is optional, but recommended if you intend to install
152 OpenSSL for production use.
153
154 ### Unix / Linux / macOS
155
156     $ ./Configure
157     $ make
158     $ make test
159
160 ### OpenVMS
161
162 Use the following commands to build OpenSSL:
163
164     $ perl Configure
165     $ mms
166     $ mms test
167
168 ### Windows
169
170 If you are using Visual Studio, open a Developer Command Prompt and
171 issue the following commands to build OpenSSL.
172
173     $ perl Configure
174     $ nmake
175     $ nmake test
176
177 As mentioned in the [Choices](#choices) section, you need to pick one
178 of the four Configure targets in the first command.
179
180 Most likely you will be using the `VC-WIN64A` target for 64bit Windows
181 binaries (AMD64) or `VC-WIN32` for 32bit Windows binaries (X86).
182 The other two options are `VC-WIN64I` (Intel IA64, Itanium) and
183 `VC-CE` (Windows CE) are rather uncommon nowadays.
184
185 Installing OpenSSL
186 ------------------
187
188 The following commands will install OpenSSL to a default system location.
189
190 **Danger Zone:** even if you are impatient, please read the following two
191 paragraphs carefully before you install OpenSSL.
192
193 For security reasons the default system location is by default not writable
194 for unprivileged users.  So for the final installation step administrative
195 privileges are required.  The default system location and the procedure to
196 obtain administrative privileges depends on the operating system.
197 It is recommended to compile and test OpenSSL with normal user privileges
198 and use administrative privileges only for the final installation step.
199
200 On some platforms OpenSSL is preinstalled as part of the Operating System.
201 In this case it is highly recommended not to overwrite the system versions,
202 because other applications or libraries might depend on it.
203 To avoid breaking other applications, install your copy of OpenSSL to a
204 [different location](#installing-to-a-different-location) which is not in
205 the global search path for system libraries.
206
207 Finally, if you plan on using the FIPS module, you need to read the
208 [Post-installation Notes](#post-installation-notes) further down.
209
210 ### Unix / Linux / macOS
211
212 Depending on your distribution, you need to run the following command as
213 root user or prepend `sudo` to the command:
214
215     $ make install
216
217 By default, OpenSSL will be installed to
218
219     /usr/local
220
221 More precisely, the files will be installed into the  subdirectories
222
223     /usr/local/bin
224     /usr/local/lib
225     /usr/local/include
226     ...
227
228 depending on the file type, as it is custom on Unix-like operating systems.
229
230 ### OpenVMS
231
232 Use the following command to install OpenSSL.
233
234     $ mms install
235
236 By default, OpenSSL will be installed to
237
238     SYS$COMMON:[OPENSSL]
239
240 ### Windows
241
242 If you are using Visual Studio, open the Developer Command Prompt _elevated_
243 and issue the following command.
244
245     $ nmake install
246
247 The easiest way to elevate the Command Prompt is to press and hold down
248 the both the `<CTRL>` and `<SHIFT>` key while clicking the menu item in the
249 task menu.
250
251 The default installation location is
252
253     C:\Program Files\OpenSSL
254
255 for native binaries, or
256
257     C:\Program Files (x86)\OpenSSL
258
259 for 32bit binaries on 64bit Windows (WOW64).
260
261 #### Installing to a different location
262
263 To install OpenSSL to a different location (for example into your home
264 directory for testing purposes) run `Configure` as shown in the following
265 examples.
266
267 The options `--prefix` and `--openssldir` are explained in further detail in
268 [Directories](#directories) below, and the values used here are mere examples.
269
270 On Unix:
271
272     $ ./Configure --prefix=/opt/openssl --openssldir=/usr/local/ssl
273
274 On OpenVMS:
275
276     $ perl Configure --prefix=PROGRAM:[INSTALLS] --openssldir=SYS$MANAGER:[OPENSSL]
277
278 Note: if you do add options to the configuration command, please make sure
279 you've read more than just this Quick Start, such as relevant `NOTES-*` files,
280 the options outline below, as configuration options may change the outcome
281 in otherwise unexpected ways.
282
283 Configuration Options
284 =====================
285
286 There are several options to `./Configure` to customize the build (note that
287 for Windows, the defaults for `--prefix` and `--openssldir` depend on what
288 configuration is used and what Windows implementation OpenSSL is built on.
289 For more information, see the [Notes for Windows platforms](NOTES-WINDOWS.md).
290
291 API Level
292 ---------
293
294     --api=x.y[.z]
295
296 Build the OpenSSL libraries to support the API for the specified version.
297 If [no-deprecated](#no-deprecated) is also given, don't build with support
298 for deprecated APIs in or below the specified version number.  For example,
299 addding
300
301     --api=1.1.0 no-deprecated
302
303 will remove support for all APIs that were deprecated in OpenSSL version
304 1.1.0 or below.  This is a rather specialized option for developers.
305 If you just intend to remove all deprecated APIs up to the current version
306 entirely, just specify [no-deprecated](#no-deprecated).
307 If `--api` isn't given, it defaults to the current (minor) OpenSSL version.
308
309 Cross Compile Prefix
310 --------------------
311
312     --cross-compile-prefix=<PREFIX>
313
314 The `<PREFIX>` to include in front of commands for your toolchain.
315
316 It is likely to have to end with dash, e.g. `a-b-c-` would invoke GNU compiler
317 as `a-b-c-gcc`, etc.  Unfortunately cross-compiling is too case-specific to put
318 together one-size-fits-all instructions.  You might have to pass more flags or
319 set up environment variables to actually make it work.  Android and iOS cases
320 are discussed in corresponding `Configurations/15-*.conf` files.  But there are
321 cases when this option alone is sufficient.  For example to build the mingw64
322 target on Linux `--cross-compile-prefix=x86_64-w64-mingw32-` works.  Naturally
323 provided that mingw packages are installed.  Today Debian and Ubuntu users
324 have option to install a number of prepackaged cross-compilers along with
325 corresponding run-time and development packages for "alien" hardware.  To give
326 another example `--cross-compile-prefix=mipsel-linux-gnu-` suffices in such
327 case.
328
329 For cross compilation, you must [configure manually](#manual-configuration).
330 Also, note that `--openssldir` refers to target's file system, not one you are
331 building on.
332
333 Build Type
334 ----------
335
336     --debug
337
338 Build OpenSSL with debugging symbols and zero optimization level.
339
340     --release
341
342 Build OpenSSL without debugging symbols.  This is the default.
343
344 Directories
345 -----------
346
347 ### libdir
348
349     --libdir=DIR
350
351 The name of the directory under the top of the installation directory tree
352 (see the `--prefix` option) where libraries will be installed.  By default
353 this is `lib/`. Note that on Windows only static libraries (`*.lib`) will
354 be stored in this location. Shared libraries (`*.dll`) will always be
355 installed to the `bin/` directory.
356
357 ### openssldir
358
359     --openssldir=DIR
360
361 Directory for OpenSSL configuration files, and also the default certificate
362 and key store.  Defaults are:
363
364     Unix:           /usr/local/ssl
365     Windows:        C:\Program Files\Common Files\SSL
366     OpenVMS:        SYS$COMMON:[OPENSSL-COMMON]
367
368 For 32bit Windows applications on Windows 64bit (WOW64), always replace
369 `C:\Program Files` by `C:\Program Files (x86)`.
370
371 ### prefix
372
373     --prefix=DIR
374
375 The top of the installation directory tree.  Defaults are:
376
377     Unix:           /usr/local
378     Windows:        C:\Program Files\OpenSSL
379     OpenVMS:        SYS$COMMON:[OPENSSL]
380
381 Compiler Warnings
382 -----------------
383
384     --strict-warnings
385
386 This is a developer flag that switches on various compiler options recommended
387 for OpenSSL development.  It only works when using gcc or clang as the compiler.
388 If you are developing a patch for OpenSSL then it is recommended that you use
389 this option where possible.
390
391 ZLib Flags
392 ----------
393
394 ### with-zlib-include
395
396     --with-zlib-include=DIR
397
398 The directory for the location of the zlib include file.  This option is only
399 necessary if [zlib](#zlib) is used and the include file is not
400 already on the system include path.
401
402 ### with-zlib-lib
403
404     --with-zlib-lib=LIB
405
406 **On Unix**: this is the directory containing the zlib library.
407 If not provided the system library path will be used.
408
409 **On Windows:** this is the filename of the zlib library (with or
410 without a path).  This flag must be provided if the
411 [zlib-dynamic](#zlib-dynamic) option is not also used. If `zlib-dynamic` is used
412 then this flag is optional and defaults to `ZLIB1` if not provided.
413
414 **On VMS:** this is the filename of the zlib library (with or without a path).
415 This flag is optional and if not provided then `GNV$LIBZSHR`, `GNV$LIBZSHR32`
416 or `GNV$LIBZSHR64` is used by default depending on the pointer size chosen.
417
418 Seeding the Random Generator
419 ----------------------------
420
421     --with-rand-seed=seed1[,seed2,...]
422
423 A comma separated list of seeding methods which will be tried by OpenSSL
424 in order to obtain random input (a.k.a "entropy") for seeding its
425 cryptographically secure random number generator (CSPRNG).
426 The current seeding methods are:
427
428 ### os
429
430 Use a trusted operating system entropy source.
431 This is the default method if such an entropy source exists.
432
433 ### getrandom
434
435 Use the [getrandom(2)][man-getrandom] or equivalent system call.
436
437 [man-getrandom]: http://man7.org/linux/man-pages/man2/getrandom.2.html
438
439 ### devrandom
440
441 Use the first device from the `DEVRANDOM` list which can be opened to read
442 random bytes.  The `DEVRANDOM` preprocessor constant expands to
443
444     "/dev/urandom","/dev/random","/dev/srandom"
445
446 on most unix-ish operating systems.
447
448 ### egd
449
450 Check for an entropy generating daemon.
451 This source is ignored by the FIPS provider.
452
453 ### rdcpu
454
455 Use the `RDSEED` or `RDRAND` command if provided by the CPU.
456
457 ### librandom
458
459 Use librandom (not implemented yet).
460 This source is ignored by the FIPS provider.
461
462 ### none
463
464 Disable automatic seeding.  This is the default on some operating systems where
465 no suitable entropy source exists, or no support for it is implemented yet.
466 This option is ignored by the FIPS provider.
467
468 For more information, see the section [Notes on random number generation][rng]
469 at the end of this document.
470
471 [rng]: #notes-on-random-number-generation
472
473 Setting the FIPS HMAC key
474 -------------------------
475
476     --fips-key=value
477
478 As part of its self-test validation, the FIPS module must verify itself
479 by performing a SHA-256 HMAC computation on itself. The default key is
480 the SHA256 value of "the holy handgrenade of antioch" and is sufficient
481 for meeting the FIPS requirements.
482
483 To change the key to a different value, use this flag. The value should
484 be a hex string no more than 64 characters.
485
486 Enable and Disable Features
487 ---------------------------
488
489 Feature options always come in pairs, an option to enable feature
490 `xxxx`, and an option to disable it:
491
492     [ enable-xxxx | no-xxxx ]
493
494 Whether a feature is enabled or disabled by default, depends on the feature.
495 In the following list, always the non-default variant is documented: if
496 feature `xxxx` is disabled by default then `enable-xxxx` is documented and
497 if feature `xxxx` is enabled by default then `no-xxxx` is documented.
498
499 ### no-afalgeng
500
501 Don't build the AFALG engine.
502
503 This option will be forced on a platform that does not support AFALG.
504
505 ### enable-ktls
506
507 Build with Kernel TLS support.
508
509 This option will enable the use of the Kernel TLS data-path, which can improve
510 performance and allow for the use of sendfile and splice system calls on
511 TLS sockets.  The Kernel may use TLS accelerators if any are available on the
512 system.  This option will be forced off on systems that do not support the
513 Kernel TLS data-path.
514
515 ### enable-asan
516
517 Build with the Address sanitiser.
518
519 This is a developer option only.  It may not work on all platforms and should
520 never be used in production environments.  It will only work when used with
521 gcc or clang and should be used in conjunction with the [no-shared](#no-shared)
522 option.
523
524 ### no-acvp_tests
525
526 Do not build support for Automated Cryptographic Validation Protocol (ACVP)
527 tests.
528
529 This is required for FIPS validation purposes. Certain ACVP tests require
530 access to algorithm internals that are not normally accessible.
531 Additional information related to ACVP can be found at
532 <https://github.com/usnistgov/ACVP>.
533
534 ### no-asm
535
536 Do not use assembler code.
537
538 This should be viewed as debugging/troubleshooting option rather than for
539 production use.  On some platforms a small amount of assembler code may still
540 be used even with this option.
541
542 ### no-async
543
544 Do not build support for async operations.
545
546 ### no-autoalginit
547
548 Don't automatically load all supported ciphers and digests.
549
550 Typically OpenSSL will make available all of its supported ciphers and digests.
551 For a statically linked application this may be undesirable if small executable
552 size is an objective.  This only affects libcrypto.  Ciphers and digests will
553 have to be loaded manually using `EVP_add_cipher()` and `EVP_add_digest()`
554 if this option is used.  This option will force a non-shared build.
555
556 ### no-autoerrinit
557
558 Don't automatically load all libcrypto/libssl error strings.
559
560 Typically OpenSSL will automatically load human readable error strings.  For a
561 statically linked application this may be undesirable if small executable size
562 is an objective.
563
564 ### no-autoload-config
565
566 Don't automatically load the default `openssl.cnf` file.
567
568 Typically OpenSSL will automatically load a system config file which configures
569 default SSL options.
570
571 ### enable-buildtest-c++
572
573 While testing, generate C++ buildtest files that simply check that the public
574 OpenSSL header files are usable standalone with C++.
575
576 Enabling this option demands extra care.  For any compiler flag given directly
577 as configuration option, you must ensure that it's valid for both the C and
578 the C++ compiler.  If not, the C++ build test will most likely break.  As an
579 alternative, you can use the language specific variables, `CFLAGS` and `CXXFLAGS`.
580
581 ### no-bulk
582
583 Build only some minimal set of features.
584 This is a developer option used internally for CI build tests of the project.
585
586 ### no-cached-fetch
587
588 Never cache algorithms when they are fetched from a provider.  Normally, a
589 provider indicates if the algorithms it supplies can be cached or not.  Using
590 this option will reduce run-time memory usage but it also introduces a
591 significant performance penalty.  This option is primarily designed to help
592 with detecting incorrect reference counting.
593
594 ### no-capieng
595
596 Don't build the CAPI engine.
597
598 This option will be forced if on a platform that does not support CAPI.
599
600 ### no-cmp
601
602 Don't build support for Certificate Management Protocol (CMP)
603 and Certificate Request Message Format (CRMF).
604
605 ### no-cms
606
607 Don't build support for Cryptographic Message Syntax (CMS).
608
609 ### no-comp
610
611 Don't build support for SSL/TLS compression.
612
613 If this option is enabled (the default), then compression will only work if
614 the zlib or `zlib-dynamic` options are also chosen.
615
616 ### enable-crypto-mdebug
617
618 This now only enables the `failed-malloc` feature.
619
620 ### enable-crypto-mdebug-backtrace
621
622 This is a no-op; the project uses the compiler's address/leak sanitizer instead.
623
624 ### no-ct
625
626 Don't build support for Certificate Transparency (CT).
627
628 ### no-deprecated
629
630 Don't build with support for deprecated APIs up until and including the version
631 given with `--api` (or the current version, if `--api` wasn't specified).
632
633 ### no-dgram
634
635 Don't build support for datagram based BIOs.
636
637 Selecting this option will also force the disabling of DTLS.
638
639 ### no-dso
640
641 Don't build support for loading Dynamic Shared Objects (DSO)
642
643 ### enable-devcryptoeng
644
645 Build the `/dev/crypto` engine.
646
647 This option is automatically selected on the BSD platform, in which case it can
648 be disabled with `no-devcryptoeng`.
649
650 ### no-dynamic-engine
651
652 Don't build the dynamically loaded engines.
653
654 This only has an effect in a shared build.
655
656 ### no-ec
657
658 Don't build support for Elliptic Curves.
659
660 ### no-ec2m
661
662 Don't build support for binary Elliptic Curves
663
664 ### enable-ec_nistp_64_gcc_128
665
666 Enable support for optimised implementations of some commonly used NIST
667 elliptic curves.
668
669 This option is only supported on platforms:
670
671  - with little-endian storage of non-byte types
672  - that tolerate misaligned memory references
673  - where the compiler:
674    - supports the non-standard type `__uint128_t`
675    - defines the built-in macro `__SIZEOF_INT128__`
676
677 ### enable-egd
678
679 Build support for gathering entropy from the Entropy Gathering Daemon (EGD).
680
681 ### no-engine
682
683 Don't build support for loading engines.
684
685 ### no-err
686
687 Don't compile in any error strings.
688
689 ### enable-external-tests
690
691 Enable building of integration with external test suites.
692
693 This is a developer option and may not work on all platforms.  The following
694 external test suites are currently supported:
695
696  - GOST engine test suite
697  - Python PYCA/Cryptography test suite
698  - krb5 test suite
699
700 See the file [test/README-external.md](test/README-external.md)
701 for further details.
702
703 ### no-filenames
704
705 Don't compile in filename and line number information (e.g.  for errors and
706 memory allocation).
707
708 ### no-fips
709
710 Don't compile the FIPS provider
711
712 ### no-fips-securitychecks
713
714 Don't perform FIPS module run-time checks related to enforcement of security
715 parameters such as minimum security strength of keys.
716
717 ### enable-fuzz-libfuzzer, enable-fuzz-afl
718
719 Build with support for fuzzing using either libfuzzer or AFL.
720
721 These are developer options only.  They may not work on all  platforms and
722 should never be used in production environments.
723
724 See the file [fuzz/README.md](fuzz/README.md) for further details.
725
726 ### no-gost
727
728 Don't build support for GOST based ciphersuites.
729
730 Note that if this feature is enabled then GOST ciphersuites are only available
731 if the GOST algorithms are also available through loading an externally supplied
732 engine.
733
734 ### no-legacy
735
736 Don't build the legacy provider.
737
738 Disabling this also disables the legacy algorithms: MD2 (already disabled by default).
739
740 ### no-makedepend
741
742 Don't generate dependencies.
743
744 ### no-module
745
746 Don't build any dynamically loadable engines.
747
748 This also implies `no-dynamic-engine`.
749
750 ### no-multiblock
751
752 Don't build support for writing multiple records in one go in libssl
753
754 Note: this is a different capability to the pipelining functionality.
755
756 ### no-nextprotoneg
757
758 Don't build support for the Next Protocol Negotiation (NPN) TLS extension.
759
760 ### no-ocsp
761
762 Don't build support for Online Certificate Status Protocol (OCSP).
763
764 ### no-padlockeng
765
766 Don't build the padlock engine.
767
768 ### no-hw-padlock
769
770 As synonym for `no-padlockeng`.  Deprecated and should not be used.
771
772 ### no-pic
773
774 Don't build with support for Position Independent Code.
775
776 ### no-pinshared
777
778 Don't pin the shared libraries.
779
780 By default OpenSSL will attempt to stay in memory until the process exits.
781 This is so that libcrypto and libssl can be properly cleaned up automatically
782 via an `atexit()` handler.  The handler is registered by libcrypto and cleans
783 up both libraries.  On some platforms the `atexit()` handler will run on unload of
784 libcrypto (if it has been dynamically loaded) rather than at process exit.  This
785 option can be used to stop OpenSSL from attempting to stay in memory until the
786 process exits.  This could lead to crashes if either libcrypto or libssl have
787 already been unloaded at the point that the atexit handler is invoked, e.g.  on a
788 platform which calls `atexit()` on unload of the library, and libssl is unloaded
789 before libcrypto then a crash is likely to happen.  Applications can suppress
790 running of the `atexit()` handler at run time by using the
791 `OPENSSL_INIT_NO_ATEXIT` option to `OPENSSL_init_crypto()`.
792 See the man page for it for further details.
793
794 ### no-posix-io
795
796 Don't use POSIX IO capabilities.
797
798 ### no-psk
799
800 Don't build support for Pre-Shared Key based ciphersuites.
801
802 ### no-rdrand
803
804 Don't use hardware RDRAND capabilities.
805
806 ### no-rfc3779
807
808 Don't build support for RFC3779, "X.509 Extensions for IP Addresses and
809 AS Identifiers".
810
811 ### sctp
812
813 Build support for Stream Control Transmission Protocol (SCTP).
814
815 ### no-shared
816
817 Do not create shared libraries, only static ones.
818
819 See [Notes on shared libraries](#notes-on-shared-libraries) below.
820
821 ### no-sock
822
823 Don't build support for socket BIOs.
824
825 ### no-srp
826
827 Don't build support for Secure Remote Password (SRP) protocol or
828 SRP based ciphersuites.
829
830 ### no-srtp
831
832 Don't build Secure Real-Time Transport Protocol (SRTP) support.
833
834 ### no-sse2
835
836 Exclude SSE2 code paths from 32-bit x86 assembly modules.
837
838 Normally SSE2 extension is detected at run-time, but the decision whether or not
839 the machine code will be executed is taken solely on CPU capability vector.  This
840 means that if you happen to run OS kernel which does not support SSE2 extension
841 on Intel P4 processor, then your application might be exposed to "illegal
842 instruction" exception.  There might be a way to enable support in kernel, e.g.
843 FreeBSD kernel can be compiled with `CPU_ENABLE_SSE`, and there is a way to
844 disengage SSE2 code paths upon application start-up, but if you aim for wider
845 "audience" running such kernel, consider `no-sse2`.  Both the `386` and `no-asm`
846 options imply `no-sse2`.
847
848 ### enable-ssl-trace
849
850 Build with the SSL Trace capabilities.
851
852 This adds the `-trace` option to `s_client` and `s_server`.
853
854 ### no-static-engine
855
856 Don't build the statically linked engines.
857
858 This only has an impact when not built "shared".
859
860 ### no-stdio
861
862 Don't use anything from the C header file `stdio.h` that makes use of the `FILE`
863 type.  Only libcrypto and libssl can be built in this way.  Using this option will
864 suppress building the command line applications.  Additionally, since the OpenSSL
865 tests also use the command line applications, the tests will also be skipped.
866
867 ### no-tests
868
869 Don't build test programs or run any tests.
870
871 ### no-threads
872
873 Don't build with support for multi-threaded applications.
874
875 ### threads
876
877 Build with support for multi-threaded applications.  Most platforms will enable
878 this by default.  However, if on a platform where this is not the case then this
879 will usually require additional system-dependent options!
880
881 See [Notes on multi-threading](#notes-on-multi-threading) below.
882
883 ### enable-trace
884
885 Build with support for the integrated tracing api.
886
887 See manual pages OSSL_trace_set_channel(3) and OSSL_trace_enabled(3) for details.
888
889 ### no-ts
890
891 Don't build Time Stamping (TS) Authority support.
892
893 ### enable-ubsan
894
895 Build with the Undefined Behaviour sanitiser (UBSAN).
896
897 This is a developer option only.  It may not work on all platforms and should
898 never be used in production environments.  It will only work when used with
899 gcc or clang and should be used in conjunction with the `-DPEDANTIC` option
900 (or the `--strict-warnings` option).
901
902 ### no-ui-console
903
904 Don't build with the User Interface (UI) console method
905
906 The User Interface console method enables text based console prompts.
907
908 ### enable-unit-test
909
910 Enable additional unit test APIs.
911
912 This should not typically be used in production deployments.
913
914 ### no-uplink
915
916 Don't build support for UPLINK interface.
917
918 ### enable-weak-ssl-ciphers
919
920 Build support for SSL/TLS ciphers that are considered "weak"
921
922 Enabling this includes for example the RC4 based ciphersuites.
923
924 ### zlib
925
926 Build with support for zlib compression/decompression.
927
928 ### zlib-dynamic
929
930 Like the zlib option, but has OpenSSL load the zlib library dynamically
931 when needed.
932
933 This is only supported on systems where loading of shared libraries is supported.
934
935 ### 386
936
937 In 32-bit x86 builds, use the 80386 instruction set only in assembly modules
938
939 The default x86 code is more efficient, but requires at least an 486 processor.
940 Note: This doesn't affect compiler generated code, so this option needs to be
941 accompanied by a corresponding compiler-specific option.
942
943 ### no-{protocol}
944
945     no-{ssl|ssl3|tls|tls1|tls1_1|tls1_2|tls1_3|dtls|dtls1|dtls1_2}
946
947 Don't build support for negotiating the specified SSL/TLS protocol.
948
949 If `no-tls` is selected then all of `tls1`, `tls1_1`, `tls1_2` and `tls1_3`
950 are disabled.
951 Similarly `no-dtls` will disable `dtls1` and `dtls1_2`.  The `no-ssl` option is
952 synonymous with `no-ssl3`.  Note this only affects version negotiation.
953 OpenSSL will still provide the methods for applications to explicitly select
954 the individual protocol versions.
955
956 ### no-{protocol}-method
957
958     no-{ssl|ssl3|tls|tls1|tls1_1|tls1_2|tls1_3|dtls|dtls1|dtls1_2}-method
959
960 Analogous to `no-{protocol}` but in addition do not build the methods for
961 applications to explicitly select individual protocol versions.  Note that there
962 is no `no-tls1_3-method` option because there is no application method for
963 TLSv1.3.
964
965 Using individual protocol methods directly is deprecated.  Applications should
966 use `TLS_method()` instead.
967
968 ### enable-{algorithm}
969
970     enable-{md2|rc5}
971
972 Build with support for the specified algorithm.
973
974 ### no-{algorithm}
975
976     no-{aria|bf|blake2|camellia|cast|chacha|cmac|
977         des|dh|dsa|ecdh|ecdsa|idea|md4|mdc2|ocb|
978         poly1305|rc2|rc4|rmd160|scrypt|seed|
979         siphash|siv|sm2|sm3|sm4|whirlpool}
980
981 Build without support for the specified algorithm.
982
983 The `ripemd` algorithm is deprecated and if used is synonymous with `rmd160`.
984
985 ### Compiler-specific options
986
987     -Dxxx, -Ixxx, -Wp, -lxxx, -Lxxx, -Wl, -rpath, -R, -framework, -static
988
989 These system specific options will be recognised and passed through to the
990 compiler to allow you to define preprocessor symbols, specify additional
991 libraries, library directories or other compiler options.  It might be worth
992 noting that some compilers generate code specifically for processor the
993 compiler currently executes on.  This is not necessarily what you might have
994 in mind, since it might be unsuitable for execution on other, typically older,
995 processor.  Consult your compiler documentation.
996
997 Take note of the [Environment Variables](#environment-variables) documentation
998 below and how these flags interact with those variables.
999
1000     -xxx, +xxx, /xxx
1001
1002 Additional options that are not otherwise recognised are passed through as
1003 they are to the compiler as well.  Unix-style options beginning with a
1004 `-` or `+` and Windows-style options beginning with a `/` are recognized.
1005 Again, consult your compiler documentation.
1006
1007 If the option contains arguments separated by spaces, then the URL-style
1008 notation `%20` can be used for the space character in order to avoid having
1009 to quote the option.  For example, `-opt%20arg` gets expanded to `-opt arg`.
1010 In fact, any ASCII character can be encoded as %xx using its hexadecimal
1011 encoding.
1012
1013 Take note of the [Environment Variables](#environment-variables) documentation
1014 below and how these flags interact with those variables.
1015
1016 ### Environment Variables
1017
1018     VAR=value
1019
1020 Assign the given value to the environment variable `VAR` for `Configure`.
1021
1022 These work just like normal environment variable assignments, but are supported
1023 on all platforms and are confined to the configuration scripts only.
1024 These assignments override the corresponding value in the inherited environment,
1025 if there is one.
1026
1027 The following variables are used as "`make` variables" and can be used as an
1028 alternative to giving preprocessor, compiler and linker options directly as
1029 configuration.  The following variables are supported:
1030
1031     AR              The static library archiver.
1032     ARFLAGS         Flags for the static library archiver.
1033     AS              The assembler compiler.
1034     ASFLAGS         Flags for the assembler compiler.
1035     CC              The C compiler.
1036     CFLAGS          Flags for the C compiler.
1037     CXX             The C++ compiler.
1038     CXXFLAGS        Flags for the C++ compiler.
1039     CPP             The C/C++ preprocessor.
1040     CPPFLAGS        Flags for the C/C++ preprocessor.
1041     CPPDEFINES      List of CPP macro definitions, separated
1042                     by a platform specific character (':' or
1043                     space for Unix, ';' for Windows, ',' for
1044                     VMS).  This can be used instead of using
1045                     -D (or what corresponds to that on your
1046                     compiler) in CPPFLAGS.
1047     CPPINCLUDES     List of CPP inclusion directories, separated
1048                     the same way as for CPPDEFINES.  This can
1049                     be used instead of -I (or what corresponds
1050                     to that on your compiler) in CPPFLAGS.
1051     HASHBANGPERL    Perl invocation to be inserted after '#!'
1052                     in public perl scripts (only relevant on
1053                     Unix).
1054     LD              The program linker (not used on Unix, $(CC)
1055                     is used there).
1056     LDFLAGS         Flags for the shared library, DSO and
1057                     program linker.
1058     LDLIBS          Extra libraries to use when linking.
1059                     Takes the form of a space separated list
1060                     of library specifications on Unix and
1061                     Windows, and as a comma separated list of
1062                     libraries on VMS.
1063     RANLIB          The library archive indexer.
1064     RC              The Windows resource compiler.
1065     RCFLAGS         Flags for the Windows resource compiler.
1066     RM              The command to remove files and directories.
1067
1068 These cannot be mixed with compiling/linking flags given on the command line.
1069 In other words, something like this isn't permitted.
1070
1071     $ ./Configure -DFOO CPPFLAGS=-DBAR -DCOOKIE
1072
1073 Backward compatibility note:
1074
1075 To be compatible with older configuration scripts, the environment variables
1076 are ignored if compiling/linking flags are given on the command line, except
1077 for the following:
1078
1079     AR, CC, CXX, CROSS_COMPILE, HASHBANGPERL, PERL, RANLIB, RC, and WINDRES
1080
1081 For example, the following command will not see `-DBAR`:
1082
1083     $ CPPFLAGS=-DBAR ./Configure -DCOOKIE
1084
1085 However, the following will see both set variables:
1086
1087     $ CC=gcc CROSS_COMPILE=x86_64-w64-mingw32- ./Configure -DCOOKIE
1088
1089 If `CC` is set, it is advisable to also set `CXX` to ensure both the C and C++
1090 compiler are in the same "family".  This becomes relevant with
1091 `enable-external-tests` and `enable-buildtest-c++`.
1092
1093 ### Reconfigure
1094
1095     reconf
1096     reconfigure
1097
1098 Reconfigure from earlier data.
1099
1100 This fetches the previous command line options and environment from data
1101 saved in `configdata.pm` and runs the configuration process again, using
1102 these options and environment.  Note: NO other option is permitted together
1103 with `reconf`.  Note: The original configuration saves away values for ALL
1104 environment variables that were used, and if they weren't defined, they are
1105 still saved away with information that they weren't originally defined.
1106 This information takes precedence over environment variables that are
1107 defined when reconfiguring.
1108
1109 Displaying configuration data
1110 -----------------------------
1111
1112 The configuration script itself will say very little, and finishes by
1113 creating `configdata.pm`.  This perl module can be loaded by other scripts
1114 to find all the configuration data, and it can also be used as a script to
1115 display all sorts of configuration data in a human readable form.
1116
1117 For more information, please do:
1118
1119     $ ./configdata.pm --help                         # Unix
1120
1121 or
1122
1123     $ perl configdata.pm --help                      # Windows and VMS
1124
1125 Installation Steps in Detail
1126 ============================
1127
1128 Configure OpenSSL
1129 -----------------
1130
1131 ### Automatic Configuration
1132
1133 On some platform a `config` script is available which attempts to guess
1134 your operating system (and compiler, if necessary) and calls the `Configure`
1135 Perl script with appropriate target based on its guess.  Further options can
1136 be supplied to the `config` script, which will be passed on to the `Configure`
1137 script.
1138
1139 #### Unix / Linux / macOS
1140
1141     $ ./Configure [[ options ]]
1142
1143 #### OpenVMS
1144
1145     $ perl Configure [[ options ]]
1146
1147 #### Windows
1148
1149     $ perl Configure [[ options ]]
1150
1151 ### Manual Configuration
1152
1153 OpenSSL knows about a range of different operating system, hardware and
1154 compiler combinations.  To see the ones it knows about, run
1155
1156     $ ./Configure LIST                               # Unix
1157
1158 or
1159
1160     $ perl Configure LIST                            # All other platforms
1161
1162 For the remainder of this text, the Unix form will be used in all examples.
1163 Please use the appropriate form for your platform.
1164
1165 Pick a suitable name from the list that matches your system.  For most
1166 operating systems there is a choice between using cc or gcc.
1167 When you have identified your system (and if necessary compiler) use this
1168 name as the argument to `Configure`.  For example, a `linux-elf` user would
1169 run:
1170
1171     $ ./Configure linux-elf [[ options ]]
1172
1173 ### Creating your own Configuration
1174
1175 If your system isn't listed, you will have to create a configuration
1176 file named `Configurations/{{ something }}.conf` and add the correct
1177 configuration for your system.  See the available configs as examples
1178 and read [Configurations/README.md](Configurations/README.md) and
1179 [Configurations/README-design.md](Configurations/README-design.md)
1180 for more information.
1181
1182 The generic configurations `cc` or `gcc` should usually work on 32 bit
1183 Unix-like systems.
1184
1185 `Configure` creates a build file (`Makefile` on Unix, `makefile` on Windows
1186 and `descrip.mms` on OpenVMS) from a suitable template in `Configurations/`,
1187 and defines various macros in `include/openssl/configuration.h` (generated
1188 from `include/openssl/configuration.h.in`.
1189
1190 ### Out of Tree Builds
1191
1192 OpenSSL can be configured to build in a build directory separate from the
1193 source code directory.  It's done by placing yourself in some other
1194 directory and invoking the configuration commands from there.
1195
1196 #### Unix example
1197
1198     $ mkdir /var/tmp/openssl-build
1199     $ cd /var/tmp/openssl-build
1200     $ /PATH/TO/OPENSSL/SOURCE/Configure [[ options ]]
1201
1202 #### OpenVMS example
1203
1204     $ set default sys$login:
1205     $ create/dir [.tmp.openssl-build]
1206     $ set default [.tmp.openssl-build]
1207     $ perl D:[PATH.TO.OPENSSL.SOURCE]Configure [[ options ]]
1208
1209 #### Windows example
1210
1211     $ C:
1212     $ mkdir \temp-openssl
1213     $ cd \temp-openssl
1214     $ perl d:\PATH\TO\OPENSSL\SOURCE\Configure [[ options ]]
1215
1216 Paths can be relative just as well as absolute.  `Configure` will do its best
1217 to translate them to relative paths whenever possible.
1218
1219 Build OpenSSL
1220 -------------
1221
1222 Build OpenSSL by running:
1223
1224     $ make                                           # Unix
1225     $ mms                                            ! (or mmk) OpenVMS
1226     $ nmake                                          # Windows
1227
1228 This will build the OpenSSL libraries (`libcrypto.a` and `libssl.a` on
1229 Unix, corresponding on other platforms) and the OpenSSL binary
1230 (`openssl`).  The libraries will be built in the top-level directory,
1231 and the binary will be in the `apps/` subdirectory.
1232
1233 If the build fails, take a look at the [Build Failures](#build-failures)
1234 subsection of the [Troubleshooting](#troubleshooting) section.
1235
1236 Test OpenSSL
1237 ------------
1238
1239 After a successful build, and before installing, the libraries should
1240 be tested.  Run:
1241
1242     $ make test                                      # Unix
1243     $ mms test                                       ! OpenVMS
1244     $ nmake test                                     # Windows
1245
1246 **Warning:** you MUST run the tests from an unprivileged account (or disable
1247 your privileges temporarily if your platform allows it).
1248
1249 See [test/README.md](test/README.md) for further details how run tests.
1250
1251 See [test/README-dev.md](test/README-dev.md) for guidelines on adding tests.
1252
1253 Install OpenSSL
1254 ---------------
1255
1256 If everything tests ok, install OpenSSL with
1257
1258     $ make install                                   # Unix
1259     $ mms install                                    ! OpenVMS
1260     $ nmake install                                  # Windows
1261
1262 Note that in order to perform the install step above you need to have
1263 appropriate permissions to write to the installation directory.
1264
1265 The above commands will install all the software components in this
1266 directory tree under `<PREFIX>` (the directory given with `--prefix` or
1267 its default):
1268
1269 ### Unix / Linux / macOS
1270
1271     bin/           Contains the openssl binary and a few other
1272                    utility scripts.
1273     include/openssl
1274                    Contains the header files needed if you want
1275                    to build your own programs that use libcrypto
1276                    or libssl.
1277     lib            Contains the OpenSSL library files.
1278     lib/engines    Contains the OpenSSL dynamically loadable engines.
1279
1280     share/man/man1 Contains the OpenSSL command line man-pages.
1281     share/man/man3 Contains the OpenSSL library calls man-pages.
1282     share/man/man5 Contains the OpenSSL configuration format man-pages.
1283     share/man/man7 Contains the OpenSSL other misc man-pages.
1284
1285     share/doc/openssl/html/man1
1286     share/doc/openssl/html/man3
1287     share/doc/openssl/html/man5
1288     share/doc/openssl/html/man7
1289                    Contains the HTML rendition of the man-pages.
1290
1291 ### OpenVMS
1292
1293 'arch' is replaced with the architecture name, `ALPHA` or `IA64`,
1294 'sover' is replaced with the shared library version (`0101` for 1.1), and
1295 'pz' is replaced with the pointer size OpenSSL was built with:
1296
1297     [.EXE.'arch']  Contains the openssl binary.
1298     [.EXE]         Contains a few utility scripts.
1299     [.include.openssl]
1300                    Contains the header files needed if you want
1301                    to build your own programs that use libcrypto
1302                    or libssl.
1303     [.LIB.'arch']  Contains the OpenSSL library files.
1304     [.ENGINES'sover''pz'.'arch']
1305                    Contains the OpenSSL dynamically loadable engines.
1306     [.SYS$STARTUP] Contains startup, login and shutdown scripts.
1307                    These define appropriate logical names and
1308                    command symbols.
1309     [.SYSTEST]     Contains the installation verification procedure.
1310     [.HTML]        Contains the HTML rendition of the manual pages.
1311
1312 ### Additional Directories
1313
1314 Additionally, install will add the following directories under
1315 OPENSSLDIR (the directory given with `--openssldir` or its default)
1316 for you convenience:
1317
1318     certs          Initially empty, this is the default location
1319                    for certificate files.
1320     private        Initially empty, this is the default location
1321                    for private key files.
1322     misc           Various scripts.
1323
1324 The installation directory should be appropriately protected to ensure
1325 unprivileged users cannot make changes to OpenSSL binaries or files, or
1326 install engines.  If you already have a pre-installed version of OpenSSL as
1327 part of your Operating System it is recommended that you do not overwrite
1328 the system version and instead install to somewhere else.
1329
1330 Package builders who want to configure the library for standard locations,
1331 but have the package installed somewhere else so that it can easily be
1332 packaged, can use
1333
1334     $ make DESTDIR=/tmp/package-root install         # Unix
1335     $ mms/macro="DESTDIR=TMP:[PACKAGE-ROOT]" install ! OpenVMS
1336
1337 The specified destination directory will be prepended to all installation
1338 target paths.
1339
1340 Compatibility issues with previous OpenSSL versions
1341 ---------------------------------------------------
1342
1343 ### COMPILING existing applications
1344
1345 Starting with version 1.1.0, OpenSSL hides a number of structures that were
1346 previously open.  This includes all internal libssl structures and a number
1347 of EVP types.  Accessor functions have been added to allow controlled access
1348 to the structures' data.
1349
1350 This means that some software needs to be rewritten to adapt to the new ways
1351 of doing things.  This often amounts to allocating an instance of a structure
1352 explicitly where you could previously allocate them on the stack as automatic
1353 variables, and using the provided accessor functions where you would previously
1354 access a structure's field directly.
1355
1356 Some APIs have changed as well.  However, older APIs have been preserved when
1357 possible.
1358
1359 Post-installation Notes
1360 -----------------------
1361
1362 With the default OpenSSL installation comes a FIPS provider module, which
1363 needs some post-installation attention, without which it will not be usable.
1364 This involves using the following command:
1365
1366     $ openssl fipsinstall
1367
1368 See the openssl-fipsinstall(1) manual for details and examples.
1369
1370 Advanced Build Options
1371 ======================
1372
1373 Environment Variables
1374 ---------------------
1375
1376 A number of environment variables can be used to provide additional control
1377 over the build process.  Typically these should be defined prior to running
1378 `Configure`.  Not all environment variables are relevant to all platforms.
1379
1380     AR
1381                    The name of the ar executable to use.
1382
1383     BUILDFILE
1384                    Use a different build file name than the platform default
1385                    ("Makefile" on Unix-like platforms, "makefile" on native Windows,
1386                    "descrip.mms" on OpenVMS).  This requires that there is a
1387                    corresponding build file template.
1388                    See [Configurations/README.md](Configurations/README.md)
1389                    for further information.
1390
1391     CC
1392                    The compiler to use. Configure will attempt to pick a default
1393                    compiler for your platform but this choice can be overridden
1394                    using this variable. Set it to the compiler executable you wish
1395                    to use, e.g. gcc or clang.
1396
1397     CROSS_COMPILE
1398                    This environment variable has the same meaning as for the
1399                    "--cross-compile-prefix" Configure flag described above. If both
1400                    are set then the Configure flag takes precedence.
1401
1402     NM
1403                    The name of the nm executable to use.
1404
1405     OPENSSL_LOCAL_CONFIG_DIR
1406                    OpenSSL comes with a database of information about how it
1407                    should be built on different platforms as well as build file
1408                    templates for those platforms. The database is comprised of
1409                    ".conf" files in the Configurations directory.  The build
1410                    file templates reside there as well as ".tmpl" files. See the
1411                    file [Configurations/README.md](Configurations/README.md)
1412                    for further information about the format of ".conf" files
1413                    as well as information on the ".tmpl" files.
1414                    In addition to the standard ".conf" and ".tmpl" files, it is
1415                    possible to create your own ".conf" and ".tmpl" files and
1416                    store them locally, outside the OpenSSL source tree.
1417                    This environment variable can be set to the directory where
1418                    these files are held and will be considered by Configure
1419                    before it looks in the standard directories.
1420
1421     PERL
1422                    The name of the Perl executable to use when building OpenSSL.
1423                    Only needed if builing should use a different Perl executable
1424                    than what is used to run the Configure script.
1425
1426     HASHBANGPERL
1427                    The command string for the Perl executable to insert in the
1428                    #! line of perl scripts that will be publicly installed.
1429                    Default: /usr/bin/env perl
1430                    Note: the value of this variable is added to the same scripts
1431                    on all platforms, but it's only relevant on Unix-like platforms.
1432
1433     RC
1434                    The name of the rc executable to use. The default will be as
1435                    defined for the target platform in the ".conf" file. If not
1436                    defined then "windres" will be used. The WINDRES environment
1437                    variable is synonymous to this. If both are defined then RC
1438                    takes precedence.
1439
1440     RANLIB
1441                    The name of the ranlib executable to use.
1442
1443     WINDRES
1444                    See RC.
1445
1446 Makefile Targets
1447 ----------------
1448
1449 The `Configure` script generates a Makefile in a format relevant to the specific
1450 platform.  The Makefiles provide a number of targets that can be used.  Not all
1451 targets may be available on all platforms.  Only the most common targets are
1452 described here.  Examine the Makefiles themselves for the full list.
1453
1454     all
1455                    The target to build all the software components and
1456                    documentation.
1457
1458     build_sw
1459                    Build all the software components.
1460                    THIS IS THE DEFAULT TARGET.
1461
1462     build_docs
1463                    Build all documentation components.
1464
1465     clean
1466                    Remove all build artefacts and return the directory to a "clean"
1467                    state.
1468
1469     depend
1470                    Rebuild the dependencies in the Makefiles. This is a legacy
1471                    option that no longer needs to be used since OpenSSL 1.1.0.
1472
1473     install
1474                    Install all OpenSSL components.
1475
1476     install_sw
1477                    Only install the OpenSSL software components.
1478
1479     install_docs
1480                    Only install the OpenSSL documentation components.
1481
1482     install_man_docs
1483                    Only install the OpenSSL man pages (Unix only).
1484
1485     install_html_docs
1486                    Only install the OpenSSL HTML documentation.
1487
1488     install_fips
1489                    Install the FIPS provider module configuration file.
1490
1491     list-tests
1492                    Prints a list of all the self test names.
1493
1494     test
1495                    Build and run the OpenSSL self tests.
1496
1497     uninstall
1498                    Uninstall all OpenSSL components.
1499
1500     reconfigure
1501     reconf
1502                    Re-run the configuration process, as exactly as the last time
1503                    as possible.
1504
1505     update
1506                    This is a developer option. If you are developing a patch for
1507                    OpenSSL you may need to use this if you want to update
1508                    automatically generated files; add new error codes or add new
1509                    (or change the visibility of) public API functions. (Unix only).
1510
1511 Running Selected Tests
1512 ----------------------
1513
1514 You can specify a set of tests to be performed
1515 using the `make` variable `TESTS`.
1516
1517 See the section [Running Selected Tests of
1518 test/README.md](test/README.md#running-selected-tests).
1519
1520 Troubleshooting
1521 ===============
1522
1523 Configuration Problems
1524 ----------------------
1525
1526 ### Selecting the correct target
1527
1528 The `./Configure` script tries hard to guess your operating system, but in some
1529 cases it does not succeed. You will see a message like the following:
1530
1531     $ ./Configure
1532     Operating system: x86-whatever-minix
1533     This system (minix) is not supported. See file INSTALL.md for details.
1534
1535 Even if the automatic target selection by the `./Configure` script fails,
1536 chances are that you still might find a suitable target in the `Configurations`
1537 directory, which you can supply to the `./Configure` command,
1538 possibly after some adjustment.
1539
1540 The `Configurations/` directory contains a lot of examples of such targets.
1541 The main configuration file is [10-main.conf], which contains all targets that
1542 are officially supported by the OpenSSL team. Other configuration files contain
1543 targets contributed by other OpenSSL users. The list of targets can be found in
1544 a Perl list `my %targets = ( ... )`.
1545
1546     my %targets = (
1547     ...
1548     "target-name" => {
1549         inherit_from     => [ "base-target" ],
1550         CC               => "...",
1551         cflags           => add("..."),
1552         asm_arch         => '...',
1553         perlasm_scheme   => "...",
1554     },
1555     ...
1556     )
1557
1558 If you call `./Configure` without arguments, it will give you a list of all
1559 known targets. Using `grep`, you can lookup the target definition in the
1560 `Configurations/` directory. For example the `android-x86_64` can be found in
1561 [Configurations/15-android.conf](Configurations/15-android.conf).
1562
1563 The directory contains two README files, which explain the general syntax and
1564 design of the configuration files.
1565
1566  - [Configurations/README.md](Configurations/README.md)
1567  - [Configurations/README-design.md](Configurations/README-design.md)
1568
1569 If you need further help, try to search the [openssl-users] mailing list
1570 or the [GitHub Issues] for existing solutions. If you don't find anything,
1571 you can [raise an issue] to ask a question yourself.
1572
1573 More about our support resources can be found in the [SUPPORT] file.
1574
1575 ### Configuration Errors
1576
1577 If the `./Configure` or `./Configure` command fails with an error message,
1578 read the error message carefully and try to figure out whether you made
1579 a mistake (e.g., by providing a wrong option), or whether the script is
1580 working incorrectly. If you think you encountered a bug, please
1581 [raise an issue] on GitHub to file a bug report.
1582
1583 Along with a short description of the bug, please provide the complete
1584 configure command line and the relevant output including the error message.
1585
1586 Note: To make the output readable, pleace add a 'code fence' (three backquotes
1587 ` ``` ` on a separate line) before and after your output:
1588
1589      ```
1590      ./Configure [your arguments...]
1591
1592      [output...]
1593
1594      ```
1595
1596 Build Failures
1597 --------------
1598
1599 If the build fails, look carefully at the output. Try to locate and understand
1600 the error message. It might be that the compiler is already telling you
1601 exactly what you need to do to fix your problem.
1602
1603 There may be reasons for the failure that aren't problems in OpenSSL itself,
1604 for example if the compiler reports missing standard or third party headers.
1605
1606 If the build succeeded previously, but fails after a source or configuration
1607 change, it might be helpful to clean the build tree before attempting another
1608 build.  Use this command:
1609
1610     $ make clean                                     # Unix
1611     $ mms clean                                      ! (or mmk) OpenVMS
1612     $ nmake clean                                    # Windows
1613
1614 Assembler error messages can sometimes be sidestepped by using the `no-asm`
1615 configuration option. See also [notes](#notes-on-assembler-modules-compilation).
1616
1617 Compiling parts of OpenSSL with gcc and others with the system compiler will
1618 result in unresolved symbols on some systems.
1619
1620 If you are still having problems, try to search the [openssl-users] mailing
1621 list or the [GitHub Issues] for existing solutions. If you think you
1622 encountered an OpenSSL bug, please [raise an issue] to file a bug report.
1623 Please take the time to review the existing issues first; maybe the bug was
1624 already reported or has already been fixed.
1625
1626 Test Failures
1627 -------------
1628
1629 If some tests fail, look at the output.  There may be reasons for the failure
1630 that isn't a problem in OpenSSL itself (like an OS malfunction or a Perl issue).
1631
1632 You may want increased verbosity, that can be accomplished as described in
1633 section [Test Failures of test/README.md](test/README.md#test-failures).
1634
1635 You may also want to selectively specify which test(s) to perform. This can be
1636 done using the `make` variable `TESTS` as described in section [Running
1637 Selected Tests of test/README.md](test/README.md#running-selected-tests).
1638
1639 If you find a problem with OpenSSL itself, try removing any
1640 compiler optimization flags from the `CFLAGS` line in the Makefile and
1641 run `make clean; make` or corresponding.
1642
1643 To report a bug please open an issue on GitHub, at
1644 <https://github.com/openssl/openssl/issues>.
1645
1646 Notes
1647 =====
1648
1649 Notes on multi-threading
1650 ------------------------
1651
1652 For some systems, the OpenSSL `Configure` script knows what compiler options
1653 are needed to generate a library that is suitable for multi-threaded
1654 applications.  On these systems, support for multi-threading is enabled
1655 by default; use the `no-threads` option to disable (this should never be
1656 necessary).
1657
1658 On other systems, to enable support for multi-threading, you will have
1659 to specify at least two options: `threads`, and a system-dependent option.
1660 (The latter is `-D_REENTRANT` on various systems.)  The default in this
1661 case, obviously, is not to include support for multi-threading (but
1662 you can still use `no-threads` to suppress an annoying warning message
1663 from the `Configure` script.)
1664
1665 OpenSSL provides built-in support for two threading models: pthreads (found on
1666 most UNIX/Linux systems), and Windows threads.  No other threading models are
1667 supported.  If your platform does not provide pthreads or Windows threads then
1668 you should use `Configure` with the `no-threads` option.
1669
1670 For pthreads, all locks are non-recursive. In addition, in a debug build,
1671 the mutex attribute `PTHREAD_MUTEX_ERRORCHECK` is used. If this is not
1672 available on your platform, you might have to add
1673 `-DOPENSSL_NO_MUTEX_ERRORCHECK` to your `Configure` invocation.
1674 (On Linux `PTHREAD_MUTEX_ERRORCHECK` is an enum value, so a built-in
1675 ifdef test cannot be used.)
1676
1677 Notes on shared libraries
1678 -------------------------
1679
1680 For most systems the OpenSSL `Configure` script knows what is needed to
1681 build shared libraries for libcrypto and libssl.  On these systems
1682 the shared libraries will be created by default.  This can be suppressed and
1683 only static libraries created by using the `no-shared` option.  On systems
1684 where OpenSSL does not know how to build shared libraries the `no-shared`
1685 option will be forced and only static libraries will be created.
1686
1687 Shared libraries are named a little differently on different platforms.
1688 One way or another, they all have the major OpenSSL version number as
1689 part of the file name, i.e.  for OpenSSL 1.1.x, `1.1` is somehow part of
1690 the name.
1691
1692 On most POSIX platforms, shared libraries are named `libcrypto.so.1.1`
1693 and `libssl.so.1.1`.
1694
1695 on Cygwin, shared libraries are named `cygcrypto-1.1.dll` and `cygssl-1.1.dll`
1696 with import libraries `libcrypto.dll.a` and `libssl.dll.a`.
1697
1698 On Windows build with MSVC or using MingW, shared libraries are named
1699 `libcrypto-1_1.dll` and `libssl-1_1.dll` for 32-bit Windows,
1700 `libcrypto-1_1-x64.dll` and `libssl-1_1-x64.dll` for 64-bit x86_64 Windows,
1701 and `libcrypto-1_1-ia64.dll` and `libssl-1_1-ia64.dll` for IA64 Windows.
1702 With MSVC, the import libraries are named `libcrypto.lib` and `libssl.lib`,
1703 while with MingW, they are named `libcrypto.dll.a` and `libssl.dll.a`.
1704
1705 On VMS, shareable images (VMS speak for shared libraries) are named
1706 `ossl$libcrypto0101_shr.exe` and `ossl$libssl0101_shr.exe`.  However, when
1707 OpenSSL is specifically built for 32-bit pointers, the shareable images
1708 are named `ossl$libcrypto0101_shr32.exe` and `ossl$libssl0101_shr32.exe`
1709 instead, and when built for 64-bit pointers, they are named
1710 `ossl$libcrypto0101_shr64.exe` and `ossl$libssl0101_shr64.exe`.
1711
1712 Notes on random number generation
1713 ---------------------------------
1714
1715 Availability of cryptographically secure random numbers is required for
1716 secret key generation.  OpenSSL provides several options to seed the
1717 internal CSPRNG.  If not properly seeded, the internal CSPRNG will refuse
1718 to deliver random bytes and a "PRNG not seeded error" will occur.
1719
1720 The seeding method can be configured using the `--with-rand-seed` option,
1721 which can be used to specify a comma separated list of seed methods.
1722 However, in most cases OpenSSL will choose a suitable default method,
1723 so it is not necessary to explicitly provide this option.  Note also
1724 that not all methods are available on all platforms.  The FIPS provider will
1725 silently ignore seed sources that were not validated.
1726
1727 I) On operating systems which provide a suitable randomness source (in
1728 form  of a system call or system device), OpenSSL will use the optimal
1729 available  method to seed the CSPRNG from the operating system's
1730 randomness sources.  This corresponds to the option `--with-rand-seed=os`.
1731
1732 II) On systems without such a suitable randomness source, automatic seeding
1733 and reseeding is disabled (`--with-rand-seed=none`) and it may be necessary
1734 to install additional support software to obtain a random seed and reseed
1735 the CSPRNG manually.  Please check out the manual pages for `RAND_add()`,
1736 `RAND_bytes()`, `RAND_egd()`, and the FAQ for more information.
1737
1738 Notes on assembler modules compilation
1739 --------------------------------------
1740
1741 Compilation of some code paths in assembler modules might depend on whether the
1742 current assembler version supports certain ISA extensions or not. Code paths
1743 that use the AES-NI, PCLMULQDQ, SSSE3, and SHA extensions are always assembled.
1744 Apart from that, the minimum requirements for the assembler versions are shown
1745 in the table below:
1746
1747 | ISA extension | GNU as | nasm   | llvm    |
1748 |---------------|--------|--------|---------|
1749 | AVX           | 2.19   | 2.09   | 3.0     |
1750 | AVX2          | 2.22   | 2.10   | 3.1     |
1751 | ADCX/ADOX     | 2.23   | 2.10   | 3.3     |
1752 | AVX512        | 2.25   | 2.11.8 | 3.6 (*) |
1753 | AVX512IFMA    | 2.26   | 2.11.8 | 6.0 (*) |
1754 | VAES          | 2.30   | 2.13.3 | 6.0 (*) |
1755
1756 ---
1757
1758 (*) Even though AVX512 support was implemented in llvm 3.6, prior to version 7.0
1759 an explicit -march flag was apparently required to compile assembly modules. But
1760 then the compiler generates processor-specific code, which in turn contradicts
1761 the idea of performing dispatch at run-time, which is facilitated by the special
1762 variable `OPENSSL_ia32cap`. For versions older than 7.0, it is possible to work
1763 around the problem by forcing the build procedure to use the following script:
1764
1765     #!/bin/sh
1766     exec clang -no-integrated-as "$@"
1767
1768 instead of the real clang. In which case it doesn't matter what clang version
1769 is used, as it is the version of the GNU assembler that will be checked.
1770
1771 ---
1772
1773 <!-- Links  -->
1774
1775 [openssl-users]:
1776     <https://mta.openssl.org/mailman/listinfo/openssl-users>
1777
1778 [SUPPORT]:
1779     ./SUPPORT.md
1780
1781 [GitHub Issues]:
1782     <https://github.com/openssl/openssl/issues>
1783
1784 [raise an issue]:
1785     <https://github.com/openssl/openssl/issues/new/choose>
1786
1787 [10-main.conf]:
1788     Configurations/10-main.conf