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 ]

open-plc-utils-0.0.3                                Feb 2015                                             rkey(1)