NAME

       String::MkPasswd - random password generator

SYNOPSIS

         use String::MkPasswd qw(mkpasswd);

         print mkpasswd();

         # for the masochisticly paranoid...
         print mkpasswd(
             -length     => 27,
             -minnum     => 5,
             -minlower   => 1,   # minlower is increased if necessary
             -minupper   => 5,
             -minspecial => 5,
             -distribute => 1,
         );

ABSTRACT

       This Perl library defines a single function, "mkpasswd()", to generate random passwords.
       The function is meant to be a simple way for developers and system administrators to
       easily generate a relatively secure password.

DESCRIPTION

       The exportable "mkpasswd()" function returns a single scalar: a random password.  By
       default, this password is nine characters long with a random distribution of four lower-
       case characters, two upper-case characters, two digits, and one non-alphanumeric
       character.  These parameters can be tuned by the user, as described in the "ARGUMENTS"
       section.

   ARGUMENTS
       The "mkpasswd()" function takes an optional hash of arguments.

       -length
           The total length of the password.  The default is 9.

       -minnum
           The minimum number of digits that will appear in the final password.  The default is
           2.

       -minlower
           The minimum number of lower-case characters that will appear in the final password.
           The default is 2.

       -minupper
           The minimum number of upper-case characters that will appear in the final password.
           The default is 2.

       -minspecial
           The minimum number of non-alphanumeric characters that will appear in the final
           password.  The default is 1.

       -distribute
           If set to a true value, password characters will be distributed between the left- and
           right-hand sides of the keyboard.  This makes it more difficult for an onlooker to see
           the password as it is typed.  The default is false.

       -noambiguous
           If set to a true value, password characters will not include any that might be
           mistaken for others. This is particularly helpful if you're distributing a printed
           list of passwords to a group of people. The default is false.

       -fatal
           If set to a true value, "mkpasswd()" will Carp::croak() rather than return "undef" on
           error.  The default is false.

       If -minnum, -minlower, -minupper, and -minspecial do not add up to -length, -minlower will
       be increased to compensate.  However, if -minnum, -minlower, -minupper, and -minspecial
       add up to more than -length, then "mkpasswd()" will return "undef".  See the section
       entitled "EXCEPTION HANDLING" for how to change this behavior.

   EXCEPTION HANDLING
       By default, "mkpasswd()" will return "undef" if it cannot generate a password.  Some
       people are inclined to exception handling, so String::MkPasswd does its best to
       accommodate them.  If the variable $String::MkPasswd::FATAL is set to a true value,
       "mkpasswd()" will Carp::croak() with an error instead of returning "undef".

   EXPORT
       None by default.  The "mkpasswd()" method is exportable.

SEE ALSO

       <http://expect.nist.gov/#examples>, mkpasswd(1)

AKNOWLEDGEMENTS

       Don Libes of the National Institute of Standards and Technology, who wrote the Expect
       example, mkpasswd(1).

AUTHOR

       Chris Grau <cgrau@cpan.org>

COPYRIGHT AND LICENSE

       Copyright (C) 2003-2012 by Chris Grau

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself, either Perl version 5.8.1 or, at your option, any later version of
       Perl 5 you may have available.