X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=blobdiff_plain;f=INSTALL;h=9173a4efd98a1f3166a996c5f73a130a10f0bcf6;hp=e5388b16cd97d2b9b2dd151b4fe0e81d2cc72b98;hb=e113c9c59dcb419dd00525cec431edb854a6c897;hpb=4fd53220b66e5c6476e9d7dd3b43977d4bb02e37 diff --git a/INSTALL b/INSTALL index e5388b16cd..9173a4efd9 100644 --- a/INSTALL +++ b/INSTALL @@ -2,12 +2,20 @@ INSTALLATION ON THE UNIX PLATFORM --------------------------------- - [For instructions for compiling OpenSSL on Windows systems, see INSTALL.W32]. + [Installation on DOS (with djgpp), Windows, OpenVMS, MacOS (before MacOS X) + and NetWare is described in INSTALL.DJGPP, INSTALL.W32, INSTALL.VMS, + INSTALL.MacOS and INSTALL.NW. + + This document describes installation on operating systems in the Unix + family.] To install OpenSSL, you will need: - * Perl 5 - * ANSI C compiler + * make + * Perl 5 with core modules (see 'Note on Perl' further down) + * an ANSI C compiler + * a development environment in form of development libraries and C + header files * a supported Unix operating system Quick Start @@ -15,40 +23,103 @@ If you want to just get on with it, do: - $ ./config [if this fails, go to step 1b below] + $ ./config $ make - $ make rehash $ make test $ make install + [If any of these steps fails, see section Installation in Detail below.] + This will build and install OpenSSL in the default location, which is (for historical reasons) /usr/local/ssl. If you want to install it anywhere else, - do this after running `./config': + run config like this: + + $ ./config --prefix=/usr/local --openssldir=/usr/local/openssl + + + Configuration Options + --------------------- + + There are several options to ./config (or ./Configure) to customize + the build: + + --prefix=DIR Install in DIR/bin, DIR/lib, DIR/include/openssl. + Configuration files used by OpenSSL will be in DIR/ssl + or the directory specified by --openssldir. + + --openssldir=DIR Directory for OpenSSL files. If no prefix is specified, + the library files and binaries are also installed there. + + no-threads Don't try to build with support for multi-threaded + applications. + + threads Build with support for multi-threaded applications. + This will usually require additional system-dependent options! + See "Note on multi-threading" below. + + no-zlib Don't try to build with support for zlib compression and + decompression. + + zlib Build with support for zlib compression/decompression. - $ perl util/ssldir.pl /new/install/path + zlib-dynamic Like "zlib", but has OpenSSL load the zlib library dynamically + when needed. This is only supported on systems where loading + of shared libraries is supported. This is the default choice. - There are several options to ./config to customize the build: + no-shared Don't try to create shared libraries. - rsaref Build with RSADSI's RSAREF toolkit. - no-asm Build with no assembler code. - 386 Use the 80386 instruction set only (the default x86 code is - more efficient, but requires at least a 486). + shared In addition to the usual static libraries, create shared + libraries on platforms where it's supported. See "Note on + shared libraries" below. + + no-asm Do not use assembler code. + + 386 Use the 80386 instruction set only (the default x86 code is + more efficient, but requires at least a 486). Note: Use + compiler flags for any other CPU specific configuration, + e.g. "-m32" to build x86 code on an x64 system. + + no-sse2 Exclude SSE2 code pathes. Normally SSE2 extension is + detected at run-time, but the decision whether or not the + machine code will be executed is taken solely on CPU + capability vector. This means that if you happen to run OS + kernel which does not support SSE2 extension on Intel P4 + processor, then your application might be exposed to + "illegal instruction" exception. There might be a way + to enable support in kernel, e.g. FreeBSD kernel can be + compiled with CPU_ENABLE_SSE, and there is a way to + disengage SSE2 code pathes upon application start-up, + but if you aim for wider "audience" running such kernel, + consider no-sse2. Both 386 and no-asm options above imply + no-sse2. + + no- Build without the specified cipher (bf, cast, des, dh, dsa, + hmac, md2, md5, mdc2, rc2, rc4, rc5, rsa, sha). + The crypto/ directory can be removed after running + "make depend". + + -Dxxx, -lxxx, -Lxxx, -fxxx, -mXXX, -Kxxx These system specific options will + be passed through to the compiler to allow you to + define preprocessor symbols, specify additional libraries, + library directories or other compiler options. - If anything goes wrong, follow the detailed instructions below. If your - operating system is not (yet) supported by OpenSSL, see the section on - porting to a new system. Installation in Detail ---------------------- 1a. Configure OpenSSL for your operation system automatically: - $ ./config + $ ./config [options] This guesses at your operating system (and compiler, if necessary) and - configures OpenSSL based on this guess. Check the first line of output to - see if it guessed correctly. If it did not get it correct or you want to - use a different compiler then go to step 1b. Otherwise go to step 2. + configures OpenSSL based on this guess. Run ./config -t to see + if it guessed correctly. If you want to use a different compiler, you + are cross-compiling for another platform, or the ./config guess was + wrong for other reasons, go to step 1b. Otherwise go to step 2. + + On some systems, you can include debugging information as follows: + + $ ./config -d [options] 1b. Configure OpenSSL for your operating system manually @@ -63,29 +134,18 @@ as the argument to ./Configure. For example, a "linux-elf" user would run: - $ ./Configure linux-elf + $ ./Configure linux-elf [options] If your system is not available, you will have to edit the Configure - program and add the correct configuration for your system. + program and add the correct configuration for your system. The + generic configurations "cc" or "gcc" should usually work on 32 bit + systems. - Configure creates the Makefile.ssl from Makefile.org and defines - various macros in crypto/opensslconf.h (generated from + Configure creates the file Makefile.ssl from Makefile.org and + defines various macros in crypto/opensslconf.h (generated from crypto/opensslconf.h.in). - 2. Set the install directory - - If the install directory will be the default of /usr/local/ssl, skip to - the next stage. Otherwise, run - - $ perl util/ssldir.pl /new/install/path - - This configures the installation location into the "install" target of - the top-level Makefile, and also updates some defines in an include file - so that the default certificate directory is under the proper - installation directory. It also updates a few utility files used in the - build process. - - 3. Build OpenSSL by running: + 2. Build OpenSSL by running: $ make @@ -93,31 +153,96 @@ OpenSSL binary ("openssl"). The libraries will be built in the top-level directory, and the binary will be in the "apps" directory. - 4. After a successful build, the libraries should be tested. Run: + If "make" fails, look at the output. There may be reasons for + the failure that aren't problems in OpenSSL itself (like missing + standard headers). If it is a problem with OpenSSL itself, please + report the problem to (note that your + message will be recorded in the request tracker publicly readable + via http://www.openssl.org/support/rt.html and will be forwarded to a + public mailing list). Include the output of "make report" in your message. + Please check out the request tracker. Maybe the bug was already + reported or has already been fixed. + + [If you encounter assembler error messages, try the "no-asm" + configuration option as an immediate fix.] + + Compiling parts of OpenSSL with gcc and others with the system + compiler will result in unresolved symbols on some systems. + + 3. After a successful build, the libraries should be tested. Run: - $ make rehash $ make test - (The first line makes the test certificates in the "certs" directory - accessable via an hash name, which is required for some of the tests). + If some tests fail, look at the output. There may be reasons for + the failure that isn't a problem in OpenSSL itself (like a + malfunction with Perl). You may want increased verbosity, that + can be accomplished like this: + + $ HARNESS_VERBOSE=yes make test + + Also, you will find logs for all commands the tests have executed + in logs, test/test_*.log, one for each individual test. + + If you want to run just one or a few specific tests, you can use + the make variable TESTS to specify them, like this: + + $ make TESTS='test_rsa test_dsa' test + + And of course, you can combine: + + $ HARNESS_VERBOSE=yes make TESTS='test_rsa test_dsa' test + + You can find the list of available tests like this: + + $ make list-tests - 5. If everything tests ok, install OpenSSL with + If you find a problem with OpenSSL itself, try removing any + compiler optimization flags from the CFLAG line in Makefile and + run "make clean; make". + + Please send a bug report to , and when + you do, please run the following and include the output in your + report: + + $ make report + + 4. If everything tests ok, install OpenSSL with $ make install This will create the installation directory (if it does not exist) and - then create the following subdirectories: + then the following subdirectories: + + certs Initially empty, this is the default location + for certificate files. + man/man1 Manual pages for the 'openssl' command line tool + man/man3 Manual pages for the libraries (very incomplete) + misc Various scripts. + private Initially empty, this is the default location + for private key files. + + If you didn't choose a different installation prefix, the + following additional subdirectories will be created: - bin Contains the openssl binary and a few other - utility programs. - include Contains the header files needed if you want to - compile programs with libcrypto or libssl. - lib Contains the library files themselves and the - OpenSSL configuration file "openssl.cnf". - certs Initially empty, this is the default location - for certificate files. - private Initially empty, this is the default location - for private key files. + bin Contains the openssl binary and a few other + utility programs. + include/openssl Contains the header files needed if you want to + compile programs with libcrypto or libssl. + lib Contains the OpenSSL library files themselves. + + Use "make install_sw" to install the software without documentation, + and "install_docs_html" to install HTML renditions of the manual + pages. + + Package builders who want to configure the library for standard + locations, but have the package installed somewhere else so that + it can easily be packaged, can use + + $ make INSTALL_PREFIX=/tmp/package-root install + + (or specify "--install_prefix=/tmp/package-root" as a configure + option). The specified prefix will be prepended to all + installation target filenames. NOTE: The header files used to reside directly in the include @@ -185,138 +310,89 @@ with names of the form . - --------------------------------------------------------------------------------- -The orignal Unix build instructions from SSLeay follow. -Note: some of this may be out of date and no longer applicable --------------------------------------------------------------------------------- - -# When bringing the SSLeay distribution back from the evil intel world -# of Windows NT, do the following to make it nice again under unix :-) -# You don't normally need to run this. -sh util/fixNT.sh # This only works for NT now - eay - 21-Jun-1996 - -# If you have perl, and it is not in /usr/local/bin, you can run -perl util/perlpath.pl /new/path -# and this will fix the paths in all the scripts. DO NOT put -# /new/path/perl, just /new/path. The build -# environment always run scripts as 'perl perlscript.pl' but some of the -# 'applications' are easier to usr with the path fixed. - -# Edit crypto/cryptlib.h, tools/c_rehash, and Makefile.ssl -# to set the install locations if you don't like -# the default location of /usr/local/ssl -# Do this by running -perl util/ssldir.pl /new/ssl/home -# if you have perl, or by hand if not. - -# If things have been stuffed up with the sym links, run -make -f Makefile.ssl links -# This will re-populate lib/include with symlinks and for each -# directory, link Makefile to Makefile.ssl - -# Setup the machine dependent stuff for the top level makefile -# and some select .h files -# If you don't have perl, this will bomb, in which case just edit the -# top level Makefile.ssl -./Configure 'system type' - -# The 'Configure' command contains default configuration parameters -# for lots of machines. Configure edits 5 lines in the top level Makefile -# It modifies the following values in the following files -Makefile.ssl CC CFLAG EX_LIBS BN_MULW -crypto/des/des.h DES_LONG -crypto/des/des_locl.h DES_PTR -crypto/md2/md2.h MD2_INT -crypto/rc4/rc4.h RC4_INT -crypto/rc4/rc4_enc.c RC4_INDEX -crypto/rc2/rc2.h RC2_INT -crypto/bf/bf_locl.h BF_INT -crypto/idea/idea.h IDEA_INT -crypto/bn/bn.h BN_LLONG (and defines one of SIXTY_FOUR_BIT, - SIXTY_FOUR_BIT_LONG, THIRTY_TWO_BIT, - SIXTEEN_BIT or EIGHT_BIT) -Please remember that all these files are actually copies of the file with -a .org extention. So if you change crypto/des/des.h, the next time -you run Configure, it will be runover by a 'configured' version of -crypto/des/des.org. So to make the changer the default, change the .org -files. The reason these files have to be edited is because most of -these modifications change the size of fundamental data types. -While in theory this stuff is optional, it often makes a big -difference in performance and when using assember, it is importaint -for the 'Bignum bits' match those required by the assember code. -A warning for people using gcc with sparc cpu's. Gcc needs the -mv8 -flag to use the hardware multiply instruction which was not present in -earlier versions of the sparc CPU. I define it by default. If you -have an old sparc, and it crashes, try rebuilding with this flag -removed. I am leaving this flag on by default because it makes -things run 4 times faster :-) - -# clean out all the old stuff -make clean - -# Do a make depend only if you have the makedepend command installed -# This is not needed but it does make things nice when developing. -make depend - -# make should build everything -make - -# fix up the demo certificate hash directory if it has been stuffed up. -make rehash - -# test everything -make test - -# install the lot -make install - -# It is worth noting that all the applications are built into the one -# program, ssleay, which is then has links from the other programs -# names to it. -# The applicatons can be built by themselves, just don't define the -# 'MONOLITH' flag. So to build the 'enc' program stand alone, -gcc -O2 -Iinclude apps/enc.c apps/apps.c libcrypto.a - -# Other useful make options are -make makefile.one -# which generate a 'makefile.one' file which will build the complete -# SSLeay distribution with temp. files in './tmp' and 'installable' files -# in './out' - -# Have a look at running -perl util/mk1mf.pl help -# this can be used to generate a single makefile and is about the only -# way to generate makefiles for windows. - -# There is actually a final way of building SSLeay. -gcc -O2 -c -Icrypto -Iinclude crypto/crypto.c -gcc -O2 -c -Issl -Iinclude ssl/ssl.c -# and you now have the 2 libraries as single object files :-). -# If you want to use the assember code for your particular platform -# (DEC alpha/x86 are the main ones, the other assember is just the -# output from gcc) you will need to link the assember with the above generated -# object file and also do the above compile as -gcc -O2 -DBN_ASM -c -Icrypto -Iinclude crypto/crypto.c - -This last option is probably the best way to go when porting to another -platform or building shared libraries. It is not good for development so -I don't normally use it. - -To build shared libararies under unix, have a look in shlib, basically -you are on your own, but it is quite easy and all you have to do -is compile 2 (or 3) files. - -For mult-threading, have a read of doc/threads.doc. Again it is quite -easy and normally only requires some extra callbacks to be defined -by the application. -The examples for solaris and windows NT/95 are in the mt directory. - -have fun - -eric 25-Jun-1997 - -IRIX 5.x will build as a 32 bit system with mips1 assember. -IRIX 6.x will build as a 64 bit system with mips3 assember. It conforms -to n32 standards. In theory you can compile the 64 bit assember under -IRIX 5.x but you will have to have the correct system software installed. + Note on Perl + ------------ + + For our scripts, we rely quite a bit on Perl, and increasingly on + some core Perl modules. These Perl modules are part of the Perl + source, so if you build Perl on your own, you should be set. + + However, if you install Perl as binary packages, the outcome might + differ, and you may have to check that you do get the core modules + installed properly. We do not claim to know them all, but experience + has told us the following: + + - on Linux distributions based on Debian, the package 'perl' will + install the core Perl modules as well, so you will be fine. + - on Linux distributions based on RPMs, you will need to install + 'perl-core' rather than just 'perl'. + + It is highly recommended that you have at least Perl version 5.12 + installed. + + Note on multi-threading + ----------------------- + + For some systems, the OpenSSL Configure script knows what compiler options + are needed to generate a library that is suitable for multi-threaded + applications. On these systems, support for multi-threading is enabled + by default; use the "no-threads" option to disable (this should never be + necessary). + + On other systems, to enable support for multi-threading, you will have + to specify at least two options: "threads", and a system-dependent option. + (The latter is "-D_REENTRANT" on various systems.) The default in this + case, obviously, is not to include support for multi-threading (but + you can still use "no-threads" to suppress an annoying warning message + from the Configure script.) + + + Note on shared libraries + ------------------------ + + Shared libraries have certain caveats. Binary backward compatibility + can't be guaranteed before OpenSSL version 1.0. The only reason to + use them would be to conserve memory on systems where several programs + are using OpenSSL. + + For some systems, the OpenSSL Configure script knows what is needed to + build shared libraries for libcrypto and libssl. On these systems, + the shared libraries are currently not created by default, but giving + the option "shared" will get them created. This method supports Makefile + targets for shared library creation, like linux-shared. Those targets + can currently be used on their own just as well, but this is expected + to change in future versions of OpenSSL. + + Note on random number generation + -------------------------------- + + Availability of cryptographically secure random numbers is required for + secret key generation. OpenSSL provides several options to seed the + internal PRNG. If not properly seeded, the internal PRNG will refuse + to deliver random bytes and a "PRNG not seeded error" will occur. + On systems without /dev/urandom (or similar) device, it may be necessary + to install additional support software to obtain random seed. + Please check out the manual pages for RAND_add(), RAND_bytes(), RAND_egd(), + and the FAQ for more information. + + Note on support for multiple builds + ----------------------------------- + + OpenSSL is usually built in its source tree. Unfortunately, this doesn't + support building for multiple platforms from the same source tree very well. + It is however possible to build in a separate tree through the use of lots + of symbolic links, which should be prepared like this: + + mkdir -p objtree/"`uname -s`-`uname -r`-`uname -m`" + cd objtree/"`uname -s`-`uname -r`-`uname -m`" + (cd $OPENSSL_SOURCE; find . -type f) | while read F; do + mkdir -p `dirname $F` + rm -f $F; ln -s $OPENSSL_SOURCE/$F $F + echo $F '->' $OPENSSL_SOURCE/$F + done + make -f Makefile.org clean + + OPENSSL_SOURCE is an environment variable that contains the absolute (this + is important!) path to the OpenSSL source tree. + + Also, operations like 'make update' should still be made in the source tree.