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