INSTALL revision 59191
155714Skris 255714Skris INSTALLATION ON THE UNIX PLATFORM 355714Skris --------------------------------- 455714Skris 559191Skris [Installation on Windows, OpenVMS and MacOS (before MacOS X) is described 659191Skris in INSTALL.W32, INSTALL.VMS and INSTALL.MacOS.] 755714Skris 855714Skris To install OpenSSL, you will need: 955714Skris 1055714Skris * Perl 5 1155714Skris * an ANSI C compiler 1255714Skris * a supported Unix operating system 1355714Skris 1455714Skris Quick Start 1555714Skris ----------- 1655714Skris 1755714Skris If you want to just get on with it, do: 1855714Skris 1955714Skris $ ./config 2055714Skris $ make 2155714Skris $ make test 2255714Skris $ make install 2355714Skris 2455714Skris [If any of these steps fails, see section Installation in Detail below.] 2555714Skris 2655714Skris This will build and install OpenSSL in the default location, which is (for 2755714Skris historical reasons) /usr/local/ssl. If you want to install it anywhere else, 2855714Skris run config like this: 2955714Skris 3055714Skris $ ./config --prefix=/usr/local --openssldir=/usr/local/openssl 3155714Skris 3255714Skris 3355714Skris Configuration Options 3455714Skris --------------------- 3555714Skris 3659191Skris There are several options to ./config (or ./Configure) to customize 3759191Skris the build: 3855714Skris 3955714Skris --prefix=DIR Install in DIR/bin, DIR/lib, DIR/include/openssl. 4055714Skris Configuration files used by OpenSSL will be in DIR/ssl 4155714Skris or the directory specified by --openssldir. 4255714Skris 4355714Skris --openssldir=DIR Directory for OpenSSL files. If no prefix is specified, 4455714Skris the library files and binaries are also installed there. 4555714Skris 4655714Skris rsaref Build with RSADSI's RSAREF toolkit (this assumes that 4755714Skris librsaref.a is in the library search path). 4855714Skris 4955714Skris no-threads Don't try to build with support for multi-threaded 5055714Skris applications. 5155714Skris 5255714Skris threads Build with support for multi-threaded applications. 5355714Skris This will usually require additional system-dependent options! 5455714Skris See "Note on multi-threading" below. 5555714Skris 5655714Skris no-asm Do not use assembler code. 5755714Skris 5855714Skris 386 Use the 80386 instruction set only (the default x86 code is 5955714Skris more efficient, but requires at least a 486). 6055714Skris 6155714Skris no-<cipher> Build without the specified cipher (bf, cast, des, dh, dsa, 6255714Skris hmac, md2, md5, mdc2, rc2, rc4, rc5, rsa, sha). 6355714Skris The crypto/<cipher> directory can be removed after running 6455714Skris "make depend". 6555714Skris 6655714Skris -Dxxx, -lxxx, -Lxxx, -fxxx, -Kxxx These system specific options will 6755714Skris be passed through to the compiler to allow you to 6855714Skris define preprocessor symbols, specify additional libraries, 6955714Skris library directories or other compiler options. 7055714Skris 7155714Skris 7255714Skris Installation in Detail 7355714Skris ---------------------- 7455714Skris 7555714Skris 1a. Configure OpenSSL for your operation system automatically: 7655714Skris 7755714Skris $ ./config [options] 7855714Skris 7955714Skris This guesses at your operating system (and compiler, if necessary) and 8055714Skris configures OpenSSL based on this guess. Run ./config -t to see 8159191Skris if it guessed correctly. If you want to use a different compiler, you 8259191Skris are cross-compiling for another platform, or the ./config guess was 8359191Skris wrong for other reasons, go to step 1b. Otherwise go to step 2. 8455714Skris 8555714Skris On some systems, you can include debugging information as follows: 8655714Skris 8755714Skris $ ./config -d [options] 8855714Skris 8955714Skris 1b. Configure OpenSSL for your operating system manually 9055714Skris 9155714Skris OpenSSL knows about a range of different operating system, hardware and 9255714Skris compiler combinations. To see the ones it knows about, run 9355714Skris 9455714Skris $ ./Configure 9555714Skris 9655714Skris Pick a suitable name from the list that matches your system. For most 9755714Skris operating systems there is a choice between using "cc" or "gcc". When 9855714Skris you have identified your system (and if necessary compiler) use this name 9955714Skris as the argument to ./Configure. For example, a "linux-elf" user would 10055714Skris run: 10155714Skris 10255714Skris $ ./Configure linux-elf [options] 10355714Skris 10455714Skris If your system is not available, you will have to edit the Configure 10555714Skris program and add the correct configuration for your system. The 10659191Skris generic configurations "cc" or "gcc" should usually work on 32 bit 10759191Skris systems. 10855714Skris 10955714Skris Configure creates the file Makefile.ssl from Makefile.org and 11055714Skris defines various macros in crypto/opensslconf.h (generated from 11155714Skris crypto/opensslconf.h.in). 11255714Skris 11355714Skris 2. Build OpenSSL by running: 11455714Skris 11555714Skris $ make 11655714Skris 11755714Skris This will build the OpenSSL libraries (libcrypto.a and libssl.a) and the 11855714Skris OpenSSL binary ("openssl"). The libraries will be built in the top-level 11955714Skris directory, and the binary will be in the "apps" directory. 12055714Skris 12159191Skris If "make" fails, please report the problem to <openssl-bugs@openssl.org> 12259191Skris (note that your message will be forwarded to a public mailing list). 12359191Skris Include the output of "make report" in your message. 12455714Skris 12555714Skris [If you encounter assembler error messages, try the "no-asm" 12659191Skris configuration option as an immediate fix.] 12755714Skris 12855714Skris Compiling parts of OpenSSL with gcc and others with the system 12955714Skris compiler will result in unresolved symbols on some systems. 13055714Skris 13155714Skris 3. After a successful build, the libraries should be tested. Run: 13255714Skris 13355714Skris $ make test 13455714Skris 13555714Skris If a test fails, try removing any compiler optimization flags from 13655714Skris the CFLAGS line in Makefile.ssl and run "make clean; make". Please 13755714Skris send a bug report to <openssl-bugs@openssl.org>, including the 13859191Skris output of "make report". 13955714Skris 14055714Skris 4. If everything tests ok, install OpenSSL with 14155714Skris 14255714Skris $ make install 14355714Skris 14455714Skris This will create the installation directory (if it does not exist) and 14555714Skris then the following subdirectories: 14655714Skris 14755714Skris certs Initially empty, this is the default location 14855714Skris for certificate files. 14959191Skris man/man1 Manual pages for the 'openssl' command line tool 15059191Skris man/man3 Manual pages for the libraries (very incomplete) 15155714Skris misc Various scripts. 15255714Skris private Initially empty, this is the default location 15355714Skris for private key files. 15455714Skris 15559191Skris If you didn't choose a different installation prefix, the 15655714Skris following additional subdirectories will be created: 15755714Skris 15855714Skris bin Contains the openssl binary and a few other 15955714Skris utility programs. 16055714Skris include/openssl Contains the header files needed if you want to 16155714Skris compile programs with libcrypto or libssl. 16255714Skris lib Contains the OpenSSL library files themselves. 16355714Skris 16455714Skris Package builders who want to configure the library for standard 16555714Skris locations, but have the package installed somewhere else so that 16655714Skris it can easily be packaged, can use 16755714Skris 16855714Skris $ make INSTALL_PREFIX=/tmp/package-root install 16955714Skris 17055714Skris (or specify "--install_prefix=/tmp/package-root" as a configure 17155714Skris option). The specified prefix will be prepended to all 17255714Skris installation target filenames. 17355714Skris 17455714Skris 17555714Skris NOTE: The header files used to reside directly in the include 17655714Skris directory, but have now been moved to include/openssl so that 17755714Skris OpenSSL can co-exist with other libraries which use some of the 17855714Skris same filenames. This means that applications that use OpenSSL 17955714Skris should now use C preprocessor directives of the form 18055714Skris 18155714Skris #include <openssl/ssl.h> 18255714Skris 18355714Skris instead of "#include <ssl.h>", which was used with library versions 18455714Skris up to OpenSSL 0.9.2b. 18555714Skris 18655714Skris If you install a new version of OpenSSL over an old library version, 18755714Skris you should delete the old header files in the include directory. 18855714Skris 18955714Skris Compatibility issues: 19055714Skris 19155714Skris * COMPILING existing applications 19255714Skris 19355714Skris To compile an application that uses old filenames -- e.g. 19455714Skris "#include <ssl.h>" --, it will usually be enough to find 19555714Skris the CFLAGS definition in the application's Makefile and 19655714Skris add a C option such as 19755714Skris 19855714Skris -I/usr/local/ssl/include/openssl 19955714Skris 20055714Skris to it. 20155714Skris 20255714Skris But don't delete the existing -I option that points to 20355714Skris the ..../include directory! Otherwise, OpenSSL header files 20455714Skris could not #include each other. 20555714Skris 20655714Skris * WRITING applications 20755714Skris 20855714Skris To write an application that is able to handle both the new 20955714Skris and the old directory layout, so that it can still be compiled 21055714Skris with library versions up to OpenSSL 0.9.2b without bothering 21155714Skris the user, you can proceed as follows: 21255714Skris 21355714Skris - Always use the new filename of OpenSSL header files, 21455714Skris e.g. #include <openssl/ssl.h>. 21555714Skris 21655714Skris - Create a directory "incl" that contains only a symbolic 21755714Skris link named "openssl", which points to the "include" directory 21855714Skris of OpenSSL. 21955714Skris For example, your application's Makefile might contain the 22055714Skris following rule, if OPENSSLDIR is a pathname (absolute or 22155714Skris relative) of the directory where OpenSSL resides: 22255714Skris 22355714Skris incl/openssl: 22455714Skris -mkdir incl 22555714Skris cd $(OPENSSLDIR) # Check whether the directory really exists 22655714Skris -ln -s `cd $(OPENSSLDIR); pwd`/include incl/openssl 22755714Skris 22855714Skris You will have to add "incl/openssl" to the dependencies 22955714Skris of those C files that include some OpenSSL header file. 23055714Skris 23155714Skris - Add "-Iincl" to your CFLAGS. 23255714Skris 23355714Skris With these additions, the OpenSSL header files will be available 23455714Skris under both name variants if an old library version is used: 23555714Skris Your application can reach them under names like <openssl/foo.h>, 23655714Skris while the header files still are able to #include each other 23755714Skris with names of the form <foo.h>. 23855714Skris 23955714Skris 24055714Skris Note on multi-threading 24155714Skris ----------------------- 24255714Skris 24355714Skris For some systems, the OpenSSL Configure script knows what compiler options 24455714Skris are needed to generate a library that is suitable for multi-threaded 24555714Skris applications. On these systems, support for multi-threading is enabled 24655714Skris by default; use the "no-threads" option to disable (this should never be 24755714Skris necessary). 24855714Skris 24955714Skris On other systems, to enable support for multi-threading, you will have 25055714Skris to specify at least two options: "threads", and a system-dependent option. 25155714Skris (The latter is "-D_REENTRANT" on various systems.) The default in this 25255714Skris case, obviously, is not to include support for multi-threading (but 25355714Skris you can still use "no-threads" to suppress an annoying warning message 25455714Skris from the Configure script.) 25555714Skris 256