csu3_am335x/EVSE/GPL/plc-utils.LNX.2.1.20/source/docbook2/oHPAVKey.xml

<chapter id='oHPAVKey'>
	<title>
		Class oHPAVKey
		</title>
	<section id="oHPAVKey-class" >
		<title>
			Introduction
			</title>
		<para>
			This class implements a HomePlug AV compliant encryption key generator. It can be used to generate a Device Access Key (<acronym>DAK</acronym>),  Network Management Key (<acronym>NMK</acronym>) or Network Identifier (<acronym>NID</acronym>) from user supplied passwords or pass phrases. It can also be used to verify that passwords and pass phrases conform to recommendations outlined in the <citetitle>HomePlug AV Specification</citetitle>, although such conformace is optional.
			</para>
		<para>
			This class is declared in <ulink url='oHPAVKey.hpp.html'>oHPAVKey.hpp</ulink> and defined in <ulink url='oHPAVKey.cpp.html'>oHPAVKey.cpp</ulink>.
			</para>
		<section id="oHPAVKey-inheritance">
			<title>
				Inheritance
				</title>
			<para>
				This class inherits the <link linkend='oflagword'>oflagword</link> class to implement the validation flagword. All public flagword properties and methods are accessible.
				</para>
			</section>
		<section id="oHPAVKey-dependence">
			<title>
				Dependence
				</title>
			<para>
				None.
				</para>
			</section>
		</section>
	<section id="oHPAVKey-properties">
		<title>
			Properties
			</title>
		<para>
			None.
			</para>
		<section id="oHPAVKey-DAKLength">
			<title>
				oHPAVKey::DAKLength
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>unsigned <function>DAKLength</function></funcdef>
   					<paramdef><parameter></parameter></paramdef>
					</funcprototype>
				</funcsynopsis>
			<para>
				The length of an Device Access Key (<acronym>DAK</acronym>) in bytes as defined in the <citetitle>HomePlug AV Specification</citetitle>. This property is implemented as a true constant. Parenthesis are not used when referencing it.
				</para>
			</section>
		<section id="oHPAVKey-DigestLength">
			<title>
				oHPAVKey::DigestLength
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>unsigned <function>DigestLength</function></funcdef>
   					<paramdef><parameter></parameter></paramdef>
					</funcprototype>
				</funcsynopsis>
			<para>
				The SHA256 digest length in bytes. All HomePlug AV keys are first computed as an SHA256 digest but only a portion of the digest is used as the key. The portion used depends on the key type. HomePlug AV keys will never exceed this length. This property is implemented as a true constant. Parenthesis are not used when referencing it.
				</para>
			</section>
		<section id="oHPAVKey-MaxCharValue">
			<title>
				oHPAVKey::MaxCharValue
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>unsigned <function>MaxCharValue</function></funcdef>
   					<paramdef><parameter></parameter></paramdef>
					</funcprototype>
				</funcsynopsis>
			<para>
				The maximum character value permitted in a HomePlug AV compliant pass phrase, as defined in the <citetitle>HomePlug AV Specification</citetitle>. Key encryption will work given any byte value but this constant is provided for cases where HomePlug AV compliance is important. Class method <link linkend='oHPAVKey-IllegalCharValue'>IllegalCharValue</link> uses this constant internally when validating pass phrases. This property is implemented as a true constant. Parenthesis are not used when referencing it.
				</para>
			</section>
		<section id="oHPAVKey-MaxPhraseLength">
			<title>
				oHPAVKey::MaxPhraseLength
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>unsigned <function>MaxPhraseLength</function></funcdef>
   					<paramdef><parameter></parameter></paramdef>
					</funcprototype>
				</funcsynopsis>
			<para>
				The maximum length of a HomePlug AV compliant pass phrase,  as defined in the <citetitle>HomePlug AV Specification</citetitle>. Key encryption will work given pass phrases of any length but this constant is provided for cases where HomePlug AV compliance is important. Class method <link linkend='oHPAVKey-IllegalPassPhrase'>IllegalPassPhrase</link> uses this constant internally when validating pass phrases. This property is implemented as a true constant. Parenthesis are not used when referencing it.
				</para>
			</section>
		<section id="oHPAVKey-MinCharValue">
			<title>
				oHPAVKey::MinCharValue
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>unsigned <function>MinCharValue</function></funcdef>
   					<paramdef><parameter></parameter></paramdef>
					</funcprototype>
				</funcsynopsis>
			<para>
				The minimum character value permitted in a HomePlug AV compliant pass phrase, as defined in the <citetitle>HomePlug AV Specification</citetitle>. Key encryption will work given any byte value but this constant is provided for cases where HomePlug AV compliance is important. Class method <link linkend='oHPAVKey-IllegalCharValue'>IllegalCharValue</link> uses this constant internally when validating pass phrases. This property is implemented as a true constant. Parenthesis are not used when referencing it.
				</para>
			</section>
		<section id="oHPAVKey-MinPhraseLength">
			<title>
				oHPAVKey::MinPhraseLength
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>unsigned <function>MinPhraseLength</function></funcdef>
   					<paramdef><parameter></parameter></paramdef>
					</funcprototype>
				</funcsynopsis>
			<para>
				The minimum length of a HomePlug AV compliant pass phrase, as defined in the <citetitle>HomePlug AV Specification</citetitle>. Key encryption will work given pass phrases of any length but this constant is provided for cases where HomePlug AV compliance is important. Class method <link linkend='oHPAVKey-IllegalPassPhrase'>IllegalPassPhrase</link> uses this constant internally when validating pass phrases.This property is implemented as a true constant. Parenthesis are not used when referencing it.
				</para>
			</section>
		<section id="oHPAVKey-NIDLength">
			<title>
				oHPAVKey::NIDLength
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>unsigned <function>NIDLength</function></funcdef>
   					<paramdef><parameter></parameter></paramdef>
					</funcprototype>
				</funcsynopsis>
			<para>
				The length of a Network Identifier (<acronym>NID</acronym>) in bytes as defined in the <citetitle>HomePlug AV Specification</citetitle>. This property is implemented as a true constant. Parenthesis are not used when referencing it.
				</para>
			</section>
		<section id="oHPAVKey-NMKLength">
			<title>
				oHPAVKey::NMKLength
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>unsigned <function>NMKLength</function></funcdef>
   					<paramdef><parameter></parameter></paramdef>
					</funcprototype>
				</funcsynopsis>
			<para>
				The length of a Network Membership Key (<acronym>NMK</acronym>) in bytes as defined in the <citetitle>HomePlug AV Specification</citetitle>. This property is implemented as a true constant. Parenthesis are not used when referencing it.
				</para>
			</section>
		</section>
	<section id="oHPAVKey-methods">
		<title>
			Methods
			</title>
		<para>
			</para>
		<section id="oHPAVKey-ComputeDAK">
			<title>
				oHPAVKey::ComputeDAK
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>oHPAVKey &amp; <function>ComputeDAK</function></funcdef>
					<paramdef>char const * <parameter>phrase</parameter></paramdef>
 					</funcprototype>
				</funcsynopsis>
			<para>
				Compute the HomePlug AV compliant Device Access Key (<acronym>DAK</acronym>) from the <constant>NUL</constant> terminated pass phrase string. Return the object instance reference. Use method <link linkend='oHPAVKey-ExportKey'>ExportKey</link> to obtain the key portion of the computed digest. The string argument is called the <quote>Device Password</quote> but the encrypted version is called the <quote>Device Access Key</quote>. 
				</para>
			<para>
				This method does not enforce HomePlug AV pass phrase rules. Consequently, the pass phrase may be any length and contain any non-<constant>NUL</constant> character value. Use method <link linkend='oHPAVKey-IllegalPassPhrase'>IllegalPassPhrase</link> to validate the string argument before calling this method, if HomePlug AV pass phrase compliance is important.
				</para>
			</section>
		<section id="oHPAVKey-ComputeNMK">
			<title>
				oHPAVKey::ComputeNMK
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>oHPAVKey &amp; <function>ComputeNMK</function></funcdef>
					<paramdef>char const * <parameter>phrase</parameter></paramdef>
 					</funcprototype>
				</funcsynopsis>
			<para>
				Compute the HomePlug AV compliant Network Membership Key (<acronym>NMK</acronym>) from the <constant>NUL</constant> terminated pass phrase string. Return the object instance reference. Use method <link linkend='oHPAVKey-ExportKey'>ExportKey</link> to obtain the key portion of the computed digest. The string argument is called the <quote>Network Password</quote> but the encrypted version is called the <quote>Network Membership Key</quote>. 
				</para>
			<para>
				This method does not enforce HomePlug AV pass phrase rules. Consequently, the pass phrase may be any length and contain any non-<constant>NUL</constant> character value. Use method <link linkend='oHPAVKey-IllegalPassPhrase'>IllegalPassPhrase</link> to validate the string argument before calling this method, if HomePlug AV pass phrase compliance is important.
				</para>
			</section>
		<section id="oHPAVKey-ComputeNID">
			<title>
				oHPAVKey::ComputeNID
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>oHPAVKey &amp; <function>ComputeNID</function></funcdef>
					<paramdef> byte <parameter>level</parameter></paramdef>
 					</funcprototype>
				</funcsynopsis>
			<para>
				Compute the HomePlug AV compliant preferred Network Identifier (<acronym>NID</acronym>) from the encrypted Network Membership Key. Return the object instance reference. This method assumes that an <varname>NMK</varname> has just been computed using method <link linkend='oHPAVKey-ComputeNMK'>ComputeNMK</link>. Use method <link linkend='oHPAVKey-ExportKey'>ExportKey</link> to obtain the key portion of the digest.
				</para>
			<para>
				The preferred <acronym>NID</acronym> is derived by encrypting the <acronym>NMK</acronym>. This means that a new preferred <acronym>NID</acronym> should be computed whenever the <acronym>NMK</acronym> is computed. 
				</para>
			</section>
		<section id="oHPAVKey-ExportKey">
			<title>
				oHPAVKey::ExportKey
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>oHPAVKey &amp; <function>ExportKey</function></funcdef>
					<paramdef>void const * <parameter>memory</parameter></paramdef>
 					</funcprototype>
				</funcsynopsis>
			<para>
				Copy the computed digest to external memory. The computed digest is <link linkend='oHPAVKey-DigestLength'>DigestLength</link> bytes in length, but fewer bytes may be copied, depending on the key type that was last computed. Only <link linkend='oHPAVKey-DAKLength'>DAKLength</link> bytes are copied for a <acronym>DAK</acronym>. Only <link linkend='oHPAVKey-NMKLength'>NMKLength</link> bytes are copied for an <acronym>NMK</acronym>. Only <link linkend='oHPAVKey-NIDLength'>NIDLength</link> bytes are copied for a <acronym>NID</acronym>.
				</para>
			</section>
		<section id="oHPAVKey-IllegalCharValue">
			<title>
				oHPAVKey::IllegalCharValue
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>bool <function>IllegalCharValue</function></funcdef>
					<paramdef>unsigned <parameter>character</parameter></paramdef>
 					</funcprototype>
				</funcsynopsis>
			<para>
				Return <constant>true</constant> if the character argument <varname>character</varname> exceeds the range <link linkend='oHPAVKey-MinCharValue'>MinCharValue</link> through <link linkend='oHPAVKey-MaxCharValue'>MaxCharValue</link>. 
				</para>
			</section>
		<section id="oHPAVKey-IllegalPassPhrase">
			<title>
				oHPAVKey::IllegalPassPhrase
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>bool <function>IllegalPassPhrase</function></funcdef>
					<paramdef>char const * <parameter>phrase</parameter></paramdef>
 					</funcprototype>
				</funcsynopsis>
			<para>
				Return <constant>true</constant> if character string argument <varname>phrase</varname> either contains illegal characters, as determined by method <link linkend='oHPAVKey-IllegalCharValue'>IllegalCharValue</link>, or exceeds the lengths <link linkend='oHPAVKey-MinPhraseLength'>MinPhraseLength</link> through <link linkend='oHPAVKey-MaxPhraseLength'>MaxPhraseLength</link>.  
				</para>
			</section>
		<section id="oHPAVKey-Print">
			<title>
				oHPAVKey::Print
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>oHPAVKey &amp; <function>Print</function></funcdef>
					<paramdef>char const * <parameter>phrase</parameter></paramdef>
 					</funcprototype>
				</funcsynopsis>
			<para>
				Print the last computed key on stdout. If argument <varname>phrase</varname> is not <constant>NULL</constant> and is not empty then append one space and print the phrase. Terminate output with a newline.
				</para>
			</section>
		</section>
	<section id="oHPAVKey-examples">
		<title>
			Examples
			</title>
		<example>
			<title>
				Encrypt a Device Password
				</title>
<programlisting>
oHPAVKey <varname>encoder</varname>; 
char * <varname>password</varname> = "HelloWorld!"; 
byte <varname>buffer</varname> [<varname>encoder</varname>.<constant>DigestLength</constant>]
<varname>encoder</varname>.<function>ComputeDAK</function> (<varname>password</varname>); 
<varname>encoder</varname>.<function>ExportKey</function> (<varname>buffer</varname>)
</programlisting>
			<para>
				This example instantiates an <varname>encoder</varname>, defines the <varname>password</varname> to be encrypted and allocates a <varname>buffer</varname> having <link linkend='oHPAVKey-DigestLength'>DigestLength</link> bytes. Class method <link linkend='oHPAVKey-ComputeDAK'>ComputeDAK</link> encrypts the <varname>password</varname> using <acronym>DAK</acronym> encryption rules. Method <link linkend='oHPAVKey-ExportKey'>ExportKey</link> copies the encrypted password into <varname>buffer</varname>. Since <varname>buffer</varname> contains a <acronym>DAK</acronym>, only the first <link linkend='oHPAVKey-DAKLength'>DAKLength</link> bytes are relevant.
				</para>
			</example>
		<example>
			<title>
				Encrypt a Network Password
				</title>
<programlisting>
oHPAVKey <varname>encoder</varname>; 
char * <varname>password</varname> = "Super Computers Inc."; 
byte <varname>buffer</varname> [<varname>encoder</varname>.<constant>DigestLength</constant>]
<varname>encoder</varname>.<function>ComputeNMK</function> (<varname>password</varname>); 
<varname>encoder</varname>.<function>ExportKey</function> (<varname>buffer</varname>)
<varname>encoder</varname>.<function>ComputeNID</function> (<varname>1</varname>); 
<varname>encoder</varname>.<function>ExportKey</function> (<varname>buffer</varname>)
</programlisting>
			<para>
				This example instantiates an <varname>encoder</varname>, defines the <varname>password</varname> to be encrypted and allocates a <varname>buffer</varname> having <link linkend='oHPAVKey-DigestLength'>DigestLength</link> bytes,  as above. Class method <link linkend='oHPAVKey-ComputeNMK'>ComputeNMK</link> encrypts the <varname>password</varname> using <acronym>NMK</acronym> encryption rules. Method <link linkend='oHPAVKey-ExportKey'>ExportKey</link> copies the encrypted password into <varname>buffer</varname>. Since <varname>buffer</varname> now contains an <acronym>NMK</acronym>, only the first <link linkend='oHPAVKey-NMKLength'>NMKLength</link> bytes are relevant.
				</para>
			<para>
				The example then computes an <acronym>NID</acronym> from the <acronym>NMK</acronym> that was just computed. Class methods ComputeNID encrypts the <acronym>NMK</acronym> and encodes it with security level <constant>1</constant>. Method <link linkend='oHPAVKey-ExportKey'>ExportKey</link> copies the encrypted <acronym>NMK</acronym> into <varname>buffer</varname>. Since <varname>buffer</varname> now contains a <acronym>NID</acronym>, only the first <link linkend='oHPAVKey-NIDLength'>NIDLength</link> bytes are relevant.
				</para>
			</example>
		</section>
	</chapter>