.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Crypt::GeneratePassword 3pm" .TH Crypt::GeneratePassword 3pm "2015-11-14" "perl v5.20.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Crypt::GeneratePassword \- generate secure random pronounceable passwords .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 5 \& use Crypt::GeneratePassword qw(word chars); \& $word = word($minlen,$maxlen); \& $word = chars($minlen,$maxlen); \& *Crypt::GeneratePassword::restrict = \e&my_restriction_filter; \& *Crypt::GeneratePassword::random_number = \e&my_random_number_generator; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Crypt::GeneratePassword generates random passwords that are (more or less) pronounceable. Unlike Crypt::RandPasswd, it doesn't use the \s-1FIPS\-181 NIST\s0 standard, which is proven to be insecure. It does use a similar interface, so it should be a drop-in replacement in most cases. .PP If you want to use passwords from a different language than english, you can use one of the packaged alternate unit tables or generate your own. See below for details. .PP For details on why \s-1FIPS\-181\s0 is insecure and why the solution used in this module is reasonably secure, see \*(L"A New Attack on Random Pronounceable Password Generators\*(R" by Ravi Ganesan and Chris Davies, available online in may places \- use your favourite search engine. .PP This module improves on \s-1FIPS\-181\s0 using a true random selection with the word generator as mere filter. Other improvements are better pronounceability using third order approximation instead of second order and multi-language support. Drawback of this method is that it is usually slower. Then again, computer speed has improved a little since 1977. .SH "Functions" .IX Header "Functions" .SS "chars" .IX Subsection "chars" .Vb 1 \& $word = chars($minlen, $maxlen [, $set [, $characters, $maxcount ] ... ] ); .Ve .PP Generates a completely random word between \f(CW$minlen\fR and \f(CW$maxlen\fR in length. If \f(CW$set\fR is given, it must be an array ref of characters to use. You can restrict occurrence of some characters by providing ($characters, \f(CW$maxcount\fR) pairs, as many as you like. \f(CW$characters\fR must be a string consisting of those characters which may appear at most \f(CW$maxcount\fR times in the word. .PP Note that the length is determined via relative probability, not uniformly. .SS "word" .IX Subsection "word" .Vb 2 \& $word = word($minlen, $maxlen [, $lang [, $numbers [, $caps [, $minfreq, $avgfreq ] ] ] ); \& $word = word3($minlen, $maxlen [, $lang [, $numbers [, $caps [, $minfreq, $avgfreq ] ] ] ); .Ve .PP Generates a random pronounceable word. The length of the returned word will be between \f(CW$minlen\fR and \f(CW$maxlen\fR. If you supply a non-zero value for \f(CW$numbers\fR, up to that many numbers and special characters will occur in the password. If you specify a non-zero value for \f(CW$caps\fR, up to this many characters will be upper case. \f(CW$lang\fR is the language description to use, loaded via load_language or built-in. Built-in languages are: 'en' (english) and 'de' (german). Contributions welcome. The default language is 'en' but may be changed by calling load_language with a true value as third parameter. Pass undef as language to select the current default language. \f(CW$minfreq\fR and \f(CW$minsum\fR determine quality of the password: \f(CW$minfreq\fR and \f(CW$avgfreq\fR are the minimum frequency each quad/trigram must have and the average frequency that the quad/trigrams must have for a word to be selected. Both are values between 0.0 and 1.0, specifying the percentage of the maximum frequency. Higher values create less secure, better pronounceable passwords and are slower. Useful \f(CW$minfreq\fR values are usually between 0.001 and 0.0001, useful \f(CW$avgfreq\fR values are around 0.05 for trigrams (word3) and 0.001 for quadgrams (word). .SS "analyze" .IX Subsection "analyze" .Vb 2 \& $ratio = analyze($count,@word_params); \& $ratio = analyze3($count,@word_params); .Ve .PP Returns a statistical(!) security ratio to measure password quality. \f(CW$ratio\fR is the ratio of passwords chosen among all possible ones, e.g. a ratio of 0.0149 means 1.49% of the theoretical password space was actually considered a pronounceable password. Since this analysis is only statistical, it proves absolutely nothing if you are deeply concerned about security \- but in that case you should use \&\fIchars()\fR, not \fIword()\fR anyways. In reality, it says a lot about your chosen parameters if you use large values for \&\f(CW$count\fR. .SS "generate_language" .IX Subsection "generate_language" .Vb 1 \& $language_description = generate_language($wordlist); .Ve .PP Generates a language description which can be saved in a file and/or loaded with load_language. \f(CW$wordlist\fR can be a string containing whitespace separated words, an array ref containing one word per element or a file handle or name to read words from, one word per line7. Alternatively, you may pass an array directly, not as reference. A language description is about 1MB in size. .PP If you generate a general-purpose language description for a language not yet built-in, feel free to contribute it for inclusion into this package. .SS "load_language" .IX Subsection "load_language" .Vb 1 \& load_language($language_description, $name [, $default]); .Ve .PP Loads a language description which is then available in \fIwords()\fR. \&\f(CW$language_description\fR is a string returned by generate_language, \&\f(CW$name\fR is a name of your choice which is used to select this language as the fifth parameter of \fIwords()\fR. You should use the well-known \s-1ISO\s0 two letter language codes if possible, for best interoperability. .PP If you specify \f(CW$default\fR with a true value, this language will be made global default language. If you give undef as \&\f(CW$language_description\fR, only the default language will be changed. .SS "random_number" .IX Subsection "random_number" .Vb 1 \& $number = random_number($limit); .Ve .PP Returns a random integer between 0 (inclusive) and \f(CW$limit\fR (exclusive). Change this to a function of your choice by doing something like this: .PP .Vb 3 \& sub my_rng ($) { \& ... \& } \& \& { \& # suppress warning about function being redefined \& no warnings \*(Aqredefine\*(Aq; \& *Crypt::GeneratePassword::random_number = \e&my_rng; \& } .Ve .PP The default implementation uses perl's \fIrand()\fR, which might not be appropriate for some sites. .SS "restrict" .IX Subsection "restrict" .Vb 1 \& $forbidden = restrict($word,$language); .Ve .PP Filters undesirable words. Returns false if the \f(CW$word\fR is allowed in language \f(CW$lang\fR, false otherwise. Change this to a function of your choice by doing something like this: .PP .Vb 3 \& sub my_filter ($$) { \& ... \& } \& \& { \& no warnings \*(Aqredefine\*(Aq; \& *Crypt::GeneratePassword::restrict = \e&my_filter; \& } .Ve .PP The default implementation scans for a few letter sequences that english or german people might find offending, mostly because of their sexual nature. You might want to hook up a regular password checker here, or a wordlist comparison. .SH "SEE ALSO" .IX Header "SEE ALSO" Crypt::RandPasswd .SH "REPOSITORY" .IX Header "REPOSITORY" .SH "AUTHOR" .IX Header "AUTHOR" Copyright 2002 by Jo\*:rg Walter , inspired by ideas from Tom Van Vleck and Morris Gasser/FIPS\-181. .PP Now maintained by Neil Bowers .SH "COPYRIGHT" .IX Header "COPYRIGHT" This perl module is free software; it may be redistributed and/or modified under the same terms as Perl itself.