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> <bits> <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<bits> must be one of the following: 91 92 "" compile using default pointer size 93 32 compile using 32 bit pointer size 94 64 compile using 64 bit pointer size 95 96<debug-p> must be one of the following: 97 98 DEBUG compile with debugging info (will not optimize) 99 NODEBUG compile without debugging info (will optimize) 100 101<compiler> must be one of the following: 102 103 DECC For DEC C. 104 GNUC For GNU C. 105 106 107You will find the crypto library in [.xxx.EXE.CRYPTO] (where xxx is VAX, 108ALPHA or IA64), called SSL_LIBCRYPTO32.OLB or SSL_LIBCRYPTO.OLB depending 109on how it was built. You will find the SSL library in [.xxx.EXE.SSL], 110named SSL_LIBSSL32.OLB or SSL_LIBSSL.OLB, and you will find a bunch of 111useful programs in [.xxx.EXE.APPS]. However, these shouldn't be used 112right off unless it's just to test them. For production use, make sure 113you install first, see Installation below. 114 115Note 1: Some programs in this package require a TCP/IP library. 116 117Note 2: if you want to compile the crypto library only, please make sure 118 you have at least done a @MAKEVMS CONFIG, a @MAKEVMS BUILDINF and 119 a @MAKEVMS SOFTLINKS. A lot of things will break if you don't. 120 121 122Logical names: 123============== 124 125There are a few things that can't currently be given through the command 126line. Instead, logical names are used. 127 128Currently, the logical names supported are: 129 130 OPENSSL_NO_ASM with value YES, the assembler parts of OpenSSL will 131 not be used. Instead, plain C implementations are 132 used. This is good to try if something doesn't work. 133 OPENSSL_NO_'alg' with value YES, the corresponding crypto algorithm 134 will not be implemented. Supported algorithms to 135 do this with are: RSA, DSA, DH, MD2, MD4, MD5, RIPEMD, 136 SHA, DES, MDC2, CR2, RC4, RC5, IDEA, BF, CAST, HMAC, 137 SSL2. So, for example, having the logical name 138 OPENSSL_NO_RSA with the value YES means that the 139 LIBCRYPTO.OLB library will not contain an RSA 140 implementation. 141 142 143Test: 144===== 145 146Testing is very simple, just do the following: 147 148 @[.TEST]TESTS 149 150If a test fails, try with defining the logical name OPENSSL_NO_ASM (yes, 151it's an ugly hack!) and rebuild. Please send a bug report to 152<openssl-bugs@openssl.org>, including the output of "openssl version -a" 153and of the failed test. 154 155 156Installation: 157============= 158 159Installation is easy, just do the following: 160 161 @INSTALL <root> <bits> 162 163<root> is the directory in which everything will be installed, 164subdirectories, libraries, header files, programs and startup command 165procedures. 166 167<bits> works the same way as for MAKEVMS.COM 168 169N.B.: INSTALL.COM builds a new directory structure, different from 170the directory tree where you have now build OpenSSL. 171 172In the [.VMS] subdirectory of the installation, you will find the 173following command procedures: 174 175 OPENSSL_STARTUP.COM 176 177 defines all needed logical names. Takes one argument that 178 tells it in what logical name table to insert the logical 179 names. If you insert if it SYS$MANAGER:SYSTARTUP_VMS.COM, the 180 call should look like this: 181 182 @openssldev:[openssldir.VMS]OPENSSL_STARTUP "/SYSTEM" 183 184 OPENSSL_UTILS.COM 185 186 sets up the symbols to the applications. Should be called 187 from for example SYS$MANAGER:SYLOGIN.COM 188 189 OPENSSL_UNDO.COM 190 191 deassigns the logical names created with OPENSSL_STARTUP.COM. 192 193The logical names that are set up are the following: 194 195 SSLROOT a dotted concealed logical name pointing at the 196 root directory. 197 198 SSLCERTS Initially an empty directory, this is the default 199 location for certificate files. 200 SSLPRIVATE Initially an empty directory, this is the default 201 location for private key files. 202 203 SSLEXE Contains the openssl binary and a few other utility 204 programs. 205 SSLINCLUDE Contains the header files needed if you want to 206 compile programs with libcrypto or libssl. 207 SSLLIB Contains the OpenSSL library files themselves: 208 - SSL_LIBCRYPTO32.OLB and SSL_LIBSSL32.OLB or 209 - SSL_LIBCRYPTO.OLB and SSL_LIBSSL.OLB 210 211 OPENSSL Same as SSLINCLUDE. This is because the standard 212 way to include OpenSSL header files from version 213 0.9.3 and on is: 214 215 #include <openssl/header.h> 216 217 For more info on this issue, see the INSTALL. file 218 (the NOTE in section 4 of "Installation in Detail"). 219 You don't need to "deleting old header files"!!! 220 221 222Backward portability: 223===================== 224 225One great problem when you build a library is making sure it will work 226on as many versions of VMS as possible. Especially, code compiled on 227OpenVMS version 7.x and above tend to be unusable in version 6.x or 228lower, because some C library routines have changed names internally 229(the C programmer won't usually see it, because the old name is 230maintained through C macros). One obvious solution is to make sure 231you have a development machine with an old enough version of OpenVMS. 232However, if you are stuck with a bunch of Alphas running OpenVMS version 2337.1, you seem to be out of luck. Fortunately, the DEC C header files 234are cluttered with conditionals that make some declarations and definitions 235dependent on the OpenVMS version or the C library version, *and* you 236can use those macros to simulate older OpenVMS or C library versions, 237by defining the macros _VMS_V6_SOURCE, __VMS_VER and __CTRL_VER with 238correct values. In the compilation scripts, I've provided the possibility 239for the user to influence the creation of such macros, through a bunch of 240symbols, all having names starting with USER_. Here's the list of them: 241 242 USER_CCFLAGS - Used to give additional qualifiers to the 243 compiler. It can't be used to define macros 244 since the scripts will do such things as well. 245 To do such things, use USER_CCDEFS. 246 USER_CCDEFS - Used to define macros on the command line. The 247 value of this symbol will be inserted inside a 248 /DEFINE=(...). 249 USER_CCDISABLEWARNINGS - Used to disable some warnings. The value is 250 inserted inside a /DISABLE=WARNING=(...). 251 252So, to maintain backward compatibility with older VMS versions, do the 253following before you start compiling: 254 255 $ USER_CCDEFS := _VMS_V6_SOURCE=1,__VMS_VER=60000000,__CRTL_VER=60000000 256 $ USER_CCDISABLEWARNINGS := PREOPTW 257 258The USER_CCDISABLEWARNINGS is there because otherwise, DEC C will complain 259that those macros have been changed. 260 261Note: Currently, this is only useful for library compilation. The 262 programs will still be linked with the current version of the 263 C library shareable image, and will thus complain if they are 264 faced with an older version of the same C library shareable image. 265 This will probably be fixed in a future revision of OpenSSL. 266 267 268Possible bugs or quirks: 269======================== 270 271I'm not perfectly sure all the programs will use the SSLCERTS: 272directory by default, it may very well be that you have to give them 273extra arguments. Please experiment. 274 275 276TODO: 277===== 278 279There are a few things that need to be worked out in the VMS version of 280OpenSSL, still: 281 282- Description files. ("Makefile's" :-)) 283- Script code to link an already compiled build tree. 284- A VMSINSTALlable version (way in the future, unless someone else hacks). 285- shareable images (DLL for you Windows folks). 286 287There may be other things that I have missed and that may be desirable. 288Please send mail to <openssl-users@openssl.org> or to me directly if you 289have any ideas. 290 291-- 292Richard Levitte <richard@levitte.org> 2932000-02-27, 2011-03-18 294