NAME

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

SYNOPSIS

Generate Passwords:

    hsxkpasswd [options] [num_passwords]

Available Options:

    -c|--config-file FILE
    -d|--dict-file FILE
    --dict-pkg PERL_PACKAGE_NAME
    --dict-pkg-args JSON_STRING
    -o|--overrides JSON_STRING
    -p|--preset PRESET_NAME
    -r|--rng-pkg PERL_PACKAGE_NAME
    --rng-pkg-args JSON_STRING

Information/Utility Functions:

    hsxkpasswd -v|--version
    hsxkpasswd -h|--help
    hsxkpasswd> -l|--list-presets
    hsxkpasswd> -t|--test-config FILE
    hsxkpasswd> --test-rcfile FILE

OPTIONS

-c, --config-file

The path to a file containing a valid config as a JSON string.

Config files can be tested with either of the commands:

    hsxkpasswd -t file
    hsxkpasswd --test-config file

If the specified config is invalid, the command will try to give useful feedback to help debug the config.

It is possible for a config file to contain extraneous configuration keys but still be usable by the command. In this case the command will issue warnings, but still evaluate the config as valid.

-d, --dict-file

The path to a dictionary file to use as the word source. The file must be UTF-8 encoded.

--dict-pkg

The name of a Perl module to use as the word source when generating passwords.

The specified module must meet the following criteria:

The package must be installed on the system and available within Perl's standard library paths (@INC).
The package must extend the class Crypt::HSXKPasswd::Dictionary, and must override all the needed functions as described in the "WORD SOURCES" section of the Crypt::HSXKPasswd documentation.
The package should not require any parameters on import.

Crypt::HSXKPasswd ships with a number of standard packages that can be used with this option. For more details see the "WORD SOURCES" section of the Crypt::HSXKPasswd documentation.

If this option is not passed, the package Crypt::HSXKPasswd::Dictionary::EN_Default is used.

--dict-pkg-args

A JSON string representing an array of arguments to pass to the constructor of the package specified with --dict-pkg.

-o, --overrides

A JSON string representing a hash of configuration key names and values to override one or more configuration values from the loaded preset.

This option is ignored unless a preset is specified.

-p, --preset

Use the specified preset when generating passwords.

A list of presets can be generated with either of the the commands:

    hsxkpasswd -l
    hsxkpasswd --list-presets

Note that -c/--config-file takes precedence over this option.

-r, --rng-pkg

The name of a Perl module to use as the random number generator (RNG) when generating passwords.

The specified module must meet the following criteria:

The package must be installed on the system and available within Perl's standard library paths (@INC).
The package must extend the class Crypt::HSXKPasswd::RNG, and must override all the needed functions as described in the "RANDOM NUMBER SOURCES" section of the Crypt::HSXKPasswd documentation.
The package should not require any parameters to import.

Crypt::HSXKPasswd ships with a number of standard packages that can be used with this option. For more details see the "RANDOM NUMBER SOURCES" section of the Crypt::HSXKPasswd documentation.

If this option is not passed, the package uses the most secure supported RNG available on the system.

--rng-pkg-args: A JSON string representing an array of arguments to pass to the constructor of the package specified with -r/--rng-pkg.
-w, --warn: The entropy warning level to use when initialising the Crypt::HSXKPasswd object that will be used to generate the passwords.
Must be one of "ALL", "BLIND", or "NONE".
--rcfile: The path to a hsxkpasswdrc file. For more details see the FILES section of this document.
--verbose: Enable verbose output. Information about the internal state of the Crypt::HSXKPasswd object initialised by the command to generate passwords will be printed to STDERR before the passwords are printed to STDOUT.

EXIT CODES

0: Success - the command executed without error.
1: User Error - there was something wrong with some input form the user.
2: System Error - an unexpected error occurred while trying to generate the password(s).

DESCRIPTION

This is a command-line interface to the Perl module Crypt::HSXKPasswd, a module designed to generate secure memorable passwords inspired by Steve Gibson's Password Hay Stacks (https://www.grc.com/haystack.htm) and the famous 'correct horse battery staple' issue of the XKCD web comic (https://xkcd.com/936/).

Passwords are generated using the following algorithm:

1.: Randomly choose some words from a word source.
2.: Apply any desired case transformations to the words.
3.: Create pseudo-words consisting of a few randomly chosen digits and add one to the front and back of the words
4.: Insert a separator symbol between each of the words. This symbol can be randomly chosen, but all the words and pseudo-words will be separated from each other by the same symbol.
5.: Zero or more instances of a padding symbol are added to the front and back of the password. Again, this symbol can be randomly chosen, but there will be just one padding symbol used in any one password.

This process can be visualised as follows:

    correct horse battery staple
    CORRECT horse BATTERY STAPLE
    94 CORRECT horse BATTERY STAPLE 34
    94-CORRECT-horse-BATTERY-STAPLE-34
    !!94-CORRECT-horse-BATTERY-STAPLE-34!!

Many aspects of this algorithm can be customised, and all steps apart from the first one are optional. You could use this command to generate a random password consisting of only words, with no case transformations, no digits, no separator symbol, and no padding symbol.

For ease of use, a number of named presets have been created. See the SYNOPSIS and OPTIONS sections of this document for details on how to use presets.

It is also possible to tweak a preset by overriding one or more configuration keys using the --overrides option.

For a more detailed explanation on how to configure this password generator, see the documentation for the Crypt::HSXKPasswd documentation, which can be accessed using the perldoc command: perldoc Crypt::HSXKPasswd

"hsxkpasswdrc" FILES

hsxkpasswdrc files can be used to specify custom presets, and to override some default settings.

hsxkpasswdrc files can be loaded explicitly by using the --rcfile option, or implicitly by creating a file called .hsxkpasswdrc and placing it at the root of the home folder of the user account executing the hsxkpasswd command.

If the --rcfile option is specified, and there is a file named .hsxkpasswdrc in the user's home directory, the file specified with the --rcfile option takes precedence.

The --rcfile option can also be used to suppress the loading of all hsxkpasswdrc files by specifying the special value "NONE".

The "hsxkpasswdrc" File Format

hsxkpasswdrc files must contain a valid JSON string, and be UTF-8 encoded.

The JSON string must represent a reference to a hash indexed by zero or more of the following keys (and no other keys):

custom_presets

A hash of preset definitions indexed by preset name.

Preset names must be strings of length at least one consisting of only upper-case un-accented letters, digits, and underscores.

Preset definitions must be hashes indexed by the keys "description" and "config", with description contianing a non-empty string, and config a valid config hashref.

default_entropy_warnings

The entropy warning level to use when initialising the Crypt::HSXKPasswd object that will be used to generate the passwords.

Must be one of ALL, BLIND, or NONE.

This value will be ignored whenever either of the -w or --warn options are specified.

default_dictionary

A reference to a hash indexed by either:

file

The path to a dictionary file to use as the default word source.

package

A string containing the perl package name to use as the default word source.

The package must extend Crypt::HSXKPasswd::Dictionary.

Arguments to the package's constructor can be specified using the optional key package_constructor_arguments. The arguments must be a reference to an array.

Word sources passed as command line options take precedence over the word source specified here.

default_rng

A reference to a hash indexed by package, and optionally package_constructor_arguments.

package must be a string containing the perl package name to use as the default random number source, and the package must extend Crypt::HSXKPasswd::RNG.

Arguments for the package's constructor can be specified with package_constructor_arguments, which must be a reference to an array.

The package specified will only be used when neither the -r nor --rng-pkg command line options are specified.

Testing "hsxkpasswdrc" Files

The --test-rcfile option can be used to test whether the specified file is a valid hsxkpasswdrc file.

LICENCE AND COPYRIGHT

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1.: Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2.: Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

AUTHOR

Bart Busschots (http://www.bartbusschots.ie/)