From 010805cbc79243354603dc2051c978010a030244 Mon Sep 17 00:00:00 2001 From: Jeffrey Walton Date: Mon, 18 Jan 2016 16:20:55 -0500 Subject: [PATCH] Updated documentation --- dh.h | 82 ++++++++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 75 insertions(+), 7 deletions(-) diff --git a/dh.h b/dh.h index 64cb811b..ef8a62ae 100644 --- a/dh.h +++ b/dh.h @@ -1,7 +1,6 @@ // dh.h - written and placed in the public domain by Wei Dai -//! \file -//! \headerfile dh.h +//! \file dh.h //! \brief Classes for Diffie-Hellman key exchange #ifndef CRYPTOPP_DH_H @@ -13,7 +12,13 @@ NAMESPACE_BEGIN(CryptoPP) -//! , +//! \class DH_Domain +//! \brief Diffie-Hellman domain +//! \tparam GROUP_PARAMETERS group parameters +//! \tparam COFACTOR_OPTION cofactor options +//! \details A Diffie-Hellman domain is a set of parameters that must be shared +//! by two parties in a key agreement protocol, along with the algorithms +//! for generating key pairs and deriving agreed values. template class DH_Domain : public DL_SimpleKeyAgreementDomainBase { @@ -25,41 +30,104 @@ public: typedef DL_KeyAgreementAlgorithm_DH DH_Algorithm; typedef DH_Domain Domain; + //! \brief Construct a Diffie-Hellman domain DH_Domain() {} + //! \brief Construct a Diffie-Hellman domain + //! \param params group parameters and options DH_Domain(const GroupParameters ¶ms) : m_groupParameters(params) {} + //! \brief Construct a Diffie-Hellman domain + //! \param bt BufferedTransformation with group parameters and options DH_Domain(BufferedTransformation &bt) {m_groupParameters.BERDecode(bt);} + //! \brief Construct a Diffie-Hellman domain + //! \tparam T2 template parameter used as a constructor parameter + //! \param v1 RandomNumberGenerator derived class + //! \param v2 second parameter + //! \details v1 and v2 are passed directly to the GROUP_PARAMETERS object. template DH_Domain(RandomNumberGenerator &v1, const T2 &v2) {m_groupParameters.Initialize(v1, v2);} - + + //! \brief Construct 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 + //! \param v2 second parameter + //! \param v3 third parameter + //! \details v1, v2 and v3 are passed directly to the GROUP_PARAMETERS object. template DH_Domain(RandomNumberGenerator &v1, const T2 &v2, const T3 &v3) {m_groupParameters.Initialize(v1, v2, v3);} - + + //! \brief Construct 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 + //! \param v1 RandomNumberGenerator derived class + //! \param v2 second parameter + //! \param v3 third parameter + //! \param v4 fourth parameter + //! \details v1, v2, v3 and v4 are passed directly to the GROUP_PARAMETERS object. template DH_Domain(RandomNumberGenerator &v1, const T2 &v2, const T3 &v3, const T4 &v4) {m_groupParameters.Initialize(v1, v2, v3, v4);} + //! \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 DH_Domain(const T1 &v1, const 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 DH_Domain(const T1 &v1, const T2 &v2, const 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 fourth parameter + //! \details v1, v2, v3 and v4 are passed directly to the GROUP_PARAMETERS object. template DH_Domain(const T1 &v1, const T2 &v2, const T3 &v3, const 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 Generate a public key from a private key in this domain + //! \param rng RandomNumberGenerator derived class + //! \param privateKey byte buffer with the previously generated private key + //! \param publicKey byte buffer for the generated public key in this domain + //! \details If using a FIPS 140-2 validated library on Windows, then this class will perform + //! a self test to ensure the key pair is pairwise consistent. Non-FIPS and non-Windows + //! builds of the library do not provide FIPS validated cryptography, so the code should be + //! removed by the optimizer. + //! \pre COUNTOF(publicKey) == PublicKeyLength() void GeneratePublicKey(RandomNumberGenerator &rng, const byte *privateKey, byte *publicKey) const { Base::GeneratePublicKey(rng, privateKey, publicKey);