OPENSSL INSTALLATION
--------------------
- [This document describes installation on the main supported operating
- systems, currently the Linux/Unix family, OpenVMS and Windows.
- Installation on DOS (with djgpp), MacOS (before MacOS X)
- is described in INSTALL.DJGPP or INSTALL.MacOS, respectively.]
+ [This document describes installation on all supported operating
+ systems (currently mainly the Linux/Unix family, OpenVMS and
+ Windows)]
To install OpenSSL, you will need:
- * make
- * Perl 5 with core modules (please read README.PERL)
- * The perl module Text::Template (please read README.PERL)
+ * A make implementation
+ * Perl 5 with core modules (please read NOTES.PERL)
+ * The perl module Text::Template (please read NOTES.PERL)
* an ANSI C compiler
* a development environment in the form of development libraries and C
header files
please read one of these:
* NOTES.VMS (OpenVMS)
- * NOTES.WIN (any Windows except for Windows CE)
+ * NOTES.WIN (any supported Windows)
+ * NOTES.DJGPP (DOS platform with DJGPP)
Quick Start
-----------
--openssldir depend in what configuration is used and what Windows
implementation OpenSSL is built on. More notes on this in NOTES.WIN):
- --prefix=DIR
- The top of the installation directory tree. Defaults are:
+ --api=x.y.z
+ 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.
- Unix: /usr/local
- Windows: C:\Program Files\OpenSSL
- or C:\Program Files (x86)\OpenSSL
- OpenVMS: SYS$COMMON:[OPENSSL-'version']
+ --cross-compile-prefix=PREFIX
+ The PREFIX to include in front of commands for your
+ 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.
+
+ --libdir=DIR
+ The name of the directory under the top of the installation
+ directory tree (see the --prefix option) where libraries will
+ be installed. By default this is "lib". Note that on Windows
+ only ".lib" files will be stored in this location. dll files
+ will always be installed to the "bin" directory.
--openssldir=DIR
Directory for OpenSSL configuration files, and also the
or C:\Program Files (x86)\Common Files\SSL
OpenVMS: SYS$COMMON:[OPENSSL-COMMON]
- --api=x.y.z
- 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.
+ --prefix=DIR
+ The top of the installation directory tree. Defaults are:
+
+ Unix: /usr/local
+ Windows: C:\Program Files\OpenSSL
+ or C:\Program Files (x86)\OpenSSL
+ OpenVMS: SYS$COMMON:[OPENSSL-'version']
+
+ --release
+ Build OpenSSL without debugging symbols. This is the default.
+
+ --strict-warnings
+ This is a developer flag that switches on various compiler
+ options recommended for OpenSSL development. It only works
+ when using gcc or clang as the compiler. If you are
+ developing a patch for OpenSSL then it is recommended that
+ you use this option where possible.
+
+ --with-zlib-include=DIR
+ The directory for the location of the zlib include file. This
+ option is only necessary if enable-zlib (see below) is used
+ and the include file is not already on the system include
+ path.
+
+ --with-zlib-lib=LIB
+ On Unix: this is the directory containing the zlib library.
+ If not provided the system library path will be used.
+ On Windows: this is the filename of the zlib library (with or
+ without a path). This flag must be provided if the
+ zlib-dynamic option is not also used. If zlib-dynamic is used
+ then this flag is optional and a default value ("ZLIB1") is
+ used if not provided.
+ On VMS: this is the filename of the zlib library (with or
+ without a path). This flag is optional and if not provided
+ then "GNV$LIBZSHR", "GNV$LIBZSHR32" or "GNV$LIBZSHR64" is
+ used by default depending on the pointer size chosen.
no-afalgeng
Don't build the AFALG engine. This option will be forced if
on a platform that does not support AFALG.
+ enable-asan
+ Build with the Address sanitiser. This is a developer option
+ only. It may not work on all platforms and should never be
+ used in production environments. It will only work when used
+ with gcc or clang and should be used in conjunction with the
+ no-shared option.
+
no-asm
Do not use assembler code. On some platforms a small amount
of assembler code may still be used.
enable-crypto-mdebug-backtrace
As for crypto-mdebug, but additionally provide backtrace
information for allocated memory.
+ TO BE USED WITH CARE: this uses GNU C functionality, and
+ is therefore not usable for non-GNU config targets. If
+ your build complains about the use of '-rdynamic' or the
+ lack of header file execinfo.h, this option is not for you.
+ ALSO NOTE that even though execinfo.h is available on your
+ system (through Gnulib), the functions might just be stubs
+ that do nothing.
no-ct
Don't build support for Certificate Transparency.
Don't compile in filename and line number information (e.g.
for errors and memory allocation).
+ 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
if this feature is enabled then GOST ciphersuites are only
"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 pathes upon application start-up,
+ 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.
no-ts
Don't build Time Stamping Authority support.
+ enable-ubsan
+ Build with the Undefined Behaviour sanitiser. This is a
+ developer option only. It may not work on all platforms and
+ should never be used in production environments. It will only
+ work when used with gcc or clang and should be used in
+ conjunction with the "-DPEDANTIC" option (or the
+ --strict-warnings option).
+
no-ui
Don't build with the "UI" capability (i.e. the set of
features enabling text based prompts).
The generic configurations "cc" or "gcc" should usually work on 32 bit
Unix-like systems.
- Configure creates a build file ("Makefile" on Unix and "descrip.mms"
- on OpenVMS) from a suitable template in Configurations, and
- defines various macros in crypto/opensslconf.h (generated from
- crypto/opensslconf.h.in).
+ Configure creates a build file ("Makefile" on Unix, "makefile" on Windows
+ and "descrip.mms" on OpenVMS) from a suitable template in Configurations,
+ and defines various macros in include/openssl/opensslconf.h (generated from
+ include/openssl/opensslconf.h.in).
1c. Configure OpenSSL for building outside of the source tree.
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 it is a problem with OpenSSL itself, please
- report the problem to <rt@openssl.org> (note that your message
- will be recorded in the request tracker publicly readable at
+ 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
+ <rt@openssl.org> (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
$ mms test ! OpenVMS
$ nmake test # Windows
+ NOTE: you MUST run the tests from an unprivileged account (or
+ disable your privileges temporarily if your platform allows it).
+
If some tests fail, look at the output. There may be reasons for
the failure that isn't a problem in OpenSSL itself (like a
malfunction with Perl). You may want increased verbosity, that
$ make VERBOSE=1 test # Unix
- $ DEFINE VERBOSE 1
- $ mms test ! OpenVMS
+ $ mms /macro=(VERBOSE=1) test ! OpenVMS
$ nmake VERBOSE=1 test # Windows
compiler optimization flags from the CFLAGS line in Makefile and
run "make clean; make" or corresponding.
- Please send a bug reports to <rt@openssl.org>.
+ Please send bug reports to <rt@openssl.org>.
4. If everything tests ok, install OpenSSL with
$ make install # Unix
$ 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
* COMPILING existing applications
- OpenSSL 1.1 hides a number of structures that were previously
+ OpenSSL 1.1.0 hides a number of structures that were previously
open. This includes all internal libssl structures and a number
of EVP types. Accessor functions have been added to allow
controlled access to the structures' data.
provided accessor functions where you would previously access a
structure's field directly.
- <TBA>
-
Some APIs have changed as well. However, older APIs have been
preserved when possible.
+ Environment Variables
+ ---------------------
+
+ A number of environment variables can be used to provide additional control
+ over the build process. Typically these should be defined prior to running
+ config or Configure. Not all environment variables are relevant to all
+ platforms.
+
+ AR
+ The name of the ar executable to use.
+
+ CC
+ The compiler to use. Configure will attempt to pick a default
+ compiler for your platform but this choice can be overridden
+ using this variable. Set it to the compiler executable you wish
+ to use, e.g. "gcc" or "clang".
+
+ CROSS_COMPILE
+ This environment variable has the same meaning as for the
+ "--cross-compile-prefix" Configure flag described above. If both
+ are set then the Configure flag takes precedence.
+
+ NM
+ The name of the nm executable to use.
+
+ 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
+ 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.
+
+ PERL
+ The name of the Perl executable to use when building OpenSSL.
+
+ 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
+ defined for the target platform in the ".conf" file. If not
+ defined then "windres" will be used. The WINDRES environment
+ variable is synonymous to this. If both are defined then RC
+ takes precedence.
+
+ RANLIB
+ The name of the ranlib executable to use.
+
+ WINDRES
+ See RC.
+
+ Makefile targets
+ ----------------
+
+ The Configure script generates a Makefile in a format relevant to the specific
+ platform. The Makefiles provide a number of targets that can be used. Not all
+ targets may be available on all platforms. Only the most common targets are
+ described here. Examine the Makefiles themselves for the full list.
+
+ all
+ The default target to build all the software components.
+
+ clean
+ Remove all build artefacts and return the directory to a "clean"
+ state.
+
+ depend
+ Rebuild the dependencies in the Makefiles. This is a legacy
+ option that no longer needs to be used in OpenSSL 1.1.0.
+
+ install
+ Install all OpenSSL components.
+
+ install_sw
+ Only install the OpenSSL software components.
+
+ install_docs
+ Only install the OpenSSL documentation components.
+
+ install_man_docs
+ Only install the OpenSSL man pages (Unix only).
+
+ install_html_docs
+ Only install the OpenSSL html documentation.
+
+ list-tests
+ Prints a list of all the self test names.
+
+ test
+ Build and run the OpenSSL self tests.
+
+ uninstall
+ Uninstall all OpenSSL components.
+
+ update
+ This is a developer option. If you are developing a patch for
+ OpenSSL you may need to use this if you want to update
+ automatically generated files; add new error codes or add new
+ (or change the visibility of) public API functions. (Unix only).
Note on multi-threading
-----------------------
internal PRNG. If not properly seeded, the internal PRNG will refuse
to deliver random bytes and a "PRNG not seeded error" will occur.
On systems without /dev/urandom (or similar) device, it may be necessary
- to install additional support software to obtain random seed.
+ to install additional support software to obtain a random seed.
Please check out the manual pages for RAND_add(), RAND_bytes(), RAND_egd(),
and the FAQ for more information.
projects / openssl.git / blobdiff