1HSXKPASSWD(1) User Contributed Perl Documentation HSXKPASSWD(1)
2
6 hsxkpasswd (v1.3) - a command-line interface to the Crypt::HSXKPasswd
7 secure memorable password generator (<http://www.bartb.ie/xkpasswd>).
8
10 Generate Passwords:
11 hsxkpasswd [options] [num_passwords]
13 Available Options:
15 -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 Information/Utility Functions:
26 hsxkpasswd -v|--version
28 hsxkpasswd -h|--help
29 hsxkpasswd> -l|--list-presets
30 hsxkpasswd> -t|--test-config FILE
31 hsxkpasswd> --test-rcfile FILE
32
34 -c, --config-file
35 The path to a file containing a valid config as a JSON string.
36 Config files can be tested with either of the commands:
38 hsxkpasswd -t file
40 hsxkpasswd --test-config file
41 If the specified config is invalid, the command will try to
43 give useful feedback to help debug the config.
44 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 -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 --dict-pkg
55 The name of a Perl module to use as the word source when
56 generating passwords.
57 The specified module must meet the following criteria:
59 · The package must be installed on the system and available
61 within Perl's standard library paths (@INC).
62 · 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 · The package should not require any parameters on import.
69 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 If this option is not passed, the package
75 Crypt::HSXKPasswd::Dictionary::EN_Default is used.
76 --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 -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 This option is ignored unless a preset is specified.
87 -p, --preset
89 Use the specified preset when generating passwords.
90 A list of presets can be generated with either of the the
92 commands:
93 hsxkpasswd -l
95 hsxkpasswd --list-presets
96 Note that -c/--config-file takes precedence over this option.
98 -r, --rng-pkg
100 The name of a Perl module to use as the random number generator
101 (RNG) when generating passwords.
102 The specified module must meet the following criteria:
104 · The package must be installed on the system and available
106 within Perl's standard library paths (@INC).
107 · 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 · The package should not require any parameters to import.
114 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 If this option is not passed, the package uses the most secure
120 supported RNG available on the system.
121 --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 -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 Must be one of "ALL", "BLIND", or "NONE".
132 --rcfile
134 The path to a hsxkpasswdrc file. For more details see the FILES
135 section of this document.
136 --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
144 0 Success - the command executed without error.
145 1 User Error - there was something wrong with some input form the
147 user.
148 2 System Error - an unexpected error occurred while trying to
150 generate the password(s).
151
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 Passwords are generated using the following algorithm:
160 1. Randomly choose some words from a word source.
162 2. Apply any desired case transformations to the words.
164 3. Create pseudo-words consisting of a few randomly chosen digits and
166 add one to the front and back of the words
167 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 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 This process can be visualised as follows:
178 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 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 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 It is also possible to tweak a preset by overriding one or more
195 configuration keys using the --overrides option.
196 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
203 hsxkpasswdrc files can be used to specify custom presets, and to
204 override some default settings.
205 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 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 The --rcfile option can also be used to suppress the loading of all
216 hsxkpasswdrc files by specifying the special value "NONE".
217 The "hsxkpasswdrc" File Format
219 hsxkpasswdrc files must contain a valid JSON string, and be UTF-8
220 encoded.
221 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 custom_presets
226 A hash of preset definitions indexed by preset name.
227 Preset names must be strings of length at least one consisting
229 of only upper-case un-accented letters, digits, and
230 underscores.
231 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 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 Must be one of ALL, BLIND, or NONE.
242 This value will be ignored whenever either of the -w or --warn
244 options are specified.
245 default_dictionary
247 A reference to a hash indexed by either:
248 file The path to a dictionary file to use as the default
250 word source.
251 package A string containing the perl package name to use as the
253 default word source.
254 The package must extend Crypt::HSXKPasswd::Dictionary.
256 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 Word sources passed as command line options take precedence
262 over the word source specified here.
263 default_rng
265 A reference to a hash indexed by package, and optionally
266 package_constructor_arguments.
267 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 Arguments for the package's constructor can be specified with
273 package_constructor_arguments, which must be a reference to an
274 array.
275 The package specified will only be used when neither the -r nor
277 --rng-pkg command line options are specified.
278 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 Redistribution and use in source and binary forms, with or without
288 modification, are permitted provided that the following conditions are
289 met:
290 1. Redistributions of source code must retain the above copyright
292 notice, this list of conditions and the following disclaimer.
293 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 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
312 Bart Busschots (http://www.bartbusschots.ie/)
313perl v5.30.0 2019-07-25 HSXKPASSWD(1)