INSTALL revision 59191
13302Sagiri 23302Sagiri INSTALLATION ON THE UNIX PLATFORM 33302Sagiri --------------------------------- 43302Sagiri 53302Sagiri [Installation on Windows, OpenVMS and MacOS (before MacOS X) is described 63302Sagiri in INSTALL.W32, INSTALL.VMS and INSTALL.MacOS.] 73302Sagiri 83302Sagiri To install OpenSSL, you will need: 93302Sagiri 103302Sagiri * Perl 5 113302Sagiri * an ANSI C compiler 123302Sagiri * a supported Unix operating system 133302Sagiri 143302Sagiri Quick Start 153302Sagiri ----------- 163302Sagiri 173302Sagiri If you want to just get on with it, do: 183302Sagiri 193302Sagiri $ ./config 203302Sagiri $ make 213302Sagiri $ make test 2210489SGiri.Adari@Sun.COM $ make install 233302Sagiri 243302Sagiri [If any of these steps fails, see section Installation in Detail below.] 253302Sagiri 263302Sagiri This will build and install OpenSSL in the default location, which is (for 273302Sagiri historical reasons) /usr/local/ssl. If you want to install it anywhere else, 283302Sagiri run config like this: 293302Sagiri 303302Sagiri $ ./config --prefix=/usr/local --openssldir=/usr/local/openssl 313302Sagiri 323302Sagiri 333302Sagiri Configuration Options 343302Sagiri --------------------- 353302Sagiri 363302Sagiri There are several options to ./config (or ./Configure) to customize 373302Sagiri the build: 383302Sagiri 393302Sagiri --prefix=DIR Install in DIR/bin, DIR/lib, DIR/include/openssl. 403302Sagiri Configuration files used by OpenSSL will be in DIR/ssl 413302Sagiri or the directory specified by --openssldir. 423302Sagiri 433302Sagiri --openssldir=DIR Directory for OpenSSL files. If no prefix is specified, 443302Sagiri the library files and binaries are also installed there. 453302Sagiri 463302Sagiri rsaref Build with RSADSI's RSAREF toolkit (this assumes that 473302Sagiri librsaref.a is in the library search path). 483302Sagiri 493302Sagiri no-threads Don't try to build with support for multi-threaded 503302Sagiri applications. 513302Sagiri 523302Sagiri threads Build with support for multi-threaded applications. 533302Sagiri This will usually require additional system-dependent options! 543302Sagiri See "Note on multi-threading" below. 553302Sagiri 563302Sagiri no-asm Do not use assembler code. 573302Sagiri 583302Sagiri 386 Use the 80386 instruction set only (the default x86 code is 593302Sagiri more efficient, but requires at least a 486). 603302Sagiri 613302Sagiri no-<cipher> Build without the specified cipher (bf, cast, des, dh, dsa, 623302Sagiri hmac, md2, md5, mdc2, rc2, rc4, rc5, rsa, sha). 633302Sagiri The crypto/<cipher> directory can be removed after running 643302Sagiri "make depend". 653302Sagiri 663302Sagiri -Dxxx, -lxxx, -Lxxx, -fxxx, -Kxxx These system specific options will 673302Sagiri be passed through to the compiler to allow you to 683302Sagiri define preprocessor symbols, specify additional libraries, 693302Sagiri library directories or other compiler options. 703302Sagiri 713302Sagiri 723302Sagiri Installation in Detail 733302Sagiri ---------------------- 743302Sagiri 753302Sagiri 1a. Configure OpenSSL for your operation system automatically: 763302Sagiri 773302Sagiri $ ./config [options] 783302Sagiri 793302Sagiri This guesses at your operating system (and compiler, if necessary) and 803302Sagiri configures OpenSSL based on this guess. Run ./config -t to see 813302Sagiri if it guessed correctly. If you want to use a different compiler, you 823302Sagiri are cross-compiling for another platform, or the ./config guess was 833302Sagiri wrong for other reasons, go to step 1b. Otherwise go to step 2. 843302Sagiri 853302Sagiri On some systems, you can include debugging information as follows: 863302Sagiri 873302Sagiri $ ./config -d [options] 883302Sagiri 893302Sagiri 1b. Configure OpenSSL for your operating system manually 903302Sagiri 913302Sagiri OpenSSL knows about a range of different operating system, hardware and 924467Sagiri compiler combinations. To see the ones it knows about, run 934467Sagiri 944467Sagiri $ ./Configure 954467Sagiri 964703Shiremath Pick a suitable name from the list that matches your system. For most 974703Shiremath operating systems there is a choice between using "cc" or "gcc". When 983302Sagiri you have identified your system (and if necessary compiler) use this name 994467Sagiri as the argument to ./Configure. For example, a "linux-elf" user would 1003302Sagiri run: 1013302Sagiri 1023302Sagiri $ ./Configure linux-elf [options] 1034467Sagiri 1044467Sagiri If your system is not available, you will have to edit the Configure 1054467Sagiri program and add the correct configuration for your system. The 1064467Sagiri generic configurations "cc" or "gcc" should usually work on 32 bit 1074467Sagiri systems. 1084467Sagiri 1094467Sagiri Configure creates the file Makefile.ssl from Makefile.org and 1104467Sagiri defines various macros in crypto/opensslconf.h (generated from 1114467Sagiri crypto/opensslconf.h.in). 1124467Sagiri 1134467Sagiri 2. Build OpenSSL by running: 1144467Sagiri 1154467Sagiri $ make 1164467Sagiri 1174467Sagiri This will build the OpenSSL libraries (libcrypto.a and libssl.a) and the 1184467Sagiri OpenSSL binary ("openssl"). The libraries will be built in the top-level 1194467Sagiri directory, and the binary will be in the "apps" directory. 1204467Sagiri 1214467Sagiri If "make" fails, please report the problem to <openssl-bugs@openssl.org> 1224467Sagiri (note that your message will be forwarded to a public mailing list). 1233302Sagiri Include the output of "make report" in your message. 1243302Sagiri 1253302Sagiri [If you encounter assembler error messages, try the "no-asm" 1263302Sagiri configuration option as an immediate fix.] 1273302Sagiri 1283302Sagiri Compiling parts of OpenSSL with gcc and others with the system 1294467Sagiri compiler will result in unresolved symbols on some systems. 1303302Sagiri 1313302Sagiri 3. After a successful build, the libraries should be tested. Run: 1323302Sagiri 1334467Sagiri $ make test 1344467Sagiri 1354467Sagiri If a test fails, try removing any compiler optimization flags from 1364467Sagiri the CFLAGS line in Makefile.ssl and run "make clean; make". Please 1374467Sagiri send a bug report to <openssl-bugs@openssl.org>, including the 1384467Sagiri output of "make report". 1394467Sagiri 1404467Sagiri 4. If everything tests ok, install OpenSSL with 1414467Sagiri 1424467Sagiri $ make install 1434467Sagiri 1444467Sagiri This will create the installation directory (if it does not exist) and 1454467Sagiri then the following subdirectories: 1464467Sagiri 1474467Sagiri certs Initially empty, this is the default location 1484467Sagiri for certificate files. 1493302Sagiri man/man1 Manual pages for the 'openssl' command line tool 1503302Sagiri man/man3 Manual pages for the libraries (very incomplete) 1514467Sagiri misc Various scripts. 1524467Sagiri private Initially empty, this is the default location 1534467Sagiri for private key files. 1543302Sagiri 1554467Sagiri If you didn't choose a different installation prefix, the 1564467Sagiri following additional subdirectories will be created: 1574467Sagiri 1584467Sagiri bin Contains the openssl binary and a few other 1594467Sagiri utility programs. 1604467Sagiri include/openssl Contains the header files needed if you want to 1614467Sagiri compile programs with libcrypto or libssl. 1623302Sagiri lib Contains the OpenSSL library files themselves. 1633302Sagiri 1644467Sagiri Package builders who want to configure the library for standard 1654467Sagiri locations, but have the package installed somewhere else so that 1664467Sagiri it can easily be packaged, can use 1673302Sagiri 1684467Sagiri $ make INSTALL_PREFIX=/tmp/package-root install 1694467Sagiri 1703302Sagiri (or specify "--install_prefix=/tmp/package-root" as a configure 1713302Sagiri option). The specified prefix will be prepended to all 1723302Sagiri installation target filenames. 1733302Sagiri 1743302Sagiri 1753302Sagiri NOTE: The header files used to reside directly in the include 1764467Sagiri directory, but have now been moved to include/openssl so that 1773302Sagiri OpenSSL can co-exist with other libraries which use some of the 1783302Sagiri same filenames. This means that applications that use OpenSSL 1793302Sagiri should now use C preprocessor directives of the form 1804467Sagiri 1814467Sagiri #include <openssl/ssl.h> 1824467Sagiri 1834467Sagiri instead of "#include <ssl.h>", which was used with library versions 1844467Sagiri up to OpenSSL 0.9.2b. 1854467Sagiri 1864467Sagiri If you install a new version of OpenSSL over an old library version, 1874467Sagiri you should delete the old header files in the include directory. 1884467Sagiri 1894467Sagiri Compatibility issues: 1904467Sagiri 1914467Sagiri * COMPILING existing applications 1924467Sagiri 1934467Sagiri To compile an application that uses old filenames -- e.g. 1944467Sagiri "#include <ssl.h>" --, it will usually be enough to find 1954467Sagiri the CFLAGS definition in the application's Makefile and 1963302Sagiri add a C option such as 1973302Sagiri 1984467Sagiri -I/usr/local/ssl/include/openssl 1994467Sagiri 2004467Sagiri to it. 2013302Sagiri 2024467Sagiri But don't delete the existing -I option that points to 2034467Sagiri the ..../include directory! Otherwise, OpenSSL header files 2044467Sagiri could not #include each other. 2054467Sagiri 2064467Sagiri * WRITING applications 2074467Sagiri 2084467Sagiri To write an application that is able to handle both the new 2093302Sagiri and the old directory layout, so that it can still be compiled 2103302Sagiri with library versions up to OpenSSL 0.9.2b without bothering 2114467Sagiri the user, you can proceed as follows: 2124467Sagiri 2134467Sagiri - Always use the new filename of OpenSSL header files, 2143302Sagiri e.g. #include <openssl/ssl.h>. 2154467Sagiri 2164467Sagiri - Create a directory "incl" that contains only a symbolic 2173302Sagiri link named "openssl", which points to the "include" directory 2183302Sagiri of OpenSSL. 2193302Sagiri For example, your application's Makefile might contain the 2203302Sagiri following rule, if OPENSSLDIR is a pathname (absolute or 2213302Sagiri relative) of the directory where OpenSSL resides: 2223302Sagiri 2234467Sagiri incl/openssl: 2243302Sagiri -mkdir incl 2254467Sagiri cd $(OPENSSLDIR) # Check whether the directory really exists 2264467Sagiri -ln -s `cd $(OPENSSLDIR); pwd`/include incl/openssl 2274467Sagiri 2284467Sagiri You will have to add "incl/openssl" to the dependencies 2294467Sagiri of those C files that include some OpenSSL header file. 2304467Sagiri 2314467Sagiri - Add "-Iincl" to your CFLAGS. 2324467Sagiri 2334467Sagiri With these additions, the OpenSSL header files will be available 2344467Sagiri under both name variants if an old library version is used: 2354467Sagiri Your application can reach them under names like <openssl/foo.h>, 2364467Sagiri while the header files still are able to #include each other 2374467Sagiri with names of the form <foo.h>. 2384467Sagiri 2394467Sagiri 2404467Sagiri Note on multi-threading 2414467Sagiri ----------------------- 2424467Sagiri 2434467Sagiri For some systems, the OpenSSL Configure script knows what compiler options 2444467Sagiri are needed to generate a library that is suitable for multi-threaded 2454467Sagiri applications. On these systems, support for multi-threading is enabled 2464467Sagiri by default; use the "no-threads" option to disable (this should never be 2473302Sagiri necessary). 2483302Sagiri 2493302Sagiri On other systems, to enable support for multi-threading, you will have 2503302Sagiri to specify at least two options: "threads", and a system-dependent option. 2514467Sagiri (The latter is "-D_REENTRANT" on various systems.) The default in this 2523302Sagiri case, obviously, is not to include support for multi-threading (but 2534467Sagiri you can still use "no-threads" to suppress an annoying warning message 2544467Sagiri from the Configure script.) 2554467Sagiri 2564467Sagiri