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.

perl v5.18.1                                       2013-10-20                              String::MkPasswd(3pm)