1Crypt::RandPasswd(3)  User Contributed Perl Documentation Crypt::RandPasswd(3)
2
3
4

NAME

6       Crypt::RandPasswd - random password generator based on FIPS-181
7

SYNOPSIS

9         use Crypt::RandPasswd;
10         ( $word, $hyphenated ) = Crypt::RandPasswd->word( $minlen, $maxlen );
11         $word = Crypt::RandPasswd->word( $minlen, $maxlen );
12         $word = Crypt::RandPasswd->letters( $minlen, $maxlen );
13         $word = Crypt::RandPasswd->chars( $minlen, $maxlen );
14
15         # override the defaults for these functions:
16         *Crypt::RandPasswd::rng = \&my_random_number_generator;
17         *Crypt::RandPasswd::restrict = \&my_restriction_filter;
18

DESCRIPTION

20       Crypt::RandPasswd provides three functions that can be used to generate
21       random passwords, constructed from words, letters, or characters.
22
23       This code is a Perl implementation of the Automated Password Generator
24       standard, like the program described in "A Random Word Generator For
25       Pronounceable Passwords" (not available on-line).  This code is a re-
26       engineering of the program contained in Appendix A of FIPS Publication
27       181, "Standard for Automated Password Generator".  In accordance with
28       the standard, the results obtained from this program are logically
29       equivalent to those produced by the standard.
30

CAVEATS

32   Bugs
33       The function to generate a password can sometimes take an extremely
34       long time.
35
36   Deviations From Standard
37       This implementation deviates in one critical way from the standard upon
38       which it is based: the random number generator in this implementation
39       does not use DES.  Instead, it uses perl's built-in "rand()" function,
40       which in turn is (usually) built on the pseudo-random number generator
41       functions of the underlying C library.
42
43       However, the random function can be replaced by the user if desired.
44       (See "rng".)
45

Functions

47   word
48         word = word( minlen, maxlen );
49         ( word, hyphenated_form ) = word( minlen, maxlen );
50
51       Generates a random word, as well as its hyphenated form.  The length of
52       the returned word will be between minlen and maxlen.
53
54   letters
55         word = letters( minlen, maxlen );
56
57       Generates a string of random letters.  The length of the returned word
58       is between minlen and maxlen.  Calls "random_chars_in_range( 'a' => 'z'
59       )".
60
61   chars
62         word = chars( minlen, maxlen );
63
64       Generates a string of random printable characters.  The length of the
65       returned word is between minlen and maxlen.  Calls
66       "random_chars_in_range( '!' => '~' )".
67
68   random_chars_in_range
69         word = random_chars_in_range( minlen, maxlen, lo_char => hi_char );
70
71       Generates a string of printable characters.  The length of the returned
72       string is between minlen and maxlen.  Each character is selected from
73       the range of ASCII characters delimited by (lo_char,hi_char).
74
75   rand_int_in_range
76         n = rand_int_in_range( min, max );
77
78       Returns an integer between min and max, inclusive.  Calls "rng" like
79       so:
80
81         n = min + int( rng( max - min + 1 ) )
82
83   random_element
84         e = random_element( \@elts )
85
86       Selects a random element from an array, which is passed by ref.
87
88   rng
89         r = rng( n );
90
91       "rng" is designed to have the same interface as the built-in "rand"
92       function.  The default implementation here is a simple wrapper around
93       "rand", which is typically a wrapper for some pseudo-random number
94       function in the underlying C library.
95
96       The reason for having this simple wrapper is so the user can easily
97       substitute a different random number generator if desired.  Since many
98       rng's have the same interface as "rand", replacing "rng()" is as simple
99       as
100
101           {
102               local $^W; # squelch sub redef warning.
103               *Crypt::RandPasswd::rng = \&my_rng;
104           }
105
106       See rand.
107
108   restrict
109         word = restrict( word );
110
111       A filter.  Returns the arg unchanged if it is allowable; returns undef
112       if not.
113
114       The default version of "restrict()" allows everything.  You may install
115       a different form to implement other restrictions, by doing something
116       like this:
117
118           {
119             local $^W; # squelch sub redef warning.
120             *Crypt::RandPasswd::restrict = \&my_filter;
121           }
122
123   init
124       This initializes the environment, which by default simply seeds the
125       random number generator.
126
127   get_syllable
128       Generate next unit to password, making sure that it follows these
129       rules:
130
131       1. Each syllable must contain exactly 1 or 2 consecutive vowels, where
132       y is considered a vowel.
133
134       2. Syllable end is determined as follows:
135
136          a. Vowel is generated and previous unit is a consonant and syllable already has a vowel.
137             In this case, new syllable is started and already contains a vowel.
138          b. A pair determined to be a "break" pair is encountered.
139             In this case new syllable is started with second unit of this pair.
140          c. End of password is encountered.
141          d. "begin" pair is encountered legally.  New syllable is started with this pair.
142          e. "end" pair is legally encountered.  New syllable has nothing yet.
143
144       3. Try generating another unit if:
145
146          a. third consecutive vowel and not y.
147          b. "break" pair generated but no vowel yet in current or previous 2 units are "not_end".
148          c. "begin" pair generated but no vowel in syllable preceding begin pair,
149             or both previous 2 pairs are designated "not_end".
150          d. "end" pair generated but no vowel in current syllable or in "end" pair.
151          e. "not_begin" pair generated but new syllable must begin (because previous syllable ended as defined in 2 above).
152          f. vowel is generated and 2a is satisfied, but no syllable break is possible in previous 3 pairs.
153          g. Second and third units of syllable must begin, and first unit is "alternate_vowel".
154

SEE ALSO

156       CPAN modules for generating passwords
157       <http://neilb.org/reviews/passwords.html> - a review of modules of CPAN
158       for random password generation.
159
160       Some of the better modules: App::Genpass, Crypt::XkcdPassword,
161       Crypt::YAPassGen, Data::Random, String::Random.
162
163       FIPS 181 - (APG), Automated Password Generator:
164       http://www.itl.nist.gov/fipspubs/fip181.htm
165

REPOSITORY

167       <https://github.com/neilbowers/Crypt-RandPasswd>
168

AUTHOR

170       JDPORTER@cpan.org (John Porter)
171
172       Now maintained by Neil Bowers <neilb@cpan.org>
173
175       This perl module is free software; it may be redistributed and/or
176       modified under the same terms as Perl itself.
177
178
179
180perl v5.32.1                      2021-01-27              Crypt::RandPasswd(3)
Impressum