From e6f6db5fdf4f1682dff525e6f8cf4dca31aa7f00 Mon Sep 17 00:00:00 2001 From: Jeffrey Walton Date: Sun, 4 Dec 2016 00:36:03 -0500 Subject: [PATCH] Updated documentation (Issue 328) --- dh.h | 110 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file 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; -//! Diffie-Hellman 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 Issue +//! 328, Diffie-Hellman example code not compiling. +//! \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. +//! 
  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;
+//!
+//! \details Output of the program above will be similar to the following. +//! 
  $ ./cryptest.exe
+//!   Private key:
+//!   72b45a42371545e9d4880f48589aefh
+//!   Public key:
+//!   45fdb13f97b1840626f0250cec1dba4a23b894100b51fb5d2dd13693d789948f8bfc88f9200014b2
+//!   ba8dd8a6debc471c69ef1e2326c61184a2eca88ec866346bh
+//!
+//!\sa Diffie-Hellman in GF(p) with key validation +#if defined(CRYPTOPP_DOXYGEN_PROCESSING) +struct DH : public DH_Domain +{ + typedef DH_Domain 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 ¶ms) : 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 DH; +#endif NAMESPACE_END