Back to home page

openssl Cross Reference

 
 

    


0001                         VMS Installation instructions
0002                         written by Richard Levitte
0003                         <richard@levitte.org>
0004 
0005 
0006 Intro:
0007 ======
0008 
0009 This file is divided in the following parts:
0010 
0011   Requirements                  - Mandatory reading.
0012   Checking the distribution     - Mandatory reading.
0013   Compilation                   - Mandatory reading.
0014   Logical names                 - Mandatory reading.
0015   Test                          - Mandatory reading.
0016   Installation                  - Mandatory reading.
0017   Backward portability          - Read if it's an issue.
0018   Possible bugs or quirks       - A few warnings on things that
0019                                   may go wrong or may surprise you.
0020   TODO                          - Things that are to come.
0021 
0022 
0023 Requirements:
0024 =============
0025 
0026 To build and install OpenSSL, you will need:
0027 
0028  * DEC C or some other ANSI C compiler.  VAX C is *not* supported.
0029    [Note: OpenSSL has only been tested with DEC C.  Compiling with 
0030     a different ANSI C compiler may require some work]
0031 
0032 Checking the distribution:
0033 ==========================
0034 
0035 There have been reports of places where the distribution didn't quite get
0036 through, for example if you've copied the tree from a NFS-mounted Unix
0037 mount point.
0038 
0039 The easiest way to check if everything got through as it should is to check
0040 for one of the following files:
0041 
0042         [.CRYPTO]OPENSSLCONF.H_IN
0043         [.CRYPTO]OPENSSLCONF_H.IN
0044 
0045 They should never exist both at once, but one of them should (preferably
0046 the first variant).  If you can't find any of those two, something went
0047 wrong.
0048 
0049 The best way to get a correct distribution is to download the gzipped tar
0050 file from ftp://ftp.openssl.org/source/, use GUNZIP to uncompress it and
0051 use VMSTAR to unpack the resulting tar file.
0052 
0053 GUNZIP is available in many places on the net.  One of the distribution
0054 points is the WKU software archive, ftp://ftp.wku.edu/vms/fileserv/ .
0055 
0056 VMSTAR is also available in many places on the net.  The recommended place
0057 to find information about it is http://www.free.lp.se/vmstar/ .
0058 
0059 
0060 Compilation:
0061 ============
0062 
0063 I've used the very good command procedures written by Robert Byer
0064 <byer@mail.all-net.net>, and just slightly modified them, making
0065 them slightly more general and easier to maintain.
0066 
0067 You can actually compile in almost any directory separately.  Look
0068 for a command procedure name xxx-LIB.COM (in the library directories)
0069 or MAKExxx.COM (in the program directories) and read the comments at
0070 the top to understand how to use them.  However, if you want to
0071 compile all you can get, the simplest is to use MAKEVMS.COM in the top
0072 directory.  The syntax is the following:
0073 
0074   @MAKEVMS <option> <bits> <debug-p> [<compiler>]
0075 
0076 <option> must be one of the following:
0077 
0078       ALL       Just build "everything".
0079       CONFIG    Just build the "[.CRYPTO]OPENSSLCONF.H" file.
0080       BUILDINF  Just build the "[.INCLUDE]BUILDINF.H" file.
0081       SOFTLINKS Just copies some files, to simulate Unix soft links.
0082       BUILDALL  Same as ALL, except CONFIG, BUILDINF and SOFTLINKS aren't done.
0083       RSAREF    Just build the "[.xxx.EXE.RSAREF]LIBRSAGLUE.OLB" library.
0084       CRYPTO    Just build the "[.xxx.EXE.CRYPTO]LIBCRYPTO.OLB" library.
0085       SSL       Just build the "[.xxx.EXE.SSL]LIBSSL.OLB" library.
0086       SSL_TASK  Just build the "[.xxx.EXE.SSL]SSL_TASK.EXE" program.
0087       TEST      Just build the "[.xxx.EXE.TEST]" test programs for OpenSSL.
0088       APPS      Just build the "[.xxx.EXE.APPS]" application programs for OpenSSL.
0089 
0090 <bits> must be one of the following:
0091 
0092       ""        compile using default pointer size
0093       32        compile using 32 bit pointer size
0094       64        compile using 64 bit pointer size
0095 
0096 <debug-p> must be one of the following:
0097 
0098       DEBUG     compile with debugging info (will not optimize)
0099       NODEBUG   compile without debugging info (will optimize)
0100 
0101 <compiler> must be one of the following:
0102 
0103       DECC      For DEC C.
0104       GNUC      For GNU C.
0105 
0106 
0107 You will find the crypto library in [.xxx.EXE.CRYPTO] (where xxx is VAX,
0108 ALPHA or IA64), called SSL_LIBCRYPTO32.OLB or SSL_LIBCRYPTO.OLB depending
0109 on how it was built.  You will find the SSL library in [.xxx.EXE.SSL],
0110 named SSL_LIBSSL32.OLB or SSL_LIBSSL.OLB, and you will find a bunch of
0111 useful programs in [.xxx.EXE.APPS].  However, these shouldn't be used
0112 right off unless it's just to test them.  For production use, make sure
0113 you install first, see Installation below.
0114 
0115 Note 1: Some programs in this package require a TCP/IP library.
0116 
0117 Note 2: if you want to compile the crypto library only, please make sure
0118         you have at least done a @MAKEVMS CONFIG, a @MAKEVMS BUILDINF and
0119         a @MAKEVMS SOFTLINKS.  A lot of things will break if you don't.
0120 
0121 
0122 Logical names:
0123 ==============
0124 
0125 There are a few things that can't currently be given through the command
0126 line.  Instead, logical names are used.
0127 
0128 Currently, the logical names supported are:
0129 
0130       OPENSSL_NO_ASM    with value YES, the assembler parts of OpenSSL will
0131                         not be used.  Instead, plain C implementations are
0132                         used.  This is good to try if something doesn't work.
0133       OPENSSL_NO_'alg'  with value YES, the corresponding crypto algorithm
0134                         will not be implemented.  Supported algorithms to
0135                         do this with are: RSA, DSA, DH, MD2, MD4, MD5, RIPEMD,
0136                         SHA, DES, MDC2, CR2, RC4, RC5, IDEA, BF, CAST, HMAC,
0137                         SSL2.  So, for example, having the logical name
0138                         OPENSSL_NO_RSA with the value YES means that the
0139                         LIBCRYPTO.OLB library will not contain an RSA
0140                         implementation.
0141 
0142 
0143 Test:
0144 =====
0145 
0146 Testing is very simple, just do the following:
0147 
0148   @[.TEST]TESTS
0149 
0150 If a test fails, try with defining the logical name OPENSSL_NO_ASM (yes,
0151 it's an ugly hack!) and rebuild. Please send a bug report to
0152 <openssl-bugs@openssl.org>, including the output of "openssl version -a"
0153 and of the failed test.
0154 
0155 
0156 Installation:
0157 =============
0158 
0159 Installation is easy, just do the following:
0160 
0161   @INSTALL <root> <bits>
0162 
0163 <root> is the directory in which everything will be installed,
0164 subdirectories, libraries, header files, programs and startup command
0165 procedures.
0166 
0167 <bits> works the same way as for MAKEVMS.COM
0168 
0169 N.B.: INSTALL.COM builds a new directory structure, different from
0170 the directory tree where you have now build OpenSSL.
0171 
0172 In the [.VMS] subdirectory of the installation, you will find the
0173 following command procedures:
0174 
0175   OPENSSL_STARTUP.COM
0176 
0177         defines all needed logical names.  Takes one argument that
0178         tells it in what logical name table to insert the logical
0179         names.  If you insert if it SYS$MANAGER:SYSTARTUP_VMS.COM, the
0180         call should look like this: 
0181 
0182           @openssldev:[openssldir.VMS]OPENSSL_STARTUP "/SYSTEM"
0183 
0184   OPENSSL_UTILS.COM
0185 
0186         sets up the symbols to the applications.  Should be called
0187         from for example SYS$MANAGER:SYLOGIN.COM 
0188 
0189   OPENSSL_UNDO.COM
0190 
0191         deassigns the logical names created with OPENSSL_STARTUP.COM.
0192 
0193 The logical names that are set up are the following:
0194 
0195   SSLROOT       a dotted concealed logical name pointing at the
0196                 root directory.
0197 
0198   SSLCERTS      Initially an empty directory, this is the default
0199                 location for certificate files.
0200   SSLPRIVATE    Initially an empty directory, this is the default
0201                 location for private key files.
0202 
0203   SSLEXE        Contains the openssl binary and a few other utility
0204                 programs.
0205   SSLINCLUDE    Contains the header files needed if you want to
0206                 compile programs with libcrypto or libssl.
0207   SSLLIB        Contains the OpenSSL library files themselves:
0208                 - SSL_LIBCRYPTO32.OLB and SSL_LIBSSL32.OLB or
0209                 - SSL_LIBCRYPTO.OLB and SSL_LIBSSL.OLB
0210 
0211   OPENSSL       Same as SSLINCLUDE.  This is because the standard
0212                 way to include OpenSSL header files from version
0213                 0.9.3 and on is:
0214 
0215                         #include <openssl/header.h>
0216 
0217                 For more info on this issue, see the INSTALL. file
0218                 (the NOTE in section 4 of "Installation in Detail").
0219                 You don't need to "deleting old header files"!!!
0220 
0221 
0222 Backward portability:
0223 =====================
0224 
0225 One great problem when you build a library is making sure it will work
0226 on as many versions of VMS as possible.  Especially, code compiled on
0227 OpenVMS version 7.x and above tend to be unusable in version 6.x or
0228 lower, because some C library routines have changed names internally
0229 (the C programmer won't usually see it, because the old name is
0230 maintained through C macros).  One obvious solution is to make sure
0231 you have a development machine with an old enough version of OpenVMS.
0232 However, if you are stuck with a bunch of Alphas running OpenVMS version
0233 7.1, you seem to be out of luck.  Fortunately, the DEC C header files
0234 are cluttered with conditionals that make some declarations and definitions
0235 dependent on the OpenVMS version or the C library version, *and* you
0236 can use those macros to simulate older OpenVMS or C library versions,
0237 by defining the macros _VMS_V6_SOURCE, __VMS_VER and __CTRL_VER with
0238 correct values.  In the compilation scripts, I've provided the possibility
0239 for the user to influence the creation of such macros, through a bunch of
0240 symbols, all having names starting with USER_.  Here's the list of them:
0241 
0242   USER_CCFLAGS           - Used to give additional qualifiers to the
0243                            compiler.  It can't be used to define macros
0244                            since the scripts will do such things as well.
0245                            To do such things, use USER_CCDEFS.
0246   USER_CCDEFS            - Used to define macros on the command line.  The
0247                            value of this symbol will be inserted inside a
0248                            /DEFINE=(...).
0249   USER_CCDISABLEWARNINGS - Used to disable some warnings.  The value is
0250                            inserted inside a /DISABLE=WARNING=(...).
0251 
0252 So, to maintain backward compatibility with older VMS versions, do the
0253 following before you start compiling:
0254 
0255   $ USER_CCDEFS := _VMS_V6_SOURCE=1,__VMS_VER=60000000,__CRTL_VER=60000000
0256   $ USER_CCDISABLEWARNINGS := PREOPTW
0257 
0258 The USER_CCDISABLEWARNINGS is there because otherwise, DEC C will complain
0259 that those macros have been changed.
0260 
0261 Note: Currently, this is only useful for library compilation.  The
0262       programs will still be linked with the current version of the
0263       C library shareable image, and will thus complain if they are
0264       faced with an older version of the same C library shareable image.
0265       This will probably be fixed in a future revision of OpenSSL.
0266 
0267 
0268 Possible bugs or quirks:
0269 ========================
0270 
0271 I'm not perfectly sure all the programs will use the SSLCERTS:
0272 directory by default, it may very well be that you have to give them
0273 extra arguments.  Please experiment.
0274 
0275 
0276 TODO:
0277 =====
0278 
0279 There are a few things that need to be worked out in the VMS version of
0280 OpenSSL, still:
0281 
0282 - Description files. ("Makefile's" :-))
0283 - Script code to link an already compiled build tree.
0284 - A VMSINSTALlable version (way in the future, unless someone else hacks).
0285 - shareable images (DLL for you Windows folks).
0286 
0287 There may be other things that I have missed and that may be desirable.
0288 Please send mail to <openssl-users@openssl.org> or to me directly if you
0289 have any ideas.
0290 
0291 --
0292 Richard Levitte <richard@levitte.org>
0293 2000-02-27, 2011-03-18