1Crypt::HSXKPasswd(3) User Contributed Perl Documentation Crypt::HSXKPasswd(3)
2
6 "Crypt::HSXKPasswd" - A secure memorable password generator inspired by
7 Steve Gibson's Passord Haystacks (<https://www.grc.com/haystack.htm>),
8 and the famous XKCD password cartoon (<https://xkcd.com/936/>).
9
11 This documentation refers to "Crypt::HSXKPasswd" version 3.6.
12
14 use Crypt::HSXKPasswd;
15 #
17 # Functional Interface - a shortcut for generating single passwords
18 #
19 # generate a single password using the default word source, configuration,
21 # and random number generator
22 my $password = hsxkpasswd();
23 # the above call is simply a shortcut for the following
25 my $password = Crypt::HSXKPasswd->new()->password();
26 # this function passes all arguments on to Crypt::HSXKPasswd->new()
28 # so all the same customisations can be specified, e.g. specifying a
29 # config preset:
30 my $password = hsxkpasswd(preset => 'XKCD');
31 #
33 # Object Oriented Interface - recommended for generating multiple passwords
34 #
35 # create a new instance with the default dictionary, config, and random
37 # number generator
38 my $hsxkpasswd_instance = Crypt::HSXKPasswd->new();
39 # generate a single password
41 my $password = $hsxkpasswd_instance->password();
42 # generate multiple passwords
44 my @passwords = $hsxkpasswd_instance->passwords(10);
45
47 A secure memorable password generator inspired by the wonderful XKCD
48 webcomic at <http://www.xkcd.com/> and Steve Gibson's Password
49 Haystacks page at <https://www.grc.com/haystack.htm>. This is the Perl
50 module that powers <https://www.xkpasswd.net>.
51 PHILOSOPHY
53 More and more of the things we do on our computer require passwords,
54 and at the same time it seems we hear about organisations or sites
55 losing user database on every day that ends in a y. If we re-use our
56 passwords we expose ourself to an ever greater risk, but we need more
57 passwords than we can possibly remember or invent. Coming up with one
58 good password is easy, but coming up with one good password a week is a
59 lot harder, let alone one a day!
60 Obviously we need some technological help. We need our computers to
62 help us generate robust password and store them securely. There are
63 many great password managers out there to help us securely store and
64 sync our passwords, including commercial offerings and open-source
65 projects. Many of these managers also offer to generate random
66 passwords for us, usually in the form of a random string of meaningless
67 letters numbers and symbols. These kinds of nonsense passwords are
68 certainly secure, but they are often impractical.
69 Regardless of how good your chosen password manager is, there will
71 always be times when you need to type in your passwords, and that's
72 when random gibberish passwords become a real pain point. As annoying
73 as it is to have to glance over and back at a small cellphone screen to
74 manually type a gibberish password into a computer, that's nothing
75 compared to the annoyance of trying to communicate such a password to a
76 family member, friend, colleague or customer over the phone.
77 Surely it would be better to have passwords that are still truly random
79 in the way humans can't be, but are also human-friendly in the way
80 random gibberish never will be? This is the problem this module aims to
81 solve.
82 Rather than randomly choosing many letters, digits, and symbols from a
84 fairly small alphabet of possible characters, this library chooses a
85 small number of words from a large alphabet of possible words as the
86 basis for passwords. Words are easy to remember, easy to read from a
87 screen, easy to type, and easy to communicate over the telephone.
88 This module uses words to make up the bulk of the passwords it
90 generates, but it also adds carefully placed symbols and digits to add
91 security without making the passwords difficult to remember, read,
92 type, and speak.
93 In shot, this module is for people who prefer passwords that look like
95 this:
96 !15.play.MAJOR.fresh.FLAT.23!
98 to passwords that look like this:
100 eB8.GJXa@TuM
102 PASSWORD GENERATION ALGORITHM
104 This module always uses a simple five-step algorithm to generate
105 passwords, but each step can be customised, and many steps can be
106 skipped completely.
107 It's important to understand the algorithm before trying to create your
109 own custom configurations for this module.
110 The algorithm is broken in to the following steps:
112 1. Pick random words from the dictionary.
114 2. Apply transformations to the words.
116 3. Create pseudo-words made up for randomly chosen digits and add them
118 as the first and last words.
119 4. Insert a copy of the same symbol between each of the words and
121 pseudo-words. This symbol is referred to as the separator
122 character.
123 5. Pad the password with multiple instances of the same symbol front
125 and/or back. This symbol is referred to as the padding character.
126 You can visualise this process as follows:
128 correct horse batter staple
130 correct HORSE battery staple
131 25 correct HORSE battery staple 83
132 25*correct*HORSE*battery*staple*83
133 ++25*correct*HORSE*battery*staple*83++
134 Each of these steps can be customised in the following ways:
136 1. The number of words to be used, and the minimum and maximum lengths
138 of the words can be configured.
139 2. The case of the words can be modified in a number of ways,
141 including randomly choosing the case for each word.
142 It is also possible to specify so-called 133t-style character
144 substitutions, e.g. replacing all occurrences of the letter "e"
145 with the digit 3, or all occurrences of the letter "s" with the
146 symbol "$".
147 3. The number of digits to add as pseudo words to the front and back
149 of the password can be configured. A length of zero can be
150 specified for both to generate passwords without any randomly
151 chosen digits.
152 4. The separator character can be specified directly, or it can be
154 randomly chosen from a list of symbols. It is also possible to
155 specify that no separator should be used.
156 5. The padding character can also be specified directly, or remotely
158 chosen from a list of possible symbols. Padding can also be
159 disabled completely. If padding is to be used it can be applied in
160 two modes - fixed, and adaptive.
161 With fixed padding a specified number of copies of the separator
163 character are added to the front and back of the password. The
164 fixed padding does not have to be symmetric.
165 With adaptive padding the required number of copies of the
167 separator character are added to the back of the password until it
168 reaches a specified length.
169 THE MATHS
171 Before examining the password strength of passwords generated with this
172 module we need to lay out the relatively simple maths underlying it
173 all.
174 Maths Primer
176 A coin could be used as a very simple password generator. Each
178 character in the password would be the result of a single coin toss. If
179 the coin lands heads up, we add a "H" to our password, if it lands
180 tails up, we add a "T".
181 If you made a one-letter password in this way there would only be two
183 possibilities, "H", or "T", or two permutations. If you made a two-
184 letter password in this way there would be four possible combinations,
185 or permutations, "HH", "HT", "TH", and "TT". If you made a three-
186 character password in this way there would be 16 permutations, a five
187 character one would have 32 permutations, and so forth.
188 So, for a coin toss, which has two possible values for each character,
190 the formula for the number of permutations "P" for a given length of
191 password "L" is:
192 P = 2^L
194 Or, two to the power of the length of the password.
196 If we now swapped our coin for a dice, we would go from two possible
198 values per letter, to six possible values per letter. For one dice roll
199 there would be six permutations, for two there would be 36, for three
200 there would be 108 and so on.
201 This means that for a dice, the number of permutations can be
203 calculated with the formula:
204 P = 6^L
206 When talking about passwords, the set of possible symbols used for each
208 character in the password is referred to as the password's alphabet.
209 So, for the coin toss the alphabet was just "H" and "T", and for the
210 dice it was 1, 2, 3, 4, 5, and 6. The actual characters used in the
211 alphabet make no difference to the strength of the password, all that
212 matters is the size of the alphabet, which we'll call "A".
213 As you can probably infer from the two examples above, the formula for
215 the number of possible permutations "P" for a password of length "L"
216 created from an alphabet of size "A" is:
217 P = A^L
219 In the real world our passwords are generally made up of a mix of
221 letters, digits, and symbols. If we use mixed case that gives us 52
222 letters alone, then add in the ten digits from 0 to 9 and we're already
223 up to 62 possible characters before we even start on the array of
224 symbols and punctuation characters on our keyboards. It's generally
225 accepted that if you include symbols and punctuation, there are 95
226 characters available for use in randomly generated passwords. Hence, in
227 the real-world, the value for "A" is assumed to be 95. When you start
228 raising a number as big as 95 to even low powers the number of
229 permutations quickly rises.
230 A two character password with alphabet of 95 has 9025 permutations,
232 increasing the length to three characters brings that up to 857,375,
233 and so on. These numbers very quickly become too big to handle. For
234 just an 8 character password we are talking about 6,634,204,312,890,625
235 permutations, which is a number so big most people couldn't say it
236 (what do you call something a thousand times bigger than a trillion?).
237 Because the numbers get so astronomically big so quickly, computer
239 scientists use bits of entropy to measure password strength rather than
240 the number of permutations. The formula to turn permutations into bits
241 of entropy "E" is very simple:
242 E = Log(2)P
244 In other words, the entropy is the log to base two of the permutations.
246 For our eight character example that equates to about 52 bits.
247 There are two approaches to increasing the number of permutations, and
249 hence the entropy, you can choose more characters, or, you can make the
250 alphabet you are choosing from bigger.
251 The Entropy of HSXKPasswd Passwords
253 Exactly how much entropy does a password need? That's the subject of
255 much debate, and the answer ultimately depends on the value of the
256 assets being protected by the password.
257 Two common recommendations you hear are 8 characters containing a mix
259 of upper and lower case letters, digits, and symbols, or 12 characters
260 with the same composition. These evaluation to approximately 52 bits of
261 entropy and 78 bits of entropy respectively.
262 When evaluating the entropy of passwords generated by this module, it
264 has to be done from two points of view for the answer to be meaningful.
265 Firstly, a best-case scenario - the attacker has absolutely no
266 knowledge of how the password was generated, and hence must mount a
267 brute-force attack. Then, secondly from the point of view of an
268 attacker with full knowledge of how the password was generated. Not
269 just the knowledge that this module was used, but a copy of the
270 dictionary file used, and, a copy of the configuration settings used.
271 For the purpose of this documentation, the entropy in the first
273 scenario, the brute force attack, will be referred to as the blind
274 entropy, and the entropy in the second scenario the seen entropy.
275 The blind entropy is solely determined by the configuration settings,
277 the seen entropy depends on both the settings and the dictionary file
278 used.
279 Calculating the bind entropy "Eb" is quite straightforward, we just
281 need to know the size of the alphabet resulting from the configuration
282 "A", and the minimum length of passwords generated with the
283 configuration "L", and plug those values into this formula:
284 Eb = Log(2)(A^L)
286 Calculating "A" simply involves determining whether or not the
288 configuration results in a mix of letter cases (26 or 52 characters),
289 the inclusion of at least one symbol (if any one is present, assume the
290 industry standard of a 33 character search space), and the inclusion of
291 at least one digit (10 character). This will result in a value between
292 26 and 95.
293 Calculating "L" is also straightforward. The one minor complication is
295 that some configurations result in a variable length password. In this
296 case, assume the shortest possible length the configuration could
297 produce.
298 The example password from the "PHILOSOPHY" section
300 ("!15.play.MAJOR.fresh.FLAT.23!") was generated using the preset
301 "WEB32". This preset uses four words of between four and five letters
302 long, with the case of each word randomly set to all lower or all upper
303 as the basis for the password, it then chooses two pairs of random
304 digits as extra words to go front and back, before separating each word
305 with a copy of a randomly chosen symbol, and padding the front and back
306 of the password with a copy of a different randomly chosen symbol. This
307 results in passwords that contain a mix of cases, digits, and symbols,
308 and are between 27 and 31 characters long. If we add these values into
309 the formula we find that the blind entropy for passwords created with
310 this preset is:
311 Eb = Log(2)(95^27) = 163 bits
313 This is spectacularly secure! And, this is the most likely kind of
315 attack for a password to face. However, to have confidence in the
316 password we must also now calculate the entropy when the attacker knows
317 everything about how the password was generated.
318 We will calculate the entropy resulting from the same "WEB32" config
320 being used to generate a password using the sample library file that
321 ships with the module.
322 The number of permutations the attacker needs to check is purely the
324 product of possibly results for each random choice made during the
325 assembly of the password.
326 Lets start with the words that will form the core of the password. The
328 configuration chooses four words of between four and five letters long
329 from the dictionary, and then randomises their case, effectively making
330 it a choice from twice as many words (each word in each case).
331 The sample dictionary file contains 698 words of the configured length,
333 which doubles to 1396. Choosing four words from that very large
334 alphabet gives a starting point of "1396^4", or 3,797,883,801,856
335 permutations.
336 Next we need to calculate the permutations for the separator character.
338 The configuration specifies just nine permitted characters, and we
339 choose just one, so that equates to 9 permutations.
340 Similarly, the padding character on the end is chosen from 13 permitted
342 symbols giving 13 more permutations.
343 Finally, there are four randomly chosen digits, giving "10^4", or
345 10,000 permutations.
346 The total number of permutations is the product of all these
348 permutations:
349 Pseen = 3,797,883,801,856 * 9 * 13 * 10,000 = 2.77x10^17
351 Finally, we convert this to entropy by taking the base 2 log:
353 Eseen = Log(2)2.77x10^17 = ~57bits
355 What this means is that most probably, passwords generated with this
357 preset using the sample dictionary file are spectacularly more secure
358 than even 12 randomly chosen characters, and, that in the very unlikely
359 event that an attackers knows absolutely everything about how the
360 password was generated, it is still significantly more secure than 8
361 randomly chosen characters.
362 Because the exact strength of the passwords produced by this module
364 depend on the configuration and dictionary file used, the constructor
365 does the above math when creating an HSXKPasswd object, and throws a
366 warning if either the blind entropy falls below 78bits, or the seen
367 entropy falls below 52 bits.
368
370 MODULE CONFIGURATION
371 It is possible to tweak the module's behaviour in certain areas by
372 updating the values contained within a set of module configuration
373 keys. The values associated with these keys can be accessed and updated
374 via the class function "module_config()".
375 # get the current debug status
377 my $debug_status = Crypt::HSXKPasswd->module_config('DEBUG');
378 # configure the module to suppress all entropy warnings
380 Crypt::HSXKPasswd->module_config('ENTROPY_WARNINGS', 'NONE');
381 The following module configuration keys exist within the module:
383 • "DEBUG" - A True/False value denoting whether or not the module
385 should print debug messages. The default is not to print debug
386 messages.
387 For more details see the DIAGNOSTICS section of this document.
389 • "LOG_ERRORS" - A True/False value denoting whether or not errors
391 should be logged. The default is not to log.
392 For more details see the DIAGNOSTICS section of this document.
394 • "LOG_STREAM" - the stream to which debug messages should be printed
396 if debugging is enabled, and log messages should be printed when
397 error logging is enabled. The default is to print to "STDERR".
398 For more details see the DIAGNOSTICS section of this document.
400 • "ENTROPY_MIN_BLIND" - the minimum allowable entropy against brute
402 force attacks in bits. The default is 78 bits.
403 For more details see the ENTROPY CHECKING section of this document.
405 • "ENTROPY_MIN_SEEN" - the minimum allowable entropy against an
407 attacker with full knowledge. The default is 52 bits.
408 For more details see the ENTROPY CHECKING section of this document.
410 • "ENTROPY_WARNINGS" - control the emission of entropy warnings. The
412 value must be one of "ALL", "BLIND", or "NONE". The default value
413 is "ALL".
414 For more details see the ENTROPY CHECKING section of this document.
416 CUSTOM DATA TYPES
418 This module uses a custom type library created with "Type::Library" for
419 data validation. It is important to know this for two reasons -
420 firstly, these custom types are mentioned in many error messages, and
421 secondly these custom types are available for developers to use in
422 their own code, either when utilising "Crypt::HSXKPasswd", or writing
423 custom word sources by extending "Crypt::HSXKPasswd::Dictionary", or
424 when writing custom random number generators by extending
425 "Crypt::HSXKPasswd::RNG".
426 Defined Types
428 • "NonEmptyString" - a string containing at least one character.
430 • "PositiveInteger" - a whole number greater than or equal to zero.
432 • "NonZeroPositiveInteger" - a whole number greater than zero.
434 • "TrueFalse" - a reasonable boolean value, specifically, "undef",
436 and empty string, or 0 to indicate false, and a 1 to indicate true.
437 • "PerlPackageName" - string representing a valid Perl package name
439 like "Crypt::HSXKPasswd::Dictionary::NL".
440 • "Letter" - a string containing a single letter. Because this module
442 is Unicode-aware, it should be noted that a letter is defined as a
443 single Unicode grapheme with the Unicode property "Letter". What
444 this means is that accented letters like "e" are considered valid,
445 as are ligatures like "ae".
446 • "Symbol" - a string containing a single non-letter character.
448 Because this module is Unicode-aware, should be noted that a non-
449 letter character is defined as a single Unicode grapheme that does
450 not have the Unicode property "Letter". What this means is that
451 neither letters, accented characters, nor ligatures can be used as
452 symbols, but just about every other Unicode character can,
453 including punctuation symbols, mathematical symbols, and even
454 emoji!
455 • "Word" - a string containing only letters (as defined by the type
457 "Letter"), and at least four long.
458 • "SymbolAlphabet" - a symbol alphabet is a reference to an array
460 that contains at least two distinct symbols (as defined by the type
461 "Symbol"), and no values that are not symbols.
462 • "WordLength" - a valid value when specifying the length of a word,
464 specifically, a whole number greater than or equal to four.
465 • "ConfigKeyDefinition" - a valid configuration key definition. A
467 reference to a hash mapping "required" to a true/false value,
468 "expects" to a non-empty string, and "type" to a "Type::Tiny"
469 object.
470 • "ConfigKeyName" - a valid configuration key name, see the
472 CONFIGURATION section of this document for a description of each
473 configuration key supported by this module. You can get a list of
474 valid configuration key names programatically by calling the
475 function "Crypt::HSXKPasswd-"defined_config_keys()>.
476 • "ConfigKeyAssignment" - a mapping between a valid configuration key
478 name and a valid value for that configuration key.
479 • "ConfigOverride" - a reference to hash containing one or more
481 configuration key assignments as defined by the type
482 "ConfigKeyAssignment".
483 • "Config" - a reference to a hash that contains a complete and valid
485 set of mappings between configuration key names and values. For a
486 config to be considered valid it must contain only valid valid
487 configuration key assignments as defined by the type
488 "ConfigKeyAssignment", must contain a configuration key assignment
489 for each required configuration key and all interdependencies
490 between the specified configuration key assignments must be
491 fulfilled.
492 See the CONFIG section of this document for a detailed description
494 of each of the defined configuration keys and their various
495 interdependencies.
496 • "PresetDefinition" - a valid preset definition. A reference to a
498 hash mapping "description" to a non-empty string, and "config" to
499 a valid Config.
500 • "PresetName" - a valid preset name, see the PRESETS section of this
502 document for a description of each preset supported by this module.
503 You can get a list of valid preset names programatically by calling
504 the function "Crypt::HSXKPasswd-"defined_presets()>.
505 Using the Custom Types
507 The library of custom types is defined in the package
509 "Crypt::HSXKPasswd::Types", and it is a standard "Type::Library" type
510 library containing "Type::Tiny" type definitions.
511 Useful Links:
513 • The documentation for "Type::Tiny" -
515 <http://search.cpan.org/perldoc?Type%3A%3ATiny>
516 • The documentation for "Type::Library" -
518 <http://search.cpan.org/perldoc?Type%3A%3ALibrary>
519 To use the bare type definitions listed above, import the module as
521 follows:
522 use Crypt::HSXKPasswd::Types qw( :types );
524 Each type listed above will now be imported, and become available as a
526 bare word. The "Type::Tiny" documentation provides a full list of
527 available functions, but the examples below illustrate some of the more
528 useful ones:
529 $is_valid = Letter->check('e'); # $is_valid = 1
531 $is_valid = Letter->check('-'); # $is_valid = undef
532 $err_msg = Letter->validate('e'); # $err_msg = undef
533 $err_msg = Letter->validate('-'); # $err_msg = "'-' is not a Letter ...
534 # ... (must be a string containing exactly one letter)"
535 "Type::Library" automatically creates an "is_TypeName" function for
537 each type defined in the library. These are not imported by default. To
538 import them add the export tag ":is" to the "use" line. I would
539 recommend the following "use" line:
540 use Crypt::HSXKPasswd::Types qw( :types :is );
542 You can now do things like the following:
544 $is_valid = is_Letter('e'); # $is_valid = 1
546 $is_valid = is_Letter('-'); # $is_valid = undef
547 Each of the types listed above also contains a custom function using
549 "Type::Tiny"'s new, and still officially experimental, "my_methods"
550 feature. The custom function is called "my_english", and can be used
551 to return an English description of the values considered valid by the
552 type, e.g.:
553 print Letter->my_english(); # prints: a string containing exactly one letter
555 As well as the named types listed above, there are also anonymous types
557 defined for each supported configuration key. These can be accessed
558 using the function "Crypt::HSXKPasswd-"config_key_definitions()>.
559 If declaring your own "Type::Tiny" types, you may also find the public
561 subroutine "Crypt::HSXKPasswd::Types::var_to_string()" useful - it will
562 turn anything passed as a scalar into a meaningful string, truncating
563 any resulting strings longer than 72 characters in nice way. All the
564 custom error messages in all the types defined in
565 "Crypt::HSXKPasswd::Types" make use of this subroutine.
566 CONFIGURATION
568 The module builds passwords using the following process.
569 First, a set of words are randomly chosen from the word source. Then,
571 two pseudo-words made of one or more digits may added before and/or
572 after the words from. Next, a separator character may be placed between
573 all the words (including the groups of digits), and one or more
574 occurrences of a padding symbol may be added front and/or back.
575 You can envisage the process as follows:
577 correct HORSE BATTERY staple
579 34 correct HORSE BATTERY staple 56
580 34-correct-HORSE-BATTERY-staple-56
581 !!34-correct-HORSE-BATTERY-staple-56!!
582 Many aspects of this password generation process are configurable. You
584 can control the length and number of words chosen, and what, if any,
585 case transformations should be applied to those words, and how accented
586 characters should be treated. How many, if any, digits should be added
587 front and back. What symbol, if any, should be used as a separator.
588 And finally how the password should be padded, if at all, and with what
589 symbol. Passwords can be padded to a given length, or by a given number
590 of symbols front and back.
591 The symbols used as the separator and for padding can be explicitly
593 specified, or the they can be randomly chosen from a given alphabet of
594 possible symbols. Both symbols can be randomly chosen from the same
595 alphabet, or from two separately specified alphabets.
596 Every instance of an HSXKPasswd password generator stores its
598 configuration as a set of name-value pairs, referred to as
599 configuration keys throughout this documentation.
600 Configurations can be specified either as a complete set of
602 configuration keys with values that together form a valid
603 configuration, as a named preset, or, as a named preset accompanied by
604 a list of one or more configuration keys with new values to override
605 those specified by the preset.
606 The module contains a preset called "DEFAULT", and this preset is used
608 if no configuration is specified. The function "default_config()" will
609 return a copy of this configuration as a reference to a hashtable.
610 For more details on how to specify configurations, see the
612 documentation for the constructor (the function "new()") below.
613 Password Generator Configuration Keys
615 Below is a list of all the configuration keys that can be used to
617 customise the password generation algorithm. Each configuration key is
618 accompanied by a description of what aspect of the algorithm they
619 control, and any validation rules that apply to the key.
620 Note that some keys are always required, and that there are
622 dependencies between keys. For examples, if you specify that the
623 separator symbol should be chosen at random, you must also specify an
624 alphabet from which the symbol should be randomly chosen.
625 • "allow_accents" (optional) - if not specified, or if a falsy value
627 is specified, accents will be removed from letters in the generated
628 passwords. E.g. "e" becomes "e". If a truthy value is specified,
629 accents will be preserved, and appear in the generated passwords.
630 • "case_transform" (required) - the transformations, if any, that
632 should be applied to the words that appear in the generated
633 passwords. The value specified must be one of the following:
634 • "ALTERNATE" - each alternate word will be converted to all
636 upper case and all lower case. The case of the first word is
637 chosen at random.
638 • "CAPITALISE" - the first letter in every word will be converted
640 to upper case, all other letters will be converted to lower
641 case.
642 • "INVERT" - the first letter in every word will be converted to
644 lower case, all other letters will be converted to upper case.
645 • "LOWER" - all letters in all the words will be converted to
647 lower case. Use of this option is strongly discouraged for
648 security reasons.
649 • "NONE" - the case of the letters that make up the words will
651 not be altered from how they were specified in the original
652 word source.
653 • "RANDOM" - each word will be randomly converted to all upper
655 case or all lower case.
656 • "UPPER" - all letters in all the words will be converted to
658 upper case. Use of this option is strongly discouraged for
659 security reasons.
660 The function "default_config()" returns a value of "CAPITALISE" for
662 this key.
663 • "character_substitutions" (optional) - a reference to a hashtable
665 containing containing zero or more character substitutions to be
666 applied to the randomly chosen words when generating passwords. The
667 keys in the hashtable must be single letters. The substitutions can
668 contain multiple characters. Specifying one or more substitutions
669 with a length greater than one could lead to passwords being longer
670 than expected, and to entropy calculations being under estimated.
671 The module will issue a warning when such a config is loaded.
672 • "num_words" (required) - the number of words to randomly choose
674 from the word source as the basis for the generated passwords.
675 The function "default_config()" returns a value of 3 for this key.
677 • "pad_to_length" (conditionally required) - the length generated
679 passwords must be padded to when using adaptive padding, i.e. when
680 "padding_type" is set to "ADAPTIVE"). The value must be an integer
681 greater than or equal to 12. Lengths of less than 12 are not
682 permitted for security reasons.
683 • "padding_alphabet" (optional) - this key is ignored unless the
685 configuration specifies that the padding character should be
686 randomly chosen, i.e. unless "padding_character" is set to
687 "RANDOM".
688 When the padding character is set to be randomly chosen, the module
690 will check for the presence of this key. If it is specified, the
691 padding character will be randomly chosen from the set of symbols
692 defined by this key. If this key is not set, the module will use
693 the set of symbols specified by the key "symbol_alphabet". If
694 neither this key nor "symbol_alphabet" are specified, then the
695 configuration will be considered invalid.
696 If specified, this key must be a reference to an array of single-
698 character strings.
699 • "padding_character" (conditionally required) - this key is unless
701 the key "padding_type" is set to "NONE". It specifies the padding
702 symbol to be used when generating passwords.
703 If specified, they key's value must be a single character string,
705 or one of the following special values:
706 • "RANDOM" - the character should be randomly chosen from the set
708 of characters specified by the key "padding_alphabet" or
709 "symbol_alphabet". If specified, "padding_alphabet" takes
710 precedence over "symbol_alphabet". If this value is specified
711 for "padding_character", and neither "padding_alphabet" nor
712 "symbol_alphabet" are specified, the configuration will be
713 considered invalid.
714 • "SEPARATOR" - pad the password with the same symbol that is
716 used to separate the words. The key "padding_character" cannot
717 be set to "SEPARATOR" when the key "separator_character" is set
718 to "NONE".
719 The function "default_config" return the value "RANDOM" for this
721 key.
722 • "padding_characters_before" & "padding_characters_after"
724 (conditionally required) - both of these keys are required if the
725 key "padding_type" is set to "FIXED".
726 These keys specify the number of padding symbols that should be
728 added to the front and back of the password.
729 Both keys require that the specified value be an integer greater
731 than or equal to zero.
732 The function "default_config()" returns a value of 2 for both of
734 these keys.
735 • "padding_digits_before" & "padding_digits_after" (required) - the
737 number of random digits to include before and after the randomly
738 chosen words when generating passwords.
739 Both keys require that the specified value be an integer greater
741 than or equal to zero.
742 The function "default_config()" returns a value of 2 for both of
744 these keys.
745 • "padding_type" (required) - the way in which padding symbols should
747 be added when generating passwords.
748 Only the following values are valid for this key:
750 • "NONE" - do not add any padding symbols when generating
752 passwords.
753 • "FIXED" - add an exactly specified number of copies of the
755 padding symbol to the front and back of generated passwords.
756 When they key "padding_type" is set to "FIXED", the three keys
758 "padding_character", "padding_characters_before" &
759 "padding_characters_after" become required.
760 • "ADAPTIVE" - add no copies of the padding symbol will be added
762 to the front of the generated passwords, and copies of the
763 padding character will be added to the end of the generated
764 passwords until the total length of the password is equal to
765 the value specified for the key "pad_to_length".
766 Note that If the password is longer than the value specified by
768 the key "pad_to_length" before any copies of the padding symbol
769 are added, the password will be truncated to the length
770 specified by the key "pad_to_length".
771 When they key "padding_type" is set to "ADAPTIVE", the three
773 keys "padding_character", "padding_characters_before" &
774 "padding_characters_after" become required.
775 The function "default_config()" returns a value of "FIXED" for this
777 key.
778 • "separator_alphabet" (optional) - this key is ignored unless the
780 configuration specifies that the separator character should be
781 randomly chosen, i.e. unless "separator_character" is set to
782 "RANDOM".
783 When the separator character is set to be randomly chosen, the
785 module will check for the presence of this key. If it is specified,
786 the separator character will be randomly chosen from the set of
787 symbols defined by this key. If this key is not set, the module
788 will use the set of symbols specified by the key "symbol_alphabet".
789 If neither this key nor "symbol_alphabet" are specified, then the
790 configuration will be considered invalid.
791 If specified, this key must be a reference to an array of single-
793 character strings.
794 • "separator_character" (required) - the symbol to use to separate
796 the words when generating passwords.
797 The value specified for this key must be a single-character string,
799 or one of the following special values:
800 • "NONE" - no separator character will be used. I.e. the words,
802 and the groups of digits before and after the words, if any,
803 will be directly joined together.
804 "RANDOM" - a single character will be randomly chosen from the
806 list of symbols specified by one of the keys
807 "separator_alphabet" or "symbol_alphabet". If both keys are
808 set, "separator_alphabet" takes precedence.
809 The function "default_config()" returns a value of "RANDOM" for
811 this key.
812 • "symbol_alphabet" (optional) - this key specifies a default
814 alphabet of symbols that can be used when either or both the
815 separator character and the padding character are set to be chosen
816 at random. I.e. when either or both of the keys
817 "separator_character" and "padding_character" are set to "RANDOM".
818 Note that the keys "separator_alphabet" and "padding_alphabet" take
820 precedence over this key if specified.
821 The value specified for this key must be a reference to an array of
823 single-character strings.
824 The function "default_config()" returns a value of "['!', '@', '$',
826 '%', '^', '&', '*', '-', '_', '+', '=', ':', '|', '~', '?', '/',
827 '.', ';']" for this key.
828 • "word_length_min" & "word_length_max" (required) - the minimum and
830 maximum length of the words that will form the basis of the
831 generated passwords.
832 The values specified for both keys must be integers greater than
834 three, and the value specified for "word_length_max" must be
835 greater than or equal to the value specified for "word_length_min".
836 The function "default_config()" returns values of 4 and 8 for these
838 keys.
839 PRESETS
841 Below is a list of all the presets defined by this module.
842 This information can be accessed programatically using the functions
844 "defined_presets()", "presets_to_string()", "preset_description()", and
845 "preset_config()".
846 • "APPLEID" - a preset respecting the many prerequisites Apple places
848 on Apple ID passwords. Apple's official password policy cam be
849 found at the following URL: <http://support.apple.com/kb/ht4232>.
850 Note that Apple's knowledge base article omits to mention that
851 passwords can't be longer than 32 characters. This preset is also
852 configured to use only characters that are easy to type on the
853 standard iOS keyboard, i.e. those appearing on the letters keyboard
854 ("ABC") or the numbers keyboard ".?123", and not those on the
855 harder to reach symbols keyboard "#+=".
856 Sample Password:
858 -25,favor,MANY,BEAR,53-
860 Preset Definition:
862 {
864 padding_alphabet => [qw{- : . ! ? @ &}],
865 separator_alphabet => [qw{- : . @}, q{,}, q{ }],
866 word_length_min => 4,
867 word_length_max => 7,
868 num_words => 3,
869 separator_character => 'RANDOM',
870 padding_digits_before => 2,
871 padding_digits_after => 2,
872 padding_type => 'FIXED',
873 padding_character => 'RANDOM',
874 padding_characters_before => 1,
875 padding_characters_after => 1,
876 case_transform => 'RANDOM',
877 allow_accents => 0,
878 }
879 • "DEFAULT" - the default configuration.
881 Sample Password:
883 ~~12:settle:SUCCEED:summer:48~~
885 Preset Definition:
887 {
889 symbol_alphabet => [qw{! @ $ % ^ & * - _ + = : | ~ ? / . ;}],
890 word_length_min => 4,
891 word_length_max => 8,
892 num_words => 3,
893 separator_character => 'RANDOM',
894 padding_digits_before => 2,
895 padding_digits_after => 2,
896 padding_type => 'FIXED',
897 padding_character => 'RANDOM',
898 padding_characters_before => 2,
899 padding_characters_after => 2,
900 case_transform => 'ALTERNATE',
901 allow_accents => 0,
902 }
903 • "NTLM" - a preset for 14 character NTMLv1 (NTLM Version 1)
905 passwords. ONLY USE THIS PRESET IF YOU MUST! The 14 character limit
906 does not allow for sufficient entropy in scenarios where the
907 attacker knows the dictionary and config used to generate the
908 password. Use of this preset will generate a low entropy warning.
909 Sample Password:
911 0=mAYAN=sCART@
913 Preset Definition:
915 {
917 padding_alphabet => [qw{! @ $ % ^ & * + = : | ~ ?}],
918 separator_alphabet => [qw{- + = . * _ | ~}, q{,}],
919 word_length_min => 5,
920 word_length_max => 5,
921 num_words => 2,
922 separator_character => 'RANDOM',
923 padding_digits_before => 1,
924 padding_digits_after => 0,
925 padding_type => 'FIXED',
926 padding_character => 'RANDOM',
927 padding_characters_before => 0,
928 padding_characters_after => 1,
929 case_transform => 'INVERT',
930 allow_accents => 0,
931 }
932 • "SECURITYQ" - a preset for creating fake answers to security
934 questions. This preset generates long nonsense sentences ending in
935 "." "!" or "?".
936 Sample 'Password':
938 Wales outside full month minutes gentle?
940 Preset Definition:
942 {
944 word_length_min => 4,
945 word_length_max => 8,
946 num_words => 6,
947 separator_character => q{ },
948 padding_digits_before => 0,
949 padding_digits_after => 0,
950 padding_type => 'FIXED',
951 padding_character => 'RANDOM',
952 padding_alphabet => [qw{. ! ?}],
953 padding_characters_before => 0,
954 padding_characters_after => 1,
955 case_transform => 'NONE',
956 allow_accents => 0,
957 }
958 • "WEB16" - a preset for websites that don't allow passwords to be
960 longer than 16 characters. ONLY USE THIS PRESET IF YOU MUST! The 14
961 character limit does not allow for sufficient entropy in scenarios
962 where the attacker knows the dictionary and config used to generate
963 the password. Use of this preset will generate a low entropy
964 warning.
965 Sample Password:
967 tube+NICE+iron+02
969 Preset Definition:
971 {
973 symbol_alphabet => [qw{! @ $ % ^ & * - _ + = : | ~ ? / . ;}],
974 word_length_min => 4,
975 word_length_max => 4,
976 num_words => 3,
977 separator_character => 'RANDOM',
978 padding_digits_before => 0,
979 padding_digits_after => 2,
980 padding_type => 'NONE',
981 case_transform => 'RANDOM',
982 allow_accents => 0,
983 }
984 • "WEB32" - a preset for websites that don't allow passwords to be
986 longer than 32 characters.
987 Sample Password:
989 +93-took-CASE-money-AHEAD-31+
991 Preset Definition:
993 {
995 padding_alphabet => [qw{! @ $ % ^ & * + = : | ~ ?}],
996 separator_alphabet => [qw{- + = . * _ | ~}, q{,}],
997 word_length_min => 4,
998 word_length_max => 5,
999 num_words => 4,
1000 separator_character => 'RANDOM',
1001 padding_digits_before => 2,
1002 padding_digits_after => 2,
1003 padding_type => 'FIXED',
1004 padding_character => 'RANDOM',
1005 padding_characters_before => 1,
1006 padding_characters_after => 1,
1007 case_transform => 'ALTERNATE',
1008 allow_accents => 0,
1009 }
1010 • "WIFI" - a preset for generating 63 character long WPA2 keys (most
1012 routers allow 64 characters, but some only allow 63, hence the
1013 somewhat unexpected length).
1014 Sample Password:
1016 2736_ITSELF_PARTIAL_QUICKLY_SCOTLAND_wild_people_7441!!!!!!!!!!
1018 Preset Definition:
1020 {
1022 padding_alphabet => [qw{! @ $ % ^ & * + = : | ~ ?}],
1023 separator_alphabet => [qw{- + = . * _ | ~}, q{,}],
1024 word_length_min => 4,
1025 word_length_max => 8,
1026 num_words => 6,
1027 separator_character => 'RANDOM',
1028 padding_digits_before => 4,
1029 padding_digits_after => 4,
1030 padding_type => 'ADAPTIVE',
1031 padding_character => 'RANDOM',
1032 pad_to_length => 63,
1033 case_transform => 'RANDOM',
1034 allow_accents => 0,
1035 }
1036 • "XKCD" - a preset inspired by the original XKCD comic
1038 (<http://xkcd.com/936/>), but with some alterations to provide
1039 sufficient entropy to avoid low entropy warnings.
1040 Sample Password:
1042 quiet-children-OCTOBER-today-HOPE
1044 Preset Definition:
1046 {
1048 word_length_min => 4,
1049 word_length_max => 8,
1050 num_words => 5,
1051 separator_character => q{-},
1052 padding_digits_before => 0,
1053 padding_digits_after => 0,
1054 padding_type => 'NONE',
1055 case_transform => 'RANDOM',
1056 allow_accents => 0,
1057 }
1058 FUNCTIONAL INTERFACE
1060 Although the package was primarily designed to be used in an object-
1061 oriented way, there is a functional interface too. The functional
1062 interface initialises an object internally and then uses that object to
1063 generate a single password. If you only need one password, this is no
1064 less efficient than the object-oriented interface, however, if you are
1065 generating multiple passwords it is much less efficient.
1066 There is only a single function exported by the module:
1068 hsxkpasswd()
1070 my $password = hsxkpasswd();
1072 This function call is equivalent to the following Object-Oriented code:
1074 my $password = Crypt::HSXKPasswd->new()->password();
1076 This function passes all arguments it receives through to the
1078 constructor, so all arguments that are valid in "new()" are valid here.
1079 This function Croaks if there is a problem generating the password.
1081 Note that it is inefficient to use this function to generate multiple
1083 passwords because the dictionary will be re-loaded, and the entropy
1084 stats re-calculated each time the function is called.
1085 CONSTRUCTOR
1087 # create a new instance with the default dictionary, config, and random
1088 # number generator
1089 my $hsxkpasswd_instance = Crypt::HSXKPasswd->new();
1090 # the constructor takes optional named arguments, these can be used to
1092 # customise the word source, config, and random number source.
1093 # create an instance that uses the UNIX words file as the word source
1095 my $hsxkpasswd_instance = Crypt::HSXKPasswd->new(
1096 dictionary => Crypt::HSXKPasswd::Dictionary::System->new()
1097 );
1098 # create an instance that uses an array reference as the word source
1100 my $hsxkpasswd_instance = Crypt::HSXKPasswd->new(dictionary_list => $array_ref);
1101 # create an instance that uses a dictionary file as the word source
1103 my $hsxkpasswd_instance = Crypt::HSXKPasswd->new(
1104 dictionary_file => 'sample_dict_EN.txt'
1105 );
1106 # the class Crypt::HSXKPasswd::Dictionary::Basic can be used to aggregate
1108 # multiple array refs and/or dictionary files into a single word source
1109 my $dictionary = Crypt::HSXKPasswd::Dictionary::Basic->new();
1110 $dictionary->add_words('dict1.txt');
1111 $dictionary->add_words('dict2.txt');
1112 $dictionary->add_words($array_ref);
1113 my $hsxkpasswd_instance = Crypt::HSXKPasswd->new(dictionary => $dictionary);
1114 # create an instance from the preset 'XKCD'
1116 my $hsxkpasswd_instance = Crypt::HSXKPasswd->new(preset => 'XKCD');
1117 # create an instance based on the preset 'XKCD' with one customisation
1119 my $hsxkpasswd_instance = Crypt::HSXKPasswd->new(
1120 preset => 'XKCD',
1121 preset_override => {separator_character => q{ }}
1122 );
1123 # create an instance from a config based on a preset
1125 # but with many alterations
1126 my $config = Crypt::HSXKPasswd->preset_config('XKCD');
1127 $config->{separator_character} = q{ };
1128 $config->{case_transform} = 'INVERT';
1129 $config->{padding_type} = "FIXED";
1130 $config->{padding_characters_before} = 1;
1131 $config->{padding_characters_after} = 1;
1132 $config->{padding_character} = '*';
1133 my $hsxkpasswd_instance = Crypt::HSXKPasswd->new(config => $config);
1134 # create an instance from an entirely custom configuration
1136 my $config = {
1137 padding_alphabet => [qw{! @ $ % ^ & * + = : ~ ?}],
1138 separator_alphabet => [qw{- + = . _ | ~}],
1139 word_length_min => 6,
1140 word_length_max => 6,
1141 num_words => 3,
1142 separator_character => 'RANDOM',
1143 padding_digits_before => 2,
1144 padding_digits_after => 2,
1145 padding_type => 'FIXED',
1146 padding_character => 'RANDOM',
1147 padding_characters_before => 2,
1148 padding_characters_after => 2,
1149 case_transform => 'CAPITALISE',
1150 }
1151 my $hsxkpasswd_instance = Crypt::HSXKPasswd->new(config => $config);
1152 # create an instance from an entire custom config passed as a JSON string
1154 # a convenient way to use configs generated using the web interface at
1155 # https://xkpasswd.net
1156 my $config = <<'END_CONF';
1157 {
1158 "num_words": 4,
1159 "word_length_min": 4,
1160 "word_length_max": 8,
1161 "case_transform": "RANDOM",
1162 "separator_character": " ",
1163 "padding_digits_before": 0,
1164 "padding_digits_after": 0,
1165 "padding_type": "NONE",
1166 }
1167 END_CONF
1168 my $hsxkpasswd_instance = Crypt::HSXKPasswd->new(config_json => $config);
1169 # create an instance which uses /dev/urandom as the RNG
1171 # (only possible on Linux/Unix only systems)
1172 my $hsxkpasswd_instance = Crypt::HSXKPasswd->new(
1173 rng => Crypt::HSXKPasswd::RNG::DevUrandom->new();
1174 );
1175 # create an instance which uses Random.Org as the random number generator
1177 # NOTE - this should be used sparingly, and only by the paranoid. If you
1178 # abuse this RNG your IP will get blacklisted on Random.Org. You must pass
1179 # a valid email address to the constructor for
1180 # Crypt::HSXKPasswd::RNG::RandomDorOrg because Random.Org's usage
1181 # guidelines request that all invocations to their API contain a contact
1182 # email in the useragent header, and this module honours that request.
1183 my $hsxkpasswd_instance = Crypt::HSXKPasswd->new(
1184 rng => Crypt::HSXKPasswd::RNG::RandomDorOrg->new('your.email@addre.ss');
1185 );
1186 The constructor must be called via the package name.
1188 If called with no arguments the constructor will use an instance of
1190 "Crypt::HSXKPasswd::Dictionary::EN" as the word source, the preset
1191 "DEFAULT", and an instance of the class "Crypt::HSXKPasswd::RNG::Basic"
1192 to generate random numbers.
1193 The function accepts named arguments to allow for custom specification
1195 of the word source, config, and random number source.
1196 Specifying Custom Word Sources
1198 Three named arguments can be used to specify a word source, but only
1200 one should be specified at a time. If multiple are specified, the one
1201 with the highest priority will be used, and the rest ignored. The
1202 variables are listed below in descending order of priority:
1203 • "dictionary" - an instance of a class that extends
1205 "Crypt::HSXKPasswd::Dictionary".
1206 • "dictionary_list" - a reference to an array containing words as
1208 scalars.
1209 • "dictionary_file" - the path to a dictionary file. Dictionary files
1211 should contain one word per. Lines starting with a # symbol will be
1212 ignored. It is assumed files will be UTF-8 encoded. If not, a
1213 second named argument, "dictionary_file_encoding", can be used to
1214 specify another encoding.
1215 Specifying Custom Password Generator Configurations
1217 Two primary named arguments can be used to specify the config the
1219 instance should use to generate passwords. Only one should be specified
1220 at a time. If multiple are specified, the one with the highest priority
1221 will be used, and the rest ignored. The variables are listed below in
1222 descending order of priority:
1223 • "config" - a valid config hashref.
1225 • "config_json" - a JSON string representing a valid config hashref.
1227 This named argument provides a convenient way to use configs
1229 generated using the web interface at <https://xkpasswd.net/>. The
1230 Save/Load tab in that interface saves and loads configs in JSON
1231 format.
1232 • "preset" - a valid preset name. If this variable is used, then any
1234 desired config overrides can be passed as a hashref using the
1235 variable "preset_overrides".
1236 Specifying Custom Random Number Generators
1238 A custom RNG can be specified using the named argument "rng". The
1240 passed value must be an instance of a class that extends
1241 "Crypt::HSXKPasswd::RNG" and overrides the function "random_numbers()".
1242 INSTANCE METHODS
1244 NOTE - all instance methods must be invoked on a Crypt::HSXKPasswd
1245 object or they will croak.
1246 ->config()
1248 my $config = $hsxkpasswd_instance->config(); # getter
1250 $hsxkpasswd_instance->config($config_hashref); # setter
1251 $hsxkpasswd_instance->config($config_json_string); # setter
1252 When called with no arguments the function returns a clone of the
1254 instance's config hashref.
1255 When called with a single argument the function sets the config of the
1257 instance to a clone of the passed config. If present, the argument must
1258 be either a hashref containing valid config keys and values, or a JSON
1259 string representing a hashref containing valid config keys and values.
1260 The function will croak if an invalid config is passed.
1262 ->config_as_json()
1264 my $config_json_string = $hsxkpasswd_instance->config_as_json();
1266 This function returns the content of the instance's loaded config
1268 hashref as a JSON string.
1269 The output from this function can be loaded into the web interface at
1271 <https://xkpasswd.net> (using the load/save tab).
1272 ->config_as_string()
1274 my $config_string = $hsxkpasswd_instance->config_as_string();
1276 This function returns the content of the instance's loaded config
1278 hashref as a scalar string.
1279 ->dictionary()
1281 my $dictionary_clone = $hsxkpasswd_instance->dictionary();
1283 $hsxkpasswd_instance->dictionary($dictionary_instance);
1284 $hsxkpasswd_instance->dictionary($array_ref);
1285 $hsxkpasswd_instance->dictionary('sample_dict_EN.txt');
1286 $hsxkpasswd_instance->dictionary('sample_dict_EN.txt', 'Latin1');
1287 When called with no arguments this function returns a clone of the
1289 currently loaded dictionary which will be an instance of a class that
1290 extends "Crypt::HSXKPasswd::Dictionary".
1291 To load a new dictionary into an instance, call this function with
1293 arguments. The first argument argument can be an instance of a class
1294 that extends "Crypt::HSXKPasswd::Dictionary", a reference to an array
1295 of words, or the path to a dictionary file. If either an array
1296 reference or a file path are passed, they will be used to instantiate
1297 an instance of the class "Crypt::HSXKPasswd::Dictionary::Basic", and
1298 that new instance will then be loaded into the object. If a file path
1299 is passed, it will be assumed to be UTF-8 encoded. If not, an optional
1300 second argument can be passed to specify the file's encoding.
1301 ->password()
1303 my $password = $hsxkpasswd_instance->password();
1305 This function generates a random password based on the instance's
1307 loaded config and returns it as a scalar. The function takes no
1308 arguments.
1309 The function croaks if there is an error generating the password. The
1311 most likely cause of and error is the random number generation,
1312 particularly if the loaded random generation function relies on a cloud
1313 service or a non-standard library.
1314 ->passwords()
1316 my @passwords = $hsxkpasswd_instance->passwords(10);
1318 This function generates a number of passwords and returns them all as
1320 an array.
1321 The function uses "password()" to generate the passwords, and hence
1323 will croak if there is an error generating any of the requested
1324 passwords.
1325 ->passwords_json()
1327 my $json_string = $hsxkpasswd_instance->passwords_json(10);
1329 This function generates a number of passwords and returns them and the
1331 instance's entropy stats as a JSON string representing a hashref
1332 containing an array of passwords indexed by "passwords", and a hashref
1333 of entropy stats indexed by "stats". The stats hashref itself is
1334 indexed by: "password_entropy_blind", "password_permutations_blind",
1335 "password_entropy_blind_min", "password_entropy_blind_max",
1336 "password_permutations_blind_max", "password_entropy_seen" &
1337 "password_permutations_seen".
1338 The function uses "passwords()" to generate the passwords, and hence
1340 will croak if there is an error generating any of the requested
1341 passwords.
1342 ->rng()
1344 my $rng_instance = $hsxkpasswd_instance->rng();
1346 $hsxkpasswd_instance->rng($rng_instance);
1347 When called with no arguments this function returns currently loaded
1349 Random Number Generator (RNG) which will be an instance of a class that
1350 extends "Crypt::HSXKPasswd::RNG".
1351 To load a new RNG into an instance, call this function with a single
1353 argument, an instance of a class that extends "Crypt::HSXKPasswd::RNG".
1354 ->stats()
1356 my %stats = $hsxkpasswd_instance->stats();
1358 This function generates a hash containing stats about the instance
1360 indexed by the following keys:
1361 • "dictionary_contains_accents" - 1 if the filtered word list
1363 contains accented letters, 0 otherwise.
1364 • "dictionary_filter_length_min" & "dictionary_filter_length_max" -
1366 the minimum and maximum word lengths allowed by the dictionary
1367 filter (defined by config keys "word_length_min" and
1368 "word_length_max")
1369 • "dictionary_source" - the source of the word list loaded into the
1371 instance.
1372 • "dictionary_words_filtered" - the number of words loaded from the
1374 dictionary file that meet the criteria defined by the loaded
1375 config.
1376 • "dictionary_words_percent_available" - the percentage of the words
1378 in the dictionary file that are available for use with the loaded
1379 config.
1380 • "dictionary_words_total" - the total number of words loaded from
1382 the dictionary file.
1383 • "password_entropy_blind_min" - the entropy (in bits) of the
1385 shortest password the loaded config can generate from the point of
1386 view of a brute-force attacker.
1387 • "password_entropy_blind_max" - the entropy (in bits) of the longest
1389 password the loaded config can generate from the point of view of a
1390 brute-force attacker.
1391 • "password_entropy_blind" - the entropy (in bits) of the average
1393 length of passwords the loaded config can generate from the point
1394 of view of a brute-force attacker.
1395 • "password_entropy_seen" - the entropy (in bits) of passwords
1397 generated by the instance assuming the dictionary and config are
1398 known to the attacker.
1399 • "password_length_min" - the minimum length of passwords generated
1401 by the loaded config.
1402 • "password_length_max" - the maximum length of passwords generated
1404 by the loaded config.
1405 • "password_permutations_blind_min" - the number of permutations a
1407 brute-force attacker would have to try to be sure of cracking the
1408 shortest possible passwords generated by this instance. Because
1409 this number can be very big, it's returned as a "Math::BigInt"
1410 object.
1411 • "password_permutations_blind_max" - the number of permutations a
1413 brute-force attacker would have to try to be sure of cracking the
1414 longest possible passwords generated by this instance. Because this
1415 number can be very big, it's returned as a "Math::BigInt" object.
1416 • "password_permutations_blind" - the number of permutations a brute-
1418 force attacker would have to try to be sure of cracking an average
1419 length password generated by this instance. Because this number can
1420 be very big, it's returned as a "Math::BigInt" object.
1421 • "password_permutations_seen" - the number of permutations an
1423 attacker with a copy of the dictionary and config would need to try
1424 to be sure of cracking a password generated by this instance.
1425 Because this number can be very big, it's returned as a
1426 "Math::BigInt" object.
1427 • "passwords_generated" - the number of passwords this instance has
1429 generated.
1430 • "password_random_numbers_required" - the number of random numbers
1432 needed to generate a single password using the loaded config.
1433 • "randomnumbers_cached" - the number of random numbers currently
1435 cached within the instance.
1436 • "randomnumbers_cache_increment" - the number of random numbers
1438 generated at once to replenish the cache when it's empty.
1439 • "randomnumbers_source" - the class used by the instance to generate
1441 random numbers.
1442 ->status()
1444 print $hsxkpasswd_instance->status();
1446 Generates a string detailing the internal status of the instance. Below
1448 is a sample status string:
1449 *DICTIONARY*
1451 Source: Crypt::HSXKPasswd::Dictionary::EN
1452 # words: 1425
1453 # words of valid length: 1194 (84%)
1454 *CONFIG*
1456 case_transform: 'ALTERNATE'
1457 num_words: '3'
1458 padding_character: 'RANDOM'
1459 padding_characters_after: '2'
1460 padding_characters_before: '2'
1461 padding_digits_after: '2'
1462 padding_digits_before: '2'
1463 padding_type: 'FIXED'
1464 separator_alphabet: ['!', '$', '%', '&', '*', '+', '-', '.', '/', ':', ';', '=', '?', '@', '^', '_', '|', '~']
1465 separator_character: 'RANDOM'
1466 symbol_alphabet: ['!', '$', '%', '&', '*', '+', '-', '.', '/', ':', ';', '=', '?', '@', '^', '_', '|', '~']
1467 word_length_max: '8'
1468 word_length_min: '4'
1469 *RANDOM NUMBER CACHE*
1471 Random Number Generator: Crypt::HSXKPasswd::RNG::Basic
1472 # in cache: 0
1473 *PASSWORD STATISTICS*
1475 Password length: between 24 & 36
1476 Permutations (brute-force): between 2.91x10^47 & 1.57x10^71 (average 2.14x10^59)
1477 Permutations (given dictionary & config): 5.51x10^15
1478 Entropy (Brute-Force): between 157bits and 236bits (average 197bits)
1479 Entropy (given dictionary & config): 52bits
1480 # Random Numbers needed per-password: 9
1481 Passwords Generated: 0
1482 ->update_config()
1484 $hsxkpasswd_instance->update_config({separator_character => '+'});
1486 The function updates the config within an HSXKPasswd instance. A
1488 hashref with the config options to be changed must be passed. The
1489 function returns a reference to the instance to enable function
1490 chaining. The function will croak if the updated config would be
1491 invalid in some way. Note that if this happens the running config will
1492 not have been altered in any way.
1493 CLASS METHODS
1495 NOTE - All class methods must be invoked via the package name, or they
1496 will croak.
1497 clone_config()
1499 my $clone = Crypt::HSXKPasswd->clone_config($config);
1501 This function must be passed a valid config hashref as the first
1503 argument or it will croak. The function returns a hashref.
1504 config_key_definition()
1506 my %key_definition = Crypt::HSXKPasswd->config_key_definition($key_name);
1508 A function to return the definition for a config key. The definition is
1510 returned as a hash indexed by the following keys:
1511 • "required" - 1 if the key is a required key, and 0 otherwise.
1513 • "type" - a "Type::Tiny" object representing the valid data type for
1515 the key.
1516 • "expects" - an English description of valid values for the key.
1518 config_key_definitions()
1520 my %key_definitions = Crypt::HSXKPasswd->config_key_definitions();
1522 A function to return definitions for all defined config keys as a hash
1524 indexed by config key names. Each definition is represented as a hash
1525 with the same keys as the hashes returned by the function
1526 "config_key_definition()".
1527 config_stats()
1529 my %stats = Crypt::HSXKPasswd->config_stats($config);
1531 my %stats = Crypt::HSXKPasswd->config_stats(
1532 $config,
1533 suppress_warnings => 1,
1534 );
1535 This function requires one argument, a valid config hashref. It returns
1537 a hash of statistics about a given configuration. The hash is indexed
1538 by the following:
1539 • "length_min" - the minimum length a password generated with the
1541 given config could be.
1542 • "length_max" - the maximum length a password generated with the
1544 given config could be. (see caveat below)
1545 • "random_numbers_required" - the amount of random numbers needed to
1547 generate a password using the given config.
1548 There is one scenario in which the calculated maximum length will not
1550 be reliably accurate, and that's when a character substitution with a
1551 length greater than 1 is specified, and "padding_type" is not set to
1552 "ADAPTIVE". If the config passed contains such a character
1553 substitution, the length will be calculated ignoring the possibility
1554 that one or more extra characters could be introduced depending on how
1555 many, if any, of the long substitutions get triggered by the randomly
1556 chosen words. If this happens the function will also carp with a
1557 warning. Such warnings can be suppressed by passing an optional named
1558 argument "suppress_warnings" with the value 1.
1559 config_to_json()
1561 my $config_json_string = Crypt::HSXKPasswd->config_to_json($config);
1563 This function returns a JSON representation of the passed config
1565 hashref as a scalar string.
1566 The function must be passed a valid config hashref or it will croak.
1568 config_to_string()
1570 my $config_string = Crypt::HSXKPasswd->config_to_string($config);
1572 This function returns the content of the passed config hashref as a
1574 scalar string. The function must be passed a valid config hashref or it
1575 will croak.
1576 default_config()
1578 my $config = Crypt::HSXKPasswd->default_config();
1580 This function returns a hashref containing a config with default
1582 values.
1583 This function can optionally be called with a single argument, a
1585 hashref containing keys with values to override the defaults with.
1586 my $config = Crypt::HSXKPasswd->default_config({num_words => 3});
1588 When overrides are present, the function will carp if an invalid key or
1590 value is passed, and croak if the resulting merged config is invalid.
1591 This function is a shortcut for "preset_config()", and the two examples
1593 above are equivalent to the following:
1594 my $config = Crypt::HSXKPasswd->preset_config('DEFAULT');
1596 my $config = Crypt::HSXKPasswd->preset_config('DEFAULT', {num_words => 3});
1597 defined_config_keys()
1599 my @config_key_names = Crypt::HSXKPasswd->defined_config_keys();
1601 This function returns the list of valid config key names as an array of
1603 strings.
1604 defined_presets()
1606 my @preset_names = Crypt::HSXKPasswd->defined_presets();
1608 This function returns the list of defined preset names as an array of
1610 strings.
1611 distil_to_config_keys()
1613 my $dist_hashref = Crypt::HSXKPasswd->distil_to_config_keys($hashref);
1615 This function takes a hashref as an argument, and returns a deep clone
1617 of that hashref containing only valid config keys with valid values.
1618 By default the function silently drops keys that are not valid config
1620 keys, but issues a warning when dropping a key that is a valid config
1621 key, but contains an invalid value. The function can also issue
1622 warnings when dropping keys that are not valid config keys.
1623 The warnings can be controlled with a pair of optional named arguments
1625 that can be added as a second argument:
1626 # suppress all warnings
1628 my $dist_hashref = Crypt::HSXKPasswd->distil_to_config_keys(
1629 $hashref,
1630 suppress_warnings => 1,
1631 );
1632 # emit warnings when dropping invalidly named keys
1634 my $dist_hashref = Crypt::HSXKPasswd->distil_to_config_keys(
1635 $hashref,
1636 warn_invalid_key_names => 1,
1637 );
1638 distil_to_symbol_alphabet()
1640 my @unique_syms = Crypt::HSXKPasswd->distil_to_symbol_alphabet($arrayref);
1642 my @unique_syms = Crypt::HSXKPasswd->distil_to_symbol_alphabet(
1643 $arrayref,
1644 warn => 1,
1645 );
1646 This function takes reference to an array of strings and returns a new
1648 array containing all the valid symbols from the referenced array. The
1649 valid symbols are de-duplicated before being returned.
1650 By default the function silently skips over strings that are not valid
1652 symbols. The function can be made issue warnings each time a string is
1653 skipped by passing a named argument "warn" with a value of 1 (0 can
1654 also be passed to explicitly disable warnings).
1655 distil_to_words()
1657 my @valid_unique_words = Crypt::HSXKPasswd->distil_to_words($arrayref);
1659 my @valid_unique_words = Crypt::HSXKPasswd->distil_to_words(
1660 $arrayref,
1661 warn => 1,
1662 );
1663 This function takes reference to an array of strings and returns a new
1665 array containing all the valid words from the referenced array. The
1666 valid words are de-duplicated before being returned.
1667 By default the function silently skips over strings that are not valid
1669 words. The function can be made issue warnings each time a string is
1670 skipped by passing a named argument "warn" with a value of 1 (0 can
1671 also be passed to explicitly disable warnings).
1672 is_valid_config()
1674 # determine the validity
1676 my $is_ok = Crypt::HSXKPasswd->is_valid_config($config);
1677 # assert the validity - will croak if the config is invalid
1679 Crypt::HSXKPasswd->is_valid_config($config, croak => 1);
1680 This function must be passed a hashref to test as the first argument.
1682 The function returns 1 if the passed config is valid, and 0 otherwise.
1683 Optionally, a named argument "croak" can also be passed to control
1685 whether or not the function should croak if the config is invalid. The
1686 value of this named argument should be 1 or 0.
1687 When calling the function with "croak" set to 1, the message thrown by
1689 croak will explain why the config is invalid.
1690 use English qw( -no_match_vars );
1692 eval{
1693 Crypt::HSXKPasswd->is_valid_config($config, croak => 1);
1694 }or do{
1695 print "ERROR - config is invalid because: $EVAL_ERROR\n";
1696 }
1697 module_config()
1699 my $debug_val = Crypt::HSXKPasswd->module_config('DEBUG'); # getter
1701 Crypt::HSXKPasswd->module_config('DEBUG', 1); # setter
1702 This function is used to access or alter the value of one of the module
1704 configuration settings. The first function must always be a valid
1705 module configuration key name. If no second argument is provided, the
1706 value stored in the module configuration key will not be updated. To
1707 update the stored value, pass a new value as a second argument.
1708 Regardless of whether or not a second argument is passed, the value
1709 stored in the module configuration key is always returned.
1710 The function will croak if called with an invalid module configuration
1712 key name, or passed an invalid new value.
1713 For a list of the module configuration keys, see the MODULE
1715 CONFIGURATION section of this document.
1716 preset_config()
1718 my $config = Crypt::HSXKPasswd->preset_config('XKCD');
1720 This function returns the config hashref for a given preset. See above
1722 for the list of available presets.
1723 The first argument this function accepts is the name of the desired
1725 preset as a scalar. If an invalid name is passed, the function will
1726 carp. If no preset is passed the preset "DEFAULT" is assumed.
1727 This function can optionally accept a second argument, a hashref
1729 containing keys with values to override the defaults with.
1730 my $config = Crypt::HSXKPasswd->preset_config(
1732 'XKCD',
1733 {case_transform => 'INVERT'}
1734 );
1735 When overrides are present, the function will carp if an invalid key or
1737 value is passed, and croak if the resulting merged config is invalid.
1738 preset_definition()
1740 my %preset_def = Crypt::HSXKPasswd->preset_definition('XKCD');
1742 This function returns a hash defining a preset. The hash contains an
1744 English description of the preset indexed be "description" and a config
1745 hashref indexed by "config".
1746 The function expects to be called with one argument, a valid preset
1748 name, but it can be called without arguments, in which case it will
1749 return the definition for the preset c<DEFAULT>.
1750 You can see all the defined presets in the PRESETS section of this
1752 document, and you can get a list of valid preset names programatically
1753 with the function "defined_presets()".
1754 preset_definitions()
1756 my %preset_defs = Crypt::HSXKPasswd->preset_definitions();
1758 This function returns a hash of all defined presets indexed by preset
1760 name. Each preset definition is a hash as returned by
1761 "preset_definition()".
1762 This function does not take any arguments.
1764 presets_json()
1766 my $json_string = Crypt::HSXKPasswd->presets_json();
1768 This function returns a JSON string representing all the defined
1770 configs, including their descriptions.
1771 The returned JSON string represents a hashref indexed by three keys:
1773 "defined_keys" contains an array of preset identifiers, "presets"
1774 contains the preset configs indexed by reset identifier, and
1775 "preset_descriptions" contains a hashref of descriptions indexed by
1776 preset identifiers.
1777 preset_description()
1779 my $description = Crypt::HSXKPasswd->preset_description('XKCD');
1781 This function returns the description for a given preset. See above for
1783 the list of available presets.
1784 The first argument this function accepts is the name of the desired
1786 preset as a scalar. If an invalid name is passed, the function will
1787 carp. If no preset is passed the preset "DEFAULT" is assumed.
1788 presets_to_string()
1790 print Crypt::HSXKPasswd->presets_to_string();
1792 This function returns a string containing a description of each defined
1794 preset and the configs associated with the presets.
1795 COMMANDLINE INTERFACE
1797 The module ships with a commandline interface to this library, simply
1798 called "hsxkpasswd".
1799 This interface allows for the generation of multiple passwords at a
1801 time, the use of presets and preset overrides, the use of custom
1802 password generator configurations, the use of custom word sources, and
1803 the use of custom random number generators.
1804 Both preset overrides and password generator configurations must be
1806 specified in JSON format.
1807 Examples
1809 Generate a single password using all the default settings:
1811 hsxkpasswd
1813 Generate five passwords using the default settings:
1815 hsxkpasswd 5
1817 Generate five passwords using the "XKCD" preset:
1819 hsxkpasswd -p XKCD 5
1821 Generate five passwords using the "XKCD" preset with an overridden
1823 password generator configuration key:
1824 hsxkpasswd -p XKCD -o '{"separator_character" : "*"}' 5
1826 Generate five passwords using a custom password generator configuration
1828 stored in a text file in JSON format:
1829 hsxkpasswd -c my_config.json
1831 Further Reading
1833 The examples above are just a sample of what the command can do, for
1835 complete documentation, run the command with the -h flag:
1836 hsxkpasswd -h
1838 If you are new to JSON, you may find the following links useful:
1840 • JSON on Wikipedia - <http://en.wikipedia.org/wiki/JSON>
1842 • A free online JSON validator -
1844 <http://jsonformatter.curiousconcept.com>
1845 • A JSON tutorial from W3Schools - <http://www.w3schools.com/json/>
1847 ENTROPY CHECKING
1849 For security reasons, this module's default behaviour is to warn (using
1850 "carp()") when ever the loaded combination of word source and
1851 configuration would result in low-entropy passwords. When the
1852 constructor is invoked, or when an instance's the word source or config
1853 are altered (using "dictionary()" or "config()"), the entropy is re-
1854 calculated and re-checked against the defined minima.
1855 Entropy is calculated and checked for two scenarios. Firstly, for the
1857 best-case scenario, when an attacker has no prior knowledge about the
1858 password, and must resort to a brute-force attack. And secondly, for
1859 the worst-case scenario, when the attacker is assumed to know that this
1860 module was used to generate the password, and, that the attacker has a
1861 copy of the word source and config settings used to generate the
1862 password.
1863 Entropy checking is controlled via three module configuration variables
1865 (which can be accessed and updated using the function
1866 "module_config()"):
1867 • "ENTROPY_MIN_BLIND" - the minimum acceptable entropy in bits for a
1869 brute-force attack. The default value is 78bits, the equivalent to
1870 a 12 character password consisting of mixed-case letters, digits,
1871 and symbols.
1872 • "ENTROPY_MIN_SEEN" - the minimum acceptable entropy in bits for a
1874 worst-case scenario (where the word source and config are known).
1875 The default value is 52bits, equivalent to an 8 character password
1876 consisting of mixed-case letters, digits, and symbols.
1877 • "ENTROPY_WARNINGS" - this variable can be used to control the
1879 emission of entropy warnings. The following values are valid:
1880 • "ALL" - all entropy warnings are emitted. This is the default
1882 value.
1883 • "BLIND" - only warnings for the best-case scenario are emitted.
1885 I.e. warnings for the worst-case scenario (attacker has full
1886 knowledge) are suppressed.
1887 • "NONE" - all entropy warnings are suppressed.
1889 Caveats
1891 The entropy calculations make some assumptions which may in some cases
1893 lead to the results being inaccurate. In general, an attempt has been
1894 made to always round down, meaning that in reality the entropy of the
1895 produced passwords may be higher than the values calculated by the
1896 package.
1897 When calculating the entropy for brute force attacks on configurations
1899 that can result in variable length passwords, the shortest possible
1900 password is assumed.
1901 When calculating the entropy for brute force attacks on configurations
1903 that contain at least one symbol, it is assumed that an attacker would
1904 have to brute-force-check 33 symbols. This is the same value used by
1905 Steve Gibson's Password Haystacks calculator
1906 (<https://www.grc.com/haystack.htm>).
1907 When calculating the entropy for worst-case attacks on configurations
1909 that contain symbol substitutions where the replacement is more than 1
1910 character long the possible extra length is ignored.
1911 WORD SOURCES (DICTIONARIES)
1913 The abstract class "Crypt::HSXKPasswd::Dictionary" acts as a base class
1914 for sources of words for use by this module. Word sources should extend
1915 this base class and implement the function "word_list()", which should
1916 return an array of words.
1917 In order to produce secure passwords it's important to use a word
1919 source that contains a large selection of words with a good mix of
1920 different lengths of words.
1921 The module ships with a number of pre-defined word sources:
1923 "Crypt::HSXKPasswd::Dictionary::DE"
1925 A German word list based on the GPL-licensed German dictionary for
1927 WinEdit by Juergen Vierheilig.
1928 Note: This module is licensed under the GPL, not the BSD license used
1930 for the majority of this project.
1931 "Crypt::HSXKPasswd::Dictionary::EN"
1933 A default word list consisting of English words and place names.
1935 "Crypt::HSXKPasswd::Dictionary::ES"
1937 A Spanish word list based on the BSD-licensed Spanish dictionary for
1939 WinEdit by Juan L. Varona from the Universidad de La Rioja.
1940 "Crypt::HSXKPasswd::Dictionary::FR"
1942 A French word list based on the GPL-licensed French dictionary for
1944 WinEdit.
1945 Note: This module is licensed under GPL V2, not the BSD license used
1947 for the majority of this project.
1948 "Crypt::HSXKPasswd::Dictionary::IT"
1950 An Italian word list based on the free-for-non-commerical-use Italian
1952 dictionary for WinEdit by Karl Koeller.
1953 Note: This module is licensed under GPL V2, not the BSD license used
1955 for the majority of this project.
1956 "Crypt::HSXKPasswd::Dictionary::NL"
1958 A Dutch/Flemish word list based on the GPL-licensed Dutch dictionary
1960 for WinEdit.
1961 Note: This module is licensed under GPL V2, not the BSD license used
1963 for the majority of this project.
1964 "Crypt::HSXKPasswd::Dictionary::PT"
1966 A Portuguese word list based on the GPL-licensed Portuguese dictionary
1968 for WinEdit compiled by Bernhard Enders (building on work by Raimundo
1969 Santos Moura & Ricardo Ueda Karpischek).
1970 Note: This module is licensed under GPL V2.1, not the BSD license used
1972 for the majority of this project.
1973 "Crypt::HSXKPasswd::Dictionary::System"
1975 This class tries to find and use a Unix words file on the system.
1977 The constructor croaks if no system words file can be found.
1979 Usage
1981 my $word_source = Crypt::HSXKPasswd::Dictionary::System->new();
1983 "Crypt::HSXKPasswd::Dictionary::Basic"
1985 This class can be initialised from a words file, or from an array ref
1987 containing words.
1988 Usage
1990 my $word_source = Crypt::HSXKPasswd::Dictionary::Basic->new('file_path');
1992 my $word_source = Crypt::HSXKPasswd::Dictionary::Basic->new(
1993 'file_path',
1994 'Latin1'
1995 );
1996 my $word_source = Crypt::HSXKPasswd::Dictionary::Basic->new($array_ref);
1997 The rules for the formatting of dictionary files are simple. Dictionary
1999 files must contain one word per line. Words shorter than four letters
2000 will be ignored, as will all lines starting with the # symbol. Files
2001 are assumed to be UTF-8 encoded, but an optional second argument can be
2002 passed specifying a different file encoding.
2003 This format is the same as that of the standard Unix Words file,
2005 usually found at "/usr/share/dict/words" on Unix and Linux operating
2006 systems (including OS X).
2007 RANDOM NUMBER SOURCES
2009 In order to minimise the number of non-standard modules this module
2010 requires, the default source of randomness is Perl's built-in "rand()"
2011 function. This provides a reasonable level of randomness, and should
2012 suffice for most users, however, some users will prefer to make use of
2013 one of the many advanced randomisation modules in CPAN, or, reach out
2014 to a web service like <http://random.org> for their random numbers. To
2015 facilitate both of these options, this module uses a cache of
2016 randomness, and provides an abstract Random Number Generator (RNG)
2017 class that can be extended.
2018 The module can use an instance of any class that extends
2020 "Crypt::HSXKPasswd::RNG" as it's source of randomness. Custom RNG
2021 classes must implement the method "random_numbers()" which will be
2022 invoked on an instance of the class and passed one argument, the number
2023 of random numbers required to generate a single password. The function
2024 must return an array of random numbers between 0 and 1. The number of
2025 random numbers returned is entirely up to the module to decide. The
2026 number required for a single password is passed purely as a guide. The
2027 function must always return at least one random number.
2028 The module ships with five standard RNGs (described below).
2030 By default, the module will try to use one of the following four RNGs,
2032 listed from most to least preferred, depending on what is available on
2033 the system:
2034 1. "Crypt::HSXKPasswd::RNG::Math_Random_Secure" (only available if
2036 "Math::Random::Secure" is installed on the system).
2037 2. "Crypt::HSXKPasswd::RNG::Data_Entropy" (only available if
2039 "Data::Entropy::Algorithms" is installed on the system).
2040 3. "Crypt::HSXKPasswd::RNG::DevUrandom" (only available on Linux/Unix
2042 systems with a "/dev/urandom").
2043 4. "Crypt::HSXKPasswd::RNG::Basic" (available on all systems because
2045 it uses Perl's built-in "rand()" function).
2046 If the constructor is called without specifying an RNG, and if the only
2048 available RNG is "Crypt::HSXKPasswd::RNG::Basic", a warning will be
2049 thrown suggesting installing "Math::Random::Secure" or
2050 "Data::Entropy::Algorithms".
2051 The module also ships with a fifth RNG,
2053 "Crypt::HSXKPasswd::RNG::RandomDotOrg", but this one must be explicitly
2054 used, the constructor will never used it by default. As its name
2055 suggests, this class uses <http://Random.Org/>'s HTTP API to generate
2056 random numbers.
2057 To explicitly use any particular RNG, create an instance of it, and
2059 either pass that instance to the constructor with the named argument
2060 "rng", or, set the RNG after instantiating the object using the "rng()"
2061 function.
2062 Crypt::HSXKPasswd::RNG::Math_Random_Secure
2064 my $rng = Crypt::HSXKPasswd::RNG::Math_Random_Secure->new();
2066 This is the preferred RNG because it is both fast and secure, but, it
2068 requires the non-standard module "Math::Random::Secure"
2069 (<http://search.cpan.org/perldoc?Math%3A%3ARandom%3A%3ASecure>) be
2070 installed.
2071 Crypt::HSXKPasswd::RNG::Data_Entropy
2073 my $rng = Crypt::HSXKPasswd::RNG::Data_Entropy->new();
2075 This RNG is secure, but it is quite slow (about six times slower than
2077 "Crypt::HSXKPasswd::RNG::Math_Random_Secure"), and it requires the non-
2078 standard module "Data::Entropy::Algorithms"
2079 (<http://search.cpan.org/perldoc?Data%3A%3AEntropy%3A%3AAlgorithms>) be
2080 installed.
2081 Crypt::HSXKPasswd::RNG::DevUrandom
2083 my $rng = Crypt::HSXKPasswd::RNG::DevUrandom->new();
2085 This RNG is secure and relatively fast (faster than
2087 "Crypt::HSXKPasswd::RNG::Data_Entropy" but slower than
2088 "Crypt::HSXKPasswd::RNG::Math_Random_Secure"), but is only available on
2089 Linux/Unix systems with a "/dev/urandom" special file.
2090 Crypt::HSXKPasswd::RNG::Basic
2092 my $rng = Crypt::HSXKPasswd::RNG::Basic->new();
2094 This RNG uses Perl's built-in "rand()" function as its source of
2096 randomness, and this is sub-optimal. The Perl docs warn that "rand()"
2097 is not a particularly good source of random numbers, and advises
2098 against its use for cryptography.
2099 This RNG provides a base-line, and should only be used if none of the
2101 better RNGs are available. While it is sub-optimal, it will still
2102 generate passwords with sufficient entropy in most situations.
2103 Ultimately, even using this imperfect RNG, this module will still
2104 produce passwords that are much better than those produced by the human
2105 imagination!
2106 Crypt::HSXKPasswd::RNG::RandomDotOrg
2108 my $rng = Crypt::HSXKPasswd::RNG::RandomDotOrg->new('my.address@my.dom');
2110 my $rng = Crypt::HSXKPasswd::RNG::RandomDotOrg->new('my.address@my.dom',
2111 timeout => 180,
2112 num_passwords => 3,
2113 );
2114 This RNG serves as a usable example of an RNG that queries a web
2116 service. As its name suggests, this class uses <http://Random.Org/>'s
2117 HTTP API to generate random numbers.
2118 In order to comply with Random.Org's client guidelines
2120 (<https://www.random.org/clients/>), this module requires that a valid
2121 email address be passed as the first argument.
2122 The client guidelines also request that clients use long timeouts, and
2124 batch their requests. They prefer to be asked for more number less
2125 frequently than less numbers more frequently. For this reason the
2126 class's default behaviour is to use a timeout of 180 seconds, and to
2127 request enough random numbers to generate three passwords at a time.
2128 These defaults can be overridden by passing named arguments to the
2130 constructor after the email address. The following named arguments are
2131 supported:
2132 • "timeout" - the timeout to use when making HTTP requests to
2134 Random.Org in seconds (the default is 180).
2135 • "num_passwords" - the number of password generations to fetch
2137 random numbers for per request from Random.org. This value is in
2138 effect a multiplier for the value passed to the "random_numbers()"
2139 function by "Crypt::HSXKPasswd".
2140 "num_absolute" - the absolute number of random numbers to fetch per
2142 request to Random.Org. This argument takes precedence over
2143 "num_passwords".
2144 "num_passwords" and "num_absolute" should not be used together, but if
2146 they are, "num_absolute" use used, and "num_passwords" is ignored.
2147 This class requires a number of modules not used by any other classes
2149 under "Crypt::HSXKPasswd", and not listed in that module's
2150 requirements. If all of the following modules are not installed, the
2151 constructor will croak:
2152 • "Email::Valid"
2154 • "LWP::UserAgent"
2156 • "Mozilla::CA"
2158 • "URI"
2160
2162 By default this module does all of it's error notification via the
2163 functions "carp()", "croak()", and "confess()" from the "Carp" module.
2164 Optionally, all error messages can also be printed to a stream. To
2165 enable the printing of messages, set the "LOG_ERRORS" module
2166 configuration variable to 1. All error messages will then be printed to
2167 the stream defined by the module configuration variable "LOG_STREAM",
2168 which is set to "STDERR" by default.
2169 Ordinarily this module produces very little output. To enable more
2171 verbose output the module configuration variable "DEBUG" can be set to
2172 1. Debug message are printed to the stream specified by the module
2173 variable "LOG_STREAM".
2174 This module produces output at three severity levels:
2176 • "DEBUG" - this output is completely suppressed unless the module
2178 configuration variable "DEBUG" is set to 1. All debug messages are
2179 printed to the stream defined in the module configuration variable
2180 "LOG_STREAM" (regardless of the the value of the module
2181 configuration variable "LOG_ERRORS").
2182 • "WARNING" - warning messages are always thrown with "carp()", and
2184 also printed to the stream specified by the module configuration
2185 variable "LOG_STREAM" if the module configuration variable
2186 "LOG_ERRORS" is set to 1.
2187 • "ERROR" - error messages are usually thrown with "croak()", but
2189 will be thrown with "confess()" if the module configuration
2190 variable "DEBUG" is set to 1. If the module configuration variable
2191 "LOG_ERRORS" is set to 1 errors are also printed to the stream
2192 defined by the module configuration variable "LOG_STREAM",
2193 including a stack trace if the module configuration variable
2194 "DEBUG" is set to 1 and the module "Devel::StackTrace" is
2195 installed.
2196 The value stored in a module configuration variable can be accessed and
2198 updated using the function "module_config()".
2199
2201 This module does not currently support configuration files, nor does it
2202 currently interact with the environment. It may do so in future
2203 versions.
2204
2206 This module requires the following Perl modules:
2207 • "Carp" - <http://search.cpan.org/perldoc?Carp>
2209 • "Clone" - <http://search.cpan.org/perldoc?Clone>
2211 • "DateTime" - <http://search.cpan.org/perldoc?DateTime>
2213 • "English" - <http://search.cpan.org/perldoc?English>
2215 • "Fatal" - <http://search.cpan.org/perldoc?Fatal>
2217 • "File::HomeDir" -
2219 <http://search.cpan.org/perldoc?File%3A%3AHomeDir>
2220 • "Getopt::Long" - <http://search.cpan.org/perldoc?Getopt%3A%3ALong>
2222 • "JSON" - <http://search.cpan.org/perldoc?JSON>
2224 • "List::MoreUtils" -
2226 <http://search.cpan.org/perldoc?List%3A%3AMoreUtils>
2227 • "Math::BigInt" - <http://search.cpan.org/perldoc?Math%3A%3ABigInt>
2229 • "Math::Round" - <http://search.cpan.org/perldoc?Math%3A%3ARound>
2231 • "Module::Load" - <http://search.cpan.org/perldoc?Module%3A%3ALoad>
2233 • "Pod::Usage" - <http://search.cpan.org/perldoc?Pod%3A%3AUsage>
2235 • "Readonly" - <http://search.cpan.org/perldoc?Readonly>
2237 • "Scalar::Util" - <http://search.cpan.org/perldoc?Scalar%3A%3AUtil>
2239 • "strict" - <http://search.cpan.org/perldoc?strict>
2241 • "Text::Unidecode" -
2243 <http://search.cpan.org/perldoc?Text%3A%3AUnidecode>
2244 • "Type::Library" -
2246 <http://search.cpan.org/perldoc?Type%3A%3ALibrary>
2247 • "Type::Params" - <http://search.cpan.org/perldoc?Type%3A%3AParams>
2249 • "Type::Tiny" - <http://search.cpan.org/perldoc?Type%3A%3ATiny>
2251 • "Types::Standard" -
2253 <http://search.cpan.org/perldoc?Types%3A%3AStandard>
2254 • "warnings" - <http://search.cpan.org/perldoc?warnings>
2256 The module can also optionally use the following Perl modules:
2258 • "Data::Entropy::Algorithms" -
2260 <http://search.cpan.org/perldoc?Data%3A%3AEntropy%3A%3AAlgorithms>
2261 Used by the RNG class "Crypt::HSXKPasswd::RNG::Data_Entropy".
2263 • "Devel::StackTrace" -
2265 <http://search.cpan.org/perldoc?Devel%3A%3AStackTrace>
2266 Used for printing stack traces with error messages if
2268 $XKPasswd::DEBUG and $XKPasswd::LOG_ERRORS both evaluate to true.
2269 If the module is not installed the stack traces will be omitted
2270 from the log messages.
2271 • "Email::Valid" - <http://search.cpan.org/perldoc?Email%3A%3AValid>
2273 Used by the Random.Org RNG class
2275 "Crypt::HSXKPasswd::RNG::RandomDotOrg".
2276 • "LWP::UserAgent" -
2278 <http://search.cpan.org/perldoc?LWP%3A%3AUserAgent>
2279 Used by the Random.Org RNG class
2281 "Crypt::HSXKPasswd::RNG::RandomDotOrg".
2282 • "Math::Random::Secure" -
2284 <http://search.cpan.org/perldoc?Math%3A%3ARandom%3A%3ASecure>
2285 Used by the RNG class "Crypt::HSXKPasswd::RNG::Math_Random_Secure".
2287 • "Mozilla::CA" - <http://search.cpan.org/perldoc?Mozilla%3A%3ACA>
2289 Indirectly required by the Random.Org RNG class
2291 "Crypt::HSXKPasswd::RNG::RandomDotOrg" because without it
2292 "LWP::UserAgent" can't use HTTPS, and the Random.Org API uses
2293 HTTPS.
2294 • "URI" - <http://search.cpan.org/perldoc?URI>
2296 Used by the Random.Org RNG class
2298 "Crypt::HSXKPasswd::RNG::RandomDotOrg".
2299
2301 This module has no known incompatibilities.
2302
2304 There are no known bugs in this module.
2305 Please report any bugs you may find on the module's GitHub page:
2307 <https://github.com/bbusschots/xkpasswd.pm>.
2308
2310 Copyright (c) 2014-15, Bart Busschots T/A Bartificer Web Solutions All
2311 rights reserved.
2312 Redistribution and use in source and binary forms, with or without
2314 modification, are permitted provided that the following conditions are
2315 met:
2316 1. Redistributions of source code must retain the above copyright
2318 notice, this list of conditions and the following disclaimer.
2319 2. Redistributions in binary form must reproduce the above copyright
2321 notice, this list of conditions and the following disclaimer in the
2322 documentation and/or other materials provided with the
2323 distribution.
2324 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
2326 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
2327 TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
2328 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
2329 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
2330 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
2331 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
2332 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
2333 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
2334 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
2335 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
2336 The following components of this package are covered by the more
2338 restrictive GPL V2 license <https://www.gnu.org/licenses/gpl-2.0.html>:
2339 • The "share/sample_dict_DE.txt" text file.
2341 • The "Crypt::HSXKPasswd::Dictionary::DE" Perl module.
2343 • The "share/sample_dict_FR.txt" text file.
2345 • The "Crypt::HSXKPasswd::Dictionary::FR" Perl module.
2347 • The "share/sample_dict_IT.txt" text file.
2349 • The "Crypt::HSXKPasswd::Dictionary::IT" Perl module.
2351 • The "share/sample_dict_NL.txt" text file.
2353 • The "Crypt::HSXKPasswd::Dictionary::NL" Perl module.
2355 • The "share/sample_dict_PT.txt" text file.
2357 • The "Crypt::HSXKPasswd::Dictionary::PT" Perl module.
2359
2361 Bart Busschots (<mailto:bart@bartificer.net>)
2362perl v5.36.0 2023-01-06 Crypt::HSXKPasswd(3)