INSTALL.VMS

   1                         VMS Installation instructions
   2                         written by Richard Levitte
   3                         <richard@levitte.org>
   4
   5
   6 Intro:
   7 ======
   8
   9 This file is divided in the following parts:
  10
  11   Requirements                  - Mandatory reading.
  12   Checking the distribution     - Mandatory reading.
  13   Compilation                   - Mandatory reading.
  14   Logical names                 - Mandatory reading.
  15   Test                          - Mandatory reading.
  16   Installation                  - Mandatory reading.
  17   Backward portability          - Read if it's an issue.
  18   Possible bugs or quirks       - A few warnings on things that
  19                                   may go wrong or may surprise you.
  20   TODO                          - Things that are to come.
  21
  22
  23 Requirements:
  24 =============
  25
  26 To build and install OpenSSL, you will need:
  27
  28  * DEC C or some other ANSI C compiler.  VAX C is *not* supported.
  29    [Note: OpenSSL has only been tested with DEC C.  Compiling with
  30     a different ANSI C compiler may require some work]
  31
  32 Checking the distribution:
  33 ==========================
  34
  35 There have been reports of places where the distribution didn't quite get
  36 through, for example if you've copied the tree from a NFS-mounted unix
  37 mount point.
  38
  39 The easiest way to check if everything got through as it should is to check
  40 for oen of the following files:
  41
  42         [.CRYPTO]OPENSSLCONF.H_IN
  43         [.CRYPTO]OPENSSLCONF_H.IN
  44
  45 They should never exist both at once, but one of them should (preferably
  46 the first variant).  If you can't find any of those two, something went
  47 wrong.
  48
  49 The best way to get a correct distribution is to download the gzipped tar
  50 file from ftp://ftp.openssl.org/source/, use GUNZIP to uncompress it and
  51 use VMSTAR to unpack the resulting tar file.
  52
  53 GUNZIP is available in many places on the net.  One of the distribution
  54 points is the WKU software archive, ftp://ftp.wku.edu/vms/fileserv/ .
  55
  56 VMSTAR is also available in many places on the net.  The recommended place
  57 to find information about it is http://www.free.lp.se/vmstar/ .
  58
  59
  60 Compilation:
  61 ============
  62
  63 I've used the very good command procedures written by Robert Byer
  64 <byer@mail.all-net.net>, and just slightly modified them, making
  65 them slightly more general and easier to maintain.
  66
  67 You can actually compile in almost any directory separately.  Look
  68 for a command procedure name xxx-LIB.COM (in the library directories)
  69 or MAKExxx.COM (in the program directories) and read the comments at
  70 the top to understand how to use them.  However, if you want to
  71 compile all you can get, the simplest is to use MAKEVMS.COM in the top
  72 directory.  The syntax is trhe following:
  73
  74   @MAKEVMS <option> <rsaref-p> <debug-p> [<compiler>]
  75
  76 <option> must be one of the following:
  77
  78       ALL       Just build "everything".
  79       CONFIG    Just build the "[.CRYPTO]OPENSSLCONF.H" file.
  80       BUILDINF  Just build the "[.INCLUDE]BUILDINF.H" file.
  81       SOFTLINKS Just copies some files, to simulate Unix soft links.
  82       BUILDALL  Same as ALL, except CONFIG, BUILDINF and SOFTILNKS aren't done.
  83       RSAREF    Just build the "[.xxx.EXE.RSAREF]LIBRSAGLUE.OLB" library.
  84       CRYPTO    Just build the "[.xxx.EXE.CRYPTO]LIBCRYPTO.OLB" library.
  85       SSL       Just build the "[.xxx.EXE.SSL]LIBSSL.OLB" library.
  86       SSL_TASK  Just build the "[.xxx.EXE.SSL]SSL_TASK.EXE" program.
  87       TEST      Just build the "[.xxx.EXE.TEST]" test programs for OpenSSL.
  88       APPS      Just build the "[.xxx.EXE.APPS]" application programs for OpenSSL.
  89
  90 <rsaref-p> must be one of the following:
  91
  92       RSAREF    compile using the RSAREF Library
  93       NORSAREF  compile without using RSAREF
  94
  95 Note 0: The RASREF library IS NO LONGER NEEDED.  The RSA patent
  96         expires September 20, 2000, and RSA Security chose to make
  97         the algorithm public domain two weeks before that.
  98
  99 Note 1: If you still want to use RSAREF, the library is NOT INCLUDED
 100         and you have to download it.  RSA Security doesn't carry it
 101         any more, but there are a number of places where you can find
 102         it.  You have to get the ".tar-Z" file as the ".zip" file
 103         doesn't have the directory structure stored.  You have to
 104         extract the file into the [.RSAREF] directory as that is where
 105         the scripts will look for the files.
 106
 107 Note 2: I have never done this, so I've no idea if it works or not.
 108
 109 <debug-p> must be one of the following:
 110
 111       DEBUG     compile with debugging info (will not optimize)
 112       NODEBUG   compile without debugging info (will optimize)
 113
 114 <compiler> must be one of the following:
 115
 116       DECC      For DEC C.
 117       GNUC      For GNU C.
 118
 119
 120 You will find the crypto library in [.xxx.EXE.CRYPTO], called LIBCRYPTO.OLB,
 121 where xxx is VAX or AXP.  You will find the SSL library in [.xxx.EXE.SSL],
 122 named LIBSSL.OLB, and you will find a bunch of useful programs in
 123 [.xxx.EXE.APPS].  However, these shouldn't be used right off unless it's
 124 just to test them.  For production use, make sure you install first, see
 125 Installation below.
 126
 127 Note 1: Some programs in this package require a TCP/IP library.
 128
 129 Note 2: if you want to compile the crypto library only, please make sure
 130         you have at least done a @MAKEVMS CONFIG, a @MAKEVMS BUILDINF and
 131         a @MAKEVMS SOFTLINKS.  A lot of things will break if you don't.
 132
 133
 134 Logical names:
 135 ==============
 136
 137 There are a few things that can't currently be given through the command
 138 line.  Instead, logical names are used.
 139
 140 Currently, the logical names supported are:
 141
 142       OPENSSL_NO_ASM    with value YES, the assembler parts of OpenSSL will
 143                         not be used.  Instead, plain C implementations are
 144                         used.  This is good to try if something doesn't work.
 145       OPENSSL_NO_'alg'  with value YES, the corresponding crypto algorithm
 146                         will not be implemented.  Supported algorithms to
 147                         do this with are: RSA, DSA, DH, MD2, MD4, MD5, RIPEMD,
 148                         SHA, DES, MDC2, CR2, RC4, RC5, IDEA, BF, CAST, HMAC,
 149                         SSL2.  So, for example, having the logical name
 150                         OPENSSL_NO_RSA with the value YES means that the
 151                         LIBCRYPTO.OLB library will not contain an RSA
 152                         implementation.
 153
 154
 155 Test:
 156 =====
 157
 158 Testing is very simple, just do the following:
 159
 160   @[.TEST]TESTS
 161
 162 If a test fails, try with defining the logical name OPENSSL_NO_ASM (yes,
 163 it's an ugly hack!) and rebuild. Please send a bug report to
 164 <openssl-bugs@openssl.org>, including the output of "openssl version -a"
 165 and of the failed test.
 166
 167
 168 Installation:
 169 =============
 170
 171 Installation is easy, just do the following:
 172
 173   @INSTALL <root>
 174
 175 <root> is the directory in which everything will be installed,
 176 subdirectories, libraries, header files, programs and startup command
 177 procedures.
 178
 179 N.B.: INSTALL.COM builds a new directory structure, different from
 180 the directory tree where you have now build OpenSSL.
 181
 182 In the [.VMS] subdirectory of the installation, you will find the
 183 following command procedures:
 184
 185   OPENSSL_STARTUP.COM
 186
 187         defines all needed logical names.  Takes one argument that
 188         tells it in what logical name table to insert the logical
 189         names.  If you insert if it SYS$MANAGER:SYSTARTUP_VMS.COM, the
 190         call should look like this:
 191
 192           @openssldev:[openssldir.VMS]OPENSSL_STARTUP "/SYSTEM"
 193
 194   OPENSSL_UTILS.COM
 195
 196         sets up the symbols to the applications.  Should be called
 197         from for example SYS$MANAGER:SYLOGIN.COM
 198
 199 The logical names that are set up are the following:
 200
 201   SSLROOT       a dotted concealed logical name pointing at the
 202                 root directory.
 203
 204   SSLCERTS      Initially an empty directory, this is the default
 205                 location for certificate files.
 206   SSLMISC       Various scripts.
 207   SSLPRIVATE    Initially an empty directory, this is the default
 208                 location for private key files.
 209
 210   SSLEXE        Contains the openssl binary and a few other utility
 211                 programs.
 212   SSLINCLUDE    Contains the header files needed if you want to
 213                 compile programs with libcrypto or libssl.
 214   SSLLIB        Contains the OpenSSL library files (LIBCRYPTO.OLB
 215                 and LIBSSL.OLB) themselves.
 216
 217   OPENSSL       Same as SSLINCLUDE.  This is because the standard
 218                 way to include OpenSSL header files from version
 219                 0.9.3 and on is:
 220
 221                         #include <openssl/header.h>
 222
 223                 For more info on this issue, see the INSTALL. file
 224                 (the NOTE in section 4 of "Installation in Detail").
 225                 You don't need to "deleting old header files"!!!
 226
 227
 228 Backward portability:
 229 =====================
 230
 231 One great problem when you build a library is making sure it will work
 232 on as many versions of VMS as possible.  Especially, code compiled on
 233 OpenVMS version 7.x and above tend to be unusable in version 6.x or
 234 lower, because some C library routines have changed names internally
 235 (the C programmer won't usually see it, because the old name is
 236 maintained through C macros).  One obvious solution is to make sure
 237 you have a development machine with an old enough version of OpenVMS.
 238 However, if you are stuck with a bunch of Alphas running OpenVMS version
 239 7.1, you seem to be out of luck.  Fortunately, the DEC C header files
 240 are cluttered with conditionals that make some declarations and definitions
 241 dependent on the OpenVMS version or the C library version, *and* you
 242 can use those macros to simulate older OpenVMS or C library versions,
 243 by defining the macros _VMS_V6_SOURCE, __VMS_VER and __CTRL_VER with
 244 correct values.  In the compilation scripts, I've provided the possibility
 245 for the user to influence the creation of such macros, through a bunch of
 246 symbols, all having names starting with USER_.  Here's the list of them:
 247
 248   USER_CCFLAGS           - Used to give additional qualifiers to the
 249                            compiler.  It can't be used to define macros
 250                            since the scripts will do such things as well.
 251                            To do such things, use USER_CCDEFS.
 252   USER_CCDEFS            - Used to define macros on the command line.  The
 253                            value of this symbol will be inserted inside a
 254                            /DEFINE=(...).
 255   USER_CCDISABLEWARNINGS - Used to disable some warnings.  The value is
 256                            inserted inside a /DISABLE=WARNING=(...).
 257
 258 So, to maintain backward compatibility with older VMS versions, do the
 259 following before you start compiling:
 260
 261   $ USER_CCDEFS := _VMS_V6_SOURCE=1,__VMS_VER=60000000,__CRTL_VER=60000000
 262   $ USER_CCDISABLEWARNINGS := PREOPTW
 263
 264 The USER_CCDISABLEWARNINGS is there because otherwise, DEC C will complain
 265 that those macros have been changed.
 266
 267 Note: Currently, this is only usefull for library compilation.  The
 268       programs will still be linked with the current version of the
 269       C library shareable image, and will thus complain if they are
 270       faced with an older version of the same C library shareable image.
 271       This will probably be fixed in a future revision of OpenSSL.
 272
 273
 274 Possible bugs or quirks:
 275 ========================
 276
 277 I'm not perfectly sure all the programs will use the SSLCERTS:
 278 directory by default, it may very well be that you have to give them
 279 extra arguments.  Please experiment.
 280
 281
 282 TODO:
 283 =====
 284
 285 There are a few things that need to be worked out in the VMS version of
 286 OpenSSL, still:
 287
 288 - Description files. ("Makefile's" :-))
 289 - Script code to link an already compiled build tree.
 290 - A VMSINSTALlable version (way in the future, unless someone else hacks).
 291 - shareable images (DLL for you Windows folks).
 292
 293 There may be other things that I have missed and that may be desirable.
 294 Please send mail to <openssl-users@openssl.org> or to me directly if you
 295 have any ideas.
 296
 297 --
 298 Richard Levitte <richard@levitte.org>
 299 2000-02-27