From 850aed5bed098e68d678231a68258ce7e546f78f Mon Sep 17 00:00:00 2001 From: Jeffrey Walton Date: Mon, 29 Feb 2016 07:40:04 -0500 Subject: [PATCH] Update documentation --- modarith.h | 133 ++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 127 insertions(+), 6 deletions(-) diff --git a/modarith.h b/modarith.h index bde1bbe6..a69945b8 100644 --- a/modarith.h +++ b/modarith.h @@ -31,96 +31,217 @@ public: typedef int RandomizationParameter; typedef Integer Element; +#ifndef CRYPTOPP_MAINTAIN_BACKWARDS_COMPATIBILITY_562 + virtual ~ModularArithmetic() {} +#endif + + //! \brief Construct a ModularArithmetic + //! \param modulus congruence class modulus ModularArithmetic(const Integer &modulus = Integer::One()) : AbstractRing(), m_modulus(modulus), m_result((word)0, modulus.reg.size()) {} + + //! \brief Copy construct a ModularArithmetic + //! \param ma other ModularArithmetic ModularArithmetic(const ModularArithmetic &ma) : AbstractRing(), m_modulus(ma.m_modulus), m_result((word)0, ma.m_modulus.reg.size()) {} + //! \brief Construct a ModularArithmetic + //! \param bt BER encoded ModularArithmetic ModularArithmetic(BufferedTransformation &bt); // construct from BER encoded parameters + //! \brief Clone a ModularArithmetic virtual ModularArithmetic * Clone() const {return new ModularArithmetic(*this);} + //! \brief Encodes in DER format + //! \param bt BufferedTransformation object void DEREncode(BufferedTransformation &bt) const; + //! \brief Encodes element in DER format + //! \param out BufferedTransformation object + //! \param a Element to encode void DEREncodeElement(BufferedTransformation &out, const Element &a) const; + + //! \brief Decodes element in DER format + //! \param in BufferedTransformation object + //! \param a Element to decode void BERDecodeElement(BufferedTransformation &in, Element &a) const; + //! \brief Retrieves the modulus + //! \returns the modulus const Integer& GetModulus() const {return m_modulus;} + + //! \brief Sets the modulus + //! \param newModulus the new modulus void SetModulus(const Integer &newModulus) {m_modulus = newModulus; m_result.reg.resize(m_modulus.reg.size());} + //! \brief Retrieves the representation + //! \returns true if the representation is MontgomeryRepresentation, false otherwise virtual bool IsMontgomeryRepresentation() const {return false;} + //! \brief Reduces an element in the congruence class + //! \param a element to convert + //! \returns the reduced element + //! \details ConvertIn is useful for derived classes, like MontgomeryRepresentation, which + //! must convert between representations. virtual Integer ConvertIn(const Integer &a) const {return a%m_modulus;} + //! \brief Reduces an element in the congruence class + //! \param a element to convert + //! \returns the reduced element + //! \details ConvertOut is useful for derived classes, like MontgomeryRepresentation, which + //! must convert between representations. virtual Integer ConvertOut(const Integer &a) const {return a;} + //! \brief TODO + //! \param a element to convert const Integer& Half(const Integer &a) const; + //! \brief Compare two elements for equality + //! \param a first element + //! \param b second element + //! \returns true if the elements are equal, false otherwise + //! \details Equal() tests the elements for equality using a==b bool Equal(const Integer &a, const Integer &b) const {return a==b;} + //! \brief Provides the Identity element + //! \returns the Identity element const Integer& Identity() const {return Integer::Zero();} + //! \brief Adds elements in the Ring + //! \param a first element + //! \param b second element + //! \returns the sum of a and b const Integer& Add(const Integer &a, const Integer &b) const; + //! \brief TODO + //! \param a first element + //! \param b second element + //! \returns TODO Integer& Accumulate(Integer &a, const Integer &b) const; + //! \brief Inverts the element in the Ring + //! \param a first element + //! \returns the inverse of the element const Integer& Inverse(const Integer &a) const; + //! \brief Subtracts elements in the Ring + //! \param a first element + //! \param b second element + //! \returns the difference of a and b. The element a must provide a Subtract member function. const Integer& Subtract(const Integer &a, const Integer &b) const; + //! \brief TODO + //! \param a first element + //! \param b second element + //! \returns TODO Integer& Reduce(Integer &a, const Integer &b) const; + //! \brief Doubles an element in the Ring + //! \param a the element + //! \returns the element doubled + //! \details Double returns Add(a, a). The element a must provide an Add member function. const Integer& Double(const Integer &a) const {return Add(a, a);} + //! \brief Retrieves the multiplicative identity + //! \returns the multiplicative identity + //! \details the base class implementations returns 1. const Integer& MultiplicativeIdentity() const {return Integer::One();} + //! \brief Multiplies elements in the Ring + //! \param a first element + //! \param b second element + //! \returns the product of a and b + //! \details Multiply returns a*b\%n. const Integer& Multiply(const Integer &a, const Integer &b) const {return m_result1 = a*b%m_modulus;} + //! \brief Square an element in the Ring + //! \param a the element + //! \returns the element squared + //! \details Square returns a*a\%n. The element a must provide a Square member function. const Integer& Square(const Integer &a) const {return m_result1 = a.Squared()%m_modulus;} + //! \brief Determines whether an element is a unit in the Ring + //! \param a the element + //! \returns true if the element is a unit after reduction, false otherwise. bool IsUnit(const Integer &a) const {return Integer::Gcd(a, m_modulus).IsUnit();} + //! \brief Calculate the multiplicative inverse of an element in the Ring + //! \param a the element + //! \details MultiplicativeInverse returns a-1\%n. The element a must + //! provide a InverseMod member function. const Integer& MultiplicativeInverse(const Integer &a) const {return m_result1 = a.InverseMod(m_modulus);} + //! \brief Divides elements in the Ring + //! \param a first element + //! \param b second element + //! \returns the element squared + //! \details Divide returns a*b-1\%n. const Integer& Divide(const Integer &a, const Integer &b) const {return Multiply(a, MultiplicativeInverse(b));} + //! \brief TODO + //! \param x first element + //! \param e1 first exponent + //! \param y second element + //! \param e2 second exponent + //! \returns TODO Integer CascadeExponentiate(const Integer &x, const Integer &e1, const Integer &y, const Integer &e2) const; + //! \brief Exponentiates a base to multiple exponents in the Ring + //! \param results an array of Elements + //! \param base the base to raise to the exponents + //! \param exponents an array of exponents + //! \param exponentsCount the number of exponents in the array + //! \details SimultaneousExponentiate() raises the base to each exponent in the exponents array and stores the + //! result at the respective position in the results array. + //! \details SimultaneousExponentiate() must be implemented in a derived class. + //! \pre COUNTOF(results) == exponentsCount + //! \pre COUNTOF(exponents) == exponentsCount void SimultaneousExponentiate(Element *results, const Element &base, const Integer *exponents, unsigned int exponentsCount) const; + //! \brief Provides the maximum bit size of an element in the Ring + //! \returns maximum bit size of an element unsigned int MaxElementBitLength() const {return (m_modulus-1).BitCount();} + //! \brief Provides the maximum byte size of an element in the Ring + //! \returns maximum byte size of an element unsigned int MaxElementByteLength() const {return (m_modulus-1).ByteCount();} - Element RandomElement( RandomNumberGenerator &rng , const RandomizationParameter &ignore_for_now = 0 ) const + //! \brief Provides a random element in the Ring + //! \param rng RandomNumberGenerator used to generate material + //! \param ignore_for_now unused + //! \returns a random element that is uniformly distributed + //! \details RandomElement constructs a new element in the range [0,n-1], inclusive. + //! The element's class must provide a constructor with the signature Element(RandomNumberGenerator rng, + //! Element min, Element max). + Element RandomElement( RandomNumberGenerator &rng , const RandomizationParameter &ignore_for_now = 0) const // left RandomizationParameter arg as ref in case RandomizationParameter becomes a more complicated struct { CRYPTOPP_UNUSED(ignore_for_now); return Element(rng, Integer::Zero(), m_modulus - Integer::One()) ; } + //! \brief Compares two ModularArithmetic for equality + //! \param rhs other ModularArithmetic + //! \returns true if this is equal to the other, false otherwise + //! \details The operator tests for equality using this.m_modulus == rhs.m_modulus. bool operator==(const ModularArithmetic &rhs) const {return m_modulus == rhs.m_modulus;} static const RandomizationParameter DefaultRandomizationParameter ; - -#ifndef CRYPTOPP_MAINTAIN_BACKWARDS_COMPATIBILITY_562 - virtual ~ModularArithmetic() {} -#endif protected: Integer m_modulus; @@ -133,7 +254,7 @@ protected: //! \class MontgomeryRepresentation //! \brief Performs modular arithmetic in Montgomery representation for increased speed //! \details The Montgomery representation represents each congruence class [a] as -//! a*r%n, where r is a convenient power of 2. +//! a*r\%n, where r is a convenient power of 2. class CRYPTOPP_DLL MontgomeryRepresentation : public ModularArithmetic { public: