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