hpavkey(1)

💖 hpavkey — HomePlug AV Key Generator 💖

okay so bestie, you found hpavkey(1), and honestly? she's a whole vibe. this is the key generator from the Qualcomm Atheros Open Powerline Toolkit, and she turns your cute little pass phrases into encrypted HomePlug AV keys. no cap. let's get into it 🫶

---

✨ SYNOPSIS ✨

hpavkey [options] phrase [phrase] [...]

---

🌸 DESCRIPTION 🌸

She converts one or more phrases into encrypted HomePlug AV keys. The phrases come in as command line arguments, get converted into either Device Access Keys, Network Membership Keys or Network Identification Keys, and then get printed on stdout. By default you only get the keys, one key per line — but if you want, you can print keys and phrases together, one pair per line. iconic behaviour, truly 💅

This program is part of the Qualcomm Atheros Powerline Toolkit. Peep the AMP man page for the overview and the install instructions, iykyk.

---

🧚 BACKGROUND 🧚

HomePlug AV technology uses special 16-byte binary values called "keys" for lots of stuff — identity, security, the whole thing. Three keys you actually care about are the Device Access Key (DAK), the Network Memership Key (NMK) and the Network Identification Key (NID). What each one is for is described in the HomePlug AV Specification, bestie, go read it.

The HomePlug AV Specification explains how to generate those 16-byte binary DAK, NMK and NID values using the SHA-256 algorithm to hash user-supplied ASCII strings — the spec calls them "pass phrases". HomePlug AV compliant pass phrases have from 12 to 64 7-bit ASCII character values in the range 0x20 to 0x7F. In some cases, a specified 8-byte salt is added to the pass phrase before computing the 32-byte hash value. And in all cases, the computed hash then gets rehashed a specified number of times to produce the final 32-byte value. The HomePlug AV key is the lower 16 bytes of that value. periodt.

Keys can technically be any 16-byte binary value, but bestie… binary values are so hard to remember. 😭 HomePlug AV applications — like the Qualcomm Atheros Windows Device Manager — will just ask the user for a pass phrase and convert it to a 16-byte binary value using a known hashing algorithm. In principle, no two phrases will product the same key, and deriving the pass phrase from the key would be computationally expensive. So even though HomePlug AV software deals directly with the key, users only need to remember the pass phrase to reproduce the key. that's the whole magic trick ✨

---

💅 OPTIONS 💅

• -D — Uses HomePlug AV rules to compute Device Access Keys (DAK) from pass phrases read from file or stdin. A DAK is 16 bytes expressed as 32 hexadecimal digits. This option over-rides any -M and -N options previously specified on the command line.
• -e — Enforce HomePlug AV length and content rules for phrases. Non-compliant phrases are reported and ignored. Compliant phrases are 12 to 64 7-bit ASCII characters in the range 0x20 (SP) through 0x7F (DEL). Essentially, this includes any character that can be typed on a standard US or UK keyboard, excluding horizontal tab (HT). ⚠️ Be aware that some command shells intercept and act on special characters instead of passing them to the application. In such cases, you may need to include meta characters.
• -L level — Set security level. The security level is encoded into the NID. Level 0 enables pushbutton pairing. Level 1 disables it. This option has no effect unless a NID is computed.
• -M — Uses HomePlug AV rules to compute Network Membership Keys (NMK) from pass phrases read from file or stdin. An NMK is 16 bytes expressed as 32 hexadecimal digits. This option over-rides any -D or -N options previously specified on the command line.
• -N — Uses HomePlug AV rules to compute Network Identification Keys (NID) from pass phrases read from file or stdin. A NID is 7 bytes expressed as 14 hexadecimal digits. This option over-rides any -D or -M options previously specified on the command line.
• -q — Enable quiet mode which, for this application, has no effect. 💀 (yes really, it does nothing here)
• -v — Enable verbose mode which, for this application, prints the pass phrase after each key.
• -?, --help — Print program help summary on stdout. This option takes precedence over other options on the command line.
• -!, --version — Print program version information on stdout. This option takes precedence over other options on the command line. Use this option when sending screen dumps to Atheros Technical Support so that they know exactly which version of the Linux Toolkit you are using. 📸

---

🦋 ARGUMENTS 🦋

• phrase — A pass phrase to be converted to a DAK, NMK or NID. More than one pass phrase can be entered on the command line. Each phrase will be converted to the same type of key and printed in the order specified. Phrases that contain quotes or special delimiters should be enclosed in quotes or apostrophes. By default, phrases can be any length and contain any ASCII chracter except ASCII NUL. Use option -e to enforce HomePlug AV password character and length rules.

---

🌈 EXAMPLES 🌈

okay this is the fun part, let's go 🎀

The following example prints the ordinary SHA256 key for the phrase, "HomePlugAV0123", entered on the command line. An SHA key is 256 bits or 32 bytes expressed as 64 hexadecimal characters. SHA256 keys are the default output when no key type is specified. SHA256 is a public domain standard, not a HomePlug AV standard.

# hpavkey HomePlugAV0123
EA41A2383355FA7CA3B467DF0848A8EB9C41591BE53696C5F45DDAF621784F07

The following example prints the DAK for the phrase, "HomePlugAV0123", entered on the command line.

# hpavkey -D HomePlugAV0123
F084B4E8F6069FF1300C9BDB812367FF

The following command prints the NMK, instead of the DAK, for the phrase entered on the command line. The ouput is different because the DAK and NMK are computed differently given the same pass phrase. 🤯

# hpavkey -M HomePlugAV0123
B59319D7E8157BA001B018669CCEE30D

The following command prints the NMK for each phrase entered on the command line. Notice that spaces are legal and significant. Phrases containing spaces must be enclosed in quotes.

# hpavkey -M HomePlugAV0123 "The quick brown fox jumped over the lazy dog."
B59319D7E8157BA001B018669CCEE30D
56F3C7F539D4F8F5EEC00E63F11A8DEC

The following command prints the NMK and pass phrase for each pass phrase entered on the command line because the verbose option is specified.

# hpavkey -v -M HomePlugAV0123 "The quick brown fox jumped over the lazy dog."
B59319D7E8157BA001B018669CCEE30D HomePlugAV0123
56F3C7F539D4F8F5EEC00E63F11A8DEC The quick brown fox jumped over the lazy dog.

hpavkey can be used to compute a key and pass it to another program as an argument. The modpib command shown below will edit file example.pib by replacing the DAK. The -D option expects a hexadecimal key so we can supply one from the phrase "HomePlugAV0123".

# modpid -D $(hpavkey -D HomePlugAV0123) example.pib

---

🔥 TIPS&TRICKS 🔥

The following example illustrates an unusual case where the passwords start with dash ("-"). The program assumes that the dash is an option prefix which is incorrect in this case. An error occurs because option -H is illegal.

# hpavkey -vM -HomePlugAV -HomePlugAV123
hpavkey: Operation canceled: Option 'H' has no meaning

one solution is to insert a double-dash ("--") on the command line to indicate that no further options appear on the command line. We include option -v to display the passwords on output.

# hpavkey -vM -- -HomePlugAV -HomePlugAV123
80B74B14E92A739AD41ACDC377451D1B -HomePlugAV
1A46BDE6F75209292FDFC4CCE4D19B4E -HomePlugAV123

See the hpavkeys man page for yet another solution to this problem. 👑

---

📚 REFERENCES 📚

See the HomePlug AV Specification for more information on encryption keys, pass phrases and hash algorithms used. See standard FIPS180-2 sec 5.3.2 for more information on SHA256 encoding.

---

⚠️ DISCLAIMER ⚠️

Qualcomm Atheros reserves the right to modify program names, functionality, input format or output format in future toolkit releases without any obligation to notify or compensate toolkit users.

---

👀 SEE ALSO 👀

hpavkeys(1), mac2pw(1), mac2pwd(1), rkey(1)

---

🌟 CREDITS 🌟

Charles Maier

---

and that's the whole page bestie!! 🫶 this was hpavkey(1) from open-plc-utils-0.0.3, dated Feb 2015. she's a lil vintage but she ate, fr fr. go generate some keys 💖✨