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