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 ('major'_'minor').
  59   Windows: currently don't have an install function     <TBA>
  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:           PREFIX/ssl (PREFIX is given by --prefix)
  91                    Windows:        C:\Program Files\Common Files\SSL
  92                                 or C:\Program Files (x86)\Common Files\SSL
  93                    OpenVMS:        SYS$COMMON:[SSL]
  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