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

NAME

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

VERSION

11       This documentation refers to "Crypt::HSXKPasswd" version 3.6.
12

SYNOPSIS

14           use Crypt::HSXKPasswd;
15
16           #
17           # Functional Interface - a shortcut for generating single passwords
18           #
19
20           # generate a single password using the default word source, configuration,
21           # and random number generator
22           my $password = hsxkpasswd();
23
24           # the above call is simply a shortcut for the following
25           my $password = Crypt::HSXKPasswd->new()->password();
26
27           # 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
32           #
33           # Object Oriented Interface - recommended for generating multiple passwords
34           #
35
36           # create a new instance with the default dictionary, config, and random
37           # number generator
38           my $hsxkpasswd_instance = Crypt::HSXKPasswd->new();
39
40           # generate a single password
41           my $password = $hsxkpasswd_instance->password();
42
43           # generate multiple passwords
44           my @passwords = $hsxkpasswd_instance->passwords(10);
45

DESCRIPTION

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
52   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
61       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
70       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
78       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
83       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
89       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
94       In shot, this module is for people who prefer passwords that look like
95       this:
96
97           !15.play.MAJOR.fresh.FLAT.23!
98
99       to passwords that look like this:
100
101           eB8.GJXa@TuM
102
103   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
108       It's important to understand the algorithm before trying to create your
109       own custom configurations for this module.
110
111       The algorithm is broken in to the following steps:
112
113       1.  Pick random words from the dictionary.
114
115       2.  Apply transformations to the words.
116
117       3.  Create pseudo-words made up for randomly chosen digits and add them
118           as the first and last words.
119
120       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
124       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
127       You can visualise this process as follows:
128
129           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
135       Each of these steps can be customised in the following ways:
136
137       1.  The number of words to be used, and the minimum and maximum lengths
138           of the words can be configured.
139
140       2.  The case of the words can be modified in a number of ways,
141           including randomly choosing the case for each word.
142
143           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
148       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
153       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
157       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
162           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
166           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
170   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
175       Maths Primer
176
177       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
182       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
189       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
193           P = 2^L
194
195       Or, two to the power of the length of the password.
196
197       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
202       This means that for a dice, the number of permutations can be
203       calculated with the formula:
204
205           P = 6^L
206
207       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
214       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
218           P = A^L
219
220       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
231       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
238       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
243           E = Log(2)P
244
245       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
248       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
252       The Entropy of HSXKPasswd Passwords
253
254       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
258       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
263       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
272       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
276       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
280       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
285           Eb = Log(2)(A^L)
286
287       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
294       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
299       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
312           Eb = Log(2)(95^27) = 163 bits
313
314       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
319       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
323       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
327       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
332       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
337       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
341       Similarly, the padding character on the end is chosen from 13 permitted
342       symbols giving 13 more permutations.
343
344       Finally, there are four randomly chosen digits, giving "10^4", or
345       10,000 permutations.
346
347       The total number of permutations is the product of all these
348       permutations:
349
350           Pseen = 3,797,883,801,856 * 9 * 13 * 10,000 = 2.77x10^17
351
352       Finally, we convert this to entropy by taking the base 2 log:
353
354           Eseen = Log(2)2.77x10^17 = ~57bits
355
356       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
363       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

SUBROUTINES/METHODS

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
376           # get the current debug status
377           my $debug_status = Crypt::HSXKPasswd->module_config('DEBUG');
378
379           # configure the module to suppress all entropy warnings
380           Crypt::HSXKPasswd->module_config('ENTROPY_WARNINGS', 'NONE');
381
382       The following module configuration keys exist within the module:
383
384       •   "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
388           For more details see the DIAGNOSTICS section of this document.
389
390       •   "LOG_ERRORS" - A True/False value denoting whether or not errors
391           should be logged. The default is not to log.
392
393           For more details see the DIAGNOSTICS section of this document.
394
395       •   "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
399           For more details see the DIAGNOSTICS section of this document.
400
401       •   "ENTROPY_MIN_BLIND" - the minimum allowable entropy against brute
402           force attacks in bits. The default is 78 bits.
403
404           For more details see the ENTROPY CHECKING section of this document.
405
406       •   "ENTROPY_MIN_SEEN" - the minimum allowable entropy against an
407           attacker with full knowledge. The default is 52 bits.
408
409           For more details see the ENTROPY CHECKING section of this document.
410
411       •   "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
415           For more details see the ENTROPY CHECKING section of this document.
416
417   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
427       Defined Types
428
429       •   "NonEmptyString" - a string containing at least one character.
430
431       •   "PositiveInteger" - a whole number greater than or equal to zero.
432
433       •   "NonZeroPositiveInteger" - a whole number greater than zero.
434
435       •   "TrueFalse" - a reasonable boolean value, specifically, "undef",
436           and empty string, or 0 to indicate false, and a 1 to indicate true.
437
438       •   "PerlPackageName" - string representing a valid Perl package name
439           like "Crypt::HSXKPasswd::Dictionary::NL".
440
441       •   "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
447       •   "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
456       •   "Word" - a string containing only letters (as defined by the type
457           "Letter"), and at least four long.
458
459       •   "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
463       •   "WordLength" - a valid value when specifying the length of a word,
464           specifically, a whole number greater than or equal to four.
465
466       •   "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
471       •   "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
477       •   "ConfigKeyAssignment" - a mapping between a valid configuration key
478           name and a valid value for that configuration key.
479
480       •   "ConfigOverride" - a reference to hash containing one or more
481           configuration key assignments as defined by the type
482           "ConfigKeyAssignment".
483
484       •   "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
493           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
497       •   "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
501       •   "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
506       Using the Custom Types
507
508       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
512       Useful Links:
513
514       •   The documentation for "Type::Tiny" -
515           <http://search.cpan.org/perldoc?Type%3A%3ATiny>
516
517       •   The documentation for "Type::Library" -
518           <http://search.cpan.org/perldoc?Type%3A%3ALibrary>
519
520       To use the bare type definitions listed above, import the module as
521       follows:
522
523           use Crypt::HSXKPasswd::Types qw( :types );
524
525       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
530           $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
536       "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
541           use Crypt::HSXKPasswd::Types qw( :types :is );
542
543       You can now do things like the following:
544
545           $is_valid = is_Letter('e'); # $is_valid = 1
546           $is_valid = is_Letter('-'); # $is_valid = undef
547
548       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
554           print Letter->my_english(); # prints: a string containing exactly one letter
555
556       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
560       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
567   CONFIGURATION
568       The module builds passwords using the following process.
569
570       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
576       You can envisage the process as follows:
577
578           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
583       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
592       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
597       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
601       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
607       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
611       For more details on how to specify configurations, see the
612       documentation for the constructor (the function "new()") below.
613
614       Password Generator Configuration Keys
615
616       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
621       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
626       •   "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
631       •   "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
635           •   "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
639           •   "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
643           •   "INVERT" - the first letter in every word will be converted to
644               lower case, all other letters will be converted to upper case.
645
646           •   "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
650           •   "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
654           •   "RANDOM" - each word will be randomly converted to all upper
655               case or all lower case.
656
657           •   "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
661           The function "default_config()" returns a value of "CAPITALISE" for
662           this key.
663
664       •   "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
673       •   "num_words" (required) - the number of words to randomly choose
674           from the word source as the basis for the generated passwords.
675
676           The function "default_config()" returns a value of 3 for this key.
677
678       •   "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
684       •   "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
689           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
697           If specified, this key must be a reference to an array of single-
698           character strings.
699
700       •   "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
704           If specified, they key's value must be a single character string,
705           or one of the following special values:
706
707           •   "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
715           •   "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
720           The function "default_config" return the value "RANDOM" for this
721           key.
722
723       •   "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
727           These keys specify the number of padding symbols that should be
728           added to the front and back of the password.
729
730           Both keys require that the specified value be an integer greater
731           than or equal to zero.
732
733           The function "default_config()" returns a value of 2 for both of
734           these keys.
735
736       •   "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
740           Both keys require that the specified value be an integer greater
741           than or equal to zero.
742
743           The function "default_config()" returns a value of 2 for both of
744           these keys.
745
746       •   "padding_type" (required) - the way in which padding symbols should
747           be added when generating passwords.
748
749           Only the following values are valid for this key:
750
751           •   "NONE" - do not add any padding symbols when generating
752               passwords.
753
754           •   "FIXED" - add an exactly specified number of copies of the
755               padding symbol to the front and back of generated passwords.
756
757               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
761           •   "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
767               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
772               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
776           The function "default_config()" returns a value of "FIXED" for this
777           key.
778
779       •   "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
784           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
792           If specified, this key must be a reference to an array of single-
793           character strings.
794
795       •   "separator_character" (required) - the symbol to use to separate
796           the words when generating passwords.
797
798           The value specified for this key must be a single-character string,
799           or one of the following special values:
800
801           •   "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
805               "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
810           The function "default_config()" returns a value of "RANDOM" for
811           this key.
812
813       •   "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
819           Note that the keys "separator_alphabet" and "padding_alphabet" take
820           precedence over this key if specified.
821
822           The value specified for this key must be a reference to an array of
823           single-character strings.
824
825           The function "default_config()" returns a value of "['!', '@', '$',
826           '%', '^', '&', '*', '-', '_', '+', '=', ':', '|', '~', '?', '/',
827           '.', ';']" for this key.
828
829       •   "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
833           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
837           The function "default_config()" returns values of 4 and 8 for these
838           keys.
839
840   PRESETS
841       Below is a list of all the presets defined by this module.
842
843       This information can be accessed programatically using the functions
844       "defined_presets()", "presets_to_string()", "preset_description()", and
845       "preset_config()".
846
847       •   "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
857           Sample Password:
858
859               -25,favor,MANY,BEAR,53-
860
861           Preset Definition:
862
863               {
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
880       •   "DEFAULT" - the default configuration.
881
882           Sample Password:
883
884               ~~12:settle:SUCCEED:summer:48~~
885
886           Preset Definition:
887
888               {
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
904       •   "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
910           Sample Password:
911
912               0=mAYAN=sCART@
913
914           Preset Definition:
915
916               {
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
933       •   "SECURITYQ" - a preset for creating fake answers to security
934           questions. This preset generates long nonsense sentences ending in
935           "." "!" or "?".
936
937           Sample 'Password':
938
939               Wales outside full month minutes gentle?
940
941           Preset Definition:
942
943               {
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
959       •   "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
966           Sample Password:
967
968               tube+NICE+iron+02
969
970           Preset Definition:
971
972               {
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
985       •   "WEB32" - a preset for websites that don't allow passwords to be
986           longer than 32 characters.
987
988           Sample Password:
989
990               +93-took-CASE-money-AHEAD-31+
991
992           Preset Definition:
993
994               {
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
1011       •   "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
1015           Sample Password:
1016
1017               2736_ITSELF_PARTIAL_QUICKLY_SCOTLAND_wild_people_7441!!!!!!!!!!
1018
1019           Preset Definition:
1020
1021               {
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
1037       •   "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
1041           Sample Password:
1042
1043               quiet-children-OCTOBER-today-HOPE
1044
1045           Preset Definition:
1046
1047               {
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
1059   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
1067       There is only a single function exported by the module:
1068
1069       hsxkpasswd()
1070
1071           my $password = hsxkpasswd();
1072
1073       This function call is equivalent to the following Object-Oriented code:
1074
1075           my $password =  Crypt::HSXKPasswd->new()->password();
1076
1077       This function passes all arguments it receives through to the
1078       constructor, so all arguments that are valid in "new()" are valid here.
1079
1080       This function Croaks if there is a problem generating the password.
1081
1082       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
1086   CONSTRUCTOR
1087           # create a new instance with the default dictionary, config, and random
1088           # number generator
1089           my $hsxkpasswd_instance = Crypt::HSXKPasswd->new();
1090
1091           # the constructor takes optional named arguments, these can be used to
1092           # customise the word source, config, and random number source.
1093
1094           # 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
1099           # create an instance that uses an array reference as the word source
1100           my $hsxkpasswd_instance = Crypt::HSXKPasswd->new(dictionary_list => $array_ref);
1101
1102           # 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
1107           # 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
1115           # create an instance from the preset 'XKCD'
1116           my $hsxkpasswd_instance = Crypt::HSXKPasswd->new(preset => 'XKCD');
1117
1118           # 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
1124           # 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
1135           # 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
1153           # 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
1170           # 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
1176           # 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
1187       The constructor must be called via the package name.
1188
1189       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
1194       The function accepts named arguments to allow for custom specification
1195       of the word source, config, and random number source.
1196
1197       Specifying Custom Word Sources
1198
1199       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
1204       •   "dictionary" - an instance of a class that extends
1205           "Crypt::HSXKPasswd::Dictionary".
1206
1207       •   "dictionary_list" - a reference to an array containing words as
1208           scalars.
1209
1210       •   "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
1216       Specifying Custom Password Generator Configurations
1217
1218       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
1224       •   "config" - a valid config hashref.
1225
1226       •   "config_json" - a JSON string representing a valid config hashref.
1227
1228           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
1233       •   "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
1237       Specifying Custom Random Number Generators
1238
1239       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
1243   INSTANCE METHODS
1244       NOTE - all instance methods must be invoked on a Crypt::HSXKPasswd
1245       object or they will croak.
1246
1247       ->config()
1248
1249           my $config = $hsxkpasswd_instance->config(); # getter
1250           $hsxkpasswd_instance->config($config_hashref); # setter
1251           $hsxkpasswd_instance->config($config_json_string); # setter
1252
1253       When called with no arguments the function returns a clone of the
1254       instance's config hashref.
1255
1256       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
1261       The function will croak if an invalid config is passed.
1262
1263       ->config_as_json()
1264
1265           my $config_json_string = $hsxkpasswd_instance->config_as_json();
1266
1267       This function returns the content of the instance's loaded config
1268       hashref as a JSON string.
1269
1270       The output from this function can be loaded into the web interface at
1271       <https://xkpasswd.net> (using the load/save tab).
1272
1273       ->config_as_string()
1274
1275           my $config_string = $hsxkpasswd_instance->config_as_string();
1276
1277       This function returns the content of the instance's loaded config
1278       hashref as a scalar string.
1279
1280       ->dictionary()
1281
1282           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
1288       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
1292       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
1302       ->password()
1303
1304           my $password = $hsxkpasswd_instance->password();
1305
1306       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
1310       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
1315       ->passwords()
1316
1317           my @passwords = $hsxkpasswd_instance->passwords(10);
1318
1319       This function generates a number of passwords and returns them all as
1320       an array.
1321
1322       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
1326       ->passwords_json()
1327
1328           my $json_string = $hsxkpasswd_instance->passwords_json(10);
1329
1330       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
1339       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
1343       ->rng()
1344
1345           my $rng_instance = $hsxkpasswd_instance->rng();
1346           $hsxkpasswd_instance->rng($rng_instance);
1347
1348       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
1352       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
1355       ->stats()
1356
1357           my %stats = $hsxkpasswd_instance->stats();
1358
1359       This function generates a hash containing stats about the instance
1360       indexed by the following keys:
1361
1362       •   "dictionary_contains_accents" - 1 if the filtered word list
1363           contains accented letters, 0 otherwise.
1364
1365       •   "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
1370       •   "dictionary_source" - the source of the word list loaded into the
1371           instance.
1372
1373       •   "dictionary_words_filtered" - the number of words loaded from the
1374           dictionary file that meet the criteria defined by the loaded
1375           config.
1376
1377       •   "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
1381       •   "dictionary_words_total" - the total number of words loaded from
1382           the dictionary file.
1383
1384       •   "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
1388       •   "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
1392       •   "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
1396       •   "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
1400       •   "password_length_min" - the minimum length of passwords generated
1401           by the loaded config.
1402
1403       •   "password_length_max" - the maximum length of passwords generated
1404           by the loaded config.
1405
1406       •   "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
1412       •   "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
1417       •   "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
1422       •   "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
1428       •   "passwords_generated" - the number of passwords this instance has
1429           generated.
1430
1431       •   "password_random_numbers_required" - the number of random numbers
1432           needed to generate a single password using the loaded config.
1433
1434       •   "randomnumbers_cached" - the number of random numbers currently
1435           cached within the instance.
1436
1437       •   "randomnumbers_cache_increment" - the number of random numbers
1438           generated at once to replenish the cache when it's empty.
1439
1440       •   "randomnumbers_source" - the class used by the instance to generate
1441           random numbers.
1442
1443       ->status()
1444
1445           print $hsxkpasswd_instance->status();
1446
1447       Generates a string detailing the internal status of the instance. Below
1448       is a sample status string:
1449
1450           *DICTIONARY*
1451           Source: Crypt::HSXKPasswd::Dictionary::EN
1452           # words: 1425
1453           # words of valid length: 1194 (84%)
1454
1455           *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
1470           *RANDOM NUMBER CACHE*
1471           Random Number Generator: Crypt::HSXKPasswd::RNG::Basic
1472           # in cache: 0
1473
1474           *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
1483       ->update_config()
1484
1485           $hsxkpasswd_instance->update_config({separator_character => '+'});
1486
1487       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
1494   CLASS METHODS
1495       NOTE - All class methods must be invoked via the package name, or they
1496       will croak.
1497
1498       clone_config()
1499
1500           my $clone = Crypt::HSXKPasswd->clone_config($config);
1501
1502       This function must be passed a valid config hashref as the first
1503       argument or it will croak. The function returns a hashref.
1504
1505       config_key_definition()
1506
1507           my %key_definition = Crypt::HSXKPasswd->config_key_definition($key_name);
1508
1509       A function to return the definition for a config key. The definition is
1510       returned as a hash indexed by the following keys:
1511
1512       •   "required" - 1 if the key is a required key, and 0 otherwise.
1513
1514       •   "type" - a "Type::Tiny" object representing the valid data type for
1515           the key.
1516
1517       •   "expects" - an English description of valid values for the key.
1518
1519       config_key_definitions()
1520
1521           my %key_definitions = Crypt::HSXKPasswd->config_key_definitions();
1522
1523       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
1528       config_stats()
1529
1530           my %stats = Crypt::HSXKPasswd->config_stats($config);
1531           my %stats = Crypt::HSXKPasswd->config_stats(
1532               $config,
1533               suppress_warnings => 1,
1534           );
1535
1536       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
1540       •   "length_min" - the minimum length a password generated with the
1541           given config could be.
1542
1543       •   "length_max" - the maximum length a password generated with the
1544           given config could be. (see caveat below)
1545
1546       •   "random_numbers_required" - the amount of random numbers needed to
1547           generate a password using the given config.
1548
1549       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
1560       config_to_json()
1561
1562           my $config_json_string = Crypt::HSXKPasswd->config_to_json($config);
1563
1564       This function returns a JSON representation of the passed config
1565       hashref as a scalar string.
1566
1567       The function must be passed a valid config hashref or it will croak.
1568
1569       config_to_string()
1570
1571           my $config_string = Crypt::HSXKPasswd->config_to_string($config);
1572
1573       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
1577       default_config()
1578
1579           my $config = Crypt::HSXKPasswd->default_config();
1580
1581       This function returns a hashref containing a config with default
1582       values.
1583
1584       This function can optionally be called with a single argument, a
1585       hashref containing keys with values to override the defaults with.
1586
1587           my $config = Crypt::HSXKPasswd->default_config({num_words => 3});
1588
1589       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
1592       This function is a shortcut for "preset_config()", and the two examples
1593       above are equivalent to the following:
1594
1595           my $config = Crypt::HSXKPasswd->preset_config('DEFAULT');
1596           my $config = Crypt::HSXKPasswd->preset_config('DEFAULT', {num_words => 3});
1597
1598       defined_config_keys()
1599
1600           my @config_key_names = Crypt::HSXKPasswd->defined_config_keys();
1601
1602       This function returns the list of valid config key names as an array of
1603       strings.
1604
1605       defined_presets()
1606
1607           my @preset_names = Crypt::HSXKPasswd->defined_presets();
1608
1609       This function returns the list of defined preset names as an array of
1610       strings.
1611
1612       distil_to_config_keys()
1613
1614           my $dist_hashref = Crypt::HSXKPasswd->distil_to_config_keys($hashref);
1615
1616       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
1619       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
1624       The warnings can be controlled with a pair of optional named arguments
1625       that can be added as a second argument:
1626
1627           # suppress all warnings
1628           my $dist_hashref = Crypt::HSXKPasswd->distil_to_config_keys(
1629               $hashref,
1630               suppress_warnings => 1,
1631           );
1632
1633           # 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
1639       distil_to_symbol_alphabet()
1640
1641           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
1647       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
1651       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
1656       distil_to_words()
1657
1658           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
1664       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
1668       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
1673       is_valid_config()
1674
1675           # determine the validity
1676           my $is_ok = Crypt::HSXKPasswd->is_valid_config($config);
1677
1678           # assert the validity - will croak if the config is invalid
1679           Crypt::HSXKPasswd->is_valid_config($config, croak => 1);
1680
1681       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
1684       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
1688       When calling the function with "croak" set to 1, the message thrown by
1689       croak will explain why the config is invalid.
1690
1691           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
1698       module_config()
1699
1700           my $debug_val = Crypt::HSXKPasswd->module_config('DEBUG'); # getter
1701           Crypt::HSXKPasswd->module_config('DEBUG', 1); # setter
1702
1703       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
1711       The function will croak if called with an invalid module configuration
1712       key name, or passed an invalid new value.
1713
1714       For a list of the module configuration keys, see the MODULE
1715       CONFIGURATION section of this document.
1716
1717       preset_config()
1718
1719           my $config = Crypt::HSXKPasswd->preset_config('XKCD');
1720
1721       This function returns the config hashref for a given preset. See above
1722       for the list of available presets.
1723
1724       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
1728       This function can optionally accept a second argument, a hashref
1729       containing keys with values to override the defaults with.
1730
1731           my $config = Crypt::HSXKPasswd->preset_config(
1732               'XKCD',
1733               {case_transform => 'INVERT'}
1734           );
1735
1736       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
1739       preset_definition()
1740
1741           my %preset_def = Crypt::HSXKPasswd->preset_definition('XKCD');
1742
1743       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
1747       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
1751       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
1755       preset_definitions()
1756
1757           my %preset_defs = Crypt::HSXKPasswd->preset_definitions();
1758
1759       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
1763       This function does not take any arguments.
1764
1765       presets_json()
1766
1767           my $json_string = Crypt::HSXKPasswd->presets_json();
1768
1769       This function returns a JSON string representing all the defined
1770       configs, including their descriptions.
1771
1772       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
1778       preset_description()
1779
1780           my $description = Crypt::HSXKPasswd->preset_description('XKCD');
1781
1782       This function returns the description for a given preset. See above for
1783       the list of available presets.
1784
1785       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
1789       presets_to_string()
1790
1791           print Crypt::HSXKPasswd->presets_to_string();
1792
1793       This function returns a string containing a description of each defined
1794       preset and the configs associated with the presets.
1795
1796   COMMANDLINE INTERFACE
1797       The module ships with a commandline interface to this library, simply
1798       called "hsxkpasswd".
1799
1800       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
1805       Both preset overrides and password generator configurations must be
1806       specified in JSON format.
1807
1808       Examples
1809
1810       Generate a single password using all the default settings:
1811
1812           hsxkpasswd
1813
1814       Generate five passwords using the default settings:
1815
1816           hsxkpasswd 5
1817
1818       Generate five passwords using the "XKCD" preset:
1819
1820           hsxkpasswd -p XKCD 5
1821
1822       Generate five passwords using the "XKCD" preset with an overridden
1823       password generator configuration key:
1824
1825           hsxkpasswd -p XKCD -o '{"separator_character" : "*"}' 5
1826
1827       Generate five passwords using a custom password generator configuration
1828       stored in a text file in JSON format:
1829
1830           hsxkpasswd -c my_config.json
1831
1832       Further Reading
1833
1834       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
1837           hsxkpasswd -h
1838
1839       If you are new to JSON, you may find the following links useful:
1840
1841       •   JSON on Wikipedia - <http://en.wikipedia.org/wiki/JSON>
1842
1843       •   A free online JSON validator -
1844           <http://jsonformatter.curiousconcept.com>
1845
1846       •   A JSON tutorial from W3Schools - <http://www.w3schools.com/json/>
1847
1848   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
1856       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
1864       Entropy checking is controlled via three module configuration variables
1865       (which can be accessed and updated using the function
1866       "module_config()"):
1867
1868       •   "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
1873       •   "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
1878       •   "ENTROPY_WARNINGS" - this variable can be used to control the
1879           emission of entropy warnings. The following values are valid:
1880
1881           •   "ALL" - all entropy warnings are emitted. This is the default
1882               value.
1883
1884           •   "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
1888           •   "NONE" - all entropy warnings are suppressed.
1889
1890       Caveats
1891
1892       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
1898       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
1902       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
1908       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
1912   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
1918       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
1922       The module ships with a number of pre-defined word sources:
1923
1924       "Crypt::HSXKPasswd::Dictionary::DE"
1925
1926       A German word list based on the GPL-licensed German dictionary for
1927       WinEdit by Juergen Vierheilig.
1928
1929       Note: This module is licensed under the GPL, not the BSD license used
1930       for the majority of this project.
1931
1932       "Crypt::HSXKPasswd::Dictionary::EN"
1933
1934       A default word list consisting of English words and place names.
1935
1936       "Crypt::HSXKPasswd::Dictionary::ES"
1937
1938       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
1941       "Crypt::HSXKPasswd::Dictionary::FR"
1942
1943       A French word list based on the GPL-licensed French dictionary for
1944       WinEdit.
1945
1946       Note: This module is licensed under GPL V2, not the BSD license used
1947       for the majority of this project.
1948
1949       "Crypt::HSXKPasswd::Dictionary::IT"
1950
1951       An Italian word list based on the free-for-non-commerical-use Italian
1952       dictionary for WinEdit by Karl Koeller.
1953
1954       Note: This module is licensed under GPL V2, not the BSD license used
1955       for the majority of this project.
1956
1957       "Crypt::HSXKPasswd::Dictionary::NL"
1958
1959       A Dutch/Flemish word list based on the GPL-licensed Dutch dictionary
1960       for WinEdit.
1961
1962       Note: This module is licensed under GPL V2, not the BSD license used
1963       for the majority of this project.
1964
1965       "Crypt::HSXKPasswd::Dictionary::PT"
1966
1967       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
1971       Note: This module is licensed under GPL V2.1, not the BSD license used
1972       for the majority of this project.
1973
1974       "Crypt::HSXKPasswd::Dictionary::System"
1975
1976       This class tries to find and use a Unix words file on the system.
1977
1978       The constructor croaks if no system words file can be found.
1979
1980       Usage
1981
1982           my $word_source = Crypt::HSXKPasswd::Dictionary::System->new();
1983
1984       "Crypt::HSXKPasswd::Dictionary::Basic"
1985
1986       This class can be initialised from a words file, or from an array ref
1987       containing words.
1988
1989       Usage
1990
1991           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
1998       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
2004       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
2008   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
2019       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
2029       The module ships with five standard RNGs (described below).
2030
2031       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
2035       1.  "Crypt::HSXKPasswd::RNG::Math_Random_Secure" (only available if
2036           "Math::Random::Secure" is installed on the system).
2037
2038       2.  "Crypt::HSXKPasswd::RNG::Data_Entropy" (only available if
2039           "Data::Entropy::Algorithms" is installed on the system).
2040
2041       3.  "Crypt::HSXKPasswd::RNG::DevUrandom" (only available on Linux/Unix
2042           systems with a "/dev/urandom").
2043
2044       4.  "Crypt::HSXKPasswd::RNG::Basic" (available on all systems because
2045           it uses Perl's built-in "rand()" function).
2046
2047       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
2052       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
2058       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
2063       Crypt::HSXKPasswd::RNG::Math_Random_Secure
2064
2065           my $rng = Crypt::HSXKPasswd::RNG::Math_Random_Secure->new();
2066
2067       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
2072       Crypt::HSXKPasswd::RNG::Data_Entropy
2073
2074           my $rng = Crypt::HSXKPasswd::RNG::Data_Entropy->new();
2075
2076       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
2082       Crypt::HSXKPasswd::RNG::DevUrandom
2083
2084           my $rng = Crypt::HSXKPasswd::RNG::DevUrandom->new();
2085
2086       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
2091       Crypt::HSXKPasswd::RNG::Basic
2092
2093           my $rng = Crypt::HSXKPasswd::RNG::Basic->new();
2094
2095       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
2100       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
2107       Crypt::HSXKPasswd::RNG::RandomDotOrg
2108
2109           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
2115       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
2119       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
2123       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
2129       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
2133       •   "timeout" - the timeout to use when making HTTP requests to
2134           Random.Org in seconds (the default is 180).
2135
2136       •   "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
2141           "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
2145       "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
2148       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
2153       •   "Email::Valid"
2154
2155       •   "LWP::UserAgent"
2156
2157       •   "Mozilla::CA"
2158
2159       •   "URI"
2160

DIAGNOSTICS

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
2170       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
2175       This module produces output at three severity levels:
2176
2177       •   "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
2183       •   "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
2188       •   "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
2197       The value stored in a module configuration variable can be accessed and
2198       updated using the function "module_config()".
2199

CONFIGURATION AND ENVIRONMENT

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

DEPENDENCIES

2206       This module requires the following Perl modules:
2207
2208       •   "Carp" - <http://search.cpan.org/perldoc?Carp>
2209
2210       •   "Clone" - <http://search.cpan.org/perldoc?Clone>
2211
2212       •   "DateTime" - <http://search.cpan.org/perldoc?DateTime>
2213
2214       •   "English" - <http://search.cpan.org/perldoc?English>
2215
2216       •   "Fatal" - <http://search.cpan.org/perldoc?Fatal>
2217
2218       •   "File::HomeDir" -
2219           <http://search.cpan.org/perldoc?File%3A%3AHomeDir>
2220
2221       •   "Getopt::Long" - <http://search.cpan.org/perldoc?Getopt%3A%3ALong>
2222
2223       •   "JSON" - <http://search.cpan.org/perldoc?JSON>
2224
2225       •   "List::MoreUtils" -
2226           <http://search.cpan.org/perldoc?List%3A%3AMoreUtils>
2227
2228       •   "Math::BigInt" - <http://search.cpan.org/perldoc?Math%3A%3ABigInt>
2229
2230       •   "Math::Round" - <http://search.cpan.org/perldoc?Math%3A%3ARound>
2231
2232       •   "Module::Load" - <http://search.cpan.org/perldoc?Module%3A%3ALoad>
2233
2234       •   "Pod::Usage" - <http://search.cpan.org/perldoc?Pod%3A%3AUsage>
2235
2236       •   "Readonly" - <http://search.cpan.org/perldoc?Readonly>
2237
2238       •   "Scalar::Util" - <http://search.cpan.org/perldoc?Scalar%3A%3AUtil>
2239
2240       •   "strict" - <http://search.cpan.org/perldoc?strict>
2241
2242       •   "Text::Unidecode" -
2243           <http://search.cpan.org/perldoc?Text%3A%3AUnidecode>
2244
2245       •   "Type::Library" -
2246           <http://search.cpan.org/perldoc?Type%3A%3ALibrary>
2247
2248       •   "Type::Params" - <http://search.cpan.org/perldoc?Type%3A%3AParams>
2249
2250       •   "Type::Tiny" - <http://search.cpan.org/perldoc?Type%3A%3ATiny>
2251
2252       •   "Types::Standard" -
2253           <http://search.cpan.org/perldoc?Types%3A%3AStandard>
2254
2255       •   "warnings" - <http://search.cpan.org/perldoc?warnings>
2256
2257       The module can also optionally use the following Perl modules:
2258
2259       •   "Data::Entropy::Algorithms" -
2260           <http://search.cpan.org/perldoc?Data%3A%3AEntropy%3A%3AAlgorithms>
2261
2262           Used by the RNG class "Crypt::HSXKPasswd::RNG::Data_Entropy".
2263
2264       •   "Devel::StackTrace" -
2265           <http://search.cpan.org/perldoc?Devel%3A%3AStackTrace>
2266
2267           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
2272       •   "Email::Valid" - <http://search.cpan.org/perldoc?Email%3A%3AValid>
2273
2274           Used by the Random.Org RNG class
2275           "Crypt::HSXKPasswd::RNG::RandomDotOrg".
2276
2277       •   "LWP::UserAgent" -
2278           <http://search.cpan.org/perldoc?LWP%3A%3AUserAgent>
2279
2280           Used by the Random.Org RNG class
2281           "Crypt::HSXKPasswd::RNG::RandomDotOrg".
2282
2283       •   "Math::Random::Secure" -
2284           <http://search.cpan.org/perldoc?Math%3A%3ARandom%3A%3ASecure>
2285
2286           Used by the RNG class "Crypt::HSXKPasswd::RNG::Math_Random_Secure".
2287
2288       •   "Mozilla::CA" - <http://search.cpan.org/perldoc?Mozilla%3A%3ACA>
2289
2290           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
2295       •   "URI" - <http://search.cpan.org/perldoc?URI>
2296
2297           Used by the Random.Org RNG class
2298           "Crypt::HSXKPasswd::RNG::RandomDotOrg".
2299

INCOMPATIBILITIES

2301       This module has no known incompatibilities.
2302

BUGS AND LIMITATIONS

2304       There are no known bugs in this module.
2305
2306       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
2313       Redistribution and use in source and binary forms, with or without
2314       modification, are permitted provided that the following conditions are
2315       met:
2316
2317       1.  Redistributions of source code must retain the above copyright
2318           notice, this list of conditions and the following disclaimer.
2319
2320       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
2325       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
2337       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
2340       •   The "share/sample_dict_DE.txt" text file.
2341
2342       •   The "Crypt::HSXKPasswd::Dictionary::DE" Perl module.
2343
2344       •   The "share/sample_dict_FR.txt" text file.
2345
2346       •   The "Crypt::HSXKPasswd::Dictionary::FR" Perl module.
2347
2348       •   The "share/sample_dict_IT.txt" text file.
2349
2350       •   The "Crypt::HSXKPasswd::Dictionary::IT" Perl module.
2351
2352       •   The "share/sample_dict_NL.txt" text file.
2353
2354       •   The "Crypt::HSXKPasswd::Dictionary::NL" Perl module.
2355
2356       •   The "share/sample_dict_PT.txt" text file.
2357
2358       •   The "Crypt::HSXKPasswd::Dictionary::PT" Perl module.
2359

AUTHOR

2361       Bart Busschots (<mailto:bart@bartificer.net>)
2362
2363
2364
2365perl v5.34.0                      2022-01-20              Crypt::HSXKPasswd(3)
Impressum