2 INSTALLATION ON THE UNIX PLATFORM
3 ---------------------------------
5 [Installation on Windows, OpenVMS and MacOS (before MacOS X) is described
6 in INSTALL.W32, INSTALL.VMS and INSTALL.MacOS.]
8 To install OpenSSL, you will need:
13 * a development environment in form of development libraries and C
15 * a supported Unix operating system
20 If you want to just get on with it, do:
27 [If any of these steps fails, see section Installation in Detail below.]
29 This will build and install OpenSSL in the default location, which is (for
30 historical reasons) /usr/local/ssl. If you want to install it anywhere else,
33 $ ./config --prefix=/usr/local --openssldir=/usr/local/openssl
39 There are several options to ./config (or ./Configure) to customize
42 --prefix=DIR Install in DIR/bin, DIR/lib, DIR/include/openssl.
43 Configuration files used by OpenSSL will be in DIR/ssl
44 or the directory specified by --openssldir.
46 --openssldir=DIR Directory for OpenSSL files. If no prefix is specified,
47 the library files and binaries are also installed there.
49 no-threads Don't try to build with support for multi-threaded
52 threads Build with support for multi-threaded applications.
53 This will usually require additional system-dependent options!
54 See "Note on multi-threading" below.
56 no-shared Don't try to create shared libraries.
58 shared In addition to the usual static libraries, create shared
59 libraries on platforms where it's supported. See "Note on
60 shared libraries" below.
62 no-asm Do not use assembler code.
64 386 Use the 80386 instruction set only (the default x86 code is
65 more efficient, but requires at least a 486).
67 no-<cipher> Build without the specified cipher (bf, cast, des, dh, dsa,
68 hmac, md2, md5, mdc2, rc2, rc4, rc5, rsa, sha).
69 The crypto/<cipher> directory can be removed after running
72 -Dxxx, -lxxx, -Lxxx, -fxxx, -Kxxx These system specific options will
73 be passed through to the compiler to allow you to
74 define preprocessor symbols, specify additional libraries,
75 library directories or other compiler options.
78 Installation in Detail
79 ----------------------
81 1a. Configure OpenSSL for your operation system automatically:
85 This guesses at your operating system (and compiler, if necessary) and
86 configures OpenSSL based on this guess. Run ./config -t to see
87 if it guessed correctly. If you want to use a different compiler, you
88 are cross-compiling for another platform, or the ./config guess was
89 wrong for other reasons, go to step 1b. Otherwise go to step 2.
91 On some systems, you can include debugging information as follows:
93 $ ./config -d [options]
95 1b. Configure OpenSSL for your operating system manually
97 OpenSSL knows about a range of different operating system, hardware and
98 compiler combinations. To see the ones it knows about, run
102 Pick a suitable name from the list that matches your system. For most
103 operating systems there is a choice between using "cc" or "gcc". When
104 you have identified your system (and if necessary compiler) use this name
105 as the argument to ./Configure. For example, a "linux-elf" user would
108 $ ./Configure linux-elf [options]
110 If your system is not available, you will have to edit the Configure
111 program and add the correct configuration for your system. The
112 generic configurations "cc" or "gcc" should usually work on 32 bit
115 Configure creates the file Makefile.ssl from Makefile.org and
116 defines various macros in crypto/opensslconf.h (generated from
117 crypto/opensslconf.h.in).
119 2. Build OpenSSL by running:
123 This will build the OpenSSL libraries (libcrypto.a and libssl.a) and the
124 OpenSSL binary ("openssl"). The libraries will be built in the top-level
125 directory, and the binary will be in the "apps" directory.
127 If "make" fails, look at the output. There may be reasons for
128 the failure that aren't problems in OpenSSL itself (like missing
129 standard headers). If it is a problem with OpenSSL itself, please
130 report the problem to <openssl-bugs@openssl.org> (note that your
131 message will be recorded in the request tracker publicly readable
132 via http://www.openssl.org/rt2.html and will be forwarded to a public
133 mailing list). Include the output of "make report" in your message.
134 Please check out the request tracker. Maybe the bug was already
135 reported or has already been fixed.
137 [If you encounter assembler error messages, try the "no-asm"
138 configuration option as an immediate fix.]
140 Compiling parts of OpenSSL with gcc and others with the system
141 compiler will result in unresolved symbols on some systems.
143 3. After a successful build, the libraries should be tested. Run:
147 If a test fails, look at the output. There may be reasons for
148 the failure that isn't a problem in OpenSSL itself (like a missing
149 or malfunctioning bc). If it is a problem with OpenSSL itself,
150 try removing any compiler optimization flags from the CFLAGS line
151 in Makefile.ssl and run "make clean; make". Please send a bug
152 report to <openssl-bugs@openssl.org>, including the output of
153 "make report" in order to be added to the request tracker at
154 http://www.openssl.org/rt2.html.
156 4. If everything tests ok, install OpenSSL with
160 This will create the installation directory (if it does not exist) and
161 then the following subdirectories:
163 certs Initially empty, this is the default location
164 for certificate files.
165 man/man1 Manual pages for the 'openssl' command line tool
166 man/man3 Manual pages for the libraries (very incomplete)
167 misc Various scripts.
168 private Initially empty, this is the default location
169 for private key files.
171 If you didn't choose a different installation prefix, the
172 following additional subdirectories will be created:
174 bin Contains the openssl binary and a few other
176 include/openssl Contains the header files needed if you want to
177 compile programs with libcrypto or libssl.
178 lib Contains the OpenSSL library files themselves.
180 Package builders who want to configure the library for standard
181 locations, but have the package installed somewhere else so that
182 it can easily be packaged, can use
184 $ make INSTALL_PREFIX=/tmp/package-root install
186 (or specify "--install_prefix=/tmp/package-root" as a configure
187 option). The specified prefix will be prepended to all
188 installation target filenames.
191 NOTE: The header files used to reside directly in the include
192 directory, but have now been moved to include/openssl so that
193 OpenSSL can co-exist with other libraries which use some of the
194 same filenames. This means that applications that use OpenSSL
195 should now use C preprocessor directives of the form
197 #include <openssl/ssl.h>
199 instead of "#include <ssl.h>", which was used with library versions
200 up to OpenSSL 0.9.2b.
202 If you install a new version of OpenSSL over an old library version,
203 you should delete the old header files in the include directory.
205 Compatibility issues:
207 * COMPILING existing applications
209 To compile an application that uses old filenames -- e.g.
210 "#include <ssl.h>" --, it will usually be enough to find
211 the CFLAGS definition in the application's Makefile and
212 add a C option such as
214 -I/usr/local/ssl/include/openssl
218 But don't delete the existing -I option that points to
219 the ..../include directory! Otherwise, OpenSSL header files
220 could not #include each other.
222 * WRITING applications
224 To write an application that is able to handle both the new
225 and the old directory layout, so that it can still be compiled
226 with library versions up to OpenSSL 0.9.2b without bothering
227 the user, you can proceed as follows:
229 - Always use the new filename of OpenSSL header files,
230 e.g. #include <openssl/ssl.h>.
232 - Create a directory "incl" that contains only a symbolic
233 link named "openssl", which points to the "include" directory
235 For example, your application's Makefile might contain the
236 following rule, if OPENSSLDIR is a pathname (absolute or
237 relative) of the directory where OpenSSL resides:
241 cd $(OPENSSLDIR) # Check whether the directory really exists
242 -ln -s `cd $(OPENSSLDIR); pwd`/include incl/openssl
244 You will have to add "incl/openssl" to the dependencies
245 of those C files that include some OpenSSL header file.
247 - Add "-Iincl" to your CFLAGS.
249 With these additions, the OpenSSL header files will be available
250 under both name variants if an old library version is used:
251 Your application can reach them under names like <openssl/foo.h>,
252 while the header files still are able to #include each other
253 with names of the form <foo.h>.
256 Note on multi-threading
257 -----------------------
259 For some systems, the OpenSSL Configure script knows what compiler options
260 are needed to generate a library that is suitable for multi-threaded
261 applications. On these systems, support for multi-threading is enabled
262 by default; use the "no-threads" option to disable (this should never be
265 On other systems, to enable support for multi-threading, you will have
266 to specify at least two options: "threads", and a system-dependent option.
267 (The latter is "-D_REENTRANT" on various systems.) The default in this
268 case, obviously, is not to include support for multi-threading (but
269 you can still use "no-threads" to suppress an annoying warning message
270 from the Configure script.)
273 Note on shared libraries
274 ------------------------
276 Shared library is currently an experimental feature. The only reason to
277 have them would be to conserve memory on systems where several program
278 are using OpenSSL. Binary backward compatibility can't be guaranteed
279 before OpenSSL version 1.0.
281 For some systems, the OpenSSL Configure script knows what is needed to
282 build shared libraries for libcrypto and libssl. On these systems,
283 the shared libraries are currently not created by default, but giving
284 the option "shared" will get them created. This method supports Makefile
285 targets for shared library creation, like linux-shared. Those targets
286 can currently be used on their own just as well, but this is expected
287 to change in future versions of OpenSSL.