1HSXKPASSWD(1)         User Contributed Perl Documentation        HSXKPASSWD(1)
2
3
4

NAME

6       hsxkpasswd (v1.3) - a command-line interface to the Crypt::HSXKPasswd
7       secure memorable password generator (<http://www.bartb.ie/xkpasswd>).
8

SYNOPSIS

10       Generate Passwords:
11
12           hsxkpasswd [options] [num_passwords]
13
14       Available Options:
15
16           -c|--config-file FILE
17           -d|--dict-file FILE
18           --dict-pkg PERL_PACKAGE_NAME
19           --dict-pkg-args JSON_STRING
20           -o|--overrides JSON_STRING
21           -p|--preset PRESET_NAME
22           -r|--rng-pkg PERL_PACKAGE_NAME
23           --rng-pkg-args JSON_STRING
24
25       Information/Utility Functions:
26
27           hsxkpasswd -v|--version
28           hsxkpasswd -h|--help
29           hsxkpasswd> -l|--list-presets
30           hsxkpasswd> -t|--test-config FILE
31           hsxkpasswd> --test-rcfile FILE
32

OPTIONS

34       -c, --config-file
35               The path to a file containing a valid config as a JSON string.
36
37               Config files can be tested with either of the commands:
38
39                   hsxkpasswd -t file
40                   hsxkpasswd --test-config file
41
42               If the specified config is invalid, the command will try to
43               give useful feedback to help debug the config.
44
45               It is possible for a config file to contain extraneous
46               configuration keys but still be usable by the command. In this
47               case the command will issue warnings, but still evaluate the
48               config as valid.
49
50       -d, --dict-file
51               The path to a dictionary file to use as the word source. The
52               file must be UTF-8 encoded.
53
54       --dict-pkg
55               The name of a Perl module to use as the word source when
56               generating passwords.
57
58               The specified module must meet the following criteria:
59
60               •   The package must be installed on the system and available
61                   within Perl's standard library paths (@INC).
62
63               •   The package must extend the class
64                   Crypt::HSXKPasswd::Dictionary, and must override all the
65                   needed functions as described in the "WORD SOURCES" section
66                   of the Crypt::HSXKPasswd documentation.
67
68               •   The package should not require any parameters on import.
69
70               Crypt::HSXKPasswd ships with a number of standard packages that
71               can be used with this option. For more details see the "WORD
72               SOURCES" section of the Crypt::HSXKPasswd documentation.
73
74               If this option is not passed, the package
75               Crypt::HSXKPasswd::Dictionary::EN_Default is used.
76
77       --dict-pkg-args
78               A JSON string representing an array of arguments to pass to the
79               constructor of the package specified with --dict-pkg.
80
81       -o, --overrides
82               A JSON string representing a hash of configuration key names
83               and values to override one or more configuration values from
84               the loaded preset.
85
86               This option is ignored unless a preset is specified.
87
88       -p, --preset
89               Use the specified preset when generating passwords.
90
91               A list of presets can be generated with either of the the
92               commands:
93
94                   hsxkpasswd -l
95                   hsxkpasswd --list-presets
96
97               Note that -c/--config-file takes precedence over this option.
98
99       -r, --rng-pkg
100               The name of a Perl module to use as the random number generator
101               (RNG) when generating passwords.
102
103               The specified module must meet the following criteria:
104
105               •   The package must be installed on the system and available
106                   within Perl's standard library paths (@INC).
107
108               •   The package must extend the class Crypt::HSXKPasswd::RNG,
109                   and must override all the needed functions as described in
110                   the "RANDOM NUMBER SOURCES" section of the
111                   Crypt::HSXKPasswd documentation.
112
113               •   The package should not require any parameters to import.
114
115               Crypt::HSXKPasswd ships with a number of standard packages that
116               can be used with this option. For more details see the "RANDOM
117               NUMBER SOURCES" section of the Crypt::HSXKPasswd documentation.
118
119               If this option is not passed, the package uses the most secure
120               supported RNG available on the system.
121
122       --rng-pkg-args
123               A JSON string representing an array of arguments to pass to the
124               constructor of the package specified with -r/--rng-pkg.
125
126       -w, --warn
127               The entropy warning level to use when initialising the
128               Crypt::HSXKPasswd object that will be used to generate the
129               passwords.
130
131               Must be one of "ALL", "BLIND", or "NONE".
132
133       --rcfile
134               The path to a hsxkpasswdrc file. For more details see the FILES
135               section of this document.
136
137       --verbose
138               Enable verbose output. Information about the internal state of
139               the Crypt::HSXKPasswd object initialised by the command to
140               generate passwords will be printed to STDERR before the
141               passwords are printed to STDOUT.
142

EXIT CODES

144       0       Success - the command executed without error.
145
146       1       User Error - there was something wrong with some input form the
147               user.
148
149       2       System Error - an unexpected error occurred while trying to
150               generate the password(s).
151

DESCRIPTION

153       This is a command-line interface to the Perl module Crypt::HSXKPasswd,
154       a module designed to generate secure memorable passwords inspired by
155       Steve Gibson's Password Hay Stacks (https://www.grc.com/haystack.htm)
156       and the famous 'correct horse battery staple' issue of the XKCD web
157       comic (https://xkcd.com/936/).
158
159       Passwords are generated using the following algorithm:
160
161       1.  Randomly choose some words from a word source.
162
163       2.  Apply any desired case transformations to the words.
164
165       3.  Create pseudo-words consisting of a few randomly chosen digits and
166           add one to the front and back of the words
167
168       4.  Insert a separator symbol between each of the words. This symbol
169           can be randomly chosen, but all the words and pseudo-words will be
170           separated from each other by the same symbol.
171
172       5.  Zero or more instances of a padding symbol are added to the front
173           and back of the password. Again, this symbol can be randomly
174           chosen, but there will be just one padding symbol used in any one
175           password.
176
177       This process can be visualised as follows:
178
179           correct horse battery staple
180           CORRECT horse BATTERY STAPLE
181           94 CORRECT horse BATTERY STAPLE 34
182           94-CORRECT-horse-BATTERY-STAPLE-34
183           !!94-CORRECT-horse-BATTERY-STAPLE-34!!
184
185       Many aspects of this algorithm can be customised, and all steps apart
186       from the first one are optional. You could use this command to generate
187       a random password consisting of only words, with no case
188       transformations, no digits, no separator symbol, and no padding symbol.
189
190       For ease of use, a number of named presets have been created. See the
191       SYNOPSIS and OPTIONS sections of this document for details on how to
192       use presets.
193
194       It is also possible to tweak a preset by overriding one or more
195       configuration keys using the --overrides option.
196
197       For a more detailed explanation on how to configure this password
198       generator, see the documentation for the Crypt::HSXKPasswd
199       documentation, which can be accessed using the perldoc command:
200           perldoc Crypt::HSXKPasswd
201

"hsxkpasswdrc" FILES

203       hsxkpasswdrc files can be used to specify custom presets, and to
204       override some default settings.
205
206       hsxkpasswdrc files can be loaded explicitly by using the --rcfile
207       option, or implicitly by creating a file called .hsxkpasswdrc and
208       placing it at the root of the home folder of the user account executing
209       the hsxkpasswd command.
210
211       If the --rcfile option is specified, and there is a file named
212       .hsxkpasswdrc in the user's home directory, the file specified with the
213       --rcfile option takes precedence.
214
215       The --rcfile option can also be used to suppress the loading of all
216       hsxkpasswdrc files by specifying the special value "NONE".
217
218   The "hsxkpasswdrc" File Format
219       hsxkpasswdrc files must contain a valid JSON string, and be UTF-8
220       encoded.
221
222       The JSON string must represent a reference to a hash indexed by zero or
223       more of the following keys (and no other keys):
224
225       custom_presets
226               A hash of preset definitions indexed by preset name.
227
228               Preset names must be strings of length at least one consisting
229               of only upper-case un-accented letters, digits, and
230               underscores.
231
232               Preset definitions must be hashes indexed by the keys
233               "description" and "config", with description contianing a non-
234               empty string, and config a valid config hashref.
235
236       default_entropy_warnings
237               The entropy warning level to use when initialising the
238               Crypt::HSXKPasswd object that will be used to generate the
239               passwords.
240
241               Must be one of ALL, BLIND, or NONE.
242
243               This value will be ignored whenever either of the -w or --warn
244               options are specified.
245
246       default_dictionary
247               A reference to a hash indexed by either:
248
249               file    The path to a dictionary file to use as the default
250                       word source.
251
252               package A string containing the perl package name to use as the
253                       default word source.
254
255                       The package must extend Crypt::HSXKPasswd::Dictionary.
256
257                       Arguments to the package's constructor can be specified
258                       using the optional key package_constructor_arguments.
259                       The arguments must be a reference to an array.
260
261               Word sources passed as command line options take precedence
262               over the word source specified here.
263
264       default_rng
265               A reference to a hash indexed by package, and optionally
266               package_constructor_arguments.
267
268               package must be a string containing the perl package name to
269               use as the default random number source, and the package must
270               extend Crypt::HSXKPasswd::RNG.
271
272               Arguments for the package's constructor can be specified with
273               package_constructor_arguments, which must be a reference to an
274               array.
275
276               The package specified will only be used when neither the -r nor
277               --rng-pkg command line options are specified.
278
279   Testing "hsxkpasswdrc" Files
280       The --test-rcfile option can be used to test whether the specified file
281       is a valid hsxkpasswdrc file.
282
284       Copyright (c) 2015, Bart Busschots T/A Bartificer Web Solutions All
285       rights reserved.
286
287       Redistribution and use in source and binary forms, with or without
288       modification, are permitted provided that the following conditions are
289       met:
290
291       1.  Redistributions of source code must retain the above copyright
292           notice, this list of conditions and the following disclaimer.
293
294       2.  Redistributions in binary form must reproduce the above copyright
295           notice, this list of conditions and the following disclaimer in the
296           documentation and/or other materials provided with the
297           distribution.
298
299       THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
300       IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
301       TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
302       PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
303       OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
304       SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
305       LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
306       DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
307       THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
308       (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
309       OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
310

AUTHOR

312       Bart Busschots (http://www.bartbusschots.ie/)
313
314
315
316perl v5.34.0                      2022-01-20                     HSXKPASSWD(1)
Impressum