Tweak some more information in INSTALL
[openssl.git] / INSTALL
1
2  INSTALLATION ON THE UNIX PLATFORM
3  ---------------------------------
4
5  [Installation on DOS (with djgpp), Windows, MacOS (before MacOS X)
6   and NetWare is described in INSTALL.DJGPP, INSTALL.WIN, INSTALL.MacOS
7   and INSTALL.NW.
8   
9   This document describes installation on the main supported operating
10   systems, currently the Unix family and OpenVMS.]
11
12  To install OpenSSL, you will need:
13
14   * make
15   * Perl 5 with core modules (please read README.PERL)
16   * The perl module Text::Template (please read README.PERL)
17   * an ANSI C compiler
18   * a development environment in form of development libraries and C
19     header files
20   * a supported operating system
21
22  For more details regarding specific platforms, there are these notes
23  available:
24
25   * NOTES.VMS
26
27  Quick Start
28  -----------
29
30  If you want to just get on with it, do:
31
32   on Unix:
33
34     $ ./config
35     $ make
36     $ make test
37     $ make install
38
39   on OpenVMS:
40
41     $ @config
42     $ mms
43     $ mms test
44     $ mms install
45
46  [If any of these steps fails, see section Installation in Detail below.]
47
48  This will build and install OpenSSL in the default location, which is:
49
50   Unix:    normal installation directories under /usr/local
51   OpenVMS: SYS$COMMON:[OPENSSL-'version'...], where 'version' is the
52            OpenSSL version number ('major'_'minor').
53
54  If you want to install it anywhere else, run config like this:
55
56   On Unix:
57
58     $ ./config --prefix=/opt/openssl --openssldir=/usr/local/ssl
59
60   On OpenVMS:
61
62     $ @config --prefix=PROGRAM:[INSTALLS] --openssldir=SYS$MANAGER:[OPENSSL]
63
64
65  Configuration Options
66  ---------------------
67
68  There are several options to ./config (or ./Configure) to customize
69  the build:
70
71   --prefix=DIR  The top of the installation directory tree.  Defaults are:
72
73                 Unix:           /usr/local
74                 OpenVMS:        SYS$COMMON:[OPENSSL-'version']
75
76   --openssldir=DIR Directory for OpenSSL configuration files, and also the
77                 default certificate and key store.  Defaults are:
78
79                 Unix:           PREFIX/ssl (PREFIX is given by --prefix)
80                 OpenVMS:        SYS$COMMON:[SSL]
81
82   no-autoalginit Don't automatically load all supported ciphers and digests.
83                 Typically OpenSSL will make available all of its supported
84                 ciphers and digests. For a statically linked application this
85                 may be undesirable if small executable size is an objective.
86                 This only affects libcrypto. Ciphers and digests will have to be
87                 loaded manually using EVP_add_cipher() and EVP_add_digest() if
88                 this option is used.
89
90   no-autoerrinit Don't automatically load all libcrypto/libssl error strings.
91                 Typically OpenSSL will automatically load human readable error
92                 strings. For a statically linked application this may be
93                 undesirable if small executable size is an objective.
94
95   no-threads    Don't try to build with support for multi-threaded
96                 applications.
97
98   threads       Build with support for multi-threaded applications.
99                 This will usually require additional system-dependent options!
100                 See "Note on multi-threading" below.
101
102   no-zlib       Don't try to build with support for zlib compression and
103                 decompression.
104
105   zlib          Build with support for zlib compression/decompression.
106
107   zlib-dynamic  Like "zlib", but has OpenSSL load the zlib library dynamically
108                 when needed.  This is only supported on systems where loading
109                 of shared libraries is supported.  This is the default choice.
110
111   no-shared     Don't try to create shared libraries.
112
113   shared        In addition to the usual static libraries, create shared
114                 libraries on platforms where it's supported.  See "Note on
115                 shared libraries" below.
116
117   no-asm        Do not use assembler code.
118
119   386           On Intel hardware, use the 80386 instruction set only
120                 (the default x86 code is more efficient, but requires at
121                 least a 486). Note: Use compiler flags for any other CPU
122                 specific configuration, e.g. "-m32" to build x86 code on
123                 an x64 system.
124
125   no-sse2       Exclude SSE2 code pathes. Normally SSE2 extension is
126                 detected at run-time, but the decision whether or not the
127                 machine code will be executed is taken solely on CPU
128                 capability vector. This means that if you happen to run OS
129                 kernel which does not support SSE2 extension on Intel P4
130                 processor, then your application might be exposed to
131                 "illegal instruction" exception. There might be a way
132                 to enable support in kernel, e.g. FreeBSD kernel can be
133                 compiled with CPU_ENABLE_SSE, and there is a way to
134                 disengage SSE2 code pathes upon application start-up,
135                 but if you aim for wider "audience" running such kernel,
136                 consider no-sse2. Both 386 and no-asm options above imply
137                 no-sse2.
138
139   no-<cipher>   Build without the specified cipher (bf, cast, des, dh, dsa,
140                 hmac, md2, md5, mdc2, rc2, rc4, rc5, rsa, sha).
141                 The crypto/<cipher> directory can be removed after running
142                 "make depend".
143
144   -Dxxx, -lxxx, -Lxxx, -fxxx, -mXXX, -Kxxx These system specific options will
145                 be passed through to the compiler to allow you to
146                 define preprocessor symbols, specify additional libraries,
147                 library directories or other compiler options.
148
149
150  Installation in Detail
151  ----------------------
152
153  1a. Configure OpenSSL for your operation system automatically:
154
155        $ ./config [options]                             # Unix
156
157        or
158
159        $ @config [options]                              ! OpenVMS
160
161      For the remainder of this text, the Unix form will be used in all
162      examples, please use the appropriate form for your platform.
163
164      This guesses at your operating system (and compiler, if necessary) and
165      configures OpenSSL based on this guess. Run ./config -t to see
166      if it guessed correctly. If you want to use a different compiler, you
167      are cross-compiling for another platform, or the ./config guess was
168      wrong for other reasons, go to step 1b. Otherwise go to step 2.
169
170      On some systems, you can include debugging information as follows:
171
172        $ ./config -d [options]
173
174  1b. Configure OpenSSL for your operating system manually
175
176      OpenSSL knows about a range of different operating system, hardware and
177      compiler combinations. To see the ones it knows about, run
178
179        $ ./Configure                                    # Unix
180
181        or
182
183        $ perl Configure                                 # All other platforms
184
185      For the remainder of this text, the Unix form will be used in all
186      examples, please use the appropriate form for your platform.
187
188      Pick a suitable name from the list that matches your system. For most
189      operating systems there is a choice between using "cc" or "gcc".  When
190      you have identified your system (and if necessary compiler) use this name
191      as the argument to Configure. For example, a "linux-elf" user would
192      run:
193
194        $ ./Configure linux-elf [options]
195
196      If your system isn't listed, you will have to create a configuration
197      file named Configurations/{something}.conf and add the correct
198      configuration for your system. See the available configs as examples
199      and read Configurations/README and Configurations/README.design for
200      more information.
201
202      The generic configurations "cc" or "gcc" should usually work on 32 bit
203      Unix-like systems.
204
205      Configure creates a build file ("Makefile" on Unix and "descrip.mms"
206      on OpenVMS) from a suitable template in Configurations, and
207      defines various macros in crypto/opensslconf.h (generated from
208      crypto/opensslconf.h.in).
209
210  1c. Configure OpenSSL for building outside of the source tree.
211
212      OpenSSL can be configured to build in a build directory separate from
213      the directory with the source code.  It's done by placing yourself in
214      some other directory and invoking the configuration commands from
215      there.
216
217      Unix example:
218
219        $ mkdir /var/tmp/openssl-build
220        $ cd /var/tmp/openssl-build
221        $ /PATH/TO/OPENSSL/SOURCE/config [options]
222
223        or
224
225        $ /PATH/TO/OPENSSL/SOURCE/Configure [target] [options]
226
227      OpenVMS example:
228
229        $ set default sys$login:
230        $ create/dir [.tmp.openssl-build]
231        $ set default [.tmp.openssl-build]
232        $ @[PATH.TO.OPENSSL.SOURCE]config {options}
233
234        or
235
236        $ @[PATH.TO.OPENSSL.SOURCE]Configure {target} {options}
237
238      Paths can be relative just as well as absolute.  Configure will
239      do its best to translate them to relative paths whenever possible.
240
241   2. Build OpenSSL by running:
242
243        $ make                                           # Unix
244        $ mms                                            ! (or mmk) OpenVMS
245
246      This will build the OpenSSL libraries (libcrypto.a and libssl.a on
247      Unix, corresponding on other platforms) and the OpenSSL binary
248      ("openssl"). The libraries will be built in the top-level directory,
249      and the binary will be in the "apps" subdirectory.
250
251      If the build fails, look at the output.  There may be reasons for
252      the failure that aren't problems in OpenSSL itself (like missing
253      standard headers).  If it is a problem with OpenSSL itself, please
254      report the problem to <rt@openssl.org> (note that your message
255      will be recorded in the request tracker publicly readable at
256      https://www.openssl.org/community/index.html#bugs and will be
257      forwarded to a public mailing list). Include the output of "make
258      report" in your message.  Please check out the request tracker. Maybe
259      the bug was already reported or has already been fixed.
260
261      [If you encounter assembler error messages, try the "no-asm"
262      configuration option as an immediate fix.]
263
264      Compiling parts of OpenSSL with gcc and others with the system
265      compiler will result in unresolved symbols on some systems.
266
267   3. After a successful build, the libraries should be tested. Run:
268
269        $ make test                                      # Unix
270        $ mms test                                       ! OpenVMS
271
272      If some tests fail, look at the output.  There may be reasons for
273      the failure that isn't a problem in OpenSSL itself (like a
274      malfunction with Perl).  You may want increased verbosity, that
275      can be accomplished like this:
276
277        $ HARNESS_VERBOSE=yes make test                  # Unix
278
279        $ DEFINE HARNESS_VERBOSE YES
280        $ mms test                                       ! OpenVMS
281
282      If you want to run just one or a few specific tests, you can use
283      the make variable TESTS to specify them, like this:
284
285        $ make TESTS='test_rsa test_dsa' test            # Unix
286        $ mms/macro="TESTS=test_rsa test_dsa" test       ! OpenVMS
287
288      And of course, you can combine (Unix example shown):
289        
290        $ HARNESS_VERBOSE=yes make TESTS='test_rsa test_dsa' test
291
292      You can find the list of available tests like this:
293
294        $ make list-tests                                # Unix
295        $ mms list-tests                                 ! OpenVMS
296
297      Have a look at the manual for the perl module Test::Harness to
298      see what other HARNESS_* variables there are.
299
300      If you find a problem with OpenSSL itself, try removing any
301      compiler optimization flags from the CFLAGS line in Makefile and
302      run "make clean; make" or corresponding.
303
304      Please send a bug report to <openssl-bugs@openssl.org>, and when
305      you do, please run the following and include the output in your
306      report:
307
308        $ make report
309
310   4. If everything tests ok, install OpenSSL with
311
312        $ make install                                   # Unix
313        $ mms install                                    ! OpenVMS
314
315      This will install all the software components in this directory
316      tree under PREFIX (the directory given with --prefix or its
317      default):
318
319        Unix:
320
321          bin/           Contains the openssl binary and a few other
322                         utility scripts.
323          include/openssl
324                         Contains the header files needed if you want
325                         to build your own programs that use libcrypto
326                         or libssl.
327          lib            Contains the OpenSSL library files.
328          lib/engines    Contains the OpenSSL dynamically loadable engines.
329          share/man/{man1,man3,man5,man7}
330                         Contains the OpenSSL man-pages.
331          share/doc/openssl/html{man1,man3,man5,man7}
332                         Contains the HTML rendition of the man-pages.
333
334        OpenVMS ('arch' is replaced with the architecture name, "Alpha"
335        or "ia64"):
336
337          [.EXE.'arch']  Contains the openssl binary and a few other
338                         utility scripts.
339          [.include.openssl]
340                         Contains the header files needed if you want
341                         to build your own programs that use libcrypto
342                         or libssl.
343          [.LIB.'arch']  Contains the OpenSSL library files.
344          [.ENGINES.'arch']
345                         Contains the OpenSSL dynamically loadable engines.
346          [.SYS$STARTUP] Contains startup, login and shutdown scripts.
347                         These define appropriate logical names and
348                         command symbols.
349                         
350
351      Additionally, install will add the following directories under
352      OPENSSLDIR (the directory given with --openssldir or its default)
353      for you convenience:
354
355          certs          Initially empty, this is the default location
356                         for certificate files.
357          private        Initially empty, this is the default location
358                         for private key files.
359          misc           Various scripts.
360
361      Package builders who want to configure the library for standard
362      locations, but have the package installed somewhere else so that
363      it can easily be packaged, can use
364
365        $ make DESTDIR=/tmp/package-root install         # Unix
366        $ mms/macro="DESTDIR=TMP:[PACKAGE-ROOT]" install ! OpenVMS
367
368      The specified destination directory will be prepended to all
369      installation target paths.
370
371   Compatibility issues with previous OpenSSL versions:
372
373   *  COMPILING existing applications
374
375      OpenSSL 1.1 hides a number of structures that were previously
376      open.  This includes all internal libssl structures and a number
377      of EVP types.  Accessor functions have been added to allow
378      controlled access to the structures' data.
379
380      This means that some software needs to be rewritten to adapt to
381      the new ways of doing things.  This often amounts to allocating
382      an instance of a structure explicitly where you could previously
383      allocate them on the stack as automatic variables, and using the
384      provided accessor functions where you would previously access a
385      structure's field directly.
386
387      <TBA>
388
389      Some APIs have changed as well.  However, older APIs have been
390      preserved when possible.
391
392
393  Note on multi-threading
394  -----------------------
395
396  For some systems, the OpenSSL Configure script knows what compiler options
397  are needed to generate a library that is suitable for multi-threaded
398  applications.  On these systems, support for multi-threading is enabled
399  by default; use the "no-threads" option to disable (this should never be
400  necessary).
401
402  On other systems, to enable support for multi-threading, you will have
403  to specify at least two options: "threads", and a system-dependent option.
404  (The latter is "-D_REENTRANT" on various systems.)  The default in this
405  case, obviously, is not to include support for multi-threading (but
406  you can still use "no-threads" to suppress an annoying warning message
407  from the Configure script.)
408
409  OpenSSL provides built-in support for two threading models: pthreads (found on
410  most UNIX/Linux systems), and Windows threads. No other threading models are
411  supported. If your platform does not provide pthreads or Windows threads then
412  you should Configure with the "no-threads" option.
413
414  Note on shared libraries
415  ------------------------
416
417  Shared libraries have certain caveats.  Binary backward compatibility
418  can't be guaranteed before OpenSSL version 1.0.  The only reason to
419  use them would be to conserve memory on systems where several programs
420  are using OpenSSL.
421
422  For some systems, the OpenSSL Configure script knows what is needed to
423  build shared libraries for libcrypto and libssl.  On these systems,
424  the shared libraries are currently not created by default, but giving
425  the option "shared" will get them created.  This method supports Makefile
426  targets for shared library creation, like linux-shared.  Those targets
427  can currently be used on their own just as well, but this is expected
428  to change in future versions of OpenSSL.
429
430  Note on random number generation
431  --------------------------------
432
433  Availability of cryptographically secure random numbers is required for
434  secret key generation. OpenSSL provides several options to seed the
435  internal PRNG. If not properly seeded, the internal PRNG will refuse
436  to deliver random bytes and a "PRNG not seeded error" will occur.
437  On systems without /dev/urandom (or similar) device, it may be necessary
438  to install additional support software to obtain random seed.
439  Please check out the manual pages for RAND_add(), RAND_bytes(), RAND_egd(),
440  and the FAQ for more information.
441