INSTALL revision 314125
155714Skris 255714Skris INSTALLATION ON THE UNIX PLATFORM 355714Skris --------------------------------- 455714Skris 5160814Ssimon [Installation on DOS (with djgpp), Windows, OpenVMS, MacOS (before MacOS X) 6160814Ssimon and NetWare is described in INSTALL.DJGPP, INSTALL.W32, INSTALL.VMS, 7160814Ssimon INSTALL.MacOS and INSTALL.NW. 8160814Ssimon 9109998Smarkm This document describes installation on operating systems in the Unix 10109998Smarkm family.] 1155714Skris 1255714Skris To install OpenSSL, you will need: 1355714Skris 1479998Skris * make 1555714Skris * Perl 5 1655714Skris * an ANSI C compiler 1779998Skris * a development environment in form of development libraries and C 1879998Skris header files 1955714Skris * a supported Unix operating system 2055714Skris 2155714Skris Quick Start 2255714Skris ----------- 2355714Skris 2455714Skris If you want to just get on with it, do: 2555714Skris 2655714Skris $ ./config 2755714Skris $ make 2855714Skris $ make test 2955714Skris $ make install 3055714Skris 3155714Skris [If any of these steps fails, see section Installation in Detail below.] 3255714Skris 3355714Skris This will build and install OpenSSL in the default location, which is (for 3455714Skris historical reasons) /usr/local/ssl. If you want to install it anywhere else, 3555714Skris run config like this: 3655714Skris 3755714Skris $ ./config --prefix=/usr/local --openssldir=/usr/local/openssl 3855714Skris 3955714Skris 4055714Skris Configuration Options 4155714Skris --------------------- 4255714Skris 4359191Skris There are several options to ./config (or ./Configure) to customize 4459191Skris the build: 4555714Skris 4655714Skris --prefix=DIR Install in DIR/bin, DIR/lib, DIR/include/openssl. 4755714Skris Configuration files used by OpenSSL will be in DIR/ssl 4855714Skris or the directory specified by --openssldir. 4955714Skris 5055714Skris --openssldir=DIR Directory for OpenSSL files. If no prefix is specified, 5155714Skris the library files and binaries are also installed there. 5255714Skris 5355714Skris no-threads Don't try to build with support for multi-threaded 5455714Skris applications. 5555714Skris 5655714Skris threads Build with support for multi-threaded applications. 5755714Skris This will usually require additional system-dependent options! 5855714Skris See "Note on multi-threading" below. 5955714Skris 60109998Smarkm no-zlib Don't try to build with support for zlib compression and 61109998Smarkm decompression. 62109998Smarkm 63109998Smarkm zlib Build with support for zlib compression/decompression. 64109998Smarkm 65109998Smarkm zlib-dynamic Like "zlib", but has OpenSSL load the zlib library dynamically 66109998Smarkm when needed. This is only supported on systems where loading 67109998Smarkm of shared libraries is supported. This is the default choice. 68109998Smarkm 6968651Skris no-shared Don't try to create shared libraries. 7068651Skris 7168651Skris shared In addition to the usual static libraries, create shared 7268651Skris libraries on platforms where it's supported. See "Note on 7368651Skris shared libraries" below. 7468651Skris 7555714Skris no-asm Do not use assembler code. 7655714Skris 77314125Sdelphij 386 In 32-bit x86 builds, when generating assembly modules, 78314125Sdelphij use the 80386 instruction set only (the default x86 code 79314125Sdelphij is more efficient, but requires at least a 486). Note: 80314125Sdelphij This doesn't affect code generated by compiler, you're 81314125Sdelphij likely to complement configuration command line with 82314125Sdelphij suitable compiler-specific option. 8355714Skris 84314125Sdelphij no-sse2 Exclude SSE2 code paths from 32-bit x86 assembly modules. 85314125Sdelphij Normally SSE2 extension is detected at run-time, but the 86314125Sdelphij decision whether or not the machine code will be executed 87314125Sdelphij is taken solely on CPU capability vector. This means that 88314125Sdelphij if you happen to run OS kernel which does not support SSE2 89314125Sdelphij extension on Intel P4 processor, then your application 90314125Sdelphij might be exposed to "illegal instruction" exception. 91314125Sdelphij There might be a way to enable support in kernel, e.g. 92314125Sdelphij FreeBSD kernel can be compiled with CPU_ENABLE_SSE, and 93314125Sdelphij there is a way to disengage SSE2 code paths upon application 94314125Sdelphij start-up, but if you aim for wider "audience" running 95314125Sdelphij such kernel, consider no-sse2. Both the 386 and 96314125Sdelphij no-asm options imply no-sse2. 97160814Ssimon 9855714Skris no-<cipher> Build without the specified cipher (bf, cast, des, dh, dsa, 9955714Skris hmac, md2, md5, mdc2, rc2, rc4, rc5, rsa, sha). 10055714Skris The crypto/<cipher> directory can be removed after running 10155714Skris "make depend". 10255714Skris 103238405Sjkim -Dxxx, -lxxx, -Lxxx, -fxxx, -mXXX, -Kxxx These system specific options will 10455714Skris be passed through to the compiler to allow you to 10555714Skris define preprocessor symbols, specify additional libraries, 106314125Sdelphij library directories or other compiler options. It might be 107314125Sdelphij worth noting that some compilers generate code specifically 108314125Sdelphij for processor the compiler currently executes on. This is 109314125Sdelphij not necessarily what you might have in mind, since it might 110314125Sdelphij be unsuitable for execution on other, typically older, 111314125Sdelphij processor. Consult your compiler documentation. 11255714Skris 113238405Sjkim -DHAVE_CRYPTODEV Enable the BSD cryptodev engine even if we are not using 114238405Sjkim BSD. Useful if you are running ocf-linux or something 115238405Sjkim similar. Once enabled you can also enable the use of 116238405Sjkim cryptodev digests, which is usually slower unless you have 117238405Sjkim large amounts data. Use -DUSE_CRYPTODEV_DIGESTS to force 118238405Sjkim it. 11955714Skris 12055714Skris Installation in Detail 12155714Skris ---------------------- 12255714Skris 12355714Skris 1a. Configure OpenSSL for your operation system automatically: 12455714Skris 12555714Skris $ ./config [options] 12655714Skris 12755714Skris This guesses at your operating system (and compiler, if necessary) and 12855714Skris configures OpenSSL based on this guess. Run ./config -t to see 12959191Skris if it guessed correctly. If you want to use a different compiler, you 13059191Skris are cross-compiling for another platform, or the ./config guess was 13159191Skris wrong for other reasons, go to step 1b. Otherwise go to step 2. 13255714Skris 13355714Skris On some systems, you can include debugging information as follows: 13455714Skris 13555714Skris $ ./config -d [options] 13655714Skris 13755714Skris 1b. Configure OpenSSL for your operating system manually 13855714Skris 13955714Skris OpenSSL knows about a range of different operating system, hardware and 14055714Skris compiler combinations. To see the ones it knows about, run 14155714Skris 14255714Skris $ ./Configure 14355714Skris 14455714Skris Pick a suitable name from the list that matches your system. For most 14555714Skris operating systems there is a choice between using "cc" or "gcc". When 14655714Skris you have identified your system (and if necessary compiler) use this name 14755714Skris as the argument to ./Configure. For example, a "linux-elf" user would 14855714Skris run: 14955714Skris 15055714Skris $ ./Configure linux-elf [options] 15155714Skris 15255714Skris If your system is not available, you will have to edit the Configure 15355714Skris program and add the correct configuration for your system. The 15459191Skris generic configurations "cc" or "gcc" should usually work on 32 bit 15559191Skris systems. 15655714Skris 157160814Ssimon Configure creates the file Makefile.ssl from Makefile.org and 15855714Skris defines various macros in crypto/opensslconf.h (generated from 15955714Skris crypto/opensslconf.h.in). 16055714Skris 16155714Skris 2. Build OpenSSL by running: 16255714Skris 16355714Skris $ make 16455714Skris 16555714Skris This will build the OpenSSL libraries (libcrypto.a and libssl.a) and the 16655714Skris OpenSSL binary ("openssl"). The libraries will be built in the top-level 16755714Skris directory, and the binary will be in the "apps" directory. 16855714Skris 169314125Sdelphij If the build fails, look at the output. There may be reasons 170314125Sdelphij for the failure that aren't problems in OpenSSL itself (like 171314125Sdelphij missing standard headers). If you are having problems you can 172314125Sdelphij get help by sending an email to the openssl-users email list (see 173314125Sdelphij https://www.openssl.org/community/mailinglists.html for details). If 174314125Sdelphij it is a bug with OpenSSL itself, please open an issue on GitHub, at 175314125Sdelphij https://github.com/openssl/openssl/issues. Please review the existing 176314125Sdelphij ones first; maybe the bug was already reported or has already been 177314125Sdelphij fixed. 17855714Skris 179314125Sdelphij (If you encounter assembler error messages, try the "no-asm" 180314125Sdelphij configuration option as an immediate fix.) 18155714Skris 18255714Skris Compiling parts of OpenSSL with gcc and others with the system 18355714Skris compiler will result in unresolved symbols on some systems. 18455714Skris 18555714Skris 3. After a successful build, the libraries should be tested. Run: 18655714Skris 18755714Skris $ make test 18855714Skris 18968651Skris If a test fails, look at the output. There may be reasons for 19068651Skris the failure that isn't a problem in OpenSSL itself (like a missing 19168651Skris or malfunctioning bc). If it is a problem with OpenSSL itself, 192111147Snectar try removing any compiler optimization flags from the CFLAG line 193160814Ssimon in Makefile.ssl and run "make clean; make". Please send a bug 19468651Skris report to <openssl-bugs@openssl.org>, including the output of 195100936Snectar "make report" in order to be added to the request tracker at 196194206Ssimon http://www.openssl.org/support/rt.html. 19755714Skris 19855714Skris 4. If everything tests ok, install OpenSSL with 19955714Skris 20055714Skris $ make install 20155714Skris 20255714Skris This will create the installation directory (if it does not exist) and 20355714Skris then the following subdirectories: 20455714Skris 20555714Skris certs Initially empty, this is the default location 20655714Skris for certificate files. 20759191Skris man/man1 Manual pages for the 'openssl' command line tool 20859191Skris man/man3 Manual pages for the libraries (very incomplete) 20955714Skris misc Various scripts. 21055714Skris private Initially empty, this is the default location 21155714Skris for private key files. 21255714Skris 21359191Skris If you didn't choose a different installation prefix, the 21455714Skris following additional subdirectories will be created: 21555714Skris 21655714Skris bin Contains the openssl binary and a few other 21755714Skris utility programs. 21855714Skris include/openssl Contains the header files needed if you want to 21955714Skris compile programs with libcrypto or libssl. 22055714Skris lib Contains the OpenSSL library files themselves. 22155714Skris 222238405Sjkim Use "make install_sw" to install the software without documentation, 223238405Sjkim and "install_docs_html" to install HTML renditions of the manual 224238405Sjkim pages. 225238405Sjkim 22655714Skris Package builders who want to configure the library for standard 22755714Skris locations, but have the package installed somewhere else so that 22855714Skris it can easily be packaged, can use 22955714Skris 23055714Skris $ make INSTALL_PREFIX=/tmp/package-root install 23155714Skris 23255714Skris (or specify "--install_prefix=/tmp/package-root" as a configure 23355714Skris option). The specified prefix will be prepended to all 23455714Skris installation target filenames. 23555714Skris 23655714Skris 23755714Skris NOTE: The header files used to reside directly in the include 23855714Skris directory, but have now been moved to include/openssl so that 23955714Skris OpenSSL can co-exist with other libraries which use some of the 24055714Skris same filenames. This means that applications that use OpenSSL 24155714Skris should now use C preprocessor directives of the form 24255714Skris 24355714Skris #include <openssl/ssl.h> 24455714Skris 24555714Skris instead of "#include <ssl.h>", which was used with library versions 24655714Skris up to OpenSSL 0.9.2b. 24755714Skris 24855714Skris If you install a new version of OpenSSL over an old library version, 24955714Skris you should delete the old header files in the include directory. 25055714Skris 25155714Skris Compatibility issues: 25255714Skris 25355714Skris * COMPILING existing applications 25455714Skris 25555714Skris To compile an application that uses old filenames -- e.g. 25655714Skris "#include <ssl.h>" --, it will usually be enough to find 25755714Skris the CFLAGS definition in the application's Makefile and 25855714Skris add a C option such as 25955714Skris 26055714Skris -I/usr/local/ssl/include/openssl 26155714Skris 26255714Skris to it. 26355714Skris 26455714Skris But don't delete the existing -I option that points to 26555714Skris the ..../include directory! Otherwise, OpenSSL header files 26655714Skris could not #include each other. 26755714Skris 26855714Skris * WRITING applications 26955714Skris 27055714Skris To write an application that is able to handle both the new 27155714Skris and the old directory layout, so that it can still be compiled 27255714Skris with library versions up to OpenSSL 0.9.2b without bothering 27355714Skris the user, you can proceed as follows: 27455714Skris 27555714Skris - Always use the new filename of OpenSSL header files, 27655714Skris e.g. #include <openssl/ssl.h>. 27755714Skris 27855714Skris - Create a directory "incl" that contains only a symbolic 27955714Skris link named "openssl", which points to the "include" directory 28055714Skris of OpenSSL. 28155714Skris For example, your application's Makefile might contain the 28255714Skris following rule, if OPENSSLDIR is a pathname (absolute or 28355714Skris relative) of the directory where OpenSSL resides: 28455714Skris 28555714Skris incl/openssl: 28655714Skris -mkdir incl 28755714Skris cd $(OPENSSLDIR) # Check whether the directory really exists 28855714Skris -ln -s `cd $(OPENSSLDIR); pwd`/include incl/openssl 28955714Skris 29055714Skris You will have to add "incl/openssl" to the dependencies 29155714Skris of those C files that include some OpenSSL header file. 29255714Skris 29355714Skris - Add "-Iincl" to your CFLAGS. 29455714Skris 29555714Skris With these additions, the OpenSSL header files will be available 29655714Skris under both name variants if an old library version is used: 29755714Skris Your application can reach them under names like <openssl/foo.h>, 29855714Skris while the header files still are able to #include each other 29955714Skris with names of the form <foo.h>. 30055714Skris 30155714Skris 30255714Skris Note on multi-threading 30355714Skris ----------------------- 30455714Skris 30555714Skris For some systems, the OpenSSL Configure script knows what compiler options 30655714Skris are needed to generate a library that is suitable for multi-threaded 30755714Skris applications. On these systems, support for multi-threading is enabled 30855714Skris by default; use the "no-threads" option to disable (this should never be 30955714Skris necessary). 31055714Skris 31155714Skris On other systems, to enable support for multi-threading, you will have 31255714Skris to specify at least two options: "threads", and a system-dependent option. 31355714Skris (The latter is "-D_REENTRANT" on various systems.) The default in this 31455714Skris case, obviously, is not to include support for multi-threading (but 31555714Skris you can still use "no-threads" to suppress an annoying warning message 31655714Skris from the Configure script.) 31755714Skris 31868651Skris 31968651Skris Note on shared libraries 32068651Skris ------------------------ 32168651Skris 322167612Ssimon Shared libraries have certain caveats. Binary backward compatibility 323167612Ssimon can't be guaranteed before OpenSSL version 1.0. The only reason to 324167612Ssimon use them would be to conserve memory on systems where several programs 325167612Ssimon are using OpenSSL. 326100928Snectar 32768651Skris For some systems, the OpenSSL Configure script knows what is needed to 32868651Skris build shared libraries for libcrypto and libssl. On these systems, 32968651Skris the shared libraries are currently not created by default, but giving 33068651Skris the option "shared" will get them created. This method supports Makefile 33168651Skris targets for shared library creation, like linux-shared. Those targets 33268651Skris can currently be used on their own just as well, but this is expected 33368651Skris to change in future versions of OpenSSL. 334109998Smarkm 335109998Smarkm Note on random number generation 336109998Smarkm -------------------------------- 337109998Smarkm 338109998Smarkm Availability of cryptographically secure random numbers is required for 339109998Smarkm secret key generation. OpenSSL provides several options to seed the 340109998Smarkm internal PRNG. If not properly seeded, the internal PRNG will refuse 341109998Smarkm to deliver random bytes and a "PRNG not seeded error" will occur. 342109998Smarkm On systems without /dev/urandom (or similar) device, it may be necessary 343109998Smarkm to install additional support software to obtain random seed. 344109998Smarkm Please check out the manual pages for RAND_add(), RAND_bytes(), RAND_egd(), 345109998Smarkm and the FAQ for more information. 346111147Snectar 347111147Snectar Note on support for multiple builds 348111147Snectar ----------------------------------- 349111147Snectar 350160814Ssimon OpenSSL is usually built in its source tree. Unfortunately, this doesn't 351111147Snectar support building for multiple platforms from the same source tree very well. 352111147Snectar It is however possible to build in a separate tree through the use of lots 353111147Snectar of symbolic links, which should be prepared like this: 354111147Snectar 355111147Snectar mkdir -p objtree/"`uname -s`-`uname -r`-`uname -m`" 356111147Snectar cd objtree/"`uname -s`-`uname -r`-`uname -m`" 357111147Snectar (cd $OPENSSL_SOURCE; find . -type f) | while read F; do 358111147Snectar mkdir -p `dirname $F` 359111147Snectar rm -f $F; ln -s $OPENSSL_SOURCE/$F $F 360111147Snectar echo $F '->' $OPENSSL_SOURCE/$F 361111147Snectar done 362111147Snectar make -f Makefile.org clean 363111147Snectar 364111147Snectar OPENSSL_SOURCE is an environment variable that contains the absolute (this 365111147Snectar is important!) path to the OpenSSL source tree. 366111147Snectar 367111147Snectar Also, operations like 'make update' should still be made in the source tree. 368