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