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