RT3962: Check accept_count only if not unlimited
[openssl.git] / INSTALL.VMS
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> <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       TEST      Just build the "[.xxx.EXE.TEST]" test programs for OpenSSL.
87       APPS      Just build the "[.xxx.EXE.APPS]" application programs for OpenSSL.
88
89 <bits> must be one of the following:
90
91       ""        compile using default pointer size
92       32        compile using 32 bit pointer size
93       64        compile using 64 bit pointer size
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
102       DECC      For DEC C.
103       GNUC      For GNU C.
104
105
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.
113
114 Note 1: Some programs in this package require a TCP/IP library.
115
116 Note 2: if you want to compile the crypto library only, please make sure
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.
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, MD2, MD4,
138                         MD5, OCB, OCSP, PSK, RC2, RC4, RC5, RMD160, RSA, SCTP,
139                         SEED, SOCK, SRP, SRTP, 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.
149
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
162
163 Installation:
164 =============
165
166 Installation is easy, just do the following:
167
168   @INSTALL <root> <bits>
169
170 <root> is the directory in which everything will be installed,
171 subdirectories, libraries, header files, programs and startup command
172 procedures.
173
174 <bits> works the same way as for MAKEVMS.COM
175
176 N.B.: INSTALL.COM builds a new directory structure, different from
177 the directory tree where you have now build OpenSSL.
178
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
196   OPENSSL_UNDO.COM
197
198         deassigns the logical names created with OPENSSL_STARTUP.COM.
199
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.
204
205   SSLCERTS      Initially an empty directory, this is the default
206                 location for certificate files.
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 themselves:
215                 - SSL_LIBCRYPTO32.OLB and SSL_LIBSSL32.OLB or
216                 - SSL_LIBCRYPTO.OLB and SSL_LIBSSL.OLB
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"!!!
227
228
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
246 for the user to influence the creation of such macros, through a bunch of
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
268 Note: Currently, this is only useful for library compilation.  The
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
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>
300 2000-02-27, 2011-03-18