INSTALL revision 111147
155714Skris 255714Skris INSTALLATION ON THE UNIX PLATFORM 355714Skris --------------------------------- 455714Skris 5109998Smarkm [Installation on DOS (with djgpp), Windows, OpenVMS and MacOS (before MacOS X) 6109998Smarkm is described in INSTALL.DJGPP, INSTALL.W32, INSTALL.VMS and INSTALL.MacOS. 7109998Smarkm This document describes installation on operating systems in the Unix 8109998Smarkm family.] 955714Skris 1055714Skris To install OpenSSL, you will need: 1155714Skris 1279998Skris * make 1355714Skris * Perl 5 1455714Skris * an ANSI C compiler 1579998Skris * a development environment in form of development libraries and C 1679998Skris header files 1755714Skris * a supported Unix operating system 1855714Skris 1955714Skris Quick Start 2055714Skris ----------- 2155714Skris 2255714Skris If you want to just get on with it, do: 2355714Skris 2455714Skris $ ./config 2555714Skris $ make 2655714Skris $ make test 2755714Skris $ make install 2855714Skris 2955714Skris [If any of these steps fails, see section Installation in Detail below.] 3055714Skris 3155714Skris This will build and install OpenSSL in the default location, which is (for 3255714Skris historical reasons) /usr/local/ssl. If you want to install it anywhere else, 3355714Skris run config like this: 3455714Skris 3555714Skris $ ./config --prefix=/usr/local --openssldir=/usr/local/openssl 3655714Skris 3755714Skris 3855714Skris Configuration Options 3955714Skris --------------------- 4055714Skris 4159191Skris There are several options to ./config (or ./Configure) to customize 4259191Skris the build: 4355714Skris 4455714Skris --prefix=DIR Install in DIR/bin, DIR/lib, DIR/include/openssl. 4555714Skris Configuration files used by OpenSSL will be in DIR/ssl 4655714Skris or the directory specified by --openssldir. 4755714Skris 4855714Skris --openssldir=DIR Directory for OpenSSL files. If no prefix is specified, 4955714Skris the library files and binaries are also installed there. 5055714Skris 5155714Skris no-threads Don't try to build with support for multi-threaded 5255714Skris applications. 5355714Skris 5455714Skris threads Build with support for multi-threaded applications. 5555714Skris This will usually require additional system-dependent options! 5655714Skris See "Note on multi-threading" below. 5755714Skris 58109998Smarkm no-zlib Don't try to build with support for zlib compression and 59109998Smarkm decompression. 60109998Smarkm 61109998Smarkm zlib Build with support for zlib compression/decompression. 62109998Smarkm 63109998Smarkm zlib-dynamic Like "zlib", but has OpenSSL load the zlib library dynamically 64109998Smarkm when needed. This is only supported on systems where loading 65109998Smarkm of shared libraries is supported. This is the default choice. 66109998Smarkm 6768651Skris no-shared Don't try to create shared libraries. 6868651Skris 6968651Skris shared In addition to the usual static libraries, create shared 7068651Skris libraries on platforms where it's supported. See "Note on 7168651Skris shared libraries" below. 7268651Skris 7355714Skris no-asm Do not use assembler code. 7455714Skris 7555714Skris 386 Use the 80386 instruction set only (the default x86 code is 7655714Skris more efficient, but requires at least a 486). 7755714Skris 7855714Skris no-<cipher> Build without the specified cipher (bf, cast, des, dh, dsa, 7955714Skris hmac, md2, md5, mdc2, rc2, rc4, rc5, rsa, sha). 8055714Skris The crypto/<cipher> directory can be removed after running 8155714Skris "make depend". 8255714Skris 8355714Skris -Dxxx, -lxxx, -Lxxx, -fxxx, -Kxxx These system specific options will 8455714Skris be passed through to the compiler to allow you to 8555714Skris define preprocessor symbols, specify additional libraries, 8655714Skris library directories or other compiler options. 8755714Skris 8855714Skris 8955714Skris Installation in Detail 9055714Skris ---------------------- 9155714Skris 9255714Skris 1a. Configure OpenSSL for your operation system automatically: 9355714Skris 9455714Skris $ ./config [options] 9555714Skris 9655714Skris This guesses at your operating system (and compiler, if necessary) and 9755714Skris configures OpenSSL based on this guess. Run ./config -t to see 9859191Skris if it guessed correctly. If you want to use a different compiler, you 9959191Skris are cross-compiling for another platform, or the ./config guess was 10059191Skris wrong for other reasons, go to step 1b. Otherwise go to step 2. 10155714Skris 10255714Skris On some systems, you can include debugging information as follows: 10355714Skris 10455714Skris $ ./config -d [options] 10555714Skris 10655714Skris 1b. Configure OpenSSL for your operating system manually 10755714Skris 10855714Skris OpenSSL knows about a range of different operating system, hardware and 10955714Skris compiler combinations. To see the ones it knows about, run 11055714Skris 11155714Skris $ ./Configure 11255714Skris 11355714Skris Pick a suitable name from the list that matches your system. For most 11455714Skris operating systems there is a choice between using "cc" or "gcc". When 11555714Skris you have identified your system (and if necessary compiler) use this name 11655714Skris as the argument to ./Configure. For example, a "linux-elf" user would 11755714Skris run: 11855714Skris 11955714Skris $ ./Configure linux-elf [options] 12055714Skris 12155714Skris If your system is not available, you will have to edit the Configure 12255714Skris program and add the correct configuration for your system. The 12359191Skris generic configurations "cc" or "gcc" should usually work on 32 bit 12459191Skris systems. 12555714Skris 12655714Skris Configure creates the file Makefile.ssl from Makefile.org and 12755714Skris defines various macros in crypto/opensslconf.h (generated from 12855714Skris crypto/opensslconf.h.in). 12955714Skris 13055714Skris 2. Build OpenSSL by running: 13155714Skris 13255714Skris $ make 13355714Skris 13455714Skris This will build the OpenSSL libraries (libcrypto.a and libssl.a) and the 13555714Skris OpenSSL binary ("openssl"). The libraries will be built in the top-level 13655714Skris directory, and the binary will be in the "apps" directory. 13755714Skris 13868651Skris If "make" fails, look at the output. There may be reasons for 13979998Skris the failure that aren't problems in OpenSSL itself (like missing 14068651Skris standard headers). If it is a problem with OpenSSL itself, please 14168651Skris report the problem to <openssl-bugs@openssl.org> (note that your 142100936Snectar message will be recorded in the request tracker publicly readable 143109998Smarkm via http://www.openssl.org/support/rt2.html and will be forwarded to a 144109998Smarkm public mailing list). Include the output of "make report" in your message. 145100936Snectar Please check out the request tracker. Maybe the bug was already 146100936Snectar reported or has already been fixed. 14755714Skris 14855714Skris [If you encounter assembler error messages, try the "no-asm" 14959191Skris configuration option as an immediate fix.] 15055714Skris 15155714Skris Compiling parts of OpenSSL with gcc and others with the system 15255714Skris compiler will result in unresolved symbols on some systems. 15355714Skris 15455714Skris 3. After a successful build, the libraries should be tested. Run: 15555714Skris 15655714Skris $ make test 15755714Skris 15868651Skris If a test fails, look at the output. There may be reasons for 15968651Skris the failure that isn't a problem in OpenSSL itself (like a missing 16068651Skris or malfunctioning bc). If it is a problem with OpenSSL itself, 161111147Snectar try removing any compiler optimization flags from the CFLAG line 16268651Skris in Makefile.ssl and run "make clean; make". Please send a bug 16368651Skris report to <openssl-bugs@openssl.org>, including the output of 164100936Snectar "make report" in order to be added to the request tracker at 165109998Smarkm http://www.openssl.org/support/rt2.html. 16655714Skris 16755714Skris 4. If everything tests ok, install OpenSSL with 16855714Skris 16955714Skris $ make install 17055714Skris 17155714Skris This will create the installation directory (if it does not exist) and 17255714Skris then the following subdirectories: 17355714Skris 17455714Skris certs Initially empty, this is the default location 17555714Skris for certificate files. 17659191Skris man/man1 Manual pages for the 'openssl' command line tool 17759191Skris man/man3 Manual pages for the libraries (very incomplete) 17855714Skris misc Various scripts. 17955714Skris private Initially empty, this is the default location 18055714Skris for private key files. 18155714Skris 18259191Skris If you didn't choose a different installation prefix, the 18355714Skris following additional subdirectories will be created: 18455714Skris 18555714Skris bin Contains the openssl binary and a few other 18655714Skris utility programs. 18755714Skris include/openssl Contains the header files needed if you want to 18855714Skris compile programs with libcrypto or libssl. 18955714Skris lib Contains the OpenSSL library files themselves. 19055714Skris 19155714Skris Package builders who want to configure the library for standard 19255714Skris locations, but have the package installed somewhere else so that 19355714Skris it can easily be packaged, can use 19455714Skris 19555714Skris $ make INSTALL_PREFIX=/tmp/package-root install 19655714Skris 19755714Skris (or specify "--install_prefix=/tmp/package-root" as a configure 19855714Skris option). The specified prefix will be prepended to all 19955714Skris installation target filenames. 20055714Skris 20155714Skris 20255714Skris NOTE: The header files used to reside directly in the include 20355714Skris directory, but have now been moved to include/openssl so that 20455714Skris OpenSSL can co-exist with other libraries which use some of the 20555714Skris same filenames. This means that applications that use OpenSSL 20655714Skris should now use C preprocessor directives of the form 20755714Skris 20855714Skris #include <openssl/ssl.h> 20955714Skris 21055714Skris instead of "#include <ssl.h>", which was used with library versions 21155714Skris up to OpenSSL 0.9.2b. 21255714Skris 21355714Skris If you install a new version of OpenSSL over an old library version, 21455714Skris you should delete the old header files in the include directory. 21555714Skris 21655714Skris Compatibility issues: 21755714Skris 21855714Skris * COMPILING existing applications 21955714Skris 22055714Skris To compile an application that uses old filenames -- e.g. 22155714Skris "#include <ssl.h>" --, it will usually be enough to find 22255714Skris the CFLAGS definition in the application's Makefile and 22355714Skris add a C option such as 22455714Skris 22555714Skris -I/usr/local/ssl/include/openssl 22655714Skris 22755714Skris to it. 22855714Skris 22955714Skris But don't delete the existing -I option that points to 23055714Skris the ..../include directory! Otherwise, OpenSSL header files 23155714Skris could not #include each other. 23255714Skris 23355714Skris * WRITING applications 23455714Skris 23555714Skris To write an application that is able to handle both the new 23655714Skris and the old directory layout, so that it can still be compiled 23755714Skris with library versions up to OpenSSL 0.9.2b without bothering 23855714Skris the user, you can proceed as follows: 23955714Skris 24055714Skris - Always use the new filename of OpenSSL header files, 24155714Skris e.g. #include <openssl/ssl.h>. 24255714Skris 24355714Skris - Create a directory "incl" that contains only a symbolic 24455714Skris link named "openssl", which points to the "include" directory 24555714Skris of OpenSSL. 24655714Skris For example, your application's Makefile might contain the 24755714Skris following rule, if OPENSSLDIR is a pathname (absolute or 24855714Skris relative) of the directory where OpenSSL resides: 24955714Skris 25055714Skris incl/openssl: 25155714Skris -mkdir incl 25255714Skris cd $(OPENSSLDIR) # Check whether the directory really exists 25355714Skris -ln -s `cd $(OPENSSLDIR); pwd`/include incl/openssl 25455714Skris 25555714Skris You will have to add "incl/openssl" to the dependencies 25655714Skris of those C files that include some OpenSSL header file. 25755714Skris 25855714Skris - Add "-Iincl" to your CFLAGS. 25955714Skris 26055714Skris With these additions, the OpenSSL header files will be available 26155714Skris under both name variants if an old library version is used: 26255714Skris Your application can reach them under names like <openssl/foo.h>, 26355714Skris while the header files still are able to #include each other 26455714Skris with names of the form <foo.h>. 26555714Skris 26655714Skris 26755714Skris Note on multi-threading 26855714Skris ----------------------- 26955714Skris 27055714Skris For some systems, the OpenSSL Configure script knows what compiler options 27155714Skris are needed to generate a library that is suitable for multi-threaded 27255714Skris applications. On these systems, support for multi-threading is enabled 27355714Skris by default; use the "no-threads" option to disable (this should never be 27455714Skris necessary). 27555714Skris 27655714Skris On other systems, to enable support for multi-threading, you will have 27755714Skris to specify at least two options: "threads", and a system-dependent option. 27855714Skris (The latter is "-D_REENTRANT" on various systems.) The default in this 27955714Skris case, obviously, is not to include support for multi-threading (but 28055714Skris you can still use "no-threads" to suppress an annoying warning message 28155714Skris from the Configure script.) 28255714Skris 28368651Skris 28468651Skris Note on shared libraries 28568651Skris ------------------------ 28668651Skris 287100928Snectar Shared library is currently an experimental feature. The only reason to 288100928Snectar have them would be to conserve memory on systems where several program 289100928Snectar are using OpenSSL. Binary backward compatibility can't be guaranteed 290100928Snectar before OpenSSL version 1.0. 291100928Snectar 29268651Skris For some systems, the OpenSSL Configure script knows what is needed to 29368651Skris build shared libraries for libcrypto and libssl. On these systems, 29468651Skris the shared libraries are currently not created by default, but giving 29568651Skris the option "shared" will get them created. This method supports Makefile 29668651Skris targets for shared library creation, like linux-shared. Those targets 29768651Skris can currently be used on their own just as well, but this is expected 29868651Skris to change in future versions of OpenSSL. 299109998Smarkm 300109998Smarkm Note on random number generation 301109998Smarkm -------------------------------- 302109998Smarkm 303109998Smarkm Availability of cryptographically secure random numbers is required for 304109998Smarkm secret key generation. OpenSSL provides several options to seed the 305109998Smarkm internal PRNG. If not properly seeded, the internal PRNG will refuse 306109998Smarkm to deliver random bytes and a "PRNG not seeded error" will occur. 307109998Smarkm On systems without /dev/urandom (or similar) device, it may be necessary 308109998Smarkm to install additional support software to obtain random seed. 309109998Smarkm Please check out the manual pages for RAND_add(), RAND_bytes(), RAND_egd(), 310109998Smarkm and the FAQ for more information. 311111147Snectar 312111147Snectar Note on support for multiple builds 313111147Snectar ----------------------------------- 314111147Snectar 315111147Snectar OpenSSL is usually built in it's source tree. Unfortunately, this doesn't 316111147Snectar support building for multiple platforms from the same source tree very well. 317111147Snectar It is however possible to build in a separate tree through the use of lots 318111147Snectar of symbolic links, which should be prepared like this: 319111147Snectar 320111147Snectar mkdir -p objtree/"`uname -s`-`uname -r`-`uname -m`" 321111147Snectar cd objtree/"`uname -s`-`uname -r`-`uname -m`" 322111147Snectar (cd $OPENSSL_SOURCE; find . -type f) | while read F; do 323111147Snectar mkdir -p `dirname $F` 324111147Snectar rm -f $F; ln -s $OPENSSL_SOURCE/$F $F 325111147Snectar echo $F '->' $OPENSSL_SOURCE/$F 326111147Snectar done 327111147Snectar make -f Makefile.org clean 328111147Snectar 329111147Snectar OPENSSL_SOURCE is an environment variable that contains the absolute (this 330111147Snectar is important!) path to the OpenSSL source tree. 331111147Snectar 332111147Snectar Also, operations like 'make update' should still be made in the source tree. 333