INSTALL

   1 Installing OpenSSL on Unix
   2 --------------------------
   3
   4 [For instructions for compiling OpenSSL on Windows systems, see
   5 INSTALL.W32].
   6
   7 To install OpenSSL, you will need:
   8
   9   * Perl
  10   * C compiler
  11   * A supported operating system
  12
  13 Quick Start
  14 -----------
  15
  16 If you want to just get on with it, do:
  17
  18   sh config                      [if this fails, go to step 1b below]
  19   make
  20   make rehash
  21   make test
  22   make install
  23
  24 This will build and install OpenSSL in the default location, which is
  25 /usr/local/ssl. If you want to install it anywhere else, do this
  26 after running ./Configure <system>:
  27
  28   perl util/ssldir.pl /new/install/path
  29
  30 If anything goes wrong, follow the detailed instructions below. If
  31 your operating system is not (yet) supported by OpenSSL, see the
  32 section on porting to a new system.
  33
  34 Installation in Detail
  35 ----------------------
  36
  37  1a. Configure OpenSSL for your operation system automatically
  38
  39      Run
  40
  41        sh config
  42
  43      This guesses at your operating system (and compiler, if
  44      necessary) and configures OpenSSL based on this guess. Check the
  45      first line of output to see if it guessed correctly. If it did
  46      not get it correct or you want to use a different compiler then
  47      go to step 1b. Otherwise go to step 2.
  48
  49  1b. Configure OpenSSL for your operating system manually
  50
  51      OpenSSL knows about a range of different operating system, hardware
  52      and compiler combinations. To see the ones it knows about, run
  53
  54        ./Configure
  55
  56      Pick a suitable name from the list that matches your system. For
  57      most operating systems there is a choice between using "cc" or
  58      "gcc".
  59
  60      When you have identified your system (and if necessary compiler)
  61      use this name as the argument to ./Configure. For example, a
  62      "linux-elf" user would run:
  63
  64        ./Configure linux-elf
  65
  66      If your system is not available, you will have to edit the Configure
  67      program and add the correct configuration for your system.
  68
  69      Configure configures various files by converting an existing .org
  70      file into the real file. If you edit any files, remember that if
  71      a corresponding .org file exists them the next time you run
  72      ./Configure your changes will be lost when the file gets
  73      re-created from the .org file. The files that are created from
  74      .org files are:
  75
  76        Makefile.ssl
  77        crypto/des/des.h
  78        crypto/des/des_locl.h
  79        crypto/md2/md2.h
  80        crypto/rc4/rc4.h
  81        crypto/rc4/rc4_enc.c
  82        crypto/rc2/rc2.h
  83        crypto/bf/bf_locl.h
  84        crypto/idea/idea.h
  85        crypto/bn/bn.h
  86
  87   2. Set the install directory
  88
  89      If the install directory will be the default of /usr/local/ssl,
  90      skip to the next stage. Otherwise, run
  91
  92        perl util/ssldir.pl /new/install/path
  93
  94      This configures the installation location into the "install"
  95      target of the top-level Makefile, and also updates some defines
  96      in an include file so that the default certificate directory is
  97      under the proper installation directory. It also updates a few
  98      utility files used in the build process.
  99
 100   3. Build OpenSSL
 101
 102      Now run
 103
 104        make
 105
 106      This will build the OpenSSL libraries (libcrypto.a and libssl.a)
 107      and the OpenSSL binary ("openssl"). The libraries will be built
 108      in the top-level directory, and the binary will be in the "apps"
 109      directory.
 110
 111   4. After a successful build, the libraries should be tested. Run
 112
 113        make rehash
 114        make test
 115
 116      (The first line makes the test certificates in the "certs"
 117      directory accessable via an hash name, which is required for some
 118      of the tests).
 119
 120   5. If everything tests ok, install OpenSSL with
 121
 122        make install
 123
 124      This will create the installation directory (if it does not
 125      exist) and then create the following subdirectories:
 126
 127        bin            Contains the openssl binary and a few other utility
 128                       programs. It also contains symbolic links so
 129                       that openssl commands can be accessed directly
 130                       (e.g. so that "s_client" can be used instead of
 131                       "openssl s_client").
 132        certs          Initially empty, this is the default location
 133                       for certificate files.
 134        include        Contains the header files needed if you want to
 135                       compile programs with libcrypto or libssl.
 136        lib            Contains the library files themselves and the
 137                       OpenSSL configuration file "openssl.cnf".
 138        private        Initially empty, this is the default location
 139                       for private key files.
 140
 141 ----------------------------------------------------------------------
 142
 143 Additional Compilation Notes
 144 ----------------------------
 145
 146 These notes come from SSLeay 0.9.1 and cover some more advanced
 147 facilities (such as building a single makefile for use on Windows
 148 systems).
 149
 150
 151 # Installation of SSLeay.
 152 # It depends on perl for a few bits but those steps can be skipped and
 153 # the top level makefile edited by hand
 154
 155 # When bringing the SSLeay distribution back from the evil intel world
 156 # of Windows NT, do the following to make it nice again under unix :-)
 157 # You don't normally need to run this.
 158 sh util/fixNT.sh        # This only works for NT now - eay - 21-Jun-1996
 159
 160 # If you have perl, and it is not in /usr/local/bin, you can run
 161 perl util/perlpath.pl /new/path
 162 # and this will fix the paths in all the scripts.  DO NOT put
 163 # /new/path/perl, just /new/path. The build
 164 # environment always run scripts as 'perl perlscript.pl' but some of the
 165 # 'applications' are easier to usr with the path fixed.
 166
 167 # Edit crypto/cryptlib.h, tools/c_rehash, and Makefile.ssl
 168 # to set the install locations if you don't like
 169 # the default location of /usr/local/ssl
 170 # Do this by running
 171 perl util/ssldir.pl /new/ssl/home
 172 # if you have perl, or by hand if not.
 173
 174 # If things have been stuffed up with the sym links, run
 175 make -f Makefile.ssl links
 176 # This will re-populate lib/include with symlinks and for each
 177 # directory, link Makefile to Makefile.ssl
 178
 179 # Setup the machine dependent stuff for the top level makefile
 180 # and some select .h files
 181 # If you don't have perl, this will bomb, in which case just edit the
 182 # top level Makefile.ssl
 183 ./Configure 'system type'
 184
 185 # The 'Configure' command contains default configuration parameters
 186 # for lots of machines.  Configure edits 5 lines in the top level Makefile
 187 # It modifies the following values in the following files
 188 Makefile.ssl            CC CFLAG EX_LIBS BN_MULW
 189 crypto/des/des.h        DES_LONG
 190 crypto/des/des_locl.h   DES_PTR
 191 crypto/md2/md2.h        MD2_INT
 192 crypto/rc4/rc4.h        RC4_INT
 193 crypto/rc4/rc4_enc.c    RC4_INDEX
 194 crypto/rc2/rc2.h        RC2_INT
 195 crypto/bf/bf_locl.h     BF_INT
 196 crypto/idea/idea.h      IDEA_INT
 197 crypto/bn/bn.h          BN_LLONG (and defines one of SIXTY_FOUR_BIT,
 198                                   SIXTY_FOUR_BIT_LONG, THIRTY_TWO_BIT,
 199                                   SIXTEEN_BIT or EIGHT_BIT)
 200 Please remember that all these files are actually copies of the file with
 201 a .org extention.  So if you change crypto/des/des.h, the next time
 202 you run Configure, it will be runover by a 'configured' version of
 203 crypto/des/des.org.  So to make the changer the default, change the .org
 204 files.  The reason these files have to be edited is because most of
 205 these modifications change the size of fundamental data types.
 206 While in theory this stuff is optional, it often makes a big
 207 difference in performance and when using assember, it is importaint
 208 for the 'Bignum bits' match those required by the assember code.
 209 A warning for people using gcc with sparc cpu's.  Gcc needs the -mv8
 210 flag to use the hardware multiply instruction which was not present in
 211 earlier versions of the sparc CPU.  I define it by default.  If you
 212 have an old sparc, and it crashes, try rebuilding with this flag
 213 removed.  I am leaving this flag on by default because it makes
 214 things run 4 times faster :-)
 215
 216 # clean out all the old stuff
 217 make clean
 218
 219 # Do a make depend only if you have the makedepend command installed
 220 # This is not needed but it does make things nice when developing.
 221 make depend
 222
 223 # make should build everything
 224 make
 225
 226 # fix up the demo certificate hash directory if it has been stuffed up.
 227 make rehash
 228
 229 # test everything
 230 make test
 231
 232 # install the lot
 233 make install
 234
 235 # It is worth noting that all the applications are built into the one
 236 # program, ssleay, which is then has links from the other programs
 237 # names to it.
 238 # The applicatons can be built by themselves, just don't define the
 239 # 'MONOLITH' flag.  So to build the 'enc' program stand alone,
 240 gcc -O2 -Iinclude apps/enc.c apps/apps.c libcrypto.a
 241
 242 # Other useful make options are
 243 make makefile.one
 244 # which generate a 'makefile.one' file which will build the complete
 245 # SSLeay distribution with temp. files in './tmp' and 'installable' files
 246 # in './out'
 247
 248 # Have a look at running
 249 perl util/mk1mf.pl help
 250 # this can be used to generate a single makefile and is about the only
 251 # way to generate makefiles for windows.
 252
 253 # There is actually a final way of building SSLeay.
 254 gcc -O2 -c -Icrypto -Iinclude crypto/crypto.c
 255 gcc -O2 -c -Issl -Iinclude ssl/ssl.c
 256 # and you now have the 2 libraries as single object files :-).
 257 # If you want to use the assember code for your particular platform
 258 # (DEC alpha/x86 are the main ones, the other assember is just the
 259 # output from gcc) you will need to link the assember with the above generated
 260 # object file and also do the above compile as
 261 gcc -O2 -DBN_ASM -c -Icrypto -Iinclude crypto/crypto.c
 262
 263 This last option is probably the best way to go when porting to another
 264 platform or building shared libraries.  It is not good for development so
 265 I don't normally use it.
 266
 267 To build shared libararies under unix, have a look in shlib, basically
 268 you are on your own, but it is quite easy and all you have to do
 269 is compile 2 (or 3) files.
 270
 271 For mult-threading, have a read of doc/threads.doc.  Again it is quite
 272 easy and normally only requires some extra callbacks to be defined
 273 by the application.
 274 The examples for solaris and windows NT/95 are in the mt directory.
 275
 276 have fun
 277
 278 eric 25-Jun-1997
 279
 280 IRIX 5.x will build as a 32 bit system with mips1 assember.
 281 IRIX 6.x will build as a 64 bit system with mips3 assember.  It conforms
 282 to n32 standards. In theory you can compile the 64 bit assember under
 283 IRIX 5.x but you will have to have the correct system software installed.