debian man page for string::mkpasswd

String::MkPasswd(3pm)					User Contributed Perl Documentation				     String::MkPasswd(3pm)

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.

       -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-2010 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.10.1							    2010-10-18						     String::MkPasswd(3pm)