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