INSTALL revision 142425
1226586Sdim 2226586Sdim INSTALLATION ON THE UNIX PLATFORM 3353358Sdim --------------------------------- 4353358Sdim 5353358Sdim [Installation on DOS (with djgpp), Windows, OpenVMS and MacOS (before MacOS X) 6226586Sdim is described in INSTALL.DJGPP, INSTALL.W32, INSTALL.VMS and INSTALL.MacOS. 7226586Sdim This document describes installation on operating systems in the Unix 8226586Sdim family.] 9226586Sdim 10226586Sdim To install OpenSSL, you will need: 11226586Sdim 12226586Sdim * make 13249423Sdim * Perl 5 14314564Sdim * an ANSI C compiler 15226586Sdim * a development environment in form of development libraries and C 16226586Sdim header files 17226586Sdim * a supported Unix operating system 18226586Sdim 19226586Sdim Quick Start 20226586Sdim ----------- 21226586Sdim 22341825Sdim If you want to just get on with it, do: 23327952Sdim 24327952Sdim $ ./config 25327952Sdim $ make 26327952Sdim $ make test 27327952Sdim $ make install 28327952Sdim 29327952Sdim [If any of these steps fails, see section Installation in Detail below.] 30327952Sdim 31327952Sdim This will build and install OpenSSL in the default location, which is (for 32327952Sdim historical reasons) /usr/local/ssl. If you want to install it anywhere else, 33327952Sdim run config like this: 34327952Sdim 35327952Sdim $ ./config --prefix=/usr/local --openssldir=/usr/local/openssl 36327952Sdim 37327952Sdim 38327952Sdim Configuration Options 39327952Sdim --------------------- 40226586Sdim 41226586Sdim There are several options to ./config (or ./Configure) to customize 42226586Sdim the build: 43226586Sdim 44226586Sdim --prefix=DIR Install in DIR/bin, DIR/lib, DIR/include/openssl. 45226586Sdim Configuration files used by OpenSSL will be in DIR/ssl 46296417Sdim or the directory specified by --openssldir. 47226586Sdim 48226586Sdim --openssldir=DIR Directory for OpenSSL files. If no prefix is specified, 49226586Sdim the library files and binaries are also installed there. 50226586Sdim 51296417Sdim no-threads Don't try to build with support for multi-threaded 52288943Sdim applications. 53226586Sdim 54226586Sdim threads Build with support for multi-threaded applications. 55296417Sdim This will usually require additional system-dependent options! 56234353Sdim See "Note on multi-threading" below. 57234353Sdim 58234353Sdim no-zlib Don't try to build with support for zlib compression and 59234353Sdim decompression. 60296417Sdim 61226586Sdim zlib Build with support for zlib compression/decompression. 62296417Sdim 63226586Sdim zlib-dynamic Like "zlib", but has OpenSSL load the zlib library dynamically 64226586Sdim when needed. This is only supported on systems where loading 65226586Sdim of shared libraries is supported. This is the default choice. 66234353Sdim 67243830Sdim no-shared Don't try to create shared libraries. 68276479Sdim 69276479Sdim shared In addition to the usual static libraries, create shared 70226586Sdim libraries on platforms where it's supported. See "Note on 71226586Sdim shared libraries" below. 72226586Sdim 73239462Sdim no-asm Do not use assembler code. 74234353Sdim 75234353Sdim 386 Use the 80386 instruction set only (the default x86 code is 76226586Sdim more efficient, but requires at least a 486). 77226586Sdim 78296417Sdim no-<cipher> Build without the specified cipher (bf, cast, des, dh, dsa, 79226586Sdim hmac, md2, md5, mdc2, rc2, rc4, rc5, rsa, sha). 80243830Sdim The crypto/<cipher> directory can be removed after running 81239462Sdim "make depend". 82239462Sdim 83239462Sdim -Dxxx, -lxxx, -Lxxx, -fxxx, -Kxxx These system specific options will 84239462Sdim be passed through to the compiler to allow you to 85243830Sdim define preprocessor symbols, specify additional libraries, 86327952Sdim library directories or other compiler options. 87327952Sdim 88327952Sdim 89327952Sdim Installation in Detail 90239462Sdim ---------------------- 91239462Sdim 92276479Sdim 1a. Configure OpenSSL for your operation system automatically: 93276479Sdim 94276479Sdim $ ./config [options] 95276479Sdim 96276479Sdim This guesses at your operating system (and compiler, if necessary) and 97276479Sdim configures OpenSSL based on this guess. Run ./config -t to see 98226586Sdim if it guessed correctly. If you want to use a different compiler, you 99226586Sdim are cross-compiling for another platform, or the ./config guess was 100296417Sdim wrong for other reasons, go to step 1b. Otherwise go to step 2. 101327952Sdim 102327952Sdim On some systems, you can include debugging information as follows: 103353358Sdim 104353358Sdim $ ./config -d [options] 105360784Sdim 106360784Sdim 1b. Configure OpenSSL for your operating system manually 107296417Sdim 108226586Sdim OpenSSL knows about a range of different operating system, hardware and 109234353Sdim compiler combinations. To see the ones it knows about, run 110226586Sdim 111226586Sdim $ ./Configure 112296417Sdim 113226586Sdim Pick a suitable name from the list that matches your system. For most 114296417Sdim operating systems there is a choice between using "cc" or "gcc". When 115226586Sdim you have identified your system (and if necessary compiler) use this name 116226586Sdim as the argument to ./Configure. For example, a "linux-elf" user would 117226586Sdim run: 118226586Sdim 119226586Sdim $ ./Configure linux-elf [options] 120226586Sdim 121226586Sdim If your system is not available, you will have to edit the Configure 122226586Sdim program and add the correct configuration for your system. The 123226586Sdim generic configurations "cc" or "gcc" should usually work on 32 bit 124226586Sdim systems. 125226586Sdim 126226586Sdim Configure creates the file Makefile from Makefile.org and 127226586Sdim defines various macros in crypto/opensslconf.h (generated from 128226586Sdim crypto/opensslconf.h.in). 129296417Sdim 130226586Sdim 2. Build OpenSSL by running: 131226586Sdim 132226586Sdim $ make 133226586Sdim 134234353Sdim This will build the OpenSSL libraries (libcrypto.a and libssl.a) and the 135296417Sdim OpenSSL binary ("openssl"). The libraries will be built in the top-level 136226586Sdim directory, and the binary will be in the "apps" directory. 137226586Sdim 138226586Sdim If "make" fails, look at the output. There may be reasons for 139226586Sdim the failure that aren't problems in OpenSSL itself (like missing 140234353Sdim standard headers). If it is a problem with OpenSSL itself, please 141234353Sdim report the problem to <openssl-bugs@openssl.org> (note that your 142296417Sdim message will be recorded in the request tracker publicly readable 143226586Sdim via http://www.openssl.org/support/rt2.html and will be forwarded to a 144226586Sdim public mailing list). Include the output of "make report" in your message. 145226586Sdim Please check out the request tracker. Maybe the bug was already 146226586Sdim reported or has already been fixed. 147296417Sdim 148226586Sdim [If you encounter assembler error messages, try the "no-asm" 149226586Sdim configuration option as an immediate fix.] 150226586Sdim 151296417Sdim Compiling parts of OpenSSL with gcc and others with the system 152226586Sdim compiler will result in unresolved symbols on some systems. 153296417Sdim 154226586Sdim 3. After a successful build, the libraries should be tested. Run: 155226586Sdim 156296417Sdim $ make test 157226586Sdim 158226586Sdim If a test fails, look at the output. There may be reasons for 159226586Sdim the failure that isn't a problem in OpenSSL itself (like a missing 160296417Sdim or malfunctioning bc). If it is a problem with OpenSSL itself, 161226586Sdim try removing any compiler optimization flags from the CFLAG line 162226586Sdim in Makefile and run "make clean; make". Please send a bug 163296417Sdim report to <openssl-bugs@openssl.org>, including the output of 164226586Sdim "make report" in order to be added to the request tracker at 165296417Sdim http://www.openssl.org/support/rt2.html. 166234353Sdim 167226586Sdim 4. If everything tests ok, install OpenSSL with 168226586Sdim 169226586Sdim $ make install 170276479Sdim 171243830Sdim This will create the installation directory (if it does not exist) and 172226586Sdim then the following subdirectories: 173226586Sdim 174226586Sdim certs Initially empty, this is the default location 175226586Sdim for certificate files. 176226586Sdim man/man1 Manual pages for the 'openssl' command line tool 177226586Sdim man/man3 Manual pages for the libraries (very incomplete) 178226586Sdim misc Various scripts. 179226586Sdim private Initially empty, this is the default location 180296417Sdim for private key files. 181296417Sdim 182226586Sdim If you didn't choose a different installation prefix, the 183239462Sdim following additional subdirectories will be created: 184234353Sdim 185226586Sdim bin Contains the openssl binary and a few other 186234353Sdim utility programs. 187296417Sdim include/openssl Contains the header files needed if you want to 188226586Sdim compile programs with libcrypto or libssl. 189226586Sdim lib Contains the OpenSSL library files themselves. 190226586Sdim 191296417Sdim Package builders who want to configure the library for standard 192226586Sdim locations, but have the package installed somewhere else so that 193226586Sdim it can easily be packaged, can use 194226586Sdim 195226586Sdim $ make INSTALL_PREFIX=/tmp/package-root install 196226586Sdim 197226586Sdim (or specify "--install_prefix=/tmp/package-root" as a configure 198296417Sdim option). The specified prefix will be prepended to all 199226586Sdim installation target filenames. 200239462Sdim 201296417Sdim 202239462Sdim NOTE: The header files used to reside directly in the include 203296417Sdim directory, but have now been moved to include/openssl so that 204261991Sdim OpenSSL can co-exist with other libraries which use some of the 205261991Sdim same filenames. This means that applications that use OpenSSL 206296417Sdim should now use C preprocessor directives of the form 207239462Sdim 208296417Sdim #include <openssl/ssl.h> 209239462Sdim 210239462Sdim instead of "#include <ssl.h>", which was used with library versions 211239462Sdim up to OpenSSL 0.9.2b. 212239462Sdim 213296417Sdim If you install a new version of OpenSSL over an old library version, 214239462Sdim you should delete the old header files in the include directory. 215239462Sdim 216296417Sdim Compatibility issues: 217296417Sdim 218296417Sdim * COMPILING existing applications 219239462Sdim 220296417Sdim To compile an application that uses old filenames -- e.g. 221296417Sdim "#include <ssl.h>" --, it will usually be enough to find 222296417Sdim the CFLAGS definition in the application's Makefile and 223296417Sdim add a C option such as 224296417Sdim 225296417Sdim -I/usr/local/ssl/include/openssl 226296417Sdim 227296417Sdim to it. 228296417Sdim 229296417Sdim But don't delete the existing -I option that points to 230296417Sdim the ..../include directory! Otherwise, OpenSSL header files 231296417Sdim could not #include each other. 232296417Sdim 233296417Sdim * WRITING applications 234296417Sdim 235296417Sdim To write an application that is able to handle both the new 236239462Sdim and the old directory layout, so that it can still be compiled 237296417Sdim with library versions up to OpenSSL 0.9.2b without bothering 238321369Sdim the user, you can proceed as follows: 239296417Sdim 240321369Sdim - Always use the new filename of OpenSSL header files, 241296417Sdim e.g. #include <openssl/ssl.h>. 242296417Sdim 243296417Sdim - Create a directory "incl" that contains only a symbolic 244321369Sdim link named "openssl", which points to the "include" directory 245239462Sdim of OpenSSL. 246239462Sdim For example, your application's Makefile might contain the 247239462Sdim following rule, if OPENSSLDIR is a pathname (absolute or 248296417Sdim relative) of the directory where OpenSSL resides: 249226586Sdim 250243830Sdim incl/openssl: 251234353Sdim -mkdir incl 252239462Sdim cd $(OPENSSLDIR) # Check whether the directory really exists 253276479Sdim -ln -s `cd $(OPENSSLDIR); pwd`/include incl/openssl 254276479Sdim 255226586Sdim You will have to add "incl/openssl" to the dependencies 256226586Sdim of those C files that include some OpenSSL header file. 257226586Sdim 258226586Sdim - Add "-Iincl" to your CFLAGS. 259314564Sdim 260314564Sdim With these additions, the OpenSSL header files will be available 261314564Sdim under both name variants if an old library version is used: 262314564Sdim Your application can reach them under names like <openssl/foo.h>, 263341825Sdim while the header files still are able to #include each other 264341825Sdim with names of the form <foo.h>. 265341825Sdim 266341825Sdim 267341825Sdim Note on multi-threading 268341825Sdim ----------------------- 269341825Sdim 270314564Sdim For some systems, the OpenSSL Configure script knows what compiler options 271341825Sdim are needed to generate a library that is suitable for multi-threaded 272341825Sdim applications. On these systems, support for multi-threading is enabled 273314564Sdim by default; use the "no-threads" option to disable (this should never be 274314564Sdim necessary). 275314564Sdim 276314564Sdim On other systems, to enable support for multi-threading, you will have 277341825Sdim to specify at least two options: "threads", and a system-dependent option. 278360784Sdim (The latter is "-D_REENTRANT" on various systems.) The default in this 279341825Sdim case, obviously, is not to include support for multi-threading (but 280314564Sdim you can still use "no-threads" to suppress an annoying warning message 281314564Sdim from the Configure script.) 282314564Sdim 283314564Sdim 284314564Sdim Note on shared libraries 285314564Sdim ------------------------ 286314564Sdim 287314564Sdim Shared library is currently an experimental feature. The only reason to 288314564Sdim have them would be to conserve memory on systems where several program 289314564Sdim are using OpenSSL. Binary backward compatibility can't be guaranteed 290314564Sdim before OpenSSL version 1.0. 291314564Sdim 292314564Sdim For some systems, the OpenSSL Configure script knows what is needed to 293314564Sdim build shared libraries for libcrypto and libssl. On these systems, 294314564Sdim the shared libraries are currently not created by default, but giving 295314564Sdim the option "shared" will get them created. This method supports Makefile 296314564Sdim targets for shared library creation, like linux-shared. Those targets 297314564Sdim can currently be used on their own just as well, but this is expected 298314564Sdim to change in future versions of OpenSSL. 299314564Sdim 300314564Sdim Note on random number generation 301296417Sdim -------------------------------- 302226586Sdim 303296417Sdim Availability of cryptographically secure random numbers is required for 304226586Sdim secret key generation. OpenSSL provides several options to seed the 305226586Sdim internal PRNG. If not properly seeded, the internal PRNG will refuse 306296417Sdim to deliver random bytes and a "PRNG not seeded error" will occur. 307234353Sdim On systems without /dev/urandom (or similar) device, it may be necessary 308226586Sdim to install additional support software to obtain random seed. 309226586Sdim Please check out the manual pages for RAND_add(), RAND_bytes(), RAND_egd(), 310226586Sdim and the FAQ for more information. 311234353Sdim 312234353Sdim Note on support for multiple builds 313234353Sdim ----------------------------------- 314226586Sdim 315226586Sdim OpenSSL is usually built in it's source tree. Unfortunately, this doesn't 316226586Sdim support building for multiple platforms from the same source tree very well. 317296417Sdim It is however possible to build in a separate tree through the use of lots 318296417Sdim of symbolic links, which should be prepared like this: 319226586Sdim 320226586Sdim mkdir -p objtree/"`uname -s`-`uname -r`-`uname -m`" 321296417Sdim cd objtree/"`uname -s`-`uname -r`-`uname -m`" 322226586Sdim (cd $OPENSSL_SOURCE; find . -type f) | while read F; do 323226586Sdim mkdir -p `dirname $F` 324296417Sdim rm -f $F; ln -s $OPENSSL_SOURCE/$F $F 325243830Sdim echo $F '->' $OPENSSL_SOURCE/$F 326226586Sdim done 327226586Sdim make -f Makefile.org clean 328296417Sdim 329226586Sdim OPENSSL_SOURCE is an environment variable that contains the absolute (this 330243830Sdim is important!) path to the OpenSSL source tree. 331243830Sdim 332243830Sdim Also, operations like 'make update' should still be made in the source tree. 333226586Sdim