HSXKPASSWD(1)

📦
version 3.6 · 2 versions
, in alpine 3.24

💅 hsxkpasswd (v1.3) — User Contributed Perl Documentation, but make it cute 💅

🌸 NAME 🌸

Okay so bestie, this is hsxkpasswd (v1.3) — a command-line interface to the Crypt::HSXKPasswd secure memorable password generator (http://www.bartb.ie/xkpasswd). It is literally the CLI glow-up of the Perl module, and it is here to make passwords that are both secure and memorable. Iconic behavior, honestly. ✨

🦋 SYNOPSIS 🦋

Here’s the shape of the whole thing:

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 these 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. Very demure, very mindful of your debugging era. 🫶

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. So it’s giving “messy but functional,” and honestly same.

  • -d, --dict-file — The path to a dictionary file to use as the word source. The file must be UTF-8 encoded. No cap, encoding matters here. 🧚
  • --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. Default queen behavior. 👑

  • --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. It is strictly preset-coded, bestie. 💅

  • -p, --preset — Use the specified preset when generating passwords.

A list of presets can be generated with either of these 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. Security first, always. 🔥

  • --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. It’s giving behind-the-scenes director’s commentary. 🎬

💀 EXIT CODES 💀

  • 0 — Success - the command executed without error.
  • 1 — User Error - there was something wrong with some input from 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/). Yes, we are in our secure-but-memorable era. 🐴🔋📎

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. Minimalist chic, honestly. 🎀

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 the full detailed tea on configuring this password generator, check the documentation for the Crypt::HSXKPasswd documentation, which can be accessed using the perldoc command:

perldoc Crypt::HSXKPasswd

🎀 FILES 🎀

🗂️ 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 containing 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.

Okay bestie, legal time — but don't scroll past, this part is literally the receipts. 💅

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.

So like — two conditions, both super chill, both non-negotiable. Keep the notice, keep the disclaimer. That's the whole vibe check. 🫶

And now the ALL CAPS part, which is the legal equivalent of someone yelling "I'M NOT RESPONSIBLE FOR THIS" from across the room 😭 — but fr fr, it means what it says:

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.
TL;DR for the girlies: it's free to use, free to change, free to ship — just don't strip the copyright notice, don't strip the disclaimer, and if it explodes in your face that's on you, not on Bart. No cap. 💀

👑 AUTHOR 👑

Bart Busschots (<http://www.bartbusschots.ie/>) — he wrote the whole thing, show some respect, main character energy only. 🌟

And that's a wrap on the entire page, bestie!! 🎀 You made it all the way to the end, iconic behavior honestly. 💖 This page ships as part of perl v5.42.2 and was last updated 2024-02-18 — go forth and generate passwords that would make literally everyone jealous. 🦋✨ Slay. 💅

📦 where this page comes from