This is the second part of a two-part post – read part 1 here.

In part 1 we learned how to use the command line too hsxkpasswd to generate passwords, and how to use various flags to specify custom password generation configurations, and word sources. In this second part we’ll look at how to save these customisations for future use with .hsxkpasswdrc files.

.hsxkpasswdrc Files

Before we starts, I just want to say that I don’t want to type ‘.hsxkpasswdrc file’ over and over again, so I’ll use the abbreviation version rc file instead.

Rc files allow you to specify default settings, and to define your own named presets. You can specify that a particular rc file should be used with the --rcfile flag. However, if you save the file in your home directory, and give it the name .hsxkpasswdrc, it will be loaded automatically.

While rc files allow you to specify defaults, their contents will never take precedence over command line flags. So, if you specify a default word source in your rc file, and then specify a different word source with the -d flag, the word source specified with the -d flag is the one that will be used. Similarly, if a file called .hsxkpasswdrc exists in your home directory, and you use the --rcfile flag to point at a different rc file, the one pointed to by the --rcfile flag will be used. You can also use the –rcfile flag with the special value NONE to ignore the file named .hsxkpasswdrc in your home directory.

You can see which rc file is in use, if any, and what settings from that file are being used with the --verbose flag. At the the start of the output you will see a series of notes that show the path to the rc file being used, the entropy warning level in use, and where that setting came from, the config in use, and where it came from, the word source in use, and where it came from, and the random number generator in use, and where it came from.

If we use the --verbose flag and explicitly specify that no rc file should be used, you’ll get the following output:

bart-iMac2013:~ bart$ hsxkpasswd --rcfile NONE --verbose 10
*NOTE* loading of hsxkpasswdrc files disabled with --rcfile=NONE
*NOTE* no custom entropy warning level set
*NOTE* using standard default config
*NOTE* using default word source
*NOTE* using default rng

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

*CONFIG*
allow_accents: '0'
case_transform: 'ALTERNATE'
num_words: '3'
padding_character: 'RANDOM'
padding_characters_after: '2'
padding_characters_before: '2'
padding_digits_after: '2'
padding_digits_before: '2'
padding_type: 'FIXED'
separator_character: 'RANDOM'
symbol_alphabet: ['!', '$', '%', '&', '*', '+', '-', '.', '/', ':', ';', '=', '?', '@', '^', '_', '|', '~']
word_length_max: '8'
word_length_min: '4'

*RANDOM NUMBER CACHE*
Random Number Generator: Crypt::HSXKPasswd::RNG::Math_Random_Secure
# in cache: 0

*PASSWORD STATISTICS*
Password length: between 24 & 36
Permutations (brute-force): between 2.91x10^47 & 1.57x10^71 (average 2.14x10^59)
Permutations (given dictionary & config): 1.10x10^16
Entropy (Brute-Force): between 157bits and 236bits (average 197bits)
Entropy (given dictionary & config): 53bits
# Random Numbers needed per-password: 9
Passwords Generated: 0

==64&texas&CLASS&prepare&67==
~~51-hunt-READY-three-20~~
**27^ORDER^separate^HUNGER^57**
::22@division@PAGE@crops@71::
::14-COUNTRY-picked-MEET-83::
^^92;reach;FIRE;greece;02^^
..10!SHOUT!raise!FINLAND!95..
??62&suit&POEM&belgium&65??
^^03-RIGHT-berlin-BABY-24^^
::17!compare!APRIL!line!97::
bart-iMac2013:~ bart$ 

I have marked the notes I am referring to in bold. Notice that a lot of information about the inner workings of the module are printed when --verbose is used, but that the 10 passwords requested also get printed. For the remainder of this tutorial I’ll be truncating the output of --verbose to show only what’s relevant at the time.

Like all other data structures used by hsxkpasswd, rc files must be in JSON format. To that end, you might find the JSON primer I posted a few weeks ago useful.

Defining Your Own Presets

To define your own presets, add a JSON dictionary to the root of the rc file called custom_presets. The names in the custom_presets JSON dictionary should be the names of the presets being defined, and the values should be JSON dictionaries containing the following key/value pairs:

• descrption: must be a non-empty string
• config

: a valid HSXKPasswd configuration as a JSON dictionary (just like the ones we used in part 1 for specifying custom configurations with the -c key)

Preset names must be in all caps, and contain only letters, digits, and underscores.

This sounds very complicated when you write it down, but it’s not. The following is a fully valid rc file that defines one custom preset called TRUE_XKCD:

{
    "custom_presets" : {
        "TRUE_XKCD" : {
            "description" : "A preset that mimicks the famous cartoon exactly",
            "config" : {
                "word_length_min" : 4,
                "word_length_max" : 8,
                "num_words" : 4,
                "separator_character" : " ",
                "padding_digits_before" : 0,
                "padding_digits_after" : 0,
                "padding_type" : "NONE",
                "case_transform" : "LOWER",
                "allow_accents" : 0
            }
        }
    }
}

Before saving this file into your home directory, you might consider saving it somewhere else and giving it a name like test_hsxkpasswdrc, and testing to make sure the format is valid. You can test the validity of an rc file using the --test-rcfile flag, e.g.:

bart-iMac2013:~ bart$ hsxkpasswd --test-rcfile test_hsxkpasswdrc 
Validing the converted datatsructure from the hsxkpasswdrc file ...
** hsxkpasswdrc data OK **
bart-iMac2013:~ bart$

You can also test that your preset does what you expect by combining the --rcfile and -p flags:

bart-iMac2013:~ bart$ hsxkpasswd --rcfile test_hsxkpasswdrc -p TRUE_XKCD 10
WARNING - Crypt::HSXKPasswd::_update_entropystats_cache(): for attacks assuming full knowledge, the combination of the loaded config and dictionary produces an entropy of 40bits, below the minimum recommended 52bits at /usr/local/bin/hsxkpasswd line 451.
moment early spot table
fish make dark talk
lift paris train lose
killed printed journey east
movement within fight beat
duck wrote round person
speed value norway yourself
expect neighbor finland those
current dare mother doubt
safety public indian mountain
bart-iMac2013:~ bart$

You should now notice two things, firstly, 10 passwords using the new custom preset were generated and printed, and secondly, the command issued a low entropy warning.

What does this warning mean? It means that, in the very unlikely event that the person attacking your password knows ALL of the following, your password is not as secure as a truly random 8-character password:

1. that you use this tool to create your passwords
2. the exact configuration you use
3. the exact word source you use

It’s very unlikely than an attacker will know all of those things, so this warning refers to a very unlikely scenario. You probably want to suppress those warnings. You can do that using the -w flag, or, you can set the warning level in your rc file.

There are three warnings levels, and I am listing them here from most to least paranoid:

1. SEEN – assume the attackers has full knowledge of how your password was made, and if the combination of configuration and word source in use would be easier for that attacker to crack than an 8 character truly random password, issue a warning.
2. BLIND – assume the attacker does not know how you create your passwords, and must resort to a brute-force attack (a very realistic scenario), warn if the passwords generated with the current config would be less secure than a 12 character truly random password.
3. NONE – never warn about password strength

At the moment, the module, and the command-line tool, default to the most paranoid warning level of SEEN. In hind sight I think that was probably a mistake, and it’s likely to change in future versions. I now think BLIND would make a better default.

To set the warning level to BLIND, we could specify -w BLIND each time we use the hsxkpasswd command like so:

bart-iMac2013:~ bart$ hsxkpasswd --rcfile test_hsxkpasswdrc -p TRUE_XKCD -w BLIND 10
note fine sign discover
probable canada friends present
twelve forward nine farm
holland belgium seem germany
drawing desire arrive cloud
tokyo away actually true
bottom galaxy workers corner
family wind history evening
child give green hurry
also green hand describe
bart-iMac2013:~ bart$

Rather than passing our warning level each time, it probably makes more sense to use our rc file to set the default for us. We can do that by adding our desired value using a key called default_entropy_warnings. Below is our original sample rc file with the default warning level added to it:

{
    "custom_presets" : {
        "TRUE_XKCD" : {
            "description" : "A preset that mimicks the famous cartoon exactly",
            "config" : {
                "word_length_min" : 4,
                "word_length_max" : 8,
                "num_words" : 4,
                "separator_character" : " ",
                "padding_digits_before" : 0,
                "padding_digits_after" : 0,
                "padding_type" : "NONE",
                "case_transform" : "LOWER",
                "allow_accents" : 0
            }
        }
    },
    "default_entropy_warnings" : "BLIND"
}

You might want to test your file again, to make sure you didn’t make a mistake adding the default warning level:

bart-iMac2013:~ bart$ hsxkpasswd --test-rcfile test_hsxkpasswdrc
Validing the converted datatsructure from the hsxkpasswdrc file ...
** hsxkpasswdrc data OK **
bart-iMac2013:~ bart$ 

Assuming the file passes the test, you are now ready to move it into place as .hsxkpasswdrc in your home directory:

mv test_hsxkpasswdrc ~/.hsxkpasswdrc

Once that’s done, you can use your new custom preset with just the -p flag, as if it were a built-in preset:

bart-iMac2013:~ bart$ hsxkpasswd -p TRUE_XKCD 10
ship show small carry
season egypt hard type
between duck seeds succeed
seed settle moscow enter
they says almost hall
know drawing farmers death
throw wheels beside rock
wants pole girl action
rest received someone tools
member case finger neither
bart-iMac2013:~ bart$

You’ll notice that your preset also shows up when you list the available presets with the -l flag:

bart-iMac2013:~ bart$ hsxkpasswd -l
APPLEID, DEFAULT, NTLM, SECURITYQ, TRUE_XKCD, WEB16, WEB32, WIFI, XKCD
bart-iMac2013:~ bart$

Finally, you can use the --verbose flag to verify that your rc file is being used:

bart-iMac2013:~ bart$ hsxkpasswd -p TRUE_XKCD --verbose 10
*NOTE* using hsxkpasswdrc file /Users/bart/.hsxkpasswdrc
*NOTE* using entropy warning level specified in hsxkpasswdrc file
*NOTE* using config from custom preset 'TRUE_XKCD'
*NOTE* using default word source
*NOTE* using default rng

...

mexico night decide instead
broke scotland matter june
nine hunt minute daughter
company appear outer fall
possible entered bird neck
practice tried rome certain
earth great meeting farmers
save cents dark worn
less gift divide bicycle
master beauty exactly rome
bart-iMac2013:~ bart$

Overriding Standard Presets

Presets defined in an rc file take precedence over the built-in presets, so, if you disagree with my choices, you can replace my version of a preset with your own.

Instead of adding a new preset called TRUE_XKCD, you could equally well replace the standard preset XKCD with your own version. You do this by simply creating a custom preset with the same name as the standard preset you want to override. We can alter our existing example to that by simply changing TRUE_XKCD to XKCD, resulting in the following file:

{
    "custom_presets" : {
        "XKCD" : {
            "description" : "A preset that mimicks the famous cartoon exactly",
            "config" : {
                "word_length_min" : 4,
                "word_length_max" : 8,
                "num_words" : 4,
                "separator_character" : " ",
                "padding_digits_before" : 0,
                "padding_digits_after" : 0,
                "padding_type" : "NONE",
                "case_transform" : "LOWER",
                "allow_accents" : 0
            }
        }
    },
    "default_entropy_warnings" : "BLIND"
}

Now, we can use our version of the XKCD preset as follows:

bart-iMac2013:~ bart$ hsxkpasswd -p XKCD 10
high will effort cells
havana charge could beyond
three month spain thrown
finished angle saturday cool
himself moscow cake minutes
mouth past there plan
door entered money wood
threw poem case know
niece explain noise sense
quickly practice island wait
bart-iMac2013:~ bart$

Again, you can use the --verbose flag to verify that the custom config in the rc file is taking precedence over the standard:

bart-iMac2013:~ bart$ hsxkpasswd -p XKCD --verbose 10
*NOTE* using hsxkpasswdrc file /Users/bart/.hsxkpasswdrc
*NOTE* using entropy warning level specified in hsxkpasswdrc file
*NOTE* using config from custom preset 'XKCD'
*NOTE* using default word source
*NOTE* using default rng

...

forest equal mind strength
goodbye white likely village
guard this park burn
march venus burn liar
threw silent course egypt
page that nerve entire
plural practice sold want
favor large numeral under
west shirt peru cannot
public century warm succeed
bart-iMac2013:~ bart$

The default configuration used when no preset or config is supplied is the standard preset DEFAULT. This is just a preset though, so, it can be replaced with your own custom preset using an rc file.

In the version of our example rc file below, I have added a new DEFAULT preset of my own that is similar to, but not quite the same as, the standard APPLEID preset:

{
    "custom_presets" : {
        "DEFAULT" : {
            "description" : "A custom default preset to ovrride the standard default",
            "config" : {
                "padding_alphabet" : ["!", "?", "@", "&"],
                "separator_alphabet" : ["-", ":", ".", ","],
                "word_length_min" : 4,
                "word_length_max" : 8,
                "num_words" : 2,
                "separator_character" : "RANDOM",
                "padding_digits_before" : 2,
                "padding_digits_after" : 2,
                "padding_type" : "FIXED",
                "padding_character" : "RANDOM",
                "padding_characters_before" : 1,
                "padding_characters_after" : 1,
                "case_transform" : "ALTERNATE",
                "allow_accents" : 0
            }
        },
        "XKCD" : {
            "description" : "A preset that mimicks the famous cartoon exactly",
            "config" : {
                "word_length_min" : 4,
                "word_length_max" : 8,
                "num_words" : 4,
                "separator_character" : " ",
                "padding_digits_before" : 0,
                "padding_digits_after" : 0,
                "padding_type" : "NONE",
                "case_transform" : "LOWER",
                "allow_accents" : 0
            }
        }
    },
    "default_entropy_warnings" : "BLIND"
}

This new preset will now be used when no configuration is specified:

bart-iMac2013:~ bart$ hsxkpasswd 10
&60,SOLDIERS,flow,59&
?14.shape.NATION.51?
@20.USUALLY.note.54@
!16-DELAWARE-grave-65!
@35-PART-edge-11@
@63:mail:EVER:51@
@13.back.PRODUCTS.82@
?48-that-MORNING-52?
@35-OFFICE-malta-90@
?43,BEYOND,addition,61?
bart-iMac2013:~ bart$

Again, we can use the --verbose flag to verify that that is indeed what is going on:

bart-iMac2013:~ bart$ hsxkpasswd --verbose 10
*NOTE* using hsxkpasswdrc file /Users/bart/.hsxkpasswdrc
*NOTE* using entropy warning level specified in hsxkpasswdrc file
*NOTE* using custom default config from hsxkpasswdrc file
*NOTE* using default word source
*NOTE* using default rng

...

&98:suffix:START:31&
@67.NECK.drive.93@
@22:INDIAN:cold:23@
?96-beauty-VIRGINIA-36?
!69-manner-PROMISE-95!
!85,YOURSELF,enemy,46!
!35.GREAT.uncle.00!
&93:ICELAND:road:29&
?56.SENT.stream.45?
!42.stock.FORGET.06!
bart-iMac2013:~ bart$

Specifying Default Word Sources

Another important use for rc files is to specify a default word source.

Just like there are two ways to specify a word source with flags (-d/--dict-file and --dict-pkg), there are two equivalent options in rc files.

Let’s start by specifying a Perl package as the default word source. Perhaps, your native language is not English, but Dutch, so you would like the Dutch dictionary used by default. The module ships with a Dutch dictionary package, specifically Crypt::HSXKPasswd::Dictionary::NL, we can use that as the default word source by adding a top-level dictionary called default_dictionary to the rc file. In that dictionary we add an entry with the name package and the name of the desired Perl package as the value.

Below is our example rc file updated to use the built-in Dutch dictionary package by default:

{
    "custom_presets" : {
        "DEFAULT" : {
            "description" : "A custom default preset to ovrride the standard default",
            "config" : {
                "padding_alphabet" : ["!", "?", "@", "&"],
                "separator_alphabet" : ["-", ":", ".", ","],
                "word_length_min" : 4,
                "word_length_max" : 8,
                "num_words" : 2,
                "separator_character" : "RANDOM",
                "padding_digits_before" : 2,
                "padding_digits_after" : 2,
                "padding_type" : "FIXED",
                "padding_character" : "RANDOM",
                "padding_characters_before" : 1,
                "padding_characters_after" : 1,
                "case_transform" : "ALTERNATE",
                "allow_accents" : 0
            }
        },
        "XKCD" : {
            "description" : "A preset that mimicks the famous cartoon exactly",
            "config" : {
                "word_length_min" : 4,
                "word_length_max" : 8,
                "num_words" : 4,
                "separator_character" : " ",
                "padding_digits_before" : 0,
                "padding_digits_after" : 0,
                "padding_type" : "NONE",
                "case_transform" : "LOWER",
                "allow_accents" : 0
            }
        }
    },
    "default_entropy_warnings" : "BLIND",
    "default_dictionary" : {
        "package" : "Crypt::HSXKPasswd::Dictionary::NL"
    }
}

We can now generate 10 passwords with Dutch words using our custom default preset as follows:

bart-iMac2013:~ bart$ hsxkpasswd 10
&35.MEMBRAAN.verpacht.82&
?06.BIJGEVAL.beijverd.94?
&19,kopzijde,AFROEIT,79&
!80,lijvigst,BITTERDE,23!
&23,RIJT,kluppel,82&
@01,ONTHIEF,vastheid,96@
!31-AFTOMEN-enten-74!
?97,oostkant,MEEGA,73?
!10.vangrad.UITKEREN.21!
@52:SMEEDDE:gedropen:77@
bart-iMac2013:~ bart$

Again, we can verify that the rc file is being properly interpreted with –verbose:

bart-iMac2013:~ bart$ hsxkpasswd --verbose 10
*NOTE* using hsxkpasswdrc file /Users/bart/.hsxkpasswdrc
*NOTE* using entropy warning level specified in hsxkpasswdrc file
*NOTE* using custom default config from hsxkpasswdrc file
*NOTE* using dictionary package from hsxkpasswdrc file
*NOTE* using default rng

...

@14,aanpap,ZEURIGST,59@
@78.TONGPUNT.goud.12@
?54,kromlag,STROPJE,70?
!10:ZANGERES:treksels:91!
@55:bevragen:BEKEERT:23@
?75,broekpak,MADAMS,20?
?78-puzzels-VOORAAN-50?
&85-HOENTJES-zwingelt-24&
!19,VRIJSTE,melodie,55!
!83:GEDUURD:gelaten:35!
bart-iMac2013:~ bart$ 

There is a lot of value in having a custom dictionary file of your own, so the second thing we’ll look at is how to specify a dictionary file rather than a package.

Just a reminder, dictionary files are text files containing one word per line, and lines starting with a # symbol are ignored. This is the same format as the standard Unix words file.

As an example, let’s edit the rc file to use the standard Unix words file (/usr/share/dict/words on OS X) as our default word source. We do this by changing the name package to file inside default_dictionary, and changing the associated value from the package name to the path to our desired dictionary file. Below is our example rf file updated accordingly:

{
    "custom_presets" : {
        "DEFAULT" : {
            "description" : "A custom default preset to ovrride the standard default",
            "config" : {
                "padding_alphabet" : ["!", "?", "@", "&"],
                "separator_alphabet" : ["-", ":", ".", ","],
                "word_length_min" : 4,
                "word_length_max" : 8,
                "num_words" : 2,
                "separator_character" : "RANDOM",
                "padding_digits_before" : 2,
                "padding_digits_after" : 2,
                "padding_type" : "FIXED",
                "padding_character" : "RANDOM",
                "padding_characters_before" : 1,
                "padding_characters_after" : 1,
                "case_transform" : "ALTERNATE",
                "allow_accents" : 0
            }
        },
        "XKCD" : {
            "description" : "A preset that mimicks the famous cartoon exactly",
            "config" : {
                "word_length_min" : 4,
                "word_length_max" : 8,
                "num_words" : 4,
                "separator_character" : " ",
                "padding_digits_before" : 0,
                "padding_digits_after" : 0,
                "padding_type" : "NONE",
                "case_transform" : "LOWER",
                "allow_accents" : 0
            }
        }
    },
    "default_entropy_warnings" : "BLIND",
    "default_dictionary" : {
        "file" : "/usr/share/dict/words"
    }
}

Again, we can verify that things are working as expected with the --verbose option:

bart-iMac2013:~ bart$ hsxkpasswd --verbose 10
*NOTE* using hsxkpasswdrc file /Users/bart/.hsxkpasswdrc
*NOTE* using entropy warning level specified in hsxkpasswdrc file
*NOTE* using custom default config from hsxkpasswdrc file
*NOTE* using dictionary file from hsxkpasswdrc file
*NOTE* using default rng

*DICTIONARY*
Source: Crypt::HSXKPasswd::Dictionary::Basic (loaded from: the file(s) /usr/share/dict/words)
# words: 234252
# words of valid length: 87066 (37%)
Contains Accented Characters: NO

...

!30-ESSENIS-dogvane-11!
?45.undrying.MYRRH.79?
&02-ZONELIKE-annoyer-15&
@86-VARLETRY-notice-73@
@53,INCONNU,rocklike,43@
&54.CATLING.adipsy.11&
&28,yearday,PHENOLIC,84&
?65-BELLHOP-keyless-99?
!93:HANKY:coupelet:26!
!35.iguanian.MIAN.21!
bart-iMac2013:~ bart$

Final Thoughts

We have not covered everything .hsxkpasswdrc files can do in this short tutorial. For more details see the hsxkpasswd man page:

man hsxkpasswd

Using a .hsxkpasswdrc file, it’s possible to use the hsxkpasswd command with few, or no arguments, and still get a highly customised experience. This makes it very easy to customise hsxkpasswd, and generate passwords just the way you like them.