NAME

       Authen::DecHpwd - DEC VMS password hashing

SYNOPSIS

               use Authen::DecHpwd qw(
                       UAI_C_AD_II UAI_C_PURDY UAI_C_PURDY_V UAI_C_PURDY_S
                       lgi_hpwd
               );

               $hash = lgi_hpwd("JRANDOM", "PASSWORD", UAI_C_PURDY_S, 1234);

               use Authen::DecHpwd qw(vms_username vms_password);

               $username = vms_username($username);
               $password = vms_password($password);

DESCRIPTION

       This module implements the "SYS$HASH_PASSWORD" password hashing function from VMS (also
       known as "LGI$HPWD"), and some associated VMS username and password handling functions.

       The password hashing function is implemented in XS, with a hideously slow pure Perl backup
       version for systems that can't handle XS.

FUNCTIONS

       UAI_C_AD_II
       UAI_C_PURDY
       UAI_C_PURDY_V
       UAI_C_PURDY_S
           These constants are used to identify the four password hashing algorithms used by VMS.
           They are the "UAI$C_" constants in VMS.

           "UAI_C_AD_II" refers to a 32-bit CRC algorithm.  The CRC polynomial used is the IEEE
           CRC-32 polynomial, as used in Ethernet, and in this context is known as "AUTODIN-II".
           The hash is merely the CRC of the password.

           "UAI_C_PURDY", "UAI_C_PURDY_V", and "UAI_C_PURDY_S" refer to successive refinements of
           an algorithm based on Purdy polynomials.  All of these algorithms use the salt and
           username parameters as salt, use the whole password, and return an eight-byte (64-bit)
           hash.  The main part of the algorithm, the Purdy polynomial, is identical in all
           three.  They differ in the pre-hashing, particularly in the treatment of the username
           parameter.

           In "UAI_C_PURDY" the username is truncated or space-padded to 12 characters before
           being hashed in.  "UAI_C_PURDY_V" accepts a variable-length username.  "UAI_C_PURDY_S"
           accepts a variable-length username and also includes the password length in the hash.
           "UAI_C_PURDY_S" also does some extra bit rotations when hashing in the username and
           password strings, in order to avoid aliasing.

       lgi_hpwd(USERNAME, PASSWORD, ALGORITHM, SALT)
           This is the "SYS$HASH_PASSWORD" function from VMS (also known as "LGI$HPWD"), but with
           the parameters in a different order.  It hashes the PASSWORD string in a manner
           determined by the other parameters, and returns the hash as a string of bytes.

           ALGORITHM determines which hashing algorithm will be used.  It must be the value of
           one of the algorithm constants supplied by this module (see above).

           SALT must be an integer in the range [0, 2^16).  It modifies the hashing so that the
           same password does not always produce the same hash.

           USERNAME is a string that is used as more salt.  In VMS it is the username of the
           account to which the password controls access.

           VMS usernames and passwords are constrained in character set and length, and are case-
           insensitive.  This function does not enforce these restrictions, nor perform
           canonicalisation.  If restrictions and canonicalisation are desired then they must be
           applied separately.  The functions "vms_username" and "vms_password" described below
           may be useful.

       vms_username(USERNAME)
           Checks whether the USERNAME string matches VMS username syntax, and canonicalises it.
           VMS username syntax is 1 to 31 characters from case-insensitive alphanumerics, "_",
           and "$".  If the string has correct username syntax then the username is returned in
           canonical form (uppercase).  If the string is not a username then "undef" is returned.

       vms_password(PASSWORD)
           Checks whether the PASSWORD string is an acceptable VMS password, and canonicalises
           it.  VMS password syntax is 1 to 32 characters from case-insensitive alphanumerics,
           "_", and "$".  If the string is an acceptable password then the password is returned
           in canonical form (uppercase).  If the string is not an acceptable password then
           "undef" is returned.

SEE ALSO

       VMS::User

AUTHOR

       The original C implementation of "LGI$HPWD" was written by Shawn Clifford.  The code has
       since been developed by Davide Casale, Mario Ambrogetti, Terence Lee, Jean-loup Gailly,
       Solar Designer, and Andrew Main (Zefram).

       Mike McCauley <mikem@open.com.au> created the first version of "Authen::DecHpwd",
       establishing the Perl interface.  This was based on Shawn Clifford's code without the
       later developments.

       Andrew Main (Zefram) <zefram@fysh.org> created a new "Authen::DecHpwd" based on the more
       developed C code presently used, and added ancillary functions.

COPYRIGHT

       Copyright (C) 2002 Jean-loup Gailly <http://gailly.net>

       Based in part on code from John the Ripper, Copyright (C) 1996-2002 Solar Designer

       Copyright (C) 2006, 2007, 2009, 2010, 2011 Andrew Main (Zefram) <zefram@fysh.org>

LICENSE

       This module is free software; you can redistribute it and/or modify it under the terms of
       the GNU General Public License as published by the Free Software Foundation; either
       version 2 of the License, or (at your option) any later version.