X-Git-Url: https://git.openssl.org/gitweb/?a=blobdiff_plain;f=INSTALL;h=c818ed72b1710d455ada2107aa32d34f2053a7ae;hb=dcea51afe9e3aec83a0c53f435beec9bc0faa07b;hp=be0ce9d3b7cdf69bc5f3993aa065a36212d4f97e;hpb=469ce8ff48ef06b2e508d0c06a42ec86379b0032;p=openssl.git diff --git a/INSTALL b/INSTALL index be0ce9d3b7..c818ed72b1 100644 --- a/INSTALL +++ b/INSTALL @@ -23,6 +23,7 @@ * NOTES.WIN (any supported Windows) * NOTES.DJGPP (DOS platform with DJGPP) * NOTES.ANDROID (obviously Android [NDK]) + * NOTES.VALGRIND (testing with Valgrind) Notational conventions in this document --------------------------------------- @@ -98,6 +99,9 @@ $ nmake test $ nmake install + Note that in order to perform the install step above you need to have + appropriate permissions to write to the installation directory. + If any of these steps fails, see section Installation in Detail below. This will build and install OpenSSL in the default location, which is: @@ -107,6 +111,12 @@ OpenSSL version number with underscores instead of periods. Windows: C:\Program Files\OpenSSL or C:\Program Files (x86)\OpenSSL + The installation directory should be appropriately protected to ensure + unprivileged users cannot make changes to OpenSSL binaries or files, or install + engines. If you already have a pre-installed version of OpenSSL as part of + your Operating System it is recommended that you do not overwrite the system + version and instead install to somewhere else. + If you want to install it anywhere else, run config like this: On Unix: @@ -135,7 +145,10 @@ Don't build with support for deprecated APIs below the specified version number. For example "--api=1.1.0" will remove support for all APIS that were deprecated in OpenSSL - version 1.1.0 or below. + version 1.1.0 or below. This is a rather specialized option + for developers. If you just intend to remove all deprecated + APIs entirely (up to the current version), it is easier + to add the 'no-deprecated' option instead (see below). --cross-compile-prefix=PREFIX The PREFIX to include in front of commands for your @@ -229,7 +242,7 @@ source exists. getrandom: Use the L or equivalent system call. - devrandom: Use the the first device from the DEVRANDOM list + devrandom: Use the first device from the DEVRANDOM list which can be opened to read random bytes. The DEVRANDOM preprocessor constant expands to "/dev/urandom","/dev/random","/dev/srandom" on @@ -296,10 +309,26 @@ Typically OpenSSL will automatically load a system config file which configures default ssl options. + enable-buildtest-c++ + While testing, generate C++ buildtest files that + simply check that the public OpenSSL header files + are usable standalone with C++. + + Enabling this option demands extra care. For any + compiler flag given directly as configuration + option, you must ensure that it's valid for both + the C and the C++ compiler. If not, the C++ build + test will most likely break. As an alternative, + you can use the language specific variables, CFLAGS + and CXXFLAGS. + no-capieng Don't build the CAPI engine. This option will be forced if on a platform that does not support CAPI. + no-cmp + Don't build support for CMP features + no-cms Don't build support for CMS features @@ -335,14 +364,14 @@ Don't build support for datagram based BIOs. Selecting this option will also force the disabling of DTLS. + no-dso + Don't build support for loading Dynamic Shared Objects. + enable-devcryptoeng Build the /dev/crypto engine. It is automatically selected on BSD implementations, in which case it can be disabled with no-devcryptoeng. - no-dso - Don't build support for loading Dynamic Shared Objects. - no-dynamic-engine Don't build the dynamically loaded engines. This only has an effect in a "shared" build @@ -384,6 +413,9 @@ Don't compile in filename and line number information (e.g. for errors and memory allocation). + no-fips + Don't compile the FIPS module + 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 @@ -396,9 +428,17 @@ available if the GOST algorithms are also available through loading an externally supplied engine. + no-legacy + Don't build the legacy provider. Disabling this also disables + the legacy algorithms: MD2 (already disabled by default). + no-makedepend Don't generate dependencies. + no-module + Don't build any dynamically loadable engines. This also + implies 'no-dynamic-engine'. + no-multiblock Don't build support for writing multiple records in one go in libssl (Note: this is a different capability to the @@ -510,6 +550,10 @@ require additional system-dependent options! See "Note on multi-threading" below. + enable-trace + Build with support for the integrated tracing api. See manual pages + OSSL_trace_set_channel(3) and OSSL_trace_enabled(3) for details. + no-ts Don't build Time Stamping Authority support. @@ -529,6 +573,9 @@ Enable additional unit test APIs. This should not typically be used in production deployments. + no-uplink + Don't build support for UPLINK interface. + enable-weak-ssl-ciphers Build support for SSL/TLS ciphers that are considered "weak" (e.g. RC4 based ciphersuites). @@ -594,10 +641,19 @@ Take note of the VAR=value documentation below and how these flags interact with those variables. - -xxx, +xxx + -xxx, +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. + passed through as they are to the compiler as well. + Unix-style options beginning with a '-' or '+' and + Windows-style options beginning with a '/' are recognized. + Again, consult your compiler documentation. + + If the option contains arguments separated by spaces, + then the URL-style notation %20 can be used for the space + character in order to avoid having to quote the option. + For example, -opt%20arg gets expanded to -opt arg. + In fact, any ASCII character can be encoded as %xx using its + hexadecimal encoding. Take note of the VAR=value documentation below and how these flags interact with those variables. @@ -676,6 +732,11 @@ CC=gcc CROSS_COMPILE=x86_64-w64-mingw32- \ ./config -DCOOKIE + If CC is set, it is advisable to also set CXX to ensure + both C and C++ compilers are in the same "family". This + becomes relevant with 'enable-external-tests' and + 'enable-buildtest-c++'. + reconf reconfigure Reconfigure from earlier data. This fetches the previous @@ -862,11 +923,17 @@ malfunction with Perl). You may want increased verbosity, that can be accomplished like this: - $ make VERBOSE=1 test # Unix + Verbosity on failure only (make macro VERBOSE_FAILURE or VF): - $ mms /macro=(VERBOSE=1) test ! OpenVMS + $ make VF=1 test # Unix + $ mms /macro=(VF=1) test ! OpenVMS + $ nmake VF=1 test # Windows - $ nmake VERBOSE=1 test # Windows + Full verbosity (make macro VERBOSE or V): + + $ make V=1 test # Unix + $ mms /macro=(V=1) test ! OpenVMS + $ nmake V=1 test # Windows If you want to run just one or a few specific tests, you can use the make variable TESTS to specify them, like this: @@ -877,7 +944,7 @@ And of course, you can combine (Unix example shown): - $ make VERBOSE=1 TESTS='test_rsa test_dsa' test + $ make VF=1 TESTS='test_rsa test_dsa' test You can find the list of available tests like this: @@ -904,8 +971,11 @@ $ mms install ! OpenVMS $ nmake install # Windows - This will install all the software components in this directory - tree under PREFIX (the directory given with --prefix or its + Note that in order to perform the install step above you need to have + appropriate permissions to write to the installation directory. + + The above commands will install all the software components in this + directory tree under PREFIX (the directory given with --prefix or its default): Unix: @@ -961,6 +1031,12 @@ for private key files. misc Various scripts. + The installation directory should be appropriately protected to ensure + unprivileged users cannot make changes to OpenSSL binaries or files, or + install engines. If you already have a pre-installed version of OpenSSL as + part of your Operating System it is recommended that you do not overwrite + the system version and instead install to somewhere else. + Package builders who want to configure the library for standard locations, but have the package installed somewhere else so that it can easily be packaged, can use @@ -1169,6 +1245,11 @@ $ make TESTS='[89]? -90' +To stochastically verify that the algorithm that produces uniformly distributed +random numbers is operating correctly (with a false positive rate of 0.01%): + + $ ./util/shlib_wrap.sh test/bntest -stochastic + Note on multi-threading -----------------------