]>
Commit | Line | Data |
---|---|---|
7d7d2cbc UM |
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 | ||
713f2261 | 11 | Requirements - Mandatory reading. |
2e98ec56 | 12 | Checking the distribution - Mandatory reading. |
7d7d2cbc | 13 | Compilation - Mandatory reading. |
2e98ec56 | 14 | Logical names - Mandatory reading. |
7d7d2cbc UM |
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. | |
2e98ec56 RL |
20 | TODO - Things that are to come. |
21 | ||
22 | ||
713f2261 RL |
23 | Requirements: |
24 | ============= | |
25 | ||
26 | To build and install OpenSSL, you will need: | |
27 | ||
187bad4c RL |
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/ | |
713f2261 RL |
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 | ||
2e98ec56 RL |
34 | Checking the distribution: |
35 | ========================== | |
36 | ||
37 | There have been reports of places where the distribution didn't quite get | |
3b80e3aa | 38 | through, for example if you've copied the tree from a NFS-mounted Unix |
2e98ec56 RL |
39 | mount point. |
40 | ||
41 | The easiest way to check if everything got through as it should is to check | |
3b80e3aa | 42 | for one of the following files: |
2e98ec56 RL |
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/ . | |
7d7d2cbc | 60 | |
1a8b087a | 61 | |
7d7d2cbc UM |
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 | |
3b80e3aa | 74 | directory. The syntax is the following: |
7d7d2cbc | 75 | |
537c9823 | 76 | @MAKEVMS <option> <bits> <debug-p> [<compiler>] |
7d7d2cbc UM |
77 | |
78 | <option> must be one of the following: | |
79 | ||
80 | ALL Just build "everything". | |
1a8b087a RL |
81 | CONFIG Just build the "[.CRYPTO]OPENSSLCONF.H" file. |
82 | BUILDINF Just build the "[.INCLUDE]BUILDINF.H" file. | |
7d7d2cbc | 83 | SOFTLINKS Just copies some files, to simulate Unix soft links. |
3b80e3aa | 84 | BUILDALL Same as ALL, except CONFIG, BUILDINF and SOFTLINKS aren't done. |
7d7d2cbc UM |
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. | |
1a8b087a RL |
88 | TEST Just build the "[.xxx.EXE.TEST]" test programs for OpenSSL. |
89 | APPS Just build the "[.xxx.EXE.APPS]" application programs for OpenSSL. | |
7d7d2cbc | 90 | |
537c9823 | 91 | <bits> must be one of the following: |
7d7d2cbc | 92 | |
537c9823 RL |
93 | "" compile using default pointer size |
94 | 32 compile using 32 bit pointer size | |
95 | 64 compile using 64 bit pointer size | |
7d7d2cbc UM |
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 | ||
7d7d2cbc UM |
104 | DECC For DEC C. |
105 | GNUC For GNU C. | |
106 | ||
107 | ||
537c9823 RL |
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. | |
7d7d2cbc | 115 | |
1a8b087a | 116 | Note 1: Some programs in this package require a TCP/IP library. |
7d7d2cbc UM |
117 | |
118 | Note 2: if you want to compile the crypto library only, please make sure | |
1a8b087a RL |
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. | |
4fdde1aa RL |
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, | |
e36827f6 | 139 | ERR, GOST, HEARTBEATS, HMAC, IDEA, MD2, MD4, |
4fdde1aa | 140 | MD5, OCB, OCSP, PSK, RC2, RC4, RC5, RMD160, RSA, SCTP, |
e481f9b9 | 141 | SEED, SOCK, SRP, SRTP, WHIRLPOOL. So, for |
4fdde1aa RL |
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. | |
58dc480f | 151 | |
7d7d2cbc UM |
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 | ||
1a8b087a | 164 | |
7d7d2cbc UM |
165 | Installation: |
166 | ============= | |
167 | ||
168 | Installation is easy, just do the following: | |
169 | ||
537c9823 | 170 | @INSTALL <root> <bits> |
7d7d2cbc UM |
171 | |
172 | <root> is the directory in which everything will be installed, | |
173 | subdirectories, libraries, header files, programs and startup command | |
174 | procedures. | |
175 | ||
537c9823 RL |
176 | <bits> works the same way as for MAKEVMS.COM |
177 | ||
58dc480f BM |
178 | N.B.: INSTALL.COM builds a new directory structure, different from |
179 | the directory tree where you have now build OpenSSL. | |
180 | ||
7d7d2cbc UM |
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 | ||
537c9823 RL |
198 | OPENSSL_UNDO.COM |
199 | ||
200 | deassigns the logical names created with OPENSSL_STARTUP.COM. | |
201 | ||
7d7d2cbc UM |
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. | |
7d7d2cbc | 206 | |
9dff4cc0 UM |
207 | SSLCERTS Initially an empty directory, this is the default |
208 | location for certificate files. | |
9dff4cc0 UM |
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. | |
537c9823 RL |
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 | |
9dff4cc0 UM |
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"!!! | |
7d7d2cbc | 229 | |
1a8b087a | 230 | |
7d7d2cbc UM |
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 | |
657e60fa | 248 | for the user to influence the creation of such macros, through a bunch of |
7d7d2cbc UM |
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 | ||
3b80e3aa | 270 | Note: Currently, this is only useful for library compilation. The |
7d7d2cbc UM |
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 | ||
58dc480f BM |
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> | |
537c9823 | 302 | 2000-02-27, 2011-03-18 |