INSTALL

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