INSTALL revision 55714
155714Skris 255714Skris INSTALLATION ON THE UNIX PLATFORM 355714Skris --------------------------------- 455714Skris 555714Skris [See INSTALL.W32 for instructions for compiling OpenSSL on Windows systems, 655714Skris and INSTALL.VMS for installing on OpenVMS systems.] 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 3655714Skris There are several options to ./config to customize the build: 3755714Skris 3855714Skris --prefix=DIR Install in DIR/bin, DIR/lib, DIR/include/openssl. 3955714Skris Configuration files used by OpenSSL will be in DIR/ssl 4055714Skris or the directory specified by --openssldir. 4155714Skris 4255714Skris --openssldir=DIR Directory for OpenSSL files. If no prefix is specified, 4355714Skris the library files and binaries are also installed there. 4455714Skris 4555714Skris rsaref Build with RSADSI's RSAREF toolkit (this assumes that 4655714Skris librsaref.a is in the library search path). 4755714Skris 4855714Skris no-threads Don't try to build with support for multi-threaded 4955714Skris applications. 5055714Skris 5155714Skris threads Build with support for multi-threaded applications. 5255714Skris This will usually require additional system-dependent options! 5355714Skris See "Note on multi-threading" below. 5455714Skris 5555714Skris no-asm Do not use assembler code. 5655714Skris 5755714Skris 386 Use the 80386 instruction set only (the default x86 code is 5855714Skris more efficient, but requires at least a 486). 5955714Skris 6055714Skris no-<cipher> Build without the specified cipher (bf, cast, des, dh, dsa, 6155714Skris hmac, md2, md5, mdc2, rc2, rc4, rc5, rsa, sha). 6255714Skris The crypto/<cipher> directory can be removed after running 6355714Skris "make depend". 6455714Skris 6555714Skris -Dxxx, -lxxx, -Lxxx, -fxxx, -Kxxx These system specific options will 6655714Skris be passed through to the compiler to allow you to 6755714Skris define preprocessor symbols, specify additional libraries, 6855714Skris library directories or other compiler options. 6955714Skris 7055714Skris 7155714Skris Installation in Detail 7255714Skris ---------------------- 7355714Skris 7455714Skris 1a. Configure OpenSSL for your operation system automatically: 7555714Skris 7655714Skris $ ./config [options] 7755714Skris 7855714Skris This guesses at your operating system (and compiler, if necessary) and 7955714Skris configures OpenSSL based on this guess. Run ./config -t to see 8055714Skris if it guessed correctly. If it did not get it correct or you want to 8155714Skris use a different compiler then go to step 1b. Otherwise go to step 2. 8255714Skris 8355714Skris On some systems, you can include debugging information as follows: 8455714Skris 8555714Skris $ ./config -d [options] 8655714Skris 8755714Skris 1b. Configure OpenSSL for your operating system manually 8855714Skris 8955714Skris OpenSSL knows about a range of different operating system, hardware and 9055714Skris compiler combinations. To see the ones it knows about, run 9155714Skris 9255714Skris $ ./Configure 9355714Skris 9455714Skris Pick a suitable name from the list that matches your system. For most 9555714Skris operating systems there is a choice between using "cc" or "gcc". When 9655714Skris you have identified your system (and if necessary compiler) use this name 9755714Skris as the argument to ./Configure. For example, a "linux-elf" user would 9855714Skris run: 9955714Skris 10055714Skris $ ./Configure linux-elf [options] 10155714Skris 10255714Skris If your system is not available, you will have to edit the Configure 10355714Skris program and add the correct configuration for your system. The 10455714Skris generic configurations "cc" or "gcc" should usually work. 10555714Skris 10655714Skris Configure creates the file Makefile.ssl from Makefile.org and 10755714Skris defines various macros in crypto/opensslconf.h (generated from 10855714Skris crypto/opensslconf.h.in). 10955714Skris 11055714Skris 2. Build OpenSSL by running: 11155714Skris 11255714Skris $ make 11355714Skris 11455714Skris This will build the OpenSSL libraries (libcrypto.a and libssl.a) and the 11555714Skris OpenSSL binary ("openssl"). The libraries will be built in the top-level 11655714Skris directory, and the binary will be in the "apps" directory. 11755714Skris 11855714Skris If "make" fails, please report the problem to <openssl-bugs@openssl.org>. 11955714Skris Include the output of "./config -t" and the OpenSSL version 12055714Skris number in your message. 12155714Skris 12255714Skris [If you encounter assembler error messages, try the "no-asm" 12355714Skris configuration option as an immediate fix. Note that on Solaris x86 12455714Skris (not on Sparcs!) you may have to install the GNU assembler to use 12555714Skris OpenSSL assembler code -- /usr/ccs/bin/as won't do.] 12655714Skris 12755714Skris Compiling parts of OpenSSL with gcc and others with the system 12855714Skris compiler will result in unresolved symbols on some systems. 12955714Skris 13055714Skris 3. After a successful build, the libraries should be tested. Run: 13155714Skris 13255714Skris $ make test 13355714Skris 13455714Skris If a test fails, try removing any compiler optimization flags from 13555714Skris the CFLAGS line in Makefile.ssl and run "make clean; make". Please 13655714Skris send a bug report to <openssl-bugs@openssl.org>, including the 13755714Skris output of "openssl version -a" and of the failed test. 13855714Skris 13955714Skris 4. If everything tests ok, install OpenSSL with 14055714Skris 14155714Skris $ make install 14255714Skris 14355714Skris This will create the installation directory (if it does not exist) and 14455714Skris then the following subdirectories: 14555714Skris 14655714Skris certs Initially empty, this is the default location 14755714Skris for certificate files. 14855714Skris misc Various scripts. 14955714Skris private Initially empty, this is the default location 15055714Skris for private key files. 15155714Skris 15255714Skris If you didn't chose a different installation prefix, the 15355714Skris following additional subdirectories will be created: 15455714Skris 15555714Skris bin Contains the openssl binary and a few other 15655714Skris utility programs. 15755714Skris include/openssl Contains the header files needed if you want to 15855714Skris compile programs with libcrypto or libssl. 15955714Skris lib Contains the OpenSSL library files themselves. 16055714Skris 16155714Skris Package builders who want to configure the library for standard 16255714Skris locations, but have the package installed somewhere else so that 16355714Skris it can easily be packaged, can use 16455714Skris 16555714Skris $ make INSTALL_PREFIX=/tmp/package-root install 16655714Skris 16755714Skris (or specify "--install_prefix=/tmp/package-root" as a configure 16855714Skris option). The specified prefix will be prepended to all 16955714Skris installation target filenames. 17055714Skris 17155714Skris 17255714Skris NOTE: The header files used to reside directly in the include 17355714Skris directory, but have now been moved to include/openssl so that 17455714Skris OpenSSL can co-exist with other libraries which use some of the 17555714Skris same filenames. This means that applications that use OpenSSL 17655714Skris should now use C preprocessor directives of the form 17755714Skris 17855714Skris #include <openssl/ssl.h> 17955714Skris 18055714Skris instead of "#include <ssl.h>", which was used with library versions 18155714Skris up to OpenSSL 0.9.2b. 18255714Skris 18355714Skris If you install a new version of OpenSSL over an old library version, 18455714Skris you should delete the old header files in the include directory. 18555714Skris 18655714Skris Compatibility issues: 18755714Skris 18855714Skris * COMPILING existing applications 18955714Skris 19055714Skris To compile an application that uses old filenames -- e.g. 19155714Skris "#include <ssl.h>" --, it will usually be enough to find 19255714Skris the CFLAGS definition in the application's Makefile and 19355714Skris add a C option such as 19455714Skris 19555714Skris -I/usr/local/ssl/include/openssl 19655714Skris 19755714Skris to it. 19855714Skris 19955714Skris But don't delete the existing -I option that points to 20055714Skris the ..../include directory! Otherwise, OpenSSL header files 20155714Skris could not #include each other. 20255714Skris 20355714Skris * WRITING applications 20455714Skris 20555714Skris To write an application that is able to handle both the new 20655714Skris and the old directory layout, so that it can still be compiled 20755714Skris with library versions up to OpenSSL 0.9.2b without bothering 20855714Skris the user, you can proceed as follows: 20955714Skris 21055714Skris - Always use the new filename of OpenSSL header files, 21155714Skris e.g. #include <openssl/ssl.h>. 21255714Skris 21355714Skris - Create a directory "incl" that contains only a symbolic 21455714Skris link named "openssl", which points to the "include" directory 21555714Skris of OpenSSL. 21655714Skris For example, your application's Makefile might contain the 21755714Skris following rule, if OPENSSLDIR is a pathname (absolute or 21855714Skris relative) of the directory where OpenSSL resides: 21955714Skris 22055714Skris incl/openssl: 22155714Skris -mkdir incl 22255714Skris cd $(OPENSSLDIR) # Check whether the directory really exists 22355714Skris -ln -s `cd $(OPENSSLDIR); pwd`/include incl/openssl 22455714Skris 22555714Skris You will have to add "incl/openssl" to the dependencies 22655714Skris of those C files that include some OpenSSL header file. 22755714Skris 22855714Skris - Add "-Iincl" to your CFLAGS. 22955714Skris 23055714Skris With these additions, the OpenSSL header files will be available 23155714Skris under both name variants if an old library version is used: 23255714Skris Your application can reach them under names like <openssl/foo.h>, 23355714Skris while the header files still are able to #include each other 23455714Skris with names of the form <foo.h>. 23555714Skris 23655714Skris 23755714Skris Note on multi-threading 23855714Skris ----------------------- 23955714Skris 24055714Skris For some systems, the OpenSSL Configure script knows what compiler options 24155714Skris are needed to generate a library that is suitable for multi-threaded 24255714Skris applications. On these systems, support for multi-threading is enabled 24355714Skris by default; use the "no-threads" option to disable (this should never be 24455714Skris necessary). 24555714Skris 24655714Skris On other systems, to enable support for multi-threading, you will have 24755714Skris to specify at least two options: "threads", and a system-dependent option. 24855714Skris (The latter is "-D_REENTRANT" on various systems.) The default in this 24955714Skris case, obviously, is not to include support for multi-threading (but 25055714Skris you can still use "no-threads" to suppress an annoying warning message 25155714Skris from the Configure script.) 25255714Skris 25355714Skris 25455714Skris-------------------------------------------------------------------------------- 25555714SkrisThe orignal Unix build instructions from SSLeay follow. 25655714SkrisNote: some of this may be out of date and no longer applicable 25755714Skris-------------------------------------------------------------------------------- 25855714Skris 25955714Skris# When bringing the SSLeay distribution back from the evil intel world 26055714Skris# of Windows NT, do the following to make it nice again under unix :-) 26155714Skris# You don't normally need to run this. 26255714Skrissh util/fixNT.sh # This only works for NT now - eay - 21-Jun-1996 26355714Skris 26455714Skris# If you have perl, and it is not in /usr/local/bin, you can run 26555714Skrisperl util/perlpath.pl /new/path 26655714Skris# and this will fix the paths in all the scripts. DO NOT put 26755714Skris# /new/path/perl, just /new/path. The build 26855714Skris# environment always run scripts as 'perl perlscript.pl' but some of the 26955714Skris# 'applications' are easier to usr with the path fixed. 27055714Skris 27155714Skris# Edit crypto/cryptlib.h, tools/c_rehash, and Makefile.ssl 27255714Skris# to set the install locations if you don't like 27355714Skris# the default location of /usr/local/ssl 27455714Skris# Do this by running 27555714Skrisperl util/ssldir.pl /new/ssl/home 27655714Skris# if you have perl, or by hand if not. 27755714Skris 27855714Skris# If things have been stuffed up with the sym links, run 27955714Skrismake -f Makefile.ssl links 28055714Skris# This will re-populate lib/include with symlinks and for each 28155714Skris# directory, link Makefile to Makefile.ssl 28255714Skris 28355714Skris# Setup the machine dependent stuff for the top level makefile 28455714Skris# and some select .h files 28555714Skris# If you don't have perl, this will bomb, in which case just edit the 28655714Skris# top level Makefile.ssl 28755714Skris./Configure 'system type' 28855714Skris 28955714Skris# The 'Configure' command contains default configuration parameters 29055714Skris# for lots of machines. Configure edits 5 lines in the top level Makefile 29155714Skris# It modifies the following values in the following files 29255714SkrisMakefile.ssl CC CFLAG EX_LIBS BN_MULW 29355714Skriscrypto/des/des.h DES_LONG 29455714Skriscrypto/des/des_locl.h DES_PTR 29555714Skriscrypto/md2/md2.h MD2_INT 29655714Skriscrypto/rc4/rc4.h RC4_INT 29755714Skriscrypto/rc4/rc4_enc.c RC4_INDEX 29855714Skriscrypto/rc2/rc2.h RC2_INT 29955714Skriscrypto/bf/bf_locl.h BF_INT 30055714Skriscrypto/idea/idea.h IDEA_INT 30155714Skriscrypto/bn/bn.h BN_LLONG (and defines one of SIXTY_FOUR_BIT, 30255714Skris SIXTY_FOUR_BIT_LONG, THIRTY_TWO_BIT, 30355714Skris SIXTEEN_BIT or EIGHT_BIT) 30455714SkrisPlease remember that all these files are actually copies of the file with 30555714Skrisa .org extention. So if you change crypto/des/des.h, the next time 30655714Skrisyou run Configure, it will be runover by a 'configured' version of 30755714Skriscrypto/des/des.org. So to make the changer the default, change the .org 30855714Skrisfiles. The reason these files have to be edited is because most of 30955714Skristhese modifications change the size of fundamental data types. 31055714SkrisWhile in theory this stuff is optional, it often makes a big 31155714Skrisdifference in performance and when using assember, it is importaint 31255714Skrisfor the 'Bignum bits' match those required by the assember code. 31355714SkrisA warning for people using gcc with sparc cpu's. Gcc needs the -mv8 31455714Skrisflag to use the hardware multiply instruction which was not present in 31555714Skrisearlier versions of the sparc CPU. I define it by default. If you 31655714Skrishave an old sparc, and it crashes, try rebuilding with this flag 31755714Skrisremoved. I am leaving this flag on by default because it makes 31855714Skristhings run 4 times faster :-) 31955714Skris 32055714Skris# clean out all the old stuff 32155714Skrismake clean 32255714Skris 32355714Skris# Do a make depend only if you have the makedepend command installed 32455714Skris# This is not needed but it does make things nice when developing. 32555714Skrismake depend 32655714Skris 32755714Skris# make should build everything 32855714Skrismake 32955714Skris 33055714Skris# fix up the demo certificate hash directory if it has been stuffed up. 33155714Skrismake rehash 33255714Skris 33355714Skris# test everything 33455714Skrismake test 33555714Skris 33655714Skris# install the lot 33755714Skrismake install 33855714Skris 33955714Skris# It is worth noting that all the applications are built into the one 34055714Skris# program, ssleay, which is then has links from the other programs 34155714Skris# names to it. 34255714Skris# The applicatons can be built by themselves, just don't define the 34355714Skris# 'MONOLITH' flag. So to build the 'enc' program stand alone, 34455714Skrisgcc -O2 -Iinclude apps/enc.c apps/apps.c libcrypto.a 34555714Skris 34655714Skris# Other useful make options are 34755714Skrismake makefile.one 34855714Skris# which generate a 'makefile.one' file which will build the complete 34955714Skris# SSLeay distribution with temp. files in './tmp' and 'installable' files 35055714Skris# in './out' 35155714Skris 35255714Skris# Have a look at running 35355714Skrisperl util/mk1mf.pl help 35455714Skris# this can be used to generate a single makefile and is about the only 35555714Skris# way to generate makefiles for windows. 35655714Skris 35755714Skris# There is actually a final way of building SSLeay. 35855714Skrisgcc -O2 -c -Icrypto -Iinclude crypto/crypto.c 35955714Skrisgcc -O2 -c -Issl -Iinclude ssl/ssl.c 36055714Skris# and you now have the 2 libraries as single object files :-). 36155714Skris# If you want to use the assember code for your particular platform 36255714Skris# (DEC alpha/x86 are the main ones, the other assember is just the 36355714Skris# output from gcc) you will need to link the assember with the above generated 36455714Skris# object file and also do the above compile as 36555714Skrisgcc -O2 -DBN_ASM -c -Icrypto -Iinclude crypto/crypto.c 36655714Skris 36755714SkrisThis last option is probably the best way to go when porting to another 36855714Skrisplatform or building shared libraries. It is not good for development so 36955714SkrisI don't normally use it. 37055714Skris 37155714SkrisTo build shared libararies under unix, have a look in shlib, basically 37255714Skrisyou are on your own, but it is quite easy and all you have to do 37355714Skrisis compile 2 (or 3) files. 37455714Skris 37555714SkrisFor mult-threading, have a read of doc/threads.doc. Again it is quite 37655714Skriseasy and normally only requires some extra callbacks to be defined 37755714Skrisby the application. 37855714SkrisThe examples for solaris and windows NT/95 are in the mt directory. 37955714Skris 38055714Skrishave fun 38155714Skris 38255714Skriseric 25-Jun-1997 38355714Skris 38455714SkrisIRIX 5.x will build as a 32 bit system with mips1 assember. 38555714SkrisIRIX 6.x will build as a 64 bit system with mips3 assember. It conforms 38655714Skristo n32 standards. In theory you can compile the 64 bit assember under 38755714SkrisIRIX 5.x but you will have to have the correct system software installed. 388