csu3_am335x/EVSE/GPL/plc-utils.LNX.2.1.20/source/key/hpavkeys.1

.TH hpavkeys 1 "Feb 2015" "plc-utils-2.1.8" "Qualcomm Atheros Powerline Toolkit"

.SH NAME
hpavkeys - HomePlug AV Key Generator

.SH SYNOPSIS
.B hpavkeys 
.RI [ options ] 
.IR file 
.RI [ file ] 
[...]

.SH DESCRIPTION
Convert blocks of phrases to encrypted \fBHomePlug AV\fR keys.
Phrases are read from one or more files, converted to either Device Access Keys, Networks Membership Keys or Network Identification Keys and printed on stdout.
By default, only keys are printed, one per line, but both keys and phrases can be printed, one pair per line.

.PP
This program is part of the Qualcomm Atheros Powerline Toolkit.
See the \fBAMP\fR man page for an overview and installation instructions.

.SH BACKGROUND
HomePlug AV technology uses 16-byte binary values, called "keys", for various purposes such as identity and security.
Three keys of interest to users are the Device Access Key (DAK), the Network Memership Key (NMK) and Network Identification Key (NID).
Their purpose is described in the HomePlug AV Specification.

.PP
The HomePlug AV Specification explains how to generate 16-byte binary DAK, NMK and NID values using the SHA-256 algorithm to hash user-supplied ASCII strings, called "pass phrases" in the specification.
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.
In all cases, the computed hash is then 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.

.PP
Keys can be any 16-byte binary value but binary values are difficult to remember.
HomePlug AV compliant applications, like the Qualcomm Atheros Device Manager, ask users for a pass phrase that is converted to a 16-byte binary value using a standard hashing algorithm.
In principle, no two phrases will produce the same key and it would be computationally expensive to derive the pass phrase given the key.
Although HomePlug AV software deals directly with the key, users need only remember the pass phrase in order to reproduce the key.

.SH OPTIONS

.TP
.RB - 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 \fB-M\fR and \fB-N\fR options previously specified on the command line.

.TP
.RB - 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.

.TP
-\fBL\fR \fIlevel\fR
Set security level.
The security level is encoded into the NID.
Level \fB0\fR enables pushbutton pairing.
Level \fB1\fR disables it.
This option has no effect unless a NID is computed.

.TP
.RB - 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 characters.
This option over-rides any \fB-D\fR or \fB-N\fR options previsously specified on the command line.

.TP
.RB - N
Uses HomePlug AV rules to compute Network Identification Keys (NID) from pass phrases read from file or stdin.
An NID is 7 bytes expressed as 14 hexadecimal digits.
This option over-rides any \fB-D\fR or \fB-M\fR options previously specified on the command line.

.TP
.RB - p
Print the password, or pass phrase, used to generate each key after each key on stdout.
One single space seperates the pass phrase from the key string.
The pass phrase consists of all subsequent characters, including spaces, appearing up to the end of the line.
Without this option, only the keys are printed.

.TP
.RB - q
Enable quiet mode which, for this application, has no effect.
This behavior has changed from earlier program versions.

.TP
.RB - v
Enable verbose mode which, for this application, prints the input phrase after each key.
This behavior has changed from earlier program versions.

.TP
.RB - ? ,-- help
Print program help summary on stdout.
This option takes precedence over other options on the command line.

.TP
.RB - ! ,-- 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.

.SH ARGUMENTS

.TP
.BR file
Any valid filename.
Each file on the command line is read in turn and output is written to stdout, much like the \fBcat\fR utility.
Input is read from the console when no filenames are specified.

.SH EXAMPLES
The following command reads file \fBexample.keys\fR and prints the SHA256 key for each phrase in that file.
An SHA256 key is 128 bits or 32 bytes expressed as 32 hexadecimal digits.
SHA256 keys are the default output when no key type is specified.
SHA256 is a public domain standard, not a HomePlug AV standard.

.PP
   # hpavkeys example.keys
   EA41A2383355FA7CA3B467DF0848A8EB9C41591BE53696C5F45DDAF621784F07
   4E76AD8354461437C04EF9B9B242540B6406D782FF2C3FB28AFDAB5B423F88FE
   71C480DF93D6AE2F1EFAD1447C66C9525E316218CF51FC8D9ED832F2DAF18B73
   7257DF11A035A49119FD881F20AA7FE88970F1A034E4BBBF2D50FAB0D0239F25
   FAC202F439E47EB5EACF6B9CC4151BF6B2B6E736A79BCAB0F589C63BCB78D16B

.PP
The following command reads file \fBexample.keys\fR and prints the DAK for each phrase in that file.
Input phrases are checked for HomePlugAV compliance and illegal phrases are reported then ignored.
A legal HomePlug pass phrase is 12 to 64 characters consisting of ASCII characters ' ' through '~'.
Essentially, these are the only characters that one can enter on a standard English keyboard.

.PP
   # hpavkeys -D example.keys
   F084B4E8F6069FF1300C9BDB812367FF
   7A6F36AC0DF1031CF04C5AF8DC0A70F0
   910B3D08D309BCE66452DBB40FDCB551
   309743236F0403C450A718494825FC02
   3C94A168BDF4BC19AA111BAB930171A5
   72D6E17E6756CD778F59FAFC6BF6D2B6
   914EB1D58AB66461A27794BFF648C04F
   7B7C094380A6E26F9F4618884C81DB63
   08AE750B07884E2C380BDCEDBC28D2C8
   F8EE1AC7F4234A3F724D21F8B837B547

.PP
The following example reads the same file as above but prints the NMK for each phrase, instead of the DAK.
The keys printed here have different values because the \fBHomePlug AV Specification\fR requires different hash algorithms for the DAK and NMK.
Don't mix them up.
.PP
   # hpavkeys -M example.keys
   B59319D7E8157BA001B018669CCEE30D
   F2B0C7F6C355981EBDD484FF49957420
   54CB8AB1235896E45E6B643C7BF11ADB
   75CD66973ED683E041F8AC37ACA88B58
   E20A0A69A3C6326C623202D3F42AF416
   1671D61F305E81BAF000D58AF09888D5
   05EFD9C9452BF8415D84BB1C415EE52A
   56F3C7F539D4F8F5EEC00E63F11A8DEC
   9718D29451897404DA2719CB80CA2ADA
   E5A7C020E0889A0265759D80DB3F9834
.PP
The following command reads the same file as above but prints the pass phrase because the \fB-v\fR option is specified.  Keys are printed as 32 hex digits then one space then the phrase. Spaces are significant within the phrase. Printed phrases start in column 34 and continue to the end of the line. 
.PP
   # hpavkeys -M example.keys -v
   B59319D7E8157BA001B018669CCEE30D HomePlugAV0123
   F2B0C7F6C355981EBDD484FF49957420 01234567890123456789
   54CB8AB1235896E45E6B643C7BF11ADB abcdefghijklmnopqrstuvwxyz
   75CD66973ED683E041F8AC37ACA88B58    I     love     my    dog   .
   E20A0A69A3C6326C623202D3F42AF416 A.B.C.D.E.F.G.H.I.J.K.L.M.N.O.P.Q.R.S.T.U.V.W.X.Y.Z
   1671D61F305E81BAF000D58AF09888D5 ~!@#$%^&*()_-`{}[]":;'\|<>./?
   05EFD9C9452BF8415D84BB1C415EE52A QWRT-YPSD-FGHJ-KLZX
   56F3C7F539D4F8F5EEC00E63F11A8DEC The quick brown fox jumped over the lazy dog.
   9718D29451897404DA2719CB80CA2ADA Super-Duper Electrosonic Frepitator SSEI43
   E5A7C020E0889A0265759D80DB3F9834 A = 3 * (5+2) - 1045

.SH TIPS&TRICKS
The following example illustrates an unusual case where passwords start with dash ("\fB-\fR").
Program \fBhpavkey\fR assumes that the dash is an option prefix which is incorrect in this case.
An error occurs because option \fB-H\fR is illegal.

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

.PP
One solution is to insert the keys verbatim in a password file, in this case \fBpassword.txt\fR, then run program \fBhpavkeys\fR on that file.

.PP
   # hpavkeys -vM password.txt
   80B74B14E92A739AD41ACDC377451D1B -HomePlugAV
   1A46BDE6F75209292FDFC4CCE4D19B4E -HomePlugAV123

.SH REFERENCES
See the \fBHomePlug AV Specification\fR for more information on encryption keys, pass phrases and hash algorithms used.
See standard \fBFIPS180-2 sec 5.3.2\fR for more information on SHA256 encoding.

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

.SH SEE ALSO
.BR hpavkey ( 1 ),
.BR keys ( 1 ),
.BR mac2pw ( 1 ),
.BR mac2pwd ( 1 ),
.BR rkey ( 1 )

.SH CREDITS
 Charles Maier <cmaier@qca.qualcomm.com>