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 one 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 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: 95: Note 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: 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 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: 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