Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
HSXKPASSWD(1)	      User Contributed Perl Documentation	 HSXKPASSWD(1)

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:

	       o   The package must be installed on the	system and available
		   within Perl's standard library paths	(@INC).

	       o   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.

	       o   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:

	       o   The package must be installed on the	system and available
		   within Perl's standard library paths	(@INC).

	       o   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.

	       o   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
       Copyright (c) 2015, Bart	Busschots T/A Bartificer Web Solutions All
       rights reserved.

       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/)

perl v5.32.1			  2015-08-11			 HSXKPASSWD(1)

NAME | SYNOPSIS | OPTIONS | EXIT CODES | DESCRIPTION | "hsxkpasswdrc" FILES | LICENCE AND COPYRIGHT | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=hsxkpasswd&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help