X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=blobdiff_plain;f=INSTALL;h=57e3be2aad8ba3eef72e31ced33911f59c9298b4;hp=29db22ea75003217f971c94acdd1d1714b3b0016;hb=a3cb4cfc6af3f5fc1cd81ccd264daaa79d1c0a46;hpb=f430ba31ac81f27f0014320fee335d2dc4562a95 diff --git a/INSTALL b/INSTALL index 29db22ea75..57e3be2aad 100644 --- a/INSTALL +++ b/INSTALL @@ -2,9 +2,8 @@ OPENSSL INSTALLATION -------------------- - [This document describes installation on all supported operating - systems (currently mainly the Linux/Unix family, OpenVMS and - Windows)] + This document describes installation on all supported operating + systems (the Linux/Unix family, OpenVMS and Windows) To install OpenSSL, you will need: @@ -16,13 +15,62 @@ header files * a supported operating system - For additional platform specific requirements and other details, - please read one of these: + For additional platform specific requirements, solutions to specific + issues and other details, please read one of these: + * NOTES.UNIX (any supported Unix like system) * NOTES.VMS (OpenVMS) * NOTES.WIN (any supported Windows) * NOTES.DJGPP (DOS platform with DJGPP) + Notational conventions in this document + --------------------------------------- + + Throughout this document, we use the following conventions in command + examples: + + $ command Any line starting with a dollar sign + ($) is a command line. + + { word1 | word2 | word3 } This denotes a mandatory choice, to be + replaced with one of the given words. + A simple example would be this: + + $ echo { FOO | BAR | COOKIE } + + which is to be understood as one of + these: + + $ echo FOO + - or - + $ echo BAR + - or - + $ echo COOKIE + + [ word1 | word2 | word3 ] Similar to { word1 | word2 | word3 } + except it's optional to give any of + those. In addition to the examples + above, this would also be valid: + + $ echo + + {{ target }} This denotes a mandatory word or + sequence of words of some sort. A + simple example would be this: + + $ type {{ filename }} + + which is to be understood to use the + command 'type' on some file name + determined by the user. + + [[ options ]] Similar to {{ target }}, but is + optional. + + Note that the notation assumes spaces around {, }, [, ], {{, }} and + [[, ]]. This is to differentiate from OpenVMS directory + specifications, which also use [ and ], but without spaces. + Quick Start ----------- @@ -49,7 +97,7 @@ $ nmake test $ nmake install - [If any of these steps fails, see section Installation in Detail below.] + If any of these steps fails, see section Installation in Detail below. This will build and install OpenSSL in the default location, which is: @@ -85,10 +133,25 @@ --cross-compile-prefix=PREFIX The PREFIX to include in front of commands for your - toolchain. For example to build the mingw64 target on Linux - you might use "--cross-compile-prefix=x86_64-w64-mingw32-". - If the compiler is gcc, then this will attempt to run - x86_64-w64-mingw32-gcc when compiling. + toolchain. It's likely to have to end with dash, e.g. + a-b-c- would invoke GNU compiler as a-b-c-gcc, etc. + Unfortunately cross-compiling is too case-specific to + put together one-size-fits-all instructions. You might + have to pass more flags or set up environment variables + to actually make it work. Android and iOS cases are + discussed in corresponding Configurations/10-main.cf + sections. But there are cases when this option alone is + sufficient. For example to build the mingw64 target on + Linux "--cross-compile-prefix=x86_64-w64-mingw32-" + works. Naturally provided that mingw packages are + installed. Today Debian and Ubuntu users have option to + install a number of prepackaged cross-compilers along + with corresponding run-time and development packages for + "alien" hardware. To give another example + "--cross-compile-prefix=mipsel-linux-gnu-" suffices + in such case. Needless to mention that you have to + invoke ./Configure, not ./config, and pass your target + name explicitly. --debug Build OpenSSL with debugging symbols. @@ -248,15 +311,22 @@ no-err Don't compile in any error strings. + enable-external-tests + Enable building of integration with external test suites. + This is a developer option and may not work on all platforms. + The only supported external test suite at the current time is + the BoringSSL test suite. See the file test/README.external + for further details. + no-filenames Don't compile in filename and line number information (e.g. for errors and memory allocation). - enable-fuzz - Build with support for fuzzing. This is a developer option - only. It may not work on all platforms and should never be - used in production environments. See the file fuzz/README.md - for further details. + enable-fuzz-libfuzzer, enable-fuzz-afl + Build with support for fuzzing using either libfuzzer or AFL. + These are developer options only. They may not work on all + platforms and should never be used in production environments. + See the file fuzz/README.md for further details. no-gost Don't build support for GOST based ciphersuites. Note that @@ -264,9 +334,6 @@ available if the GOST algorithms are also available through loading an externally supplied engine. - enable-heartbeats - Build support for DTLS heartbeats. - no-hw-padlock Don't build the padlock engine. @@ -317,19 +384,19 @@ Don't build SRTP support no-sse2 - Exclude SSE2 code paths. Normally SSE2 extension is - detected at run-time, but the decision whether or not the - machine code will be executed is taken solely on CPU - capability vector. This means that if you happen to run OS - kernel which does not support SSE2 extension on Intel P4 - processor, then your application might be exposed to - "illegal instruction" exception. There might be a way - to enable support in kernel, e.g. FreeBSD kernel can be - compiled with CPU_ENABLE_SSE, and there is a way to - disengage SSE2 code paths upon application start-up, - but if you aim for wider "audience" running such kernel, - consider no-sse2. Both the 386 and no-asm options imply - no-sse2. + Exclude SSE2 code paths from 32-bit x86 assembly modules. + Normally SSE2 extension is detected at run-time, but the + decision whether or not the machine code will be executed + is taken solely on CPU capability vector. This means that + if you happen to run OS kernel which does not support SSE2 + extension on Intel P4 processor, then your application + might be exposed to "illegal instruction" exception. + There might be a way to enable support in kernel, e.g. + FreeBSD kernel can be compiled with CPU_ENABLE_SSE, and + there is a way to disengage SSE2 code paths upon application + start-up, but if you aim for wider "audience" running + such kernel, consider no-sse2. Both the 386 and + no-asm options imply no-sse2. enable-ssl-trace Build with the SSL Trace capabilities (adds the "-trace" @@ -346,6 +413,9 @@ the OpenSSL tests also use the command line applications the tests will also be skipped. + no-tests + Don't build test programs or run any test. + no-threads Don't try to build with support for multi-threaded applications. @@ -357,6 +427,16 @@ require additional system-dependent options! See "Note on multi-threading" below. + enable-tls13downgrade + TODO(TLS1.3): Make this enabled by default and remove the + option when TLSv1.3 is out of draft + TLSv1.3 offers a downgrade protection mechanism. This is + implemented but disabled by default. It should not typically + be enabled except for testing purposes. Otherwise this could + cause problems if a pre-RFC version of OpenSSL talks to an + RFC implementation (it will erroneously be detected as a + downgrade). + no-ts Don't build Time Stamping Authority support. @@ -389,11 +469,18 @@ where loading of shared libraries is supported. 386 - On Intel hardware, use the 80386 instruction set only - (the default x86 code is more efficient, but requires at - least a 486). Note: Use compiler flags for any other CPU - specific configuration, e.g. "-m32" to build x86 code on - an x64 system. + In 32-bit x86 builds, when generating assembly modules, + use the 80386 instruction set only (the default x86 code + is more efficient, but requires at least a 486). Note: + This doesn't affect code generated by compiler, you're + likely to complement configuration command line with + suitable compiler-specific option. + + enable-tls1_3 + TODO(TLS1.3): Make this enabled by default + Build support for TLS1.3. Note: This is a WIP feature and + does not currently interoperate with other TLS1.3 + implementations! Use with caution!! no- Don't build support for negotiating the specified SSL/TLS @@ -417,16 +504,26 @@ no- Build without support for the specified algorithm, where is one of: bf, blake2, camellia, cast, chacha, cmac, - des, dh, dsa, ecdh, ecdsa, idea, md4, md5, mdc2, ocb, - ploy1305, rc2, rc4, rmd160, scrypt, seed or whirlpool. The + des, dh, dsa, ecdh, ecdsa, idea, md4, mdc2, ocb, poly1305, + rc2, rc4, rmd160, scrypt, seed, siphash or whirlpool. The "ripemd" algorithm is deprecated and if used is synonymous with rmd160. - -Dxxx, -lxxx, -Lxxx, -fxxx, -mXXX, -Kxxx - These system specific options will be passed through to the - compiler to allow you to define preprocessor symbols, specify - additional libraries, library directories or other compiler - options. + -Dxxx, lxxx, -Lxxx, -Wl, -rpath, -R, -framework, -static + These system specific options will be recocognised and + passed through to the compiler to allow you to define + preprocessor symbols, specify additional libraries, library + directories or other compiler options. It might be worth + noting that some compilers generate code specifically for + processor the compiler currently executes on. This is not + necessarily what you might have in mind, since it might be + unsuitable for execution on other, typically older, + processor. Consult your compiler documentation. + + -xxx, +xxx + Additional options that are not otherwise recognised are + passed through as they are to the compiler as well. Again, + consult your compiler documentation. Installation in Detail @@ -436,11 +533,11 @@ NOTE: This is not available on Windows. - $ ./config [options] # Unix + $ ./config [[ options ]] # Unix or - $ @config [options] ! OpenVMS + $ @config [[ options ]] ! OpenVMS For the remainder of this text, the Unix form will be used in all examples, please use the appropriate form for your platform. @@ -453,7 +550,7 @@ On some systems, you can include debugging information as follows: - $ ./config -d [options] + $ ./config -d [[ options ]] 1b. Configure OpenSSL for your operating system manually @@ -475,10 +572,10 @@ as the argument to Configure. For example, a "linux-elf" user would run: - $ ./Configure linux-elf [options] + $ ./Configure linux-elf [[ options ]] If your system isn't listed, you will have to create a configuration - file named Configurations/{something}.conf and add the correct + file named Configurations/{{ something }}.conf and add the correct configuration for your system. See the available configs as examples and read Configurations/README and Configurations/README.design for more information. @@ -502,29 +599,29 @@ $ mkdir /var/tmp/openssl-build $ cd /var/tmp/openssl-build - $ /PATH/TO/OPENSSL/SOURCE/config [options] + $ /PATH/TO/OPENSSL/SOURCE/config [[ options ]] or - $ /PATH/TO/OPENSSL/SOURCE/Configure [target] [options] + $ /PATH/TO/OPENSSL/SOURCE/Configure {{ target }} [[ options ]] OpenVMS example: $ set default sys$login: $ create/dir [.tmp.openssl-build] $ set default [.tmp.openssl-build] - $ @[PATH.TO.OPENSSL.SOURCE]config {options} + $ @[PATH.TO.OPENSSL.SOURCE]config [[ options ]] or - $ @[PATH.TO.OPENSSL.SOURCE]Configure {target} {options} + $ @[PATH.TO.OPENSSL.SOURCE]Configure {{ target }} [[ options ]] Windows example: $ C: $ mkdir \temp-openssl $ cd \temp-openssl - $ perl d:\PATH\TO\OPENSSL\SOURCE\Configure {target} {options} + $ perl d:\PATH\TO\OPENSSL\SOURCE\Configure {{ target }} [[ options ]] Paths can be relative just as well as absolute. Configure will do its best to translate them to relative paths whenever possible. @@ -540,21 +637,18 @@ ("openssl"). The libraries will be built in the top-level directory, and the binary will be in the "apps" subdirectory. - If the build fails, look at the output. There may be reasons for - the failure that aren't problems in OpenSSL itself (like missing - standard headers). If you are having problems you can get help by - sending an email to the openssl-users email list (see - https://www.openssl.org/community/mailinglists.html for details). If it - is a bug with OpenSSL itself, please report the problem to - (note that your message will be recorded in the request - tracker publicly readable at - https://www.openssl.org/community/index.html#bugs and will be - forwarded to a public mailing list). Please check out the request - tracker. Maybe the bug was already reported or has already been + If the build fails, look at the output. There may be reasons + for the failure that aren't problems in OpenSSL itself (like + missing standard headers). If you are having problems you can + get help by sending an email to the openssl-users email list (see + https://www.openssl.org/community/mailinglists.html for details). If + it is a bug with OpenSSL itself, please open an issue on GitHub, at + https://github.com/openssl/openssl/issues. Please review the existing + ones first; maybe the bug was already reported or has already been fixed. - [If you encounter assembler error messages, try the "no-asm" - configuration option as an immediate fix.] + (If you encounter assembler error messages, try the "no-asm" + configuration option as an immediate fix.) Compiling parts of OpenSSL with gcc and others with the system compiler will result in unresolved symbols on some systems. @@ -605,6 +699,9 @@ Please send bug reports to . + For more details on how the make variables TESTS can be used, + see section TESTS in Detail below. + 4. If everything tests ok, install OpenSSL with $ make install # Unix @@ -625,26 +722,37 @@ or libssl. lib Contains the OpenSSL library files. lib/engines Contains the OpenSSL dynamically loadable engines. - share/man/{man1,man3,man5,man7} - Contains the OpenSSL man-pages. - share/doc/openssl/html/{man1,man3,man5,man7} + + share/man/man1 Contains the OpenSSL command line man-pages. + share/man/man3 Contains the OpenSSL library calls man-pages. + share/man/man5 Contains the OpenSSL configuration format man-pages. + share/man/man7 Contains the OpenSSL other misc man-pages. + + share/doc/openssl/html/man1 + share/doc/openssl/html/man3 + share/doc/openssl/html/man5 + share/doc/openssl/html/man7 Contains the HTML rendition of the man-pages. OpenVMS ('arch' is replaced with the architecture name, "Alpha" - or "ia64"): + or "ia64", 'sover' is replaced with the shared library version + (0101 for 1.1), and 'pz' is replaced with the pointer size + OpenSSL was built with): - [.EXE.'arch'] Contains the openssl binary and a few other - utility scripts. + [.EXE.'arch'] Contains the openssl binary. + [.EXE] Contains a few utility scripts. [.include.openssl] Contains the header files needed if you want to build your own programs that use libcrypto or libssl. [.LIB.'arch'] Contains the OpenSSL library files. - [.ENGINES.'arch'] + [.ENGINES'sover''pz'.'arch'] Contains the OpenSSL dynamically loadable engines. [.SYS$STARTUP] Contains startup, login and shutdown scripts. These define appropriate logical names and command symbols. + [.SYSTEST] Contains the installation verification procedure. + [.HTML] Contains the HTML rendition of the manual pages. Additionally, install will add the following directories under @@ -697,6 +805,13 @@ AR The name of the ar executable to use. + BUILDFILE + Use a different build file name than the platform default + ("Makefile" on Unixly platforms, "makefile" on native Windows, + "descrip.mms" on OpenVMS). This requires that there is a + corresponding build file template. See Configurations/README + for further information. + CC The compiler to use. Configure will attempt to pick a default compiler for your platform but this choice can be overridden @@ -713,16 +828,32 @@ OPENSSL_LOCAL_CONFIG_DIR OpenSSL comes with a database of information about how it - should be built on different platforms. This information is - held in ".conf" files in the Configurations directory. See the + should be built on different platforms as well as build file + templates for those platforms. The database is comprised of + ".conf" files in the Configurations directory. The build + file templates reside there as well as ".tmpl" files. See the file Configurations/README for further information about the - format of ".conf" files. As well as the standard ".conf" files - it is possible to create your own ".conf" files and store them - locally, outside the OpenSSL source tree. This environment - variable can be set to the directory where these files are held. + format of ".conf" files as well as information on the ".tmpl" + files. + In addition to the standard ".conf" and ".tmpl" files, it is + possible to create your own ".conf" and ".tmpl" files and store + them locally, outside the OpenSSL source tree. This environment + variable can be set to the directory where these files are held + and will be considered by Configure before it looks in the + standard directories. PERL - The name of the Perl executable to use. + The name of the Perl executable to use when building OpenSSL. + This variable is used in config script only. Configure on the + other hand imposes the interpreter by which it itself was + executed on the whole build procedure. + + HASHBANGPERL + The command string for the Perl executable to insert in the + #! line of perl scripts that will be publically installed. + Default: /usr/bin/env perl + Note: the value of this variable is added to the same scripts + on all platforms, but it's only relevant on Unix-like platforms. RC The name of the rc executable to use. The default will be as @@ -786,6 +917,57 @@ automatically generated files; add new error codes or add new (or change the visibility of) public API functions. (Unix only). + TESTS in Detail + --------------- + + The make variable TESTS supports a versatile set of space separated tokens + with which you can specify a set of tests to be performed. With a "current + set of tests" in mind, initially being empty, here are the possible tokens: + + alltests The current set of tests becomes the whole set of available + tests (as listed when you do 'make list-tests' or similar). + xxx Adds the test 'xxx' to the current set of tests. + -xxx Removes 'xxx' from the current set of tests. If this is the + first token in the list, the current set of tests is first + assigned the whole set of available tests, effectively making + this token equivalent to TESTS="alltests -xxx". + nn Adds the test group 'nn' (which is a number) to the current + set of tests. + -nn Removes the test group 'nn' from the current set of tests. + If this is the first token in the list, the current set of + tests is first assigned the whole set of available tests, + effectively making this token equivalent to + TESTS="alltests -xxx". + + Also, all tokens except for "alltests" may have wildcards, such as *. + (on Unix and Windows, BSD style wildcards are supported, while on VMS, + it's VMS style wildcards) + + Example: All tests except for the fuzz tests: + + $ make TESTS=-test_fuzz test + + or (if you want to be explicit) + + $ make TESTS='alltests -test_fuzz' test + + Example: All tests that have a name starting with "test_ssl" but not those + starting with "test_ssl_": + + $ make TESTS='test_ssl* -test_ssl_*' test + + Example: Only test group 10: + + $ make TESTS='10' + + Example: All tests except the slow group (group 99): + + $ make TESTS='-99' + + Example: All tests in test groups 80 to 99 except for tests in group 90: + + $ make TESTS='[89]? -90' + Note on multi-threading ----------------------- @@ -807,8 +989,8 @@ supported. If your platform does not provide pthreads or Windows threads then you should Configure with the "no-threads" option. - Note on shared libraries - ------------------------ + Notes on shared libraries + ------------------------- For most systems the OpenSSL Configure script knows what is needed to build shared libraries for libcrypto and libssl. On these systems @@ -817,6 +999,31 @@ where OpenSSL does not know how to build shared libraries the "no-shared" option will be forced and only static libraries will be created. + Shared libraries are named a little differently on different platforms. + One way or another, they all have the major OpenSSL version number as + part of the file name, i.e. for OpenSSL 1.1.x, 1.1 is somehow part of + the name. + + On most POSIXly platforms, shared libraries are named libcrypto.so.1.1 + and libssl.so.1.1. + + on Cygwin, shared libraries are named cygcrypto-1.1.dll and cygssl-1.1.dll + with import libraries libcrypto.dll.a and libssl.dll.a. + + On Windows build with MSVC or using MingW, shared libraries are named + libcrypto-1_1.dll and libssl-1_1.dll for 32-bit Windows, libcrypto-1_1-x64.dll + and libssl-1_1-x64.dll for 64-bit x86_64 Windows, and libcrypto-1_1-ia64.dll + and libssl-1_1-ia64.dll for IA64 Windows. With MSVC, the import libraries + are named libcrypto.lib and libssl.lib, while with MingW, they are named + libcrypto.dll.a and libssl.dll.a. + + On VMS, shareable images (VMS speak for shared libraries) are named + ossl$libcrypto0101_shr.exe and ossl$libssl0101_shr.exe. However, when + OpenSSL is specifically built for 32-bit pointers, the shareable images + are named ossl$libcrypto0101_shr32.exe and ossl$libssl0101_shr32.exe + instead, and when built for 64-bit pointers, they are named + ossl$libcrypto0101_shr64.exe and ossl$libssl0101_shr64.exe. + Note on random number generation --------------------------------