
OpenVMS AUTHENTICATOR (vmsauth)

If you need to migrate the users from an old DEC OpenVMS system to your brand
new Linux server, but you don't want to bother much with their passwords -
this package may be a good start for you. It will allow you to modify your
crypt() function (needed on Slackware) or to write an external authenticator
(on RedHat) to emulate the OpenVMS $HASH_PASSWORD system service on Linux
platform. As a result, the users will be able to use the same passwords they
had on the OpenVMS system, while Linux and VMS passwords will coexist on the
same server without any major problem.

NOTE - This package supports migration from VMS 5.0 and up to Linux. Older
VMS verions are supported as well, only if UAI$_ENCRYPT field of user
records have the value 1, 2 or 3. Value UAI$_ENCRYPT=0 is not supported.
See BACKGROUND notice at the end of this file for more information.

CREDITS

This package is based on Shawn Clifford's HPWD package, originally written
on OpenVMS, as an intention to emulate the OpenVMS $HASH_PASSWORD system
service on OpenVMS and Unix systems. The original package is available from
ftp://ftp.spc.edu/macro32/savesets/hpwd.zip. For the purpose of vmsauth
package, the original programs were slightly modified, to reflect Linux
specifics.


USAGE

The main component of the package is the file vmscrypt.c. It contains the
Unix-crypt()-like function, called VMScrypt(), which encrypts the cleartext
password using one of three supported DEC password hasing algorithms:
Purdy, Purdy_V and Purdy_S (Hickory). The oldest one (AUTODIN-II CRC) is not
supported. Since it is very similar to the standard Unix crypt() function,
it allows easy usage with most of other utilities, that make use of the
standard crypt() function (e.g. login, various authenticators, radius and
tacacs server, proxy and Web authenticators etc.).

Taking the user's username, cleartext passwrd, encryption algorithm
designator and the encryption salt, VMScrypt() produces the 64-bit long
encrypted password and stores it in the readable 27-character long form:

 			##/e/ssss/hhhhhhhh/llllllll

where e = encryption algorithm (1-3), ssss = 4-byte salt, hhhhhhhh = high
hash quadword, llllllll = low hash quadword (1 quadword = 8 bytes). The
"##" string denotes VMS password and allows mixed usage of OpenVMS (TM)
and Unix passwords in the same passwd file, e.g:.

vmsuser:##/3/ECB1/CADA8725/15278A12:10000:5000:VMS User:/home/vmsuser:/bin/sh
unixuser:E3aY.bw3se15a:50l:500:Unix User:/home/unixuser:/bin/sh


	char *VMScrypt (
		const char *username,	/* Username */
		const char *password,	/* Cleartext password */
		unsigned char encrypt,	/* Encryption scheme - 1, 2 or 3 */
		unsigned short salt);	/* 4-byte salt */


A sample authentication program, vmsauth.c, is provided in this package as
a working demo of VMScrypt() function.

NOTE - Before building the package, check the file b_order.h. VAX/VMS and
Intel/Linux platforms are both LITTLE_ENDIAN systems. Some other platforms
may be different (e.g. SunSPARC is BIG_ENDIAN).

FILES

The files included in the distribution of vmsauth package are:

vmsauth.c	A sample program - it may serve as a good starting point for
		your future authenticator programs. The program itself may
		be easily used as an external authenticator, where needed.
		The program checks the password against OpenVMS hashed
		password information, stored in passwd.vms file.

vmscrypt.c	Source code of the VMScrypt() function. The code itself uses 
                the function lgi$hpwd() from HPWD package to provide the VMS
		encrypted password.

b_order.h,
descrip.h,
hpwd.c	 	Files from the original Shawn Clifford's HPWD package, ported
		to Linux. The main function - lgi$hpwd() is located in the
		file hpwd.c.

passwd.vms	A sample passwd file, containing VMS passwords

vms/*.for	Fortran programs, to be built on an OpenVMS server. Both
		programs perform the same function - uaf2pwd1 is more proper
		("cleaner") version, while uaf2pwd2 makes use of "dirty"
		sequential SYSUAF.DAT reading. 


BACKGROUND

OpenVMS, a more than 25 years old and still alive operating system, designed
by the Digital Equipment Corporation, stores user information in a binary
user database, called user authorization file (UAF). On most OpenVMS systems
it is the file SYS$SYSTEM:SYSUAF.DAT and it's function is equivalent to the
Unix /etc/passwd file. The user passwords are stored in the UAF as well, in
the 64-bit (quadword) long encrypted form (UAI$_PWD field in the UAF user
record), along with the 32-bit (word) long encryption salt (UAI$_SALT). The
encryption algorithms, used on OpenVMS, thus, obviously differ from the
algorithm used on Unix. Furthermore, OpenVMS password encryption algorithm
changed four times during history, each time being more efficient and secure.
To ensure backward compatibility and proper password encryption, OpenVMS must
keep track of the information about algorithm being used for the current
user. A special field in the user record of the UAF - UAI$_ENCRYPT is used
to store that information. Currently, OpenVMS recognizes the following
one-way password encryption algorithms:

* AUTODIN-II CRC32 algorithm - the oldest one and NOT supported by this
  package. It is based on the simple CRC, with AUTODIN-II input polynomial.
  It was used on VMS 4.* systems. If you have such a system, you don't have
  luck this time, sorry ... :-( Users who have their passwords coded using
  this algorithm have UAI$_ENCRYPT field in their user record set to 0.

* PURDY algorithm - first published during 70's, this algorithm is based on
  a Purdy polinomial. UAI_ENCRYPT field of the user record is 1.

* PURDY_S - slightly modified version of the previous algorithm. UAI$_ENCRYPT
  field has the value of 2.

* PURDY_V (Hickory algorithm) - the most recent and most frequently used on
  OpenVMS systems. UAI$_ENCRYPT = 3.

All four algorithms use the username, along with the salt and appropriate
polynomials to create encrypted passwords. Unlike Unix crypt() function,
VMS password encryption functions make use of the username as one of the
input parameters.

As a summary, the function VMScrypt() must have 4 input parameters: user's
username (UAI$_USERNAME field in the UAF), user's cleartext password,
encryption salt (UAI$_SALT) and encryption algorithm identifier
(UAI$_ENCRYPT).


AUTHOR INFORMATION

Bug information and comments should be sent to Berislav Todorovic,
<BERI@etf.bg.ac.yu>.

