SoftwareDesign
/
csu3_am335x


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204
							<?xml version='1.0' encoding='iso-8859-1'?>
<!doctype html public '-//W3C//DTD XHTML 1.0 Strict//EN' 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd'>
<html xmlns='http://www.w3c.org/1999/xhtml' lang='en-us'>
	<head>
		<title>
			rkey.1
			</title>
		<meta http-equiv='content-type' content='text/html;iso-8859-1'/>
		<meta name='generator' content='motley-tools 1.9.4 13:40:33 Feb 18 2015'/>
		<meta name='author' content='cmaier@cmassoc.net'/>
		<meta name='robots' content='noindex,nofollow'/>
		<link href='toolkit.css' rel='stylesheet' type='text/css'/>
		</head>
	<body>
		<div class='headerlink'>
			[<a href='ptsctl.1.html' title=' ptsctl.1 '>PREV</a>]
			[<a href='toolkit.html' title=' Index '>HOME</a>]
			[<a href='sada.1.html' title=' sada.1 '>NEXT</a>]
			</div>
<pre>
rkey(1)                                      Qualcomm Atheros Open Powerline Toolkit                                     rkey(1)

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  cre‐
       ated  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 com‐
              mand 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  com‐
              mand line.

       -n count
              The number of keys to generate and print.  This program prints the specified number of distinct keys of the speci‐
              fied 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  sig‐
              nificant.   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 incre‐
       mented  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 &quot;My Company Name, Inc.&quot; &gt; 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 seed‐
       file 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 pro‐
       duce identical output.  From 12 to 24 character is a reasonable length but this is not a restriction.  If you  have  sev‐
       eral  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 tool‐
       kit 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 &lt;cmaier@qca.qualcomm.com&gt; ]

open-plc-utils-0.0.3                                        Mar 2014                                                     rkey(1)
</pre>
		<div class='footerlink'>
			[<a href='ptsctl.1.html' title=' ptsctl.1 '>PREV</a>]
			[<a href='toolkit.html' title=' Index '>HOME</a>]
			[<a href='sada.1.html' title=' sada.1 '>NEXT</a>]
			</div>
		</body>
	</html>