NAME

       Authen::Passphrase::VMSPurdy - passphrases with the VMS Purdy polynomial system

SYNOPSIS

               use Authen::Passphrase::VMSPurdy;

               $ppr = Authen::Passphrase::VMSPurdy->new(
                               username => "jrandom", salt => 25362,
                               hash_hex => "832a0c270179584a");

               $ppr = Authen::Passphrase::VMSPurdy->new(
                               username => "jrandom", salt_random => 1,
                               passphrase => "passphrase");

               $ppr = Authen::Passphrase::VMSPurdy->from_crypt(
                       '$VMS3$1263832A0C270179584AJRANDOM');

               $ppr = Authen::Passphrase::VMSPurdy->from_rfc2307(
                       '{CRYPT}$VMS3$1263832A0C270179584AJRANDOM');

               $algorithm = $ppr->algorithm;
               $username = $ppr->username;
               $salt = $ppr->salt;
               $hash = $ppr->hash;
               $hash_hex = $ppr->hash_hex;

               if($ppr->match($passphrase)) { ...

               $passwd = $ppr->as_crypt;
               $userPassword = $ppr->as_rfc2307;

DESCRIPTION

       An object of this class encapsulates a passphrase hashed using one of the Purdy polynomial
       hash functions used in VMS.  This is a subclass of Authen::Passphrase, and this document
       assumes that the reader is familiar with the documentation for that class.

       The core of the Purdy polynomial hashing algorithm transforms one 64-bit number into
       another 64-bit number.  It was developed by George B. Purdy, and described in the paper "A
       High Security Log-in Procedure" which can be found at
       <http://portal.acm.org/citation.cfm?id=361089&dl=GUIDE&coll=ACM&CFID=15151515&CFTOKEN=6184618>.

       For practical use in passphrase hashing, the Purdy polynomial must be augmented by a
       procedure to turn a variable-length passphrase into the initial 64-bit number to be
       hashed.  In VMS this pre-hashing phase also incorporates the username of the account to
       which access is being controlled, in order to prevent identical passphrases yielding
       identical hashes.  This is a form of salting.  Another salt parameter, a 16-bit integer,
       is also included, this one going under the name "salt".

       There are three variants of the pre-hashing algorithm.  The original version, known as
       "PURDY" and used during field testing of VMS 2.0, truncates or space-pads the username to
       a fixed length.  The second version, known as "PURDY_V" and used from VMS 2.0 up to (but
       not including) VMS 5.4, properly handles the variable-length nature of the username.  The
       third version, known as "PURDY_S" and used from VMS 5.4 onwards, performs some extra bit
       rotations to avoid aliasing problems when pre-hashing long strings.  All three versions
       are supported by this module.

       VMS heavily restricts the composition of both usernames and passphrases.  They may only
       contain alphanumerics, "$", and "_".  Case is insignificant.  Usernames must be between 1
       and 31 characters long, and passphrases must be between 1 and 32 characters long.  This
       module enforces these rules.  An invalid passphrase is never accepted as matching.

CONSTRUCTORS

       Authen::Passphrase::VMSPurdy->new(ATTR => VALUE, ...)
           Generates a new passphrase recogniser object using the VMS Purdy polynomial algorithm
           family.  The following attributes may be given:

           algorithm
               A string indicating which variant of the algorithm is to be used.  Valid values
               are "PURDY" (the original), "PURDY_V" (modified to use full length of the
               username), and "PURDY_S" (extra rotations to avoid aliasing when processing long
               strings).  Default "PURDY_S".

           username
               A string to be used as the `username' salt parameter.  It is limited to VMS
               username syntax.

           salt
               The salt, as an integer in the range [0, 65536).

           salt_hex
               The salt, as a string of four hexadecimal digits.  The first two digits must give
               the least-significant byte and the last two give the most-significant byte, with
               most-significant nybble first within each byte.

           salt_random
               Causes salt to be generated randomly.  The value given for this attribute is
               ignored.  The source of randomness may be controlled by the facility described in
               Data::Entropy.

           hash
               The hash, as a string of eight bytes.

           hash_hex
               The hash, as a string of 16 hexadecimal digits.

           passphrase
               A passphrase that will be accepted.  It is limited to VMS passphrase syntax.

           The username and salt must be given, and either the hash or the passphrase.

       Authen::Passphrase::VMSPurdy->from_crypt(PASSWD)
           Generates a new passphrase recogniser object using the VMS Purdy polynomial algorithm
           family, from a crypt string.  The string must consist of an algorithm identifier, the
           salt in hexadecimal, the hash in hexadecimal, then the username.  The salt must be
           given as four hexadecimal digits, the first two giving the least-significant byte and
           the last two giving the most-significant byte, with most-significant nybble first
           within each byte.  The algorithm identifier must be "$VMS1$" for "PURDY", "$VMS2$" for
           "PURDY_V", or "$VMS3$" for "PURDY_S".  The whole crypt string must be uppercase.

       Authen::Passphrase::VMSPurdy->from_rfc2307(USERPASSWORD)
           Generates a new passphrase recogniser object using the VMS Purdy polynomial algorithm
           family, from an RFC 2307 string.  The string must consist of "{CRYPT}" (case
           insensitive) followed by an acceptable crypt string.

METHODS

       $ppr->algorithm
           Returns the algorithm variant identifier string.  It may be "PURDY" (the original),
           "PURDY_V" (modified to use full length of the username), and "PURDY_S" (extra
           rotations to avoid aliasing when processing long strings).

       $ppr->username
           Returns the username string.  All alphabetic characters in it are uppercase, which is
           the canonical form.

       $ppr->salt
           Returns the salt, as an integer.

       $ppr->salt_hex
           Returns the salt, as a string of four hexadecimal digits.  The first two digits give
           the least-significant byte and the last two give the most-significant byte, with most-
           significant nybble first within each byte.

       $ppr->hash
           Returns the hash value, as a string of eight bytes.

       $ppr->hash_hex
           Returns the hash value, as a string of 16 uppercase hexadecimal digits.

       $ppr->match(PASSPHRASE)
       $ppr->as_crypt
       $ppr->as_rfc2307
           These methods are part of the standard Authen::Passphrase interface.

SEE ALSO

       Authen::DecHpwd, Authen::Passphrase

AUTHOR

       Andrew Main (Zefram) <zefram@fysh.org>

COPYRIGHT

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

LICENSE

       This module is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.