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 is not available, you will have to edit the Configure
 197      program and add the correct configuration for your system. The
 198      generic configurations "cc" or "gcc" should usually work on 32 bit
 199      systems.
 200
 201      Configure creates the file Makefile.ssl from Makefile.in and
 202      defines various macros in crypto/opensslconf.h (generated from
 203      crypto/opensslconf.h.in).
 204
 205  1c. Configure OpenSSL for building outside of the source tree.
 206
 207      OpenSSL can be configured to build in a build directory separate from
 208      the directory with the source code.  It's done by placing yourself in
 209      some other directory and invoking the configuration commands from
 210      there.
 211
 212      Unix example:
 213
 214        $ mkdir /var/tmp/openssl-build
 215        $ cd /var/tmp/openssl-build
 216        $ /PATH/TO/OPENSSL/SOURCE/config [options]
 217
 218        or
 219
 220        $ /PATH/TO/OPENSSL/SOURCE/Configure [target] [options]
 221
 222      OpenVMS example:
 223
 224        $ set default sys$login:
 225        $ create/dir [.tmp.openssl-build]
 226        $ set default [.tmp.openssl-build]
 227        $ @[PATH.TO.OPENSSL.SOURCE]config {options}
 228
 229        or
 230
 231        $ @[PATH.TO.OPENSSL.SOURCE]Configure {target} {options}
 232
 233      Paths can be relative just as well as absolute.  Configure will
 234      do its best to translate them to relative paths whenever possible.
 235
 236   2. Build OpenSSL by running:
 237
 238        $ make                                           # Unix
 239        $ mms                                            ! (or mmk) OpenVMS
 240
 241      This will build the OpenSSL libraries (libcrypto.a and libssl.a on
 242      Unix, corresponding on other platforms) and the OpenSSL binary
 243      ("openssl"). The libraries will be built in the top-level directory,
 244      and the binary will be in the "apps" subdirectory.
 245
 246      If the build fails, look at the output.  There may be reasons for
 247      the failure that aren't problems in OpenSSL itself (like missing
 248      standard headers).  If it is a problem with OpenSSL itself, please
 249      report the problem to <rt@openssl.org> (note that your message
 250      will be recorded in the request tracker publicly readable at
 251      https://www.openssl.org/community/index.html#bugs and will be
 252      forwarded to a public mailing list). Include the output of "make
 253      report" in your message.  Please check out the request tracker. Maybe
 254      the bug was already reported or has already been fixed.
 255
 256      [If you encounter assembler error messages, try the "no-asm"
 257      configuration option as an immediate fix.]
 258
 259      Compiling parts of OpenSSL with gcc and others with the system
 260      compiler will result in unresolved symbols on some systems.
 261
 262   3. After a successful build, the libraries should be tested. Run:
 263
 264        $ make test                                      # Unix
 265        $ mms test                                       ! OpenVMS
 266
 267      If some tests fail, look at the output.  There may be reasons for
 268      the failure that isn't a problem in OpenSSL itself (like a
 269      malfunction with Perl).  You may want increased verbosity, that
 270      can be accomplished like this:
 271
 272        $ HARNESS_VERBOSE=yes make test                  # Unix
 273
 274        $ DEFINE HARNESS_VERBOSE YES
 275        $ mms test                                       ! OpenVMS
 276
 277      If you want to run just one or a few specific tests, you can use
 278      the make variable TESTS to specify them, like this:
 279
 280        $ make TESTS='test_rsa test_dsa' test            # Unix
 281        $ mms/macro="TESTS=test_rsa test_dsa" test       ! OpenVMS
 282
 283      And of course, you can combine (Unix example shown):
 284
 285        $ HARNESS_VERBOSE=yes make TESTS='test_rsa test_dsa' test
 286
 287      You can find the list of available tests like this:
 288
 289        $ make list-tests                                # Unix
 290        $ make list-tests                                ! OpenVMS
 291
 292      Have a look at the manual for the perl module Test::Harness to
 293      see what other HARNESS_* variables there are.
 294
 295      If you find a problem with OpenSSL itself, try removing any
 296      compiler optimization flags from the CFLAGS line in Makefile and
 297      run "make clean; make" or corresponding.
 298
 299      Please send a bug report to <openssl-bugs@openssl.org>, and when
 300      you do, please run the following and include the output in your
 301      report:
 302
 303        $ make report
 304
 305   4. If everything tests ok, install OpenSSL with
 306
 307        $ make install                                   # Unix
 308        $ mms install                                    ! OpenVMS
 309
 310      This will install all the software components in this directory
 311      tree under PREFIX (the directory given with --prefix or its
 312      default):
 313
 314        Unix:
 315
 316          bin/           Contains the openssl binary and a few other
 317                         utility scripts.
 318          include/openssl
 319                         Contains the header files needed if you want
 320                         to build your own programs that use libcrypto
 321                         or libssl.
 322          lib            Contains the OpenSSL library files.
 323          lib/engines    Contains the OpenSSL dynamically loadable engines.
 324          share/man/{man1,man3,man5,man7}
 325                         Contains the OpenSSL man-pages.
 326          share/doc/openssl/html{man1,man3,man5,man7}
 327                         Contains the HTML rendition of the man-pages.
 328
 329        OpenVMS ('arch' is replaced with the architecture name, "Alpha"
 330        or "ia64"):
 331
 332          [.EXE.'arch']  Contains the openssl binary and a few other
 333                         utility scripts.
 334          [.include.openssl]
 335                         Contains the header files needed if you want
 336                         to build your own programs that use libcrypto
 337                         or libssl.
 338          [.LIB.'arch']  Contains the OpenSSL library files.
 339          [.ENGINES.'arch']
 340                         Contains the OpenSSL dynamically loadable engines.
 341          [.SYS$STARTUP] Contains startup, login and shutdown scripts.
 342                         These define appropriate logical names and
 343                         command symbols.
 344
 345
 346      Additionally, install will add the following directories under
 347      OPENSSLDIR (the directory given with --openssldir or its default)
 348      for you convenience:
 349
 350          certs          Initially empty, this is the default location
 351                         for certificate files.
 352          private        Initially empty, this is the default location
 353                         for private key files.
 354          misc           Various scripts.
 355
 356      Package builders who want to configure the library for standard
 357      locations, but have the package installed somewhere else so that
 358      it can easily be packaged, can use
 359
 360        $ make DESTDIR=/tmp/package-root install         # Unix
 361        $ mms/macro="DESTDIR=TMP:[PACKAGE-ROOT]" install ! OpenVMS
 362
 363      The specified destination directory will be prepended to all
 364      installation target paths.
 365
 366   Compatibility issues with previous OpenSSL versions:
 367
 368   *  COMPILING existing applications
 369
 370      OpenSSL 1.1 hides a number of structures that were previously
 371      open.  This includes all internal libssl structures and a number
 372      of EVP types.  Accessor functions have been added to allow
 373      controlled access to the structures' data.
 374
 375      This means that some software needs to be rewritten to adapt to
 376      the new ways of doing things.  This often amounts to allocating
 377      an instance of a structure explicitly where you could previously
 378      allocate them on the stack as automatic variables, and using the
 379      provided accessor functions where you would previously access a
 380      structure's field directly.
 381
 382      <TBA>
 383
 384      Some APIs have changed as well.  However, older APIs have been
 385      preserved when possible.
 386
 387
 388  Note on multi-threading
 389  -----------------------
 390
 391  For some systems, the OpenSSL Configure script knows what compiler options
 392  are needed to generate a library that is suitable for multi-threaded
 393  applications.  On these systems, support for multi-threading is enabled
 394  by default; use the "no-threads" option to disable (this should never be
 395  necessary).
 396
 397  On other systems, to enable support for multi-threading, you will have
 398  to specify at least two options: "threads", and a system-dependent option.
 399  (The latter is "-D_REENTRANT" on various systems.)  The default in this
 400  case, obviously, is not to include support for multi-threading (but
 401  you can still use "no-threads" to suppress an annoying warning message
 402  from the Configure script.)
 403
 404  OpenSSL provides built-in support for two threading models: pthreads (found on
 405  most UNIX/Linux systems), and Windows threads. No other threading models are
 406  supported. If your platform does not provide pthreads or Windows threads then
 407  you should Configure with the "no-threads" option.
 408
 409  Note on shared libraries
 410  ------------------------
 411
 412  Shared libraries have certain caveats.  Binary backward compatibility
 413  can't be guaranteed before OpenSSL version 1.0.  The only reason to
 414  use them would be to conserve memory on systems where several programs
 415  are using OpenSSL.
 416
 417  For some systems, the OpenSSL Configure script knows what is needed to
 418  build shared libraries for libcrypto and libssl.  On these systems,
 419  the shared libraries are currently not created by default, but giving
 420  the option "shared" will get them created.  This method supports Makefile
 421  targets for shared library creation, like linux-shared.  Those targets
 422  can currently be used on their own just as well, but this is expected
 423  to change in future versions of OpenSSL.
 424
 425  Note on random number generation
 426  --------------------------------
 427
 428  Availability of cryptographically secure random numbers is required for
 429  secret key generation. OpenSSL provides several options to seed the
 430  internal PRNG. If not properly seeded, the internal PRNG will refuse
 431  to deliver random bytes and a "PRNG not seeded error" will occur.
 432  On systems without /dev/urandom (or similar) device, it may be necessary
 433  to install additional support software to obtain random seed.
 434  Please check out the manual pages for RAND_add(), RAND_bytes(), RAND_egd(),
 435  and the FAQ for more information.
 436