Since version 3.5, the Crypt::HSXKPasswd password generating perl module ships with a command line interface to the password generator called hsxkpasswd. This provides a way for non-Perl programers to access the vast majority of the module’s functionality.

The easiest way to install the module, and it’s accompanying terminal command is via CPAN:

sudo cpan Crypt::HSXKPasswd

Once the module is installed, you’ll have access to the hsxkpasswd terminal command.

Getting started is simple, run the command with no arguments at all and it will generate one password using the default settings:

bart-iMac2013:~ bart$ hsxkpasswd
bart-iMac2013:~ bart$

If you want more passwords, pass a number as an argument, and you’ll get that many passwords:

bart-iMac2013:~ bart$ hsxkpasswd 10
bart-iMac2013:~ bart$

Using Built-in Presets

The module, and hence the terminal command, ships with a number of pre-defined presets. To see a list of all available presets, use the -l (or --list-presets) flag:

bart-iMac2013:~ bart$ hsxkpasswd -l
bart-iMac2013:~ bart$ 

To use a preset, use the -p (or --preset) flag:

bart-iMac2013:~ bart$ hsxkpasswd -p SECURITYQ
angry call fast soldier Monday Delaware?
bart-iMac2013:~ bart$ 

You can of course still generate as many passwords at once as you like:

bart-iMac2013:~ bart$ hsxkpasswd -p SECURITYQ 10
suddenly rich game desire Tuesday seeds.
practice mile colour practice roll always.
park resent offer signal even simple.
lower dish room sent tomorrow mind?
story drawing strange spell Fiji burn.
think shall complete march afraid sight!
suffix finally surface again seem angle.
kitchen later division dinner park killed?
over period dollar hunger kept slowly?
fellow Panama building what worn because.
bart-iMac2013:~ bart$

It is also possible to tweak an existing preset by overriding the values in specific configuration keys. The first step to doing this is to peek under the hood and look at the settings specified by the preset you want to tweak, you can do that with the --verbose flag (I’ve marked the relevant section of the verbose output in bold):

bart-iMac2013:~ bart$ hsxkpasswd --verbose -p SECURITYQ
*NOTE* no hsxkpasswdrc file loaded
*NOTE* no custom entropy warning level set
*NOTE* using standard preset 'SECURITYQ'
*NOTE* using default word source
*NOTE* using default rng

Source: Crypt::HSXKPasswd::Dictionary::EN
# words: 1259
# words of valid length: 1194 (95%)
Contains Accented Characters: NO

allow_accents: '0'
case_transform: 'NONE'
num_words: '6'
padding_alphabet: ['!', '.', '?']
padding_character: 'RANDOM'
padding_characters_after: '1'
padding_characters_before: '0'
padding_digits_after: '0'
padding_digits_before: '0'
padding_type: 'FIXED'
separator_character: ' '
word_length_max: '8'
word_length_min: '4'

Random Number Generator: Crypt::HSXKPasswd::RNG::Math_Random_Secure
# in cache: 0

Password length: between 30 & 54
Permutations (brute-force): between 1.33x10^53 & 4.22x10^95 (average 2.37x10^74)
Permutations (given dictionary & config): 8.69x10^18
Entropy (Brute-Force): between 176bits and 317bits (average 247bits)
Entropy (given dictionary & config): 62bits
# Random Numbers needed per-password: 7
Passwords Generated: 0

spring might opposite poem London soil?
bart-iMac2013:~ bart$

Let’s say we don’t like having question marks at the end of the generated security question answers, and lets say we want to alternate the case of each word, but leave the rest of the preset the same. We can do this with the -o (or --overrides) flag. This flag expects the value to be a JSON string representing configuration key name-value pairs (for help with JSON see this quick intro). The command below makes our desired changes:

bart-iMac2013:~ bart$ hsxkpasswd -p SECURITYQ -o '{"padding_alphabet" : [".", "!"], "case_transform" : "ALTERNATE"}' 10
SEEDS rain BRIGHT plan SOME receive.
happy HUNTING stop SHIP mine AFRAID!
GOVERN sand SAIL into FRONT school.
dish BETWEEN there SETTLE result AWAY!
story MEMBER british MISTER trust FIJI!
SHOUT agree SINGLE halt INCLUDE spend.
STRENGTH english STREET than TEST laugh.
later BRITAIN turn EVEN nearly MEMBER!
however NEVADA cuba RETURN happen WING.
BRAZIL none TOWARD neptune BELL forever.
bart-iMac2013:~ bart$ 

Creating Custom Presets

While tweaking existing presets might be a good approach much of the time, you may find yourself wanting to create a custom configuration that looks absolutely nothing like any of the presets. You can do this by creating a text file that represents your chosen settings in JSON format, and then passing the path to that file to hsxkpasswd using the -c (or --config-file) flag.


You can use the load/save tab in the web interface at to generate your config, then copy and paste it into a text file. The output from that web form is in JSON format. The only small caveat is that to avoid warnings, you should delete the line "random_increment": "AUTO" (and the trailing comma on the line above) from the file.

As an example, I am going to save the following JSON markup to the file ~/Documents/Temp/sampleconfig.json.txt:

 "num_words": 4,
 "word_length_min": 4,
 "word_length_max": 8,
 "case_transform": "ALTERNATE",
 "separator_character": "RANDOM",
 "separator_alphabet": [
 "padding_digits_before": 2,
 "padding_digits_after": 2,
 "padding_type": "FIXED",
 "padding_character": "RANDOM",
 "symbol_alphabet": [
 "padding_characters_before": 1,
 "padding_characters_after": 1

Once that file is saved, I can use my custom created config:

bart-iMac2013:~ bart$ hsxkpasswd -c ~/Documents/Temp/sampleconfig.json.txt 10
bart-iMac2013:~ bart$

Specifying Word Sources

There are two flags that can be used to specify the word list the terminal command should use, -d (or --dict-file), and --dict-pkg (perhaps accompanied by --dict-pkg-args).

The first flag allows users to specify the path to a dictionary file (more on this later), and the second flag allows the user to specify the name of a Perl module which will serve as the word source. The module ships with a number of standard dictionary module, and programmers can create their own custom modules by extending the class Crypt::HSXKPasswd::Dictionary. Since this is a tutorial for terminal users rather than perl programmers, we won’t discuss the ins and outs of creating your own package. I’ll simply list the included dictionary modules of interest to terminal users:

  • Crypt::HSXKPasswd::Dictionary::DE (German words)
  • Crypt::HSXKPasswd::Dictionary::EN (English words – the default word source)
  • Crypt::HSXKPasswd::Dictionary::ES (Spanish words)
  • Crypt::HSXKPasswd::Dictionary::FR (French words)
  • Crypt::HSXKPasswd::Dictionary::IT (Italian words)
  • Crypt::HSXKPasswd::Dictionary::NL (Dutch/Flemish words)
  • Crypt::HSXKPasswd::Dictionary::PT (Portuguese words)

It should be noted that with the exception of the English dictionary, all the rest should be considered beta – they are currently VERY big, so they contain words that are not very common, and, they are slow to use because of their size. I’m looking for volunteers who speak these languages to help trim these dictionaries down to size by removing the uncommon words.

With all that said, the Dutch/Flemish dictionary can be used as follows:

bart-iMac2013:~ bart$ hsxkpasswd --dict-pkg=Crypt::HSXKPasswd::Dictionary::NL 10
bart-iMac2013:~ bart$

Everyone has their own areas on interest, so you may want to create their own word lists containing words that you will find memorable. For example, Harry Potter fans might like to have words like Expelliarmus in their word list.

By far the simplest way to create your own custom word list is to create a dictionary file. The format is very simple – dictionary files must be text files with one word per line. This is the same format as the standard Unix/Linux words file.

As an example, the following command uses the standard Unix words file:

bart-iMac2013:~ bart$ hsxkpasswd -d /usr/share/dict/words 10
bart-iMac2013:~ bart$

More Information

The terminal command can do much more than just what is described in this post. The command’s detailed documentation can be accessed in two different ways, via the -h (or --help) flag, or via the man command:

hsxkpasswd -h
man hsxkpasswd

In the second part of this tutorial we will look at .hsxkpasswdrc files – these can be used to specify your own defaults for the terminal command, so you can avoid having to use flags all the time, and they can also be used to specify your own custom presets, again, saving you the need to specify overrides or point to JSON files each time you want to use custom settings.

Click here for Part 2.