diff options
Diffstat (limited to 'crypto/openssl/INSTALL')
| -rw-r--r-- | crypto/openssl/INSTALL | 387 |
1 files changed, 387 insertions, 0 deletions
diff --git a/crypto/openssl/INSTALL b/crypto/openssl/INSTALL new file mode 100644 index 0000000..6066fdd --- /dev/null +++ b/crypto/openssl/INSTALL @@ -0,0 +1,387 @@ + + INSTALLATION ON THE UNIX PLATFORM + --------------------------------- + + [See INSTALL.W32 for instructions for compiling OpenSSL on Windows systems, + and INSTALL.VMS for installing on OpenVMS systems.] + + To install OpenSSL, you will need: + + * Perl 5 + * an ANSI C compiler + * a supported Unix operating system + + Quick Start + ----------- + + If you want to just get on with it, do: + + $ ./config + $ make + $ 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, + run config like this: + + $ ./config --prefix=/usr/local --openssldir=/usr/local/openssl + + + Configuration Options + --------------------- + + There are several options to ./config 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. + + rsaref Build with RSADSI's RSAREF toolkit (this assumes that + librsaref.a is in the library search path). + + 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-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). + + no-<cipher> Build without the specified cipher (bf, cast, des, dh, dsa, + hmac, md2, md5, mdc2, rc2, rc4, rc5, rsa, sha). + The crypto/<cipher> directory can be removed after running + "make depend". + + -Dxxx, -lxxx, -Lxxx, -fxxx, -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. + + + Installation in Detail + ---------------------- + + 1a. Configure OpenSSL for your operation system automatically: + + $ ./config [options] + + This guesses at your operating system (and compiler, if necessary) and + configures OpenSSL based on this guess. Run ./config -t 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. + + On some systems, you can include debugging information as follows: + + $ ./config -d [options] + + 1b. Configure OpenSSL for your operating system manually + + OpenSSL knows about a range of different operating system, hardware and + compiler combinations. To see the ones it knows about, run + + $ ./Configure + + Pick a suitable name from the list that matches your system. For most + operating systems there is a choice between using "cc" or "gcc". When + you have identified your system (and if necessary compiler) use this name + as the argument to ./Configure. For example, a "linux-elf" user would + run: + + $ ./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. The + generic configurations "cc" or "gcc" should usually work. + + Configure creates the file Makefile.ssl from Makefile.org and + defines various macros in crypto/opensslconf.h (generated from + crypto/opensslconf.h.in). + + 2. Build OpenSSL by running: + + $ make + + This will build the OpenSSL libraries (libcrypto.a and libssl.a) and the + OpenSSL binary ("openssl"). The libraries will be built in the top-level + directory, and the binary will be in the "apps" directory. + + If "make" fails, please report the problem to <openssl-bugs@openssl.org>. + Include the output of "./config -t" and the OpenSSL version + number in your message. + + [If you encounter assembler error messages, try the "no-asm" + configuration option as an immediate fix. Note that on Solaris x86 + (not on Sparcs!) you may have to install the GNU assembler to use + OpenSSL assembler code -- /usr/ccs/bin/as won't do.] + + 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 test + + If a test fails, try removing any compiler optimization flags from + the CFLAGS line in Makefile.ssl and run "make clean; make". Please + send a bug report to <openssl-bugs@openssl.org>, including the + output of "openssl version -a" and of the failed test. + + 4. If everything tests ok, install OpenSSL with + + $ make install + + This will create the installation directory (if it does not exist) and + then the following subdirectories: + + certs Initially empty, this is the default location + for certificate files. + misc Various scripts. + private Initially empty, this is the default location + for private key files. + + If you didn't chose a different installation prefix, the + following additional subdirectories will be created: + + 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. + + 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 + directory, but have now been moved to include/openssl so that + OpenSSL can co-exist with other libraries which use some of the + same filenames. This means that applications that use OpenSSL + should now use C preprocessor directives of the form + + #include <openssl/ssl.h> + + instead of "#include <ssl.h>", which was used with library versions + up to OpenSSL 0.9.2b. + + If you install a new version of OpenSSL over an old library version, + you should delete the old header files in the include directory. + + Compatibility issues: + + * COMPILING existing applications + + To compile an application that uses old filenames -- e.g. + "#include <ssl.h>" --, it will usually be enough to find + the CFLAGS definition in the application's Makefile and + add a C option such as + + -I/usr/local/ssl/include/openssl + + to it. + + But don't delete the existing -I option that points to + the ..../include directory! Otherwise, OpenSSL header files + could not #include each other. + + * WRITING applications + + To write an application that is able to handle both the new + and the old directory layout, so that it can still be compiled + with library versions up to OpenSSL 0.9.2b without bothering + the user, you can proceed as follows: + + - Always use the new filename of OpenSSL header files, + e.g. #include <openssl/ssl.h>. + + - Create a directory "incl" that contains only a symbolic + link named "openssl", which points to the "include" directory + of OpenSSL. + For example, your application's Makefile might contain the + following rule, if OPENSSLDIR is a pathname (absolute or + relative) of the directory where OpenSSL resides: + + incl/openssl: + -mkdir incl + cd $(OPENSSLDIR) # Check whether the directory really exists + -ln -s `cd $(OPENSSLDIR); pwd`/include incl/openssl + + You will have to add "incl/openssl" to the dependencies + of those C files that include some OpenSSL header file. + + - Add "-Iincl" to your CFLAGS. + + With these additions, the OpenSSL header files will be available + under both name variants if an old library version is used: + Your application can reach them under names like <openssl/foo.h>, + while the header files still are able to #include each other + with names of the form <foo.h>. + + + 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.) + + +-------------------------------------------------------------------------------- +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. |
