Updated documentation (Issue 328)

1 files changed, 106 insertions, 4 deletions

diff --git a/dh.h b/dh.h
index 9af0bc10..ac13ca8c 100644
--- a/dh.h
+++ b/dh.h
@@ -47,7 +47,7 @@ public:
 	DH_Domain(BufferedTransformation &bt)

 		{m_groupParameters.BERDecode(bt);}

 

-	//! \brief Construct a Diffie-Hellman domain

+	//! \brief Create a Diffie-Hellman domain

 	//! \tparam T2 template parameter used as a constructor parameter

 	//! \param v1 RandomNumberGenerator derived class

 	//! \param v2 second parameter

@@ -56,7 +56,7 @@ public:
 	DH_Domain(RandomNumberGenerator &v1, const T2 &v2)

 		{m_groupParameters.Initialize(v1, v2);}

 

-	//! \brief Construct a Diffie-Hellman domain

+	//! \brief Create a Diffie-Hellman domain

 	//! \tparam T2 template parameter used as a constructor parameter

 	//! \tparam T3 template parameter used as a constructor parameter

 	//! \param v1 RandomNumberGenerator derived class

@@ -67,7 +67,7 @@ public:
 	DH_Domain(RandomNumberGenerator &v1, const T2 &v2, const T3 &v3)

 		{m_groupParameters.Initialize(v1, v2, v3);}

 

-	//! \brief Construct a Diffie-Hellman domain

+	//! \brief Create a Diffie-Hellman domain

 	//! \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

@@ -168,8 +168,110 @@ private:
 

 CRYPTOPP_DLL_TEMPLATE_CLASS DH_Domain<DL_GroupParameters_GFP_DefaultSafePrime>;

 

-//! <a href="http://www.weidai.com/scan-mirror/ka.html#DH">Diffie-Hellman</a> in GF(p) with key validation

+//! \brief Diffie-Hellman in GF(p)

+//! \details DH() class is a typedef of DH_Domain(). The documentation that follows

+//!   does not exist. Rather the documentation was created in response to <a href="https://github.com/weidai11/cryptopp/issues/328">Issue

+//!   328, Diffie-Hellman example code not compiling</a>.

+//! \details Generally speaking, a DH() object is ephemeral and is intended to execute one instance of the Diffie-Hellman protocol. The

+//!   private and public key parts are not intended to be set or persisted. Rather, a new set of domain parameters are generated each

+//!   time an object is created.

+//! \details Once a DH() object is created, once can retrieve the ephemeral public key for the other party with code similar to the

+//!   following.

+//! <pre>  AutoSeededRandomPool prng;

+//!   Integer p, q, g;

+//!   PrimeAndGenerator pg;

+//!

+//!   pg.Generate(1, prng, 512, 511);

+//!   p = pg.Prime();

+//!   q = pg.SubPrime();

+//!   g = pg.Generator();

+//!

+//!   DH dh(p, q, g);

+//!   SecByteBlock t1(dh.PrivateKeyLength()), t2(dh.PublicKeyLength());

+//!   dh.GenerateKeyPair(prng, t1, t2);

+//!   Integer k1(t1, t1.size()), k2(t2, t2.size());

+//!

+//!   cout << "Private key:\n";

+//!   cout << std::hex << k1 << endl;

+//!

+//!   cout << "Public key:\n";

+//!   cout << std::hex << k2 << endl;

+//! </pre>

+//! \details Output of the program above will be similar to the following.

+//! <pre>  $ ./cryptest.exe

+//!   Private key:

+//!   72b45a42371545e9d4880f48589aefh

+//!   Public key:

+//!   45fdb13f97b1840626f0250cec1dba4a23b894100b51fb5d2dd13693d789948f8bfc88f9200014b2

+//!   ba8dd8a6debc471c69ef1e2326c61184a2eca88ec866346bh

+//! </pre>

+//!\sa <a href="http://www.weidai.com/scan-mirror/ka.html#DH">Diffie-Hellman</a> in GF(p) with key validation

+#if defined(CRYPTOPP_DOXYGEN_PROCESSING)

+struct DH : public DH_Domain<DL_GroupParameters_GFP_DefaultSafePrime>

+{

+	typedef DH_Domain<DL_GroupParameters_GFP_DefaultSafePrime> GroupParameters;

+	typedef GroupParameters::Element Element;

+

+	virtual ~DH() {}

+

+	//! \brief Create an uninitialized Diffie-Hellman object

+	DH() : DH_Domain() {}

+

+	//! \brief Initialize a Diffie-Hellman object

+	//! \param bt BufferedTransformation with group parameters and options

+	DH(BufferedTransformation &bt) : DH_Domain(bt) {}

+

+	//! \brief Initialize a Diffie-Hellman object

+	//! \param params group parameters and options

+	DH(const GroupParameters &params) : DH_Domain(params) {}

+

+	//! \brief Create a Diffie-Hellman object

+	//! \param rng a RandomNumberGenerator derived class

+	//! \param modulusBits the size of the modulus, in bits

+	//! \details This function overload of Initialize() creates a new Diffie-Hellman object because it

+	//!   takes a RandomNumberGenerator() as a parameter.

+	DH(RandomNumberGenerator &rng, unsigned int modulusBits) : DH_Domain(rng, modulusBits) {}

+

+	//! \brief Initialize a Diffie-Hellman object

+	//! \param rng a RandomNumberGenerator derived class

+	//! \param p the modulus

+	//! \param g the generator

+	DH(const Integer &p, const Integer &g) : DH_Domain(p, g) {}

+

+	//! \brief Initialize a Diffie-Hellman object

+	//! \param rng a RandomNumberGenerator derived class

+	//! \param p the modulus

+	//! \param q the subgroup order

+	//! \param g the generator

+	DH(const Integer &p, const Integer &q, const Integer &g) : DH_Domain(p, q, g) {}

+

+	//! \brief Creates a Diffie-Hellman object

+	//! \param rng a RandomNumberGenerator derived class

+	//! \param modulusBits the size of the modulus, in bits

+	//! \details This function overload of Initialize() creates a new Diffie-Hellman object because it

+	//!   takes a RandomNumberGenerator() as a parameter.

+	void Initialize(RandomNumberGenerator &rng, unsigned int modulusBits)

+		{AccessGroupParameters().Initialize(rng, modulusBits);}

+

+	//! \brief Initialize a Diffie-Hellman object

+	//! \param rng a RandomNumberGenerator derived class

+	//! \param p the modulus

+	//! \param g the generator

+	void Initialize(const Integer &p, const Integer &g)

+		{AccessGroupParameters().Initialize(p, g);}

+

+	//! \brief Initialize a Diffie-Hellman object

+	//! \param rng a RandomNumberGenerator derived class

+	//! \param p the modulus

+	//! \param q the subgroup order

+	//! \param g the generator

+	void Initialize(const Integer &p, const Integer &q, const Integer &g)

+		{AccessGroupParameters().Initialize(p, q, g);}

+};

+#else

+// The real DH class is a typedef.

 typedef DH_Domain<DL_GroupParameters_GFP_DefaultSafePrime> DH;

+#endif

 

 NAMESPACE_END