INSTALLATION ON THE UNIX PLATFORM
---------------------------------
- [Installation on DOS (with djgpp), Windows, OpenVMS, MacOS (before MacOS X)
- and NetWare is described in INSTALL.DJGPP, INSTALL.W32, INSTALL.VMS,
- INSTALL.MacOS and INSTALL.NW.
+ [Installation on DOS (with djgpp), Windows, MacOS (before MacOS X)
+ and NetWare is described in INSTALL.DJGPP, INSTALL.WIN, INSTALL.MacOS
+ and INSTALL.NW.
- This document describes installation on operating systems in the Unix
- family.]
+ This document describes installation on the main supported operating
+ systems, currently the Unix family and OpenVMS.]
To install OpenSSL, you will need:
* make
- * Perl 5 with core modules (see 'Note on Perl' further down)
+ * Perl 5 with core modules (please read README.PERL)
+ * The perl module Text::Template (please read README.PERL)
* an ANSI C compiler
* a development environment in form of development libraries and C
header files
- * a supported Unix operating system
+ * a supported operating system
+
+ For more details regarding specific platforms, there are these notes
+ available:
+
+ * NOTES.VMS
Quick Start
-----------
If you want to just get on with it, do:
- $ ./config
- $ make
- $ make test
- $ make install
+ on Unix:
+
+ $ ./config
+ $ make
+ $ make test
+ $ make install
+
+ on OpenVMS:
+
+ $ @config
+ $ mms
+ $ mms test
+ $ mms install
[If any of these steps fails, see section Installation in Detail below.]
- This will build and install OpenSSL in the default location, which is (for
- historical reasons) /usr/local/ssl. If you want to install it anywhere else,
- run config like this:
+ This will build and install OpenSSL in the default location, which is:
+
+ Unix: normal installation directories under /usr/local
+ OpenVMS: SYS$COMMON:[OPENSSL-'version'...], where 'version' is the
+ OpenSSL version number ('major'_'minor').
+
+ If you want to install it anywhere else, run config like this:
- $ ./config --prefix=/usr/local --openssldir=/usr/local/openssl
+ On Unix:
+
+ $ ./config --prefix=/opt/openssl --openssldir=/usr/local/ssl
+
+ On OpenVMS:
+
+ $ @config --prefix=PROGRAM:[INSTALLS] --openssldir=SYS$MANAGER:[OPENSSL]
Configuration Options
There are several options to ./config (or ./Configure) to customize
the build:
- --prefix=DIR Install in DIR/bin, DIR/lib, DIR/include/openssl.
- Configuration files used by OpenSSL will be in DIR/ssl
- or the directory specified by --openssldir.
+ --prefix=DIR The top of the installation directory tree. Defaults are:
+
+ Unix: /usr/local
+ OpenVMS: SYS$COMMON:[OPENSSL-'version']
+
+ --openssldir=DIR Directory for OpenSSL configuration files, and also the
+ default certificate and key store. Defaults are:
+
+ Unix: PREFIX/ssl (PREFIX is given by --prefix)
+ OpenVMS: SYS$COMMON:[SSL]
- --openssldir=DIR Directory for OpenSSL files. If no prefix is specified,
- the library files and binaries are also installed there.
+ no-autoalginit Don't automatically load all supported ciphers and digests.
+ Typically OpenSSL will make available all of its supported
+ ciphers and digests. For a statically linked application this
+ may be undesirable if small executable size is an objective.
+ This only affects libcrypto. Ciphers and digests will have to be
+ loaded manually using EVP_add_cipher() and EVP_add_digest() if
+ this option is used.
+
+ no-autoerrinit Don't automatically load all libcrypto/libssl error strings.
+ Typically OpenSSL will automatically load human readable error
+ strings. For a statically linked application this may be
+ undesirable if small executable size is an objective.
no-threads Don't try to build with support for multi-threaded
applications.
no-asm Do not use assembler code.
- 386 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.
+ 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.
no-sse2 Exclude SSE2 code pathes. Normally SSE2 extension is
detected at run-time, but the decision whether or not the
1a. Configure OpenSSL for your operation system automatically:
- $ ./config [options]
+ $ ./config [options] # Unix
+
+ or
+
+ $ @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.
This guesses at your operating system (and compiler, if necessary) and
configures OpenSSL based on this guess. Run ./config -t to see
OpenSSL knows about a range of different operating system, hardware and
compiler combinations. To see the ones it knows about, run
- $ ./Configure
+ $ ./Configure # Unix
+
+ or
+
+ $ perl Configure # All other platforms
+
+ For the remainder of this text, the Unix form will be used in all
+ examples, please use the appropriate form for your platform.
Pick a suitable name from the list that matches your system. For most
operating systems there is a choice between using "cc" or "gcc". When
you have identified your system (and if necessary compiler) use this name
- as the argument to ./Configure. For example, a "linux-elf" user would
+ as the argument to Configure. For example, a "linux-elf" user would
run:
$ ./Configure linux-elf [options]
- If your system is not available, you will have to edit the Configure
- program and add the correct configuration for your system. The
- generic configurations "cc" or "gcc" should usually work on 32 bit
- systems.
+ If your system isn't listed, you will have to create a configuration
+ 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.
- Configure creates the file Makefile.ssl from Makefile.org and
+ 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).
- 2. Build OpenSSL by running:
-
- $ make
+ 1c. Configure OpenSSL for building outside of the source tree.
- This will build the OpenSSL libraries (libcrypto.a and libssl.a) and the
- OpenSSL binary ("openssl"). The libraries will be built in the top-level
- directory, and the binary will be in the "apps" directory.
+ OpenSSL can be configured to build in a build directory separate from
+ the directory with the source code. It's done by placing yourself in
+ some other directory and invoking the configuration commands from
+ there.
- If "make" 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 <openssl-bugs@openssl.org> (note that your
- message will be recorded in the request tracker publicly readable
- via http://www.openssl.org/support/rt.html and will be forwarded to a
- public mailing list). Include the output of "make report" in your message.
- Please check out the request tracker. Maybe the bug was already
- reported or has already been fixed.
+ Unix example:
- [If you encounter assembler error messages, try the "no-asm"
- configuration option as an immediate fix.]
+ $ mkdir /var/tmp/openssl-build
+ $ cd /var/tmp/openssl-build
+ $ /PATH/TO/OPENSSL/SOURCE/config [options]
- Compiling parts of OpenSSL with gcc and others with the system
- compiler will result in unresolved symbols on some systems.
+ or
- 3. After a successful build, the libraries should be tested. Run:
+ $ /PATH/TO/OPENSSL/SOURCE/Configure [target] [options]
- $ make test
+ OpenVMS example:
- If a test fails, look at the output. There may be reasons for
- the failure that isn't a problem in OpenSSL itself (like a missing
- or malfunctioning bc). If it is a problem with OpenSSL itself,
- try removing any compiler optimization flags from the CFLAG line
- in Makefile.ssl and run "make clean; make". Please send a bug
- report to <openssl-bugs@openssl.org>, including the output of
- "make report" in order to be added to the request tracker at
- http://www.openssl.org/support/rt.html.
+ $ set default sys$login:
+ $ create/dir [.tmp.openssl-build]
+ $ set default [.tmp.openssl-build]
+ $ @[PATH.TO.OPENSSL.SOURCE]config {options}
- 4. If everything tests ok, install OpenSSL with
+ or
- $ make install
+ $ @[PATH.TO.OPENSSL.SOURCE]Configure {target} {options}
- This will create the installation directory (if it does not exist) and
- then the following subdirectories:
+ Paths can be relative just as well as absolute. Configure will
+ do its best to translate them to relative paths whenever possible.
- certs Initially empty, this is the default location
- for certificate files.
- man/man1 Manual pages for the 'openssl' command line tool
- man/man3 Manual pages for the libraries (very incomplete)
- misc Various scripts.
- private Initially empty, this is the default location
- for private key files.
+ 2. Build OpenSSL by running:
- If you didn't choose a different installation prefix, the
- following additional subdirectories will be created:
+ $ make # Unix
+ $ mms ! (or mmk) OpenVMS
- bin Contains the openssl binary and a few other
- utility programs.
- include/openssl Contains the header files needed if you want to
- compile programs with libcrypto or libssl.
- lib Contains the OpenSSL library files themselves.
+ This will build the OpenSSL libraries (libcrypto.a and libssl.a on
+ Unix, corresponding on other platforms) and the OpenSSL binary
+ ("openssl"). The libraries will be built in the top-level directory,
+ and the binary will be in the "apps" subdirectory.
- Use "make install_sw" to install the software without documentation,
- and "install_docs_html" to install HTML renditions of the manual
- pages.
+ 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
+ https://www.openssl.org/community/index.html#bugs and will be
+ forwarded to a public mailing list). Include the output of "make
+ report" in your message. Please check out the request tracker. Maybe
+ the bug was already reported or has already been fixed.
- 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
+ [If you encounter assembler error messages, try the "no-asm"
+ configuration option as an immediate fix.]
- $ make INSTALL_PREFIX=/tmp/package-root install
+ Compiling parts of OpenSSL with gcc and others with the system
+ compiler will result in unresolved symbols on some systems.
- (or specify "--install_prefix=/tmp/package-root" as a configure
- option). The specified prefix will be prepended to all
- installation target filenames.
+ 3. After a successful build, the libraries should be tested. Run:
+ $ make test # Unix
+ $ mms test ! OpenVMS
- NOTE: The header files used to reside directly in the include
- directory, but have now been moved to include/openssl so that
- OpenSSL can co-exist with other libraries which use some of the
- same filenames. This means that applications that use OpenSSL
- should now use C preprocessor directives of the form
+ 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
+ can be accomplished like this:
- #include <openssl/ssl.h>
+ $ HARNESS_VERBOSE=yes make test # Unix
- instead of "#include <ssl.h>", which was used with library versions
- up to OpenSSL 0.9.2b.
+ $ DEFINE HARNESS_VERBOSE YES
+ $ mms test ! OpenVMS
- If you install a new version of OpenSSL over an old library version,
- you should delete the old header files in the include directory.
+ If you want to run just one or a few specific tests, you can use
+ the make variable TESTS to specify them, like this:
- Compatibility issues:
+ $ make TESTS='test_rsa test_dsa' test # Unix
+ $ mms/macro="TESTS=test_rsa test_dsa" test ! OpenVMS
- * COMPILING existing applications
+ And of course, you can combine (Unix example shown):
+
+ $ HARNESS_VERBOSE=yes make TESTS='test_rsa test_dsa' test
- To compile an application that uses old filenames -- e.g.
- "#include <ssl.h>" --, it will usually be enough to find
- the CFLAGS definition in the application's Makefile and
- add a C option such as
+ You can find the list of available tests like this:
- -I/usr/local/ssl/include/openssl
+ $ make list-tests # Unix
+ $ mms list-tests ! OpenVMS
- to it.
+ Have a look at the manual for the perl module Test::Harness to
+ see what other HARNESS_* variables there are.
- But don't delete the existing -I option that points to
- the ..../include directory! Otherwise, OpenSSL header files
- could not #include each other.
+ If you find a problem with OpenSSL itself, try removing any
+ compiler optimization flags from the CFLAGS line in Makefile and
+ run "make clean; make" or corresponding.
- * WRITING applications
+ Please send a bug report to <openssl-bugs@openssl.org>, and when
+ you do, please run the following and include the output in your
+ report:
- To write an application that is able to handle both the new
- and the old directory layout, so that it can still be compiled
- with library versions up to OpenSSL 0.9.2b without bothering
- the user, you can proceed as follows:
+ $ make report
- - Always use the new filename of OpenSSL header files,
- e.g. #include <openssl/ssl.h>.
+ 4. If everything tests ok, install OpenSSL with
- - Create a directory "incl" that contains only a symbolic
- link named "openssl", which points to the "include" directory
- of OpenSSL.
- For example, your application's Makefile might contain the
- following rule, if OPENSSLDIR is a pathname (absolute or
- relative) of the directory where OpenSSL resides:
+ $ make install # Unix
+ $ mms install ! OpenVMS
+
+ This will install all the software components in this directory
+ tree under PREFIX (the directory given with --prefix or its
+ default):
+
+ Unix:
+
+ bin/ Contains the openssl binary and a few other
+ utility scripts.
+ include/openssl
+ Contains the header files needed if you want
+ to build your own programs that use libcrypto
+ 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}
+ Contains the HTML rendition of the man-pages.
+
+ OpenVMS ('arch' is replaced with the architecture name, "Alpha"
+ or "ia64"):
+
+ [.EXE.'arch'] Contains the openssl binary and a few other
+ 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']
+ Contains the OpenSSL dynamically loadable engines.
+ [.SYS$STARTUP] Contains startup, login and shutdown scripts.
+ These define appropriate logical names and
+ command symbols.
+
+
+ Additionally, install will add the following directories under
+ OPENSSLDIR (the directory given with --openssldir or its default)
+ for you convenience:
+
+ certs Initially empty, this is the default location
+ for certificate files.
+ private Initially empty, this is the default location
+ for private key files.
+ misc Various scripts.
- incl/openssl:
- -mkdir incl
- cd $(OPENSSLDIR) # Check whether the directory really exists
- -ln -s `cd $(OPENSSLDIR); pwd`/include incl/openssl
+ 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
- You will have to add "incl/openssl" to the dependencies
- of those C files that include some OpenSSL header file.
+ $ make DESTDIR=/tmp/package-root install # Unix
+ $ mms/macro="DESTDIR=TMP:[PACKAGE-ROOT]" install ! OpenVMS
- - Add "-Iincl" to your CFLAGS.
+ The specified destination directory will be prepended to all
+ installation target paths.
- With these additions, the OpenSSL header files will be available
- under both name variants if an old library version is used:
- Your application can reach them under names like <openssl/foo.h>,
- while the header files still are able to #include each other
- with names of the form <foo.h>.
+ Compatibility issues with previous OpenSSL versions:
+ * COMPILING existing applications
- Note on Perl
- ------------
+ OpenSSL 1.1 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.
- For our scripts, we rely quite a bit on Perl, and increasingly on
- some core Perl modules. These Perl modules are part of the Perl
- source, so if you build Perl on your own, you should be set.
+ This means that some software needs to be rewritten to adapt to
+ the new ways of doing things. This often amounts to allocating
+ an instance of a structure explicitly where you could previously
+ allocate them on the stack as automatic variables, and using the
+ provided accessor functions where you would previously access a
+ structure's field directly.
- However, if you install Perl as binary packages, the outcome might
- differ, and you may have to check that you do get the core modules
- installed properly. We do not claim to know them all, but experience
- has told us the following:
+ <TBA>
- - on Linux distributions based on Debian, the package 'perl' will
- install the core Perl modules as well, so you will be fine.
- - on Linux distributions based on RPMs, you will need to install
- 'perl-core' rather than just 'perl'.
+ Some APIs have changed as well. However, older APIs have been
+ preserved when possible.
- It is highly recommended that you have at least Perl version 5.12
- installed.
Note on multi-threading
-----------------------
you can still use "no-threads" to suppress an annoying warning message
from the Configure script.)
+ OpenSSL provides built-in support for two threading models: pthreads (found on
+ most UNIX/Linux systems), and Windows threads. No other threading models are
+ supported. If your platform does not provide pthreads or Windows threads then
+ you should Configure with the "no-threads" option.
Note on shared libraries
------------------------
Please check out the manual pages for RAND_add(), RAND_bytes(), RAND_egd(),
and the FAQ for more information.
- Note on support for multiple builds
- -----------------------------------
-
- OpenSSL is usually built in its source tree. Unfortunately, this doesn't
- support building for multiple platforms from the same source tree very well.
- It is however possible to build in a separate tree through the use of lots
- of symbolic links, which should be prepared like this:
-
- mkdir -p objtree/"`uname -s`-`uname -r`-`uname -m`"
- cd objtree/"`uname -s`-`uname -r`-`uname -m`"
- (cd $OPENSSL_SOURCE; find . -type f) | while read F; do
- mkdir -p `dirname $F`
- rm -f $F; ln -s $OPENSSL_SOURCE/$F $F
- echo $F '->' $OPENSSL_SOURCE/$F
- done
- make -f Makefile.org clean
-
- OPENSSL_SOURCE is an environment variable that contains the absolute (this
- is important!) path to the OpenSSL source tree.
-
- Also, operations like 'make update' should still be made in the source tree.
projects / openssl.git / blobdiff