Updated documentation

mqv.h

@@ -30,41 +30,104 @@ public:
 	typedef typename GroupParameters::Element Element;
 	typedef MQV_Domain<GROUP_PARAMETERS, COFACTOR_OPTION> Domain;
 
+	//! \brief Construct a MQV domain
 	MQV_Domain() {}
 
+	//! \brief Construct a MQV domain
+	//! \param params group parameters and options
 	MQV_Domain(const GroupParameters &params)
 		: m_groupParameters(params) {}
 
+	//! \brief Construct a MQV domain
+	//! \param bt BufferedTransformation with group parameters and options
 	MQV_Domain(BufferedTransformation &bt)
 		{m_groupParameters.BERDecode(bt);}
 
+	//! \brief Construct a Diffie-Hellman domain
+	//! \tparam T1 template parameter used as a constructor parameter
+	//! \tparam T2 template parameter used as a constructor parameter
+	//! \param v1 first parameter 
+	//! \param v2 second parameter
+	//! \details v1 and v2 are passed directly to the GROUP_PARAMETERS object.
 	template <class T1, class T2>
 	MQV_Domain(T1 v1, T2 v2)
 		{m_groupParameters.Initialize(v1, v2);}
-	
+
+	//! \brief Construct a Diffie-Hellman domain
+	//! \tparam T1 template parameter used as a constructor parameter
+	//! \tparam T2 template parameter used as a constructor parameter
+	//! \tparam T3 template parameter used as a constructor parameter
+	//! \param v1 first parameter 
+	//! \param v2 second parameter
+	//! \param v3 third parameter
+	//! \details v1, v2 and v3 are passed directly to the GROUP_PARAMETERS object.
 	template <class T1, class T2, class T3>
 	MQV_Domain(T1 v1, T2 v2, T3 v3)
 		{m_groupParameters.Initialize(v1, v2, v3);}
-	
+
+	//! \brief Construct a Diffie-Hellman domain
+	//! \tparam T1 template parameter used as a constructor parameter
+	//! \tparam T2 template parameter used as a constructor parameter
+	//! \tparam T3 template parameter used as a constructor parameter
+	//! \tparam T4 template parameter used as a constructor parameter
+	//! \param v1 first parameter 
+	//! \param v2 second parameter
+	//! \param v3 third parameter
+	//! \param v4 third parameter
+	//! \details v1, v2, v3 and v4 are passed directly to the GROUP_PARAMETERS object.
 	template <class T1, class T2, class T3, class T4>
 	MQV_Domain(T1 v1, T2 v2, T3 v3, T4 v4)
 		{m_groupParameters.Initialize(v1, v2, v3, v4);}
 
+	//! \brief Retrieves the group parameters for this domain
+	//! \return the group parameters for this domain as a const reference
 	const GroupParameters & GetGroupParameters() const {return m_groupParameters;}
+
+	//! \brief Retrieves the group parameters for this domain
+	//! \return the group parameters for this domain as a non-const reference
 	GroupParameters & AccessGroupParameters() {return m_groupParameters;}
 
+	//! \brief Retrieves the crypto parameters for this domain
+	//! \return the crypto parameters for this domain as a non-const reference
 	CryptoParameters & AccessCryptoParameters() {return AccessAbstractGroupParameters();}
 
+	//! \brief Provides the size of the agreed value
+	//! \return size of agreed value produced  in this domain
+	//! \details The length is calculated using <tt>GetEncodedElementSize(false)</tt>, which means the
+	//!   element is encoded in a non-reversible format. A non-reversible format means its a raw byte array,
+	//!   and it lacks presentation format like an ASN.1 BIT_STRING or OCTET_STRING.
 	unsigned int AgreedValueLength() const {return GetAbstractGroupParameters().GetEncodedElementSize(false);}
+
+	//! \brief Provides the size of the static private key
+	//! \return size of static private keys in this domain
+	//! \details The length is calculated using the byte count of the subgroup order.
 	unsigned int StaticPrivateKeyLength() const {return GetAbstractGroupParameters().GetSubgroupOrder().ByteCount();}
+
+	//! \brief Provides the size of the static public key
+	//! \return size of static public keys in this domain
+	//! \details The length is calculated using <tt>GetEncodedElementSize(true)</tt>, which means the
+	//!   element is encoded in a reversible format. A reversible format means it has a presentation format,
+	//!   and its an ANS.1 encoded element or point.
 	unsigned int StaticPublicKeyLength() const {return GetAbstractGroupParameters().GetEncodedElementSize(true);}
 
+	//! \brief Generate static private key in this domain
+	//! \param rng a RandomNumberGenerator derived class
+	//! \param privateKey a byte buffer for the generated private key in this domain
+	//! \details The private key is a random scalar used as an exponent in the range <tt>[1,MaxExponent()]</tt>.
+	//! \pre <tt>COUNTOF(privateKey) == PrivateStaticKeyLength()</tt>
 	void GenerateStaticPrivateKey(RandomNumberGenerator &rng, byte *privateKey) const
 	{
 		Integer x(rng, Integer::One(), GetAbstractGroupParameters().GetMaxExponent());
 		x.Encode(privateKey, StaticPrivateKeyLength());
 	}
 
+	//! \brief Generate a static public key from a private key in this domain
+	//! \param rng a RandomNumberGenerator derived class
+	//! \param privateKey a byte buffer with the previously generated private key
+	//! \param publicKey a byte buffer for the generated public key in this domain
+	//! \details The public key is an element or point on the curve, and its stored in a revrsible format.
+	//!    A reversible format means it has a presentation format, and its an ANS.1 encoded element or point.
+	//! \pre <tt>COUNTOF(publicKey) == PublicStaticKeyLength()</tt>
 	void GenerateStaticPublicKey(RandomNumberGenerator &rng, const byte *privateKey, byte *publicKey) const
 	{
 		CRYPTOPP_UNUSED(rng);