]>
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 UM |
73 | |
74 | @MAKEVMS <option> <rsaref-p> <debug-p> [<compiler>] | |
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. | |
86 | SSL_TASK Just build the "[.xxx.EXE.SSL]SSL_TASK.EXE" program. | |
1a8b087a RL |
87 | TEST Just build the "[.xxx.EXE.TEST]" test programs for OpenSSL. |
88 | APPS Just build the "[.xxx.EXE.APPS]" application programs for OpenSSL. | |
7d7d2cbc UM |
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 | ||
3b80e3aa | 95 | Note 0: The RSAREF library IS NO LONGER NEEDED. The RSA patent |
282f92f7 RL |
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. | |
7d7d2cbc UM |
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 | ||
7d7d2cbc UM |
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 | ||
1a8b087a | 127 | Note 1: Some programs in this package require a TCP/IP library. |
7d7d2cbc UM |
128 | |
129 | Note 2: if you want to compile the crypto library only, please make sure | |
1a8b087a RL |
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 | |
282f92f7 | 147 | do this with are: RSA, DSA, DH, MD2, MD4, MD5, RIPEMD, |
1a8b087a RL |
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. | |
7d7d2cbc | 153 | |
58dc480f | 154 | |
7d7d2cbc UM |
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 | ||
1a8b087a | 167 | |
7d7d2cbc UM |
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 | ||
58dc480f BM |
179 | N.B.: INSTALL.COM builds a new directory structure, different from |
180 | the directory tree where you have now build OpenSSL. | |
181 | ||
7d7d2cbc UM |
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. | |
7d7d2cbc | 203 | |
9dff4cc0 UM |
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"!!! | |
7d7d2cbc | 226 | |
1a8b087a | 227 | |
7d7d2cbc UM |
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 | |
657e60fa | 245 | for the user to influence the creation of such macros, through a bunch of |
7d7d2cbc UM |
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 | ||
3b80e3aa | 267 | Note: Currently, this is only useful for library compilation. The |
7d7d2cbc UM |
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 | ||
58dc480f BM |
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> | |
1a8b087a | 299 | 2000-02-27 |