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