Make s_server, s_client check cipher list return codes.
[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   Compilation                   - Mandatory reading.
12   Test                          - Mandatory reading.
13   Installation                  - Mandatory reading.
14   Backward portability          - Read if it's an issue.
15   Possible bugs or quirks       - A few warnings on things that
16                                   may go wrong or may surprise you.
17   Report                        - How to get in touch with me.
18
19 Compilation:
20 ============
21
22 I've used the very good command procedures written by Robert Byer
23 <byer@mail.all-net.net>, and just slightly modified them, making
24 them slightly more general and easier to maintain.
25
26 You can actually compile in almost any directory separately.  Look
27 for a command procedure name xxx-LIB.COM (in the library directories)
28 or MAKExxx.COM (in the program directories) and read the comments at
29 the top to understand how to use them.  However, if you want to
30 compile all you can get, the simplest is to use MAKEVMS.COM in the top
31 directory.  The syntax is trhe following:
32
33   @MAKEVMS <option> <rsaref-p> <debug-p> [<compiler>]
34
35 <option> must be one of the following:
36
37       ALL       Just build "everything".
38       DATE      Just build the "[.INCLUDE]DATE.H" file.
39       SOFTLINKS Just copies some files, to simulate Unix soft links.
40       RSAREF    Just build the "[.xxx.EXE.RSAREF]LIBRSAGLUE.OLB" library.
41       CRYPTO    Just build the "[.xxx.EXE.CRYPTO]LIBCRYPTO.OLB" library.
42       SSL       Just build the "[.xxx.EXE.SSL]LIBSSL.OLB" library.
43       SSL_TASK  Just build the "[.xxx.EXE.SSL]SSL_TASK.EXE" program.
44       TEST      Just build the "test" programs for OpenSSL.
45       APPS      Just build the "application" programs for OpenSSL.
46
47 <rsaref-p> must be one of the following:
48
49       RSAREF    compile using the RSAREF Library
50       NORSAREF  compile without using RSAREF
51
52 Note: The RSAREF libraries are NOT INCLUDED and you have to
53       download it from "ftp://ftp.rsa.com/rsaref".  You have to
54       get the ".tar-Z" file as the ".zip" file dosen't have the
55       directory structure stored.  You have to extract the file
56       into the [.RSAREF] directory as that is where the scripts
57       will look for the files.
58
59 Note 2: I have never done this, so I've no idea if it works or not.
60
61 <debug-p> must be one of the following:
62
63       DEBUG     compile with debugging info (will not optimize)
64       NODEBUG   compile without debugging info (will optimize)
65
66 <compiler> must be one of the following:
67
68       VAXC      For VAX C.
69       DECC      For DEC C.
70       GNUC      For GNU C.
71
72
73 You will find the crypto library in [.xxx.EXE.CRYPTO], called LIBCRYPTO.OLB,
74 where xxx is VAX or AXP.  You will find the SSL library in [.xxx.EXE.SSL],
75 named LIBSSL.OLB, and you will find a bunch of useful programs in
76 [.xxx.EXE.APPS].  However, these shouldn't be used right off unless it's
77 just to test them.  For production use, make sure you install first, see
78 Installation below.
79
80 Note: Some programs in this package require a TCP/IP library.
81
82 Note 2: if you want to compile the crypto library only, please make sure
83         you have at least done a @MAKEVMS DATE and a @MAKEVMS SOFTLINKS.
84         A lot of things will break if you don't.
85
86 Note 3: Alpha users will get a number of informational messages when
87         compiling the [.asm]vms.mar file in the BN (bignum) part of
88         the crypto library.  These can be safely ignored.
89
90 Test:
91 =====
92
93 Testing is very simple, just do the following:
94
95   @[.TEST]TESTS
96
97 If a test fails, try with defining the logical name OPENSSL_NO_ASM (yes,
98 it's an ugly hack!) and rebuild. Please send a bug report to
99 <openssl-bugs@openssl.org>, including the output of "openssl version -a"
100 and of the failed test.
101
102 Installation:
103 =============
104
105 Installation is easy, just do the following:
106
107   @INSTALL <root>
108
109 <root> is the directory in which everything will be installed,
110 subdirectories, libraries, header files, programs and startup command
111 procedures.
112
113 N.B.: INSTALL.COM builds a new directory structure, different from
114 the directory tree where you have now build OpenSSL.
115
116 In the [.VMS] subdirectory of the installation, you will find the
117 following command procedures:
118
119   OPENSSL_STARTUP.COM
120
121         defines all needed logical names.  Takes one argument that
122         tells it in what logical name table to insert the logical
123         names.  If you insert if it SYS$MANAGER:SYSTARTUP_VMS.COM, the
124         call should look like this: 
125
126           @openssldev:[openssldir.VMS]OPENSSL_STARTUP "/SYSTEM"
127
128   OPENSSL_UTILS.COM
129
130         sets up the symbols to the applications.  Should be called
131         from for example SYS$MANAGER:SYLOGIN.COM 
132
133 The logical names that are set up are the following:
134
135   SSLROOT       a dotted concealed logical name pointing at the
136                 root directory.
137
138   SSLCERTS      Initially an empty directory, this is the default
139                 location for certificate files.
140   SSLMISC       Various scripts.
141   SSLPRIVATE    Initially an empty directory, this is the default
142                 location for private key files.
143
144   SSLEXE        Contains the openssl binary and a few other utility
145                 programs.
146   SSLINCLUDE    Contains the header files needed if you want to
147                 compile programs with libcrypto or libssl.
148   SSLLIB        Contains the OpenSSL library files (LIBCRYPTO.OLB
149                 and LIBSSL.OLB) themselves.
150
151   OPENSSL       Same as SSLINCLUDE.  This is because the standard
152                 way to include OpenSSL header files from version
153                 0.9.3 and on is:
154
155                         #include <openssl/header.h>
156
157                 For more info on this issue, see the INSTALL. file
158                 (the NOTE in section 4 of "Installation in Detail").
159                 You don't need to "deleting old header files"!!!
160
161 Backward portability:
162 =====================
163
164 One great problem when you build a library is making sure it will work
165 on as many versions of VMS as possible.  Especially, code compiled on
166 OpenVMS version 7.x and above tend to be unusable in version 6.x or
167 lower, because some C library routines have changed names internally
168 (the C programmer won't usually see it, because the old name is
169 maintained through C macros).  One obvious solution is to make sure
170 you have a development machine with an old enough version of OpenVMS.
171 However, if you are stuck with a bunch of Alphas running OpenVMS version
172 7.1, you seem to be out of luck.  Fortunately, the DEC C header files
173 are cluttered with conditionals that make some declarations and definitions
174 dependent on the OpenVMS version or the C library version, *and* you
175 can use those macros to simulate older OpenVMS or C library versions,
176 by defining the macros _VMS_V6_SOURCE, __VMS_VER and __CTRL_VER with
177 correct values.  In the compilation scripts, I've provided the possibility
178 for the user to influense the creation of such macros, through a bunch of
179 symbols, all having names starting with USER_.  Here's the list of them:
180
181   USER_CCFLAGS           - Used to give additional qualifiers to the
182                            compiler.  It can't be used to define macros
183                            since the scripts will do such things as well.
184                            To do such things, use USER_CCDEFS.
185   USER_CCDEFS            - Used to define macros on the command line.  The
186                            value of this symbol will be inserted inside a
187                            /DEFINE=(...).
188   USER_CCDISABLEWARNINGS - Used to disable some warnings.  The value is
189                            inserted inside a /DISABLE=WARNING=(...).
190
191 So, to maintain backward compatibility with older VMS versions, do the
192 following before you start compiling:
193
194   $ USER_CCDEFS := _VMS_V6_SOURCE=1,__VMS_VER=60000000,__CRTL_VER=60000000
195   $ USER_CCDISABLEWARNINGS := PREOPTW
196
197 The USER_CCDISABLEWARNINGS is there because otherwise, DEC C will complain
198 that those macros have been changed.
199
200 Note: Currently, this is only usefull for library compilation.  The
201       programs will still be linked with the current version of the
202       C library shareable image, and will thus complain if they are
203       faced with an older version of the same C library shareable image.
204       This will probably be fixed in a future revision of OpenSSL.
205
206
207 Possible bugs or quirks:
208 ========================
209
210 I'm not perfectly sure all the programs will use the SSLCERTS:
211 directory by default, it may very well be that you have to give them
212 extra arguments.  Please experiment.
213
214
215 Report:
216 =======
217
218 I maintain a few mailinglists for bug reports and such on software that
219 I develop/port/enhance/destroy.  Please look at http://www.free.lp.se/
220 for further info.
221
222
223 -- 
224 Richard Levitte <richard@levitte.org>
225 1999-03-09
226
227
228 TODO:
229 =====
230
231 There are a few things that need to be worked out in the VMS version of
232 OpenSSL, still:
233
234 - Description files. ("Makefile's" :-))
235 - Script code to link an already compiled build tree.
236 - A VMSINSTALlable version (way in the future, unless someone else hacks).
237 - shareable images (DLL for you Windows folks).
238
239 There may be other things that I have missed and that may be desirable.
240 Please send mail to <openssl-users@openssl.org> or to me directly if you
241 have any ideas.
242
243 --
244 Richard Levitte <richard@levitte.org>
245 1999-05-24