1 VMS Installation instructions 2 written by Richard Levitte 3 <richard@levitte.org> 4 5 6Intro: 7====== 8 9This 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 23Requirements: 24============= 25 26To 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 32Checking the distribution: 33========================== 34 35There have been reports of places where the distribution didn't quite get 36through, for example if you've copied the tree from a NFS-mounted Unix 37mount point. 38 39The easiest way to check if everything got through as it should is to check 40for one of the following files: 41 42 [.CRYPTO]OPENSSLCONF.H_IN 43 [.CRYPTO]OPENSSLCONF_H.IN 44 45They should never exist both at once, but one of them should (preferably 46the first variant). If you can't find any of those two, something went 47wrong. 48 49The best way to get a correct distribution is to download the gzipped tar 50file from ftp://ftp.openssl.org/source/, use GUNZIP to uncompress it and 51use VMSTAR to unpack the resulting tar file. 52 53GUNZIP is available in many places on the net. One of the distribution 54points is the WKU software archive, ftp://ftp.wku.edu/vms/fileserv/ . 55 56VMSTAR is also available in many places on the net. The recommended place 57to find information about it is http://www.free.lp.se/vmstar/ . 58 59 60Compilation: 61============ 62 63I've used the very good command procedures written by Robert Byer 64<byer@mail.all-net.net>, and just slightly modified them, making 65them slightly more general and easier to maintain. 66 67You can actually compile in almost any directory separately. Look 68for a command procedure name xxx-LIB.COM (in the library directories) 69or MAKExxx.COM (in the program directories) and read the comments at 70the top to understand how to use them. However, if you want to 71compile all you can get, the simplest is to use MAKEVMS.COM in the top 72directory. The syntax is the 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 SOFTLINKS 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 95Note 0: The RSAREF 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 99Note 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 107Note 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 120You will find the crypto library in [.xxx.EXE.CRYPTO], called LIBCRYPTO.OLB, 121where xxx is VAX or AXP. You will find the SSL library in [.xxx.EXE.SSL], 122named 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 124just to test them. For production use, make sure you install first, see 125Installation below. 126 127Note 1: Some programs in this package require a TCP/IP library. 128 129Note 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 134Logical names: 135============== 136 137There are a few things that can't currently be given through the command 138line. Instead, logical names are used. 139 140Currently, 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 155Test: 156===== 157 158Testing is very simple, just do the following: 159 160 @[.TEST]TESTS 161 162If a test fails, try with defining the logical name OPENSSL_NO_ASM (yes, 163it's an ugly hack!) and rebuild. Please send a bug report to 164<openssl-bugs@openssl.org>, including the output of "openssl version -a" 165and of the failed test. 166 167 168Installation: 169============= 170 171Installation is easy, just do the following: 172 173 @INSTALL <root> 174 175<root> is the directory in which everything will be installed, 176subdirectories, libraries, header files, programs and startup command 177procedures. 178 179N.B.: INSTALL.COM builds a new directory structure, different from 180the directory tree where you have now build OpenSSL. 181 182In the [.VMS] subdirectory of the installation, you will find the 183following 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 199The 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 228Backward portability: 229===================== 230 231One great problem when you build a library is making sure it will work 232on as many versions of VMS as possible. Especially, code compiled on 233OpenVMS version 7.x and above tend to be unusable in version 6.x or 234lower, because some C library routines have changed names internally 235(the C programmer won't usually see it, because the old name is 236maintained through C macros). One obvious solution is to make sure 237you have a development machine with an old enough version of OpenVMS. 238However, if you are stuck with a bunch of Alphas running OpenVMS version 2397.1, you seem to be out of luck. Fortunately, the DEC C header files 240are cluttered with conditionals that make some declarations and definitions 241dependent on the OpenVMS version or the C library version, *and* you 242can use those macros to simulate older OpenVMS or C library versions, 243by defining the macros _VMS_V6_SOURCE, __VMS_VER and __CTRL_VER with 244correct values. In the compilation scripts, I've provided the possibility 245for the user to influence the creation of such macros, through a bunch of 246symbols, 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 258So, to maintain backward compatibility with older VMS versions, do the 259following before you start compiling: 260 261 $ USER_CCDEFS := _VMS_V6_SOURCE=1,__VMS_VER=60000000,__CRTL_VER=60000000 262 $ USER_CCDISABLEWARNINGS := PREOPTW 263 264The USER_CCDISABLEWARNINGS is there because otherwise, DEC C will complain 265that those macros have been changed. 266 267Note: Currently, this is only useful 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 274Possible bugs or quirks: 275======================== 276 277I'm not perfectly sure all the programs will use the SSLCERTS: 278directory by default, it may very well be that you have to give them 279extra arguments. Please experiment. 280 281 282TODO: 283===== 284 285There are a few things that need to be worked out in the VMS version of 286OpenSSL, 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 293There may be other things that I have missed and that may be desirable. 294Please send mail to <openssl-users@openssl.org> or to me directly if you 295have any ideas. 296 297-- 298Richard Levitte <richard@levitte.org> 2992000-02-27 300