INSTALL revision 100936
117721Speter 217721Speter INSTALLATION ON THE UNIX PLATFORM 317721Speter --------------------------------- 417721Speter 517721Speter [Installation on Windows, OpenVMS and MacOS (before MacOS X) is described 617721Speter in INSTALL.W32, INSTALL.VMS and INSTALL.MacOS.] 717721Speter 817721Speter To install OpenSSL, you will need: 917721Speter 1017721Speter * make 1117721Speter * Perl 5 1217721Speter * an ANSI C compiler 1317721Speter * a development environment in form of development libraries and C 1417721Speter header files 1517721Speter * a supported Unix operating system 1617721Speter 1717721Speter Quick Start 1817721Speter ----------- 1917721Speter 2017721Speter If you want to just get on with it, do: 2117721Speter 2217721Speter $ ./config 2317721Speter $ make 2417721Speter $ make test 2517721Speter $ make install 2617721Speter 2717721Speter [If any of these steps fails, see section Installation in Detail below.] 2817721Speter 2917721Speter This will build and install OpenSSL in the default location, which is (for 3017721Speter historical reasons) /usr/local/ssl. If you want to install it anywhere else, 3117721Speter run config like this: 3217721Speter 3317721Speter $ ./config --prefix=/usr/local --openssldir=/usr/local/openssl 3417721Speter 3517721Speter 3617721Speter Configuration Options 3717721Speter --------------------- 3817721Speter 3917721Speter There are several options to ./config (or ./Configure) to customize 4017721Speter the build: 4117721Speter 4217721Speter --prefix=DIR Install in DIR/bin, DIR/lib, DIR/include/openssl. 4317721Speter Configuration files used by OpenSSL will be in DIR/ssl 4417721Speter or the directory specified by --openssldir. 4517721Speter 4617721Speter --openssldir=DIR Directory for OpenSSL files. If no prefix is specified, 4717721Speter the library files and binaries are also installed there. 4817721Speter 4917721Speter no-threads Don't try to build with support for multi-threaded 5017721Speter applications. 5117721Speter 5217721Speter threads Build with support for multi-threaded applications. 5317721Speter This will usually require additional system-dependent options! 5417721Speter See "Note on multi-threading" below. 5517721Speter 5617721Speter no-shared Don't try to create shared libraries. 5717721Speter 5817721Speter shared In addition to the usual static libraries, create shared 5917721Speter libraries on platforms where it's supported. See "Note on 6017721Speter shared libraries" below. 6117721Speter 6217721Speter no-asm Do not use assembler code. 6317721Speter 6417721Speter 386 Use the 80386 instruction set only (the default x86 code is 6517721Speter more efficient, but requires at least a 486). 6617721Speter 6717721Speter no-<cipher> Build without the specified cipher (bf, cast, des, dh, dsa, 6817721Speter hmac, md2, md5, mdc2, rc2, rc4, rc5, rsa, sha). 6917721Speter The crypto/<cipher> directory can be removed after running 7017721Speter "make depend". 7117721Speter 7217721Speter -Dxxx, -lxxx, -Lxxx, -fxxx, -Kxxx These system specific options will 7317721Speter be passed through to the compiler to allow you to 7417721Speter define preprocessor symbols, specify additional libraries, 7517721Speter library directories or other compiler options. 7617721Speter 7717721Speter 7817721Speter Installation in Detail 7917721Speter ---------------------- 8017721Speter 8117721Speter 1a. Configure OpenSSL for your operation system automatically: 8217721Speter 8317721Speter $ ./config [options] 8417721Speter 8517721Speter This guesses at your operating system (and compiler, if necessary) and 8617721Speter configures OpenSSL based on this guess. Run ./config -t to see 8717721Speter if it guessed correctly. If you want to use a different compiler, you 8817721Speter are cross-compiling for another platform, or the ./config guess was 8917721Speter wrong for other reasons, go to step 1b. Otherwise go to step 2. 9017721Speter 9117721Speter On some systems, you can include debugging information as follows: 9217721Speter 9317721Speter $ ./config -d [options] 9417721Speter 9517721Speter 1b. Configure OpenSSL for your operating system manually 9617721Speter 9717721Speter OpenSSL knows about a range of different operating system, hardware and 9817721Speter compiler combinations. To see the ones it knows about, run 9917721Speter 10017721Speter $ ./Configure 10117721Speter 10217721Speter Pick a suitable name from the list that matches your system. For most 10317721Speter operating systems there is a choice between using "cc" or "gcc". When 10417721Speter you have identified your system (and if necessary compiler) use this name 10517721Speter as the argument to ./Configure. For example, a "linux-elf" user would 10617721Speter run: 10717721Speter 10817721Speter $ ./Configure linux-elf [options] 10917721Speter 11017721Speter If your system is not available, you will have to edit the Configure 11117721Speter program and add the correct configuration for your system. The 11217721Speter generic configurations "cc" or "gcc" should usually work on 32 bit 11317721Speter systems. 11417721Speter 11517721Speter Configure creates the file Makefile.ssl from Makefile.org and 11617721Speter defines various macros in crypto/opensslconf.h (generated from 11717721Speter crypto/opensslconf.h.in). 11817721Speter 11917721Speter 2. Build OpenSSL by running: 12017721Speter 12117721Speter $ make 12217721Speter 12317721Speter This will build the OpenSSL libraries (libcrypto.a and libssl.a) and the 12417721Speter OpenSSL binary ("openssl"). The libraries will be built in the top-level 12517721Speter directory, and the binary will be in the "apps" directory. 12617721Speter 12717721Speter If "make" fails, look at the output. There may be reasons for 12817721Speter the failure that aren't problems in OpenSSL itself (like missing 12917721Speter standard headers). If it is a problem with OpenSSL itself, please 13017721Speter report the problem to <openssl-bugs@openssl.org> (note that your 13117721Speter message will be recorded in the request tracker publicly readable 13217721Speter via http://www.openssl.org/rt2.html and will be forwarded to a public 13317721Speter mailing list). Include the output of "make report" in your message. 13417721Speter Please check out the request tracker. Maybe the bug was already 13517721Speter reported or has already been fixed. 13617721Speter 13717721Speter [If you encounter assembler error messages, try the "no-asm" 13817721Speter configuration option as an immediate fix.] 13917721Speter 14017721Speter Compiling parts of OpenSSL with gcc and others with the system 14117721Speter compiler will result in unresolved symbols on some systems. 14217721Speter 14317721Speter 3. After a successful build, the libraries should be tested. Run: 14417721Speter 14517721Speter $ make test 14617721Speter 14717721Speter If a test fails, look at the output. There may be reasons for 14817721Speter the failure that isn't a problem in OpenSSL itself (like a missing 14917721Speter or malfunctioning bc). If it is a problem with OpenSSL itself, 15017721Speter try removing any compiler optimization flags from the CFLAGS line 15117721Speter in Makefile.ssl and run "make clean; make". Please send a bug 15217721Speter report to <openssl-bugs@openssl.org>, including the output of 15317721Speter "make report" in order to be added to the request tracker at 15417721Speter http://www.openssl.org/rt2.html. 15517721Speter 15617721Speter 4. If everything tests ok, install OpenSSL with 15717721Speter 15817721Speter $ make install 15917721Speter 16017721Speter This will create the installation directory (if it does not exist) and 16117721Speter then the following subdirectories: 16217721Speter 16317721Speter certs Initially empty, this is the default location 16417721Speter for certificate files. 16517721Speter man/man1 Manual pages for the 'openssl' command line tool 16617721Speter man/man3 Manual pages for the libraries (very incomplete) 16717721Speter misc Various scripts. 16817721Speter private Initially empty, this is the default location 16917721Speter for private key files. 17017721Speter 17117721Speter If you didn't choose a different installation prefix, the 17217721Speter following additional subdirectories will be created: 17317721Speter 17417721Speter bin Contains the openssl binary and a few other 17517721Speter utility programs. 17617721Speter include/openssl Contains the header files needed if you want to 17717721Speter compile programs with libcrypto or libssl. 17817721Speter lib Contains the OpenSSL library files themselves. 17917721Speter 18017721Speter Package builders who want to configure the library for standard 18117721Speter locations, but have the package installed somewhere else so that 18217721Speter it can easily be packaged, can use 18317721Speter 18417721Speter $ make INSTALL_PREFIX=/tmp/package-root install 18517721Speter 18617721Speter (or specify "--install_prefix=/tmp/package-root" as a configure 18717721Speter option). The specified prefix will be prepended to all 18817721Speter installation target filenames. 18917721Speter 19017721Speter 19117721Speter NOTE: The header files used to reside directly in the include 19217721Speter directory, but have now been moved to include/openssl so that 19317721Speter OpenSSL can co-exist with other libraries which use some of the 19417721Speter same filenames. This means that applications that use OpenSSL 19517721Speter should now use C preprocessor directives of the form 19617721Speter 19717721Speter #include <openssl/ssl.h> 19817721Speter 19917721Speter instead of "#include <ssl.h>", which was used with library versions 20017721Speter up to OpenSSL 0.9.2b. 20117721Speter 20217721Speter If you install a new version of OpenSSL over an old library version, 20317721Speter you should delete the old header files in the include directory. 20417721Speter 20517721Speter Compatibility issues: 20617721Speter 20717721Speter * COMPILING existing applications 20817721Speter 20917721Speter To compile an application that uses old filenames -- e.g. 21017721Speter "#include <ssl.h>" --, it will usually be enough to find 21117721Speter the CFLAGS definition in the application's Makefile and 21217721Speter add a C option such as 21317721Speter 21417721Speter -I/usr/local/ssl/include/openssl 21517721Speter 21617721Speter to it. 21717721Speter 21817721Speter But don't delete the existing -I option that points to 21917721Speter the ..../include directory! Otherwise, OpenSSL header files 22017721Speter could not #include each other. 22117721Speter 22217721Speter * WRITING applications 22317721Speter 22417721Speter To write an application that is able to handle both the new 22517721Speter and the old directory layout, so that it can still be compiled 22617721Speter with library versions up to OpenSSL 0.9.2b without bothering 22717721Speter the user, you can proceed as follows: 22817721Speter 22917721Speter - Always use the new filename of OpenSSL header files, 23017721Speter e.g. #include <openssl/ssl.h>. 23117721Speter 23217721Speter - Create a directory "incl" that contains only a symbolic 23317721Speter link named "openssl", which points to the "include" directory 23417721Speter of OpenSSL. 23517721Speter For example, your application's Makefile might contain the 23617721Speter following rule, if OPENSSLDIR is a pathname (absolute or 23717721Speter relative) of the directory where OpenSSL resides: 23817721Speter 23917721Speter incl/openssl: 24017721Speter -mkdir incl 24117721Speter cd $(OPENSSLDIR) # Check whether the directory really exists 24217721Speter -ln -s `cd $(OPENSSLDIR); pwd`/include incl/openssl 24317721Speter 24417721Speter You will have to add "incl/openssl" to the dependencies 24517721Speter of those C files that include some OpenSSL header file. 24617721Speter 24717721Speter - Add "-Iincl" to your CFLAGS. 24817721Speter 24917721Speter With these additions, the OpenSSL header files will be available 25017721Speter under both name variants if an old library version is used: 25117721Speter Your application can reach them under names like <openssl/foo.h>, 25217721Speter while the header files still are able to #include each other 25317721Speter with names of the form <foo.h>. 25417721Speter 25517721Speter 25617721Speter Note on multi-threading 25717721Speter ----------------------- 25817721Speter 25917721Speter For some systems, the OpenSSL Configure script knows what compiler options 26017721Speter are needed to generate a library that is suitable for multi-threaded 26117721Speter applications. On these systems, support for multi-threading is enabled 26217721Speter by default; use the "no-threads" option to disable (this should never be 26317721Speter necessary). 26417721Speter 26517721Speter On other systems, to enable support for multi-threading, you will have 26617721Speter to specify at least two options: "threads", and a system-dependent option. 26717721Speter (The latter is "-D_REENTRANT" on various systems.) The default in this 26817721Speter case, obviously, is not to include support for multi-threading (but 26917721Speter you can still use "no-threads" to suppress an annoying warning message 27017721Speter from the Configure script.) 27117721Speter 27217721Speter 27317721Speter Note on shared libraries 27417721Speter ------------------------ 27517721Speter 27617721Speter Shared library is currently an experimental feature. The only reason to 27717721Speter have them would be to conserve memory on systems where several program 27817721Speter are using OpenSSL. Binary backward compatibility can't be guaranteed 27917721Speter before OpenSSL version 1.0. 28017721Speter 28117721Speter For some systems, the OpenSSL Configure script knows what is needed to 28217721Speter build shared libraries for libcrypto and libssl. On these systems, 28317721Speter the shared libraries are currently not created by default, but giving 28417721Speter the option "shared" will get them created. This method supports Makefile 28517721Speter targets for shared library creation, like linux-shared. Those targets 28617721Speter can currently be used on their own just as well, but this is expected 28717721Speter to change in future versions of OpenSSL. 28817721Speter