Back to home page

openssl Cross Reference

 
 

    


0001 
0002  INSTALLATION ON THE UNIX PLATFORM
0003  ---------------------------------
0004 
0005  [Installation on DOS (with djgpp), Windows, OpenVMS, MacOS (before MacOS X)
0006   and NetWare is described in INSTALL.DJGPP, INSTALL.W32, INSTALL.VMS,
0007   INSTALL.MacOS and INSTALL.NW.
0008   
0009   This document describes installation on operating systems in the Unix
0010   family.]
0011 
0012  To install OpenSSL, you will need:
0013 
0014   * make
0015   * Perl 5
0016   * an ANSI C compiler
0017   * a development environment in form of development libraries and C
0018     header files
0019   * a supported Unix operating system
0020 
0021  Quick Start
0022  -----------
0023 
0024  If you want to just get on with it, do:
0025 
0026   $ ./config
0027   $ make
0028   $ make test
0029   $ make install
0030 
0031  [If any of these steps fails, see section Installation in Detail below.]
0032 
0033  This will build and install OpenSSL in the default location, which is (for
0034  historical reasons) /usr/local/ssl. If you want to install it anywhere else,
0035  run config like this:
0036 
0037   $ ./config --prefix=/usr/local --openssldir=/usr/local/openssl
0038 
0039 
0040  Configuration Options
0041  ---------------------
0042 
0043  There are several options to ./config (or ./Configure) to customize
0044  the build:
0045 
0046   --prefix=DIR  Install in DIR/bin, DIR/lib, DIR/include/openssl.
0047                 Configuration files used by OpenSSL will be in DIR/ssl
0048                 or the directory specified by --openssldir.
0049 
0050   --openssldir=DIR Directory for OpenSSL files. If no prefix is specified,
0051                 the library files and binaries are also installed there.
0052 
0053   no-threads    Don't try to build with support for multi-threaded
0054                 applications.
0055 
0056   threads       Build with support for multi-threaded applications.
0057                 This will usually require additional system-dependent options!
0058                 See "Note on multi-threading" below.
0059 
0060   no-zlib       Don't try to build with support for zlib compression and
0061                 decompression.
0062 
0063   zlib          Build with support for zlib compression/decompression.
0064 
0065   zlib-dynamic  Like "zlib", but has OpenSSL load the zlib library dynamically
0066                 when needed.  This is only supported on systems where loading
0067                 of shared libraries is supported.  This is the default choice.
0068 
0069   no-shared     Don't try to create shared libraries.
0070 
0071   shared        In addition to the usual static libraries, create shared
0072                 libraries on platforms where it's supported.  See "Note on
0073                 shared libraries" below.
0074 
0075   no-asm        Do not use assembler code.
0076 
0077   386           Use the 80386 instruction set only (the default x86 code is
0078                 more efficient, but requires at least a 486). Note: Use
0079                 compiler flags for any other CPU specific configuration,
0080                 e.g. "-m32" to build x86 code on an x64 system.
0081 
0082   no-sse2       Exclude SSE2 code pathes. Normally SSE2 extention is
0083                 detected at run-time, but the decision whether or not the
0084                 machine code will be executed is taken solely on CPU
0085                 capability vector. This means that if you happen to run OS
0086                 kernel which does not support SSE2 extension on Intel P4
0087                 processor, then your application might be exposed to
0088                 "illegal instruction" exception. There might be a way
0089                 to enable support in kernel, e.g. FreeBSD kernel can be
0090                 compiled with CPU_ENABLE_SSE, and there is a way to
0091                 disengage SSE2 code pathes upon application start-up,
0092                 but if you aim for wider "audience" running such kernel,
0093                 consider no-sse2. Both 386 and no-asm options above imply
0094                 no-sse2.
0095 
0096   no-<cipher>   Build without the specified cipher (bf, cast, des, dh, dsa,
0097                 hmac, md2, md5, mdc2, rc2, rc4, rc5, rsa, sha).
0098                 The crypto/<cipher> directory can be removed after running
0099                 "make depend".
0100 
0101   -Dxxx, -lxxx, -Lxxx, -fxxx, -mXXX, -Kxxx These system specific options will
0102                 be passed through to the compiler to allow you to
0103                 define preprocessor symbols, specify additional libraries,
0104                 library directories or other compiler options.
0105 
0106   -DHAVE_CRYPTODEV Enable the BSD cryptodev engine even if we are not using
0107                 BSD. Useful if you are running ocf-linux or something
0108                 similar. Once enabled you can also enable the use of
0109                 cryptodev digests, which is usually slower unless you have
0110                 large amounts data. Use -DUSE_CRYPTODEV_DIGESTS to force
0111                 it.
0112 
0113  Installation in Detail
0114  ----------------------
0115 
0116  1a. Configure OpenSSL for your operation system automatically:
0117 
0118        $ ./config [options]
0119 
0120      This guesses at your operating system (and compiler, if necessary) and
0121      configures OpenSSL based on this guess. Run ./config -t to see
0122      if it guessed correctly. If you want to use a different compiler, you
0123      are cross-compiling for another platform, or the ./config guess was
0124      wrong for other reasons, go to step 1b. Otherwise go to step 2.
0125 
0126      On some systems, you can include debugging information as follows:
0127 
0128        $ ./config -d [options]
0129 
0130  1b. Configure OpenSSL for your operating system manually
0131 
0132      OpenSSL knows about a range of different operating system, hardware and
0133      compiler combinations. To see the ones it knows about, run
0134 
0135        $ ./Configure
0136 
0137      Pick a suitable name from the list that matches your system. For most
0138      operating systems there is a choice between using "cc" or "gcc".  When
0139      you have identified your system (and if necessary compiler) use this name
0140      as the argument to ./Configure. For example, a "linux-elf" user would
0141      run:
0142 
0143        $ ./Configure linux-elf [options]
0144 
0145      If your system is not available, you will have to edit the Configure
0146      program and add the correct configuration for your system. The
0147      generic configurations "cc" or "gcc" should usually work on 32 bit
0148      systems.
0149 
0150      Configure creates the file Makefile.ssl from Makefile.org and
0151      defines various macros in crypto/opensslconf.h (generated from
0152      crypto/opensslconf.h.in).
0153 
0154   2. Build OpenSSL by running:
0155 
0156        $ make
0157 
0158      This will build the OpenSSL libraries (libcrypto.a and libssl.a) and the
0159      OpenSSL binary ("openssl"). The libraries will be built in the top-level
0160      directory, and the binary will be in the "apps" directory.
0161 
0162      If "make" fails, look at the output.  There may be reasons for
0163      the failure that aren't problems in OpenSSL itself (like missing
0164      standard headers).  If it is a problem with OpenSSL itself, please
0165      report the problem to <openssl-bugs@openssl.org> (note that your
0166      message will be recorded in the request tracker publicly readable
0167      via http://www.openssl.org/support/rt.html and will be forwarded to a
0168      public mailing list). Include the output of "make report" in your message.
0169      Please check out the request tracker. Maybe the bug was already
0170      reported or has already been fixed.
0171 
0172      [If you encounter assembler error messages, try the "no-asm"
0173      configuration option as an immediate fix.]
0174 
0175      Compiling parts of OpenSSL with gcc and others with the system
0176      compiler will result in unresolved symbols on some systems.
0177 
0178   3. After a successful build, the libraries should be tested. Run:
0179 
0180        $ make test
0181 
0182      If a test fails, look at the output.  There may be reasons for
0183      the failure that isn't a problem in OpenSSL itself (like a missing
0184      or malfunctioning bc).  If it is a problem with OpenSSL itself,
0185      try removing any compiler optimization flags from the CFLAG line
0186      in Makefile.ssl and run "make clean; make". Please send a bug
0187      report to <openssl-bugs@openssl.org>, including the output of
0188      "make report" in order to be added to the request tracker at
0189      http://www.openssl.org/support/rt.html.
0190 
0191   4. If everything tests ok, install OpenSSL with
0192 
0193        $ make install
0194 
0195      This will create the installation directory (if it does not exist) and
0196      then the following subdirectories:
0197 
0198        certs           Initially empty, this is the default location
0199                        for certificate files.
0200        man/man1        Manual pages for the 'openssl' command line tool
0201        man/man3        Manual pages for the libraries (very incomplete)
0202        misc            Various scripts.
0203        private         Initially empty, this is the default location
0204                        for private key files.
0205 
0206      If you didn't choose a different installation prefix, the
0207      following additional subdirectories will be created:
0208 
0209        bin             Contains the openssl binary and a few other 
0210                        utility programs. 
0211        include/openssl Contains the header files needed if you want to
0212                        compile programs with libcrypto or libssl.
0213        lib             Contains the OpenSSL library files themselves.
0214 
0215      Use "make install_sw" to install the software without documentation,
0216      and "install_docs_html" to install HTML renditions of the manual
0217      pages.
0218 
0219      Package builders who want to configure the library for standard
0220      locations, but have the package installed somewhere else so that
0221      it can easily be packaged, can use
0222 
0223        $ make INSTALL_PREFIX=/tmp/package-root install
0224 
0225      (or specify "--install_prefix=/tmp/package-root" as a configure
0226      option).  The specified prefix will be prepended to all
0227      installation target filenames.
0228 
0229 
0230   NOTE: The header files used to reside directly in the include
0231   directory, but have now been moved to include/openssl so that
0232   OpenSSL can co-exist with other libraries which use some of the
0233   same filenames.  This means that applications that use OpenSSL
0234   should now use C preprocessor directives of the form
0235 
0236        #include <openssl/ssl.h>
0237 
0238   instead of "#include <ssl.h>", which was used with library versions
0239   up to OpenSSL 0.9.2b.
0240 
0241   If you install a new version of OpenSSL over an old library version,
0242   you should delete the old header files in the include directory.
0243 
0244   Compatibility issues:
0245 
0246   *  COMPILING existing applications
0247 
0248      To compile an application that uses old filenames -- e.g.
0249      "#include <ssl.h>" --, it will usually be enough to find
0250      the CFLAGS definition in the application's Makefile and
0251      add a C option such as
0252 
0253           -I/usr/local/ssl/include/openssl
0254 
0255      to it.
0256 
0257      But don't delete the existing -I option that points to
0258      the ..../include directory!  Otherwise, OpenSSL header files
0259      could not #include each other.
0260 
0261   *  WRITING applications
0262 
0263      To write an application that is able to handle both the new
0264      and the old directory layout, so that it can still be compiled
0265      with library versions up to OpenSSL 0.9.2b without bothering
0266      the user, you can proceed as follows:
0267 
0268      -  Always use the new filename of OpenSSL header files,
0269         e.g. #include <openssl/ssl.h>.
0270 
0271      -  Create a directory "incl" that contains only a symbolic
0272         link named "openssl", which points to the "include" directory
0273         of OpenSSL.
0274         For example, your application's Makefile might contain the
0275         following rule, if OPENSSLDIR is a pathname (absolute or
0276         relative) of the directory where OpenSSL resides:
0277 
0278         incl/openssl:
0279                 -mkdir incl
0280                 cd $(OPENSSLDIR) # Check whether the directory really exists
0281                 -ln -s `cd $(OPENSSLDIR); pwd`/include incl/openssl
0282 
0283         You will have to add "incl/openssl" to the dependencies
0284         of those C files that include some OpenSSL header file.
0285 
0286      -  Add "-Iincl" to your CFLAGS.
0287 
0288      With these additions, the OpenSSL header files will be available
0289      under both name variants if an old library version is used:
0290      Your application can reach them under names like <openssl/foo.h>,
0291      while the header files still are able to #include each other
0292      with names of the form <foo.h>.
0293 
0294 
0295  Note on multi-threading
0296  -----------------------
0297 
0298  For some systems, the OpenSSL Configure script knows what compiler options
0299  are needed to generate a library that is suitable for multi-threaded
0300  applications.  On these systems, support for multi-threading is enabled
0301  by default; use the "no-threads" option to disable (this should never be
0302  necessary).
0303 
0304  On other systems, to enable support for multi-threading, you will have
0305  to specify at least two options: "threads", and a system-dependent option.
0306  (The latter is "-D_REENTRANT" on various systems.)  The default in this
0307  case, obviously, is not to include support for multi-threading (but
0308  you can still use "no-threads" to suppress an annoying warning message
0309  from the Configure script.)
0310 
0311 
0312  Note on shared libraries
0313  ------------------------
0314 
0315  Shared libraries have certain caveats.  Binary backward compatibility
0316  can't be guaranteed before OpenSSL version 1.0.  The only reason to
0317  use them would be to conserve memory on systems where several programs
0318  are using OpenSSL.
0319 
0320  For some systems, the OpenSSL Configure script knows what is needed to
0321  build shared libraries for libcrypto and libssl.  On these systems,
0322  the shared libraries are currently not created by default, but giving
0323  the option "shared" will get them created.  This method supports Makefile
0324  targets for shared library creation, like linux-shared.  Those targets
0325  can currently be used on their own just as well, but this is expected
0326  to change in future versions of OpenSSL.
0327 
0328  Note on random number generation
0329  --------------------------------
0330 
0331  Availability of cryptographically secure random numbers is required for
0332  secret key generation. OpenSSL provides several options to seed the
0333  internal PRNG. If not properly seeded, the internal PRNG will refuse
0334  to deliver random bytes and a "PRNG not seeded error" will occur.
0335  On systems without /dev/urandom (or similar) device, it may be necessary
0336  to install additional support software to obtain random seed.
0337  Please check out the manual pages for RAND_add(), RAND_bytes(), RAND_egd(),
0338  and the FAQ for more information.
0339 
0340  Note on support for multiple builds
0341  -----------------------------------
0342 
0343  OpenSSL is usually built in its source tree.  Unfortunately, this doesn't
0344  support building for multiple platforms from the same source tree very well.
0345  It is however possible to build in a separate tree through the use of lots
0346  of symbolic links, which should be prepared like this:
0347 
0348         mkdir -p objtree/"`uname -s`-`uname -r`-`uname -m`"
0349         cd objtree/"`uname -s`-`uname -r`-`uname -m`"
0350         (cd $OPENSSL_SOURCE; find . -type f) | while read F; do
0351                 mkdir -p `dirname $F`
0352                 rm -f $F; ln -s $OPENSSL_SOURCE/$F $F
0353                 echo $F '->' $OPENSSL_SOURCE/$F
0354         done
0355         make -f Makefile.org clean
0356 
0357  OPENSSL_SOURCE is an environment variable that contains the absolute (this
0358  is important!) path to the OpenSSL source tree.
0359 
0360  Also, operations like 'make update' should still be made in the source tree.