[thirdparty/openssl.git] / INSTALL.VMS

			VMS Installation instructions
			written by Richard Levitte
			<richard@levitte.org>


Intro:
======

This file is divided in the following parts:

  Requirements			- Mandatory reading.
  Checking the distribution	- Mandatory reading.
  Compilation			- Mandatory reading.
  Logical names			- Mandatory reading.
  Test				- Mandatory reading.
  Installation			- Mandatory reading.
  Backward portability		- Read if it's an issue.
  Possible bugs or quirks	- A few warnings on things that
				  may go wrong or may surprise you.
  TODO				- Things that are to come.


Requirements:
=============

To build and install OpenSSL, you will need:

 * DEC C or some other ANSI C compiler.  VAX C is *not* supported.
   [Note: OpenSSL has only been tested with DEC C.  Compiling with 
    a different ANSI C compiler may require some work]

Checking the distribution:
==========================

There have been reports of places where the distribution didn't quite get
through, for example if you've copied the tree from a NFS-mounted Unix
mount point.

The easiest way to check if everything got through as it should is to check
for one of the following files:

	[.CRYPTO]OPENSSLCONF.H_IN
	[.CRYPTO]OPENSSLCONF_H.IN

They should never exist both at once, but one of them should (preferably
the first variant).  If you can't find any of those two, something went
wrong.

The best way to get a correct distribution is to download the gzipped tar
file from ftp://ftp.openssl.org/source/, use GUNZIP to uncompress it and
use VMSTAR to unpack the resulting tar file.

GUNZIP is available in many places on the net.  One of the distribution
points is the WKU software archive, ftp://ftp.wku.edu/vms/fileserv/ .

VMSTAR is also available in many places on the net.  The recommended place
to find information about it is http://www.free.lp.se/vmstar/ .


Compilation:
============

I've used the very good command procedures written by Robert Byer
<byer@mail.all-net.net>, and just slightly modified them, making
them slightly more general and easier to maintain.

You can actually compile in almost any directory separately.  Look
for a command procedure name xxx-LIB.COM (in the library directories)
or MAKExxx.COM (in the program directories) and read the comments at
the top to understand how to use them.  However, if you want to
compile all you can get, the simplest is to use MAKEVMS.COM in the top
directory.  The syntax is the following:

  @MAKEVMS <option> <bits> <debug-p> [<compiler>]

<option> must be one of the following:

      ALL       Just build "everything".
      CONFIG    Just build the "[.CRYPTO]OPENSSLCONF.H" file.
      BUILDINF  Just build the "[.INCLUDE]BUILDINF.H" file.
      SOFTLINKS Just copies some files, to simulate Unix soft links.
      BUILDALL  Same as ALL, except CONFIG, BUILDINF and SOFTLINKS aren't done.
      RSAREF    Just build the "[.xxx.EXE.RSAREF]LIBRSAGLUE.OLB" library.
      CRYPTO    Just build the "[.xxx.EXE.CRYPTO]LIBCRYPTO.OLB" library.
      SSL       Just build the "[.xxx.EXE.SSL]LIBSSL.OLB" library.
      SSL_TASK  Just build the "[.xxx.EXE.SSL]SSL_TASK.EXE" program.
      TEST      Just build the "[.xxx.EXE.TEST]" test programs for OpenSSL.
      APPS      Just build the "[.xxx.EXE.APPS]" application programs for OpenSSL.

<bits> must be one of the following:

      ""        compile using default pointer size
      32        compile using 32 bit pointer size
      64        compile using 64 bit pointer size

<debug-p> must be one of the following:

      DEBUG     compile with debugging info (will not optimize)
      NODEBUG   compile without debugging info (will optimize)

<compiler> must be one of the following:

      DECC      For DEC C.
      GNUC      For GNU C.


You will find the crypto library in [.xxx.EXE.CRYPTO] (where xxx is VAX,
ALPHA or IA64), called SSL_LIBCRYPTO32.OLB or SSL_LIBCRYPTO.OLB depending
on how it was built.  You will find the SSL library in [.xxx.EXE.SSL],
named SSL_LIBSSL32.OLB or SSL_LIBSSL.OLB, and you will find a bunch of
useful programs in [.xxx.EXE.APPS].  However, these shouldn't be used
right off unless it's just to test them.  For production use, make sure
you install first, see Installation below.

Note 1: Some programs in this package require a TCP/IP library.

Note 2: if you want to compile the crypto library only, please make sure
        you have at least done a @MAKEVMS CONFIG, a @MAKEVMS BUILDINF and
        a @MAKEVMS SOFTLINKS.  A lot of things will break if you don't.


Logical names:
==============

There are a few things that can't currently be given through the command
line.  Instead, logical names are used.

Currently, the logical names supported are:

      OPENSSL_NO_ASM    with value YES, the assembler parts of OpenSSL will
                        not be used.  Instead, plain C implementations are
                        used.  This is good to try if something doesn't work.
      OPENSSL_NO_'alg'  with value YES, the corresponding crypto algorithm,
                        protocol or other routine will not be implemented if
                        disabling it is supported.  Supported algorithms to
                        do this with are: AES, BF, CAMELLIA, CAST, CMS, COMP,
                        DES, DGRAM, DH, DSA, EC, EC2M, ECDH, ECDSA, ENGINE,
                        ERR, GOST, HEARTBEATS, HMAC, IDEA, KRB5, MD2, MD4,
                        MD5, OCB, OCSP, PSK, RC2, RC4, RC5, RMD160, RSA, SCTP,
                        SEED, SOCK, SRP, SRTP, TLSEXT, WHIRLPOOL.  So, for
                        example, having the logical name OPENSSL_NO_RSA with
                        the value YES means that the LIBCRYPTO.OLB library
                        will not contain an RSA implementation.
      OPENSSL_EXPERIMENTAL_'alg'
                        with value YES, the corresponding experimental
                        algorithm is enabled.  Note that is also requires
                        the application using this to define the C macro
                        OPENSSL_EXPERIMENTAL_'alg'.  Supported algorithms
                        to do this with are: JPAKE, STORE.

Test:
=====

Testing is very simple, just do the following:

  @[.TEST]TESTS

If a test fails, try with defining the logical name OPENSSL_NO_ASM (yes,
it's an ugly hack!) and rebuild. Please send a bug report to
<openssl-bugs@openssl.org>, including the output of "openssl version -a"
and of the failed test.


Installation:
=============

Installation is easy, just do the following:

  @INSTALL <root> <bits>

<root> is the directory in which everything will be installed,
subdirectories, libraries, header files, programs and startup command
procedures.

<bits> works the same way as for MAKEVMS.COM

N.B.: INSTALL.COM builds a new directory structure, different from
the directory tree where you have now build OpenSSL.

In the [.VMS] subdirectory of the installation, you will find the
following command procedures:

  OPENSSL_STARTUP.COM

        defines all needed logical names.  Takes one argument that
        tells it in what logical name table to insert the logical
        names.  If you insert if it SYS$MANAGER:SYSTARTUP_VMS.COM, the
        call should look like this: 

          @openssldev:[openssldir.VMS]OPENSSL_STARTUP "/SYSTEM"

  OPENSSL_UTILS.COM

        sets up the symbols to the applications.  Should be called
        from for example SYS$MANAGER:SYLOGIN.COM 

  OPENSSL_UNDO.COM

	deassigns the logical names created with OPENSSL_STARTUP.COM.

The logical names that are set up are the following:

  SSLROOT       a dotted concealed logical name pointing at the
                root directory.

  SSLCERTS      Initially an empty directory, this is the default
		location for certificate files.
  SSLPRIVATE	Initially an empty directory, this is the default
		location for private key files.

  SSLEXE        Contains the openssl binary and a few other utility
		programs.
  SSLINCLUDE    Contains the header files needed if you want to
		compile programs with libcrypto or libssl.
  SSLLIB        Contains the OpenSSL library files themselves:
  		- SSL_LIBCRYPTO32.OLB and SSL_LIBSSL32.OLB or
		- SSL_LIBCRYPTO.OLB and SSL_LIBSSL.OLB

  OPENSSL	Same as SSLINCLUDE.  This is because the standard
		way to include OpenSSL header files from version
		0.9.3 and on is:

			#include <openssl/header.h>

		For more info on this issue, see the INSTALL. file
		(the NOTE in section 4 of "Installation in Detail").
		You don't need to "deleting old header files"!!!


Backward portability:
=====================

One great problem when you build a library is making sure it will work
on as many versions of VMS as possible.  Especially, code compiled on
OpenVMS version 7.x and above tend to be unusable in version 6.x or
lower, because some C library routines have changed names internally
(the C programmer won't usually see it, because the old name is
maintained through C macros).  One obvious solution is to make sure
you have a development machine with an old enough version of OpenVMS.
However, if you are stuck with a bunch of Alphas running OpenVMS version
7.1, you seem to be out of luck.  Fortunately, the DEC C header files
are cluttered with conditionals that make some declarations and definitions
dependent on the OpenVMS version or the C library version, *and* you
can use those macros to simulate older OpenVMS or C library versions,
by defining the macros _VMS_V6_SOURCE, __VMS_VER and __CTRL_VER with
correct values.  In the compilation scripts, I've provided the possibility
for the user to influence the creation of such macros, through a bunch of
symbols, all having names starting with USER_.  Here's the list of them:

  USER_CCFLAGS		 - Used to give additional qualifiers to the
			   compiler.  It can't be used to define macros
			   since the scripts will do such things as well.
			   To do such things, use USER_CCDEFS.
  USER_CCDEFS		 - Used to define macros on the command line.  The
			   value of this symbol will be inserted inside a
			   /DEFINE=(...).
  USER_CCDISABLEWARNINGS - Used to disable some warnings.  The value is
			   inserted inside a /DISABLE=WARNING=(...).

So, to maintain backward compatibility with older VMS versions, do the
following before you start compiling:

  $ USER_CCDEFS := _VMS_V6_SOURCE=1,__VMS_VER=60000000,__CRTL_VER=60000000
  $ USER_CCDISABLEWARNINGS := PREOPTW

The USER_CCDISABLEWARNINGS is there because otherwise, DEC C will complain
that those macros have been changed.

Note: Currently, this is only useful for library compilation.  The
      programs will still be linked with the current version of the
      C library shareable image, and will thus complain if they are
      faced with an older version of the same C library shareable image.
      This will probably be fixed in a future revision of OpenSSL.


Possible bugs or quirks:
========================

I'm not perfectly sure all the programs will use the SSLCERTS:
directory by default, it may very well be that you have to give them
extra arguments.  Please experiment.


TODO:
=====

There are a few things that need to be worked out in the VMS version of
OpenSSL, still:

- Description files. ("Makefile's" :-))
- Script code to link an already compiled build tree.
- A VMSINSTALlable version (way in the future, unless someone else hacks).
- shareable images (DLL for you Windows folks).

There may be other things that I have missed and that may be desirable.
Please send mail to <openssl-users@openssl.org> or to me directly if you
have any ideas.

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