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 77312826Sjkim 386 In 32-bit x86 builds, when generating assembly modules, 78312826Sjkim use the 80386 instruction set only (the default x86 code 79312826Sjkim is more efficient, but requires at least a 486). Note: 80312826Sjkim This doesn't affect code generated by compiler, you're 81312826Sjkim likely to complement configuration command line with 82312826Sjkim suitable compiler-specific option. 8355714Skris 84312826Sjkim no-sse2 Exclude SSE2 code paths from 32-bit x86 assembly modules. 85312826Sjkim Normally SSE2 extension is detected at run-time, but the 86312826Sjkim decision whether or not the machine code will be executed 87312826Sjkim is taken solely on CPU capability vector. This means that 88312826Sjkim if you happen to run OS kernel which does not support SSE2 89312826Sjkim extension on Intel P4 processor, then your application 90312826Sjkim might be exposed to "illegal instruction" exception. 91312826Sjkim There might be a way to enable support in kernel, e.g. 92312826Sjkim FreeBSD kernel can be compiled with CPU_ENABLE_SSE, and 93312826Sjkim there is a way to disengage SSE2 code paths upon application 94312826Sjkim start-up, but if you aim for wider "audience" running 95312826Sjkim such kernel, consider no-sse2. Both the 386 and 96312826Sjkim 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, 106312826Sjkim library directories or other compiler options. It might be 107312826Sjkim worth noting that some compilers generate code specifically 108312826Sjkim for processor the compiler currently executes on. This is 109312826Sjkim not necessarily what you might have in mind, since it might 110312826Sjkim be unsuitable for execution on other, typically older, 111312826Sjkim 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 169312826Sjkim If the build fails, look at the output. There may be reasons 170312826Sjkim for the failure that aren't problems in OpenSSL itself (like 171312826Sjkim missing standard headers). If you are having problems you can 172312826Sjkim get help by sending an email to the openssl-users email list (see 173312826Sjkim https://www.openssl.org/community/mailinglists.html for details). If 174312826Sjkim it is a bug with OpenSSL itself, please open an issue on GitHub, at 175312826Sjkim https://github.com/openssl/openssl/issues. Please review the existing 176312826Sjkim ones first; maybe the bug was already reported or has already been 177312826Sjkim fixed. 17855714Skris 179312826Sjkim (If you encounter assembler error messages, try the "no-asm" 180312826Sjkim 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 193325337Sjkim in Makefile.ssl and run "make clean; make". To report a bug please open an 194325337Sjkim issue on GitHub, at https://github.com/openssl/openssl/issues. 19555714Skris 19655714Skris 4. If everything tests ok, install OpenSSL with 19755714Skris 19855714Skris $ make install 19955714Skris 20055714Skris This will create the installation directory (if it does not exist) and 20155714Skris then the following subdirectories: 20255714Skris 20355714Skris certs Initially empty, this is the default location 20455714Skris for certificate files. 20559191Skris man/man1 Manual pages for the 'openssl' command line tool 20659191Skris man/man3 Manual pages for the libraries (very incomplete) 20755714Skris misc Various scripts. 20855714Skris private Initially empty, this is the default location 20955714Skris for private key files. 21055714Skris 21159191Skris If you didn't choose a different installation prefix, the 21255714Skris following additional subdirectories will be created: 21355714Skris 21455714Skris bin Contains the openssl binary and a few other 21555714Skris utility programs. 21655714Skris include/openssl Contains the header files needed if you want to 21755714Skris compile programs with libcrypto or libssl. 21855714Skris lib Contains the OpenSSL library files themselves. 21955714Skris 220238405Sjkim Use "make install_sw" to install the software without documentation, 221238405Sjkim and "install_docs_html" to install HTML renditions of the manual 222238405Sjkim pages. 223238405Sjkim 22455714Skris Package builders who want to configure the library for standard 22555714Skris locations, but have the package installed somewhere else so that 22655714Skris it can easily be packaged, can use 22755714Skris 22855714Skris $ make INSTALL_PREFIX=/tmp/package-root install 22955714Skris 23055714Skris (or specify "--install_prefix=/tmp/package-root" as a configure 23155714Skris option). The specified prefix will be prepended to all 23255714Skris installation target filenames. 23355714Skris 23455714Skris 23555714Skris NOTE: The header files used to reside directly in the include 23655714Skris directory, but have now been moved to include/openssl so that 23755714Skris OpenSSL can co-exist with other libraries which use some of the 23855714Skris same filenames. This means that applications that use OpenSSL 23955714Skris should now use C preprocessor directives of the form 24055714Skris 24155714Skris #include <openssl/ssl.h> 24255714Skris 24355714Skris instead of "#include <ssl.h>", which was used with library versions 24455714Skris up to OpenSSL 0.9.2b. 24555714Skris 24655714Skris If you install a new version of OpenSSL over an old library version, 24755714Skris you should delete the old header files in the include directory. 24855714Skris 24955714Skris Compatibility issues: 25055714Skris 25155714Skris * COMPILING existing applications 25255714Skris 25355714Skris To compile an application that uses old filenames -- e.g. 25455714Skris "#include <ssl.h>" --, it will usually be enough to find 25555714Skris the CFLAGS definition in the application's Makefile and 25655714Skris add a C option such as 25755714Skris 25855714Skris -I/usr/local/ssl/include/openssl 25955714Skris 26055714Skris to it. 26155714Skris 26255714Skris But don't delete the existing -I option that points to 26355714Skris the ..../include directory! Otherwise, OpenSSL header files 26455714Skris could not #include each other. 26555714Skris 26655714Skris * WRITING applications 26755714Skris 26855714Skris To write an application that is able to handle both the new 26955714Skris and the old directory layout, so that it can still be compiled 27055714Skris with library versions up to OpenSSL 0.9.2b without bothering 27155714Skris the user, you can proceed as follows: 27255714Skris 27355714Skris - Always use the new filename of OpenSSL header files, 27455714Skris e.g. #include <openssl/ssl.h>. 27555714Skris 27655714Skris - Create a directory "incl" that contains only a symbolic 27755714Skris link named "openssl", which points to the "include" directory 27855714Skris of OpenSSL. 27955714Skris For example, your application's Makefile might contain the 28055714Skris following rule, if OPENSSLDIR is a pathname (absolute or 28155714Skris relative) of the directory where OpenSSL resides: 28255714Skris 28355714Skris incl/openssl: 28455714Skris -mkdir incl 28555714Skris cd $(OPENSSLDIR) # Check whether the directory really exists 28655714Skris -ln -s `cd $(OPENSSLDIR); pwd`/include incl/openssl 28755714Skris 28855714Skris You will have to add "incl/openssl" to the dependencies 28955714Skris of those C files that include some OpenSSL header file. 29055714Skris 29155714Skris - Add "-Iincl" to your CFLAGS. 29255714Skris 29355714Skris With these additions, the OpenSSL header files will be available 29455714Skris under both name variants if an old library version is used: 29555714Skris Your application can reach them under names like <openssl/foo.h>, 29655714Skris while the header files still are able to #include each other 29755714Skris with names of the form <foo.h>. 29855714Skris 29955714Skris 30055714Skris Note on multi-threading 30155714Skris ----------------------- 30255714Skris 30355714Skris For some systems, the OpenSSL Configure script knows what compiler options 30455714Skris are needed to generate a library that is suitable for multi-threaded 30555714Skris applications. On these systems, support for multi-threading is enabled 30655714Skris by default; use the "no-threads" option to disable (this should never be 30755714Skris necessary). 30855714Skris 30955714Skris On other systems, to enable support for multi-threading, you will have 31055714Skris to specify at least two options: "threads", and a system-dependent option. 31155714Skris (The latter is "-D_REENTRANT" on various systems.) The default in this 31255714Skris case, obviously, is not to include support for multi-threading (but 31355714Skris you can still use "no-threads" to suppress an annoying warning message 31455714Skris from the Configure script.) 31555714Skris 31668651Skris 31768651Skris Note on shared libraries 31868651Skris ------------------------ 31968651Skris 320167612Ssimon Shared libraries have certain caveats. Binary backward compatibility 321167612Ssimon can't be guaranteed before OpenSSL version 1.0. The only reason to 322167612Ssimon use them would be to conserve memory on systems where several programs 323167612Ssimon are using OpenSSL. 324100928Snectar 32568651Skris For some systems, the OpenSSL Configure script knows what is needed to 32668651Skris build shared libraries for libcrypto and libssl. On these systems, 32768651Skris the shared libraries are currently not created by default, but giving 32868651Skris the option "shared" will get them created. This method supports Makefile 32968651Skris targets for shared library creation, like linux-shared. Those targets 33068651Skris can currently be used on their own just as well, but this is expected 33168651Skris to change in future versions of OpenSSL. 332109998Smarkm 333109998Smarkm Note on random number generation 334109998Smarkm -------------------------------- 335109998Smarkm 336109998Smarkm Availability of cryptographically secure random numbers is required for 337109998Smarkm secret key generation. OpenSSL provides several options to seed the 338109998Smarkm internal PRNG. If not properly seeded, the internal PRNG will refuse 339109998Smarkm to deliver random bytes and a "PRNG not seeded error" will occur. 340109998Smarkm On systems without /dev/urandom (or similar) device, it may be necessary 341109998Smarkm to install additional support software to obtain random seed. 342109998Smarkm Please check out the manual pages for RAND_add(), RAND_bytes(), RAND_egd(), 343109998Smarkm and the FAQ for more information. 344111147Snectar 345111147Snectar Note on support for multiple builds 346111147Snectar ----------------------------------- 347111147Snectar 348160814Ssimon OpenSSL is usually built in its source tree. Unfortunately, this doesn't 349111147Snectar support building for multiple platforms from the same source tree very well. 350111147Snectar It is however possible to build in a separate tree through the use of lots 351111147Snectar of symbolic links, which should be prepared like this: 352111147Snectar 353111147Snectar mkdir -p objtree/"`uname -s`-`uname -r`-`uname -m`" 354111147Snectar cd objtree/"`uname -s`-`uname -r`-`uname -m`" 355111147Snectar (cd $OPENSSL_SOURCE; find . -type f) | while read F; do 356111147Snectar mkdir -p `dirname $F` 357111147Snectar rm -f $F; ln -s $OPENSSL_SOURCE/$F $F 358111147Snectar echo $F '->' $OPENSSL_SOURCE/$F 359111147Snectar done 360111147Snectar make -f Makefile.org clean 361111147Snectar 362111147Snectar OPENSSL_SOURCE is an environment variable that contains the absolute (this 363111147Snectar is important!) path to the OpenSSL source tree. 364111147Snectar 365111147Snectar Also, operations like 'make update' should still be made in the source tree. 366