NAME

       rkey - HomePlug AV Random Key Generator

SYNOPSIS

       rkey [options] file

DESCRIPTION

       Dynamically  generate distinct HomePlug AV compliant keys.  A new key is printed on stdout
       with each program invocation or iteration, unless this is suppressed.  Key computation  is
       seeded  using  a 64 ASCII character string stored in a user created seedfile.  The program
       automatically increments the seedfile string to preserve continuity and uniqueness  across
       program  invocations,  program  iterations,  console sessions, host reboots and production
       sites.

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

OPTIONS

       -D     Uses  HomePlug AV rules for computing a Device Access Key (DAK) from a pass phrase.
              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.

       -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  for computing a Network Membership Key (NMK) from a pass
              phrase.  An NMK is 16 bytes expressed as 32 hexadecimal digits.  This option  over-
              rides any -D or -N options previsously specified on the command line.

       -N     Uses HomePlug AV rules for computing a Network Identification Key (NID) from a pass
              phrase.  An NID is 7 bytes expressed as 14 hexadecimal digits.  This  option  over-
              rides any -D or -M options previously specified on the command line.

       -n count
              The number of keys to generate and print.  This program prints the specified number
              of distinct keys of the specified type, one key per line.  Normally, program output
              is  directed  to  a  file  or  a  pipe  when this option is used.  It is useful for
              creating a file of random keys.

       -o     Use the old seedfile string.  This option prevents the seedfile string  from  being
              incremented before a new key is computed.  This feature allows additional key types
              to be computed from the same seedfile string.

       -q     Enable quiet mode which, for this application, has no effect.

       -v     Enable verbose mode which, for this application, prints the pass  phrase  for  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

       seedfile
              The text file containing the seed string.  This file may be any length but only the
              first 64 characters are significant.  If it is less than 64 characters then it will
              be  extended to 64 characters after the first use.  The full 64 character string is
              incremented, character by character, right to left each time this program  is  run.
              The  seedfile  string is salted differently for each type of key requested and used
              to seed the SHA256 key engine.  One property of the SHA256 algorithm is that  small
              changes  in  the  seed  will produce radically different output having an extremely
              small chance of collision.

EXAMPLES

       The following example shows how to create a seedfile.  The seedfile acts as the  seed  for
       the SHA256 algorithm.  The seed is then salted (modified) differently for each type of key
       generated by this program.  The seedfile string is then incremented  and  re-written  each
       time  the  program  is  executed, unless behaviors is suppressed.  Initially, the seedfile
       must contain at least one character or an error will occur.

          # echo "My Company Name, Inc." > secret.key

       The following example prints an SHA256 key on stdout.  An SHA256 key is  256  bits  or  32
       bytes expressed as 64 hexadecimal digits.  An SHA256 key is the default output when no key
       type is specified.  SHA256 is a public domain standard, not a HomePlug AV standard.

          # rkey secret.key
          BFF0F6E3C83CE13829EA7F1F6D25042F4B05052E44C0B801EEA7CD6317F3622E

       The following command prints a new Device Access Key (DAK) on stdout  using  the  seedfile
       secret.key  as  the  seed.   The  key will be different each time this program is executed
       because the seedfile string is incremented each time.

          # rkey -D secret.key
          F084B4E8F6069FF1300C9BDB812367FF

       To observe the seedfile string, use option -v.  Notice that  the  seedfile  string  is  64
       characters long and that spaces are significant.

          # rkey -D secret.key -v
          89F96BC11480B0E1A37441397695E676        Qualcomm        Atheros,        Ocala        FL
       [8@Z

       The following command prints a new Network Membership Key (NMK) on stdout,  instead  of  a
       DAK,  using  the  seedfile  secret.key  as the seed.  Of course, one could specify another
       seedfile.

          # rkey -M secret.key
          B59319D7E8157BA001B018669CCEE30D

       The following command prints 10 random SHA256 keys on stdout.  SHA256  keys  were  printed
       because  no other type of key was specified.  Program output could have been directed to a
       file or a pipe for further processing.

          # rkey secret.key -n 10
          780AC153CD47AB01520B5B0246DE7B78584C0413393EDA4430773DED80DDF01A
          C7FF68DB206B1E98B8752CC95296692D45AB3DFA418F5CF5DD13479836FEDD4E
          127C8E27F4C8AC7DB27EC8F977968F64D950830B8D511B798FA5A20BE807A7E1
          79E00DBD57A0E22DCEE2C9CF29F3B7DBA95137BEDC8C76EBE3C32BFFA653D136
          AC9B8DA1B480EF0ECD7A734383DC1B0F3886D0959BAE77F30F1F16C069D2FE4A
          B1F57B211EE774B506106DEC90B7D18FE0328377FCFD9A4D523B632DFAEFF87A
          B1C1C746BDC3E45EBE65FC8D5C15D68F41E9981757024A25A4C3261A154BE6F2
          06E6CCEA8C919162D22CE2ADCB2DDFBDCBB876631CE73F48525EC27E435934E9
          F26C0636C6B2D51956D04AD73DE03BE6D112661040CB23DD74922C6E05EC7E6B
          A62219B0BBABA1DBC444574D0D73A52954847E6DB2BE44441C73E12B9F8EA6E7

       The following three commands use  the  -o  option  to  prevent  the  seedfile  from  being
       incremented  before  or  after  the key is computed.  Notice that a DAK is first generated
       then regenerated again.  The third command generates an NMK using the same seedfile  value
       used to compute the previous two keys.

          # rkey -D secret.key
          B12E8BA7B0FF31D107BE15E96EF65B86
          # rkey -oD secret.key
          B12E8BA7B0FF31D107BE15E96EF65B86
          # rkey -oM secret.key
          FAD7EA3713497F2E134299FF1118F6B0

       This  utterly useless example demonstrates how to generate 10 identical device access keys
       by suppressing the normal string increment between each key computation.

          # rkey -oDn 10 secret.key
          B12E8BA7B0FF31D107BE15E96EF65B86
          B12E8BA7B0FF31D107BE15E96EF65B86
          B12E8BA7B0FF31D107BE15E96EF65B86
          B12E8BA7B0FF31D107BE15E96EF65B86
          B12E8BA7B0FF31D107BE15E96EF65B86
          B12E8BA7B0FF31D107BE15E96EF65B86
          B12E8BA7B0FF31D107BE15E96EF65B86
          B12E8BA7B0FF31D107BE15E96EF65B86
          B12E8BA7B0FF31D107BE15E96EF65B86
          B12E8BA7B0FF31D107BE15E96EF65B86

       This example demonstrates how to assign distinct keys to script variables or  insert  them
       on  a  command  line using this program.  Read the GNU bash manual for more information on
       shell scripting.  See the modpib man page for an explanation of program options shown.

          # DAK=$(rkey -D secret.key)
          # NMK=$(rkey -M secret.key)
          # echo DAK=${DAK} NMK=${NMK}
          # modpib -D $(rkey -D secret.key) -N ${NMK}

RECOMMENDATIONS

       The seedfile is critical to the continuity and  uniqueness  of  generated  keys.   The  64
       character  string  stored in the seedfile is incremented, character by character, right to
       left, with each file access unless that behavior is suppressed using the -o  option.   The
       SHA256  algorithm  generates radially different output given minor changes in this string.
       The key space is huge and the probability of collision is statistically small.

       Be aware that two seedfiles containing the same start string will generate  the  same  key
       sequence.   To  minimize  the chance of duplicate key values across production lines, each
       production line should use seedfiles having different start strings.  The  length  of  the
       start  string  is not important but it should be different for each production line.  If a
       seedfile is lost, merely replace it with another one, as though you  are  opening  another
       production line.

       Mathematically,  the  shorter  the  start string the longer it will take for two different
       seedfiles to coincidentally produce identical output.   From  12  to  24  character  is  a
       reasonable  length  but  this is not a restriction.  If you have several production lines,
       you may want to maintain a record of the start strings used on each line  in  case  a  new
       seedfile must be created.

REFERENCES

       See  the  HomePlug  AV Specification for more information on encryption keys, pass phrases
       and hash algorithms used and 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

       hpavkey(1), hpavkeys(1), keys(1), mac2pw(1), mac2pwd(1)

CREDITS

        Charles Maier ]