From 675575d96039ff840df7519ef9cfdd423a73d7df Mon Sep 17 00:00:00 2001 From: Jeffrey Walton Date: Tue, 23 Jan 2018 17:47:19 -0500 Subject: [PATCH] Update documentation --- cryptlib.h | 1 + eprecomp.h | 52 +++++++++++++++++++++++++++++++++++++++++++++++++--- pubkey.h | 25 ++++++++++++++++++++++--- stdcpp.h | 5 +++++ 4 files changed, 77 insertions(+), 6 deletions(-) diff --git a/cryptlib.h b/cryptlib.h index a552f47d..a43da4e2 100644 --- a/cryptlib.h +++ b/cryptlib.h @@ -2248,6 +2248,7 @@ public: /// \sa SupportsPrecomputation(), Precompute() virtual void LoadPrecomputation(BufferedTransformation &storedPrecomputation) {CRYPTOPP_UNUSED(storedPrecomputation); CRYPTOPP_ASSERT(!SupportsPrecomputation()); throw NotImplemented("CryptoMaterial: this object does not support precomputation");} + /// \brief Save precomputation for later use /// \param storedPrecomputation BufferedTransformation to write the precomputation /// \throws NotImplemented diff --git a/eprecomp.h b/eprecomp.h index f9e677ff..1cb84cc5 100644 --- a/eprecomp.h +++ b/eprecomp.h @@ -45,7 +45,7 @@ public: /// \brief Decodes element in DER format /// \param bt BufferedTransformation object - /// \param P Element to decode + /// \returns element in the group virtual Element BERDecodeElement(BufferedTransformation &bt) const =0; /// \brief Encodes element in DER format @@ -64,14 +64,60 @@ public: virtual ~DL_FixedBasePrecomputation() {} + /// \brief Determines whether this object is initialized + /// \returns true if this object is initialized, false otherwise virtual bool IsInitialized() const =0; + + /// \brief Set the base element + /// \param group the group + /// \param base element in the group virtual void SetBase(const DL_GroupPrecomputation &group, const Element &base) =0; + + /// \brief Get the base element + /// \param group the group + /// \returns base element in the group virtual const Element & GetBase(const DL_GroupPrecomputation &group) const =0; + + /// \brief Perform precomputation + /// \param group the group + /// \param maxExpBits used to calculate the exponent base + /// \param storage the suggested number of objects for the precompute table + /// \details The exact semantics of Precompute() varies, but it typically means calculate + /// a table of n objects that can be used later to speed up computation. + /// \details If a derived class does not override Precompute(), then the base class throws + /// NotImplemented. + /// \sa SupportsPrecomputation(), LoadPrecomputation(), SavePrecomputation() virtual void Precompute(const DL_GroupPrecomputation &group, unsigned int maxExpBits, unsigned int storage) =0; + + /// \brief Retrieve previously saved precomputation + /// \param group the the group + /// \param storedPrecomputation BufferedTransformation with the saved precomputation + /// \throws NotImplemented + /// \sa SupportsPrecomputation(), Precompute() virtual void Load(const DL_GroupPrecomputation &group, BufferedTransformation &storedPrecomputation) =0; + + /// \brief Save precomputation for later use + /// \param group the the group + /// \param storedPrecomputation BufferedTransformation to write the precomputation + /// \throws NotImplemented + /// \sa SupportsPrecomputation(), Precompute() virtual void Save(const DL_GroupPrecomputation &group, BufferedTransformation &storedPrecomputation) const =0; + + /// \brief Exponentiates an element + /// \param group the group + /// \param exponent the exponent + /// \return the result of the exponentiation virtual Element Exponentiate(const DL_GroupPrecomputation &group, const Integer &exponent) const =0; - virtual Element CascadeExponentiate(const DL_GroupPrecomputation &group, const Integer &exponent, const DL_FixedBasePrecomputation &pc2, const Integer &exponent2) const =0; + + /// \brief Exponentiates an element + /// \param pc1 the first the group precomputation + /// \param exponent1 the first exponent + /// \param pc2 the second the group precomputation + /// \param exponent2 the first exponent2 + /// \returns the public element raised to the exponent + /// \details CascadeExponentiateBaseAndPublicElement raises the public element to + /// the base element and precomputation. + virtual Element CascadeExponentiate(const DL_GroupPrecomputation &pc1, const Integer &exponent1, const DL_FixedBasePrecomputation &pc2, const Integer &exponent2) const =0; }; /// \brief DL_FixedBasePrecomputation adapter class @@ -96,7 +142,7 @@ public: void Load(const DL_GroupPrecomputation &group, BufferedTransformation &storedPrecomputation); void Save(const DL_GroupPrecomputation &group, BufferedTransformation &storedPrecomputation) const; Element Exponentiate(const DL_GroupPrecomputation &group, const Integer &exponent) const; - Element CascadeExponentiate(const DL_GroupPrecomputation &group, const Integer &exponent, const DL_FixedBasePrecomputation &pc2, const Integer &exponent2) const; + Element CascadeExponentiate(const DL_GroupPrecomputation &pc1, const Integer &exponent1, const DL_FixedBasePrecomputation &pc2, const Integer &exponent2) const; private: void PrepareCascade(const DL_GroupPrecomputation &group, std::vector > &eb, const Integer &exponent) const; diff --git a/pubkey.h b/pubkey.h index f0b02e0b..c4e9721b 100644 --- a/pubkey.h +++ b/pubkey.h @@ -786,19 +786,38 @@ public: ; } + /// \brief Determines whether the object supports precomputation + /// \return true if the object supports precomputation, false otherwise + /// \sa Precompute() bool SupportsPrecomputation() const {return true;} + /// \brief Perform precomputation + /// \param precomputationStorage the suggested number of objects for the precompute table + /// \throws NotImplemented + /// \details The exact semantics of Precompute() varies, but it typically means calculate + /// a table of n objects that can be used later to speed up computation. + /// \details If a derived class does not override Precompute(), then the base class throws + /// NotImplemented. + /// \sa SupportsPrecomputation(), LoadPrecomputation(), SavePrecomputation() void Precompute(unsigned int precomputationStorage=16) { AccessBasePrecomputation().Precompute(GetGroupPrecomputation(), GetSubgroupOrder().BitCount(), precomputationStorage); } + /// \brief Retrieve previously saved precomputation + /// \param storedPrecomputation BufferedTransformation with the saved precomputation + /// \throws NotImplemented + /// \sa SupportsPrecomputation(), Precompute() void LoadPrecomputation(BufferedTransformation &storedPrecomputation) { AccessBasePrecomputation().Load(GetGroupPrecomputation(), storedPrecomputation); m_validationLevel = 0; } + /// \brief Save precomputation for later use + /// \param storedPrecomputation BufferedTransformation to write the precomputation + /// \throws NotImplemented + /// \sa SupportsPrecomputation(), Precompute() void SavePrecomputation(BufferedTransformation &storedPrecomputation) const { GetBasePrecomputation().Save(GetGroupPrecomputation(), storedPrecomputation); @@ -814,9 +833,9 @@ public: /// \details The subgroup generator is set in the base precomputation virtual void SetSubgroupGenerator(const Element &base) {AccessBasePrecomputation().SetBase(GetGroupPrecomputation(), base);} - /// \brief Retrieves the subgroup generator - /// \return the subgroup generator - /// \details The subgroup generator is retrieved from the base precomputation. + /// \brief Exponentiates the base + /// \return the element after exponentiation + /// \details ExponentiateBase() calls GetBasePrecomputation() and then exponentiates. virtual Element ExponentiateBase(const Integer &exponent) const { return GetBasePrecomputation().Exponentiate(GetGroupPrecomputation(), exponent); diff --git a/stdcpp.h b/stdcpp.h index 54037e29..9eac8835 100644 --- a/stdcpp.h +++ b/stdcpp.h @@ -1,3 +1,8 @@ +// stdcpp.h - originally written and placed in the public domain by Wei Dai + +/// \file stdcpp.h +/// \brief Common C++ header files + #ifndef CRYPTOPP_STDCPP_H #define CRYPTOPP_STDCPP_H